Master | Development | Conda binaries |
---|---|---|
The Core Imaging Library (CIL) is an open-source Python framework for tomographic imaging with particular emphasis on reconstruction of challenging datasets. Conventional filtered backprojection reconstruction tends to be insufficient for highly noisy, incomplete, non-standard or multichannel data arising for example in dynamic, spectral and in situ tomography. CIL provides an extensive modular optimisation framework for prototyping reconstruction methods including sparsity and total variation regularisation, as well as tools for loading, preprocessing and visualising tomographic data.
The documentation for CIL can be accessed here.
Binary installation of CIL can be achieved with conda
.
We recommend using either miniconda
or miniforge
, which are both minimal installers for conda
. We also recommend a conda
version of at least 23.10
for quicker installation.
Install a new environment using:
conda create --name cil -c conda-forge -c https://software.repos.intel.com/python/conda -c ccpi cil=24.1.0
To install CIL and the additional packages and plugins needed to run the CIL demos install the environment with:
conda create --name cil -c conda-forge -c https://software.repos.intel.com/python/conda -c ccpi cil=24.1.0 astra-toolbox=*=cuda* tigre ccpi-regulariser tomophantom ipywidgets
where:
astra-toolbox
enables CIL support for ASTRA toolbox CPU projector (2D Parallel beam only) (GPLv3 license)astra-toolbox=*=cuda*
(requires an NVIDIA GPU) enables CIL support for ASTRA toolbox GPU projectors (GPLv3 license)tigre
(requires an NVIDIA GPU) enables support for TIGRE toolbox projectors (BSD license)ccpi-regulariser
is the CCPi Regularisation Toolkittomophantom
can generate phantoms to use as test data Tomophantomipywidgets
enables visulisation tools within jupyter noteboooks
CIL's optimised FDK/FBP recon
module requires:
- the Intel Integrated Performance Primitives Library (license) which can be installed via conda from the
https://software.repos.intel.com/python/conda
channel. - TIGRE, which can be installed via conda from the
ccpi
channel.
Finally, CIL can be run via a Jupyter Notebook enabled Docker container:
docker run --rm --gpus all -p 8888:8888 -it ghcr.io/tomographicimaging/cil:latest
Tip
docker tag | CIL branch/tag |
---|---|
latest |
latest tag v*.*.* |
YY.M |
latest tag vYY.M.* |
YY.M.m |
tag vYY.M.m |
master |
master |
only build & test (no tag) | CI (current commit) |
See ghcr.io/tomographicimaging/cil
for a full list of tags.
Note
GPU support requires nvidia-container-toolkit
and an NVIDIA GPU.
Omit the --gpus all
to run without GPU support.
Important
Folders can be shared with the correct (host) user permissions using
--user $(id -u) --group-add users -v /local/path:/container/path
where /local/path
is an existing directory on your local (host) machine which will be mounted at /container/path
in the docker container.
Tip
See jupyter-docker-stacks for more information.
Jupyter Notebooks usage examples without any local installation are provided in Binder. Please click the launch binder icon above. For more information, go to CIL-Demos and https://mybinder.org.
- PyCon DE & PyData Berlin 2022, Apr 2022: Abstract, Video, Material
- Training School for the Synergistic Image Reconstruction Framework (SIRF) and Core Imaging Library (CIL), Jun 2021: Videos, Material
- Synergistic Reconstruction Symposium, Nov 2019: Slides, Videos, Material
In case of development it is useful to be able to build the software directly. You should clone this repository as
git clone --recurse-submodule [email protected]:TomographicImaging/CIL
The use of --recurse-submodule
is necessary if the user wants the examples data to be fetched (they are needed by the unit tests). We have moved such data, previously hosted in this repo at Wrappers/Python/data
to the CIL-data repository and linked it to this one as submodule. If the data is not available it can be fetched in an already cloned repository as
git submodule update --init --recursive
To create a conda environment with all the dependencies for building CIL run the following shell script:
bash scripts/create_local_env_for_cil_development.sh
Or with the CIL build and test dependencies:
bash scripts/create_local_env_for_cil_development.sh -t
And then install CIL in to this environment using CMake.
Alternatively, one can use the scripts/requirements-test.yml
to create a conda environment with all the
appropriate dependencies on any OS, using the following command:
conda env create -f scripts/requirements-test.yml
CMake and a C compiler are required to build the source code. Let's suppose that the user is in the source directory, then the following commands should work:
cmake -S . -B ./build -DCMAKE_INSTALL_PREFIX=<install_directory>
cmake --build ./build --target install
If targeting an active conda environment then the <install_directory>
can be set to the CONDA_PREFIX
environment variable (e.g. ${CONDA_PREFIX}
in Bash, or %CONDA_PREFIX%
in the Anaconda Prompt on Windows).
If not installing to a conda environment then the user will also need to set the locations of the IPP library and includes, and the path to CIL.
By default the location of the IPP library and includes is ${CMAKE_INSTALL_PREFIX}/lib
and ${CMAKE_INSTALL_PREFIX}/include
respectively. To pass the location of the IPP library and headers please pass the following parameters:
cmake -S . -B ./build -DCMAKE_INSTALL_PREFIX=<install_directory> -DIPP_LIBRARY=<path_to_ipp_library> -DIPP_INCLUDE=<path_to_ipp_includes>
The user will then need to add the path <install_directory>/lib
to the environment variable PATH
or LD_LIBRARY_PATH
, depending on system OS.
In the repository root, simply update submodules and run docker build
:
git submodule update --init --recursive
docker build . -t ghcr.io/tomographicimaging/cil
One installed, CIL functionality can be tested using the following command:
export TESTS_FORCE_GPU=1 # optional, makes GPU test failures noisy
python -m unittest discover -v ./Wrappers/Python/test
If you use CIL in your research, please include citations to both the software on Zenodo, and a CIL paper:
E. Pasca, J. S. Jørgensen, E. Papoutsellis, E. Ametova, G. Fardell, K. Thielemans, L. Murgatroyd, M. Duff and H. Robarts (2023)
Core Imaging Library (CIL)
Zenodo [software archive]
DOI: https://doi.org/10.5281/zenodo.4746198
In most cases, the first CIL paper will be the appropriate choice:
J. S. Jørgensen, E. Ametova, G. Burca, G. Fardell, E. Papoutsellis, E. Pasca, K. Thielemans, M. Turner, R. Warr, W. R. B. Lionheart and P. J. Withers (2021)
Core Imaging Library - Part I: a versatile Python framework for tomographic imaging.
Phil. Trans. R. Soc. A. 379: 20200192.
DOI: https://doi.org/10.1098/rsta.2020.0192
Code: https://github.com/TomographicImaging/Paper-2021-RSTA-CIL-Part-I
However, if your work is more closely related to topics covered in our second CIL paper then please additionally or alternatively reference the second paper:
E. Papoutsellis, E. Ametova, C. Delplancke, G. Fardell, J. S. Jørgensen, E. Pasca, M. Turner, R. Warr, W. R. B. Lionheart and P. J. Withers (2021)
Core Imaging Library - Part II: multichannel reconstruction for dynamic and spectral tomography.
Phil. Trans. R. Soc. A. 379: 20200193.
DOI: https://doi.org/10.1098/rsta.2020.0193)
Code: https://github.com/TomographicImaging/Paper-2021-RSTA-CIL-Part-II