Repository Python API¶
Directory README¶
LION: AI tools for learned tomographic and other image reconstruction tasks¶
University of Cambridge Computational Image Analysis (CIA) groups AI tools for image reconstruction (e.g. tomographic reconstruction), LION (Learned Iterative Optimization Networks)
The library is a place to gather and provide resources for image reconstruction, such as Computed Tomography reconstruction, using machine learning tools implemented in PyTorch.
It contains data dowloading and pre-processing, torch DataSet classes for the existing data, and Experiments class with implementation of default realistic experiments, several data-driven methods and models, and features to enhance reproduciblity.
WARNING Building in progress. This is a tool in development in very early stages. Many things are bound to fail and many more are bound to change. If you want to help with development, send an email to Ander Biguri and/or open and issue or a discussion.
Install:
git clone https://github.com/CambridgeCIA/LION.git
cd LION
git submodule update --init --recursive # Legacy: for MSD_pytorch_
conda env create --file=env_base.yml --name=lion # You can change 'lion' to a different env name
conda activate lion
python -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128
pip install .
To change CUDA version, update the python -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128 line as well as the cuda-version=12.8 specified in env_base.yml.
If you would like to contribute to the development of LION, you can replace the last line of the above set of commands by
pip install -e ".[dev]"
to make the installation editable (i.e. changes you make to the source will be visible when you restart the REPL or start a new Python process) and install the development dependencies. Afterwards, install the pre-commit hooks. They run Black and the test suite before allowing a commit (see .pre-commit-config.yaml). The development extra and hook use the same pinned Black release, so a fresh development installation and pre-commit format identically. The test hook includes CUDA-marked tests when CUDA is available and otherwise runs the CPU-safe suite. The GitHub test workflow uses the same hardware detection, so routing it to a GPU-capable runner automatically enables CUDA tests:
pre-commit install --hook-type pre-commit --hook-type post-merge
GUI Git clients such as VS Code may not inherit an activated Conda environment. Configure the Python interpreter used by this checkout’s test hook once:
git config --local lion.testPython "$CONDA_PREFIX/bin/python"
Run that command while the LION development environment is active. The setting is local to the checkout and is not committed.
Datasets¶
Several DataSets are currently supported by LION. To point the package to the correct storage location use export LION_DATA_PATH=/path/to/Datasets. For convenience, this can be added to your .bashrc or similar file.
NOTE: If you are part of CIA at DAMTP, you already have access to these datasets and you don’t need to follow any instruction to dowload them. They should be accessible using export LION_DATA_PATH=/store/LION/datasets
The supported Datasets are 2DeteCT, LIDC-IDRI,
Models/Methods¶
LION supports all types of data-driven methods for CT reconstructions. They can, as a general taxonomy, be described as:
Post-Processing methods: a “denoising” network. Takes a noisy recon and cleans it.
Iterative Unrolled methods: Uses the operator to imitate iterative recon algorithms, but has learned parts.
Learned regularizer: Explicitly learned regularization functions.
Plug-and-Play (PnP): Implicit learned regularization, a regularization optimization step is learned, rather than an explicit one.
Folders for each of these exist in LION/models. An extra folder for standard CNNs is also available.
Read more about which models are available in each class here
Operators¶
Originally designed for tomographic reconstruction tasks, specifically Computed Tomography (CT), LION has been extended to work with more operators. Read more about operators here
Developers¶
Read developers.md
Documentation¶
The Sphinx user guide and API reference live under docs/source.
The standard development install includes everything required to build it;
pip install -e ".[docs]" is available as a documentation-only alternative.
Build the HTML site with:
conda activate lion
make -C docs html
The generated site is written to docs/_build/html. PaDIS, LIDC-IDRI, and
the CT interfaces used by the reproduction workflow are documented in detail;
older package areas are currently presented as explicitly labelled stubs.
