ToMoDL Reconstruction

A plugin for optical projection tomography reconstruction with model-based neural networks.

This napari plugin was generated with Cookiecutter using @napari's cookiecutter-napari-plugin template.

🔬 Introduction

napari-tomodl is a napari plugin that enables users to easily reconstruct tomography images directly from raw projection data. Simply load an ordered stack of projection files into the napari viewer, and the plugin takes care of reconstructing the corresponding tomographic volume.

🚀 Usage

1. Load ordered stack
   

   Go to File → Open Files as Stack... and load the angular projections for parallel beam optical tomography reconstruction.

2. Select image layer
   

   In the dropdown menu, click Select image layer and choose the loaded volume.

From here you can choose between two reconstruction modes: Basic and Advanced.

🔹 Basic Mode

3. Half-rotation

   • Click Half rotation if your projection data was acquired from 0° to 180°.
   • Leave it unchecked if data was acquired from 0° to 360°.

4. Automatic axis alignment
   If the rotation axis is not correctly aligned during acquisition, enable Automatic axis alignment. This aligns the sinogram to the detector center using the Wall-method.

5. Compression
   Projection images are assumed to have shape (Theta, Detector size, Z) in vertical axis mode.
   You can compress along the Z-axis:

   • HIGH → resize Z to 100
   • MEDIUM → resize Z to 256
   • LOW → resize Z to 512
   • NO → no compression

6. Reconstruction method

   • FBP CPU / FBP GPU → from the QBI_radon library
   • TOMODL CPU / TOMODL GPU / UNET CPU / UNET GPU → proposed in our ToMoDL-paper

7. Smoothing level
   Select smoothing strength (only applies to TOMODL methods). Can be adjusted in the Advanced mode.

   • LOW → 2
   • MEDIUM → 4
   • HIGH → 6

8. Rotation axis

   • Vertical → for data shape (Theta, Detector size, Z)
   • Horizontal → for data shape (Theta, Z, Detector size)

🔹 Advanced Mode

9. Manual axis alignment
   Shift the object along the detector axis (Z-axis).

   • Negative values → shift left
   • Positive values → shift right

10. Reshape volume
    Select a reconstruction size (alternative to compression levels from Basic mode).

11. Flat-field correction
    Apply flat-field correction to projection data before reconstruction.

12. Clip to circle
    Constrain the reconstructed object inside a circular region.

13. Filter (FBP only)
    Choose the filter to apply when using FBP methods.

14. Full volume mode

    • Enabled → reconstruct the whole volume.

15. One Slice mode

    • Enabled → reconstruct only a single slice at the # of slices to reconstruct index.

16. Slices mode

    • Enabled → reconstruct from index 0 up to the chosen slice index in the # of slices to reconstruct field.

17. Batch size
    Number of slices processed simultaneously:

    • Higher values → faster reconstruction but greater GPU memory usage.
    • On CPU → limited to processing 1 slice at a time.

18. Invert colors
    Invert grayscale values in the reconstructed volume.

19. 16-bit conversion
    Convert the reconstructed volume to 16-bit for faster 3D rendering.
    Leave unchecked to keep 32-bit float output.

21. Reconstruct!

A new layer will appear on top of the projections stack with the reconstructed volume.

💻 Installation Guide

1️⃣ Install napari as a bundled app

Please visit the official napari documentation and follow the instructions here:
👉 Napari Installation Guide (bundled app)

You can also directly download the installer for your operating system:

• Windows (.exe):
  napari-0.6.4-Windows-x86_64.exe
• Ubuntu (.sh):
  napari-0.6.4-Linux-x86_64.sh

2️⃣ Install PyTorch inside Napari’s bundled environment

This guide provides detailed instructions for installing PyTorch within the Napari bundled environment. Follow the steps carefully to ensure compatibility and a smooth installation process.

💡 Tip: Ensure Napari is closed before proceeding with the installation to avoid conflicts. Before installing PyTorch, verify your system's CUDA version if you plan to use GPU support. This ensures compatibility with the PyTorch version and CUDA toolkit.

Check CUDA Version:

• Open a Command Prompt (Windows) or terminal (Linux).
• Run the following command:

  nvidia-smi
  
  

• Choose a pytorch-cuda version that is less than or equal to your CUDA version. Supported versions include 11.8, 12.1, or 12.4.
• For more details on compatible PyTorch versions, visit the PyTorch Previous Versions page.

🪟 For Windows Users

1. Open Command Prompt (do not use PowerShell, as it may cause path resolution issues).

2. Run the appropriate command based on your hardware setup:

   🔹 For GPU Support

   Ensure your CUDA version matches the pytorch-cuda version specified (e.g., 12.1). Replace 2.5.0 and 12.1 with versions compatible with your system if needed.

   "%LOCALAPPDATA%\napari-0.6.4\envs\napari-0.6.4\Scripts\conda.exe" install -y pytorch==2.5.0 pytorch-cuda=12.1 -c conda-forge -c pytorch -c nvidia --override-channels
   
   

   🔹 For CPU Only

   If you do not have a compatible NVIDIA GPU or prefer to use CPU, run:

   "%LOCALAPPDATA%\napari-0.6.4\envs\napari-0.6.4\Scripts\conda.exe" install -y pytorch==2.5.0 cpuonly -c pytorch -c nvidia -c conda-forge --override-channels
   
   

🐧 For Linux Users

1. Open a terminal.

2. Run the appropriate command based on your hardware setup:

   🔹 For GPU Support

   Ensure your CUDA version matches the pytorch-cuda version specified (e.g., 12.1). Replace 2.5.0 and 12.1 with versions compatible with your system if needed.

   ~/.local/napari-0.6.4/bin/conda install -y pytorch==2.5.0 pytorch-cuda=12.1 -c conda-forge -c pytorch -c nvidia --override-channels
   
   

   🔹 For CPU Only

   If you do not have a compatible NVIDIA GPU or prefer to use CPU, run:

   ~/.local/napari-0.6.4/bin/conda install -y pytorch==2.5.0 cpuonly -c pytorch -c nvidia -c conda-forge --override-channels
   
   

3️⃣ Install our plugin — napari-tomodl

Our plugin is available on the napari-hub.

🔹 Option 1: Install directly from napari

1. Open napari.
2. Go to Plugins → Install/Uninstall Plugins.
3. Search for napari-tomodl and click Install.

🔹 Option 2: Install via pip (from Napari Console) Open napari’s Python Console and type:

pip install napari-tomodl

After installation, restart napari to apply the changes. 😊

🤝 Contributing

Contributions are very welcome. Tests can be run with tox, please ensure the coverage at least stays the same before you submit a pull request.

📜 License

Distributed under the terms of the MIT license, "napari-tomodl" is free and open source software

🐛Issues

If you encounter any problems, please [file an issue] along with a detailed description.