# 3dpcc/pace architecture

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

## Overview

PACE is an inference toolkit for learned LiDAR point-cloud compression. Its main workflow reads dataset-specific point clouds, quantizes and organizes them as octrees, predicts occupancy probabilities with a learned context model, and entropy-codes them into a bitstream; decoding reconstructs octree symbols, dequantizes coordinates, and writes a point cloud. Encoding supports parallel, autoregressive, and configurable multi-stage prediction. The README also documents bitrate and distortion evaluation. The excerpts show the decode path and parts of encoding; links for unsampled evaluation and encoding internals are included only where documented.

Main entry points: [`encode.py`](https://github.com/3dpcc/pace/blob/main/encode.py) (Encode), [`decode.py`](https://github.com/3dpcc/pace/blob/main/decode.py) (Decode), [`utils/rw.py`](https://github.com/3dpcc/pace/blob/main/utils/rw.py) (Point Cloud I/O), [`utils/helper.py`](https://github.com/3dpcc/pace/blob/main/utils/helper.py) (Codec Helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_io["Point Cloud I/O"]
  node_input_cloud["Input Cloud"]
  node_dataset["Dataset Handling<br/>[dataset.py]"]
  node_point_io["Point Cloud I/O<br/>[rw.py]"]
end

subgraph group_codec["Compression Pipeline"]
  node_encode["Encode<br/>[encode.py]"]
  node_octree_encode["Octree Encoding<br/>[octree.cpp]"]
  node_decode["Decode<br/>[decode.py]"]
  node_octree_decode["Octree Decoding<br/>[octree.cpp]"]
  node_bitstream["Compressed Bitstream"]
end

subgraph group_model["Learned Model"]
  node_network["Network<br/>[network.py]"]
  node_model_layers["Model Layers<br/>[nn.py]"]
  node_mamba["Mamba Block<br/>[mamba.py]"]
end

subgraph group_entropy["Entropy Coding"]
  node_codec_helpers["Codec Helpers<br/>[helper.py]"]
  node_rans_extension["rANS Coder<br/>[octrans.cpp]"]
end

subgraph group_evaluation["Evaluation"]
  node_eval_prep["Evaluation Preparation<br/>[prepare_test.py]"]
  node_eval["Distortion Evaluation<br/>[eval.py]"]
  node_summary["Bitrate Summary<br/>[summarize.py]"]
  node_metric["Point-Cloud Metric"]
  node_results["Evaluation Results"]
end

node_user(("User"))

node_user -->|"starts encoding"| node_encode
node_user -->|"starts decoding"| node_decode
node_input_cloud -->|"provides points"| node_point_io
node_encode -->|"reads coordinates"| node_point_io
node_point_io -->|"supplies coordinates"| node_dataset
node_encode -->|"quantizes points"| node_dataset
node_encode -->|"builds octree"| node_octree_encode
node_encode -->|"predicts symbols"| node_network
node_network -->|"uses layers"| node_model_layers
node_model_layers -->|"uses block"| node_mamba
node_encode -->|"prepares entropy data"| node_codec_helpers
node_codec_helpers -->|"encodes symbols"| node_rans_extension
node_encode -->|"writes bitstream"| node_bitstream
node_user -->|"selects for decoding"| node_bitstream
node_decode -->|"reads bitstream"| node_bitstream
node_decode -->|"decodes symbols"| node_codec_helpers
node_codec_helpers -->|"decodes symbols"| node_rans_extension
node_decode -->|"reconstructs octree"| node_octree_decode
node_decode -->|"predicts symbols"| node_network
node_decode -->|"dequantizes coordinates"| node_dataset
node_decode -->|"writes point cloud"| node_point_io
node_point_io -->|"writes decoded cloud"| node_results
node_user -->|"starts evaluation"| node_eval_prep
node_eval_prep -->|"prepares distortion inputs"| node_eval
node_eval -->|"measures distortion"| node_metric
node_eval -->|"reports distortion"| node_results
node_user -->|"summarizes bitrate"| node_summary
node_summary -->|"writes bitrate summary"| node_results

click node_input_cloud "https://github.com/3dpcc/pace/tree/main/data"
click node_dataset "https://github.com/3dpcc/pace/blob/main/utils/dataset.py"
click node_point_io "https://github.com/3dpcc/pace/blob/main/utils/rw.py"
click node_encode "https://github.com/3dpcc/pace/blob/main/encode.py"
click node_octree_encode "https://github.com/3dpcc/pace/blob/main/extension/octcode/src/octree.cpp"
click node_decode "https://github.com/3dpcc/pace/blob/main/decode.py"
click node_octree_decode "https://github.com/3dpcc/pace/blob/main/extension/octcode/src/octree.cpp"
click node_network "https://github.com/3dpcc/pace/blob/main/model/network.py"
click node_model_layers "https://github.com/3dpcc/pace/blob/main/model/nn.py"
click node_mamba "https://github.com/3dpcc/pace/blob/main/model/mamba.py"
click node_codec_helpers "https://github.com/3dpcc/pace/blob/main/utils/helper.py"
click node_rans_extension "https://github.com/3dpcc/pace/blob/main/extension/octrans/src/octrans.cpp"
click node_eval_prep "https://github.com/3dpcc/pace/blob/main/scripts/prepare_test.py"
click node_eval "https://github.com/3dpcc/pace/blob/main/scripts/eval.py"
click node_summary "https://github.com/3dpcc/pace/blob/main/scripts/summarize.py"
click node_metric "https://github.com/3dpcc/pace/blob/main/extension/pc_error_d"

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_input_cloud,node_dataset,node_point_io,node_user toneBlue
class node_encode,node_octree_encode,node_decode,node_octree_decode,node_bitstream toneAmber
class node_network,node_model_layers,node_mamba toneMint
class node_codec_helpers,node_rans_extension toneRose
class node_eval_prep,node_eval,node_summary,node_metric,node_results toneIndigo
```

## Components

### Point Cloud I/O

- [Input Cloud](https://github.com/3dpcc/pace/tree/main/data): `data`
- [Dataset Handling](https://github.com/3dpcc/pace/blob/main/utils/dataset.py): `utils/dataset.py`
- [Point Cloud I/O](https://github.com/3dpcc/pace/blob/main/utils/rw.py): `utils/rw.py`

### Compression Pipeline

- [Encode](https://github.com/3dpcc/pace/blob/main/encode.py): `encode.py`
- [Octree Encoding](https://github.com/3dpcc/pace/blob/main/extension/octcode/src/octree.cpp): `extension/octcode/src/octree.cpp`
- [Decode](https://github.com/3dpcc/pace/blob/main/decode.py): `decode.py`
- [Octree Decoding](https://github.com/3dpcc/pace/blob/main/extension/octcode/src/octree.cpp): `extension/octcode/src/octree.cpp`
- **Compressed Bitstream**

### Learned Model

- [Network](https://github.com/3dpcc/pace/blob/main/model/network.py): `model/network.py`
- [Model Layers](https://github.com/3dpcc/pace/blob/main/model/nn.py): `model/nn.py`
- [Mamba Block](https://github.com/3dpcc/pace/blob/main/model/mamba.py): `model/mamba.py`

### Entropy Coding

- [Codec Helpers](https://github.com/3dpcc/pace/blob/main/utils/helper.py): `utils/helper.py`
- [rANS Coder](https://github.com/3dpcc/pace/blob/main/extension/octrans/src/octrans.cpp): `extension/octrans/src/octrans.cpp`

### Evaluation

- [Evaluation Preparation](https://github.com/3dpcc/pace/blob/main/scripts/prepare_test.py): `scripts/prepare_test.py`
- [Distortion Evaluation](https://github.com/3dpcc/pace/blob/main/scripts/eval.py): `scripts/eval.py`
- [Bitrate Summary](https://github.com/3dpcc/pace/blob/main/scripts/summarize.py): `scripts/summarize.py`
- [Point-Cloud Metric](https://github.com/3dpcc/pace/blob/main/extension/pc_error_d): `extension/pc_error_d`
- **Evaluation Results**

### Other components

- **User**

## Connections

- User → Encode: starts encoding
- User → Decode: starts decoding
- Input Cloud → Point Cloud I/O: provides points
- Encode → Point Cloud I/O: reads coordinates
- Point Cloud I/O → Dataset Handling: supplies coordinates
- Encode → Dataset Handling: quantizes points
- Encode → Octree Encoding: builds octree
- Encode → Network: predicts symbols
- Network → Model Layers: uses layers
- Model Layers → Mamba Block: uses block
- Encode → Codec Helpers: prepares entropy data
- Codec Helpers → rANS Coder: encodes symbols
- Encode → Compressed Bitstream: writes bitstream
- User → Compressed Bitstream: selects for decoding
- Decode → Compressed Bitstream: reads bitstream
- Decode → Codec Helpers: decodes symbols
- Codec Helpers → rANS Coder: decodes symbols
- Decode → Octree Decoding: reconstructs octree
- Decode → Network: predicts symbols
- Decode → Dataset Handling: dequantizes coordinates
- Decode → Point Cloud I/O: writes point cloud
- Point Cloud I/O → Evaluation Results: writes decoded cloud
- User → Evaluation Preparation: starts evaluation
- Evaluation Preparation → Distortion Evaluation: prepares distortion inputs
- Distortion Evaluation → Point-Cloud Metric: measures distortion
- Distortion Evaluation → Evaluation Results: reports distortion
- User → Bitrate Summary: summarizes bitrate
- Bitrate Summary → Evaluation Results: writes bitrate summary