BSplineDeformPerturbation

Note

This page is a reference documentation. It only explains the class signature, and not how to use it. Please refer to the Habitat Guide and Python API guide (v2.0) for usage.

class BSplineDeformPerturbation(sigma_range: Sequence[float] = (1.5, 3.0), magnitude_range: Sequence[float] = (8.0, 12.0), image_mode: str | int = 'bilinear', mask_mode: str | int = 'nearest', padding_mode: str = 'reflection', device: str = 'cpu', target_dice: float | None = None, dice_tolerance: float = 0.02, control_spacing: float | None = None, mask_only: bool = False)[source]

Bases: object

MONAI elastic / B-spline free-form warp of every image and ROI.

This is not the Prior 2024 / MIRP 1.2.0 simulated-retest chain (noise → translation → rotation). Default behaviour changes ROI shape by applying one random 3-D displacement field to every modality and mask so the contour and the anatomy stay paired. mask_only=True keeps every intensity volume unchanged and warps only the ROI: same scan, different contour.

Implementation (MONAI Rand3DElasticd, optional extra monai):

  • A random offset grid is sampled, Gaussian-smoothed with a sigma drawn from sigma_range, and scaled by a magnitude drawn from magnitude_range (voxel units). Optional extra affine terms are left off so this component is a pure elastic warp.

  • Intensities are resampled with image_mode (default "bilinear", MONAI’s torch grid-sample path). Labels use mask_mode (default "nearest") so the ROI stays a discrete label. Integer 0–5 selects scipy spline order instead (order 3 is cubic B-spline resampling; it is much slower on full clinical volumes).

  • The output stays on the original grid (same shape and geometry).

Default path is MONAI’s documented 3-D elastic deformation (full- resolution random offsets + Gaussian), not Rueckert cubic-B-spline FFD. Pass control_spacing to switch to an explicit coarse control lattice with cubic interpolation — that is the smooth teaching warp (slow bulge, not 1-voxel teeth). Neither path is MIRP perturbation_roi_adapt_size (morphological grow/shrink).

Parameters:

  • sigma_range – Gaussian smoothing (low, high) of the offset grid, in voxels. Wider sigma gives a smoother warp. Ignored when control_spacing is set.

  • magnitude_range – Displacement magnitude (low, high) in voxels. Larger values wrinkle the ROI more.

  • image_mode – Intensity interpolator ("bilinear" / "nearest" or spline order 0–5).

  • mask_mode – ROI interpolator ("nearest" recommended for the MONAI path; "bilinear" then rint is a smoother iso-contour on the FFD path).

  • padding_mode – Out-of-grid padding (reflection, border, or zeros).

  • device – Torch device ("cpu" / "cuda"). Default "cpu" is the portable path; pass "cuda" when a GPU is available and the volume fits in memory. Unused on the FFD path.

  • target_dice – When set, scale one frozen offset field so the Dice between the original and warped ROI is within dice_tolerance of this value. None keeps the random magnitude from magnitude_range.

  • dice_tolerance – Allowed absolute error on target_dice.

  • control_spacing – When set, voxels between neighbouring FFD control points (must be > 1). None keeps the MONAI Rand3DElasticd path.

  • mask_only – When True, warp every ROI and leave images untouched (inter-observer contour wobble on a fixed scan). When False, image and mask share one field.

__init__(sigma_range: Sequence[float] = (1.5, 3.0), magnitude_range: Sequence[float] = (8.0, 12.0), image_mode: str | int = 'bilinear', mask_mode: str | int = 'nearest', padding_mode: str = 'reflection', device: str = 'cpu', target_dice: float | None = None, dice_tolerance: float = 0.02, control_spacing: float | None = None, mask_only: bool = False) → None[source]
property spec: Spec

Return the algorithm specification used for provenance.

__call__(subject: Subject, *, rng: Generator) → Subject[source]

Return a copy of subject warped by one MONAI elastic field.

Parameters:

  • subject – Subject providing images and/or masks on one grid.

  • rng – Random generator; one integer seed is drawn so every volume of this subject shares the same displacement.

Returns:

The warped subject copy (same keys, same geometry).

Raises:

  • OptionalDependencyError – When the monai extra is missing.

  • HABITAPIError – When the subject has no volumes, or images and masks do not share one 3-D shape. target_dice also requires at least one mask.

Examples using habit.precision.BSplineDeformPerturbation

Precise voxel features

Precise voxel features