autods_pet.roi#

ROI extraction and refinement classes.

class autods_pet.roi.AortaMBP(vertebra_labels=None, slab_axis=2, heart_exclusion_mode='dilate_intersection', heart_dilation_mm=6.0, heart_distance_mm=12.0, aorta_erosion_mm=4.0, stats=None)[source]#

Bases: object

Aorta metabolic blood pool (MBP) extraction and refinement.

Parameters:

  • vertebra_labels (list[int] | None (default: None)) – Labels for the vertebral slab. Defaults to T4-T8.

  • slab_axis (int (default: 2)) – SimpleITK index axis for slice gating (0=x, 1=y, 2=z).

  • heart_exclusion_mode (str (default: 'dilate_intersection')) – "dilate_intersection" or "distance".

  • heart_dilation_mm (float (default: 6.0)) – Dilation radius for heart buffer (mode "dilate_intersection").

  • heart_distance_mm (float (default: 12.0)) – Distance threshold (mode "distance").

  • aorta_erosion_mm (float (default: 4.0)) – Intraluminal erosion radius in mm.

  • stats (list[str] | None (default: None)) – Statistics to compute. Defaults to ["median"].

refine(whole_seg)[source]#

Refine TotalSegmentator aorta into a thoracic intraluminal MBP mask.

Pipeline: extract aorta label -> slice-gate by T4-T8 vertebral slab -> exclude heart buffer -> erode intraluminally -> keep largest component.

Parameters:

whole_seg (Image) – TotalSegmentator multilabel segmentation (must include aorta, heart, and vertebra labels).

Returns:

Result with refined_mask and shrinkage populated.

Return type:

ROIResult

extract(whole_seg, pet)[source]#

Refine mask and compute PET statistics in one call.

Parameters:

  • whole_seg (Image) – TotalSegmentator multilabel segmentation.

  • pet (Image) – PET SUV image (must share geometry with whole_seg).

Returns:

Result with refined_mask, shrinkage, and stats populated.

Return type:

ROIResult

Raises:

ValueError – If whole_seg and pet have mismatched geometry.

class autods_pet.roi.BrainROI(brain_label=90, grey_matter_only=True, cortical_thickness_mm=5.0, stats=None)[source]#

Bases: object

Brain reference ROI extraction and refinement.

When grey_matter_only is True (default), the brain mask is refined to isolate cortical gray matter using a shell extraction: the mask is eroded by cortical_thickness_mm to obtain the white-matter core, then subtracted from the original to yield the cortical shell.

Parameters:

  • brain_label (int (default: 90)) – TotalSegmentator label for brain (default 90).

  • grey_matter_only (bool (default: True)) – If True, extract cortical gray matter shell. If False, use the full brain mask.

  • cortical_thickness_mm (float (default: 5.0)) – Erosion radius used for the shell extraction (only when grey_matter_only is True).

  • stats (list[str] | None (default: None)) – Statistics to compute (e.g. ["median"]). Defaults to ["median"].

refine(whole_seg)[source]#

Refine TotalSegmentator brain label.

If grey_matter_only is True, produces a cortical shell mask (original minus eroded). Otherwise returns the cleaned brain mask.

Parameters:

whole_seg (Image) – TotalSegmentator multilabel segmentation.

Returns:

Result with refined_mask and shrinkage populated, or None if the brain label is absent from the segmentation.

Return type:

ROIResult | None

extract(whole_seg, pet)[source]#

Refine mask and compute PET statistics in one call.

Parameters:

  • whole_seg (Image) – TotalSegmentator multilabel segmentation.

  • pet (Image) – PET SUV image (must share geometry with whole_seg).

Returns:

Result with refined_mask, shrinkage, and stats populated, or None if the brain label is absent from the segmentation.

Return type:

ROIResult | None

Raises:

ValueError – If whole_seg and pet have mismatched geometry.

class autods_pet.roi.LiverROI(liver_label=5, erosion_mm=10.0, max_hole_volume_mm3=None, stats=None)[source]#

Bases: object

Liver reference ROI extraction and refinement.

Parameters:

  • liver_label (int (default: 5)) – TotalSegmentator label for liver (default 5).

  • erosion_mm (float (default: 10.0)) – Erosion radius in mm.

  • max_hole_volume_mm3 (float | None (default: None)) – If set, only fill holes smaller than this volume (mm³). Large holes (e.g. portal vein) are preserved.

  • stats (list[str] | None (default: None)) – Statistics to compute (e.g. ["median"]). Defaults to ["median"].

refine(whole_seg)[source]#

Refine TotalSegmentator liver label into a core-parenchyma mask.

Pipeline: extract label -> keep largest component -> fill holes -> erode to avoid partial-volume at boundaries.

Parameters:

whole_seg (Image) – TotalSegmentator multilabel segmentation.

Returns:

Result with refined_mask and shrinkage populated.

Return type:

ROIResult

extract(whole_seg, pet)[source]#

Refine mask and compute PET statistics in one call.

Parameters:

  • whole_seg (Image) – TotalSegmentator multilabel segmentation.

  • pet (Image) – PET SUV image (must share geometry with whole_seg).

Returns:

Result with refined_mask, shrinkage, and stats populated.

Return type:

ROIResult

Raises:

ValueError – If whole_seg and pet have mismatched geometry.

class autods_pet.roi.LongBonesROI(bones=None, diaphysis_keep_pct=60, stats=None)[source]#

Bases: object

Long bones diaphysis ROI extraction and refinement.

Parameters:

  • bones (list[tuple[str, int, float]] | None (default: None)) – (name, label, erosion_mm) tuples. Defaults to both femurs (5 mm) and both humeri (4 mm).

  • diaphysis_keep_pct (int (default: 60)) – Central percentage of each bone’s axial extent to keep.

  • stats (list[str] | None (default: None)) – Statistics to compute. Defaults to ["p95"].

refine(whole_seg)[source]#

Refine TotalSegmentator bone labels into diaphyseal marrow masks.

Pipeline per bone: extract label -> crop to central diaphysis -> erode cortex. The four masks are combined via logical union.

Parameters:

whole_seg (Image) – TotalSegmentator multilabel segmentation.

Returns:

Result with refined_mask and shrinkage populated. The shrinkage dict includes a per_bone sub-dict with per-bone volume details.

Return type:

ROIResult

extract(whole_seg, pet)[source]#

Refine mask and compute PET statistics in one call.

Parameters:

  • whole_seg (Image) – TotalSegmentator multilabel segmentation.

  • pet (Image) – PET SUV image (must share geometry with whole_seg).

Returns:

Result with refined_mask, shrinkage, and stats populated.

Return type:

ROIResult

Raises:

ValueError – If whole_seg and pet have mismatched geometry.

class autods_pet.roi.LumbarVB(lumbar_labels=None, erosion_mm=3.0, stats=None)[source]#

Bases: object

Lumbar vertebral body ROI extraction and refinement.

Parameters:

  • lumbar_labels (list[int] | None (default: None)) – TotalSegmentator labels for the target vertebrae. Defaults to L3, L4, L5.

  • erosion_mm (float (default: 3.0)) – Physical erosion radius in mm.

  • stats (list[str] | None (default: None)) – Statistics to compute (e.g. ["p95"]). Defaults to ["p95"].

refine(whole_seg, vert_body_seg)[source]#

Refine TotalSegmentator vertebra labels into a lumbar VB mask.

Pipeline: union of lumbar labels -> intersection with vertebral body binary mask -> physical erosion.

Parameters:

  • whole_seg (Image) – TotalSegmentator multilabel segmentation.

  • vert_body_seg (Image) – Binary vertebral body segmentation.

Returns:

Result with refined_mask and shrinkage populated.

Return type:

ROIResult

extract(whole_seg, vert_body_seg, pet)[source]#

Refine mask and compute PET statistics in one call.

Parameters:

  • whole_seg (Image) – TotalSegmentator multilabel segmentation.

  • vert_body_seg (Image) – Binary vertebral body segmentation.

  • pet (Image) – PET SUV image (must share geometry with whole_seg).

Returns:

Result with refined_mask, shrinkage, and stats populated.

Return type:

ROIResult

Raises:

ValueError – If whole_seg and pet have mismatched geometry.

class autods_pet.roi.TargetROI(stats=None)[source]#

Bases: object

Target ROI statistics from a user-provided binary mask.

Parameters:

stats (list[str] | None (default: None)) – Statistics to compute (e.g. ["max", "p90"]). Defaults to ["max"].

extract(mask, pet)[source]#

Extract statistics from PET within a user-provided binary mask.

Parameters:

  • mask (Image) – Binary mask selecting the target voxels.

  • pet (Image) – PET SUV image (must share geometry with mask).

Returns:

Result with stats and refined_mask populated.

Return type:

ROIResult

Raises:

ValueError – If mask and pet have mismatched geometry.