Welcome to PYRO-NN, a Python framework for state-of-the-art reconstruction algorithms seamlessly integrated into PyTorch. This library serves as a bridge to the layers implemented in PYRO-NN-Layers.

PYRO-NN is designed to bring cutting-edge reconstruction techniques to neural networks. The open-access paper detailing its capabilities and design can be accessed here.

Dependencies: PYRO-NN relies on the pyronn_layers. These are now available through pip. For those interested in the source code, it's available at PYRO-NN-Layers.

If you find PYRO-NN beneficial for your research or applications, please consider citing our work:

@article{PYRONN2019,
   author = {Syben, Christopher and Michen, Markus and Stimpel, Bernhard and Seitz, Stephan and Ploner, Stefan and Maier, Andreas K.},
   title = {Technical Note: PYRO-NN: Python reconstruction operators in neural networks},
   year = {2019},
   journal = {Medical Physics},
}

1. Download and Install Anaconda: Start by downloading the Anaconda distribution for your operating system from the official Anaconda website.

2. Create a Virtual Environment: Once you've installed Anaconda, create a virtual environment for your project. This will help you manage dependencies and avoid conflicts.

   conda create --name your_env_name python=3.12

3. Activate the Virtual Environment:

   conda activate your_env_name

4. Install the CUDA Toolkit: To make use of NVIDIA's CUDA capabilities, install the CUDA toolkit specific to version 11.8.0:

   conda install -c nvidia/label/cuda-11.8.0 cuda-toolkit

5. Install PyTorch and Associated Libraries: You can install PyTorch, torchvision, and torchaudio for the specified CUDA version:

   pip install torch==2.5.0 torchvision==0.20.0 torchaudio==2.5.0 --index-url https://download.pytorch.org/whl/cu118

6. Install Pyronn: Finally, install the pyronn library using the provided wheel file:

   pip install pyronn-0.3.2-cp312-cp312-win_amd64.whl

   For Linux users, the wheel file is available here. Python 3.11, cuda 11.8 and torch 2.1.0 are the supported versions.

For convenience, an automated installation script install_pyronn.bat is provided in the pyronn directory. This script will:

• Create a Conda environment with python=3.12
• Install CUDA toolkit 11.8.0
• Install PyTorch 2.5.0 and dependencies
• Install PYRO-NN from the provided wheel file

For a hands-on installation:

• Microsoft Visual C++: Version 14.0 or higher.
• Build Package: Essential for the build process.
• CUDA: Ensure you have version 10.2 or later.

1. Version Check: Ensure the torch version in pyproject.toml aligns with your environment to avoid DLL errors and install C++ Compiler on Linux:

   conda install conda-forge::gxx_linux-64

2. Package Build:

   python -m build

3. Wheel File: Post-build, locate the wheel file in the dist directory.

Tip: Adjust pyproject.toml if you need a different torch version.

This guide demonstrates the foundational steps for utilizing PYRO-NN layers, using a simplified example. We'll initiate with the creation of a sinogram and its corresponding geometry.

from pyronn.ct_reconstruction.geometry.geometry import Geometry
from pyronn.ct_reconstruction.helpers.trajectories.circular_trajectory import circular_trajectory_2d

# Volume Configuration:
volume_size = 256
volume_shape = [volume_size, volume_size]
volume_spacing = [1, 1]

# Detector Configuration:
detector_shape = [800]
detector_spacing = [1]

# Trajectory Configuration:
number_of_projections = 360
angular_range = 2 * np.pi

# Initialize Geometry:
geometry = Geometry()
geometry.init_from_parameters(volume_shape=volume_shape, volume_spacing=volume_spacing,
                              detector_shape=detector_shape, detector_spacing=detector_spacing,
                              number_of_projections=number_of_projections, angular_range=angular_range,
                              trajectory=circular_trajectory_2d)

To leverage the capabilities of PYRO-NN, instantiate the Geometry class. This feeds the system essential geometric information. If you lack a scanner, simulate one with PYRO-NN.

from pyronn.ct_reconstruction.helpers.phantoms import shepp_logan
from pyronn.ct_reconstruction.layers.projection_2d import ParallelProjection2D

# Create a Phantom:
phantom = shepp_logan.shepp_logan_enhanced(volume_shape)
phantom = torch.tensor(np.expand_dims(phantom, axis=0).copy(), dtype=torch.float32).cuda()

# Generate Sinogram:
sinogram = ParallelProjection2D().forward(phantom, **geometry)

Ensure that the geometry for both projection and reconstruction is consistent. The function ParallelProjection2d().forward(phantom, **geometry) emulates a scanner.

Before implementing the Filtered Back Projection (FBP) algorithm, pre-process the sinogram:

import torch
from pyronn.ct_reconstruction.helpers.filters import filters

# Apply Filter:
reco_filter = torch.tensor(
    filters.shepp_logan_2D(geometry.detector_shape, geometry.detector_spacing, geometry.number_of_projections)).cuda()
x = torch.fft.fft(sinogram, dim=-1, norm="ortho")
x = torch.multiply(x, reco_filter)
x = torch.fft.ifft(x, dim=-1, norm="ortho").real

Explore various filters in the filters module.

Post-processing is straightforward; retrieve the reconstruction with a single line:

from pyronn.ct_reconstruction.layers.backprojection_2d import ParallelBackProjection2D

# Obtain Reconstruction:
reco = ParallelBackProjection2D().forward(x.contiguous(), **geometry)
reco = reco.cpu().numpy()

Note: PYRO-NN bifurcates projection and reconstruction into distinct classes. Always remember to detach the GPU post-processing.

The Geometry class offers initialization from parameters, JSON files, or EZRT files. The exact geometry type hinges on the provided trajectory. Parameters are cataloged within the parameter_dict dictionary.

The image reconstructed using backprojection will exhibit a difference of approximately 1000 magnitudes compared to the original image.

For detailed updates and modifications, refer to the CHANGELOG.md.

This project abides by the Apache-2.0 License.