tomojax.geometry
Scan geometry: grids, detectors, beams and field-of-view helpers.
The geometry classes import without JAX; the field-of-view helpers load it on
first use. Expert helpers for calibration state and axis order are in
tomojax.geometry.api.
| Name | Summary |
|---|---|
ConeBeam | Source and detector placement in the lab frame, shared by every view. |
ConeGeometry | Cone-beam scan of a sample rotating about +z, or a tilted axis. |
ConeSegments | A scan of cone-beam segments with separate source and detector arrangements. |
Detector | Regular detector plane metadata. |
Geometry | Common pose interface for projector-compatible geometries. |
Grid | Regular voxel grid metadata. |
LaminographyGeometry | Laminography geometry with tilted rotation axis (parallel-ray model). |
ParallelGeometry | Parallel-beam CT geometry with axis-aligned detector. |
RotationAxisGeometry | Parallel-ray geometry with an arbitrary lab-frame rotation axis direction. |
ScanGeometry | A geometry that names its reconstruction grid, detector and view angles. |
beam_of | Return a geometry's cone beam, or None for parallel-beam geometries. |
compute_roi | Compute conservative FOV half-extents and grid dims from detector. |
cylindrical_mask_xy | Boolean mask (nx, ny) for cylindrical FOV in the X-Y plane. |
grid_from_detector_fov | Return a new Grid cropped to the detector FOV bounding box. |
grid_from_detector_fov_cube | Return a new cubic Grid cropped to the detector FOV (nx=ny=nz). |
grid_from_detector_fov_slices | Return an ROI Grid with square x-y slices and z from detector height. |
grid_volume_origin | Return the physical centre of voxel (0, 0, 0) for a grid. |
stack_view_poses | Stack world-from-object poses for the first n_views views. |
ConeSegments
class ConeSegments(
segments: tuple[ScanGeometry, ...],
*,
trajectory_lengths: tuple[int, ...] = (),
)A scan of cone-beam segments with separate source and detector arrangements.
Segments share the reconstruction grid and the detector's pixel count; their views follow one another. Multi-orbit scans (a source at several heights), stacked scans of a tall sample and tiled fields of view are segmented. The iterative solvers and projectors take them. FDK retains every arrangement but is only an approximate inverse for noncircular trajectories.
Parameters
segments : tuple of ScanGeometry Nonempty cone-beam geometries in acquisition order, sharing a grid and pixel sizes. trajectory_lengths : tuple of int, optional View counts of independent acquisition trajectories, in order. Empty defaults to one trajectory per segment. Calibration arrangements may change within a trajectory: a single acquisition with per-view detector offsets has one trajectory but many geometry segments.
Raises
ValueError If segments disagree in sampling, or trajectory counts do not partition the views.
ConeSegments.grid
@property
grid: GridThe shared reconstruction grid.
Returns
Grid Reconstruction grid shared by all segments.
ConeSegments.detector
@property
detector: DetectorThe first segment's detector (every segment has its pixel count).
Returns
Detector First segment's detector, with the shared pixel counts and pitches.
ConeSegments.angles
@property
angles: list[float]Every view's rotation angle, segment after segment.
Returns
list of float Rotation angles in degrees, concatenated in segment order.
ConeSegments.beam
@property
beam: ConeBeamNot defined: each segment has its own beam (see cone_parts).
Raises
ValueError Always: each segment has its own beam; a single-beam method cannot use this scan.
ConeSegments.pose_for_view
pose_for_view(i: int) -> PoseMatrixReturn the world-from-object pose of view i in its segment.
Parameters
i : int Zero-based view index.
Returns
tuple of tuple of float Row-major 4 x 4 homogeneous world-from-object transform.
Raises
IndexError If the view index lies beyond the last segment.
ConeSegments.rays_for_view
rays_for_view(i: int) -> RayPairReturn the ray callbacks of view i in its segment.
Parameters
i : int Zero-based view index.
Returns
tuple of callable Origin and unit-direction callbacks taking detector pixel indices (u, v).
Raises
IndexError If the view index lies beyond the last segment.
ConeSegments.stack_poses
stack_poses(n_views: int, dtype: jnp.dtype) -> jax.ArrayEvery segment's poses, stacked (see stack_view_poses).
Parameters
n_views : int Number of leading views to return. dtype : dtype Output pose dtype.
Returns
jax.Array Concatenated world-from-object poses, shape (views, 4, 4).
Geometry
class Geometry()Common pose interface for projector-compatible geometries.
Projector contract: pose_for_view(i) returns a 4x4 world_from_object
transform. The core projector combines that pose with the supplied
Grid/Detector to construct the standard parallel-beam detector
rays; it does not consume custom per-pixel ray callbacks.
Concrete geometries may expose rays_for_view(i) as an optional
metadata/inspection helper, but that helper is not part of the projector
contract and custom rays are not supported by forward_project_view or
backproject_view.
Geometry.pose_for_view
pose_for_view(i: int) -> PoseMatrixReturn a row-major world-from-object homogeneous transform.
Parameters
i : int Zero-based view index.
Returns
tuple of tuple of float Row-major 4 x 4 homogeneous world-from-object transform.
RotationAxisGeometry
class RotationAxisGeometry(
grid: Grid,
detector: Detector,
angles: Sequence[float],
axis_unit_lab: Sequence[float],
)Parallel-ray geometry with an arbitrary lab-frame rotation axis direction.
The detector and beam model are unchanged from the standard parallel-ray model:
rays remain fixed in the world frame along +y and detector coordinates live in
the world x/z detector plane. Only the per-view object pose changes: view
i rotates the object about the axis by angles[i], in degrees.
Parameters
grid : Grid Reconstruction voxel grid. detector : Detector Detector dimensions, pitches and physical centre. angles : sequence of float View rotation angles in degrees, in acquisition order. axis_unit_lab : sequence of float Nonzero finite lab-frame rotation-axis vector, normalized on construction.
Raises
ValueError If the rotation-axis vector is not finite, nonzero and three-dimensional.
RotationAxisGeometry.pose_for_view
pose_for_view(i: int) -> PoseMatrixReturn the world-from-object pose for one view.
Degree conversion uses host precision for lists and saved FP32 arrays alike.
Parameters
i : int Zero-based view index.
Returns
tuple of tuple of float Row-major 4 x 4 homogeneous world-from-object transform.
Raises
IndexError If the view index is outside the angle sequence.
RotationAxisGeometry.rays_for_view
rays_for_view(i: int) -> RayPairReturn detector rays for one view.
Parameters
i : int Zero-based view index.
Returns
tuple of callable Origin and unit-direction callbacks taking detector pixel indices (u, v).
ScanGeometry
class ScanGeometry()A geometry that names its reconstruction grid, detector and view angles.
Every built-in geometry is one; the plain Geometry contract needs
only poses.
ScanGeometry.grid
@property
grid: GridThe reconstruction grid.
Returns
Grid Reconstruction voxel grid.
ScanGeometry.detector
@property
detector: DetectorThe detector.
Returns
Detector Detector dimensions, pixel sizes and physical centre.
ScanGeometry.angles
@property
angles: Sequence[float]Each view's rotation angle, in degrees.
Returns
sequence of float One rotation angle per view, in degrees.
ScanGeometry.rays_for_view
rays_for_view(i: int) -> RayPairReturn world-frame ray callbacks for inspection, not projection.
Parameters
i : int Zero-based view index.
Returns
tuple of callable Origin and unit-direction callbacks taking detector pixel indices (u, v).
beam_of
beam_of(geometry: object) -> ConeBeam | NoneReturn a geometry's cone beam, or None for parallel-beam geometries.
Raises for ConeSegments, which has one beam per segment.
Parameters
geometry : object Geometry with an optional cone beam.
Returns
ConeBeam or None Beam metadata, or None for parallel-beam geometry.
Raises
ValueError If geometry has a separate beam per segment rather than one shared beam.
compute_roi
compute_roi(
grid: Grid,
detector: Detector,
*,
crop_y_to_u: bool = True,
match_parity: bool = False,
) -> RoiInfoCompute conservative FOV half-extents and grid dims from detector.
r_u = max(0, (nu/2-0.5)*du - |cx|)enforces angle-invariant coverage.r_vis half the overlap of the volume and measured detector-row intervals.- nx_roi is the largest dim whose half-extent fits within the in-plane radius r_u; nz_roi similarly fits r_v.
- ny_roi is also fit to r_u when
crop_y_to_u=True, which matches the parallel-beam x-y disk interpretation. Laminography callers can setcrop_y_to_u=Falseto keep the full source y extent. - All dimensions are clipped by the current grid.
Parameters
grid : Grid Input grid providing voxel pitches and maximum dimensions. detector : Detector Parallel-beam detector defining the physical field of view. crop_y_to_u : bool, optional Crop y to the detector-u bound as well as x; default is True. match_parity : bool, optional Preserve each input dimension's odd/even parity where possible.
Returns
RoiInfo Conservative physical half-extents and recommended voxel counts.
cylindrical_mask_xy
cylindrical_mask_xy(grid: Grid, detector: Detector) -> np.ndarrayBoolean mask (nx, ny) for cylindrical FOV in the X-Y plane.
Returns a 2D mask aligned to x and y axes where mask[x,y] is True if the voxel center lies within radius r_u in the X-Y plane. This is meant to be broadcast along z to mask a cylinder aligned with the z axis.
Parameters
grid : Grid Input grid providing voxel pitches and maximum dimensions. detector : Detector Parallel-beam detector defining the physical field of view.
Returns
numpy.ndarray Boolean (grid.nx, grid.ny) mask, broadcastable along z.
grid_from_detector_fov
grid_from_detector_fov(
grid: Grid,
detector: Detector,
*,
crop_y_to_u: bool = True,
) -> GridReturn a new Grid cropped to the detector FOV bounding box.
All three axes are cropped conservatively: x and y by the in-plane detector
radius r_u, and z by the overlapping detector-height interval. In-plane
slices stay axis-centred; the axial centre follows the measured window.
Parameters
grid : Grid Input grid providing voxel pitches and maximum dimensions. detector : Detector Parallel-beam detector defining the physical field of view. crop_y_to_u : bool, optional Crop y to the detector-u bound as well as x; default is True.
Returns
Grid Cropped grid with unchanged pitches; resized grids are axis-centred in-plane and follow the measured detector rows axially.
grid_from_detector_fov_cube
grid_from_detector_fov_cube(
grid: Grid,
detector: Detector,
*,
crop_y_to_u: bool = True,
) -> GridReturn a new cubic Grid cropped to the detector FOV (nx=ny=nz).
The shared side is limited by x/y in-plane coverage (r_u) and z coverage
(r_v). When multiple fitted dimensions with different parities compete, the
final side is adjusted downward by at most one voxel so the cubic output keeps
a consistent, parity-preserving centered-origin convention where possible.
Parameters
grid : Grid Input grid providing voxel pitches and maximum dimensions. detector : Detector Parallel-beam detector defining the physical field of view. crop_y_to_u : bool, optional Crop y to the detector-u bound as well as x; default is True.
Returns
Grid Cropped grid with unchanged pitches, centred at the origin when resized.
grid_from_detector_fov_slices
grid_from_detector_fov_slices(
grid: Grid,
detector: Detector,
*,
crop_y_to_u: bool = True,
) -> GridReturn an ROI Grid with square x-y slices and z from detector height.
- (nx, ny) chosen as the largest equal dims that fit within r_u using (vx, vy).
- nz chosen from r_v using vz, clipped by current nz.
This matches a common 3D parallel-beam reconstruction: per-z 2D CT slices.
Parameters
grid : Grid Input grid providing voxel pitches and maximum dimensions. detector : Detector Parallel-beam detector defining the physical field of view. crop_y_to_u : bool, optional Crop y to the detector-u bound as well as x; default is True.
Returns
Grid Cropped grid with unchanged pitches, centred at the origin when resized.
grid_volume_origin
grid_volume_origin(grid: Grid) -> Vec3Return the physical centre of voxel (0, 0, 0) for a grid.
Parameters
grid : Grid Voxel grid with optional origin or centre.
Returns
tuple of float Physical (x, y, z) centre of voxel (0, 0, 0).
stack_view_poses
stack_view_poses(
geometry: Geometry,
n_views: int,
*,
dtype: DTypeLike = np.float32,
) -> jnp.ndarrayStack world-from-object poses for the first n_views views.
A geometry class may define stack_poses(n_views, dtype) to build the
stack in one vectorised step (looked up on the class, so wrappers that
forward attributes to a base geometry do not inherit it).
Parameters
geometry : Geometry Geometry implementing world-from-object poses. n_views : int Number of leading views to stack. dtype : dtype, optional Output dtype; defaults to float32.
Returns
jax.Array Pose stack with shape (n_views, 4, 4).