nema_quant.utils

Utility functions for image processing and data manipulation.

nema_quant.utils.find_phantom_center(image_data_3d: numpy.typing.NDArray.typing.Any, threshold: float = 0.003) → Tuple[float, float, float][source]

Find the center of mass of the NEMA phantom in a 3D PET image.

Automatically locates the phantom’s center using morphological operations and connected component analysis. Robust to noise and artifacts.

Parameters:

  • image_data_3d (numpy.ndarray) – 3D PET image array with shape (z, y, x).

  • threshold (float, optional) – Threshold value for binary segmentation (as fraction of max intensity). Default is 0.003.

Returns:

Center-of-mass coordinates as (z, y, x) in voxels.

Return type:

tuple[float, float, float]

Raises:

  • ValueError – If input is not 3D array.

  • RuntimeError – If no objects found above threshold.

Examples

Find phantom center in a loaded image:

>>> import numpy as np
>>> image = np.random.rand(88, 256, 256)
>>> center = find_phantom_center(image, threshold=0.01)
>>> print(f"Center at: {center}")

Notes

Uses scipy.ndimage.center_of_mass to compute the centroid of the largest connected component in the binary mask above the threshold.

nema_quant.utils.find_phantom_center_cv2_threshold(image_data_3d: numpy.typing.NDArray.typing.Any, threshold_fraction: float = 0.41, method: str = 'weighted_slices') → Tuple[float, float, float][source]

Find phantom center using a fixed max-fraction threshold and cv2 moments.

Parameters:

  • image_data_3d (numpy.ndarray) – 3D PET image array with shape (z, y, x).

  • threshold_fraction (float, optional) – Fraction of the max intensity used for binarization (0-1). Default is 0.41.

  • method (str, optional) – Strategy for determinism. Options: - “weighted_slices”: area-weighted average of per-slice centroids. - “max_slice”: centroid of the slice with the largest mask area.

Returns:

Center coordinates as (z, y, x) in voxels.

Return type:

tuple[float, float, float]

nema_quant.utils.voxel_to_mm(voxel_indices_zyx: Tuple[int, int, int], image_dims_xyz: Tuple[int, int, int], voxel_spacing_xyz: Tuple[float, float, float]) → Tuple[float, float, float][source]

Converts voxel indices (order z, y, x) to physical coordinates (mm, relative to the center).

This function is considered the “ground truth” for conversion. It assumes that the voxel coordinate represents the center of that voxel.

Parameters:

  • voxel_indices_zyx (tuple of int) – The voxel indices in (z, y, x) order.

  • image_dims_xyz (tuple of int) – The total image dimensions in voxels (dim_x, dim_y, dim_z).

  • voxel_spacing_xyz (tuple of float) – The voxel size in millimeters (spacing_x, spacing_y, spacing_z).

Returns:

The physical coordinates (x, y, z) in millimeters from the center.

Return type:

tuple of float

nema_quant.utils.mm_to_voxel(mm_coords: Tuple[float, float, float], image_dims_xyz: Tuple[int, int, int], voxel_spacing_xyz: Tuple[float, float, float]) → Tuple[int, int, int][source]

Converts physical coordinates (in mm, relative to the center) to the indices of the nearest voxel.

This is the inverse function of voxel_to_mm.

Parameters:

  • mm_coords (tuple of float) – The coordinates (x, y, z) in millimeters from the center.

  • image_dims_xyz (tuple of int) – The total image dimensions in voxels (dim_x, dim_y, dim_z).

  • voxel_spacing_xyz (tuple of float) – The voxel size in millimeters (spacing_x, spacing_y, spacing_z).

Returns:

The corresponding voxel indices in (z, y, x) order.

Return type:

tuple of int

Notes

Author: EdAlita Date: 2025-07-08 09:13:50

nema_quant.utils.extract_canny_mask(image: numpy.typing.NDArray.typing.Any, voxel_size: float = 2.0644, fantoma_z_center: int = 157, phantom_center_yx: Tuple[int, int] | None = None) → numpy.typing.NDArray.typing.Any[source]

Extracts the lung insert mask using Canny edge detection, with anatomically consistent positioning.

Parameters:

  • image (np.ndarray) – 3D image array.

  • voxel_size (float) – Voxel size in millimeters. Default is 2.0644.

  • fantoma_z_center (int) – Z-coordinate of the phantom center. Default is 157.

  • phantom_center_yx (Tuple[int, int], optional) – Y, X coordinates of the phantom center for reference.

Returns:

Binary mask array corresponding to the lung insert region.

Return type:

np.ndarray

nema_quant.utils.calculate_weighted_cbr_fom(results)[source]

Extracts the lung insert mask using Canny edge detection, with anatomically consistent positioning.

Parameters:

  • image (np.ndarray) – 3D image array.

  • voxel_size (float) – Voxel size in millimeters. Default is 2.0644.

  • fantoma_z_center (int) – Z-coordinate of the phantom center. Default is 157.

  • phantom_center_yx (Tuple[int, int], optional) – Y, X coordinates of the phantom center for reference.

Returns:

Binary mask array corresponding to the lung insert region.

Return type:

np.ndarray