{"id":13654499,"url":"https://github.com/TomographicImaging/CIL","last_synced_at":"2025-04-23T09:33:31.449Z","repository":{"id":37008542,"uuid":"116682013","full_name":"TomographicImaging/CIL","owner":"TomographicImaging","description":"A versatile python framework for tomographic imaging","archived":false,"fork":false,"pushed_at":"2025-04-22T10:25:38.000Z","size":196919,"stargazers_count":110,"open_issues_count":377,"forks_count":47,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-22T10:32:56.829Z","etag":null,"topics":["optimisation","python","tomography"],"latest_commit_sha":null,"homepage":"https://tomographicimaging.github.io/CIL/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TomographicImaging.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-01-08T13:45:41.000Z","updated_at":"2025-04-22T10:20:38.000Z","dependencies_parsed_at":"2023-01-17T13:01:43.962Z","dependency_job_id":"e4253c41-5b49-4d28-ab49-2439887ab4d2","html_url":"https://github.com/TomographicImaging/CIL","commit_stats":null,"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomographicImaging%2FCIL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomographicImaging%2FCIL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomographicImaging%2FCIL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomographicImaging%2FCIL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TomographicImaging","download_url":"https://codeload.github.com/TomographicImaging/CIL/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250407710,"owners_count":21425549,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["optimisation","python","tomography"],"created_at":"2024-08-02T03:00:36.087Z","updated_at":"2025-04-23T09:33:31.436Z","avatar_url":"https://github.com/TomographicImaging.png","language":"Python","funding_links":[],"categories":["Libraries"],"sub_categories":[],"readme":"# CIL - Core Imaging Library\n\n[![CI-master](https://github.com/TomographicImaging/CIL/actions/workflows/build.yml/badge.svg)](https://github.com/TomographicImaging/CIL/actions/workflows/build.yml) ![conda-ver](https://anaconda.org/ccpi/cil/badges/version.svg) ![conda-date](https://anaconda.org/ccpi/cil/badges/latest_release_date.svg) [![conda-plat](https://anaconda.org/ccpi/cil/badges/platforms.svg) ![conda-dl](https://anaconda.org/ccpi/cil/badges/downloads.svg)](https://anaconda.org/ccpi/cil)\n\n[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/TomographicImaging/CIL-Demos/HEAD?urlpath=lab/tree/binder%2Findex.ipynb)\n\nThe 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.\n\n## Documentation\n\nThe documentation for CIL can be accessed [here](https://tomographicimaging.github.io/CIL).\n\n## Installation of CIL\n\n### Conda\n\nBinary installation of CIL can be achieved with `conda`.\n\nWe recommend using either [`miniconda`](https://docs.conda.io/projects/miniconda/en/latest) or [`miniforge`](https://github.com/conda-forge/miniforge), which are both minimal installers for `conda`. We also recommend a `conda` version of at least `23.10` for quicker installation.\n\nInstall a new environment using:\n\n```sh\nconda create --name cil -c conda-forge -c https://software.repos.intel.com/python/conda -c ccpi cil=24.3.0 ipp=2021.12\n```\n\nTo install CIL and the additional packages and plugins needed to run the [CIL demos](https://github.com/TomographicImaging/CIL-Demos) install the environment with:\n\n```sh\nconda create --name cil -c conda-forge -c https://software.repos.intel.com/python/conda -c ccpi cil=24.3.0 ipp=2021.12 astra-toolbox=*=cuda* tigre ccpi-regulariser tomophantom ipykernel ipywidgets scikit-image\n```\n\nwhere:\n- `astra-toolbox=*=py*` enables CIL support for [ASTRA toolbox](http://www.astra-toolbox.com) CPU projector (2D Parallel beam only) (GPLv3 license)\n- `astra-toolbox=*=cuda*` (requires an NVIDIA GPU) enables CIL support for [ASTRA toolbox](http://www.astra-toolbox.com) GPU projectors (GPLv3 license)\n- `tigre` (requires an NVIDIA GPU) enables support for [TIGRE](https://github.com/CERN/TIGRE) toolbox projectors (BSD license)\n- `ccpi-regulariser` is the [CCPi Regularisation Toolkit](https://github.com/TomographicImaging/CCPi-Regularisation-Toolkit)\n- `tomophantom` can generate phantoms to use as test data [Tomophantom](https://github.com/dkazanc/TomoPhantom)\n- `ipykernel`  provides the IPython kernel for Jupyter (allowing jupyter notebooks to be run)\n- `ipywidgets` enables visulisation tools within jupyter noteboooks\n\n### Dependencies\n\nCIL's [optimised FDK/FBP](https://github.com/TomographicImaging/CIL/discussions/1070) `recon` module requires:\n\n1. the Intel [Integrated Performance Primitives](https://www.intel.com/content/www/us/en/developer/tools/oneapi/ipp.html#gs.gxwq5p) Library ([license](https://www.intel.com/content/dam/develop/external/us/en/documents/pdf/intel-simplified-software-license-version-august-2021.pdf)) which can be installed via conda from the `https://software.repos.intel.com/python/conda` channel.\n2. [TIGRE](https://github.com/CERN/TIGRE), which can be installed via conda from the `ccpi` channel.\n\n### Docker\n\nFinally, CIL can be run via a Jupyter Notebook enabled Docker container:\n\n```sh\ndocker run --rm --gpus all -p 8888:8888 -it ghcr.io/tomographicimaging/cil:latest\n```\n\n\u003e [!TIP]\n\u003e docker tag | CIL branch/tag\n\u003e :---|:---\n\u003e `latest` | [latest tag `v*.*.*`](https://github.com/TomographicImaging/CIL/releases/latest)\n\u003e `YY.M` | latest tag `vYY.M.*`\n\u003e `YY.M.m` | tag `vYY.M.m`\n\u003e `master` | `master`\n\u003e only build \u0026 test (no tag) | CI (current commit)\n\u003e\n\u003e See [`ghcr.io/tomographicimaging/cil`](https://github.com/TomographicImaging/CIL/pkgs/container/cil) for a full list of tags.\n\n\u003c!-- \u003cbr/\u003e --\u003e\n\n\u003e [!NOTE]\n\u003e GPU support requires [`nvidia-container-toolkit`](https://github.com/NVIDIA/nvidia-container-toolkit) and an NVIDIA GPU.\n\u003e Omit the `--gpus all` to run without GPU support.\n\n\u003c!-- \u003cbr/\u003e --\u003e\n\n\u003e [!IMPORTANT]\n\u003e Folders can be shared with the correct (host) user permissions using\n\u003e `--user $(id -u) --group-add users -v /local/path:/container/path`\n\u003e where `/local/path` is an existing directory on your local (host) machine which will be mounted at `/container/path` in the docker container.\n\n\u003c!-- \u003cbr/\u003e --\u003e\n\n\u003e [!TIP]\n\u003e See [jupyter-docker-stacks](https://jupyter-docker-stacks.readthedocs.io/en/latest/using/common.html) for more information.\n\n## Getting Started with CIL\n\n### CIL Training\nWe typically run training courses at least twice a year - check https://ccpi.ac.uk/training/ for our upcoming events!\n\n### CIL on binder\n\n[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/TomographicImaging/CIL-Demos/HEAD?urlpath=lab/tree/binder%2Findex.ipynb)\n\nJupyter Notebooks usage examples without any local installation are provided in [Binder](https://mybinder.org/v2/gh/TomographicImaging/CIL-Demos/HEAD?urlpath=lab/tree/binder%2Findex.ipynb). Please click the launch binder icon above. For more information, go to [CIL-Demos](https://github.com/TomographicImaging/CIL-Demos) and [https://mybinder.org](https://mybinder.org).\n\n### CIL Videos\n\n- [PyCon DE \u0026 PyData Berlin 2022](https://2022.pycon.de), Apr 2022: [Abstract](https://2022.pycon.de/program/GSLJUY), [Video](https://www.youtube.com/watch?v=Xd4erPj0uEs), [Material](https://github.com/TomographicImaging/CIL-Demos/blob/main/binder/PyData22_deblurring.ipynb)\n- [Training School for the Synergistic Image Reconstruction Framework (SIRF) and Core Imaging Library (CIL)](https://www.ccpsynerbi.ac.uk/SIRFCIL2021), Jun 2021: [Videos](https://www.youtube.com/playlist?list=PLTuAla-OP8WVNPWZfis6BRsWFq_S0bqvp), [Material](https://github.com/TomographicImaging/CIL-Demos/tree/main/training/2021_Fully3D)\n- [Synergistic Reconstruction Symposium](https://www.ccpsynerbi.ac.uk/symposium2019), Nov 2019: [Slides](https://www.ccppetmr.ac.uk/sites/www.ccppetmr.ac.uk/files/Papoutsellis%202.pdf), [Videos](https://www.youtube.com/playlist?list=PLyxAZuV8tuKsOY4DTDzy04DRrwkxBkTYh), [Material](https://github.com/TomographicImaging/CIL-Demos/tree/main/training/2019_SynergisticSymposium)\n\n## Building CIL from source code\n\n### Getting the code\n\nIn case of development it is useful to be able to build the software directly. You should clone this repository as\n\n```sh\ngit clone --recurse-submodule git@github.com:TomographicImaging/CIL\n```\n\nThe 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](https://github.com/TomographicImaging/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\n\n```sh\ngit submodule update --init --recursive\n```\n\n### Build dependencies\n\nTo create a conda environment with all the dependencies for building CIL run the following shell script:\n\n```sh\nbash scripts/create_local_env_for_cil_development.sh\n```\n\nOr with the CIL build and test dependencies:\n\n```sh\nbash scripts/create_local_env_for_cil_development.sh -t\n```\n\nAnd then install CIL in to this environment using CMake.\n\nAlternatively, one can use the `scripts/requirements-test.yml` to create a conda environment with all the\nappropriate dependencies on any OS, using the following command:\n\n```sh\nconda env create -f scripts/requirements-test.yml\n```\n\n### Build with CMake\n\nCMake 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:\n\n```sh\ncmake -S . -B ./build -DCMAKE_INSTALL_PREFIX=\u003cinstall_directory\u003e -DPython_EXECUTABLE=\u003cpath_to_python_executable\u003e\ncmake --build ./build --target install\n```\n\nIf targeting an active conda environment then the `\u003cinstall_directory\u003e` can be set to the `CONDA_PREFIX` environment variable (e.g. `${CONDA_PREFIX}` in Bash, or `%CONDA_PREFIX%` in the Anaconda Prompt on Windows). Similarly, `\u003cpath_to_python_executable\u003e` can be set to the active conda environment by passing `${CONDA_PREFIX}/bin/python` on linux or `%CONDA_PREFIX%\\python` in windows.\n\n#### Linux\n```sh\ncmake -S . -B ./build -DCMAKE_INSTALL_PREFIX=${CONDA_PREFIX} -DPython_EXECUTABLE=${CONDA_PREFIX}/bin/python\n```\n#### Windows\n```sh\ncmake -S . -B .\\build -DCMAKE_INSTALL_PREFIX=%CONDA_PREFIX% -DPython_EXECUTABLE=%CONDA_PREFIX%\\python\n```\n\nIf 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.\n\nBy 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:\n\n```sh\ncmake -S . -B ./build -DCMAKE_INSTALL_PREFIX=\u003cinstall_directory\u003e -DPython_EXECUTABLE=\u003cpath_to_python_executable\u003e -DIPP_LIBRARY=\u003cpath_to_ipp_library\u003e -DIPP_INCLUDE=\u003cpath_to_ipp_includes\u003e\n```\n\nThe user will then need to add the path `\u003cinstall_directory\u003e/lib` to the environment variable `PATH` or `LD_LIBRARY_PATH`, depending on system OS.\n\n\n### Building with Docker\n\nIn the repository root, simply update submodules and run `docker build`:\n\n```sh\ngit submodule update --init --recursive\ndocker build . -t ghcr.io/tomographicimaging/cil\n```\n\n\n### Testing\n\nOne installed, CIL functionality can be tested using the following command:\n\n```sh\nexport TESTS_FORCE_GPU=1  # optional, makes GPU test failures noisy\npython -m unittest discover -v ./Wrappers/Python/test\n```\n\n\n## Citing CIL\n\n\nIf you use CIL in your research, please include citations to **both** the software on Zenodo, and a CIL paper:\n\nE. Pasca, J. S. Jørgensen, E. Papoutsellis, E. Ametova, G. Fardell, K. Thielemans, L. Murgatroyd, M. Duff and H. Robarts (2023) \u003cbr\u003e\nCore Imaging Library (CIL) \u003cbr\u003e\nZenodo [software archive] \u003cbr\u003e\n**DOI:** https://doi.org/10.5281/zenodo.4746198 \u003cbr\u003e\n\n\nIn most cases, the first CIL paper will be the appropriate choice:\n\nJ. 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) \u003cbr\u003e\nCore Imaging Library - Part I: a versatile Python framework for tomographic imaging. \u003cbr\u003e\nPhil. Trans. R. Soc. A. 379: 20200192. \u003cbr\u003e\n**DOI:** https://doi.org/10.1098/rsta.2020.0192 \u003cbr\u003e\n**Code:** https://github.com/TomographicImaging/Paper-2021-RSTA-CIL-Part-I \u003cbr\u003e\n\nHowever, if your work is more closely related to topics covered in our second CIL paper then please additionally or alternatively reference the second paper:\n\nE. 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) \u003cbr\u003e\nCore Imaging Library - Part II: multichannel reconstruction for dynamic and spectral tomography. \u003cbr\u003e\nPhil. Trans. R. Soc. A. 379: 20200193. \u003cbr\u003e\n**DOI:** https://doi.org/10.1098/rsta.2020.0193) \u003cbr\u003e\n**Code:** https://github.com/TomographicImaging/Paper-2021-RSTA-CIL-Part-II \u003cbr\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTomographicImaging%2FCIL","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTomographicImaging%2FCIL","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTomographicImaging%2FCIL/lists"}