# jiang-hb/diffusionreg architecture

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

- Interactive diagram: https://gitdiagram.com/jiang-hb/diffusionreg
- Repository: https://github.com/jiang-hb/diffusionreg

## Overview

1. **What this repo is**
   This is a PyTorch implementation of an **SE(3) diffusion-based point cloud registration system** for 6D object pose estimation. The core idea is to treat pose estimation as iterative denoising of a rigid transform between a source point cloud and an object model point cloud.

2. **Top-level execution boundary**
   The runtime entry points are `train.py` and `test.py`. These scripts are the orchestration layer: they load configuration, build the dataset, instantiate the registration/diffusion components, run optimization or evaluation, and write checkpoints/results into `results/`.

3. **Data subsystem**
   Dataset handling is split between `datasets/get_dataset.py` and `datasets/tudl_db.py`. The repo includes a concrete TUD-L dataset layout under `datasets/tudl/`, with:
   - raw/processed object models in `.ply`
   - metadata files such as `models_info.json`
   - cached preprocessing artifacts in `*.pth`
   
   This indicates the code relies on preprocessed dataset descriptors rather than reading only raw BOP-style files at runtime.

4. **Dataset boundary and external dependency**
   The data pipeline is tied to **BOP-format object pose data**, specifically TUD-L in the checked-in tree. The README mentions LINEMOD and Occluded-LINEMOD support conceptually, but only TUD-L assets are present here. So the repo’s architecture is dataset-agnostic in code structure, but the included data boundary is TUD-L-centric.

5. **Registration backbone**
   The main registration network lives under `modules/DCP/dcp.py`, with supporting feature extraction utilities in `modules/DCP/rpmnet_emb/feature_net.py` and `pointnet_util.py`. This suggests the diffusion framework is built around a **deep point-cloud registration backbone**, using a DCP-style architecture and RPMNet-derived embedding components as the surrogate alignment model.

6. **Diffusion and pose refinement logic**
   The diffusion process itself is not isolated in a separate model directory, but is supported by utilities such as `utils/diffusion_scheduler.py`, `utils/losses.py`, and `utils/criterion.py`. Architecturally, these files form the training-time control layer for:
   - adding SE(3) noise/perturbation
   - scheduling the reverse denoising steps
   - computing the registration-specific objective

7. **SE(3)/Lie algebra math layer**
   The `utils/se_math/` package is a distinct mathematical boundary for rigid-body transforms on the manifold:
   - `se3.py`, `so3.py` for transformations and rotations
   - `transforms.py`, `mesh.py`, `invmat.py`, `sinc.py` for supporting operations  
   
   This layer is important because the method operates in **SE(3)** rather than Euclidean parameter space, so pose perturbation and recovery are manifold-aware.

8. **Training infrastructure**
   `utils/options.py`, `utils/get_lr_scheduler.py`, `utils/commons.py`, and `utils/attr_dict.py` provide experiment configuration, learning-rate scheduling, and shared helpers. Together they form the experiment-management layer used by `train.py` to assemble the full system.

9. **Evaluation and outputs**
   The `results/` directory shows the output boundary of the system:
   - trained checkpoints such as `model_epoch19.pth`
   - per-object evaluation artifacts under `eval_results/`
   
   This implies evaluation is checkpoint-driven and can emit object-specific pose outputs or metrics for each test object instance.

10. **End-to-end data flow**
   The main flow is:
   - dataset loaders read preprocessed TUD-L assets
   - a point-cloud registration backbone produces pose refinements
   - the diffusion scheduler perturbs and then denoises SE(3) transforms
   - SE(3) math utilities enforce rigid-transform correctness
   - losses/criteria optimize the reverse process
   - checkpoints and evaluation outputs are written to `results/`

11. **Architectural separation**
   The repo is cleanly separated into:
   - **data access**: `datasets/`
   - **model/backbone**: `modules/DCP/`
   - **math/manifold ops**: `utils/se_math/`
   - **training/evaluation control**: `train.py`, `test.py`, and utility modules  
   
   This makes the diffusion framework modular: the backbone can be treated as a surrogate registration network while the SE(3) diffusion machinery sits around it as a higher-level refinement process.

Main entry points: [`train.py`](https://github.com/jiang-hb/diffusionreg/blob/main/train.py) (train.py), [`utils/se_math/se3.py`](https://github.com/jiang-hb/diffusionreg/blob/main/utils/se_math/se3.py) (SE(3)), [`test.py`](https://github.com/jiang-hb/diffusionreg/blob/main/test.py) (test.py), [`modules/DCP/dcp.py`](https://github.com/jiang-hb/diffusionreg/blob/main/modules/DCP/dcp.py) (DCP)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Execution"]
  node_train_py["train.py<br/>runner<br/>[train.py]"]
  node_test_py["test.py<br/>runner<br/>[test.py]"]
end

subgraph group_data["Data"]
  node_get_dataset["Get dataset<br/>loader factory<br/>[get_dataset.py]"]
  node_tudl_db["TUD-L DB<br/>dataset backend<br/>[tudl_db.py]"]
  node_tudl_assets[("TUD-L assets<br/>bop assets<br/>[models_info.json]")]
end

subgraph group_model["Model"]
  node_dcp["DCP<br/>registration backbone<br/>[dcp.py]"]
  node_feature_net["Feature net<br/>point embedding<br/>[feature_net.py]"]
  node_pointnet_util["PointNet utils<br/>point ops<br/>[pointnet_util.py]"]
end

subgraph group_math["SE(3) math"]
  node_se3(("SE(3)<br/>manifold math<br/>[se3.py]"))
  node_so3(("SO(3)<br/>rotation math<br/>[so3.py]"))
  node_transforms["Transforms<br/>geometry ops<br/>[transforms.py]"]
end

subgraph group_train["Training"]
  node_diffusion_sched["Scheduler<br/>diffusion control"]
  node_criterion["Criterion<br/>training objective<br/>[criterion.py]"]
  node_losses["Losses<br/>loss functions<br/>[losses.py]"]
  node_options["Options<br/>config<br/>[options.py]"]
  node_lr_sched["LR schedule<br/>optimizer control"]
  node_commons["Commons<br/>shared helpers<br/>[commons.py]"]
end

subgraph group_outputs["Outputs"]
  node_results[("Results<br/>artifacts<br/>[model_epoch19.pth]")]
end

node_train_py -->|"loads config"| node_options
node_train_py -->|"builds data"| node_get_dataset
node_train_py -->|"instantiates"| node_dcp
node_train_py -->|"sets schedule"| node_diffusion_sched
node_train_py -->|"optimizes"| node_criterion
node_train_py -->|"updates lr"| node_lr_sched
node_train_py -->|"writes checkpoints"| node_results
node_test_py -->|"loads config"| node_options
node_test_py -->|"builds data"| node_get_dataset
node_test_py -->|"writes evals"| node_results
node_get_dataset -->|"uses"| node_tudl_db
node_tudl_db -->|"reads"| node_tudl_assets
node_dcp -->|"uses"| node_feature_net
node_dcp -->|"uses"| node_pointnet_util
node_train_py -->|"constrains"| node_se3
node_se3 -->|"depends on"| node_so3
node_se3 -->|"supports"| node_transforms
node_diffusion_sched -->|"perturbs"| node_se3
node_criterion -->|"composes"| node_losses
node_criterion -->|"evaluates"| node_se3
node_commons -->|"supports output"| node_results

click node_train_py "https://github.com/jiang-hb/diffusionreg/blob/main/train.py"
click node_test_py "https://github.com/jiang-hb/diffusionreg/blob/main/test.py"
click node_get_dataset "https://github.com/jiang-hb/diffusionreg/blob/main/datasets/get_dataset.py"
click node_tudl_db "https://github.com/jiang-hb/diffusionreg/blob/main/datasets/tudl_db.py"
click node_tudl_assets "https://github.com/jiang-hb/diffusionreg/blob/main/datasets/tudl/models/models_info.json"
click node_dcp "https://github.com/jiang-hb/diffusionreg/blob/main/modules/DCP/dcp.py"
click node_feature_net "https://github.com/jiang-hb/diffusionreg/blob/main/modules/DCP/rpmnet_emb/feature_net.py"
click node_pointnet_util "https://github.com/jiang-hb/diffusionreg/blob/main/modules/DCP/rpmnet_emb/pointnet_util.py"
click node_diffusion_sched "https://github.com/jiang-hb/diffusionreg/blob/main/utils/diffusion_scheduler.py"
click node_criterion "https://github.com/jiang-hb/diffusionreg/blob/main/utils/criterion.py"
click node_losses "https://github.com/jiang-hb/diffusionreg/blob/main/utils/losses.py"
click node_options "https://github.com/jiang-hb/diffusionreg/blob/main/utils/options.py"
click node_lr_sched "https://github.com/jiang-hb/diffusionreg/blob/main/utils/get_lr_scheduler.py"
click node_commons "https://github.com/jiang-hb/diffusionreg/blob/main/utils/commons.py"
click node_se3 "https://github.com/jiang-hb/diffusionreg/blob/main/utils/se_math/se3.py"
click node_so3 "https://github.com/jiang-hb/diffusionreg/blob/main/utils/se_math/so3.py"
click node_transforms "https://github.com/jiang-hb/diffusionreg/blob/main/utils/se_math/transforms.py"
click node_results "https://github.com/jiang-hb/diffusionreg/blob/main/results/DiffusionReg-DiffusionDCP-tudl-diffusion_200_0.00010_0.05_0.05_0.03-nvids3_cosine/model_epoch19.pth"

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_train_py,node_test_py toneBlue
class node_get_dataset,node_tudl_db,node_tudl_assets toneAmber
class node_dcp,node_feature_net,node_pointnet_util toneMint
class node_se3,node_so3,node_transforms toneRose
class node_diffusion_sched,node_criterion,node_losses,node_options,node_lr_sched,node_commons toneIndigo
class node_results toneTeal
```

## Components

### Execution

Entry points and orchestration

- [train.py](https://github.com/jiang-hb/diffusionreg/blob/main/train.py): runner · Training entry point that builds the full diffusion-registration pipeline · `train.py`
- [test.py](https://github.com/jiang-hb/diffusionreg/blob/main/test.py): runner · Evaluation entry point that loads checkpoints and writes pose results · `test.py`

### Data

Dataset loading and checked-in assets

- [Get dataset](https://github.com/jiang-hb/diffusionreg/blob/main/datasets/get_dataset.py): loader factory · Selects and constructs the dataset implementation · `datasets/get_dataset.py`
- [TUD-L DB](https://github.com/jiang-hb/diffusionreg/blob/main/datasets/tudl_db.py): dataset backend · Dataset-specific access layer for TUD-L pose data · `datasets/tudl_db.py`
- [TUD-L assets](https://github.com/jiang-hb/diffusionreg/blob/main/datasets/tudl/models/models_info.json): bop assets · Checked-in object models, metadata, and cached preprocessing artifacts · `datasets/tudl/models/models_info.json`

### Model

Registration backbone and embeddings

- [DCP](https://github.com/jiang-hb/diffusionreg/blob/main/modules/DCP/dcp.py): registration backbone · Main deep point-cloud registration network used for pose refinement · `modules/DCP/dcp.py`
- [Feature net](https://github.com/jiang-hb/diffusionreg/blob/main/modules/DCP/rpmnet_emb/feature_net.py): point embedding · Point-cloud feature extraction used by the registration backbone · `modules/DCP/rpmnet_emb/feature_net.py`
- [PointNet utils](https://github.com/jiang-hb/diffusionreg/blob/main/modules/DCP/rpmnet_emb/pointnet_util.py): point ops · Shared point-cloud sampling and neighborhood utilities · `modules/DCP/rpmnet_emb/pointnet_util.py`

### SE(3) math

Rigid transform and manifold utilities

- [SE(3)](https://github.com/jiang-hb/diffusionreg/blob/main/utils/se_math/se3.py): manifold math · Rigid-transform operations on the SE(3) manifold · `utils/se_math/se3.py`
- [SO(3)](https://github.com/jiang-hb/diffusionreg/blob/main/utils/se_math/so3.py): rotation math · Rotation algebra and pose-relevant rotational operations · `utils/se_math/so3.py`
- [Transforms](https://github.com/jiang-hb/diffusionreg/blob/main/utils/se_math/transforms.py): geometry ops · Supporting transform conversions and rigid-body utilities · `utils/se_math/transforms.py`

### Training

Optimization, scheduling, and losses

- [Scheduler](https://github.com/jiang-hb/diffusionreg/blob/main/utils/diffusion_scheduler.py): diffusion control · Controls SE(3) noise levels and reverse denoising steps · `utils/diffusion_scheduler.py`
- [Criterion](https://github.com/jiang-hb/diffusionreg/blob/main/utils/criterion.py): training objective · Registration and diffusion-specific training criterion · `utils/criterion.py`
- [Losses](https://github.com/jiang-hb/diffusionreg/blob/main/utils/losses.py): loss functions · Objective terms for pose refinement and alignment · `utils/losses.py`
- [Options](https://github.com/jiang-hb/diffusionreg/blob/main/utils/options.py): config · Experiment and runtime configuration parsing · `utils/options.py`
- [LR schedule](https://github.com/jiang-hb/diffusionreg/blob/main/utils/get_lr_scheduler.py): optimizer control · Learning-rate scheduling helpers · `utils/get_lr_scheduler.py`
- [Commons](https://github.com/jiang-hb/diffusionreg/blob/main/utils/commons.py): shared helpers · General-purpose training and evaluation utilities · `utils/commons.py`

### Outputs

Checkpoints and evaluation artifacts

- [Results](https://github.com/jiang-hb/diffusionreg/blob/main/results/DiffusionReg-DiffusionDCP-tudl-diffusion_200_0.00010_0.05_0.05_0.03-nvids3_cosine/model_epoch19.pth): artifacts · Saved checkpoints and per-object evaluation outputs · `results/DiffusionReg-DiffusionDCP-tudl-diffusion_200_0.00010_0.05_0.05_0.03-nvids3_cosine/model_epoch19.pth`

## Connections

- train.py → Options: loads config · Training starts by parsing experiment settings
- train.py → Get dataset: builds data · Training constructs the dataset pipeline
- train.py → DCP: instantiates · Training creates the registration backbone
- train.py → Scheduler: sets schedule · Training uses the diffusion scheduler for perturbation and denoising
- train.py → Criterion: optimizes · Training computes the main training criterion
- train.py → LR schedule: updates lr · Training applies learning-rate scheduling
- train.py → Results: writes checkpoints · Training persists model checkpoints and run artifacts
- test.py → Options: loads config · Evaluation reuses the experiment configuration
- test.py → Get dataset: builds data · Evaluation loads the same dataset boundary
- test.py → Results: writes evals · Evaluation emits per-object output artifacts
- Get dataset → TUD-L DB: uses · Dataset factory delegates to the TUD-L backend
- TUD-L DB → TUD-L assets: reads · The backend reads checked-in object models and metadata
- DCP → Feature net: uses · The registration model depends on learned point features
- DCP → PointNet utils: uses · The backbone uses point-cloud utility operations
- train.py → SE(3): constrains · Training works in rigid-transform space rather than plain Euclidean parameters
- SE(3) → SO(3): depends on · SE(3) utilities build on rotation algebra
- SE(3) → Transforms: supports · Rigid-body operations rely on transform helpers
- Scheduler → SE(3): perturbs · The scheduler injects and removes pose noise in SE(3)
- Criterion → Losses: composes · The criterion aggregates training losses
- Criterion → SE(3): evaluates · Losses are computed over rigid transforms and pose residuals
- Commons → Results: supports output · Shared utilities help manage experiment artifacts
