---
title: Point Cloud Registration
emoji: 🧊
colorFrom: blue
colorTo: gray
sdk: gradio
app_file: app.py
python_version: "3.10"
pinned: false
---

# Point Cloud Registration Demo

Interactive Gradio application for **pairwise point cloud registration** using Open3D and 3DMatch RedKitchen fragments.

## Features

- **Demo Pairs**: Pre-selected point cloud pairs from 3DMatch RedKitchen dataset
- **Upload Mode**: Register your own point clouds
- **Multiple Algorithms**: 
  - RANSAC + ICP (global + local)
  - RANSAC only (global)
  - ICP only (local)
- **Hyperparameter Control**: Voxel size, normal radius, FPFH radius, RANSAC iterations, ICP iterations
- **Visualization**: Before/after 3D point clouds with colors
- **Metrics**: Fitness, RMSE, transformation matrix
- **Download**: Save aligned source point cloud

## Usage

### Run Locally

```bash
pip install -r requirements.txt
python app.py
```

Then open `http://localhost:7860` in your browser.

## Data Source

**3DMatch Geometric Registration Benchmark** - RedKitchen Scene
- Fragment dataset: Point clouds integrated from 50 depth frames using TSDF fusion
- Evaluation files: Ground-truth transformation matrices
- Reference: https://3dmatch.cs.princeton.edu/

## Pipeline

1. **Load** source and target point clouds
2. **Preprocess**: Remove non-finite points, remove duplicates, voxel downsample
3. **Features**: Estimate normals, compute FPFH descriptors
4. **Global Registration**: RANSAC-based feature matching
5. **Local Registration**: ICP refinement
6. **Visualization**: Before/after 3D views with metrics

## Project Structure

```
├── app.py                          # Main Gradio application
├── requirements.txt                # Python dependencies
├── packages.txt                    # System dependencies
├── README.md                       # This file
│
├── scripts/
│   ├── inspect_3dmatch.py         # Inspect dataset structure
│   ├── build_pair_index.py        # Parse evaluation logs
│   ├── benchmark_pairs.py         # Benchmark pairs with Open3D
│   └── prepare_demo_pairs.py      # Prepare examples for demo
│
├── examples/
│   ├── pair_metadata.json         # Demo pair metadata
│   ├── redkitchen_pair_01_source.ply
│   ├── redkitchen_pair_01_target.ply
│   └── ...
│
└── data/
    ├── raw/3dmatch/               # (local only, not pushed)
    └── processed/                 # (local only, not pushed)
```

## Development

### Prepare Data Locally

```bash
# Download and unzip
mkdir -p data/raw/3dmatch
cd data/raw/3dmatch
wget https://3dvision.princeton.edu/projects/2016/3DMatch/downloads/fragments/7-scenes-redkitchen.zip
wget https://3dvision.princeton.edu/projects/2016/3DMatch/downloads/fragments/7-scenes-redkitchen-evaluation.zip
unzip -q 7-scenes-redkitchen.zip
unzip -q 7-scenes-redkitchen-evaluation.zip
cd ../../..

# Inspect
python scripts/inspect_3dmatch.py

# Build index
python scripts/build_pair_index.py

# Benchmark
python scripts/benchmark_pairs.py

# Prepare examples
python scripts/prepare_demo_pairs.py
```

## Notes

- Point clouds are stored using Git LFS (.gitattributes configured)
- Raw dataset and processed data are not pushed to repository
- Demo pairs are downsampled for performance (typically 30k-60k points)