tomopari 0.1.0

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

tomopari

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

tomopari 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.

   After loading, the stack of θ-angular projection images should have shape of $N_{angles} × det_h × det_w$, where:

   • $N_{angles}$ is the number of projection views (one image per rotation angle θ),
   • $det_h$ is the detector height (vertical pixel dimension),
   • $det_w$ is the detector width (horizontal pixel dimension).

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
   Compression affects the detector dimension differently depending on the acquisition mode:

   • Vertical-axis mode → the $det_w$ will be resized
   • Horizontal-axis mode → the $det_h$ will be resized

   Available compression levels:

   • HIGH → resize to 100
   • MEDIUM → resize to 256
   • LOW → resize 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 more fine tuned in the Advanced mode.

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

8. Rotation axis
   Select how your data is organized with respect to the rotation axis:

   • Vertical → $det_w$ corresponds to the axis perpendicular to rotation.
   • Horizontal → $det_h$ corresponds to the axis perpendicular to rotation.

---

🔹 Advanced Mode

9. Manual axis alignment
   Shift the object along $det_w$ in vertical mode, and along $det_h$ in horizontal mode.

   • Negative values → shift left (toward lower pixel indices)
   • Positive values → shift right (toward higher pixel indices)

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 Slice # index.

16. Slices mode

    • Enabled → reconstruct from index 0 up to the chosen slice index in the Slice # 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
    The reconstructed volume is always generated in 32-bit float precision. Enable this option to convert the final volume to 16-bit, which significantly improves 3D rendering performance in napari. Leave it unchecked if you prefer to keep the full 32-bit float output.

---

21. Reconstruct!

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

💻 Installation Guide (No Code — Highly Recommended)

🧩 Step 1: Install Napari (Bundled App)

💡 Skip this step if you already installed Napari via pip.

You can directly download the official Napari bundled installer for your operating system:

• 🪟 Windows (.exe): 👉 napari-0.6.5-Windows-x86_64.exe

• 🐧 Ubuntu (.sh): 👉 napari-0.6.5-Linux-x86_64.sh

📘 Official Guide: Follow the Napari documentation for detailed installation steps: 🔗 Napari Installation Guide (Bundled App)

---

⚙️ Step 2: Install PyTorch Inside Napari’s Bundled Environment

💡 Skip this step if PyTorch is already installed in your Napari environment.

This step ensures PyTorch is properly installed within Napari’s internal Conda environment for full compatibility.

🪟 Windows Users

1. Download the installer: 🔗 install_torch2napari_windows.bat
2. Double-click the .bat file to run it. (It will automatically detect Napari’s environment and install PyTorch.)

🐧 Linux Users

1. Download the installer: 🔗 install_torch2napari_linux.sh

2. Run it in your terminal:

   bash install_torch2napari_linux.sh
   

---

3️⃣ Install our plugin — tomopari

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 tomopari and click Install.

---

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

pip install tomopari

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, "tomopari" is free and open source software

🐛Issues

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