Using TIGRE with other tools#

TIGRE works on plain arrays (NumPy in Python, single arrays in MATLAB), so it fits into most imaging pipelines. This page covers the tools people most often combine it with.

Arrays in and out#

Everything TIGRE takes or returns is an ordinary array:

  • Python: float32 NumPy arrays. Images have shape geo.nVoxel, indexed img[z, y, x]; projections have shape (len(angles), *geo.nDetector), indexed proj[angle, v, u].

  • MATLAB: single arrays, indexed img(x, y, z) and proj(v, u, angle).

So any reader that produces such an array (tifffile, h5py, imageio, pydicom, MATLAB’s imread or h5read) can feed TIGRE, and the results can be saved with the same tools. Remember that TIGRE expects line integrals, not raw intensities: see Loading scanner data. For scanners that TIGRE reads directly (Nikon, Bruker, YXLON, Diondo, Varian, DXchange, DICOM), the loaders on that page also build the geometry for you.

PyTorch#

TIGRE’s projectors are available as PyTorch modules with gradients, so they can sit inside a neural network, for example in unrolled or learned iterative reconstruction. Demo 25 trains a small learned-gradient network this way.

import numpy as np
import tigre
from tigre.utilities.pytorch_bindings import create_pytorch_operator

geo = tigre.geometry(mode="fan")
angles = np.linspace(0, np.pi, 200)
A, At = create_pytorch_operator(geo, angles)   # torch.nn.Module objects

sino = A(volume)    # volume: tensor whose last three dimensions are geo.nVoxel
back = At(sino)     # sino: tensor whose last three dimensions are (angles, v, u)
  • Any number of leading dimensions (batch, channels) is allowed; each one is projected separately.

  • create_pytorch_operator(geo, angles, gpuids) chooses which GPUs TIGRE uses, independently of the GPU your tensors are on.

  • Gradients flow through both modules: the gradient of A is computed with TIGRE’s matched backprojector and the gradient of At with the forward projector. As TIGRE’s projector pairs are not exact transposes (see Projection and backprojection), these gradients are close to, but not exactly, the true ones. create_pytorch_operator(..., backprojection_type="FDK") uses FDK weights instead, as earlier versions did.

  • Each call copies the data through host memory, because TIGRE’s CUDA code works on NumPy arrays. For large batches this copy can be a noticeable part of the run time.

The bindings are in Python only and need torch installed.

CIL (Core Imaging Library)#

CIL can use TIGRE as its GPU backend. Its cil.plugins.tigre plugin provides a ProjectionOperator and an FBP processor built on TIGRE’s projectors, and cil.recon.FDK uses TIGRE for the backprojection. CIL converts its own geometry description to TIGRE’s, so you describe the scan once in CIL and can then use CIL’s optimisation framework (for example PDHG or FISTA with any of its regularisers) with TIGRE’s projectors underneath. See the CIL plugin documentation.

TIGRE needs to be installed in the same environment as CIL for the plugin to work.

ASTRA Toolbox#

There is no automatic converter between TIGRE and ASTRA geometries, but the two describe the same scans, so translating by hand is straightforward. Things to watch:

TIGRE

ASTRA

Units

Millimetres everywhere (DSO, DSD, dVoxel, dDetector)

Detector spacing and distances are in units of the volume’s voxel size (1 by default)

Source-to-origin distance

DSO

source_origin

Origin-to-detector distance

DSD - DSO

origin_det

Source position at angle 0

On the +x axis

On the −y axis (ASTRA’s cone geometry places the source at (sin θ, −cos θ, 0) times the distance)

Arbitrary geometries

Per-projection offOrigin, offDetector, rotDetector, DSO, DSD and three Euler angles per projection

cone_vec / parallel3d_vec: source, detector centre and two detector pixel vectors per projection

Because the axis and angle conventions differ, check any translation by projecting the same simple phantom (for example tigre.utilities.sample_loader.load_head_phantom) with both tools and comparing the projections before reconstructing real data.

MATLAB and Python together#

The MATLAB and Python versions of TIGRE use the same CUDA code and the same geometry, but order the axes differently (see Python and MATLAB order the axes differently). To move data between them, save it in a format both read (for example HDF5 or .mat via scipy.io) and reorder the axes: a MATLAB image img(x, y, z) becomes img.transpose(2, 1, 0) in Python ([z, y, x]), and MATLAB projections proj(v, u, angle) become proj.transpose(2, 0, 1) ([angle, v, u]).