# napari-tomodl
[](https://github.com/marcoso96/napari-tomodl/raw/main/LICENSE)
[](https://pypi.org/project/napari-tomodl)
[](https://python.org)
<!-- [](https://github.com/marcoso96/napari-tomodl/actions) -->
[](https://codecov.io/gh/marcoso96/napari-tomodl)
[](https://napari-hub.org/plugins/napari-tomodl)
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.
<!--
Don't miss the full getting started guide to set up your new package:
https://github.com/napari/cookiecutter-napari-plugin#getting-started
and review the napari docs for plugin developers:
https://napari.org/stable/plugins/index.html
-->
## 🔬 Introduction
**napari-tomodl** is a [napari](https://napari.org/) 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.
<!-- make this line be bigger and bold -->
<h3>From here you can choose between two reconstruction modes: Basic and Advanced.</h3>
### 🔹 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**
- Enabled → reconstruct the whole volume.
- Disabled → reconstruct only a subset of slices along the detector axis (faster for testing).
15. **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**.
16. **One Slice**
- Enabled → reconstruct only a single slice at the specified index.
- Disabled → reconstruct from index 0 up to the chosen slice index in the **# of slices to reconstruct** field.
17. **Invert colors**
Invert grayscale values in the reconstructed volume.
18. **16-bit conversion**
Convert the reconstructed volume to **16-bit** for faster 3D rendering.
Leave unchecked to keep **32-bit float** output.
---
19. **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)](https://napari.org/stable/tutorials/fundamentals/installation_bundle_conda.html)
You can also directly download the installer for your operating system:
- **Windows (.exe):**
[napari-0.6.4-Windows-x86_64.exe](https://github.com/napari/napari/releases/download/v0.6.4/napari-0.6.4-Windows-x86_64.exe)
- **Ubuntu (.sh):**
[napari-0.6.4-Linux-x86_64.sh](https://github.com/napari/napari/releases/download/v0.6.4/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:
```bash
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](https://pytorch.org/get-started/previous-versions).
#### 🪟 **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.
```bash
"%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:
```bash
"%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.
```bash
~/.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:
```bash
~/.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](https://napari-hub.org/plugins/napari-tomodl.html).
---
🔹 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:
```bash
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.
[napari]: https://github.com/napari/napari
[Cookiecutter]: https://github.com/audreyr/cookiecutter
[@napari]: https://github.com/napari
[MIT]: http://opensource.org/licenses/MIT
[BSD-3]: http://opensource.org/licenses/BSD-3-Clause
[GNU GPL v3.0]: http://www.gnu.org/licenses/gpl-3.0.txt
[GNU LGPL v3.0]: http://www.gnu.org/licenses/lgpl-3.0.txt
[Apache Software License 2.0]: http://www.apache.org/licenses/LICENSE-2.0
[Mozilla Public License 2.0]: https://www.mozilla.org/media/MPL/2.0/index.txt
[cookiecutter-napari-plugin]: https://github.com/napari/cookiecutter-napari-plugin
[QBI_radon]: https://github.com/QBioImaging/QBI_radon
[Wall-method]: https://doi.org/10.1088/0031-9155/50/19/015
[ToMoDL-paper]: https://doi.org/10.1038/s41598-023-47650-3
[napari]: https://github.com/napari/napari
[tox]: https://tox.readthedocs.io/en/latest/
[pip]: https://pypi.org/project/pip/
[PyPI]: https://pypi.org/
Raw data
{
"_id": null,
"home_page": null,
"name": "napari-tomodl",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Marcos Antonio Obando, Minh Nhat Trinh, David Palecek, Germ\u00e1n Mato, Teresa Correia",
"author_email": "marcos.obando@ib.edu.ar",
"download_url": "https://files.pythonhosted.org/packages/f2/0b/2b5355eab221b5861327a7f93fe4dbe6ce6fce8146d9c809e675edf503c9/napari_tomodl-0.2.22.tar.gz",
"platform": null,
"description": "# napari-tomodl\n\n[](https://github.com/marcoso96/napari-tomodl/raw/main/LICENSE)\n[](https://pypi.org/project/napari-tomodl)\n[](https://python.org)\n<!-- [](https://github.com/marcoso96/napari-tomodl/actions) -->\n[](https://codecov.io/gh/marcoso96/napari-tomodl)\n[](https://napari-hub.org/plugins/napari-tomodl)\n\nA plugin for optical projection tomography reconstruction with model-based neural networks.\n\n----------------------------------\n\nThis [napari] plugin was generated with [Cookiecutter] using [@napari]'s [cookiecutter-napari-plugin] template.\n\n<!--\nDon't miss the full getting started guide to set up your new package:\nhttps://github.com/napari/cookiecutter-napari-plugin#getting-started\n\nand review the napari docs for plugin developers:\nhttps://napari.org/stable/plugins/index.html\n-->\n## \ud83d\udd2c Introduction\n\n**napari-tomodl** is a [napari](https://napari.org/) 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. \n\n## \ud83d\ude80 Usage\n\n1. **Load ordered stack** \n\n\n Go to **File \u2192 Open Files as Stack...** and load the angular projections for parallel beam optical tomography reconstruction.\n\n2. **Select image layer** \n \n\n In the dropdown menu, click **Select image layer** and choose the loaded volume. \n\n<!-- make this line be bigger and bold -->\n<h3>From here you can choose between two reconstruction modes: Basic and Advanced.</h3>\n\n### \ud83d\udd39 Basic Mode\n \n\n3. **Half-rotation** \n - Click **Half rotation** if your projection data was acquired from 0\u00b0 to 180\u00b0. \n - Leave it unchecked if data was acquired from 0\u00b0 to 360\u00b0.\n\n4. **Automatic axis alignment** \n 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].\n\n5. **Compression** \n Projection images are assumed to have shape **(Theta, Detector size, Z)** in vertical axis mode. \n You can compress along the Z-axis: \n - **HIGH** \u2192 resize Z to 100 \n - **MEDIUM** \u2192 resize Z to 256 \n - **LOW** \u2192 resize Z to 512 \n - **NO** \u2192 no compression \n\n6. **Reconstruction method** \n - **FBP CPU / FBP GPU** \u2192 from the [QBI_radon] library \n - **TOMODL CPU / TOMODL GPU / UNET CPU / UNET GPU** \u2192 proposed in our [ToMoDL-paper] \n\n7. **Smoothing level** \n Select smoothing strength (only applies to **TOMODL** methods). Can be adjusted in the **Advanced mode**.\n - **LOW** \u2192 2 \n - **MEDIUM** \u2192 4 \n - **HIGH** \u2192 6 \n\n8. **Rotation axis** \n - **Vertical** \u2192 for data shape (Theta, Detector size, Z) \n - **Horizontal** \u2192 for data shape (Theta, Z, Detector size)\n---\n\n### \ud83d\udd39 Advanced Mode\n\n\n9. **Manual axis alignment** \n Shift the object along the detector axis (Z-axis). \n - Negative values \u2192 shift left \n - Positive values \u2192 shift right \n\n10. **Reshape volume** \n Select a reconstruction size (alternative to compression levels from Basic mode).\n\n11. **Flat-field correction** \n Apply flat-field correction to projection data before reconstruction.\n\n12. **Clip to circle** \n Constrain the reconstructed object inside a circular region.\n\n13. **Filter (FBP only)** \n Choose the filter to apply when using FBP methods. \n\n14. **Full volume** \n - Enabled \u2192 reconstruct the whole volume. \n - Disabled \u2192 reconstruct only a subset of slices along the detector axis (faster for testing).\n\n15. **Batch size** \n Number of slices processed simultaneously: \n - Higher values \u2192 faster reconstruction but greater GPU memory usage. \n - On CPU \u2192 limited to processing **1 slice at a time**. \n\n16. **One Slice** \n - Enabled \u2192 reconstruct only a single slice at the specified index. \n - Disabled \u2192 reconstruct from index 0 up to the chosen slice index in the **# of slices to reconstruct** field. \n\n17. **Invert colors** \n Invert grayscale values in the reconstructed volume.\n\n18. **16-bit conversion** \n Convert the reconstructed volume to **16-bit** for faster 3D rendering. \n Leave unchecked to keep **32-bit float** output.\n---\n\n19. **Reconstruct!** \n\n\n\n A new layer will appear on top of the projections stack with the reconstructed volume.\n\n\n## \ud83d\udcbb Installation Guide\n\n### 1\ufe0f\u20e3 Install **napari** as a bundled app\n\nPlease visit the official napari documentation and follow the instructions here: \n\ud83d\udc49 [Napari Installation Guide (bundled app)](https://napari.org/stable/tutorials/fundamentals/installation_bundle_conda.html)\n\nYou can also directly download the installer for your operating system:\n- **Windows (.exe):** \n [napari-0.6.4-Windows-x86_64.exe](https://github.com/napari/napari/releases/download/v0.6.4/napari-0.6.4-Windows-x86_64.exe)\n- **Ubuntu (.sh):** \n [napari-0.6.4-Linux-x86_64.sh](https://github.com/napari/napari/releases/download/v0.6.4/napari-0.6.4-Linux-x86_64.sh)\n\n---\n### 2\ufe0f\u20e3 Install **PyTorch** inside Napari\u2019s bundled environment\n\nThis guide provides detailed instructions for installing **PyTorch** within the Napari bundled environment. Follow the steps carefully to ensure compatibility and a smooth installation process.\n\n> **\ud83d\udca1 Tip:** Ensure Napari is closed before proceeding with the installation to avoid conflicts.\nBefore 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.\n\n**Check CUDA Version**:\n - Open a **Command Prompt** (Windows) or **terminal** (Linux).\n - Run the following command:\n ```bash\n nvidia-smi\n ```\n - 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.\n - For more details on compatible PyTorch versions, visit the [PyTorch Previous Versions page](https://pytorch.org/get-started/previous-versions).\n\n#### \ud83e\ude9f **For Windows Users**\n\n1. Open **Command Prompt** (do **not** use PowerShell, as it may cause path resolution issues).\n2. Run the appropriate command based on your hardware setup:\n\n #### \ud83d\udd39 For GPU Support\n 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.\n\n ```bash\n \"%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\n ```\n\n #### \ud83d\udd39 For CPU Only\n If you do not have a compatible NVIDIA GPU or prefer to use CPU, run:\n\n ```bash\n \"%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\n ```\n\n#### \ud83d\udc27 **For Linux Users**\n1. Open a **terminal**.\n2. Run the appropriate command based on your hardware setup:\n\n #### \ud83d\udd39 For GPU Support\n 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.\n\n ```bash\n ~/.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\n ```\n\n #### \ud83d\udd39 For CPU Only\n If you do not have a compatible NVIDIA GPU or prefer to use CPU, run:\n\n ```bash\n ~/.local/napari-0.6.4/bin/conda install -y pytorch==2.5.0 cpuonly -c pytorch -c nvidia -c conda-forge --override-channels\n ```\n---\n### 3\ufe0f\u20e3 Install our plugin \u2014 **napari-tomodl**\n\nOur plugin is available on the [napari-hub](https://napari-hub.org/plugins/napari-tomodl.html).\n---\n\ud83d\udd39 Option 1: Install directly from napari\n1. Open **napari**. \n2. Go to **Plugins \u2192 Install/Uninstall Plugins**. \n3. Search for **napari-tomodl** and click **Install**.\n---\n\ud83d\udd39 Option 2: Install via pip (from Napari Console)\nOpen napari\u2019s **Python Console** and type:\n\n```bash\npip install napari-tomodl\n```\n\n> After installation, **restart napari** to apply the changes. \ud83d\ude0a\n\n## \ud83e\udd1d Contributing\n\nContributions are very welcome. Tests can be run with [tox], please ensure\nthe coverage at least stays the same before you submit a pull request.\n\n## \ud83d\udcdc License\n\nDistributed under the terms of the [MIT] license,\n\"napari-tomodl\" is free and open source software\n\n## \ud83d\udc1bIssues\n\nIf you encounter any problems, please [file an issue] along with a detailed description.\n\n[napari]: https://github.com/napari/napari\n[Cookiecutter]: https://github.com/audreyr/cookiecutter\n[@napari]: https://github.com/napari\n[MIT]: http://opensource.org/licenses/MIT\n[BSD-3]: http://opensource.org/licenses/BSD-3-Clause\n[GNU GPL v3.0]: http://www.gnu.org/licenses/gpl-3.0.txt\n[GNU LGPL v3.0]: http://www.gnu.org/licenses/lgpl-3.0.txt\n[Apache Software License 2.0]: http://www.apache.org/licenses/LICENSE-2.0\n[Mozilla Public License 2.0]: https://www.mozilla.org/media/MPL/2.0/index.txt\n[cookiecutter-napari-plugin]: https://github.com/napari/cookiecutter-napari-plugin\n\n[QBI_radon]: https://github.com/QBioImaging/QBI_radon\n[Wall-method]: https://doi.org/10.1088/0031-9155/50/19/015\n[ToMoDL-paper]: https://doi.org/10.1038/s41598-023-47650-3\n[napari]: https://github.com/napari/napari\n[tox]: https://tox.readthedocs.io/en/latest/\n[pip]: https://pypi.org/project/pip/\n[PyPI]: https://pypi.org/\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A plugin for optical projection tomography reconstruction with model-based neural networks.",
"version": "0.2.22",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b5619f7b572bdf63f56561cab4cdc0cc45f93875ba8f65cd8c9b44cc1801b57a",
"md5": "a55becd9c08e7a684d6280a22b71d9de",
"sha256": "9bad5547037fd93efbb29493050c63b669ad2bfcba84df18e7b597b32746916f"
},
"downloads": -1,
"filename": "napari_tomodl-0.2.22-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a55becd9c08e7a684d6280a22b71d9de",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 873469,
"upload_time": "2025-10-20T01:06:02",
"upload_time_iso_8601": "2025-10-20T01:06:02.723194Z",
"url": "https://files.pythonhosted.org/packages/b5/61/9f7b572bdf63f56561cab4cdc0cc45f93875ba8f65cd8c9b44cc1801b57a/napari_tomodl-0.2.22-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f20b2b5355eab221b5861327a7f93fe4dbe6ce6fce8146d9c809e675edf503c9",
"md5": "688dfe3fb4f128f2a0a9fe554bb2c623",
"sha256": "1a5f88ccb55aea41f1916d6f1f1cb4a7dd2475f45f4a9ae9487a8618c694974c"
},
"downloads": -1,
"filename": "napari_tomodl-0.2.22.tar.gz",
"has_sig": false,
"md5_digest": "688dfe3fb4f128f2a0a9fe554bb2c623",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 877145,
"upload_time": "2025-10-20T01:06:04",
"upload_time_iso_8601": "2025-10-20T01:06:04.904204Z",
"url": "https://files.pythonhosted.org/packages/f2/0b/2b5355eab221b5861327a7f93fe4dbe6ce6fce8146d9c809e675edf503c9/napari_tomodl-0.2.22.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-20 01:06:04",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "napari-tomodl"
}
JSON