# cdttk/biv-volumetric-meshing architecture

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

- Interactive diagram: https://gitdiagram.com/cdttk/biv-volumetric-meshing
- Repository: https://github.com/cdttk/biv-volumetric-meshing

## Overview

This repository builds finite-element biventricular heart models from UK Biobank CMR, with `src/run.py` dispatching selectable pipeline stages. The principal workflow is NIfTI images → segmentation → contour extraction → fitted surface meshes → volumetric meshes, followed by optional universal ventricular coordinates (UVC) and fiber generation. Surface fitting uses contour datasets and a biventricular model; the repository also includes model-based mass and volume measurement. The README documents the stage sequence, while sampled source confirms dispatch and portions of segmentation, fitting, and volumetric processing; unsampled stage internals are represented only at their documented boundaries.

Main entry points: [`src/run.py`](https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/run.py) (Stage runner), [`src/surface/perform_fit.py`](https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/surface/perform_fit.py) (Surface fitting), [`src/segmentation/predict_UKBB.py`](https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/segmentation/predict_UKBB.py) (nnUNet prediction), [`src/volumetric/main_testvmesh.py`](https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/volumetric/main_testvmesh.py) (Volumetric meshing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Pipeline dispatch"]
  node_runner["Stage runner<br/>[run.py]"]
end

subgraph group_segmentation["Image segmentation"]
  node_segment["nnUNet prediction<br/>[predict_UKBB.py]"]
end

subgraph group_surface["Contour and surface"]
  node_contours["Contour extraction<br/>[contour2gp_QS.py]"]
  node_fit["Surface fitting<br/>[perform_fit.py]"]
  node_dataset["Contour dataset<br/>[GPDataSet.py]"]
  node_bivmodel["Biventricular model"]
  node_meshconvert["Mesh conversion<br/>[mesh_txt_to_vtk.py]"]
end

subgraph group_volumetric["Volumetric modeling"]
  node_volmesh["Volumetric meshing<br/>[main_testvmesh.py]"]
  node_meshgen["Mesh generation"]
  node_uvcfiber["UVC and fibers"]
end

subgraph group_analysis["Model analysis"]
  node_massvolume["Mass and volume<br/>[Mass_volume.py]"]
  node_meshdata["Mesh utilities<br/>[mesh.py]"]
end

node_user(("Pipeline user"))
node_images["CMR NIfTI inputs"]
node_nnunet["nnUNet models"]
node_carp["openCARP tools"]

node_user -->|"selects stages"| node_runner
node_images -->|"provides images"| node_segment
node_runner -->|"dispatches"| node_segment
node_segment -->|"runs prediction"| node_nnunet
node_runner -->|"dispatches"| node_contours
node_segment -->|"provides segmentations"| node_contours
node_runner -->|"dispatches"| node_fit
node_contours -->|"provides contours"| node_fit
node_fit -->|"constructs dataset"| node_dataset
node_fit -->|"fits model"| node_bivmodel
node_runner -->|"dispatches"| node_meshconvert
node_runner -->|"dispatches"| node_volmesh
node_meshconvert -->|"provides surface mesh"| node_volmesh
node_volmesh -->|"generates mesh"| node_meshgen
node_meshgen -->|"invokes tools"| node_carp
node_runner -->|"dispatches"| node_uvcfiber
node_uvcfiber -->|"invokes tools"| node_carp
node_volmesh -->|"provides volumetric mesh"| node_uvcfiber
node_fit -.->|"provides fitted model"| node_massvolume
node_massvolume -->|"uses mesh operations"| node_meshdata

click node_runner "https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/run.py"
click node_segment "https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/segmentation/predict_UKBB.py"
click node_contours "https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/surface/contour2gp_QS.py"
click node_fit "https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/surface/perform_fit.py"
click node_dataset "https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/surface/BiVFitting/GPDataSet.py"
click node_bivmodel "https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/surface/BiVFitting/BiventricularModel.py"
click node_meshconvert "https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/surface/mesh_txt_to_vtk.py"
click node_volmesh "https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/volumetric/main_testvmesh.py"
click node_meshgen "https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/volumetric/v_mesh_generation.py"
click node_uvcfiber "https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/volumetric/compute_UVC_fiber.py"
click node_massvolume "https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/surface/mass_volume/Mass_volume.py"
click node_meshdata "https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/surface/mass_volume/mesh.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_runner,node_user toneBlue
class node_segment toneAmber
class node_contours,node_fit,node_dataset,node_bivmodel,node_meshconvert toneMint
class node_volmesh,node_meshgen,node_uvcfiber toneRose
class node_massvolume,node_meshdata,node_images,node_nnunet,node_carp toneIndigo
```

## Components

### Pipeline dispatch

- [Stage runner](https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/run.py): `src/run.py`

### Image segmentation

- [nnUNet prediction](https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/segmentation/predict_UKBB.py): `src/segmentation/predict_UKBB.py`

### Contour and surface

- [Contour extraction](https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/surface/contour2gp_QS.py): `src/surface/contour2gp_QS.py`
- [Surface fitting](https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/surface/perform_fit.py): `src/surface/perform_fit.py`
- [Contour dataset](https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/surface/BiVFitting/GPDataSet.py): `src/surface/BiVFitting/GPDataSet.py`
- [Biventricular model](https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/surface/BiVFitting/BiventricularModel.py): `src/surface/BiVFitting/BiventricularModel.py`
- [Mesh conversion](https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/surface/mesh_txt_to_vtk.py): `src/surface/mesh_txt_to_vtk.py`

### Volumetric modeling

- [Volumetric meshing](https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/volumetric/main_testvmesh.py): `src/volumetric/main_testvmesh.py`
- [Mesh generation](https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/volumetric/v_mesh_generation.py): `src/volumetric/v_mesh_generation.py`
- [UVC and fibers](https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/volumetric/compute_UVC_fiber.py): `src/volumetric/compute_UVC_fiber.py`

### Model analysis

- [Mass and volume](https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/surface/mass_volume/Mass_volume.py): `src/surface/mass_volume/Mass_volume.py`
- [Mesh utilities](https://github.com/cdttk/biv-volumetric-meshing/blob/main/src/surface/mass_volume/mesh.py): `src/surface/mass_volume/mesh.py`

### Other components

- **Pipeline user**
- **CMR NIfTI inputs**
- **nnUNet models**
- **openCARP tools**

## Connections

- Pipeline user → Stage runner: selects stages
- CMR NIfTI inputs → nnUNet prediction: provides images
- Stage runner → nnUNet prediction: dispatches
- nnUNet prediction → nnUNet models: runs prediction
- Stage runner → Contour extraction: dispatches
- nnUNet prediction → Contour extraction: provides segmentations
- Stage runner → Surface fitting: dispatches
- Contour extraction → Surface fitting: provides contours
- Surface fitting → Contour dataset: constructs dataset
- Surface fitting → Biventricular model: fits model
- Stage runner → Mesh conversion: dispatches
- Stage runner → Volumetric meshing: dispatches
- Mesh conversion → Volumetric meshing: provides surface mesh
- Volumetric meshing → Mesh generation: generates mesh
- Mesh generation → openCARP tools: invokes tools
- Stage runner → UVC and fibers: dispatches
- UVC and fibers → openCARP tools: invokes tools
- Volumetric meshing → UVC and fibers: provides volumetric mesh
- Surface fitting → Mass and volume: provides fitted model
- Mass and volume → Mesh utilities: uses mesh operations