Alrecon (الريكُن)

Pure Python Computed Tomography reconstruction web application. Built with Solara.

How to cite

If you use alrecon please cite:

Iori et al., (2024). Alrecon: computed tomography reconstruction web application based on Solara. Open Research Europe, 4(54). https://doi.org/10.12688/openreseurope.16863.2

Features

• CPU and GPU-accelerated CT reconstruction using the TomoPy and ASTRA toolboxes
• Sinogram and reconstructed volume visuzalization with napari or ImageJ
• Control over the sinogram portion to be loaded and processed
• Module for the optimization of the tomographic center of rotation
• Module for the correction of sinogram stripe artifacts
• Phase-retrieval module
• Different CT reconstruction algorithms, including iterative methods
• Compression of output volume data to integer and JPEG 2000 format
• Job scheduling on reconstruction HPC cluster using SLURM
• Keep a log of reconstruction jobs to a Google spreadsheet

Note

Alrecon uses TopoPy and as such supports only parallel-beam reconstruction geometries (synchrotron CT). Reconstruction of fan-beam data is not supported at the moment.

Installation

1. Checkout this repository:

git clone https://github.com/gianthk/alrecon.git

2. Navigate to the repository and create a virtual environment with all necessary dependencies:

cd alrecon
conda env create --file envs/alrecon-base.yml
conda activate alrecon-base

Note

If you already have a destination virtual environment for alrecon, you can install manually the requirements listed in the file alrecon-base.yml.

Note

If you don't have conda and want to keep things simple you can install Miniconda instead.

Note

To use TomoPy with CUDA features, install TomoPy through conda following these instructions.

3. Build the alrecon app:

pip install -e .

Usage

Run the alrecon solara web application on your localhost

solara run alrecon.pages --host localhost

Run alrecon within jupyter

1. Make sure that the alrecon virtual environment is activated and ipykernel installed:

conda activate alrecon
pip install --user ipykernel

or:

conda install -c anaconda ipykernel 

2. Install ipykernel in the alrecon virtual environment:

python -m ipykernel install --user --name=alrecon

3. Launch Jupyter Notebook or Jupyter Lab instance:

jupyter lab

4. Open and run the cells of the notebook launch_within_jupyter.ipynb.

You can take a look at solara's documnetation for more information on the different ways of running solara applications.

---

Integration with Google Sheets

• Alrecon allows you to keep a consistent log of all reconstruction jobs on an online master Google spreadsheet.
• The integration uses gspread, a Python API for Google Sheets.
• You will need to set up your Google Cloud account, enable Google Sheets API, and create a Secret Key with read/write permission to your online master Google sheet. Follow these instructions to setup the integration with Google Sheets API.

How it works

1. Set up your Google Cloud account and a Secret Key with read/write permissions as described above
2. Save your Secret Key and modify the alrecon settings file with the path to your Secret Key file
3. Create or upload to your Google account a spreadsheet master. You can find a template in resources/foo_master.xls
4. If the option log to google master spreadsheet is activated, each time you submit a job to the HPC cluster the reconstruction settings are logged as a new line of the master spreadsheet

HPC cluster integration

Alrecon can generate reconstruction job files and submit them to the workers of a cluster, if this is available. The current integration assumes that the slurm workload manager is available on the host, and is designed for the ID10-BEATS beamline of SESAME. Here are some general instructions on how to set up alrecon to work with your HPC facility:

• The remote_user specified in the alrecon settings file must exist and have ssh access to the remote_host
• slurm must be installed and running on the host
• Slurm job file creation is handled by the slurm.py module in alrecon/components
• An example slurm .job file is available in resources/foo.job
• At ID-10 BEATS, we use a Python script named BEATS_recon.py to perform complete TomoPy reconstruction pipelines. The script is available on the BEATS_recon repository. A copy of the script is in this repository in resources/BEATS_recon.py.
• The recon_script specified in the settings file must contain the full path to your reconstruction script (BEATS_recon.py in our case). This must be accessible by the host.
• To adapt alrecon to a different reconstruction script or command:
  • Start by taking a look at the slurmjob class in alrecon/components/slurm.py
  • Create a new set_recon_command method following the example of set_recon_command_beats

Use with napari

napari is a powerful pure Python multi-dimensional image viewer. Alrecon supports napari only when running the app through Jupyter.

Setup ImageJ launcher

To launch ImageJ from the alrecon web app follow these steps:

1. Modify the path to your ImageJ executable in the alrecon general settings

2. Copy the FolderOpener_virtual.ijm ImageJ macro contained in /alrecon/imagej_macros/ to the plugin folder of your ImageJ installation. On Linux this is something like /opt/Fiji.app/macros/.

Acknowledgements

This project has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No [822535](Beamline for Tomography at SESAME BEATS).