CIL - Core Imaging Library

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.

Documentation

The documentation for CIL can be accessed here.

Installation of CIL

Conda

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 minimal environment with CIL using:

conda create --name cil -c https://software.repos.intel.com/python/conda -c conda-forge -c ccpi cil=25.0.0

A number of additional dependencies are required for specific functionality in CIL, these should be added to your environment as necessary. See the dependency table below for details.

Binary packages and dependencies

While building the CIL package we test with specific versions of dependencies. These are listed in the build.yml GitHub workflow and environment-test.yml. The following table tries to resume the tested versions of CIL and its required and optional dependencies. If you use these packages as a backend please remember to cite them in addition to CIL.

Package	Tested Version	Conda install command	Description	License
Python	3.10 - 3.12	"python>=3.10,<=3.12"		PSF-2.0
Numpy	1.23 - 1.26	"numpy>=1.23,<2"		BSD-3-Clause
IPP	2021.12	-c https://software.repos.intel.com/python/conda ipp=2021.12	The Intel Integrated Performance Primitives Library (required for the CIL recon class).	ISSL
--	--	Optional dependencies	--	--
ASTRA toolbox	2.1	CPU: conda-forge::astra-toolbox=2.1=py* GPU: conda-forge::astra-toolbox=2.1=cuda*	CT projectors, FBP and FDK.	GPL-3.0
TIGRE	2.6	ccpi::tigre=2.6	CT projectors, FBP and FDK.	BSD-3-Clause
CCPi Regularisation Toolkit	24.0.1	ccpi::ccpi-regulariser=24.0.1	Toolbox of regularisation methods.	Apache-2.0
TomoPhantom	2.0.0	ccpi::tomophantom=2.0.0	Generates phantoms to use as test data.	Apache-2.0
ipykernel		ipykernel	Provides the IPython kernel to run Jupyter notebooks.	BSD-3-Clause
ipywidgets		ipywidgets	Enables visualisation tools within jupyter noteboooks.	BSD-3-Clause
zenodo_get	>= 1.6	zenodo_get>=1.6	Downloads datasets from Zenodo, is used by dataexample to get data used in CIL-Demos	AGPL-3.0

We maintain an environment file with the required packages to run the CIL demos which you can use to create a new environment. This will have specific and tested versions of all dependencies that are outlined in the table above:

conda env create -f https://tomographicimaging.github.io/scripts/env/cil_demos.yml

Or for a CPU-only environment which will work for a limited number of CIL demos

conda env create -f https://tomographicimaging.github.io/scripts/env/cil_demos_cpu.yml

Docker

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.

Getting Started with CIL

CIL Training

We typically run training courses at least twice a year - check https://ccpi.ac.uk/training/ for our upcoming events!

CIL on binder

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.

CIL Videos

• 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

Building CIL from source code

Getting the code

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 git@github.com: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

Building with pip

Install Dependencies

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 pip.

Alternatively, one can use the scripts/requirements-test.yml to create a conda environment with all the appropriate dependencies, using the following command:

conda env create -f ./scripts/requirements-test.yml

or, on windows:

conda env create -f ./scripts/requirements-test-windows.yml

Build CIL

A C++ compiler is required to build the source code. Let's suppose that the user is in the source directory, then the following commands should work:

pip install --no-deps .

If not installing inside a conda environment, then the user might need to set the locations of optional libraries:

pip install . -Ccmake.define.IPP_ROOT="<path_to_ipp>" -Ccmake.define.OpenMP_ROOT="<path_to_openmp>"

Building with Docker

In the repository root, simply update submodules and run docker build:

git submodule update --init --recursive
docker build . -t ghcr.io/tomographicimaging/cil

Testing

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

Citing CIL

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