Quickstart: Evaluating a Lung Nodule

fastrad is engineered to be a seamless, high-performance drop-in upgrade for standard clinical radiomics pipelines. This quickstart guide will walk you through a practical, end-to-end scenario: Extracting 100+ textural biomarkers from a 3D structural lung nodule utilizing GPU acceleration.

Prerequisites

Ensure you have installed fastrad alongside a DICOM handler like SimpleITK.

pip install fastrad SimpleITK torch

Step 1: Load the Clinical Volume

fastrad separates the physical geometry of the scan from the Region of Interest (the segmentation). In this scenario, we possess a directory of DICOM files containing a patient CT scan, and a structural NIfTI file containing the explicit 3D boundaries of the radiologist’s tracing.

import SimpleITK as sitk
import torch
from fastrad import MedicalImage, Mask

# Load the structural CT Array
dicom_dir = "/data/TCIA/RIDER-102/CT_Scan"
image = MedicalImage.from_dicom(dicom_dir)

# Alternatively, load the explicit Mask using SimpleITK directly to manipulate arrays
mask_path = "/data/TCIA/RIDER-102/tumor_segmentation.nii.gz"
sitk_mask = sitk.ReadImage(mask_path)

# Convert to native PyTorch Tensor geometry
mask_tensor = torch.tensor(sitk.GetArrayFromImage(sitk_mask), dtype=torch.float32)
spacing = sitk_mask.GetSpacing()

# fastrad strictly maps (z, y, x) configurations natively
mask = Mask(tensor=mask_tensor, spacing=(spacing[2], spacing[1], spacing[0]))

Step 2: Configure the Extractor Blueprint

The FeatureSettings object dictates the mathematical limits and hardware routing for your pipeline. The bin_width parameter is clinically critical: it defines how raw Hounsfield Units (HU) are quantized into discrete matrix bins for textural features like the GLCM. The IBSI commonly utilizes widths of 25.0 for CT algorithms.

from fastrad import FeatureSettings

settings = FeatureSettings(
    # Define the algorithmic scope
    feature_classes=["firstorder", "shape", "glcm", "glrlm", "glszm"],

    # IBSI-compliant mathematical binning rule
    bin_width=25.0,

    # The Core Upgrade: Dispatch to CUDA natively
    device="cuda"
)

Step 3: Execute the Extraction

Initialize the orchestrator and extract your features. If your configured machine lacks CUDA capabilities, fastrad dynamically detects the hardware restrictions and resolves gracefully to your CPU without destroying your configuration.

from fastrad import FeatureExtractor

extractor = FeatureExtractor(settings)

# Extraction occurs instantaneously across the physical PyTorch graph
features = extractor.extract(image, mask)

print(f"Extraction Successful! Gathered {len(features)} dimensional vectors.")

Step 4: Consume the Feature Output

The features variable is a standard Python dictionary identically mirroring PyRadiomics outputs, making it extremely easy to plug natively into pandas, scikit-learn classifiers, or PyTorch neural networks.

# Display physical characteristics
print(f"Maximum 3D Diameter: {features['shape:Maximum3DDiameter']:.2f} mm")
print(f"Tumor Volume:        {features['shape:MeshVolume']:.2f} mm^3")

# Display complex spatial textural signatures
print(f"GLCM Contrast:       {features['glcm:Contrast']:.4f}")
print(f"GLSZM Area Emphasis: {features['glszm:SmallAreaEmphasis']:.4f}")

Next Steps

The above example processed a single volume safely. However, standard clinical research evaluates thousands of patients identically.

To learn about iterating over batch arrays and resolving hardware Out-Of-Memory limitations, read our exhaustive User Guide.
To investigate the core 100+ IBSI vector rules mathematically extracted internally, see the formal Mathematical Documentation.

Advanced: Hardware-Accelerated Voxel-wise Feature Extraction

If your pipeline requires dense feature maps fed directly into downstream neural networks (like CNNs or Transformers), you can utilize our hardware-accelerated memory-strided patch view extractor without altering your mathematical blueprints:

from fastrad import DenseFeatureExtractor

dense_extractor = DenseFeatureExtractor(settings)

# Extracts dense sliding window feature maps
# Using a kernel size of 3x3x3 voxels and stride of 1.
dense_features = dense_extractor.extract_dense(image, mask, kernel_size=3, stride=1)

# Output maps are full natively tracked PyTorch Tensors on your hardware configuration
print(f"Dense Feature Map Shape (Energy): {dense_features['firstorder:energy'].shape}")