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:
float32NumPy arrays. Images have shapegeo.nVoxel, indexedimg[z, y, x]; projections have shape(len(angles), *geo.nDetector), indexedproj[angle, v, u].MATLAB:
singlearrays, indexedimg(x, y, z)andproj(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
Ais computed with TIGRE’smatchedbackprojector and the gradient ofAtwith 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 ( |
Detector spacing and distances are in units of the volume’s voxel size (1 by default) |
Source-to-origin distance |
|
|
Origin-to-detector distance |
|
|
Source position at angle 0 |
On the +x axis |
On the −y axis (ASTRA’s |
Arbitrary geometries |
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]).