nema_quant.analysis

Core analysis functions for image quality quantification.

Author: Edwing Ulin-Briseno Date: 2025-07-16

nema_quant.analysis.extract_circular_mask_2d(slice_dims: Tuple[int, int], roi_center_vox: Tuple[float, float], roi_radius_vox: float) → numpy.typing.NDArray.numpy.bool_[source]

Create a 2D circular region-of-interest (ROI) mask.

Generates a 2D boolean mask for a circular ROI using efficient NumPy vectorization instead of loops. Computes the Euclidean distance from each pixel to the circle’s center and marks pixels within the radius as True.

Parameters:

  • slice_dims (tuple[int, int]) – (height, width) dimensions of the 2D slice.

  • roi_center_vox (tuple[float, float]) – (y, x) coordinates of the circle’s center in voxels.

  • roi_radius_vox (float) – Radius of the circular ROI in voxels.

Returns:

2D boolean mask with shape matching slice_dims. True marks pixels inside the circular ROI, False outside.

Return type:

numpy.ndarray

Examples

Create a mask for a 100x100 pixel slice with a circle of radius 20 at center (50, 50):

>>> mask = extract_circular_mask_2d((100, 100), (50.0, 50.0), 20.0)
>>> mask.shape
(100, 100)
>>> mask.sum()  # Number of pixels inside circle
1257

Notes

Uses NumPy’s ogrid for efficient coordinate generation and vectorized distance computation for optimal performance on large images.

nema_quant.analysis.create_cylindrical_mask(shape_zyx: Tuple[int, int, int], center_zyx: Tuple[float, float, float], radius_mm: float, height_mm: float, spacing_xyz: numpy.typing.NDArray.numpy.float64) → numpy.typing.NDArray.numpy.bool_[source]

Create a boolean mask for a cylinder aligned with the z-axis.

nema_quant.analysis.calculate_weighted_cbr_from(results)[source]

Calculates weighted Contrast-to-Background Ratio (CBR) and Figure of Merit (FOM) from sphere results.

Orchestrates weighted metric calculation by processing individual sphere measurements and computing diameter-weighted averages as defined in the NEMA NU 2-2018 standard for overall image quality assessment.

Parameters:

results (list of dict) – List of calculated metrics for each sphere containing diameter_mm, percentaje_constrast_QH, and background_variability_N keys.

Returns:

Dictionary containing weighted_CBR, weighted_FOM, individual CBRs, FOMs, weights, and diameters. Returns None values for weighted metrics if results list is empty.

Return type:

dict

Notes

Author: EdAlita Date: 2025-01-08 16:15:00

The weighting scheme uses inverse diameter weighting (1/d) normalized to sum to 1.0. CBR is calculated as contrast/variability, FOM as contrast²/variability.

nema_quant.analysis.calculate_nema_metrics(image_data: numpy.typing.NDArray.typing.Any, phantom: NemaPhantom, cfg: yacs.config.CfgNode, save_visualizations: bool = False, visualizations_dir: str = 'visualizations', protocol: str | None = 'NU_2_2018') → Tuple[List[Dict[str, Any]], Dict[int, float]][source]

Calculate NEMA NU 2-2018 image quality metrics.

Orchestrates the complete NEMA image quality analysis pipeline:

  1. Identifies background regions at multiple slice positions

  2. Extracts hot sphere region counts

  3. Computes Percent Contrast (Q_H) and Background Variability (N)

  4. Analyzes lung insert counts for spillover ratio assessment

This is the primary function for quantifying image quality according to the NEMA NU 2-2018 standard.

Parameters:

  • image_data (numpy.ndarray) – 3D PET image array with shape (z, y, x) in voxel units.

  • phantom (NemaPhantom) – Initialized phantom model with ROI definitions and coordinate transforms.

  • cfg (yacs.config.CfgNode) –

    Configuration object containing:

    • ACTIVITY.RATIO: Hot/background activity ratio (a_H / a_B)

    • ROIS.CENTRAL_SLICE: Central slice index in z-axis

    • ROIS.BACKGROUND_OFFSET_YX: Background region offsets

    • ROIS.ORIENTATION_YX: Orientation multipliers for background regions

    • ROIS.SPACING: Voxel spacing in mm

  • save_visualizations (bool, optional) – If True, saves ROI mask visualizations to disk. Default is False.

  • visualizations_dir (str, optional) – Directory path for saving visualization images. Default is “visualizations”.

Returns:

  • results (list[dict]) – List of metric dictionaries for each hot sphere:

    • diameter_mm: Sphere diameter in mm

    • percentaje_constrast_QH: Percent contrast (%)

    • background_variability_N: Background variability (%)

    • avg_hot_counts_CH: Average hot sphere counts

    • avg_bkg_counts_CB: Average background counts

    • bkg_std_dev_SD: Background standard deviation

  • results_lung (dict[int, float]) – Lung insert spillover ratios indexed by slice number.

Raises:

ValueError – If activity ratio is not greater than 1.

Notes

The function analyzes multiple slice positions (±10mm and ±20mm from central slice) to account for axial variation in the phantom and image statistics.

References

  • NEMA NU 2-2018: Performance Measurements of Positron Emission Tomographs

Examples

Calculate NEMA metrics for a loaded image:

>>> from nema_quant.phantom import NemaPhantom
>>> from nema_quant.config import CfgNode
>>> phantom = NemaPhantom(image_path='pet_image.nii.gz')
>>> cfg = get_default_config()
>>> metrics, lung_results = calculate_nema_metrics(
...     image_data, phantom, cfg, save_visualizations=True
... )
>>> for m in metrics:
...     print(f"Sphere {m['diameter_mm']}mm: Q_H={m['percentaje_constrast_QH']:.1f}%")
nema_quant.analysis.calculate_nema_metrics_nu4_2008(image_data: numpy.typing.NDArray.typing.Any, phantom: NemaPhantom, cfg: yacs.config.CfgNode, save_visualizations: bool = False, visualizations_dir: str = 'visualizations') → Tuple[List[Dict[str, Any]], Dict[int, float], Dict[str, float]][source]

Calculate NEMA NU 4-2008 image quality metrics.

This function is a placeholder for the implementation of NEMA NU 4-2008 metrics calculation. The actual logic for processing the image data according to the NU 4-2008 standard needs to be implemented.

Parameters:

  • image_data (numpy.ndarray) – 3D PET image array with shape (z, y, x) in voxel units.

  • phantom (NemaPhantom) – Initialized phantom model with ROI definitions and coordinate transforms.

  • cfg (yacs.config.CfgNode) – Configuration object containing necessary parameters for NU 4-2008 analysis.

  • save_visualizations (bool, optional) – If True, saves ROI mask visualizations to disk. Default is False.

  • visualizations_dir (str, optional) – Directory path for saving visualization images. Default is “visualizations”.

Return type:

Tuple[List[Dict[str, Any]], Dict[int, float], Dict[str, float]]

nema_quant.analysis.save_sphere_visualization(image_slice: numpy.typing.NDArray.typing.Any, sphere_name: str, center_yx: Tuple[float, float], radius_vox: float, roi_mask: numpy.typing.NDArray.typing.Any, output_dir: Path, slice_idx: int) → None[source]

Saves a visualization of the sphere ROI and mask for debugging purposes.

Generates and stores an image showing the analyzed sphere, its center and radius, and the ROI mask overlay. Useful for verifying ROI placement and mask accuracy.

Parameters:

  • image_slice (np.ndarray) – 2D image slice containing the sphere.

  • sphere_name (str) – Name of the sphere being analyzed.

  • center_yx (Tuple[float, float]) – Center coordinates (y, x) of the sphere.

  • radius_vox (float) – Radius of the sphere in voxels.

  • roi_mask (np.ndarray) – Boolean mask indicating the ROI.

  • output_dir (Path) – Directory to save the visualization.

  • slice_idx (int) – Index of the slice being analyzed.

Return type:

None

nema_quant.analysis.save_background_visualization(image_slice: numpy.typing.NDArray.typing.Any, centers_offset: List[Tuple[int, int]], pivot_point_yx: Tuple[float, float], radius_vox: float, output_dir: Path, slice_idx: int) → None[source]

Saves a visualization of the background ROIs for debugging purposes.

Generates and stores an image displaying background ROI locations, offsets, reference pivot point, and radii. Useful for verifying placement and mask accuracy.

Parameters:

  • image_slice (np.ndarray) – 2D image slice.

  • centers_offset (List[Tuple[int, int]]) – List of offset positions for background ROIs.

  • pivot_point_yx (Tuple[float, float]) – Pivot point (y, x) of the reference sphere.

  • radius_vox (float) – Radius for background ROIs in voxels.

  • output_dir (Path) – Directory to save the visualization.

  • slice_idx (int) – Index of the slice being analyzed.

Return type:

None

nema_quant.analysis.calculate_advanced_metrics(image_data: numpy.typing.NDArray.typing.Any, gt_data: numpy.typing.NDArray.typing.Any, measures: Tuple[str, ...], cfg: yacs.config.CfgNode) → Dict[str, Any][source]

Compute advanced image-quality metrics against a reference mask.

Parameters:

  • image_data (npt.NDArray[Any]) – 3D reconstructed image volume.

  • gt_data (npt.NDArray[Any]) – Ground-truth or reference mask aligned with image_data.

  • measures (Tuple[str, ...]) – Metric names to compute (passed to get_values()).

  • cfg (yacs.config.CfgNode) – Configuration containing ROIS.SPACING (voxel size in mm).

Returns:

Mapping of metric names to computed values.

Return type:

Dict[str, Any]

Notes

Logs each computed metric at INFO level.