How arcadelab/deepdrr works
Project Type and Purpose
• Type: Scientific simulation library / toolkit.
• Purpose: Generate realistic radiographs and fluoroscopy images from volumetric CT data at training-set scale using a mix of analytic models, machine-learning-based segmentation, and Monte Carlo GPU kernels.
File Structure
• Top-level:
– deepdrr/ – core Python packages
– example_projector.py, deepdrr_demo.ipynb – usage examples
– docs/ – documentation sources
– tests/ – unit tests
– setup.py, environment.yml, requirements.txt – build/install
• Inside deepdrr/:
– geo/ – geometry primitives (rays, segments, hyperplanes)
– device/ – C-arm definitions (MobileCArm, SimpleDevice)
– projector/ – projection engine (analytic & CUDA kernels, MC-GPU data)
– annotations/ – helper classes for fiducials & line markup
– instruments/ – tool/implant modeling abstractions
– network_segmentation.py – volumetric segmentation (V-Net)
– load_dicom*.py, downsample_tool.py – DICOM I/O & preprocessing
– utils/ – I/O, image, mesh, heatmap utilities
– vis.py – visualization helpers
Extract Architectural Insights from README
• Pipeline steps (see “Method Overview” figure):
1. Load and orient CT volume
2. (Optional) Material decomposition via V-Net segmentation
3. Analytic attenuation projection + noise injection
4. Machine-learning–based scatter estimation or turn off scatter
• Key technologies: Python 3, PyCUDA/CUDA (C++/cu for high-performance kernels), PyTorch compatibility, NumPy, SciPy, Sphinx docs.
Main Components & Interactions
A. Entry Points (top layer)
• CLI / Scripts: example_projector.py, deepdrr_demo.ipynb
• API: Python calls into deepdrr modules
B. Core Processing Modules (middle layer)
1. Volume I/O & Preprocessing
– load_dicom.py / load_dicom_tool.py
– downsample_tool.py
2. Geometry & Device Model
– deepdrr.geo.* (Ray generation, transforms)
– deepdrr.device.* (C-arm pose, isocenter)
3. Material Segmentation
– network_segmentation.py (V-Net on GPU)
4. Projection Engine
– Analytic CPU/CUDA code (attenuation)
– GPU Monte Carlo kernels (project_kernel.cu, scatter kernels)
– Data tables (mcgpu_* directories) for spectra, scatter, mfp
5. Instrument Modeling
– deepdrr.instruments.* + binary tool volumes
6. Utilities & Visualization
– deepdrr.utils.*, vis.py
C. External Dependencies & Resources (side layer)
• GPU (CUDA driver, GPU memory)
• PyCUDA, PyTorch (optional), NumPy
• Input: CT in DICOM / NIfTI
• Output: 2D radiographs (NumPy arrays, images)
• Documentation / Sphinx, Tests
Relationships & Data Flow
– CT file → Volume I/O → Volume object
– Volume object + Device object → Projector init
– Projector call →
· (optional) Segmentation → material maps
· Analytic projection + CUDA kernels → raw projection
· Scatter estimation module → scatter map → add to projection
· Noise injection utilities → final image
– Final image → User script / Visualization
Architectural Patterns & Principles
• Modular layered architecture
• Separation of concerns: I/O, geometry, simulation, ML segmentation, utilities
• GPU-accelerated compute kernels isolated under projector/
• Extensibility points: add new device models, spectra, tools, segmentation nets
Technologies & Frameworks
• Python package structure
• PyCUDA / custom CUDA (.cu) kernels
• PyTorch (for segmentation and seamless integration)
• NumPy, SciPy, Nibabel (volume I/O)
• Sphinx (docs), pytest (tests)