How wei-shao-reg/gdr works
1. What this repository is
- This repo is a standalone C++ implementation of the Geodesic Density Regression (GDR) algorithm for correcting respiratory motion artifacts in 4DCT lung imaging.
- It is not a library/service stack; the main architecture is a pair of command-line executables plus sample medical-imaging data and parameter files.
2. Top-level execution model
- The user builds two binaries: GDR2D and GDR3D.
- Each executable takes a single parameter file path on the command line and runs a complete regression/correction job from input images to output artifacts-free results.
3. Build and runtime dependency boundary
- The code is built with CMake and depends on ITK (Insight Toolkit).
- The README explicitly targets C++11 and a Release build for performance.
- This dependency boundary is important: all image I/O, image types, and likely registration/math operations are mediated through ITK.
4. Primary subsystems
- Application entry points: GDR2D.cxx and GDR3D.cxx are the two mode-specific front ends.
- Build configuration: CMakeLists.txt wires the executables and ITK linkage.
- Parameter/configuration layer: param2D.txt, param3D.txt, and param_explanation.txt define the runtime contract.
- Data assets: the code/data directory contains example CT phases, lung masks, and artifact masks.
5. Mode split: 2D vs 3D
- The repo supports two operating modes:
- 2D GDR for a simulated time series test case.
- 3D GDR for full volumetric 4DCT correction.
- The mode distinction is architectural, not just a flag: there are separate binaries and separate parameter templates.
6. Input data flow
- The pipeline consumes a set of phase images from a respiratory cycle, e.g. 0EX, 20IN, 40IN, 60IN, 80IN, 100IN.
- For each phase, corresponding lung masks are provided.
- For some phases, additional artifact masks are provided to exclude corrupted regions from the regression.
7. Core algorithmic flow
- The algorithm uses the masks to remove artifact regions from the fitting process.
- It then performs geodesic density regression to estimate an artifact-free template and associated deformation across breathing phases.
- Conceptually, the main data flow is:
- load phase images + masks
- apply artifact exclusion
- compute density-based regression/deformation
- generate corrected images and deformation-related outputs
8. Outputs produced
- The README states that output is written under an output directory.
- Expected outputs include:
- artifact-free CT images
- Jacobian images
- displacement fields for the breathing phases
- This suggests the tool is both an image-correction and deformation-estimation pipeline.
9. Parameter-file driven orchestration
- The parameter files are the main external control surface for the executables.
- They likely encode file paths, phase selection, image/mask references, and algorithm settings.
- param_explanation.txt is the schema/documentation boundary for those inputs, which is useful when drawing the architecture diagram because the executable behavior is driven almost entirely by configuration.
10. Sample dataset as an integration test boundary
- code/data acts as a bundled regression test fixture rather than application state.
- The provided 2D example demonstrates correction of a synthetic duplication artifact in 40IN.nii.gz.
- This makes the repository self-contained for validation: build the executables, point to the sample params, and verify outputs.
11. External technology and environment constraints
- The repository is CPU-oriented and the README recommends substantial memory and many cores, indicating a compute-heavy offline workflow.
- It has been tested on macOS, Linux Mint, and an HPC environment, so the deployment model is portable batch execution rather than interactive use.
12. How to diagram the architecture
- Draw a simple pipeline:
- user + parameter file
- GDR2D or GDR3D
- ITK-based image loading/processing
- mask-aware regression/deformation computation
- output directory with corrected images, Jacobians, and displacement fields
- Treat the sample NIfTI images and masks in code/data as input assets, and the code directory as the build/runtime boundary for the executables.
Main entry points: GDR2D.cxx GDR2D · GDR3D.cxx GDR3D · CMakeLists.txt CMake · param_explanation.txt Param guide
Components 19
Build & runtime
CMake build and executable boundary
Configuration
Parameter files and their documentation
- 2D params · Parameter template for the 2D job
code/param2D.txt - 3D params · Parameter template for the 3D job
code/param3D.txt - Param guide · Explains the runtime parameter contract
code/param_explanation.txt
Sample data
Bundled 4DCT inputs and masks
- 0EX phase · Example phase image input
code/data/0EX.nii.gz - 20IN phase · Example phase image input
code/data/20IN.nii.gz - 40IN phase · Example phase image input
code/data/40IN.nii.gz - 60IN phase · Example phase image input
code/data/60IN.nii.gz - 80IN phase · Example phase image input
code/data/80IN.nii.gz - 100IN phase · Example phase image input
code/data/100IN.nii.gz - Lung masks · Phase-aligned lung masks used during fitting
code/data/0EX.lung.mask.nii.gz - Artifact masks · Corrupted-region masks excluded from regression
code/data/artifactMask_0EX.nii.gz
Outputs
Results produced by the regressors
- Output dir · Artifact-free images and deformation outputs
- Corrected CT · Artifact-free CT reconstructions
- Jacobian maps · Deformation magnitude summaries
- Displacement fields · Breathing-phase motion fields
Connections 23
- CMake → GDR2D: builds · Creates the 2D executable
- CMake → GDR3D: builds · Creates the 3D executable
- 2D params → GDR2D: drives · Supplies paths and algorithm settings
- 3D params → GDR3D: drives · Supplies paths and algorithm settings
- Param guide → 2D params: documents · Explains 2D parameter contract
- Param guide → 3D params: documents · Explains 3D parameter contract
- 0EX phase → GDR2D: input · Phase image consumed by the 2D run
- 20IN phase → GDR2D: input · Phase image consumed by the 2D run
- 40IN phase → GDR2D: input · Phase image consumed by the 2D run
- 60IN phase → GDR3D: input · Phase image consumed by the 3D run
- 80IN phase → GDR3D: input · Phase image consumed by the 3D run
- 100IN phase → GDR3D: input · Phase image consumed by the 3D run
- Lung masks → GDR2D: constraint · Lung-region fitting support
- Lung masks → GDR3D: constraint · Lung-region fitting support
- Artifact masks → GDR2D: exclude · Removes corrupted regions from fitting
- Artifact masks → GDR3D: exclude · Removes corrupted regions from fitting
- ITK → GDR2D: depends on · Image processing and I/O backend
- ITK → GDR3D: depends on · Image processing and I/O backend
- GDR2D → Output dir: writes · Places outputs under the output directory
- GDR3D → Output dir: writes · Places outputs under the output directory
- Output dir → Corrected CT: contains · Artifact-free CT images
- Output dir → Jacobian maps: contains · Jacobian images
- Output dir → Displacement fields: contains · Displacement fields