CphCT Toolbox README
Last updated/generated 04-12-2014 12:13


  1. Cph CT Toolbox
  2. Requirements
  3. Installation
    3.1. Pip
    3.2. Easy_install
    3.3. Manual Installation
  4. Run from Source
  5. Upgrade
  6. Uninstallation
  7. Questions and Feedback
  8. External References


  1. Cph CT Toolbox
  =================

Copenhagen Computed Tomography Toolbox is a collection of applications and
libraries for flexible and efficient CT reconstruction. The tools generally
take a set of projections (X-ray intensity or attenuation measurements)
and filter and back project them in order to recreate the physical image
or volume that the projections represent.

The tools are divided in the categories fan beam and cone beam with individual
algorithm implementations in the corresponding category folders. Thus
e.g. the cone beam FDK algorithm is implemented in conebeam/fdk/.

Implementations provide one or more engines optimized for particular hardware
platforms like CUDA enabled GPUs or OpenCL enabled CPUs and GPUs. In most cases
there will additionally be a NumPy reference implementation which may be
more easily understood and useful as a fall back on platforms where no
further optimized engines apply.

The doc folder contains more detailed instructions and background information
about the individual tools.


  2. Requirements
  ===============

The CphCT Toolbox relies on Python[1] and Numpy[2] for all core
functionality. Optimized CUDA and OpenCL application engines
additionally require the PyCUDA[3], PyOpenCL[4] and PyFFT[9] libraries
which in turn require access to working CUDA and OpenCL runtimes. Please
refer to the individual documentation pages online in order to satisfy
those dependencies.

The toolbox should work with any Python-2.5+ interpreter and a fairly
recent Numpy installation, but we have only tested with Python 2.6+ and
Numpy-1.3.1+ installations. If you want the reconstruction results saved
as images rather than a raw binary dump you will additionally need the
Python Imaging Library (PIL) or Scipy.


  3. Installation
  ===============

We provide three installation methods to support the widest possible
range of platforms. The easiest way to install is with the pip or
easy_install methods that can pull down the package directly from the
internet and take care of the entire installation. Manual installation
from downloaded source or repository checkout is also possible, however.
Please note that all the system wide installation commands may require
administrative privileges. 


	3.1. Pip
	========

We recommend installation with pip[5] because it makes upgrades and
uninstallation very easy.
Simply run pip with the default pypi.python.org as package source:

  pip install cphcttoolbox

Alternatively you can point pip to a specific version:

  pip install https://pypi.python.org/packages/source/c/cphcttoolbox/cphcttoolbox-1.1.2.zip

If for some reason you can't or don't want to install globally on your
system with pip you may still be able to use virtualenv[6] to
install with pip but in an isolated environment.


	3.2. Easy_install
	=================

If you do not have access to pip, easy_install[7] provides the second best choice. 
Simply run easy_install with the default pypi.python.org as package source:

  easy_install cphcttoolbox

Alternatively you can point easy_install to a specific version:

  easy_install https://pypi.python.org/packages/source/c/cphcttoolbox/cphcttoolbox-1.1.2.zip


	3.3. Manual Installation
	========================

If you do not have access to pip and easy_install or if you want more
control over the install process you can use the traditional Python
setup method.
First download the source code archive or check out a version from the
repository. Then run setup as usual:

  python setup.py install

or add any additional options to the command in order to tweak the
installation.


  4. Run from Source
  ==================

It is also possible to run the toolbox applications directly from source
code without installing. Three steps are required to use this setup:

 1. Download the source code archive from the internet
 2. Unpack the archive somewhere
 3. Set the PYTHONPATH environment to the unpacked directory path

Now you can run the applications using the absolute application paths. 

An ultra short command line example to illustrate it:
  wget https://pypi.python.org/packages/source/c/cphcttoolbox/cphcttoolbox-1.1.2.zip
  unzip cphcttoolbox-1.1.2.zip
  export PYTHONPATH=${PWD}/cphcttoolbox-1.1.2
  python cphcttoolbox-1.1.2/conebeam/katsevich/katsevich.py --help


The archive download and unpack may be replaced by a checkout from the
online code repository.


  5. Upgrade
  ==========

Upgrading is very simple if you installed the toolbox with pip or
easy_install. Simply run the install command again with the
--upgrade flag like:

  pip install --upgrade cphcttoolbox

or

  easy_install --upgrade cphcttoolbox

respectively.
If you installed manually from source you may be able to simply repeat
the installation procedure with the updated source, but we recommend
that you follow the instructions in the Uninstallation section to remove
any old leftovers before repeating the install steps. 


  6. Uninstallation
  =================

In case you installed with pip it is very simple to uninstall the
toolbox again:

  pip uninstall cphcttoolbox

For easy_install and manual installations it is more cumbersome because
manual removal of the installed files is required. You will find
installed scripts in /usr/local/bin and libraries in your python
site-packages or dist-packages directories by default. You can probably
just delete them to remove the toolbox, but please refer to e.g. [8] for
details about the process of cleaning up after manually or
easy_install'ed packages.

If you only ran the toolbox applications from unpacked source you can
simply delete the unpacked cphcttoolbox directory to completely remove
the toolbox.


  7. Questions and Feedback
  =========================

Questions, contributions and comments are always welcome. Just write to
jonas DOT bardino AT gmail DOT com or one of the other developers listed
at the official web site.


  8. External References
  ======================

 1. http://www.python.org/
 2. http://numpy.scipy.org/
 3. http://mathema.tician.de/software/pycuda
 4. http://mathema.tician.de/software/pyopencl
 5. http://pypi.python.org/pypi/pip
 6. http://pypi.python.org/pypi/virtualenv
 7. http://packages.python.org/distribute/easy_install.html
 8. http://thingsilearned.com/2009/04/13/easy_install-uninstalling/
 9. https://pypi.python.org/pypi/pyfft