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.

Create a conda environment with CIL

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 below:

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

If you prefer to give the environment your own name, include -n <env_name> in the above command. To activate the environment run

conda activate <env_name>

where <env_name> is cil_demos, cil_demos_cpu or whatever name you specified above.

Install CIL into an existing environment

If you prefer to install CIL with minimal dependencies into an existing environment you can use:

conda install -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 cil_development.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	3.0.3	ccpi::tomophantom=3.0.3	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
--	--	CT data readers	--	--
olefile	>= 0.46	olefile>=0.46	Package to process Microsoft OLE2 files, used to read ZEISS data files.	BSD-style (custom)
dxchange	>= 0.2.1	dxchange>=0.2.1	Provides an interface with TomoPy for loading tomography data.	BSD-style (custom)

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

For instructions on how to build CIL from source code, please see our Developers' Guide

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