# georgewuzy/cedex-grasp architecture

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

- Interactive diagram: https://gitdiagram.com/georgewuzy/cedex-grasp
- Repository: https://github.com/georgewuzy/cedex-grasp

## Overview

##### Project Type and Purpose
- This is a research-oriented, full-pipeline software project (not a web app) for large-scale dexterous-grasp synthesis.
- Core purpose: generate human-like contact representations, remap them to multiple robotic hands, create millions of grasps (CEDex dataset), validate them in simulation, and provide visualization tools.

##### File-Structure Analysis
- Top-level files:
- README.md, LICENSE, requirements.txt, .gitignore
- assets/ contains pipeline GIFs for documentation
- cedex/ stores precomputed grasp datasets per gripper (.pt files)
- data/ holds URDF descriptions and metadata for hands/objects
- contactgen/ is a self-contained Python package for contact-map generation
- pointnet_lib/ is a CUDA-accelerated extension for PointNet2 used by contactgen
- utils/ and utils_model/ supply helper functions, hand kinematics, optimizers
- validation/ contains scripts and modules for Isaac Gym–based grasp evaluation
- CLI scripts at root: inf_contactdb.py, inf_ycb.py, generate_data.py, eval_grasp.py, eval_grasp_filtered.py, vis_cedex.py, vis_generated_grasp.py
- Architectural patterns:
- Modular, layered pipeline: Data → Contact Generation → Grasp Generation → Validation → Visualization
- contactgen package uses PyTorch + pointnet_lib
- generate_data binds contact outputs with optimization routines in utils_model
- validation leverages NVIDIA Isaac Gym (external simulator)

##### Key README Insights
- Two-stage grasp creation:
Stage 1: generate human-like contact maps (contactgen/ + pointnet_lib)
Stage 2: optimize robot hand poses on contact maps (generate_data.py + utils_model)
Then validate (eval_grasp.py) and filter (eval_grasp_filtered.py) in simulation.
- External dependencies: PyTorch, PyTorch3D, Isaac Gym
- Dataset artifacts: cedex/*.pt, plus download links for real/synthetic objects

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        data_urdf["data/urdf/"]:::data
        cedex_allegro["allegro.pt"]:::data
        cedex_barrett["barrett.pt"]:::data
        cedex_robotiq["robotiq_3finger.pt"]:::data
        cedex_shadowhand["shadowhand.pt"]:::data
    end

    %% Contact Generation
    subgraph "Contact Generation"
        direction TB
        contactgen_pkg["contactgen/ (contactgen package)"]:::ml
        pointnet_lib_ext["pointnet_lib/ (PointNet2 CUDA)"]:::ml
        inf_contactdb["inf_contactdb.py"]:::ml
        inf_ycb["inf_ycb.py"]:::ml
    end

    %% Grasp Generation
    subgraph "Grasp Generation"
        direction TB
        generate_data["generate_data.py"]:::ml
        utils_model["utils_model/"]:::ml
    end

    %% Validation
    subgraph "Validation"
        direction TB
        validation_pkg["validation/"]:::sim
        eval_grasp["eval_grasp.py"]:::sim
        eval_grasp_filtered["eval_grasp_filtered.py"]:::sim
        isaac_env["Isaac Gym"]:::ext
    end

    %% Visualization
    subgraph "Visualization"
        direction TB
        vis_cedex["vis_cedex.py"]:::viz
        vis_generated["vis_generated_grasp.py"]:::viz
        utils_viz["utils/ (mesh_utils, hand_model, rot6d)"]:::viz
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        pytorch["PyTorch"]:::ext
        pytorch3d["PyTorch3D"]:::ext
        cuda["CUDA"]:::ext
        contactdb_src["ContactDB/YCB/Objaverse"]:::ext
    end

    %% Data Flows
    data_urdf -->|feeds URDF| contactgen_pkg
    cedex_allegro -->|precomputed grasps| generate_data
    cedex_barrett -->|precomputed grasps| generate_data
    cedex_robotiq -->|precomputed grasps| generate_data
    cedex_shadowhand -->|precomputed grasps| generate_data

    contactgen_pkg -->|outputs contact maps| generate_data
    pointnet_lib_ext -->|accelerates| contactgen_pkg

    inf_contactdb -->|run generation| contactgen_pkg
    inf_ycb -->|run generation| contactgen_pkg

    generate_data -->|proposed grasps| validation_pkg
    validation_pkg -->|validation feedback| generate_data

    generate_data -->|writes dataset| cedex_allegro
    generate_data -->|writes dataset| cedex_barrett
    generate_data -->|writes dataset| cedex_robotiq
    generate_data -->|writes dataset| cedex_shadowhand

    cedex_allegro -->|for viz| vis_cedex
    cedex_barrett -->|for viz| vis_cedex
    cedex_robotiq -->|for viz| vis_cedex
    cedex_shadowhand -->|for viz| vis_cedex
    utils_model -->|HandModel utils| vis_cedex

    eval_grasp -->|simulate in| isaac_env
    eval_grasp_filtered -->|simulate in| isaac_env

    vis_cedex -->|visualizes| utils_viz
    vis_generated -->|visualizes| utils_viz

    %% Class Assignments
    classDef data fill:#AED6F1,stroke:#2980B9,color:#1B4F72
    classDef ml fill:#ABEBC6,stroke:#27AE60,color:#145A32
    classDef sim fill:#F9E79F,stroke:#D4AC0D,color:#7D6608
    classDef viz fill:#D2B4DE,stroke:#8E44AD,color:#4A235A
    classDef ext fill:#CACFD2,stroke:#566573,color:#1B2631

    %% Click Events
    click data_urdf "https://github.com/georgewuzy/cedex-grasp/tree/main/data/urdf/"
    click cedex_allegro "https://github.com/georgewuzy/cedex-grasp/blob/main/cedex/allegro.pt"
    click cedex_barrett "https://github.com/georgewuzy/cedex-grasp/blob/main/cedex/barrett.pt"
    click cedex_robotiq "https://github.com/georgewuzy/cedex-grasp/blob/main/cedex/robotiq_3finger.pt"
    click cedex_shadowhand "https://github.com/georgewuzy/cedex-grasp/blob/main/cedex/shadowhand.pt"
    click contactgen_pkg "https://github.com/georgewuzy/cedex-grasp/tree/main/contactgen/contactgen/"
    click pointnet_lib_ext "https://github.com/georgewuzy/cedex-grasp/tree/main/contactgen/pointnet_lib/"
    click inf_contactdb "https://github.com/georgewuzy/cedex-grasp/blob/main/contactgen/inf_contactdb.py"
    click inf_ycb "https://github.com/georgewuzy/cedex-grasp/blob/main/contactgen/inf_ycb.py"
    click generate_data "https://github.com/georgewuzy/cedex-grasp/blob/main/generate_data.py"
    click utils_model "https://github.com/georgewuzy/cedex-grasp/tree/main/utils_model/"
    click validation_pkg "https://github.com/georgewuzy/cedex-grasp/tree/main/validation/"
    click eval_grasp "https://github.com/georgewuzy/cedex-grasp/blob/main/eval_grasp.py"
    click eval_grasp_filtered "https://github.com/georgewuzy/cedex-grasp/blob/main/eval_grasp_filtered.py"
    click vis_cedex "https://github.com/georgewuzy/cedex-grasp/blob/main/vis_cedex.py"
    click vis_generated "https://github.com/georgewuzy/cedex-grasp/blob/main/vis_generated_grasp.py"
    click utils_viz "https://github.com/georgewuzy/cedex-grasp/tree/main/utils/"
```
