Metadata-Version: 2.1
Name: cil
Version: 26.0.0
Summary: Core Imaging Library
Keywords: tomography,optimisation
Maintainer-Email: CIL developers <tomography+cil@stfc.ac.uk>
License: Apache-2.0
Project-URL: homepage, https://tomographicimaging.github.io/CIL
Project-URL: documentation, https://tomographicimaging.github.io/CIL/nightly
Project-URL: repository, https://github.com/TomographicImaging/CIL
Project-URL: changelog, https://github.com/TomographicImaging/CIL/blob/master/CHANGELOG.md
Requires-Python: >=3.10
Requires-Dist: h5py
Requires-Dist: numba
Requires-Dist: numpy<3,>=1.23
Requires-Dist: pillow
Requires-Dist: pywavelets
Requires-Dist: scipy>=1.4.0
Requires-Dist: tqdm
Requires-Dist: packaging
Provides-Extra: plugins
Requires-Dist: ipywidgets; extra == "plugins"
Requires-Dist: dxchange>=0.2.1; extra == "plugins"
Requires-Dist: olefile>=0.46; extra == "plugins"
Provides-Extra: gpu
Requires-Dist: astra-toolbox<3,>=2; extra == "gpu"
Description-Content-Type: text/markdown

# CIL - Core Imaging Library

[![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)

[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/TomographicImaging/CIL-Demos/HEAD?urlpath=lab/tree/binder%2Findex.ipynb)

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](https://tomographicimaging.github.io/CIL).

## Installation of CIL

### Conda

Binary installation of CIL can be achieved with `conda`.

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

#### Create a conda environment with CIL
We maintain an environment file with the required packages to run the [CIL demos](https://github.com/TomographicImaging/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:

```sh
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](https://github.com/TomographicImaging/CIL-Demos)
```sh
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:
```sh
conda install -c conda-forge -c ccpi cil=26.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
See our [documentation](https://tomographicimaging.github.io/CIL/nightly/dependencies) for details of dependency versions we support.

### Docker

Finally, CIL can be run via a Jupyter Notebook enabled Docker container:

```sh
docker run --rm --gpus all -p 8888:8888 -it ghcr.io/tomographicimaging/cil:latest
```

> [!TIP]
> docker tag | CIL branch/tag
> :---|:---
> `latest` | [latest tag `v*.*.*`](https://github.com/TomographicImaging/CIL/releases/latest)
> `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`](https://github.com/TomographicImaging/CIL/pkgs/container/cil) for a full list of tags.

<!-- <br/> -->

> [!NOTE]
> GPU support requires [`nvidia-container-toolkit`](https://github.com/NVIDIA/nvidia-container-toolkit) and an NVIDIA GPU.
> Omit the `--gpus all` to run without GPU support.

<!-- <br/> -->

> [!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.

<!-- <br/> -->

> [!TIP]
> See [jupyter-docker-stacks](https://jupyter-docker-stacks.readthedocs.io/en/latest/using/common.html) 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

[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/TomographicImaging/CIL-Demos/HEAD?urlpath=lab/tree/binder%2Findex.ipynb)

Jupyter 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).

### CIL Videos

- [PyCon DE & 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)
- [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)
- [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)

## Building CIL from source code

For instructions on how to build CIL from source code, please see our [Developers' Guide](https://tomographicimaging.github.io/CIL/nightly/developer_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) <br>
Core Imaging Library (CIL) <br>
Zenodo [software archive] <br>
**DOI:** https://doi.org/10.5281/zenodo.4746198 <br>

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) <br>
Core Imaging Library - Part I: a versatile Python framework for tomographic imaging. <br>
Phil. Trans. R. Soc. A. 379: 20200192. <br>
**DOI:** https://doi.org/10.1098/rsta.2020.0192 <br>
**Code:** https://github.com/TomographicImaging/Paper-2021-RSTA-CIL-Part-I <br>

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) <br>
Core Imaging Library - Part II: multichannel reconstruction for dynamic and spectral tomography. <br>
Phil. Trans. R. Soc. A. 379: 20200193. <br>
**DOI:** https://doi.org/10.1098/rsta.2020.0193) <br>
**Code:** https://github.com/TomographicImaging/Paper-2021-RSTA-CIL-Part-II <br>
