Developers Guide

Welcome to the fastrad backend architecture overview. This section details how you can contribute new features, integrate novel tensor operations, and scientifically validate against established benchmarks.

Architecture: PyTorch over SimpleITK

The core mechanism separating fastrad from PyRadiomics lies in its abandonment of localized, Pythonic sequential arrays, instead leveraging PyTorch (torch.Tensor).

  • All volumes are projected into 3D tensors natively formatted as standard IEEE Floats (torch.float32).

  • Region of Interest (ROI) boundaries natively crop absolute 3D bounds rather than zeroing pixels.

  • Operations must never attempt iteration (for loops over 3-dimensional indices). All spatial queries must mathematically collapse utilizing vector dot products, multi-dimensional array shifts (e.g., torch.roll), and histogram binnings (torch.bincount, torch.unique).

Adding the Baseline (Feature Classes)

Every feature module (e.g., features/glcm.py) must implement a compute() entry-point accepting image_tensor, mask_tensor, and settings.

When introducing new textural derivations: 1. Initialize the respective spatial dependency matrix (e.g., NGTDM). 2. Utilize the robust, internal get_binned_image() logic for discrete gray-level compliance rather than writing implicit quantization algorithms array-side. 3. Construct mathematical aggregates utilizing PyTorch primitive operations to retain device agnosticism (operating equally over .cpu() and .cuda() tensors).

Scientific Parity Testing

We strictly enforce Image Biomarker Standardisation Initiative (IBSI) compliance on every PR. We provide automated suite tools located within benchmarks/run_numerical_parity.py.

Before merging any internal mathematical manipulation, you must run:

python benchmarks/run_numerical_parity.py

Output parity validates the identical nature of your extracted values mapped against legacy PyRadiomics execution results. A strict Absolute Relative Deviation cutoff of 1e-4 dictates PR rejection bounds mechanically.

Out-Of-Memory (OOM) GPU Catchers

Because we rely on dense PyTorch generation rules, developers must securely ensure large tensor allocation schemas inside specific features don’t crash the global Python script natively. Do not catch VRAM exceptions inherently within the feature calculation functions: FeatureExtractor.extract() centralizes all OutOfMemoryError handlers natively via a hardware step-down CPU re-routing logic.