elsa - an elegant framework for tomographic reconstruction¶
elsa is a modern, flexible C++ library intended for use in tomographic reconstruction. Using concepts such as data containers, operators, and functionals, inverse problems can be modelled and then solved. elsa supports any imaging modality in general, but currently only implements forward models for X-ray Computed Tomography. Seamless GPU computing based on CUDA is supported, along with Python bindings for ease of use.
Requirements¶
elsa requires a C++17 compliant compiler, such as GCC or Clang in recent versions. Current testing includes Linux-based gcc 9, gcc 10, clang 9, and clang 10. The build process is controlled using CMake, version 3.14 or higher.
The main third party dependencies (Eigen3, spdlog, doctest) are integrated via CPM.
For CUDA support, you need a CUDA capable graphics card as well as an installation of the CUDA toolkit. Current testing includes CUDA 10.2 combined with gcc 8 or clang 8.
If you are running an Ubuntu 22.04 based Linux distribution, you can run the following commands to install the minimum required dependencies for elsa:
apt install git build-essential cmake ninja-build
If you plan to use the Python bindings, and/or follow the Python guide in our documentation, you’d want to install the following packages in an environment:
apt install python3 python3-pip
pip install numpy matplotlib scipy
Compiling¶
Once you have cloned the git repository, compilation can be done by simply by running
make build
The build CMake-based but a Makefile is provided as a convenience.
Calling make will configure the project with certain default configurations and create a sub-folder structured of the
form build/$BUILD_TYPE/$compiler.
Currently, if you want to change the install prefix, you have to directly call CMake. Provide -DCMAKE_INSTALL_PREFIX=folder during the CMake
step to select an installation destination other than the default (/usr/local on Unix-like systems).
To run all tests just run (from the root directory):
make tests
Once configuration was run once, other interesting targets for developers could be:
test
watch
You might need to install fzf, chromaterm, ag and/or entr for the best experience. ag and entr are necessary for the watch command. If you have fzf installed, you can also use partial test names and you can select one interactively.
Other build options you can pass: USE_CUDA, USE_DNNL, and GENERATE_PYBINDS. You can pass either y or n to any of these.
Compilation can also be done using plain CMake, without the Makefile. For create a build folder (e.g. mkdir build; cd build)
and run the following commands:
cmake ..
make
make install
You can provide the usual CMake options with a prefix of -D (e.g. -DCMAKE_INSTALL_PREFIX=path/to/install/dir)
or use ninja to build instead of make by appending -G Ninja to the CMake call.
We also provide a CMakePresets.json to support CMake’s presets.
You can use them the following way from the root of the repository:
cmake --preset=<name>
A couple of useful presets provided here are: default-gcc, default-clang, default-clang-libcxx and
default-coverage. For more configurations such as configurations with sanitizers check
the CMakePresets.json file. The preset names are rather long, that way it’s
easy to overwrite them with shorter names in your personal CMakeUserPresets.json.
Building against the elsa library¶
When using the elsa library in your project, we suggest using CMake as the build system.
Then you can configure elsa via the find_package(elsa) statement and link your target against elsa with target_link_libraries(myTarget elsa::all).
Alternatively, you can link more specifically only against the required elsa modules, such as target_link_libraries(myTarget elsa::core).
In your source code, #include "elsa.h" to include all of elsa; alternatively, include only the header files you are actually using to minimize compilation times.
Contributing¶
Do you want to contribute in some way? We appreciate and welcome contributions each and from everyone. Feel free to join our Matrix chat room and chat with us, about areas of interest! Further, see our contributing page.
We also have a couple of defined projects, which you can have a look at here
Contributors¶
The contributors to elsa are:
Tobias Lasser
Matthias Wieczorek
Jakob Vogel
David Frank
Maximilian Hornung
Nikola Dinev
Jens Petit
David Tellenbach
Jonas Jelten
Andi Braimllari
Michael Loipfuehrer
Jonas Buerger
History¶
elsa started its life as an internal library at the Computational Imaging and Inverse Problems group at the Technical University of Munich. This open-source version is a modernized and cleaned up version of our internal code and will contain most of its functionality, modulo some parts which we unfortunately cannot share (yet).
Releases: (changelog)
v0.7: major feature release, e.g. deep learning support (October 27, 2021)
v0.6: major feature release, e.g. seamless GPU-computing, Python bindings (February 2, 2021)
v0.5: the “projector” release (September 18, 2019)
v0.4: first public release (July 19, 2019)
Citation¶
If you are using elsa in your work, we would like to ask you to cite us:
@inproceedings{LasserElsa2019,
author = {Tobias Lasser and Maximilian Hornung and David Frank},
title = {{elsa - an elegant framework for tomographic reconstruction}},
volume = {11072},
booktitle = {15th International Meeting on Fully Three-Dimensional Image Reconstruction in Radiology and Nuclear Medicine},
editor = {Samuel Matej and Scott D. Metzler},
organization = {International Society for Optics and Photonics},
publisher = {SPIE},
pages = {570 -- 573},
keywords = {tomography, tomographic reconstruction, inverse problems, software framework, C++, Python},
year = {2019},
doi = {10.1117/12.2534833},
URL = {https://doi.org/10.1117/12.2534833}
}
If you are using the deep learning module of elsa, we would like to ask you to cite us as well:
@inproceedings{TellenbachElsa2020,
author = {David Tellenbach and Tobias Lasser},
title = {{elsa - an elegant framework for precision learning in tomographic reconstruction}},
booktitle = {6th International Conference on Image Formation in X-ray Computed Tomography},
venue = {Regensburg, Germany},
month = {August},
year = {2020},