diff-fvr 1.0.0__py3-none-any.whl

diff_fvr-1.0.0.dist-info/METADATA

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: diff-fvr
+Version: 1.0.0
+Summary: Dual-Domain Differentiable Fourier Volume Rendering for Ultra-Fast Biplanar 3D-2D Spine Registration
+Author-email: Pareel Amre <pareel.amre@gmail.com>
+License: MIT
+Keywords: digitally-reconstructed-radiographs,fourier-volume-rendering,3d-2d-registration,spine-surgery,medical-imaging,image-guided-interventions
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scipy>=1.10.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: matplotlib>=3.7.0
+Requires-Dist: pillow>=9.5.0
+Requires-Dist: pydicom>=2.4.0
+Requires-Dist: simpleitk>=2.2.0
+Requires-Dist: scikit-image>=0.20.0
+
+# Dual-Domain Differentiable Fourier Volume Rendering (Diff-FVR) for Real-Time Biplanar 3D–2D Spine Registration
+
+[![CI](https://github.com/pareelamre/diff-fvr/actions/workflows/ci.yml/badge.svg)](https://github.com/pareelamre/diff-fvr/actions/workflows/ci.yml)
+[![Pages](https://github.com/pareelamre/diff-fvr/actions/workflows/pages.yml/badge.svg)](https://pareelamre.github.io/diff-fvr/)
+[![Live Cockpit](https://img.shields.io/badge/Live%20Cockpit-GitHub%20Pages-brightgreen)](https://pareelamre.github.io/diff-fvr/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+
+**Author:** Pareel Amre  
+**Affiliation:** Faculty of Computer Science, Technische Universität Dresden (TU Dresden), 01062 Dresden, Germany  
+**Email:** `pareel.amre@gmail.com`  
+**Target Venue:** *IEEE Transactions on Medical Imaging* / *Medical Image Analysis*  
+
+---
+
+## 🔬 Scientific Overview
+
+Intensity-based 3D–2D registration between pre-operative volumetric Computed Tomography (pCT) and intra-operative 2D fluoroscopy is essential for computer-assisted spine surgery (e.g. pedicle screw navigation). However, conventional ray-casting DRR synthesis scales cubically ($\mathcal{O}(N^3)$), requiring $> 1.0\text{ s}$ per projection on CPU.
+
+**Diff-FVR** formulates Digitally Reconstructed Radiographs (DRRs) via the **continuous Fourier Projection-Slice Theorem**, reducing rendering complexity to $\mathcal{O}(N^2)$ frequency slice extraction:
+
+$$
+\mathcal{F}_{2D}\{\mathcal{P}[f(x,y,z)]\} = \mathcal{S}_{2D}\{\mathcal{F}_{3D}[f(x,y,z)]\}
+$$
+
+1. **Mathematical Anti-Aliasing:** Enforces $2\times$ spatial zero-padding bound ($Z_p = 2.0 \ge \sqrt{3}$) and $\text{sinc}^2$ spatial pre-multiplication to eliminate boundary wrap-around and peripheral roll-off.
+2. **Exact 1:1 Scale Preservation:** Implements full-bandwidth frequency slicing to preserve physical anatomical scale.
+3. **Normalized Spectral Cross-Correlation (Spectral-NCC):** Computes similarity directly in 2D Fourier space via Parseval's identity ($< 1.0\text{ ms}$ per pose) with **zero inverse Fourier transforms** inside the optimization loop.
+4. **Articulated Multi-Vertebra Kinematics:** Models inter-vertebral flexion (L3–L4–L5) on surgical tables using Fourier linearity:
+$$
+\mathcal{F}\left\{\sum_i I_i\right\} = \sum_i S_i(\mathbf{k}, \mathbf{T}_i)
+$$
+5. **Robustness to Physical Failure Limits:** Automatic radio-opaque metal hardware saturation masking + Masked Spatial Loss (achieving $0.000\text{ mm}$ error under $30\%$ occlusion) and isocenter geometric calibration ($1/\text{mag} = \text{SAD}/\text{SDD}$).
+
+---
+
+## 📊 Comprehensive Experimental Suite (23 Benchmarks)
+
+| Experiment | Title | Key Quantitative Finding |
+| :--- | :--- | :--- |
+| **Exp 1** | O(N²) vs O(N³) Asymptotic Complexity | **11.5× to 72.5× speedup** over spatial raycasting (1.38 ms DRR). |
+| **Exp 2** | Rotational Invariance (72 Angles) | PSNR = 23.96 dB, SSIM = 0.9329, NCC = 0.9943 ± 0.0007. |
+| **Exp 3** | Zero-Padding & Sinc² Premultiplication | 2× padding eliminates high-frequency wrap-around; roll-off removed. |
+| **Exp 4** | Spectral-NCC 50-Trial Benchmark | 0.84 mm mTRE (98.0% success < 2.0 mm) in 1.82 s (212× per-pose acceleration). |
+| **Exp 5** | Energy Landscape & Capture Range | Smooth, strictly convex basin over ±25° / ±25 mm displacement. |
+| **Exp 6** | Biplanar vs. Monoplanar 6-DoF | Depth error Δtx reduced from 3.59 mm down to **0.03 ± 0.04 mm**. |
+| **Exp 7** | Real Hospital Patient DICOM CT Series | **mTRE = 0.020 mm** (Clean), **0.031 mm** (Low-Dose); 100% success. |
+| **Exp 8** | Capture Basin Sensitivity Bounds | 100% success at ±5° / ±5 mm; 90% at ±16° / ±16 mm. |
+| **Exp 9** | Cone-Beam Perspective Divergence | Identified 1.4× magnification distortion; isocenter calibration cuts error by 89%. |
+| **Exp 10** | Surgical Metal Hardware Occlusion | Automatic saturation threshold + Masked Spatial Loss drops error from 49.15 mm to 0.000 mm. |
+| **Exp 11** | Radiation Exposure Starvation Sweep | Sub-0.05 mm mTRE maintained across 6 orders of magnitude (10⁶ down to 10³ ph/px). |
+| **Exp 12** | Multi-Center Kaggle Lumbar CT Cohort | **mTRE = 1.341 mm** (Clean), **1.351 mm** (Low-Dose); 85.0% success. |
+| **Exp 13** | Multi-Center AMOS Cohort (NCT Dresden) | **mTRE = 1.118 mm** (Clean), **1.121 mm** (Low-Dose); 90.0% success. |
+| **Exp 14** | Resolved Failure Limits Verification | Unit tests confirm 0.000 mm precision under 30% metal occlusion. |
+| **Exp 15** | Articulated Multi-Vertebra Kinematics | Hierarchical L3-L4-L5 model recovers base pose (0.767 mm) and in-vivo flexion (Δloss = −54.7%). |
+| **Exp 16** | Unified Multi-Center CED Benchmark | Standardized linear and logarithmic CED curves across all 3 independent cohorts. |
+| **Exp 17** | Detector FOV Truncation & Clipping | 2D Tukey cosine tapering preserves 0.75 mm mTRE up to 30% clipping. |
+| **Exp 18** | Non-Orthogonal C-Arm Angulations | Sub-millimeter (0.021–0.055 mm) down to Δϕ = 30° safe operating angle. |
+| **Exp 19** | Polychromatic Beam Hardening & Soft Tissue | High-Pass Spectral-NCC achieves 100% sub-mm (0.028–0.358 mm) across all tiers. |
+| **Exp 20** | Intraoperative Respiratory Motion Blur | Phase invariance preserves sub-millimeter tracking across 0–5 mm breathing smear. |
+| **Exp 21** | Preoperative CT Anisotropic Slice Thickness | Biplanar decoupling preserves sub-millimeter precision (0.0008 mm) on 5.0 mm trauma slices. |
+| **Exp 22** | Dynamic Streaming Fluoroscopy Tracking | Real-time video tracking across 60 frames with warm-start analytical gradients. |
+| **Exp 23** | Joint Articulation + Metal Implants | Base mTRE 0.776 mm, cuts residual loss by 48.2%, recovers in-vivo flexion angles. |
+
+---
+
+## 🎮 Interactive Surgical Registration Cockpit
+
+An interactive in-browser simulator demonstrating real-time 6-DoF biplanar registration, pedicle screw metal saturation, and physical breakdown regimes is live:
+
+👉 **[Launch Interactive Cockpit](https://pareelamre.github.io/diff-fvr/)**
+
+---
+
+## 🚀 Installation & CLI Quick Start
+
+```bash
+# Install package in editable mode
+pip install -e .
+
+# 1. Synthesize a fast 2D DRR from 3D CT:
+fvr-render --ct data/dicom --yaw 15.0 --pitch -5.0 --view ap --res 96 --out drr_ap.png
+
+# 2. Run biplanar 6-DoF spine registration:
+fvr-register --ct data/dicom --ap data/ap_xray.png --lat data/lat_xray.png --handle-metal --out pose_result.json
+
+# 3. Run production integration test suite:
+python tests/test_core_engine.py
+```
+
+---
+
+## 📁 Repository Structure
+
+```
+fft-drr-project/
+├── data/
+│   ├── dicom/                 # Real clinical hospital patient CT DICOM series
+│   ├── kaggle_lumbar/         # Multi-center Kaggle lumbar spine CT
+│   └── amos/                  # AMOS multi-organ abdominal CT cohort (NCT Dresden)
+├── docs/                      # GitHub Pages interactive surgical cockpit simulator
+├── src/fvr/
+│   ├── core_engine.py         # Production engine (calibration, metal masking, bounded search)
+│   ├── diff_fvr.py            # Core Differentiable Fourier Volume Renderer
+│   ├── articulated_spine.py   # Multi-body kinematic chain (L3-L4-L5)
+│   ├── gradients.py           # Closed-form analytical Fourier phase & spectral gradients
+│   ├── robust_registration.py # Masked spatial loss engine
+│   └── dicom_loader.py        # DICOM series loader & Hounsfield-to-attenuation converter
+├── experiments/               # Complete 23 benchmark experiment scripts
+├── outputs/paper_figures/     # High-resolution 300 DPI publication figures & CSV tables
+├── tests/                     # Verification and regression test suite
+├── main.tex                   # IEEE Transactions on Medical Imaging manuscript
+└── paper_manuscript.md        # Comprehensive audited research report
+```

diff_fvr-1.0.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+fvr/__init__.py,sha256=6dAIlgWZYlrKWEu7vSUAnJk4HUvn102zGZ4s6KzXgY4,1100
+fvr/articulated_spine.py,sha256=-FzPOPK9CUXJVSLrhGcQZlwqiF0yQGdXpWH4ZUKCgo0,6607
+fvr/cli.py,sha256=OHlIYLgOyn_zPwiM4Ve1rH2FplXoxOTU_WmQdtpHW1w,7103
+fvr/core_engine.py,sha256=pvTaTnyb5_xxLDggvM9mpZfy9h5NT3ElhT2Pqqe_hu8,7351
+fvr/dicom_loader.py,sha256=nvC6_FntSWRkf_v7aQ-100jxbmT6_-0qvg8jTMasZoo,6399
+fvr/diff_fvr.py,sha256=YWD4w0h-m6q9GN3AjS4JVp2ww3s_wnzWOI00S-wqQnk,8116
+fvr/fvr_engine.py,sha256=vYBp66kFqU9lVhQKSRWODUNGndUF7KQwwS9bvnYD8-4,6125
+fvr/gradient_optimizer.py,sha256=BEnsCzqu2NHN4XQMtGXlnBtoN6lPI0-8nLXsa2xr-Rg,2872
+fvr/gradients.py,sha256=KLjxceU8sltsZvbnBGWHX5UV3dMCnjwoinBopqSgkDY,5631
+fvr/raycasting_drr.py,sha256=ciS8jxIUNUBgujvFfrRiOD7Zi-iTsHx2aHPnPsmHbVU,2753
+fvr/registration_3d2d.py,sha256=KkjO-yGn0A5cGPGBWiPdMMLOLSgl6BNhJlM-UaEfxp8,5924
+fvr/robust_registration.py,sha256=doZ0rq41R5IKsYSbhva5ciXavjMXSd7eDmfHvT7X_i0,5705
+fvr/rotation_2d.py,sha256=WKVSykE1I3O0YV5TmZiLhWB5hYlaABxfXOb8E-iaMJQ,2574
+diff_fvr-1.0.0.dist-info/METADATA,sha256=nm15xez1MTWjlbw4A5xKhOO7aJLFkb-33lXUG9gwt9c,8966
+diff_fvr-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+diff_fvr-1.0.0.dist-info/entry_points.txt,sha256=zTLs9n81t3KR7p4HJbf1AXgoABNSnHB3VulCPDqxork,88
+diff_fvr-1.0.0.dist-info/top_level.txt,sha256=v00arNuDKSbJkDGsfQJPu4RRdOr6gqGqBaTbDnHRkUQ,4
+diff_fvr-1.0.0.dist-info/RECORD,,

diff_fvr-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

diff_fvr-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+fvr-register = fvr.cli:main_register
+fvr-render = fvr.cli:main_render

diff_fvr-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fvr

fvr/__init__.py

@@ -0,0 +1,35 @@
+"""
+Diff-FVR: Differentiable Fourier Volume Rendering for 3D-2D Registration.
+Author: Pareel Amre, TU Dresden
+"""
+
+from .fvr_engine import FourierVolumeRenderer
+from .diff_fvr import DifferentiableFourierVolumeRenderer
+from .core_engine import RobustDiffFVREngine, detect_radio_opaque_metal
+from .gradients import SpectralGradientEngine
+from .articulated_spine import ArticulatedSpineModel, VertebralSegment
+from .raycasting_drr import raycast_drr
+from .rotation_2d import rotate_2d_fft
+from .dicom_loader import load_dicom_series, create_spine_phantom, hu_to_attenuation
+from .registration_3d2d import compute_mtre_6dof
+from .cli import main_render, main_register
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "FourierVolumeRenderer",
+    "DifferentiableFourierVolumeRenderer",
+    "RobustDiffFVREngine",
+    "detect_radio_opaque_metal",
+    "SpectralGradientEngine",
+    "ArticulatedSpineModel",
+    "VertebralSegment",
+    "raycast_drr",
+    "rotate_2d_fft",
+    "load_dicom_series",
+    "create_spine_phantom",
+    "hu_to_attenuation",
+    "compute_mtre_6dof",
+    "main_render",
+    "main_register"
+]

fvr/articulated_spine.py

@@ -0,0 +1,163 @@
+"""
+Articulated Multi-Vertebra Kinematic Registration Framework.
+
+Models the lumbar spine as a kinematically coupled multi-body system (e.g., L3-L4-L5)
+where each vertebral segment undergoes independent relative rotation (flexion/extension,
+lateral bending, axial twist) and translation within physiological disc limits.
+
+Leverages Fourier Linearity:
+  F_2D{ sum_i I_i } = sum_i F_2D{ I_i } = sum_i S_i(k, T_i)
+allowing ultra-fast simultaneous articulated DRR synthesis and hierarchical registration.
+"""
+
+import numpy as np
+import time
+from typing import List, Dict, Any, Tuple, Optional
+from scipy.optimize import minimize
+from .diff_fvr import DifferentiableFourierVolumeRenderer
+
+
+class VertebralSegment:
+    """
+    Represents an individual segmented vertebra in 3D Fourier space.
+    """
+    def __init__(self, name: str, sub_volume: np.ndarray, nominal_offset_z: float, pad_factor: float = 2.0):
+        self.name = name
+        self.nominal_offset_z = nominal_offset_z
+        self.renderer = DifferentiableFourierVolumeRenderer(sub_volume, pad_factor=pad_factor)
+        self.shape = sub_volume.shape
+
+
+class ArticulatedSpineModel:
+    """
+    Hierarchical Articulated Spine Model with Physiological Joint Bounds.
+    """
+    def __init__(self, segments: List[VertebralSegment]):
+        self.segments = segments
+        self.num_segments = len(segments)
+
+    def render_articulated_spectrum(
+        self,
+        base_pose: np.ndarray,  # [yaw, pitch, roll, tx, ty, tz]
+        relative_articulations: List[np.ndarray],  # list of [d_yaw, d_pitch, d_roll, d_tx, d_ty, d_tz]
+        view: str = 'lateral'
+    ) -> np.ndarray:
+        """
+        Synthesize combined 2D Fourier spectrum of articulated spine via Fourier linearity.
+        """
+        ref_seg = self.segments[0]
+        slice_h = ref_seg.renderer.pz
+        slice_w = ref_seg.renderer.py if view == 'lateral' else ref_seg.renderer.px
+
+        total_spectrum = np.zeros((slice_h, slice_w), dtype=np.complex128)
+
+        curr_pose = np.copy(base_pose)
+        for i, seg in enumerate(self.segments):
+            if i > 0 and len(relative_articulations) >= i:
+                # Accumulate relative inter-vertebral articulation
+                curr_pose = curr_pose + relative_articulations[i - 1]
+
+            # In-plane translation for the specific view
+            yaw, pitch, roll, tx, ty, tz = curr_pose
+            if view == 'lateral':
+                f_slice = seg.renderer.extract_frequency_slice(yaw, pitch, roll, tx=ty, ty=tz, view='lateral')
+            elif view == 'ap':
+                f_slice = seg.renderer.extract_frequency_slice(yaw, pitch, roll, tx=tx, ty=tz, view='ap')
+            else:
+                f_slice = seg.renderer.extract_frequency_slice(yaw, pitch, roll, tx=tx, ty=ty, view='axial')
+
+            total_spectrum += f_slice
+
+        return total_spectrum
+
+    def render_drr(
+        self,
+        base_pose: np.ndarray,
+        relative_articulations: List[np.ndarray],
+        view: str = 'lateral'
+    ) -> np.ndarray:
+        """
+        Render spatial projection of the articulated spine.
+        """
+        f_spectrum = self.render_articulated_spectrum(base_pose, relative_articulations, view=view)
+        from scipy import fft
+        spatial = np.real(fft.fftshift(fft.ifft2(fft.ifftshift(f_spectrum))))
+        return np.maximum(spatial, 0.0)
+
+    def register_articulated_biplanar(
+        self,
+        f_target_ap: np.ndarray,
+        f_target_lat: np.ndarray,
+        init_base_pose: np.ndarray,
+        max_iter_global: int = 40,
+        max_iter_local: int = 30
+    ) -> Dict[str, Any]:
+        """
+        Two-Stage Hierarchical Articulated Registration:
+          Stage 1: Global Spine Alignment (all vertebrae rigidly locked).
+          Stage 2: Local Inter-Vertebral Joint Refinement within physiological bounds.
+        """
+        t0 = time.time()
+        num_joints = self.num_segments - 1
+
+        # --- Stage 1: Global Rigid Base Registration ---
+        def stage1_obj(pose):
+            zero_art = [np.zeros(6) for _ in range(num_joints)]
+            f_ap = self.render_articulated_spectrum(pose, zero_art, view='ap')
+            f_lat = self.render_articulated_spectrum(pose, zero_art, view='lateral')
+
+            ncc_ap = self.segments[0].renderer.compute_spectral_ncc(f_ap, f_target_ap)
+            ncc_lat = self.segments[0].renderer.compute_spectral_ncc(f_lat, f_target_lat)
+            return float(0.5 * (1.0 - ncc_ap) + 0.5 * (1.0 - ncc_lat))
+
+        res_stage1 = minimize(
+            stage1_obj,
+            x0=init_base_pose,
+            method='Powell',
+            options={'maxiter': max_iter_global, 'ftol': 1e-4}
+        )
+        base_converged = res_stage1.x
+
+        # --- Stage 2: Articulated Joint Refinement ---
+        # State vector: [d_yaw_1..K-1, d_pitch_1..K-1, d_roll_1..K-1, d_tx_1..K-1, ...]
+        if num_joints > 0:
+            init_art = np.zeros(num_joints * 6)
+
+            # Physiological limits: +/- 8 deg rotation, +/- 2.5 mm translation
+            joint_bounds = []
+            for _ in range(num_joints):
+                joint_bounds.extend([(-8.0, 8.0), (-8.0, 8.0), (-8.0, 8.0), (-2.5, 2.5), (-2.5, 2.5), (-2.5, 2.5)])
+
+            def stage2_obj(art_flat):
+                arts = [art_flat[j*6:(j+1)*6] for j in range(num_joints)]
+                f_ap = self.render_articulated_spectrum(base_converged, arts, view='ap')
+                f_lat = self.render_articulated_spectrum(base_converged, arts, view='lateral')
+
+                ncc_ap = self.segments[0].renderer.compute_spectral_ncc(f_ap, f_target_ap)
+                ncc_lat = self.segments[0].renderer.compute_spectral_ncc(f_lat, f_target_lat)
+
+                # Prior: small regularization on inter-vertebral strain
+                strain_penalty = 1e-4 * np.sum(art_flat ** 2)
+                return float(0.5 * (1.0 - ncc_ap) + 0.5 * (1.0 - ncc_lat) + strain_penalty)
+
+            res_stage2 = minimize(
+                stage2_obj,
+                x0=init_art,
+                method='Powell',
+                options={'maxiter': max_iter_local, 'ftol': 1e-4}
+            )
+            arts_converged = [res_stage2.x[j*6:(j+1)*6] for j in range(num_joints)]
+            final_loss = float(res_stage2.fun)
+        else:
+            arts_converged = []
+            final_loss = float(res_stage1.fun)
+
+        elapsed = time.time() - t0
+
+        return {
+            'base_pose': base_converged,
+            'articulations': arts_converged,
+            'final_loss': final_loss,
+            'time_sec': elapsed,
+            'stage1_success': res_stage1.success
+        }

fvr/cli.py

@@ -0,0 +1,160 @@
+"""
+Command-Line Interface (CLI) for Diff-FVR.
+Provides:
+  - fvr-render: Ultra-fast DRR projection synthesis from 3D CT.
+  - fvr-register: Biplanar 3D-2D 6-DoF registration against intraoperative fluoroscopy.
+"""
+
+import argparse
+import json
+from pathlib import Path
+import time
+import numpy as np
+from PIL import Image
+from scipy.ndimage import zoom
+
+from .dicom_loader import load_dicom_series, hu_to_attenuation
+from .diff_fvr import DifferentiableFourierVolumeRenderer
+from .core_engine import RobustDiffFVREngine
+
+
+def load_volume(ct_path: Path, target_res: int = 96):
+    """
+    Load CT from DICOM directory or numpy array, with isotropic cubic resampling.
+    """
+    if ct_path.is_dir():
+        vol_hu, spacing = load_dicom_series(ct_path)
+    elif ct_path.suffix in ['.npy', '.npz']:
+        vol_hu = np.load(ct_path)
+        spacing = (1.0, 1.0, 1.0)
+    else:
+        raise ValueError(f"Unsupported CT path: {ct_path}. Must be a DICOM directory or .npy file.")
+
+    if target_res is not None and vol_hu.shape[1] != target_res:
+        target_xy = target_res
+        phys_z = vol_hu.shape[0] * spacing[0]
+        phys_x = vol_hu.shape[2] * spacing[2]
+        vox_size = phys_x / target_xy
+        target_z = int(round(phys_z / vox_size))
+
+        vol_iso = zoom(vol_hu, (target_z / vol_hu.shape[0], target_xy / vol_hu.shape[1], target_xy / vol_hu.shape[2]), order=1)
+        pad_z_before = (target_xy - target_z) // 2
+        pad_z_after = target_xy - target_z - pad_z_before
+        vol_cubic = np.pad(vol_iso, ((pad_z_before, pad_z_after), (0, 0), (0, 0)), mode='constant', constant_values=-1000.0)
+    else:
+        vol_cubic = vol_hu
+
+    return hu_to_attenuation(vol_cubic)
+
+
+def main_render():
+    parser = argparse.ArgumentParser(description="Diff-FVR: Ultra-fast Digitally Reconstructed Radiograph (DRR) Renderer.")
+    parser.add_argument("--ct", type=str, required=True, help="Path to pre-op CT DICOM directory or .npy file.")
+    parser.add_argument("--yaw", type=float, default=0.0, help="Rotation yaw in degrees (default: 0.0).")
+    parser.add_argument("--pitch", type=float, default=0.0, help="Rotation pitch in degrees (default: 0.0).")
+    parser.add_argument("--roll", type=float, default=0.0, help="Rotation roll in degrees (default: 0.0).")
+    parser.add_argument("--tx", type=float, default=0.0, help="Translation Tx in mm (default: 0.0).")
+    parser.add_argument("--ty", type=float, default=0.0, help="Translation Ty in mm (default: 0.0).")
+    parser.add_argument("--tz", type=float, default=0.0, help="Translation Tz in mm (default: 0.0).")
+    parser.add_argument("--view", type=str, choices=['ap', 'lateral'], default='ap', help="View angle ('ap' or 'lateral').")
+    parser.add_argument("--res", type=int, default=128, help="Isotropic cubic grid dimension (default: 128).")
+    parser.add_argument("--out", type=str, default="drr_output.png", help="Output PNG path (default: drr_output.png).")
+    
+    args = parser.parse_args()
+
+    ct_path = Path(args.ct)
+    if not ct_path.exists():
+        print(f"Error: CT path not found: {ct_path}")
+        return
+
+    print(f"Loading CT from: {ct_path} (resampling to {args.res}^3)...")
+    t0 = time.time()
+    vol_mu = load_volume(ct_path, target_res=args.res)
+    renderer = DifferentiableFourierVolumeRenderer(vol_mu, pad_factor=2.0)
+    print(f"Initialized 3D FFT volume in {time.time() - t0:.2f} s.")
+
+    t_render = time.perf_counter()
+    drr = renderer.render_drr(args.yaw, args.pitch, args.roll, tx=args.tx, ty=args.ty, view=args.view)
+    render_ms = (time.perf_counter() - t_render) * 1000.0
+
+    print(f"Rendered {args.view.upper()} DRR in {render_ms:.2f} ms ({1000.0 / render_ms:.1f} FPS)!")
+
+    # Normalize and save image
+    drr_norm = (drr - drr.min()) / (drr.max() - drr.min() + 1e-8)
+    img_uint8 = (drr_norm * 255.0).astype(np.uint8)
+    out_path = Path(args.out)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    Image.fromarray(img_uint8).save(out_path)
+    print(f"Saved rendered DRR to: {out_path.resolve()}")
+
+
+def main_register():
+    parser = argparse.ArgumentParser(description="Diff-FVR: Biplanar 3D-2D 6-DoF Rigid Spine Registration.")
+    parser.add_argument("--ct", type=str, required=True, help="Path to pre-op CT DICOM directory or .npy file.")
+    parser.add_argument("--ap", type=str, required=True, help="Path to target intraoperative AP X-ray (PNG/TIFF/NPY).")
+    parser.add_argument("--lat", type=str, required=True, help="Path to target intraoperative Lateral X-ray.")
+    parser.add_argument("--res", type=int, default=96, help="Isotropic CT grid dimension (default: 96).")
+    parser.add_argument("--max-iter", type=int, default=30, help="Maximum optimizer iterations (default: 30).")
+    parser.add_argument("--handle-metal", action="store_true", help="Enable automatic radio-opaque surgical metal saturation masking.")
+    parser.add_argument("--out", type=str, default="registration_result.json", help="Output JSON results path.")
+
+    args = parser.parse_args()
+
+    ct_path = Path(args.ct)
+    ap_path = Path(args.ap)
+    lat_path = Path(args.lat)
+
+    if not ct_path.exists() or not ap_path.exists() or not lat_path.exists():
+        print(f"Error: One or more input paths do not exist:\n  CT: {ct_path}\n  AP: {ap_path}\n  LAT: {lat_path}")
+        return
+
+    # Load targets
+    def load_img(p: Path):
+        if p.suffix == '.npy':
+            return np.load(p)
+        im = Image.open(p).convert('L')
+        return np.array(im, dtype=np.float64)
+
+    targ_ap = load_img(ap_path)
+    targ_lat = load_img(lat_path)
+
+    print(f"Loading and initializing CT from: {ct_path}...")
+    vol_mu = load_volume(ct_path, target_res=args.res)
+    engine = RobustDiffFVREngine(vol_mu, pad_factor=2.0)
+
+    print(f"Running Biplanar 6-DoF Registration (handle_metal={args.handle_metal}, max_iter={args.max_iter})...")
+    res = engine.register_biplanar_robust(
+        target_ap=targ_ap,
+        target_lat=targ_lat,
+        handle_metal=args.handle_metal,
+        max_iter=args.max_iter
+    )
+
+    pose = res['final_pose']
+    print(f"\nREGISTRATION CONVERGED in {res['time_sec']:.2f} s ({res['evaluations']} evaluations):")
+    print(f"  Rotation:    Yaw={pose[0]:.3f}°, Pitch={pose[1]:.3f}°, Roll={pose[2]:.3f}°")
+    print(f"  Translation: Tx={pose[3]:.3f} mm, Ty={pose[4]:.3f} mm, Tz={pose[5]:.3f} mm")
+    print(f"  Final Loss:  {res['final_loss']:.6f}")
+
+    out_data = {
+        'yaw_deg': float(pose[0]),
+        'pitch_deg': float(pose[1]),
+        'roll_deg': float(pose[2]),
+        'tx_mm': float(pose[3]),
+        'ty_mm': float(pose[4]),
+        'tz_mm': float(pose[5]),
+        'final_loss': float(res['final_loss']),
+        'time_sec': float(res['time_sec']),
+        'evaluations': int(res['evaluations']),
+        'metal_detected': bool(res['metal_detected'])
+    }
+
+    out_path = Path(args.out)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(out_path, 'w', encoding='utf-8') as f:
+        json.dump(out_data, f, indent=2)
+    print(f"Saved results to: {out_path.resolve()}")
+
+
+if __name__ == '__main__':
+    main_render()