Describing your scanner: the geometry#

Every TIGRE operation takes three things: the data (an image or a set of projections), a geometry that describes the scanner, and the angles at which the projections were taken. This page explains the geometry fields, the coordinate system they live in, and how to describe less common scanners.

Coordinate system#

TIGRE uses a right-handed coordinate system centred on the origin, the point the source and detector rotate around.

  • At angle 0 the source sits on the positive x axis, at a distance DSO from the origin, and the detector sits on the other side, at a distance DSD from the source.

  • The detector’s u axis (its columns) is parallel to y, and its v axis (its rows) is parallel to z.

  • A positive angle rotates the source and detector around the z axis.

  • The image is centred on the origin unless you move it with offOrigin.

To see your own geometry, plot it:

import numpy as np
import tigre

geo = tigre.geometry_default()
tigre.plot_geometry(geo, angle=-np.pi / 6)
geo = defaultGeometry();
plotgeometry(geo, -pi/6);
Diagram of TIGRE's cone-beam geometry, labelling the source, detector and image with their distances, sizes and offsets

TIGRE’s geometry for one projection, with the names of the geo fields. From Biguri et al. (2025), TIGRE v3, figure 1 (CC BY 4.0). MATLAB’s showGeoCBCTDiagram shows a similar diagram.#

The fields#

All distances are in millimetres (any unit works, as long as every field uses the same one) and all angles are in radians.

Field

Size

Meaning

DSD

1, or one per angle

Distance from the source to the detector.

DSO

1, or one per angle

Distance from the source to the origin.

nDetector

2

Number of detector pixels.

dDetector

2

Size of one detector pixel.

sDetector

2

Total size of the detector, nDetector * dDetector.

nVoxel

3

Number of voxels in the image.

dVoxel

3

Size of one voxel.

sVoxel

3

Total size of the image, nVoxel * dVoxel.

offOrigin

3, or 3 per angle

Shift of the image centre from the origin. Optional, default 0.

offDetector

2, or 2 per angle

Shift of the detector centre. Optional, default 0.

rotDetector

3, or 3 per angle

Detector rotation (roll, pitch, yaw). Optional, default 0.

COR

1, or one per angle

Centre-of-rotation shift, along y. Optional, default 0.

accuracy

1

Sampling step of the interpolated projector, in voxels. Optional, default 0.5.

mode

text

"cone" (default) or "parallel".

TIGRE checks that nVoxel * dVoxel equals sVoxel, and that nDetector * dDetector equals sDetector, and raises an error if they don’t match. Set all three of each group, as in the example below.

Python and MATLAB order the axes differently#

This is the most common source of confusion when moving code between the two languages.

  • MATLAB stores vectors in (x, y, z) order for the image and (u, v) for the detector, and images are indexed img(x, y, z).

  • Python reverses them to match NumPy’s index order: (z, y, x) for the image and (v, u) for the detector. Images are indexed img[z, y, x] and projections proj[angle, v, u].

This applies to nVoxel, dVoxel, sVoxel, offOrigin, nDetector, dDetector, sDetector and offDetector. rotDetector is the exception: it is (roll, pitch, yaw) in both languages.

For example, moving the image 10 mm along the rotation axis is geo.offOrigin = [0; 0; 10] in MATLAB and geo.offOrigin = np.array([10, 0, 0]) in Python.

A complete example#

import numpy as np
import tigre

geo = tigre.geometry()
# Distances
geo.DSD = 1536                                  # source to detector (mm)
geo.DSO = 1000                                  # source to origin (mm)
# Detector, in (v, u) order
geo.nDetector = np.array([512, 512])            # pixels
geo.dDetector = np.array([0.8, 0.8])            # pixel size (mm)
geo.sDetector = geo.nDetector * geo.dDetector   # detector size (mm)
# Image, in (z, y, x) order
geo.nVoxel = np.array([256, 256, 256])          # voxels
geo.sVoxel = np.array([256, 256, 256])          # image size (mm)
geo.dVoxel = geo.sVoxel / geo.nVoxel            # voxel size (mm)
# Optional
geo.offOrigin = np.array([0, 0, 0])             # image offset (mm)
geo.offDetector = np.array([0, 0])              # detector offset (mm)
geo.accuracy = 0.5                              # interpolated projector step (voxels)
geo.mode = "cone"

angles = np.linspace(0, 2 * np.pi, 360, endpoint=False)
print(geo)
% Distances
geo.DSD = 1536;                             % source to detector (mm)
geo.DSO = 1000;                             % source to origin (mm)
% Detector, in (u, v) order
geo.nDetector = [512; 512];                 % pixels
geo.dDetector = [0.8; 0.8];                 % pixel size (mm)
geo.sDetector = geo.nDetector .* geo.dDetector;
% Image, in (x, y, z) order
geo.nVoxel = [256; 256; 256];               % voxels
geo.sVoxel = [256; 256; 256];               % image size (mm)
geo.dVoxel = geo.sVoxel ./ geo.nVoxel;      % voxel size (mm)
% Optional
geo.offOrigin = [0; 0; 0];                  % image offset (mm)
geo.offDetector = [0; 0];                   % detector offset (mm)
geo.accuracy = 0.5;                         % interpolated projector step (voxels)
geo.mode = 'cone';

angles = linspace(0, 2*pi, 360);
angles(end) = [];

If you are just experimenting, the default geometries save typing: tigre.geometry_default(high_resolution=False) in Python (a 64³ image) or defaultGeometry('nVoxel', [64; 64; 64]) in MATLAB.

Angles#

angles is usually a vector of N rotation angles in radians, one per projection. TIGRE does not need them to be equally spaced, sorted or to cover a full circle.

You can also give an N×3 array (3×N in MATLAB). Each row is then a set of ZYZ Euler angles, which describes source and detector trajectories that are not a circle around z. See the arbitrary-axis demo (Python, MATLAB). FDK does not support these geometries; use an iterative algorithm.

Fields that change per projection#

DSD, DSO, offOrigin, offDetector, rotDetector and COR can be given once, or once per angle. A per-angle value lets you describe geometries that are not a plain circular scan.

Helical scans. Move the image along the rotation axis at each angle with offOrigin. In Python that is column 0, geo.offOrigin[:, 0]; in MATLAB it is row 3, geo.offOrigin(3, :). See demo 13 (Python, MATLAB).

Detector offsets. A detector shifted sideways, for example to widen the field of view with a half-fan scan, is described with offDetector. See demo 14 (Python, MATLAB).

Detector rotation. Small misalignments of the detector are described with rotDetector. The first value (roll) rotates the detector within its own plane, which is usually the only one that needs correcting in practice. See demo 17 (Python, MATLAB).

Centre of rotation. If the rotation axis does not project onto the centre of the detector, set COR. TIGRE can estimate it from the data with tigre.computeCOR (Python) or computeCOR (MATLAB).

Fixed detectors and moving sources. Python has helpers that build per-angle geometries for these cases: tigre.staticDetectorGeo, tigre.staticDetLinearSourceGeo and tigre.ArbitrarySourceDetMoveGeo.

Other scanner types#

Parallel beam. Set geo.mode = "parallel". All rays are then parallel; DSD and DSO only set where each ray starts and ends, so keep both ends outside the image. In Python, tigre.geometry(mode="parallel", nVoxel=np.array([nz, ny, nx])) builds a parallel geometry with one-millimetre voxels and pixels. See demo 15.

2D tomography. TIGRE is a 3D code, so a 2D problem is a 3D problem one voxel thick: set the image to 1 slice and the detector to 1 row, and make the detector pixel height equal to the voxel height. In Python that means nVoxel = [1, ny, nx] and nDetector = [1, nu]. See demo 16.

Digital breast tomosynthesis. A limited-angle cone-beam scan; see demo 19.

Curved detectors. TIGRE’s projectors assume a flat detector. Resample curved-detector data onto a flat detector first with flatten_detector (in Python, from tigre.utilities.curved_detector import flatten_detector), then reconstruct as usual. See the curved-detector demo (d24 in Python, d024 in MATLAB).

Checking your geometry#

Most reconstruction problems are geometry problems. Before tuning an algorithm:

  1. Plot the geometry and check that the image sits inside the cone of rays.

  2. Reconstruct with FDK (or FBP for parallel beam). Blurred or doubled edges usually mean a wrong COR, a wrong offDetector or the wrong sign of the angles.

  3. Forward-project your reconstruction with Ax and compare it with your measured projections. They should line up.