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

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 file alrecon.yml.

[!NOTE] You can install Miniconda if you have conda not on your computer and have no desire for a "fully-fledged" anaoonda environment (to date, the tomopy package is only available for conda). There is an option for a "Quick command line install", which runs the complete installation without having you to click. In case of doubt, you can omit the last step ~/miniconda3/bin/conda init bash and activate conda by source miniconda3/bin/activate.

[!NOTE] To use TomoPy with CUDA features, install TomoPy from 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 with 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).