Skip to content

README.md

Latest commit

 

History

History
266 lines (196 loc) · 8.68 KB

README.md

File metadata and controls

266 lines (196 loc) · 8.68 KB

SGG-Net: Skeleton and Graph-Based Neural Network for Grasping Objects

Python PyTorch License DOI

An integrated framework combining geometric skeletonization with Graph Neural Networks for optimal 6-DoF grasp pose estimation

This repository contains the implementation of SGG-Net, an integrated framework that combines geometric skeletonization (3D-StSkel algorithm) with a Graph Neural Network (HGGQ-Net) to identify optimal grasp poses for robotic manipulation.

🎯 Key Features

  • Geometric Skeletonization: 3D-StSkel algorithm extracts geometrically salient regions for efficient grasp candidate generation
  • Graph Neural Network: HGGQ-Net evaluates and ranks grasp candidates based on quality
  • State-of-the-Art Performance: Achieves 90.74% on DexNet, 81.63% on EGAD, and 97.30% on YCB objects
  • Comprehensive Evaluation: Supports evaluation on GraspNet-1Billion, DexNet, EGAD, and YCB datasets
  • Modular Design: Clean, well-organized codebase ready for research and deployment

📋 Overview

SGG-Net consists of two main components:

  1. 3D-StSkel Algorithm: Generates initial grasp pose candidates by extracting geometrically salient regions using straight skeleton computation
  2. Heatmap Graph Grasp Quality Network (HGGQ-Net): A graph neural network that evaluates and ranks these candidates based on their quality

Architecture

Point Cloud → 3D-StSkel → Grasp Candidates → HGGQ-Net → Ranked Grasps

The method significantly reduces the search space, enabling faster and more reliable 6-DoF grasp pose estimation.

🚀 Installation

Requirements

  • Python 3.8+
  • CUDA-capable GPU (recommended for training and inference)
  • PyTorch 2.0+
  • CUDA 11.4+ (for GPU support)

Quick Start

  1. Clone the repository:

    git clone https://github.com/TaarLab/SGG-Net.git
cd SGG-Net

  2. Create a virtual environment (recommended):

    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

  3. Install dependencies:

    pip install -r requirements.txt

  4. Install PyTorch Geometric:

    pip install torch_geometric torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-2.5.1+cu124.html

    Note: Adjust the PyTorch version in the URL based on your installed PyTorch version.

💻 Usage

Training

Train the HGGQ-Net model on GraspNet dataset:

python train.py \
    --dataset_root /path/to/graspnet \
    --camera realsense \
    --num_points 10000 \
    --batch_size 1 \
    --max_epoch 11 \
    --mode optimize_parameter

Key Arguments:

  • --dataset_root: Path to GraspNet dataset root directory
  • --camera: Camera type (realsense or kinect)
  • --num_points: Number of points to sample from point cloud
  • --batch_size: Batch size for training
  • --max_epoch: Maximum number of training epochs
  • --checkpoint_path: (Optional) Path to checkpoint for resuming training

Testing/Evaluation

Evaluate the model on GraspNet test set:

python test.py \
    --dataset_root /path/to/graspnet \
    --checkpoint_path /path/to/checkpoint.tar \
    --dump_dir /path/to/output \
    --camera realsense \
    --split seen \
    --num_point 4096 \
    --collision_thresh 0.01

Splits:

  • seen: Objects seen during training
  • similar: Similar objects to training set
  • novel: Novel objects not in training set

Demo

Run inference on a single point cloud:

python demo.py \
    --checkpoint_path /path/to/checkpoint.tar \
    --point_cloud /path/to/pointcloud.ply \
    --topk 50 \
    --collision_thresh 0.01

Supported Point Cloud Formats:

  • .ply (PLY format)
  • .pcd (PCD format)
  • .npy (NumPy array format)

📊 Dataset

This codebase is designed to work with the GraspNet-1Billion dataset. Please refer to the GraspNet repository for dataset download and setup instructions.

Dataset Structure

graspnet/
├── scenes/
│   ├── scene_0000/
│   │   ├── realsense/
│   │   └── kinect/
│   └── ...
├── models/
└── ...

Supported Datasets

  • GraspNet-1Billion: Large-scale dataset with 190 scenes and over 1 billion grasp poses
  • DexNet: 54 objects for evaluation
  • EGAD: 49 objects categorized by complexity
  • YCB: 37 household objects

📁 Project Structure

SGG-NET/
├── sggnet/                          # Main package
│   ├── skeleton/                     # Skeleton generation module
│   │   ├── keypoint_generation.py   # 3D-StSkel algorithm
│   │   └── skeleton_grasp.py        # Main skeleton grasp interface
│   ├── models/                      # Neural network models
│   │   ├── hggqnet.py              # HGGQ-Net architecture
│   │   └── loss.py                 # Loss functions
│   ├── dataset/                     # Dataset handling
│   │   ├── graspnet_dataset.py     # GraspNet dataset loader
│   │   └── data_utils.py           # Data utilities
│   ├── evaluation/                  # Evaluation modules
│   │   ├── graspnet_evaluator.py   # GraspNet evaluation
│   │   ├── collision_detector.py   # Collision detection
│   │   └── average_precision.py    # AP calculation
│   ├── dexnet_evaluation/            # DexNet evaluation
│   ├── preprocessing/spnet/          # SPNet depth completion
│   ├── utils/                       # Utility functions
│   ├── visualization/               # Visualization tools
│   └── graspnetAPI/                 # GraspNet API
├── train.py                         # Training script
├── test.py                          # Testing/evaluation script
├── demo.py                          # Demo script
├── requirements.txt                 # Dependencies
├── setup.py                        # Package setup
└── README.md                        # This file

📈 Results

Performance Metrics

Dataset Success Rate Description
YCB 97.30% 36/37 objects successfully grasped
DexNet 90.74% 49/54 objects successfully grasped
EGAD 81.63% 40/49 objects successfully grasped

GraspNet-1Billion Evaluation

Split AP (%) AP₀.₈ (%) AP₀.₄ (%)
Seen 46.99 58.55 32.22
Unseen 42.27 52.21 30.39
Novel 21.14 25.55 11.92

Note: Results are based on Kinect camera evaluation. See the paper for detailed comparisons with other methods.

📚 Citation

If you use this code in your research, please cite:

@article{sggnet2025,
  title={SGG-Net: Skeleton and Graph-Based Neural Network Approaches for Grasping Objects},
  author={Beigy, AliReza and Azimmohseni, Farbod and Sabzejou, Ali and Tale Masouleh, Mehdi and Kalhor, Ahmad},
  journal={2025 33rd International Conference on Electrical Engineering (ICEE)},
  year={2025},
  doi={10.1109/ICEE67339.2025.11213553}
}

DOI: 10.1109/ICEE67339.2025.11213553

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🙏 Acknowledgments

  • GraspNet dataset and API for providing comprehensive evaluation framework
  • PyTorch Geometric for efficient graph neural network operations
  • Open3D for 3D point cloud processing and visualization
  • SPNet authors for depth completion preprocessing

👥 Authors

Human and Robot Interaction Lab, University of Tehran

📧 Contact

For questions or issues, please:

  • Open an issue on GitHub
  • Contact the authors via email

Made with ❤️ by the TaarLab Team

GitHub • Paper