API Reference

class fastrad.MedicalImage(tensor, spacing=(1.0, 1.0, 1.0))

Bases: object

Representation of a continuous 3D medical volume (e.g., CT or MRI).

tensor

The 3D image array as a PyTorch FloatTensor.

Type:

torch.Tensor

spacing

The physical voxel dimensions (z, y, x).

Type:

Tuple[float, float, float]

__init__(tensor, spacing=(1.0, 1.0, 1.0))

to(device)

Moves the underlying tensor to the specified device.

Return type:

MedicalImage

classmethod from_dicom(path)

Creates a MedicalImage from a directory containing DICOM slices.

Parameters:

path (Union[str, Path]) – Path to the directory containing the DICOM files.

Return type:

MedicalImage

classmethod from_nifti(path)

Creates a MedicalImage from a NIfTI format image file (.nii or .nii.gz).

Parameters:

path (Union[str, Path]) – Path to the NIfTI file.

Return type:

MedicalImage

Returns:

A new instantiated MedicalImage object with extracted spacing.

class fastrad.Mask(tensor, spacing=(1.0, 1.0, 1.0))

Bases: object

Representation of a binary 3D Region of Interest (ROI) mask.

tensor

The 3D binary mask array as a PyTorch FloatTensor.

Type:

torch.Tensor

spacing

The physical voxel dimensions (z, y, x).

Type:

Tuple[float, float, float]

__init__(tensor, spacing=(1.0, 1.0, 1.0))

to(device)

Moves the underlying tensor to the specified device.

Return type:

Mask

classmethod from_dicom(path)

Creates a binary Mask from a directory containing DICOM slices. Voxels strictly greater than 0 are set to 1.

Parameters:

path (Union[str, Path]) – Path to the directory containing the DICOM ROIs.

Return type:

Mask

classmethod from_nifti(path)

Creates a binary Mask from a NIfTI format image file (.nii or .nii.gz). Voxels strictly greater than 0 are set to 1.

Parameters:

path (Union[str, Path]) – Path to the NIfTI file.

Return type:

Mask

Returns:

A new instantiated binary Mask object with extracted spacing.

class fastrad.FeatureSettings(feature_classes=<factory>, bin_width=25.0, device='auto', spacing=(1.0, 1.0, 1.0), force2D=False, force2Ddimension=0, compile=False, compile_mode='reduce-overhead', amp=False, differentiable=False)

Bases: object

Configuration parameters regulating standard feature extraction pipelines.

feature_classes

List of feature groups to extract (e.g., ["firstorder", "glcm"]).

bin_width

Radiometric discretization width applied before extracting textures.

device

Target execution device ("cpu", "cuda", "mps", or "auto").

spacing

Real world physical spacing array (z, y, x) propagated downstream.

force2D

Flag controlling slice-by-slice 2D calculation routing.

force2Ddimension

Target dimension slice axis when projecting 3D volumes to 2D.

feature_classes: List[str]

bin_width: float = 25.0

device: str = 'auto'

spacing: Tuple[float, float, float] = (1.0, 1.0, 1.0)

force2D: bool = False

force2Ddimension: int = 0

compile: bool = False

compile_mode: str = 'reduce-overhead'

amp: bool = False

differentiable: bool = False

__init__(feature_classes=<factory>, bin_width=25.0, device='auto', spacing=(1.0, 1.0, 1.0), force2D=False, force2Ddimension=0, compile=False, compile_mode='reduce-overhead', amp=False, differentiable=False)

class fastrad.FeatureExtractor(settings)

Bases: object

Main orchestration engine for radiomics feature extraction.

The FeatureExtractor consumes a FeatureSettings configuration and executes the specified feature class modules against a provided image and mask. It automatically routes tensors to the requested device (CPU, CUDA, MPS) and handles OutOfMemory fallbacks gracefully.

__init__(settings)

Initializes the FeatureExtractor with the given settings.

Parameters:

settings (FeatureSettings) – Configuration defining which features to compute.

extract(image, mask)

Executes feature extraction on the given Image and Mask.

Parameters:

• image (MedicalImage) – The baseline medical volume.

• mask (Mask) – The binary Region of Interest mask.

Returns:

A dictionary mapping feature names to their computed values.

Return type:

dict[str, float]

class fastrad.DenseFeatureExtractor(settings)

Bases: FeatureExtractor

Subclass of FeatureExtractor that natively outputs dense, voxel-wise feature maps using sliding 3D window memory-strided patch views.

extract_dense(image, mask, kernel_size, stride=1)

Executes dense feature extraction on the given Image and Mask.

Parameters:

• image (MedicalImage) – Baseline medical volume.

• mask (Mask) – Binary ROIs. Only windows containing positive mask voxels are computed.

• kernel_size (Union[int, Tuple[int, int, int]]) – 3D window dimensions (z, y, x).

• stride (Union[int, Tuple[int, int, int]]) – Step size for window extraction.

Return type:

Dict[str, Tensor]

Returns:

Dict mapping feature names to dense torch.Tensor feature maps. Output shape is (Dz_out, Dy_out, Dx_out), matching the sliding window grid. Voxels with no valid input mask elements are set to NaN.

class fastrad.VoxelFeatureExtractor(settings, kernel_size=3)

Bases: object

Experimental sliding-window feature extractor for voxel-wise radiomic maps.

WARNING: Native 3D patch extraction memory consumption grows factorially. This calculates standard macro radiomics iteratively over spatial bounding boxes. It is recommended solely for small Region of Interests or with powerful GPU limits.

__init__(settings, kernel_size=3)

extract(image, mask)

Return type:

dict[str, Tensor]

fastrad.load_and_align(image_path, mask_path, resample_spacing=None, crop=True)

Core entrypoint matching the PyRadiomics pyradiomics.imageoperations logic exactly.

Return type:

Tuple[MedicalImage, Mask]

fastrad.apply_builtin_filters(image, filter_types)

Master router handling multiple simultaneous math mappings to mirror legacy automated scaling. Argument format mimics standard PyRadiomics filter definition dictionaries: e.g. {“Original”: {}, “LoG”: {“sigma”: [1.0, 2.0]}, “Square”: {}}

Return type:

Dict[str, MedicalImage]

MedicalImage

class fastrad.image.MedicalImage(tensor, spacing=(1.0, 1.0, 1.0))

Representation of a continuous 3D medical volume (e.g., CT or MRI).

tensor

The 3D image array as a PyTorch FloatTensor.

Type:

torch.Tensor

spacing

The physical voxel dimensions (z, y, x).

Type:

Tuple[float, float, float]

__init__(tensor, spacing=(1.0, 1.0, 1.0))

to(device)

Moves the underlying tensor to the specified device.

Return type:

MedicalImage

classmethod from_dicom(path)

Creates a MedicalImage from a directory containing DICOM slices.

Parameters:

path (Union[str, Path]) – Path to the directory containing the DICOM files.

Return type:

MedicalImage

classmethod from_nifti(path)

Creates a MedicalImage from a NIfTI format image file (.nii or .nii.gz).

Parameters:

path (Union[str, Path]) – Path to the NIfTI file.

Return type:

MedicalImage

Returns:

A new instantiated MedicalImage object with extracted spacing.

Mask

class fastrad.image.Mask(tensor, spacing=(1.0, 1.0, 1.0))

Representation of a binary 3D Region of Interest (ROI) mask.

tensor

The 3D binary mask array as a PyTorch FloatTensor.

Type:

torch.Tensor

spacing

The physical voxel dimensions (z, y, x).

Type:

Tuple[float, float, float]

__init__(tensor, spacing=(1.0, 1.0, 1.0))

to(device)

Moves the underlying tensor to the specified device.

Return type:

Mask

classmethod from_dicom(path)

Creates a binary Mask from a directory containing DICOM slices. Voxels strictly greater than 0 are set to 1.

Parameters:

path (Union[str, Path]) – Path to the directory containing the DICOM ROIs.

Return type:

Mask

classmethod from_nifti(path)

Creates a binary Mask from a NIfTI format image file (.nii or .nii.gz). Voxels strictly greater than 0 are set to 1.

Parameters:

path (Union[str, Path]) – Path to the NIfTI file.

Return type:

Mask

Returns:

A new instantiated binary Mask object with extracted spacing.

FeatureSettings

class fastrad.settings.FeatureSettings(feature_classes=<factory>, bin_width=25.0, device='auto', spacing=(1.0, 1.0, 1.0), force2D=False, force2Ddimension=0, compile=False, compile_mode='reduce-overhead', amp=False, differentiable=False)

Configuration parameters regulating standard feature extraction pipelines.

feature_classes

List of feature groups to extract (e.g., ["firstorder", "glcm"]).

bin_width

Radiometric discretization width applied before extracting textures.

device

Target execution device ("cpu", "cuda", "mps", or "auto").

spacing

Real world physical spacing array (z, y, x) propagated downstream.

force2D

Flag controlling slice-by-slice 2D calculation routing.

force2Ddimension

Target dimension slice axis when projecting 3D volumes to 2D.

feature_classes: List[str]

bin_width: float = 25.0

device: str = 'auto'

spacing: Tuple[float, float, float] = (1.0, 1.0, 1.0)

force2D: bool = False

force2Ddimension: int = 0

compile: bool = False

compile_mode: str = 'reduce-overhead'

amp: bool = False

differentiable: bool = False

__init__(feature_classes=<factory>, bin_width=25.0, device='auto', spacing=(1.0, 1.0, 1.0), force2D=False, force2Ddimension=0, compile=False, compile_mode='reduce-overhead', amp=False, differentiable=False)

FeatureExtractor

class fastrad.extractor.FeatureExtractor(settings)

Main orchestration engine for radiomics feature extraction.

The FeatureExtractor consumes a FeatureSettings configuration and executes the specified feature class modules against a provided image and mask. It automatically routes tensors to the requested device (CPU, CUDA, MPS) and handles OutOfMemory fallbacks gracefully.

__init__(settings)

Initializes the FeatureExtractor with the given settings.

Parameters:

settings (FeatureSettings) – Configuration defining which features to compute.

extract(image, mask)

Executes feature extraction on the given Image and Mask.

Parameters:

• image (MedicalImage) – The baseline medical volume.

• mask (Mask) – The binary Region of Interest mask.

Returns:

A dictionary mapping feature names to their computed values.

Return type:

dict[str, float]

DenseFeatureExtractor

class fastrad.dense_extractor.DenseFeatureExtractor(settings)

Subclass of FeatureExtractor that natively outputs dense, voxel-wise feature maps using sliding 3D window memory-strided patch views.

extract_dense(image, mask, kernel_size, stride=1)

Executes dense feature extraction on the given Image and Mask.

Parameters:

• image (MedicalImage) – Baseline medical volume.

• mask (Mask) – Binary ROIs. Only windows containing positive mask voxels are computed.

• kernel_size (Union[int, Tuple[int, int, int]]) – 3D window dimensions (z, y, x).

• stride (Union[int, Tuple[int, int, int]]) – Step size for window extraction.

Return type:

Dict[str, Tensor]

Returns:

Dict mapping feature names to dense torch.Tensor feature maps. Output shape is (Dz_out, Dy_out, Dx_out), matching the sliding window grid. Voxels with no valid input mask elements are set to NaN.