diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ef36d7df9..f68ac3c7e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,13 +1,13 @@ * 22.0.0 - - Strongly convex functionality in TotalVariation and FGP_TV Functions. - - Refactored KullbackLeibler function class. Fix bug on gradient method for SIRF objects. - - Numba added as a CIL requirement. + - Strongly convex functionality in TotalVariation and FGP_TV Functions + - Refactored KullbackLeibler function class. Fix bug on gradient method for SIRF objects + - Numba added as a CIL requirement - Simplify initialisation of `CentreOfRotation.ImageSharpness` with new parameter `backend` - - Added ISTA algorithm. Improve inheritance of proximal gradient algorithms. + - Added ISTA algorithm. Improve inheritance of proximal gradient algorithms - Updated interface to `plugins.tigre`/`plugins.astra` `FBP` and `ProjectionOperator` classes - Update NikonDataReader to parse and set up geometry with: `ObjectTilt` `CentreOfRotationTop` and `CentreOfRotationBottom` - Cleaned up unit test structure and output - - Removal of deprecated code + - Removal of deprecated code: - AcquisitionGeometry `__init__` no longer returns a configured geometry, use factory `create` methods instead - `subset` method removed, use `get_slice` or `reorder` methods - NikonDataReader `normalize` kwarg removed, use `normalise` @@ -18,15 +18,15 @@ - Modules not moved should be considered deprecated - CIL remains licensed as APACHE-2.0 - Minor bug fixes to the CPU 2D Parallel-beam FBP - - Add ndim property for DataContainer class. + - Add ndim property for DataContainer class - Fixes show_geometry compatibility issue with matplotlib 3.5 - - Added ZEISSDataReader with cone/parallel beam, slicing, TXM Functionality. + - Added ZEISSDataReader with cone/parallel beam, slicing, TXM Functionality - Raise exception if filename or data haven't been set in NexusDataWriter - - Fixes error when update_objective_interval is set to 0 in an algorithm run. + - Fixes error when update_objective_interval is set to 0 in an algorithm run - Deprecated: - TXRMDataReader is deprecated in favour of ZEISSDataReader - GitHub Actions: - - Update to version 0.1.1 of lauramurgatroyd/build-sphinx-action for building the documentation - ensures docs are always built from cil master. + - Update to version 0.1.1 of lauramurgatroyd/build-sphinx-action for building the documentation - ensures docs are always built from cil master * 21.4.1 - Removed prints from unittests and cleanup of unittest code. diff --git a/NOTICE.txt b/NOTICE.txt index 396c3fe65e..04e20115c9 100644 --- a/NOTICE.txt +++ b/NOTICE.txt @@ -1,23 +1,27 @@ CCPi Core Imaging Library (CIL). -Copyright 2017-2021 Rutherford Appleton Laboratory STFC -Copyright 2017-2021 University of Manchester +Copyright 2017-2022 United Kingdom Research and Innovation +Copyright 2017-2022 University of Manchester This software product is developed for the Collaborative Computational -Project in Tomographic Imaging CCPi (http://www.ccpi.ac.uk/) at RAL STFC (http://www.stfc.ac.uk), University of Manchester +Project in Tomographic Imaging CCPi (http://www.ccpi.ac.uk/) with +substantial contributions by UKRI-STFC and The University of Manchester. and other contributing institutions. Main contributors in alphabetical order: Evelina Ametova (UoM) Gemma Fardell (STFC) Jakob Jorgensen (DTU) +Laura Murgatroyd (STFC) Evangelos Papoutsellis (STFC) Edoardo Pasca (STFC) Other contributors: Claire Delplancke (UoB) Daniil Kazantsev (Diamond Light Source) -Laura Murgatroyd (STFC) +Tomas Kulhanek (STFC) Srikanth Nagella (STFC) +Andrew Sharits (UES Inc.) Kris Thielemans (UCL) +Sam Tygier (STFC) Ryan Warr (UoM) -Tomas Kulhanek (STFC) + diff --git a/README.md b/README.md index bc48eb2a39..ae94548512 100644 --- a/README.md +++ b/README.md @@ -4,65 +4,76 @@ | [![Build Status](https://anvil.softeng-support.ac.uk/jenkins/buildStatus/icon?job=CILsingle/CCPi-Framework)](https://anvil.softeng-support.ac.uk/jenkins/job/CILsingle/job/CCPi-Framework/) | [![Build Status](https://anvil.softeng-support.ac.uk/jenkins/buildStatus/icon?job=CILsingle/CCPi-Framework-dev)](https://anvil.softeng-support.ac.uk/jenkins/job/CILsingle/job/CCPi-Framework-dev/) |![conda version](https://anaconda.org/ccpi/cil/badges/version.svg) ![conda last release](https://anaconda.org/ccpi/cil/badges/latest_release_date.svg) [![conda platforms](https://anaconda.org/ccpi/cil/badges/platforms.svg) ![conda dowloads](https://anaconda.org/ccpi/cil/badges/downloads.svg)](https://anaconda.org/ccpi/cil) | # 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. - -## 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) +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. -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/), April 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) June 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), November 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). ## Documentation The documentation for CIL can be accessed [here](https://tomographicimaging.github.io/CIL). -## Installation + +# Installation of CIL Binary installation of CIL can be done with `conda`. Install a new environment using: ```bash -conda create --name cil -c conda-forge -c intel -c ccpi cil=21.4.1 +conda create --name cil -c conda-forge -c intel -c ccpi cil=22.0.0 ``` To install CIL and the additional packages and plugins needed to run the [CIL demos](https://github.com/TomographicImaging/CIL-Demos) install the environment with: ```bash -conda create --name cil -c conda-forge -c intel -c astra-toolbox -c ccpi cil=21.4.1 cil-astra tigre ccpi-regulariser tomophantom +conda create --name cil -c conda-forge -c intel -c astra-toolbox -c ccpi cil=22.0.0 astra-toolbox tigre ccpi-regulariser tomophantom ``` where, -```cil-astra``` will allow you to use CIL with the [ASTRA toolbox](http://www.astra-toolbox.com/) projectors (GPLv3 license). +```astra-toolbox``` will allow you to use CIL with the [ASTRA toolbox](http://www.astra-toolbox.com/) projectors (GPLv3 license). ```tigre``` will allow you to use CIL with the [TIGRE](https://github.com/CERN/TIGRE) toolbox projectors (BSD license). -```cudatoolkit``` If you have GPU drivers compatible with more recent CUDA versions you can modify this package selector (installing tigre via conda requires 9.2). - ```ccpi-regulariser``` will give you access to the [CCPi Regularisation Toolkit](https://github.com/vais-ral/CCPi-Regularisation-Toolkit). ```tomophantom``` [Tomophantom](https://github.com/dkazanc/TomoPhantom) will allow you to generate phantoms to use as test data. -### Dependency +```cudatoolkit``` If you have GPU drivers compatible with more recent CUDA versions you can modify this package selector (installing tigre via conda requires 9.2). + + +## Dependency CIL's [optimised FDK/FBP](https://github.com/TomographicImaging/CIL/discussions/1070) `recon` module requires: 1. 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 `intel` [channel](https://anaconda.org/intel/ipp). 2. [TIGRE](https://github.com/CERN/TIGRE), which can be installed via conda from the `ccpi` channel. -## Building from source code -### Getting the code +# Getting Started with CIL + + +## 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/), April 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) June 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), November 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 + +## Getting the code In case of development it is useful to be able to build the software directly. You should clone this repository as ```bash @@ -75,26 +86,47 @@ The use of `--recurse-submodule` is necessary if the user wants the examples dat git submodule update --init ``` -### Build with CMake -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: +## Build dependencies +To create a conda environment with all the dependencies for building CIL run: ```bash +sh scripts/create_local_env_for_cil_development.sh -n NUMPY_VERSION -p PYTHON_VERSION -e ENVIRONMENT_NAME +``` + +Or with the CIL build and test dependencies: +```bash +sh scripts/create_local_env_for_cil_development_tests.sh -n NUMPY_VERSION -p PYTHON_VERSION -e ENVIRONMENT_NAME +``` + +And then install CIL in to this environment using CMAKE. + + +## Build with CMake +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: + +```bash mkdir build cd build cmake .. -DCMAKE_INSTALL_PREFIX= cmake --build . --target install ``` -The user then needs to add the path to `/lib` where the library is installed to the environment variable `PATH` or `LD_LIBRARY_PATH`, depending on system +If targeting an active conda environment then the `` can be set to `${CONDA_PREFIX}`. + +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: -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 ```bash cmake .. -DCMAKE_INSTALL_PREFIX= -DIPP_LIBRARY= -DIPP_INCLUDE= ``` -## References +The user will then need to add the path `/lib` to the environment variable `PATH` or `LD_LIBRARY_PATH`, depending on system OS. + + +# References [1] Jørgensen JS et al. 2021 [Core Imaging Library Part I: a versatile python framework for tomographic imaging](https://doi.org/10.1098/rsta.2020.0192). Phil. Trans. R. Soc. A 20200192. [**Code.**](https://github.com/TomographicImaging/Paper-2021-RSTA-CIL-Part-I) [Pre-print](https://arxiv.org/abs/2102.04560) diff --git a/docs/docs_environment.yml b/docs/docs_environment.yml index 3f48c6f204..aae8fc6626 100644 --- a/docs/docs_environment.yml +++ b/docs/docs_environment.yml @@ -23,7 +23,7 @@ dependencies: - sphinx-copybutton=0.3 - astra-toolbox>=1.9.9.dev5,<2.1 - ccpi-regulariser=21.0.0 - - tomophantom=1.4.10 + - tomophantom=2.0.0 - ipywidgets - tqdm - jinja2<3.1