# njuvision/sparsepcgc architecture

> Architecture diagram of the GitHub repository njuvision/sparsepcgc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/njuvision/sparsepcgc
- Repository: https://github.com/njuvision/sparsepcgc

## Overview

SparsePCGC is a learned point-cloud geometry compression system. Its user-facing workflow prepares voxelized sparse point clouds, estimates occupancy through a multiscale neural model, and supports dense and sparse LiDAR evaluation in lossless and lossy modes; offset prediction and G-PCC comparisons extend the workflow. Training is a separate path that feeds point-cloud data to the model and records checkpoints and metrics. The README documents the test modes and capabilities; source-index references support the internal links shown, while links from test entry points to model components are left out because those files were not sampled.

Main entry points: [`models/model.py`](https://github.com/njuvision/sparsepcgc/blob/main/models/model.py) (Multiscale PCC model), [`data_utils/data_loader.py`](https://github.com/njuvision/sparsepcgc/blob/main/data_utils/data_loader.py) (Sparse data loader), [`models/autoencoder.py`](https://github.com/njuvision/sparsepcgc/blob/main/models/autoencoder.py) (Sparse autoencoder), [`train/train.py`](https://github.com/njuvision/sparsepcgc/blob/main/train/train.py) (Training entry point)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Point-cloud preparation"]
  node_loader["Sparse data loader<br/>[data_loader.py]"]
  node_dataset["Point-cloud datasets<br/>[dataset.py]"]
  node_io["Point-cloud I/O<br/>[inout.py]"]
  node_quant["Voxel quantization<br/>[quantize.py]"]
  node_partition["Spatial partitioning<br/>[partition.py]"]
  node_sparse["Sparse tensor ops<br/>[sparse_tensor.py]"]
end

subgraph group_models["Learned compression"]
  node_pccmodel["Multiscale PCC model<br/>[model.py]"]
  node_autoencoder["Sparse autoencoder<br/>[autoencoder.py]"]
  node_decoder["Occupancy decoder<br/>[decoder.py]"]
  node_entropy["Entropy model<br/>[entropy_model.py]"]
  node_resnet["Sparse residual blocks<br/>[resnet.py]"]
  node_offset["Offset prediction<br/>[model_offset.py]"]
end

subgraph group_runtime["Training and inference"]
  node_tests["Test entry points"]
  node_train["Training entry point<br/>[train.py]"]
  node_trainer["Training lifecycle<br/>[trainer_base.py]"]
end

subgraph group_evaluation["Codec evaluation"]
  node_metrics["Point-cloud metrics<br/>[metrics.py]"]
  node_tools["G-PCC and distortion tools<br/>[tools.py]"]
  node_gpcc["G-PCC wrapper<br/>[gpcc.py]"]
end

node_user(("Researcher"))
node_clouds["Point-cloud files"]

node_user -->|"runs tests"| node_tests
node_user -->|"starts training"| node_train
node_clouds -->|"loads coordinates"| node_loader
node_clouds -.->|"supplies samples"| node_dataset
node_loader -->|"reads files"| node_io
node_loader -->|"quantizes points"| node_quant
node_loader -->|"partitions points"| node_partition
node_dataset -->|"reads files"| node_io
node_dataset -->|"quantizes points"| node_quant
node_dataset -->|"partitions points"| node_partition
node_pccmodel -->|"loads sparse input"| node_loader
node_pccmodel -->|"quantizes scales"| node_quant
node_pccmodel -->|"writes output"| node_io
node_pccmodel -->|"measures distortion"| node_metrics
node_pccmodel -->|"selects encoder"| node_autoencoder
node_pccmodel -->|"selects decoder"| node_decoder
node_autoencoder -->|"uses blocks"| node_resnet
node_autoencoder -->|"uses coding model"| node_entropy
node_autoencoder -->|"uses decoder"| node_decoder
node_autoencoder -->|"uses tensor ops"| node_sparse
node_decoder -->|"uses blocks"| node_resnet
node_decoder -->|"uses tensor ops"| node_sparse
node_train -->|"loads batches"| node_loader
node_train -->|"trains model"| node_pccmodel
node_train -->|"extends trainer"| node_trainer
node_train -->|"builds sparse input"| node_sparse
node_offset -->|"uses blocks"| node_resnet
node_offset -->|"uses codec tools"| node_tools
node_offset -->|"quantizes coordinates"| node_quant
node_offset -->|"loads input"| node_loader
node_tests -.->|"runs compression"| node_pccmodel
node_tests -.->|"runs offset mode"| node_offset
node_tools -.->|"invokes wrapper"| node_gpcc

click node_tests "https://github.com/njuvision/sparsepcgc/tree/main/test"
click node_loader "https://github.com/njuvision/sparsepcgc/blob/main/data_utils/data_loader.py"
click node_dataset "https://github.com/njuvision/sparsepcgc/blob/main/data_utils/dataset.py"
click node_io "https://github.com/njuvision/sparsepcgc/blob/main/data_utils/inout.py"
click node_quant "https://github.com/njuvision/sparsepcgc/blob/main/data_utils/quantize.py"
click node_partition "https://github.com/njuvision/sparsepcgc/blob/main/data_utils/partition.py"
click node_sparse "https://github.com/njuvision/sparsepcgc/blob/main/data_utils/sparse_tensor.py"
click node_pccmodel "https://github.com/njuvision/sparsepcgc/blob/main/models/model.py"
click node_autoencoder "https://github.com/njuvision/sparsepcgc/blob/main/models/autoencoder.py"
click node_decoder "https://github.com/njuvision/sparsepcgc/blob/main/models/decoder.py"
click node_entropy "https://github.com/njuvision/sparsepcgc/blob/main/models/entropy_model.py"
click node_resnet "https://github.com/njuvision/sparsepcgc/blob/main/models/resnet.py"
click node_offset "https://github.com/njuvision/sparsepcgc/blob/main/models/model_offset.py"
click node_train "https://github.com/njuvision/sparsepcgc/blob/main/train/train.py"
click node_trainer "https://github.com/njuvision/sparsepcgc/blob/main/train/trainer_base.py"
click node_metrics "https://github.com/njuvision/sparsepcgc/blob/main/extension/metrics.py"
click node_tools "https://github.com/njuvision/sparsepcgc/blob/main/extension/tools.py"
click node_gpcc "https://github.com/njuvision/sparsepcgc/blob/main/extension/gpcc.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_loader,node_dataset,node_io,node_quant,node_partition,node_sparse toneBlue
class node_pccmodel,node_autoencoder,node_decoder,node_entropy,node_resnet,node_offset toneAmber
class node_tests,node_train,node_trainer toneMint
class node_metrics,node_tools,node_gpcc toneRose
class node_user,node_clouds toneIndigo
```

## Components

### Point-cloud preparation

- [Sparse data loader](https://github.com/njuvision/sparsepcgc/blob/main/data_utils/data_loader.py): `data_utils/data_loader.py`
- [Point-cloud datasets](https://github.com/njuvision/sparsepcgc/blob/main/data_utils/dataset.py): `data_utils/dataset.py`
- [Point-cloud I/O](https://github.com/njuvision/sparsepcgc/blob/main/data_utils/inout.py): `data_utils/inout.py`
- [Voxel quantization](https://github.com/njuvision/sparsepcgc/blob/main/data_utils/quantize.py): `data_utils/quantize.py`
- [Spatial partitioning](https://github.com/njuvision/sparsepcgc/blob/main/data_utils/partition.py): `data_utils/partition.py`
- [Sparse tensor ops](https://github.com/njuvision/sparsepcgc/blob/main/data_utils/sparse_tensor.py): `data_utils/sparse_tensor.py`

### Learned compression

- [Multiscale PCC model](https://github.com/njuvision/sparsepcgc/blob/main/models/model.py): `models/model.py`
- [Sparse autoencoder](https://github.com/njuvision/sparsepcgc/blob/main/models/autoencoder.py): `models/autoencoder.py`
- [Occupancy decoder](https://github.com/njuvision/sparsepcgc/blob/main/models/decoder.py): `models/decoder.py`
- [Entropy model](https://github.com/njuvision/sparsepcgc/blob/main/models/entropy_model.py): `models/entropy_model.py`
- [Sparse residual blocks](https://github.com/njuvision/sparsepcgc/blob/main/models/resnet.py): `models/resnet.py`
- [Offset prediction](https://github.com/njuvision/sparsepcgc/blob/main/models/model_offset.py): `models/model_offset.py`

### Training and inference

- [Test entry points](https://github.com/njuvision/sparsepcgc/tree/main/test): `test`
- [Training entry point](https://github.com/njuvision/sparsepcgc/blob/main/train/train.py): `train/train.py`
- [Training lifecycle](https://github.com/njuvision/sparsepcgc/blob/main/train/trainer_base.py): `train/trainer_base.py`

### Codec evaluation

- [Point-cloud metrics](https://github.com/njuvision/sparsepcgc/blob/main/extension/metrics.py): `extension/metrics.py`
- [G-PCC and distortion tools](https://github.com/njuvision/sparsepcgc/blob/main/extension/tools.py): `extension/tools.py`
- [G-PCC wrapper](https://github.com/njuvision/sparsepcgc/blob/main/extension/gpcc.py): `extension/gpcc.py`

### Other components

- **Researcher**
- **Point-cloud files**

## Connections

- Researcher → Test entry points: runs tests (evidence: `README.md`)
- Researcher → Training entry point: starts training (evidence: `README.md`)
- Point-cloud files → Sparse data loader: loads coordinates (evidence: `data_utils/data_loader.py`)
- Point-cloud files → Point-cloud datasets: supplies samples
- Sparse data loader → Point-cloud I/O: reads files (evidence: `data_utils/data_loader.py`)
- Sparse data loader → Voxel quantization: quantizes points (evidence: `data_utils/data_loader.py`)
- Sparse data loader → Spatial partitioning: partitions points (evidence: `data_utils/data_loader.py`)
- Point-cloud datasets → Point-cloud I/O: reads files (evidence: `data_utils/dataset.py`)
- Point-cloud datasets → Voxel quantization: quantizes points (evidence: `data_utils/dataset.py`)
- Point-cloud datasets → Spatial partitioning: partitions points (evidence: `data_utils/dataset.py`)
- Multiscale PCC model → Sparse data loader: loads sparse input (evidence: `models/model.py`)
- Multiscale PCC model → Voxel quantization: quantizes scales (evidence: `models/model.py`)
- Multiscale PCC model → Point-cloud I/O: writes output (evidence: `models/model.py`)
- Multiscale PCC model → Point-cloud metrics: measures distortion (evidence: `models/model.py`)
- Multiscale PCC model → Sparse autoencoder: selects encoder (evidence: `models/model.py`)
- Multiscale PCC model → Occupancy decoder: selects decoder (evidence: `models/model.py`)
- Sparse autoencoder → Sparse residual blocks: uses blocks (evidence: `models/autoencoder.py`)
- Sparse autoencoder → Entropy model: uses coding model (evidence: `models/autoencoder.py`)
- Sparse autoencoder → Occupancy decoder: uses decoder (evidence: `models/autoencoder.py`)
- Sparse autoencoder → Sparse tensor ops: uses tensor ops (evidence: `models/autoencoder.py`)
- Occupancy decoder → Sparse residual blocks: uses blocks (evidence: `models/decoder.py`)
- Occupancy decoder → Sparse tensor ops: uses tensor ops (evidence: `models/decoder.py`)
- Training entry point → Sparse data loader: loads batches (evidence: `train/train.py`)
- Training entry point → Multiscale PCC model: trains model (evidence: `train/train.py`)
- Training entry point → Training lifecycle: extends trainer (evidence: `train/train.py`)
- Training entry point → Sparse tensor ops: builds sparse input (evidence: `train/train.py`)
- Offset prediction → Sparse residual blocks: uses blocks (evidence: `models/model_offset.py`)
- Offset prediction → G-PCC and distortion tools: uses codec tools (evidence: `models/model_offset.py`)
- Offset prediction → Voxel quantization: quantizes coordinates (evidence: `models/model_offset.py`)
- Offset prediction → Sparse data loader: loads input (evidence: `models/model_offset.py`)
- Test entry points → Multiscale PCC model: runs compression
- Test entry points → Offset prediction: runs offset mode
- G-PCC and distortion tools → G-PCC wrapper: invokes wrapper
