# dougsm/ggcnn architecture

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

- Interactive diagram: https://gitdiagram.com/dougsm/ggcnn
- Repository: https://github.com/dougsm/ggcnn

## Overview

##### Project type and purpose
- This is an open-source robotics/machine-learning tool (a PyTorch port of the GG-CNN) for real-time, pixel-wise generative grasp synthesis from depth images.
- It provides data loaders for the Cornell and Jacquard datasets, scripts for preprocessing, training (`train_ggcnn.py`), evaluating (`eval_ggcnn.py`), and visualization, and two model definitions (`ggcnn.py`, `ggcnn2.py`).

##### File structure
- Top level:
- `train_ggcnn.py`, `eval_ggcnn.py` – entry-point scripts for training and evaluation.
- `models/` – network definitions and common utilities.
- `utils/` – data ingestion (`utils/data/`), dataset processing (`utils/dataset_processing/`), timing helpers, visualization (`utils/visualisation/`).
- `requirements.txt` – external dependencies (PyTorch, NumPy, etc.).
- Patterns: single-process, modular ML pipeline (data → preprocessing → model → training/eval → visualization).
- External assets: Cornell and Jacquard datasets; optional ROS integration in separate repos.

##### README insights
- Describes data preparation steps and supported datasets.
- Details how to load pretrained weights or train from scratch.
- Highlights evaluation options (IoU metric, Jacquard output).

##### Detailing is key
- That `train_ggcnn.py` invokes the `GGCNN` or `GGCNN2` class from `models/`.
- Outputs folder (`output/models`) as a persistent artifact store.
- Don’t hesitate to add as many components as exist in the codebase—better to show every major folder and script.
- Component boundaries reflect actual file/package boundaries for easy mapping back to source code.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data Sources
    subgraph "External Data Sources"
        direction TB
        Cornell["Cornell Dataset"]:::externalData
        Jacquard["Jacquard Dataset"]:::externalData
        GraspData["Grasp Data Loader"]:::externalData
    end

    %% Utils Layer
    subgraph "Utils" 
        direction TB
        subgraph "Data Ingestion"
            DataIngestion["Data Ingestion Module"]:::code
        end
        subgraph "Preprocessing Pipeline"
            DepthConv["Depth Conversion"]:::code
            Augmentation["Augmentation & Grasp Processing"]:::code
            ImageUtils["Image Utilities"]:::code
            EvalRoutines["Evaluation Routines"]:::code
        end
        subgraph "Visualization"
            Gridshow["Gridshow Visualization"]:::code
        end
        Timeit["Timing Utilities"]:::code
    end

    %% Models Layer
    subgraph "Model Definitions"
        Common["Common Utilities"]:::code
        GGCNN["GG-CNN v1 Model"]:::code
        GGCNN2["GG-CNN v2 Model"]:::code
    end

    %% Entry-point Scripts
    Train["Training Orchestrator"]:::script
    Eval["Evaluation Script"]:::script

    %% Artifacts
    TrainedModel["Trained Models Store"]:::artifact
    Metrics["Metrics / Rendered Images"]:::artifact

    %% Data Flow
    Cornell -->|loads| DataIngestion
    Jacquard -->|loads| DataIngestion
    GraspData -->|provides| DataIngestion

    DataIngestion -->|feeds| DepthConv
    DepthConv --> Augmentation
    Augmentation --> ImageUtils
    ImageUtils --> EvalRoutines
    EvalRoutines --> Train

    Train -->|uses| Common
    Train -->|uses| GGCNN
    Train -->|uses| GGCNN2
    Train -->|saves| TrainedModel

    TrainedModel --> Eval
    Eval -->|uses| Common
    Eval -->|uses| GGCNN
    Eval -->|uses| GGCNN2
    Eval -->|generates| Metrics

    Eval --> Gridshow
    Gridshow --> Metrics

    TrainedModel -.->|optional| ROS["ROS Integration"]:::externalIntegration

    %% Click Events
    click Cornell "https://github.com/dougsm/ggcnn/blob/master/utils/data/cornell_data.py"
    click Jacquard "https://github.com/dougsm/ggcnn/blob/master/utils/data/jacquard_data.py"
    click GraspData "https://github.com/dougsm/ggcnn/blob/master/utils/data/grasp_data.py"
    click DataIngestion "https://github.com/dougsm/ggcnn/tree/master/utils/data/"
    click DepthConv "https://github.com/dougsm/ggcnn/blob/master/utils/dataset_processing/generate_cornell_depth.py"
    click Augmentation "https://github.com/dougsm/ggcnn/blob/master/utils/dataset_processing/grasp.py"
    click ImageUtils "https://github.com/dougsm/ggcnn/blob/master/utils/dataset_processing/image.py"
    click EvalRoutines "https://github.com/dougsm/ggcnn/blob/master/utils/dataset_processing/evaluation.py"
    click Common "https://github.com/dougsm/ggcnn/blob/master/models/common.py"
    click GGCNN "https://github.com/dougsm/ggcnn/blob/master/models/ggcnn.py"
    click GGCNN2 "https://github.com/dougsm/ggcnn/blob/master/models/ggcnn2.py"
    click Train "https://github.com/dougsm/ggcnn/blob/master/train_ggcnn.py"
    click Eval "https://github.com/dougsm/ggcnn/blob/master/eval_ggcnn.py"
    click Gridshow "https://github.com/dougsm/ggcnn/blob/master/utils/visualisation/gridshow.py"
    click Timeit "https://github.com/dougsm/ggcnn/blob/master/utils/timeit.py"
    click Requirements "https://github.com/dougsm/ggcnn/blob/master/requirements.txt"

    %% Styles
    classDef externalData fill:#a8dadc,stroke:#457b9d,stroke-width:1px
    classDef code fill:#d0ebff,stroke:#1d3557,stroke-width:1px
    classDef script fill:#caf0f8,stroke:#0077b6,stroke-width:1px
    classDef artifact fill:#ffedcc,stroke:#e76f51,stroke-width:1px
    classDef externalIntegration stroke-dasharray: 5 5,stroke:#e63946,fill:none
```
