# jiyao06/genpose architecture

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

- Interactive diagram: https://gitdiagram.com/jiyao06/genpose
- Repository: https://github.com/jiyao06/genpose

## Overview

##### Project Type and Purpose
- This is a research-oriented full-stack deep learning project for object pose estimation. The main aim is to estimate object poses using a two-step diffusion process: first generating pose candidates with a score-based diffusion model and then refining them using an energy-based model.
- The README highlights that the project implements diffusion models for pose estimation (with both score network and energy network) and shows a clear training and evaluation pipeline.

##### File Structure
- Top-level directories include:
- configs – holds configuration scripts (configs/config.py) for managing parameters.
- data – contains dataset files and preprocessed data.
- datasets – includes dataset pre-processing scripts (e.g., datasets_genpose.py).
- networks – the core folder with subdirectories for each network module:
▪ decoder_head – contains modules for handling pose rotations and translations.
▪ gf_algorithms – includes diffusion model components (score utils, SDE, samplers, energy network, etc.).
▪ posenet and posenet_agent – modules likely responsible for initial pose estimation.
▪ pts_encoder – dedicated to processing point clouds (using PointNet2 and its utilities).
▪ The presence of “pointnet2_utils” subfolder indicates that some components are borrowed from or built on top of an established point cloud processing library.
- runners – contains scripts for training and evaluation (trainer, evaluation_single, evaluation_tracking).
- scripts – includes shell scripts to execute training and evaluation (which explicitly set different configurations).
- utils – helper functions for data augmentation, visualization, metrics, etc.
- This granularity suggests the design should clearly separate the scoring and energy algorithms with additional support around dataset handling, configuration, and training/evaluation orchestration.

##### Key Components & Architecture
a. Main Components:
- Data Input & Pre-processing: Represented by the “data”, “datasets”, and “utils” directories. This includes reading the NOCS datasets, performing augmentation, and handling segmentation results.
- Score Network: Implemented primarily under networks/gf_algorithms. The score-based model is used to generate pose candidates.
- Energy Network: Also found under networks/gf_algorithms, this module computes energies associated with each candidate and filters low-quality candidates.
- Decoder / Aggregation Modules: Under networks/decoder_head, where translation and rotation heads merge candidate outputs; and aggregation is done via mean pooling (as mentioned in the README).
- Point Cloud Encoder: The “pts_encoder” directory (via PointNet2) handles encoding of 3D data.
- Training & Evaluation Orchestration: The “runners” and “scripts” folders define the pipelines for training both the score and energy networks, as well as evaluation on datasets (REAL275 and CAMERA).
- Configuration Management: The “configs/config.py” centralizes project parameters and dataset paths.

b. Relationships and Interactions:
- Data flows from raw data input → pre-processing (datasets and utils) → point cloud encoding.
- The encoded data is then used by the Score Network to generate candidate poses.
- These candidates are fed into the Energy Network, which computes energy scores.
- The final pose is derived via aggregation (mean pooling of candidates) and is then evaluated.
- The runners/scripts coordinate the training and evaluation phases, configuring the networks appropriately.

c. Architectural Patterns and Design Principles:
- Modular Design: Each component (data handling, scoring, energy modeling, pose decoding) is encapsulated in its own module.
- Pipeline Architecture: The system flows from data ingestion and pre-processing, through candidate generation, candidate scoring, and finally aggregation.
- Separation of Concerns: Clear division between training scripts, evaluation scripts, and network definitions.
- Use of Established Libraries/Models: The project integrates established libraries (PyTorch, PyTorch3D, PointNet2) into its architecture.

d. Relevant Technologies & Frameworks:
- PyTorch: For deep learning model implementations.
- PyTorch3D: For 3D computations and rendering if needed.
- Diffusion models and denoising score matching: Underlying algorithms for pose estimation.
- PointNet2: For point cloud processing.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Data & Pre-processing Subgraph
    subgraph "Data & Pre-processing"
        DP1["Data Directory"]:::data
        DP2["Dataset Preprocessing"]:::data
        DP3["Data Augmentation"]:::data
        DP4["Datasets Utils"]:::data
        DP_AGG["Dataset & Pre-processing"]:::data
        DP1 --> DP2
        DP2 --> DP3
        DP3 --> DP4
        DP4 --> DP_AGG
    end

    %% Configuration Subgraph
    subgraph "Configuration"
        CFG["Configuration Manager"]:::config
    end

    %% Point Cloud Encoder Subgraph
    subgraph "Point Cloud Encoder"
        ENC["PointNet2 Encoder"]:::encoder
        ENC_UTIL["PointNet2 Utils"]:::encoder
        ENC --> ENC_UTIL
    end

    %% Score-Based Diffusion Model Subgraph
    subgraph "Score-Based Diffusion Model"
        SCN["Score Network Implementation"]:::score
        SCU["Score Utils"]:::score
        SDE_NODE["SDE Component"]:::score
        SAM_NODE["Samplers"]:::score
        SCN --> SCU
        SCU --> SDE_NODE
        SDE_NODE --> SAM_NODE
    end

    %% Energy-Based Diffusion Model Subgraph
    subgraph "Energy-Based Diffusion Model"
        ENN["Energy Network Implementation"]:::energy
    end

    %% Pose Decoder / Aggregation Subgraph
    subgraph "Pose Decoder / Aggregation"
        RH["Rotation Head"]:::decoder
        TH["Translation Head"]:::decoder
        RH --> TH
    end

    %% Training & Evaluation Subgraph
    subgraph "Training & Evaluation"
        TR["Trainer"]:::training
        EVS["Evaluation Single"]:::training
        EVT["Evaluation Tracking"]:::training
        TS_EN["Train Energy Script"]:::training
        TS_SC["Train Score Script"]:::training
        ES["Eval Single Script"]:::training
        ET["Eval Tracking Script"]:::training
    end

    %% External Dependencies Subgraph
    subgraph "External Dependencies"
        EX["PyTorch, PyTorch3D, CUDA, PointNet2"]:::external
    end

    %% Main Data Flow Connections
    DP_AGG --> ENC
    ENC_UTIL --> SCN
    SAM_NODE --> ENN
    ENN --> RH
    TH --> TR

    %% Configuration influences (dotted lines)
    CFG --- ENC
    CFG --- SCN
    CFG --- ENN
    CFG --- RH
    CFG --- TR

    %% External Dependencies influences (dotted lines)
    EX --- SCN
    EX --- ENN

    %% Class Definitions (with colors)
    classDef data fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef config fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef encoder fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef score fill:#FAD7A0,stroke:#D68910,stroke-width:2px;
    classDef energy fill:#D2B4DE,stroke:#7D3C98,stroke-width:2px;
    classDef decoder fill:#EDBB99,stroke:#CA6F1E,stroke-width:2px;
    classDef training fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef external fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;

click DP1 "https://github.com/jiyao06/genpose/tree/main/data"
click DP2 "https://github.com/jiyao06/genpose/blob/main/datasets/datasets_genpose.py"
click DP3 "https://github.com/jiyao06/genpose/blob/main/utils/data_augmentation.py"
click DP4 "https://github.com/jiyao06/genpose/blob/main/utils/datasets_utils.py"
click CFG "https://github.com/jiyao06/genpose/blob/main/configs/config.py"
click ENC "https://github.com/jiyao06/genpose/blob/main/networks/pts_encoder/pointnet2.py"
click ENC_UTIL "https://github.com/jiyao06/genpose/tree/main/networks/pts_encoder/pointnet2_utils"
click SCN "https://github.com/jiyao06/genpose/blob/main/networks/gf_algorithms/scorenet.py"
click SCU "https://github.com/jiyao06/genpose/blob/main/networks/gf_algorithms/score_utils.py"
click SDE_NODE "https://github.com/jiyao06/genpose/blob/main/networks/gf_algorithms/sde.py"
click SAM_NODE "https://github.com/jiyao06/genpose/blob/main/networks/gf_algorithms/samplers.py"
click ENN "https://github.com/jiyao06/genpose/blob/main/networks/gf_algorithms/energynet.py"
click RH "https://github.com/jiyao06/genpose/blob/main/networks/decoder_head/rot_head.py"
click TH "https://github.com/jiyao06/genpose/blob/main/networks/decoder_head/trans_head.py"
click TR "https://github.com/jiyao06/genpose/blob/main/runners/trainer.py"
click EVS "https://github.com/jiyao06/genpose/blob/main/runners/evaluation_single.py"
click EVT "https://github.com/jiyao06/genpose/blob/main/runners/evaluation_tracking.py"
click TS_EN "https://github.com/jiyao06/genpose/blob/main/scripts/train_energy.sh"
click TS_SC "https://github.com/jiyao06/genpose/blob/main/scripts/train_score.sh"
click ES "https://github.com/jiyao06/genpose/blob/main/scripts/eval_single.sh"
click ET "https://github.com/jiyao06/genpose/blob/main/scripts/eval_tracking.sh"
```
