# njuvision/pcgcv2 architecture

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

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

## Overview

##### Project Type and Purpose
- This is a research-oriented, end-to-end machine-learning (PyTorch) tool for 3D point-cloud geometry compression.
- It implements both training and inference pipelines, featuring a sparse-convolution autoencoder, entropy model, and practical coding back-ends (torchac, tmc3).

##### File Structure
- Top-level scripts:
- data_loader.py, data_utils.py, generate_dataset.py → data ingestion & preprocessing
- autoencoder.py, pcc_model.py, entropy_model.py, loss.py → neural-network definitions
- trainer.py, train.py → training orchestration
- coder.py, test.py, gpcc.py, pc_error.py, pc_error_d → inference & evaluation
- tmc3 (binary) → lossless coordinate compressor
- Directories:
- ckpts.zip → pretrained model checkpoints
- results/ → evaluation outputs
- Configuration is code-driven (no separate YAML), dependencies indicated in README.

##### Key Insights from the README
- Core approach: multiscale sparse convolution autoencoder with hierarchical reconstruction.
- External libs: MinkowskiEngine (sparse convolutions), torchac (arithmetic coding), tmc3 (MPEG PCC).
- Two modes: lossless (via tmc3) and lossy (via entropy model + arithmetic coder).

##### Main Components and Their Interactions
A. Data Ingestion & Preprocessing
- Input: raw .ply point-cloud files
- Tools: data_loader.py, data_utils.py, generate_dataset.py
- Output: multi-scale sparse tensors suitable for MinkowskiEngine

B. Neural Autoencoder
- Modules: autoencoder.py (encoder & decoder), pcc_model.py (model wrapper)
- Framework: PyTorch + MinkowskiEngine
- Loss: defined in loss.py

C. Entropy Model & Arithmetic Coding
- EntropyModel (entropy_model.py) estimates probability distributions
- torchac library performs arithmetic encode/decode
- Coordinate compressor: tmc3 binary invoked by gpcc.py or within coder.py

D. Training Pipeline
- Entry point: train.py → calls trainer.py
- Steps: load data, forward pass through autoencoder, compute loss, backprop, checkpoint

E. Inference / Testing Pipeline
- Entry points: coder.py (encode+decode), test.py (benchmark + error metrics)
- Steps: load checkpoint, run encoder, compress bits, run decoder, compute metrics via pc_error.py / pc_error_d

F. Evaluation & Results
- Compressed bitstreams and reconstructed point clouds → error reports in results/

##### Architectural Patterns & Design Principles
- Modular pipeline: clear separation of data, model, coding, and evaluation
- Plug-in back-ends: torchac vs tmc3 can be swapped with minimal change
- Reusable components: pcc_model wraps encoder/decoder for both training & inference

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Training Pipeline
  subgraph "Training Pipeline"
    direction TB
    DL["data_loader.py"]:::data
    DU["data_utils.py"]:::data
    GD["generate_dataset.py"]:::data
    DL -->|"raw .ply"| DU
    DU -->|"processed data"| GD
    GD -->|"multi-scale sparse tensor"| AEenc["autoencoder.py"]:::model
    AEenc --> PM["pcc_model.py"]:::model
    PM --> L["loss.py"]:::model
    L --> TR["trainer.py"]:::train
    TR -->|"checkpoints"| CK["ckpts.zip"]:::external
    TR -->|"evaluation outputs"| RES["results/"]:::results
    TR -->|"uses"| ME["MinkowskiEngine"]:::external
    Tn["train.py"]:::train --> TR
  end

  %% Inference / Testing Pipeline
  subgraph "Inference Pipeline"
    direction TB
    CK --> CM["coder.py"]:::coder
    CM --> EM["entropy_model.py"]:::coder
    EM --> AC["Arithmetic Coder (torchac)"]:::external
    CM --> GP["gpcc.py"]:::coder
    GP -->|"lossless compressor"| T3["tmc3"]:::external
    CM --> AD["Arithmetic Decoder (torchac)"]:::external
    AD --> AEDec["autoencoder.py"]:::model
    AEDec --> RPC["Reconstructed Point Cloud"]:::results
    RPC --> PE["pc_error.py / pc_error_d"]:::infer
    PE -->|"metrics (Bpp/PSNR)"| RES
    Te["test.py"]:::infer --> PE
  end

  %% Project Docs
  subgraph "Project Documentation"
    direction TB
    RD["README.md"]:::docs
    LIC["LICENSE"]:::docs
  end

  %% Relationships
  RD --> DL
  RD --> TR
  RD --> CM

  %% Click Events
  click DL "https://github.com/njuvision/pcgcv2/blob/master/data_loader.py"
  click DU "https://github.com/njuvision/pcgcv2/blob/master/data_utils.py"
  click GD "https://github.com/njuvision/pcgcv2/blob/master/generate_dataset.py"
  click AEenc "https://github.com/njuvision/pcgcv2/blob/master/autoencoder.py"
  click PM "https://github.com/njuvision/pcgcv2/blob/master/pcc_model.py"
  click L "https://github.com/njuvision/pcgcv2/blob/master/loss.py"
  click TR "https://github.com/njuvision/pcgcv2/blob/master/trainer.py"
  click Tn "https://github.com/njuvision/pcgcv2/blob/master/train.py"
  click CK "https://github.com/njuvision/pcgcv2/blob/master/ckpts.zip"
  click RES "https://github.com/njuvision/pcgcv2/tree/master/results/"
  click CM "https://github.com/njuvision/pcgcv2/blob/master/coder.py"
  click EM "https://github.com/njuvision/pcgcv2/blob/master/entropy_model.py"
  click GP "https://github.com/njuvision/pcgcv2/blob/master/gpcc.py"
  click T3 "https://github.com/njuvision/pcgcv2/tree/master/tmc3"
  click Te "https://github.com/njuvision/pcgcv2/blob/master/test.py"
  click PE "https://github.com/njuvision/pcgcv2/blob/master/pc_error.py"
  click RD "https://github.com/njuvision/pcgcv2/blob/master/README.md"
  click LIC "https://github.com/njuvision/pcgcv2/tree/master/LICENSE"

  %% Styles
  classDef data fill:#AED6F1,stroke:#1B4F72,color:#1B2631;
  classDef model fill:#A9DFBF,stroke:#196F3D,color:#145A32;
  classDef coder fill:#F5CBA7,stroke:#A04000,color:#6E2C00;
  classDef train fill:#F9E79F,stroke:#B7950B,color:#7D6608;
  classDef infer fill:#FADBD8,stroke:#943126,color:#641E16;
  classDef external fill:#D5D8DC,stroke:#6C7A89,color:#2C3E50;
  classDef results fill:#D6EAF8,stroke:#1B4F72,color:#154360;
  classDef docs fill:#EBDEF0,stroke:#7D3C98,color:#4A235A;
```
