The CI CWI group develops a set of libraries and software for real-time tomographic reconstruction. The main software packages are:
- RECAST3D. The visualization software. This typically runs at a workstation, and is controlled by a user looking at live reconstructions of arbitrarily oriented slices.
- SliceRecon. The reconstruction software library. This runs on a computer with a GPU (it can be the same as the workstation running RECAST3D). It receives the projection data, and performs slice reconstructions.
- TomoPackets. The glue between the different components. This library defines a protocol for sending messages between scanners, reconstruction nodes, and visualization workstations.
Depending on the data source, an adapter is needed that converts the acquisition metadata and projection data into a common format defined by TomoPackets. This common format that is used as input to SliceRecon.
(Recommended) Installation using Conda
The RECAST3D reconstruction stack can be installed using:
conda install -c cicwi -c astra-toolbox/label/dev recast3d tomopackets slicerecon
The software is developed for Linux. SliceRecon requires a CUDA capable GPU.
(Advanced) Manual installation
Here, we will describe in detail how to manually build all the different components of the live reconstruction software stack.
If you run into unexpected problems while following this guide, please let us know!.
0. (optional) Setting up a fresh Conda (or VirtualEnv) environment
Although it is not strictly necessary to use any Python component, it is by far the easiest way to extend and customize the software. We would suggest making a new environment in which the Python bindings to our libraries are installed. For example:
conda create -n live python=3.7 conda activate live
if you choose to do this, make and activate the environment before following the rest of these instructions.
1. Building and installing ASTRA
Recommended: Using conda
Currently (March 2020), the required files are only part of the development package of ASTRA. This can be installed using:
conda install -c astra-toolbox/label/dev astra-toolbox
Install the ASTRA toolbox into your conda environment using:
conda install -c astra-toolbox astra-toolbox
ASTRA also includes headers and configuration files as part of its conda package.
Alternative: From source
The software requires at least version v1.9 of the ASTRA toolbox, available from the ASTRA repository on github.
We have to install the ASTRA toolbox. We
need ASTRA with CUDA support, and install it in such a way so that
is able to find the library. See the ASTRA documentation for details on installing ASTRA as a C++ library.
The rest of this guide assumes that pkgconfig can find the ASTRA configuration, for this you might have to run something along the lines of:
# when installed using conda export PKG_CONFIG_PATH=$CONDA_PREFIX/lib/pkgconfig/:$PKG_CONFIG_PATH # when installed from source export PKG_CONFIG_PATH=$ASTRA_SRC_DIR/build/linux:$PKG_CONFIG_PATH
2. Installing prerequisites
Next, make sure you have the necessary OpenGL development headers and libraries and other dependencies installed. This highly depends on your operating system and/or distribution. A non-exhaustive lists of packages that might be required on Fedora 31:
dnf install python-devel boost-devel libXinerama-devel fftw-devel dnf groupinstall "X Software Development" dnf groupinstall "Development Tools"
Optionally, preinstall the submodule dependencies to speed up the build. For example:
dnf install python-devel eigen3-devel boost-devel libXinerama-devel glm-devel
If our build script cannot find these dependencies, it will build them from source.
3. Cloning the repository
git clone https://www.github.com/cicwi/RECAST3D recast3d-stack cd recast3d-stack git submodule update --init --recursive
4. Building the software
cd tomopackets mkdir build && cd build cmake .. && make
When developing your own data adapter (or using an existing one), it is easiest to use the Python bindings to the TomoPackets communication library. To install it into your Python environment, run the following:
cd .. pip install --user cmake_setuptools pip install -e .
You can now develop and run TomoPackets extensions such as data adapters.
Next, we install SliceRecon.
cd ../slicerecon mkdir build && cd build cmake .. && make
This will create a binary
Next, we install the Python bindings.
cd ../python/ pip install -e .
To build RECAST3D, run:
cd ../../recast3d mkdir build && cd build cmake .. && make
This will create a binary
recast3d. Test if you can run RECAST3D:
This should open an empty white window with a menubar. If you run into any issues, please let us know!
5. Testing the installation
To test if the SliceRecon software is installed correctly, try the following steps.
Start up a RECAST3D instance. Change directories to the
recast3d/builddirectory we made before, and run:
Start up a SliceRecon server, that connects to RECAST3D and listens for incoming (projection) data. Change directories to
slicerecon/build, and run:
./slicerecon_server --slice-size 512 --preview-size 256
Switching windows to the RECAST3D software, you should see a new scene with empty slices.
Pushing data into SliceRecon. The server is unable to reconstruct anything interesting, because it has received no data yet. To push some example data into SliceRecon, we run one of the adapter examples. For example, relative to the
cd examples/adapters python zero_adapter.py
This will send data containing zeros to the SliceRecon server.