# tj12323/geopurify architecture

> Architecture diagram of the GitHub repository tj12323/geopurify, 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/tj12323/geopurify
- Repository: https://github.com/tj12323/geopurify

## Overview

GeoPurify is a training and inference framework for open-vocabulary 3D segmentation. Its workflow prepares RGB-D views and point clouds, trains a sparse 3D student to distill geometric affinities from a frozen 3D teacher, then uses those affinities to refine 2D VLM features lifted into 3D before evaluation. The README documents ScanNetV2, Matterport3D, and ScanNet200 support. Training, validation, loader, projection, and model excerpts support the shown runtime links; the README supplies the two-stage method and capability details where implementation excerpts are incomplete.

Main entry points: [`run/validation.py`](https://github.com/tj12323/geopurify/blob/main/run/validation.py) (Segmentation inference), [`models/affinity_module.py`](https://github.com/tj12323/geopurify/blob/main/models/affinity_module.py) (Affinity trainer and purifier), [`dataset/data_loader_ablation.py`](https://github.com/tj12323/geopurify/blob/main/dataset/data_loader_ablation.py) (ScanNet loader), [`dataset/data_loader_matterport.py`](https://github.com/tj12323/geopurify/blob/main/dataset/data_loader_matterport.py) (Matterport loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Data preparation"]
  node_preprocess["Dataset preprocessing"]
end

subgraph group_input["Scene inputs"]
  node_scanloader["ScanNet loader"]
  node_matterloader["Matterport loader"]
  node_scene["Camera and scene data<br/>[scene.py]"]
  node_projection["Point-image projection<br/>[fusion_util.py]"]
end

subgraph group_model["Geometric model"]
  node_model["Affinity trainer and purifier<br/>[affinity_module.py]"]
  node_affinity["Sparse affinity network<br/>[affinity_module.py]"]
end

subgraph group_runtime["Train and evaluate"]
  node_train["Geometric distillation<br/>[train.py]"]
  node_validation["Segmentation inference<br/>[validation.py]"]
  node_metrics["Segmentation metrics<br/>[util.py]"]
  node_visualization["Result visualization<br/>[visualization.py]"]
end

node_researcher(("Researcher"))
node_datasets[("RGB-D and point-cloud datasets")]
node_sslteacher["Frozen 3D SSL teacher"]
node_vlm["Frozen 2D VLM"]
node_results["Segmentation results"]

node_researcher -->|"starts training"| node_train
node_researcher -->|"runs inference"| node_validation
node_datasets -->|"provides source data"| node_preprocess
node_preprocess -->|"prepares scenes"| node_scanloader
node_preprocess -->|"prepares scenes"| node_matterloader
node_scanloader -->|"loads cameras"| node_scene
node_matterloader -->|"loads cameras"| node_scene
node_scanloader -->|"maps points to views"| node_projection
node_matterloader -->|"maps points to views"| node_projection
node_train -->|"constructs training data"| node_scanloader
node_train -->|"trains"| node_model
node_model -->|"learns affinities"| node_affinity
node_sslteacher -.->|"provides embeddings"| node_model
node_validation -->|"constructs evaluation data"| node_matterloader
node_validation -->|"runs inference"| node_model
node_vlm -.->|"provides 2D semantics"| node_model
node_model -->|"produces predictions"| node_results
node_validation -->|"computes scores"| node_metrics
node_validation -->|"renders results"| node_visualization
node_validation -->|"reports evaluation"| node_results

click node_preprocess "https://github.com/tj12323/geopurify/tree/main/dataset/scripts/preprocess"
click node_scanloader "https://github.com/tj12323/geopurify/blob/main/dataset/data_loader_ablation.py"
click node_matterloader "https://github.com/tj12323/geopurify/blob/main/dataset/data_loader_matterport.py"
click node_scene "https://github.com/tj12323/geopurify/blob/main/models/scene/scene.py"
click node_projection "https://github.com/tj12323/geopurify/blob/main/models/utils/fusion_util.py"
click node_model "https://github.com/tj12323/geopurify/blob/main/models/affinity_module.py"
click node_affinity "https://github.com/tj12323/geopurify/blob/main/models/affinity_module.py"
click node_train "https://github.com/tj12323/geopurify/blob/main/run/train.py"
click node_validation "https://github.com/tj12323/geopurify/blob/main/run/validation.py"
click node_metrics "https://github.com/tj12323/geopurify/blob/main/util/util.py"
click node_visualization "https://github.com/tj12323/geopurify/blob/main/models/utils/visualization.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_preprocess toneBlue
class node_scanloader,node_matterloader,node_scene,node_projection,node_datasets toneAmber
class node_model,node_affinity toneMint
class node_train,node_validation,node_metrics,node_visualization toneRose
class node_researcher,node_sslteacher,node_vlm,node_results toneIndigo
```

## Components

### Data preparation

- [Dataset preprocessing](https://github.com/tj12323/geopurify/tree/main/dataset/scripts/preprocess): `dataset/scripts/preprocess`

### Scene inputs

- [ScanNet loader](https://github.com/tj12323/geopurify/blob/main/dataset/data_loader_ablation.py): `dataset/data_loader_ablation.py`
- [Matterport loader](https://github.com/tj12323/geopurify/blob/main/dataset/data_loader_matterport.py): `dataset/data_loader_matterport.py`
- [Camera and scene data](https://github.com/tj12323/geopurify/blob/main/models/scene/scene.py): `models/scene/scene.py`
- [Point-image projection](https://github.com/tj12323/geopurify/blob/main/models/utils/fusion_util.py): `models/utils/fusion_util.py`

### Geometric model

- [Affinity trainer and purifier](https://github.com/tj12323/geopurify/blob/main/models/affinity_module.py): `models/affinity_module.py`
- [Sparse affinity network](https://github.com/tj12323/geopurify/blob/main/models/affinity_module.py): `models/affinity_module.py`

### Train and evaluate

- [Geometric distillation](https://github.com/tj12323/geopurify/blob/main/run/train.py): `run/train.py`
- [Segmentation inference](https://github.com/tj12323/geopurify/blob/main/run/validation.py): `run/validation.py`
- [Segmentation metrics](https://github.com/tj12323/geopurify/blob/main/util/util.py): `util/util.py`
- [Result visualization](https://github.com/tj12323/geopurify/blob/main/models/utils/visualization.py): `models/utils/visualization.py`

### Other components

- **Researcher**
- **RGB-D and point-cloud datasets**
- **Frozen 3D SSL teacher**
- **Frozen 2D VLM**
- **Segmentation results**

## Connections

- Researcher → Geometric distillation: starts training
- Researcher → Segmentation inference: runs inference
- RGB-D and point-cloud datasets → Dataset preprocessing: provides source data
- Dataset preprocessing → ScanNet loader: prepares scenes
- Dataset preprocessing → Matterport loader: prepares scenes
- ScanNet loader → Camera and scene data: loads cameras
- Matterport loader → Camera and scene data: loads cameras
- ScanNet loader → Point-image projection: maps points to views
- Matterport loader → Point-image projection: maps points to views
- Geometric distillation → ScanNet loader: constructs training data
- Geometric distillation → Affinity trainer and purifier: trains
- Affinity trainer and purifier → Sparse affinity network: learns affinities
- Frozen 3D SSL teacher → Affinity trainer and purifier: provides embeddings
- Segmentation inference → Matterport loader: constructs evaluation data
- Segmentation inference → Affinity trainer and purifier: runs inference
- Frozen 2D VLM → Affinity trainer and purifier: provides 2D semantics
- Affinity trainer and purifier → Segmentation results: produces predictions
- Segmentation inference → Segmentation metrics: computes scores
- Segmentation inference → Result visualization: renders results
- Segmentation inference → Segmentation results: reports evaluation