Python API Reference

Module: parallelproj_core

Python bindings for parallelproj backend.

This module provides efficient C++/CUDA implementations of 3D Joseph forward and backward projectors with optional Time-of-Flight (TOF) support.

parallelproj_core.__version__

The version of the parallelproj backend library.

Type:

str

parallelproj_core.version_major

Major version number of the linked parallelproj library.

Type:

int

parallelproj_core.version_minor

Minor version number of the linked parallelproj library.

Type:

int

parallelproj_core.version_patch

Patch version number of the linked parallelproj library.

Type:

int

parallelproj_core.cuda_enabled

Flag indicating if the library was compiled with CUDA support. Returns 1 if CUDA is enabled, 0 otherwise.

Type:

int

Functions

Non-TOF Projections

parallelproj_core.joseph3d_fwd(lor_start: ndarray[dtype=float32, order='C', writable=False], lor_end: ndarray[dtype=float32, order='C', writable=False], image: ndarray[dtype=float32, shape=(*, *, *), order='C', writable=False], image_origin: ndarray[dtype=float32, shape=(3), order='C', writable=False], voxel_size: ndarray[dtype=float32, shape=(3), order='C', writable=False], projection_values: ndarray[dtype=float32, order='C'], device_id: int = 0, threads_per_block: int = 64) → None

Forward projection using the Joseph 3D algorithm.

Parameters:

  • lor_start (ndarray) – Array of shape (…, 3) with coordinates of LOR start points.

  • lor_end (ndarray) – Array of shape (…, 3) with coordinates of LOR end points.

  • image (ndarray) – 3D image array of shape (n0, n1, n2) for forward projection.

  • image_origin (ndarray) – Array of shape (3,) with coordinates of [0,0,0] voxel center.

  • voxel_size (ndarray) – Array of shape (3,) with voxel sizes.

  • projection_values (ndarray) – Output array for projection results, shape must match lor_start.shape[:-1].

  • device_id (int, optional) – Device ID for computation (default: 0).

  • threads_per_block (int, optional) – Number of threads per block for GPU (default: 64).

Notes

All arrays must be on the same device (CPU or GPU) with matching device IDs.

parallelproj_core.joseph3d_back(lor_start: ndarray[dtype=float32, order='C', writable=False], lor_end: ndarray[dtype=float32, order='C', writable=False], image: ndarray[dtype=float32, shape=(*, *, *), order='C'], image_origin: ndarray[dtype=float32, shape=(3), order='C', writable=False], voxel_size: ndarray[dtype=float32, shape=(3), order='C', writable=False], projection_values: ndarray[dtype=float32, order='C', writable=False], device_id: int = 0, threads_per_block: int = 64) → None

Backprojection using the Joseph 3D algorithm.

Parameters:

  • lor_start (ndarray) – Array of shape (…, 3) with coordinates of LOR start points.

  • lor_end (ndarray) – Array of shape (…, 3) with coordinates of LOR end points.

  • image (ndarray) – 3D image array of shape (n0, n1, n2) to accumulate backprojection into.

  • image_origin (ndarray) – Array of shape (3,) with coordinates of [0,0,0] voxel center.

  • voxel_size (ndarray) – Array of shape (3,) with voxel sizes.

  • projection_values (ndarray) – Input values to backproject, shape must match lor_start.shape[:-1].

  • device_id (int, optional) – Device ID for computation (default: 0).

  • threads_per_block (int, optional) – Number of threads per block for GPU (default: 64).

Notes

Values are accumulated into the existing image array (not overwritten). All arrays must be on the same device (CPU or GPU) with matching device IDs.

TOF Sinogram Projections

parallelproj_core.joseph3d_tof_sino_fwd(lor_start: ndarray[dtype=float32, order='C', writable=False], lor_end: ndarray[dtype=float32, order='C', writable=False], image: ndarray[dtype=float32, shape=(*, *, *), order='C', writable=False], image_origin: ndarray[dtype=float32, shape=(3), order='C', writable=False], voxel_size: ndarray[dtype=float32, shape=(3), order='C', writable=False], projection_values: ndarray[dtype=float32, order='C'], tof_bin_width: float, tof_sigma: ndarray[dtype=float32, order='C', writable=False], tof_center_offset: ndarray[dtype=float32, order='C', writable=False], num_tof_bins: int, num_sigmas: float = 3.0, device_id: int = 0, threads_per_block: int = 64) → None

TOF sinogram forward projection using the Joseph 3D algorithm.

Parameters:

  • lor_start (ndarray) – Array of shape (…, 3) with coordinates of LOR start points.

  • lor_end (ndarray) – Array of shape (…, 3) with coordinates of LOR end points.

  • image (ndarray) – 3D image array of shape (n0, n1, n2) for forward projection.

  • image_origin (ndarray) – Array of shape (3,) with coordinates of [0,0,0] voxel center.

  • voxel_size (ndarray) – Array of shape (3,) with voxel sizes.

  • projection_values (ndarray) – Output array for TOF sinogram, shape (…, num_tof_bins).

  • tof_bin_width (float) – Width of TOF bins in spatial units.

  • tof_sigma (ndarray) – TOF resolution (sigma) in spatial units. Shape (1,) or (…,) for LOR-dependent.

  • tof_center_offset (ndarray) – Offset of central TOF bin from LOR midpoint. Shape (1,) or (…,).

  • num_tof_bins (int) – Number of TOF bins.

  • num_sigmas (float, optional) – Number of sigmas for TOF kernel calculation (default: 3.0).

  • device_id (int, optional) – Device ID for computation (default: 0).

  • threads_per_block (int, optional) – Number of threads per block for GPU (default: 64).

parallelproj_core.joseph3d_tof_sino_back(lor_start: ndarray[dtype=float32, order='C', writable=False], lor_end: ndarray[dtype=float32, order='C', writable=False], image: ndarray[dtype=float32, shape=(*, *, *), order='C'], image_origin: ndarray[dtype=float32, shape=(3), order='C', writable=False], voxel_size: ndarray[dtype=float32, shape=(3), order='C', writable=False], projection_values: ndarray[dtype=float32, order='C', writable=False], tof_bin_width: float, tof_sigma: ndarray[dtype=float32, order='C', writable=False], tof_center_offset: ndarray[dtype=float32, order='C', writable=False], num_tof_bins: int, num_sigmas: float = 3.0, device_id: int = 0, threads_per_block: int = 64) → None

TOF sinogram backprojection using the Joseph 3D algorithm.

Parameters:

  • lor_start (ndarray) – Array of shape (…, 3) with coordinates of LOR start points.

  • lor_end (ndarray) – Array of shape (…, 3) with coordinates of LOR end points.

  • image (ndarray) – 3D image array of shape (n0, n1, n2) to accumulate backprojection into.

  • image_origin (ndarray) – Array of shape (3,) with coordinates of [0,0,0] voxel center.

  • voxel_size (ndarray) – Array of shape (3,) with voxel sizes.

  • projection_values (ndarray) – Input TOF sinogram to backproject, shape (…, num_tof_bins).

  • tof_bin_width (float) – Width of TOF bins in spatial units.

  • tof_sigma (ndarray) – TOF resolution (sigma) in spatial units. Shape (1,) or (…,) for LOR-dependent.

  • tof_center_offset (ndarray) – Offset of central TOF bin from LOR midpoint. Shape (1,) or (…,).

  • num_tof_bins (int) – Number of TOF bins.

  • num_sigmas (float, optional) – Number of sigmas for TOF kernel calculation (default: 3.0).

  • device_id (int, optional) – Device ID for computation (default: 0).

  • threads_per_block (int, optional) – Number of threads per block for GPU (default: 64).

Notes

Values are accumulated into the existing image array (not overwritten).

TOF Listmode Projections

parallelproj_core.joseph3d_tof_lm_fwd(event_start: ndarray[dtype=float32, order='C', writable=False], event_end: ndarray[dtype=float32, order='C', writable=False], image: ndarray[dtype=float32, shape=(*, *, *), order='C', writable=False], image_origin: ndarray[dtype=float32, shape=(3), order='C', writable=False], voxel_size: ndarray[dtype=float32, shape=(3), order='C', writable=False], projection_values: ndarray[dtype=float32, order='C'], tof_bin_width: float, tof_sigma: ndarray[dtype=float32, order='C', writable=False], tof_center_offset: ndarray[dtype=float32, order='C', writable=False], tof_bin_index: ndarray[dtype=int16, order='C', writable=False], num_tof_bins: int, num_sigmas: float = 3.0, device_id: int = 0, threads_per_block: int = 64) → None

TOF listmode forward projection using the Joseph 3D algorithm.

Parameters:

  • event_start (ndarray) – Array of shape (…, 3) with coordinates of event LOR start points.

  • event_end (ndarray) – Array of shape (…, 3) with coordinates of event LOR end points.

  • image (ndarray) – 3D image array of shape (n0, n1, n2) for forward projection.

  • image_origin (ndarray) – Array of shape (3,) with coordinates of [0,0,0] voxel center.

  • voxel_size (ndarray) – Array of shape (3,) with voxel sizes.

  • projection_values (ndarray) – Output array for event projections, shape matches event_start.shape[:-1].

  • tof_bin_width (float) – Width of TOF bins in spatial units.

  • tof_sigma (ndarray) – TOF resolution (sigma) in spatial units. Shape (1,) or (…,) for event-dependent.

  • tof_center_offset (ndarray) – Offset of central TOF bin from LOR midpoint. Shape (1,) or (…,).

  • tof_bin_index (ndarray) – TOF bin indices for each event, shape matches event_start.shape[:-1].

  • num_tof_bins (int) – Number of TOF bins.

  • num_sigmas (float, optional) – Number of sigmas for TOF kernel calculation (default: 3.0).

  • device_id (int, optional) – Device ID for computation (default: 0).

  • threads_per_block (int, optional) – Number of threads per block for GPU (default: 64).

parallelproj_core.joseph3d_tof_lm_back(event_start: ndarray[dtype=float32, order='C', writable=False], event_end: ndarray[dtype=float32, order='C', writable=False], image: ndarray[dtype=float32, shape=(*, *, *), order='C'], image_origin: ndarray[dtype=float32, shape=(3), order='C', writable=False], voxel_size: ndarray[dtype=float32, shape=(3), order='C', writable=False], projection_values: ndarray[dtype=float32, order='C', writable=False], tof_bin_width: float, tof_sigma: ndarray[dtype=float32, order='C', writable=False], tof_center_offset: ndarray[dtype=float32, order='C', writable=False], tof_bin_index: ndarray[dtype=int16, order='C', writable=False], num_tof_bins: int, num_sigmas: float = 3.0, device_id: int = 0, threads_per_block: int = 64) → None

TOF listmode backprojection using the Joseph 3D algorithm.

Parameters:

  • event_start (ndarray) – Array of shape (num_events, 3) with coordinates of event LOR start points.

  • event_end (ndarray) – Array of shape (num_events, 3) with coordinates of event LOR end points.

  • image (ndarray) – 3D image array of shape (n0, n1, n2) to accumulate backprojection into.

  • image_origin (ndarray) – Array of shape (3,) with coordinates of [0,0,0] voxel center.

  • voxel_size (ndarray) – Array of shape (3,) with voxel sizes.

  • projection_values (ndarray) – Input array to be backprojected, shape (num_events,).

  • tof_bin_width (float) – Width of TOF bins in spatial units.

  • tof_sigma (ndarray) – TOF resolution (sigma) in spatial units. Shape (1,) or (num_events,) for event-dependent.

  • tof_center_offset (ndarray) – Offset of central TOF bin from LOR midpoint. Shape (1,) or (num_events,).

  • tof_bin_index (ndarray) – TOF bin indices for each event, shape (num_events,).

  • num_tof_bins (int) – Number of TOF bins.

  • num_sigmas (float, optional) – Number of sigmas for TOF kernel calculation (default: 3.0).

  • device_id (int, optional) – Device ID for computation (default: 0).

  • threads_per_block (int, optional) – Number of threads per block for GPU (default: 64).

Notes

Values are accumulated into the existing image array (not overwritten).