# wei-shao-reg/gdr architecture

> Architecture diagram of the GitHub repository wei-shao-reg/gdr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wei-shao-reg/gdr
- Repository: https://github.com/wei-shao-reg/gdr

## Overview

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: [`code/GDR2D.cxx`](https://github.com/wei-shao-reg/gdr/blob/main/code/GDR2D.cxx) (GDR2D), [`code/GDR3D.cxx`](https://github.com/wei-shao-reg/gdr/blob/main/code/GDR3D.cxx) (GDR3D), [`code/CMakeLists.txt`](https://github.com/wei-shao-reg/gdr/blob/main/code/CMakeLists.txt) (CMake), [`code/param_explanation.txt`](https://github.com/wei-shao-reg/gdr/blob/main/code/param_explanation.txt) (Param guide)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build & runtime"]
  node_cmake["CMake<br/>build config<br/>[CMakeLists.txt]"]
  node_gdr2d["GDR2D<br/>cli executable<br/>[GDR2D.cxx]"]
  node_gdr3d["GDR3D<br/>cli executable<br/>[GDR3D.cxx]"]
  node_itk(("ITK<br/>external imaging library"))
end

subgraph group_config["Configuration"]
  node_param2d["2D params<br/>runtime config<br/>[param2D.txt]"]
  node_param3d["3D params<br/>runtime config<br/>[param3D.txt]"]
  node_paramdoc["Param guide<br/>config docs"]
end

subgraph group_data["Sample data"]
  node_phase0["0EX phase<br/>ct phase image<br/>[0EX.nii.gz]"]
  node_phase20["20IN phase<br/>ct phase image<br/>[20IN.nii.gz]"]
  node_phase40["40IN phase<br/>ct phase image<br/>[40IN.nii.gz]"]
  node_phase60["60IN phase<br/>ct phase image<br/>[60IN.nii.gz]"]
  node_phase80["80IN phase<br/>ct phase image<br/>[80IN.nii.gz]"]
  node_phase100["100IN phase<br/>ct phase image<br/>[100IN.nii.gz]"]
  node_masks["Lung masks<br/>segmentation masks"]
  node_artifact["Artifact masks<br/>exclusion masks"]
end

subgraph group_output["Outputs"]
  node_results[("Output dir<br/>result bundle")]
  node_corrected["Corrected CT<br/>derived images"]
  node_jacobian["Jacobian maps<br/>derived field"]
  node_dispfield["Displacement fields<br/>derived field"]
end

node_cmake -->|"builds"| node_gdr2d
node_cmake -->|"builds"| node_gdr3d
node_param2d -->|"drives"| node_gdr2d
node_param3d -->|"drives"| node_gdr3d
node_paramdoc -.->|"documents"| node_param2d
node_paramdoc -.->|"documents"| node_param3d
node_phase0 -->|"input"| node_gdr2d
node_phase20 -->|"input"| node_gdr2d
node_phase40 -->|"input"| node_gdr2d
node_phase60 -->|"input"| node_gdr3d
node_phase80 -->|"input"| node_gdr3d
node_phase100 -->|"input"| node_gdr3d
node_masks -->|"constraint"| node_gdr2d
node_masks -->|"constraint"| node_gdr3d
node_artifact -->|"exclude"| node_gdr2d
node_artifact -->|"exclude"| node_gdr3d
node_itk -.->|"depends on"| node_gdr2d
node_itk -.->|"depends on"| node_gdr3d
node_gdr2d -->|"writes"| node_results
node_gdr3d -->|"writes"| node_results
node_results -->|"contains"| node_corrected
node_results -->|"contains"| node_jacobian
node_results -->|"contains"| node_dispfield

click node_cmake "https://github.com/wei-shao-reg/gdr/blob/main/code/CMakeLists.txt"
click node_gdr2d "https://github.com/wei-shao-reg/gdr/blob/main/code/GDR2D.cxx"
click node_gdr3d "https://github.com/wei-shao-reg/gdr/blob/main/code/GDR3D.cxx"
click node_param2d "https://github.com/wei-shao-reg/gdr/blob/main/code/param2D.txt"
click node_param3d "https://github.com/wei-shao-reg/gdr/blob/main/code/param3D.txt"
click node_paramdoc "https://github.com/wei-shao-reg/gdr/blob/main/code/param_explanation.txt"
click node_phase0 "https://github.com/wei-shao-reg/gdr/blob/main/code/data/0EX.nii.gz"
click node_phase20 "https://github.com/wei-shao-reg/gdr/blob/main/code/data/20IN.nii.gz"
click node_phase40 "https://github.com/wei-shao-reg/gdr/blob/main/code/data/40IN.nii.gz"
click node_phase60 "https://github.com/wei-shao-reg/gdr/blob/main/code/data/60IN.nii.gz"
click node_phase80 "https://github.com/wei-shao-reg/gdr/blob/main/code/data/80IN.nii.gz"
click node_phase100 "https://github.com/wei-shao-reg/gdr/blob/main/code/data/100IN.nii.gz"
click node_masks "https://github.com/wei-shao-reg/gdr/blob/main/code/data/0EX.lung.mask.nii.gz"
click node_artifact "https://github.com/wei-shao-reg/gdr/blob/main/code/data/artifactMask_0EX.nii.gz"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmake,node_gdr2d,node_gdr3d,node_itk toneBlue
class node_param2d,node_param3d,node_paramdoc toneAmber
class node_phase0,node_phase20,node_phase40,node_phase60,node_phase80,node_phase100,node_masks,node_artifact toneMint
class node_results,node_corrected,node_jacobian,node_dispfield toneRose
```

## Components

### Build & runtime

CMake build and executable boundary

- [CMake](https://github.com/wei-shao-reg/gdr/blob/main/code/CMakeLists.txt): build config · Defines and links the executables · `code/CMakeLists.txt`
- [GDR2D](https://github.com/wei-shao-reg/gdr/blob/main/code/GDR2D.cxx): cli executable · 2D geodesic density regression runner · `code/GDR2D.cxx`
- [GDR3D](https://github.com/wei-shao-reg/gdr/blob/main/code/GDR3D.cxx): cli executable · 3D geodesic density regression runner · `code/GDR3D.cxx`
- **ITK**: external imaging library · Image I/O, image types, and processing foundation

### Configuration

Parameter files and their documentation

- [2D params](https://github.com/wei-shao-reg/gdr/blob/main/code/param2D.txt): runtime config · Parameter template for the 2D job · `code/param2D.txt`
- [3D params](https://github.com/wei-shao-reg/gdr/blob/main/code/param3D.txt): runtime config · Parameter template for the 3D job · `code/param3D.txt`
- [Param guide](https://github.com/wei-shao-reg/gdr/blob/main/code/param_explanation.txt): config docs · Explains the runtime parameter contract · `code/param_explanation.txt`

### Sample data

Bundled 4DCT inputs and masks

- [0EX phase](https://github.com/wei-shao-reg/gdr/blob/main/code/data/0EX.nii.gz): ct phase image · Example phase image input · `code/data/0EX.nii.gz`
- [20IN phase](https://github.com/wei-shao-reg/gdr/blob/main/code/data/20IN.nii.gz): ct phase image · Example phase image input · `code/data/20IN.nii.gz`
- [40IN phase](https://github.com/wei-shao-reg/gdr/blob/main/code/data/40IN.nii.gz): ct phase image · Example phase image input · `code/data/40IN.nii.gz`
- [60IN phase](https://github.com/wei-shao-reg/gdr/blob/main/code/data/60IN.nii.gz): ct phase image · Example phase image input · `code/data/60IN.nii.gz`
- [80IN phase](https://github.com/wei-shao-reg/gdr/blob/main/code/data/80IN.nii.gz): ct phase image · Example phase image input · `code/data/80IN.nii.gz`
- [100IN phase](https://github.com/wei-shao-reg/gdr/blob/main/code/data/100IN.nii.gz): ct phase image · Example phase image input · `code/data/100IN.nii.gz`
- [Lung masks](https://github.com/wei-shao-reg/gdr/blob/main/code/data/0EX.lung.mask.nii.gz): segmentation masks · Phase-aligned lung masks used during fitting · `code/data/0EX.lung.mask.nii.gz`
- [Artifact masks](https://github.com/wei-shao-reg/gdr/blob/main/code/data/artifactMask_0EX.nii.gz): exclusion masks · Corrupted-region masks excluded from regression · `code/data/artifactMask_0EX.nii.gz`

### Outputs

Results produced by the regressors

- **Output dir**: result bundle · Artifact-free images and deformation outputs
- **Corrected CT**: derived images · Artifact-free CT reconstructions
- **Jacobian maps**: derived field · Deformation magnitude summaries
- **Displacement fields**: derived field · Breathing-phase motion fields

## Connections

- 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