README.md

# Point2Mesh — A Self-Prior for Deformable Meshes

Pure Python/PyTorch reimplementation of **[Point2Mesh (SIGGRAPH 2020)](https://arxiv.org/abs/2005.11084)** by Hanocka et al.

**Input:** a point cloud (`.ply`, `.pcd`, `.xyz`, `.obj`)  
**Output:** a shrink-wrapped triangle mesh (`.obj`, `.ply`, `.stl`)

No training data needed — the method optimises a single CNN per shape at inference time, exploiting the network's architectural bias toward self-similar structure as a shape prior.

---

## Quick Start

```bash
# Install
pip install torch numpy scipy
git clone https://huggingface.co/bdck/point2mesh
cd point2mesh

# Run
python -m point2mesh --input my_cloud.ply --output mesh.obj

# Quick test (fast, lower quality)
python -m point2mesh -i cloud.ply -o mesh.obj --n-levels 2 --iters 200 --init-faces 500

# Full quality
python -m point2mesh -i cloud.ply -o mesh.obj --n-levels 5 --iters 1500 --max-faces 40000 --device cuda
```

## How It Works

```
Point Cloud ──→ Convex Hull ──→ [ CNN optimisation ] ──→ Shrink-wrapped Mesh
                  (coarse)        (coarse-to-fine)           (detailed)
```

1. **Initialise** a coarse mesh from the convex hull of the input points
2. **Optimise** a MeshCNN U-Net to deform the mesh surface toward the point cloud:
   - The CNN input is fixed random noise (not the geometry)
   - The CNN outputs per-vertex displacements
   - Losses: bidirectional Chamfer distance + beam-gap loss + normal alignment
3. **Remesh** (subdivide + decimate) and repeat at finer resolution
4. **Export** the final mesh

The key insight is the **self-prior**: the CNN architecture itself acts as a regulariser, preferring coherent, self-similar deformations over noise. No external training data is used.

## CLI Reference

```
python -m point2mesh [OPTIONS]

Required:
  --input, -i         Input point cloud (.ply, .pcd, .xyz, .obj)
  --output, -o        Output mesh (.obj, .ply, .stl)

Optimisation:
  --n-levels          Coarse-to-fine levels (default: 4)
  --iters             Iterations per level (default: 1000)
  --lr                Learning rate (default: 0.0002)
  --samples-start     Surface samples at iter 0 (default: 15000)
  --samples-end       Surface samples at final iter (default: 50000)

Mesh resolution:
  --init-faces        Initial mesh face count (default: 2000)
  --face-growth       Face multiplier between levels (default: 1.5)
  --max-faces         Stop subdividing above this (default: 20000)

Loss weights:
  --lambda-beam       Beam-gap loss weight (default: 1.0)
  --lambda-normal     Normal alignment weight (default: 0.1)
  --beam-epsilon      Beam cylinder radius (default: 0.5)

Network:
  --in-channels       Random input features per edge (default: 6)
  --enc-channels      Encoder widths (default: 64 128 256 256)

Memory:
  --part-threshold    Use PartMesh above this face count (default: 10000)
  --n-parts           Spatial grid res for PartMesh (default: 2)

Output:
  --device            torch device (auto-detect if omitted)
  --save-intermediates  Save mesh after each level
  --output-dir        Directory for intermediates (default: .)
  --log-every         Print loss every N iters (default: 50)
  --verbose, -v       Debug logging
```

## Python API

```python
from point2mesh.optimize import run_point2mesh, Point2MeshConfig

cfg = Point2MeshConfig(
    n_levels=4,
    iters_per_level=1000,
    init_faces=2000,
    max_faces=20000,
    device="cuda",
)

run_point2mesh("cloud.ply", "mesh.obj", cfg)
```

### With progress callback

```python
def on_progress(level, iteration, loss):
    print(f"Level {level}, iter {iteration}: loss = {loss:.6f}")

run_point2mesh("cloud.ply", "mesh.obj", cfg, progress_callback=on_progress)
```

## Architecture

```
point2mesh/
├── __init__.py      # Package root
├── __main__.py      # CLI entry point
├── mesh.py          # Mesh data structure + edge topology + PartMesh
├── layers.py        # MeshCNN conv / pool / unpool
├── network.py       # Point2Mesh U-Net (encoder-decoder)
├── losses.py        # Chamfer, beam-gap, normal alignment, surface sampling
├── optimize.py      # Main optimisation loop
└── io_utils.py      # PCD/PLY/XYZ/OBJ loaders, mesh exporters, remeshing
```

### Module Details

| Module | Description |
|--------|-------------|
| `mesh.py` | Half-edge-style mesh with GEMM adjacency for MeshCNN. Builds edge→4-neighbor topology. `PartMesh` splits large meshes into spatial sub-grids. |
| `layers.py` | **MeshConv**: edge convolution with symmetric neighbor aggregation `[e, \|a−c\|, a+c, \|b−d\|, b+d]`. **MeshPool**: edge collapse by L2-norm priority. **MeshUnpool**: topology restoration from stored history. |
| `network.py` | U-Net encoder-decoder on edges. Input: fixed random noise. Output: per-edge vertex displacements `[N_e, 2, 3]`. Output head initialised to zero (no initial displacement). |
| `losses.py` | Bidirectional Chamfer distance (batched for large clouds). Beam-gap loss with ε-cylinder and mutual k-NN skip. Unoriented normal alignment `1 − \|n₁·n₂\|`. Differentiable area-weighted surface sampling. |
| `optimize.py` | Full coarse-to-fine loop. Re-initialises network + noise each level. Linear sample-count ramp. Remeshing (subdivide → smooth → decimate) between levels. |
| `io_utils.py` | Zero-dependency PCD/PLY/XYZ/OBJ loaders (binary + ASCII). OBJ/PLY/STL mesh writers. Convex hull initialisation. PCA-based normal estimation. Midpoint subdivision, Laplacian smoothing, greedy edge-collapse decimation. |

## Dependencies

Only **three** packages:

- `torch >= 2.0` — autograd, GPU acceleration
- `numpy >= 1.24` — array operations
- `scipy >= 1.10` — convex hull, KD-tree for normal estimation

No Open3D, no PyTorch3D, no trimesh, no pymeshlab.

## Performance Tips

| Scenario | Recommendation |
|----------|---------------|
| Quick preview | `--n-levels 2 --iters 200 --init-faces 500` |
| Standard quality | Default settings (4 levels, 1000 iters) |
| High quality | `--n-levels 5 --iters 1500 --max-faces 40000` |
| Large point clouds (>100k pts) | Use GPU (`--device cuda`) |
| High-res meshes (>10k faces) | PartMesh auto-activates; tune `--n-parts 3` if OOM |
| CPU only | Works, but ~10× slower than GPU |

## Differences from Original Implementation

| Aspect | Original | This reimplementation |
|--------|----------|----------------------|
| Remeshing | RWM (Robust Watertight Manifold, external C++ binary) | Midpoint subdivision + Laplacian smooth + greedy decimation |
| Mesh pooling | Full half-edge data structure with manifold guards | Simplified edge collapse with adjacency redirect |
| Dependencies | PyTorch, Open3D, numpy, scipy, CUDA ops | PyTorch, numpy, scipy only |
| Initial mesh (genus > 0) | Alpha shape → coarse RWM | Convex hull (genus-0 assumption) |

The main simplification is the remeshing step: the original uses the external [Manifold](https://github.com/hjwdzh/Manifold) binary for guaranteed watertight, non-self-intersecting output between levels. This reimplementation uses pure-Python subdivision + decimation which works well for most shapes but may produce self-intersections on complex topology.

## Citation

```bibtex
@article{hanocka2020point2mesh,
  title   = {Point2Mesh: A Self-Prior for Deformable Meshes},
  author  = {Hanocka, Rana and Metzer, Gal and Giryes, Raja and Cohen-Or, Daniel},
  journal = {ACM Transactions on Graphics (TOG)},
  volume  = {39},
  number  = {4},
  year    = {2020},
  publisher = {ACM}
}
```