Updated the documentation and added small receipts and installation i…

…nstructions.

doc/source/index.rst

@@ -6,6 +6,29 @@ MedPy
 
 MedPy is a medical image processing library written in Python.
 
+Installation
+------------
+
+.. toctree::
+    :maxdepth: 1
+
+    installation/fastpath
+    installation/asroot
+    installation/asuser
+    installation/developmentmode
+    installation/uninstall
+    installation/graphcutsupport
+    installation/itkwrapper
+
+Information
+-----------
+
+.. toctree::
+    :glob:
+    :maxdepth: 1
+
+    information/*
+
 Tutorials
 ---------
 
@@ -15,6 +38,15 @@ Tutorials
 
     tutorial/*
 
+Receipts
+--------
+
+.. toctree::
+    :glob:
+    :maxdepth: 1
+
+    receipts/*
+
 Reference
 ---------
 

doc/source/information/imageformats.rst

@@ -0,0 +1,32 @@
+===============================
+Supported medical image formats
+===============================
+MedPy builds on 3rd party modules to load and save images. Currently
+implemented are the usages of
+
+* NiBabel
+* PyDicom
+* ITK
+
+, each of which supports the following formats.
+
+**NiBabel** enables support for:
+
+* NifTi - Neuroimaging Informatics Technology Initiative (.nii, nii.gz)
+* Analyze (plain, SPM99, SPM2) (.hdr/.img, .img.gz)
+* and some others more (http://nipy.sourceforge.net/nibabel/)
+
+**PyDicom** enables support for:
+
+* Dicom - Digital Imaging and Communications in Medicine (.dcm, .dicom)
+
+**ITK** enables support for:
+
+* NifTi - Neuroimaging Informatics Technology Initiative (.nii, nii.gz)
+* Analyze (plain, SPM99, SPM2) (.hdr/.img, .img.gz)
+* Dicom - Digital Imaging and Communications in Medicine (.dcm, .dicom)
+* Itk/Vtk MetaImage (.mhd, .mha/.raw)
+* Nrrd - Nearly Raw Raster Data (.nhdr, .nrrd)
+* and many others more (http://www.cmake.org/Wiki/ITK/File_Formats)
+
+For some functionalities, which are collected in the *medpy.itkvtk* package **ITK** is also required.

doc/source/installation/asroot.rst

@@ -0,0 +1,45 @@
+========================
+Installing MedPy as root
+========================
+.. note::
+
+    All installation instructions are for Ubuntu, but they should be simmilar for other distributions.
+
+When installed with root privileges, **MedPy** will be available for all uses of your machine.
+
+To install Python packages from `PyPi <https://pypi.python.org>`_, we recommend `PIP <https://pypi.python.org/pypi/pip>`_
+
+.. code-block:: bash
+
+    sudo apt-get install python-pip
+
+Furthermore, you'll require ``numpy`` and ``scipy``, which you can either install from the repositories
+
+.. code-block:: bash
+    
+    sudo apt-get install python-numpy python-scipy
+    
+Or via PIP
+
+.. code-block:: bash
+
+    sudo pip install numpy scipy
+    
+To enable the graph-cut package, we also need the following   
+
+.. code-block:: bash
+    
+    sudo apt-get install libboost-python-dev build-essential
+    
+And to enable the loading/saving of various image formats, at least ``nibabel`` and ``pydicom`` should be installed
+
+.. code-block:: bash
+
+    sudo pip install nibabel pydicom
+    
+Now we can install **MedPy**
+
+.. code-block:: bash
+
+    sudo pip install medpy
+

doc/source/installation/asuser.rst

@@ -0,0 +1,86 @@
+========================
+Installing MedPy as user
+========================
+.. note::
+
+    All installation instructions are for Ubuntu, but they will work similar for other distributions.
+
+The local install will place **MedPy** in your user site-packages directory and does not require root privileges. You can find our the location of your personal site-packages directory by calling:
+
+.. code-block:: bash
+
+	python -c 'import site;print site.USER_SITE'
+	
+In some cases, the Python configuration does not find packages in the users site-packages directory, in which case you will have to add it to your PYTHONPATH variable.
+To make this permanent, add the extension to your `.bashrc`, e.g. using:
+
+.. code-block:: bash
+
+	echo "export PYTHONPATH=${PYTHONPATH}:$( python -c 'import site;print site.USER_SITE' )" >> ~/.bashrc
+	
+More importantly, the script shipped with **MedPy** won't be in your PATH and hence can not be used directly. If your user site-packages directory is
+e.g. `/home/<user>/.local/lib/python2.7/site-packages/`, the scripts are most likely to be found under `/home/<user>/.local/bin/`. Add this directory to your PATH using:
+
+.. code-block:: bash
+
+	 echo "export PATH=${PATH}:/home/<user>/.local/bin/" >> ~/.bashrc
+	 
+(Don't forget to replace <user> with your own user name.)	
+
+Installing using `PIP <https://pypi.python.org/pypi/pip>`_
+----------------------------------------------------------
+Requires `PIP <https://pypi.python.org/pypi/pip>`_ to be installed on your machine.
+
+First install the Python requirements locally
+
+.. code-block:: bash
+
+    pip install --user numpy scipy nibabel pydicom
+    
+and then **MedPy**
+
+.. code-block:: bash
+
+    pip install --user medpy
+
+
+Installing using `easy_install <https://pypi.python.org/pypi/setuptools>`_
+--------------------------------------------------------------------------
+Requires `easy_install <https://pypi.python.org/pypi/setuptools>`_ to be installed on your machine.
+
+First install the Python requirements locally
+
+.. code-block:: bash
+
+    easy_install --user numpy scipy nibabel pydicom
+    
+and then **MedPy**
+
+.. code-block:: bash
+
+    easy_install --user medpy
+
+Installing from source
+----------------------
+No PIP, easy_install or a friendly administrator? There is one last option.
+First, install `numpy <http://www.numpy.org/>`_, `scipy <http://www.scipy.org/>`_, 
+`nibabel <http://nipy.org/nibabel/>`_ and `pydicom <https://code.google.com/p/pydicom/>`_
+from source (see there respective webpages for details) as user.
+
+The download the sources from https://pypi.python.org/pypi/MedPy/, unpack them, enter the directory and run::
+
+.. code-block:: bash
+
+    python setup.py install --user
+
+How do I enable the graph-cut packages
+--------------------------------------
+The graph-cut package shipped with **MedPy** requires Boost.Python and some standard C++ building tools.
+If these are not available during the installation, the package will not be compiled.
+You will have to ask your administrator to install the requirements for you (before installing **MedPy**):
+
+.. code-block:: bash
+    
+    sudo apt-get install libboost-python-dev build-essential
+
+

doc/source/installation/developmentmode.rst

@@ -0,0 +1,9 @@
+====================================
+Installing MedPy in development mode
+====================================
+If you care to work on the source directly, you can install **MedPy** in development mode. Then the sources will remain and any changes made them them be directly available system-wide.
+First follow all steps described in :doc:`asroot` except the last, then download the **MedPy** sources from https://pypi.python.org/pypi/MedPy/, unpack them, enter the directory and run:
+
+.. code-block:: bash
+
+	sudo python setup.py develop

doc/source/installation/fastpath.rst

@@ -0,0 +1,21 @@
+=============================
+Installing MedPy the fast way
+=============================
+.. note::
+
+    All installation instructions are for Ubuntu, but they should be simmilar for other distributions.
+
+First
+
+.. code-block:: bash
+
+    sudo apt-get install python-pip python-numpy python-scipy libboost-python-dev build-essential
+    
+Then
+
+.. code-block:: bash
+
+    sudo pip install nibabel pydicom medpy
+ 
+Done.
+

doc/source/installation/graphcutsupport.rst

@@ -0,0 +1,18 @@
+================================
+Installing with GraphCut support
+================================
+The GraphCut functionalities of **MedPy** depend on the `max-flow/min-cut library <http://vision.csd.uwo.ca/code/>`_ by Boykov and Kolmogorov.
+During installation, **MedPy** will try to compile it and its python wrappers. If the compilation fails, **MedPy** will be installed without the GraphCut module.
+To enable the GraphCut functionality of **MedPy**, the dependencies of the library must be met *before* installing **MedPy** (although it can always be simply re-installed).
+
+Dependencies
+------------
+* Boost.Python
+* g++
+* gcc
+
+These dependencies can be found in the repositories of all major distribution. For e.g. Ubuntu, you can simply call:
+
+.. code-block:: bash
+
+	sudo apt-get install libboost-python-dev build-essential

doc/source/installation/itkwrapper.rst

@@ -0,0 +1,121 @@
+==================================
+Installing ITK wrappers for Python
+==================================
+This is quite some work and absolutely not fail-save. Only try it, if you must (or are bored with too much time at hand).
+
+1. Installing ITK with Python binding on Ubuntu (>= 10.04)
+----------------------------------------------------------
+The Ubuntu repositories provide a package which can simply be installed using:
+
+.. code-block:: bash
+	
+	sudo apt-get install python-insighttoolkit3
+
+But this package wraps only a subset of ITKs functionality and therefore does not unleash **MedPy** s complete power. The recommendation is to follow the second or third approach.
+
+2. Installing ITK with Python binding on Ubuntu (= 12.04)
+---------------------------------------------------------
+If you are running Ubuntu 12.04, you can simply contact the author who will provide you with a pre-compiled Ubuntu package.
+
+3. Compiling ITK with Python bindings on POSIX/Unix platforms
+-------------------------------------------------------------
+All descriptions are for ITK 3.20 but might also be valid for newer versions.
+
+Getting ITK
+***********
+Got to http://www.itk.org/ITK/resources/software.html , download the *InsightToolkit-3.20.1.tar.gz* resp. *InsightToolkit-3.20.1.zip* archive and unpack it to a folder called somthing like *IKT3.20.1/src*.
+
+Configuring ITK
+***************
+Compiling ITK requires *cmake* which can be found for almost all platforms. Create a new directory *IKT3.20.1/build* and enter it. Then run:
+
+.. code-block:: bash
+
+	ccmake ../src
+
+and subsequently hit the *c* key to configure the build. When finished, hit the *t* key to toggle the advanced mode and activate the following options::
+
+	BUILD_SHARED_LIBS ON
+	ITK_USE_REVIEW	  ON
+	USE_WRAP_ITK	  ON
+
+, then *c* onfigure again. Ignore the warning by pressing *e*. Now set the following options::
+
+	WRAP_FFT	    OFF
+	WRAP_ITK_DIMS	    2;3;4 (or more, if you require)
+	WRAP_ITK_JAVA	    OFF
+	WRAP_ITK_PYTHON	    ON
+	WRAP_ITK_TCL	    OFF
+
+	WRAP_double         ON
+	WRAP_float          ON
+	WRAP_signed_char    ON
+	WRAP_signed_long    ON
+	WRAP_signed_short   ON
+	WRAP_unsigned_char  ON
+	WRAP_unsigned_long  ON
+	WRAP_unsigned_short ON
+	WRAP_<datatype>	  Select yourself which more to activate.
+
+, and *c* onfigure another time. Finally press *g* to generate the make-file.
+
+If *cmake* signals any errors during the configuration process, try to resolve the dependencies from which they originate.
+
+Compiling ITK
+*************
+Now that the configuration is done, we can compile ITK. Run:
+
+.. code-block:: bash
+
+	make -j<number-of-your-porcessors>
+
+and wait. This will take some time, depending on your computer up to 2 days are not unlikely.
+
+
+If an error occurs, try to understand it and eventually re-run the previpous step with some options changed.
+
+Installing ITK
+**************
+Install ITK and its Python bindings simply by running:
+
+.. code-block:: bash
+
+	make install (as root)
+
+Addditional step
+****************
+The ITK Python bindings require a third-party module called PyBuffer which is shipped with ITK but not automatically compiled. Furthermore it holds a small bug. After finishing the previous steps, create a folder called *PyBuffer/src* somewhere and copy all files and folders from *ITK/src/Wrapping/WrapITK/ExternalProjects/PyBuffer/* into it. Now open *itkPyBuffer.txx* with an text editor and change the line:
+
+.. code-block:: cpp
+
+	int dimensions[ ImageDimension ];
+
+to:
+
+.. code-block:: cpp
+
+	npy_intp dimensions[ ImageDimension ];
+
+(see http://code.google.com/p/wrapitk/issues/detail?id=39 for patch details). Then create a folder *PyBuffer/build*, enter it and run:
+
+.. code-block:: bash
+
+	ccmake ../src
+
+After *c* onfiguring you will see some warnings. Set::
+
+	WrapITK_DIR	ITK/bin/Wrapping/WrapITK/
+
+In some cases you will also have to set::
+
+	PYTHON_NUMARRAY_INCLUDE_DIR	/usr/include/numpy
+
+Now *c* onfigure again and *g* enerate. To finalize run::
+
+.. code-block:: bash
+
+	make
+	make install (as root)
+
+Congratulations, you are done compiling and installing ITK with Python wrappers.
+

doc/source/installation/uninstall.rst

@@ -0,0 +1,8 @@
+===============
+Uninstall MedPy
+===============
+Only `pip` supports the removal of Python packages. If you have installed **MedPy** by other means, you will have to remove the package manually. With `pip`, call simply::
+
+.. code-block:: bash
+
+	pip uninstall medpy