# menzelab/implicit-shape-reconstruction architecture

> Architecture diagram of the GitHub repository menzelab/implicit-shape-reconstruction, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/menzelab/implicit-shape-reconstruction
- Repository: https://github.com/menzelab/implicit-shape-reconstruction

## Overview

This repository implements sparse-input 3D shape reconstruction for medical segmentation volumes, with two model choices: an implicit AutoDecoder (AD) and ReconNet (RN). The principal workflow loads configured cases, sparsifies training data, learns a model, then reconstructs dense volumes from sparse inference inputs and optionally evaluates/exports them. Separate vertebra extraction preprocessing and the adapted surface-distance metric package are supporting product capabilities. The graph follows documented workflows and sampled entry points; some internal wiring is inferred only where README or entry-point behavior supports it.

Main entry points: [`impl_recon/eval.py`](https://github.com/menzelab/implicit-shape-reconstruction/blob/main/impl_recon/eval.py) (Inference runner), [`impl_recon/train.py`](https://github.com/menzelab/implicit-shape-reconstruction/blob/main/impl_recon/train.py) (Training runner), [`impl_recon/utils/io_utils.py`](https://github.com/menzelab/implicit-shape-reconstruction/blob/main/impl_recon/utils/io_utils.py) (Volume and checkpoint I/O), [`impl_recon/utils/data_generation.py`](https://github.com/menzelab/implicit-shape-reconstruction/blob/main/impl_recon/utils/data_generation.py) (Sparse datasets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_case_splits["Case splits"]
  node_vertebra_prep["Vertebra extraction"]
  node_data_gen["Sparse datasets<br/>[data_generation.py]"]
end

subgraph group_learning["Model training"]
  node_train_config["Training settings"]
  node_config["Config loading<br/>[config_io.py]"]
  node_io["Volume and checkpoint I/O<br/>[io_utils.py]"]
  node_trainer["Training runner<br/>[train.py]"]
  node_models["AD and ReconNet<br/>[implicits.py]"]
end

subgraph group_reconstruction["Inference and evaluation"]
  node_eval_config["Inference settings"]
  node_evaluator["Inference runner<br/>[eval.py]"]
  node_implicit_utils["Implicit sampling<br/>[impl_utils.py]"]
  node_patches["Patch inference<br/>[patch_utils.py]"]
end

subgraph group_support["Geometry and metrics"]
  node_geometry["Sampling geometry<br/>[geometry_utils.py]"]
  node_metrics["Surface metrics<br/>[metrics.py]"]
  node_lookup["Surface lookup tables<br/>[lookup_tables.py]"]
end

node_researcher(("Researcher"))
node_nifti["NIfTI labels"]
node_model_store[("Model checkpoints")]
node_predictions["Reconstructed volumes"]

node_researcher -->|"preprocesses"| node_vertebra_prep
node_nifti -->|"reads labels"| node_vertebra_prep
node_researcher -->|"starts training"| node_trainer
node_train_config -->|"configures"| node_config
node_case_splits -->|"selects cases"| node_data_gen
node_nifti -->|"loads volumes"| node_data_gen
node_trainer -->|"parses settings"| node_config
node_trainer -->|"creates loaders"| node_data_gen
node_trainer -->|"creates model"| node_models
node_trainer -->|"writes checkpoints"| node_io
node_io -->|"stores state"| node_model_store
node_researcher -->|"starts inference"| node_evaluator
node_eval_config -->|"configures"| node_config
node_evaluator -->|"parses settings"| node_config
node_evaluator -->|"creates loader"| node_data_gen
node_evaluator -->|"loads checkpoint"| node_io
node_model_store -->|"provides state"| node_io
node_evaluator -->|"creates model"| node_models
node_evaluator -->|"samples AD"| node_implicit_utils
node_implicit_utils -->|"generates coordinates"| node_geometry
node_evaluator -->|"runs RN patches"| node_patches
node_evaluator -->|"evaluates masks"| node_metrics
node_metrics -->|"uses tables"| node_lookup
node_evaluator -->|"exports volumes"| node_predictions

click node_train_config "https://github.com/menzelab/implicit-shape-reconstruction/tree/main/config_files/training"
click node_eval_config "https://github.com/menzelab/implicit-shape-reconstruction/tree/main/config_files/inference"
click node_case_splits "https://github.com/menzelab/implicit-shape-reconstruction/tree/main/casename_files"
click node_vertebra_prep "https://github.com/menzelab/implicit-shape-reconstruction/blob/main/preprocessing/extract_vertebra.py"
click node_config "https://github.com/menzelab/implicit-shape-reconstruction/blob/main/impl_recon/utils/config_io.py"
click node_data_gen "https://github.com/menzelab/implicit-shape-reconstruction/blob/main/impl_recon/utils/data_generation.py"
click node_io "https://github.com/menzelab/implicit-shape-reconstruction/blob/main/impl_recon/utils/io_utils.py"
click node_trainer "https://github.com/menzelab/implicit-shape-reconstruction/blob/main/impl_recon/train.py"
click node_models "https://github.com/menzelab/implicit-shape-reconstruction/blob/main/impl_recon/models/implicits.py"
click node_evaluator "https://github.com/menzelab/implicit-shape-reconstruction/blob/main/impl_recon/eval.py"
click node_implicit_utils "https://github.com/menzelab/implicit-shape-reconstruction/blob/main/impl_recon/utils/impl_utils.py"
click node_geometry "https://github.com/menzelab/implicit-shape-reconstruction/blob/main/impl_recon/utils/geometry_utils.py"
click node_patches "https://github.com/menzelab/implicit-shape-reconstruction/blob/main/impl_recon/utils/patch_utils.py"
click node_metrics "https://github.com/menzelab/implicit-shape-reconstruction/blob/main/surface_distance/metrics.py"
click node_lookup "https://github.com/menzelab/implicit-shape-reconstruction/blob/main/surface_distance/lookup_tables.py"

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_case_splits,node_vertebra_prep,node_data_gen toneBlue
class node_train_config,node_config,node_io,node_trainer,node_models,node_model_store toneAmber
class node_eval_config,node_evaluator,node_implicit_utils,node_patches toneMint
class node_geometry,node_metrics,node_lookup toneRose
class node_researcher,node_nifti,node_predictions toneIndigo
```

## Components

### Data preparation

- [Case splits](https://github.com/menzelab/implicit-shape-reconstruction/tree/main/casename_files): `casename_files`
- [Vertebra extraction](https://github.com/menzelab/implicit-shape-reconstruction/blob/main/preprocessing/extract_vertebra.py): `preprocessing/extract_vertebra.py`
- [Sparse datasets](https://github.com/menzelab/implicit-shape-reconstruction/blob/main/impl_recon/utils/data_generation.py): `impl_recon/utils/data_generation.py`

### Model training

- [Training settings](https://github.com/menzelab/implicit-shape-reconstruction/tree/main/config_files/training): `config_files/training`
- [Config loading](https://github.com/menzelab/implicit-shape-reconstruction/blob/main/impl_recon/utils/config_io.py): `impl_recon/utils/config_io.py`
- [Volume and checkpoint I/O](https://github.com/menzelab/implicit-shape-reconstruction/blob/main/impl_recon/utils/io_utils.py): `impl_recon/utils/io_utils.py`
- [Training runner](https://github.com/menzelab/implicit-shape-reconstruction/blob/main/impl_recon/train.py): `impl_recon/train.py`
- [AD and ReconNet](https://github.com/menzelab/implicit-shape-reconstruction/blob/main/impl_recon/models/implicits.py): `impl_recon/models/implicits.py`

### Inference and evaluation

- [Inference settings](https://github.com/menzelab/implicit-shape-reconstruction/tree/main/config_files/inference): `config_files/inference`
- [Inference runner](https://github.com/menzelab/implicit-shape-reconstruction/blob/main/impl_recon/eval.py): `impl_recon/eval.py`
- [Implicit sampling](https://github.com/menzelab/implicit-shape-reconstruction/blob/main/impl_recon/utils/impl_utils.py): `impl_recon/utils/impl_utils.py`
- [Patch inference](https://github.com/menzelab/implicit-shape-reconstruction/blob/main/impl_recon/utils/patch_utils.py): `impl_recon/utils/patch_utils.py`

### Geometry and metrics

- [Sampling geometry](https://github.com/menzelab/implicit-shape-reconstruction/blob/main/impl_recon/utils/geometry_utils.py): `impl_recon/utils/geometry_utils.py`
- [Surface metrics](https://github.com/menzelab/implicit-shape-reconstruction/blob/main/surface_distance/metrics.py): `surface_distance/metrics.py`
- [Surface lookup tables](https://github.com/menzelab/implicit-shape-reconstruction/blob/main/surface_distance/lookup_tables.py): `surface_distance/lookup_tables.py`

### Other components

- **Researcher**
- **NIfTI labels**
- **Model checkpoints**
- **Reconstructed volumes**

## Connections

- Researcher → Vertebra extraction: preprocesses
- NIfTI labels → Vertebra extraction: reads labels
- Researcher → Training runner: starts training
- Training settings → Config loading: configures
- Case splits → Sparse datasets: selects cases
- NIfTI labels → Sparse datasets: loads volumes
- Training runner → Config loading: parses settings
- Training runner → Sparse datasets: creates loaders
- Training runner → AD and ReconNet: creates model
- Training runner → Volume and checkpoint I/O: writes checkpoints
- Volume and checkpoint I/O → Model checkpoints: stores state
- Researcher → Inference runner: starts inference
- Inference settings → Config loading: configures
- Inference runner → Config loading: parses settings
- Inference runner → Sparse datasets: creates loader
- Inference runner → Volume and checkpoint I/O: loads checkpoint
- Model checkpoints → Volume and checkpoint I/O: provides state
- Inference runner → AD and ReconNet: creates model
- Inference runner → Implicit sampling: samples AD
- Implicit sampling → Sampling geometry: generates coordinates
- Inference runner → Patch inference: runs RN patches
- Inference runner → Surface metrics: evaluates masks
- Surface metrics → Surface lookup tables: uses tables
- Inference runner → Reconstructed volumes: exports volumes