Upload README.md

README.md

@@ -1,26 +1,125 @@
+# LightweightMR — Pure-Python Mesh Reconstruction
+
+Pure-Python reimplementation of **["High-Fidelity Lightweight Mesh Reconstruction from Point Clouds"](https://openaccess.thecvf.com/content/CVPR2025/papers/Zhang_High-Fidelity_Lightweight_Mesh_Reconstruction_from_Point_Clouds_CVPR_2025_paper.pdf)** (CVPR 2025 Highlight, Zhang et al.)
+
+Input: **PLY / PCD / XYZ point cloud**  
+Output: **Triangle mesh (PLY / OBJ)**
+
 ---
-tags:
-- ml-intern
+
+## Quick Start
+
+```bash
+# Install
+pip install torch numpy scipy
+
+# Run
+python -m lightweightmr -i myscan.ply -o mesh.ply
+```
+
+Or use the Python API:
+
+```python
+from lightweightmr.optimize import Runner
+
+runner = Runner("myscan.ply", out_dir="./output", device="cpu")
+v, f = runner.run(mesh_path="mesh.ply")
+print(f"Mesh: {len(v)} vertices, {len(f)} faces")
+```
+
 ---
 
-# bdck/lightweightmr
+## Two-Stage Pipeline
 
-<!-- ml-intern-provenance -->
-## Generated by ML Intern
+1. **SDF Learning** — Train a coordinate MLP with positional encoding to fit an implicit signed distance field to the point cloud.
+2. **Vertex Generation + Delaunay Meshing** —
+   - Sample surface queries using SDF gradient projection.
+   - Train a vertex generator (MLP-only, no PointTransformerV3) to displace initial FPS samples.
+   - Move vertices to the learned SDF surface.
+   - Build a 3D Delaunay triangulation (`scipy.spatial.Delaunay`).
+   - Label tetrahedra as inside/outside by sampling the SDF.
+   - Extract the surface as facets between differently-labeled cells.
+   - Post-process with midpoint-vertex insertion to fix non-manifold edges.
 
-This model repository was generated by [ML Intern](https://github.com/huggingface/ml-intern), an agent for machine learning research and development on the Hugging Face Hub.
+---
 
-- Try ML Intern: https://smolagents-ml-intern.hf.space
-- Source code: https://github.com/huggingface/ml-intern
+## Differences from Original
 
-## Usage
+| Feature | Original | This Reimplementation |
+|---------|----------|------------------------|
+| Hash encoding | CUDA hash grid + triplane | Positional encoding only (no CUDA compilation) |
+| Vertex generator | PointTransformerV3 + MLP | MLP-only (faster, no `spconv`/`torch_scatter`) |
+| KDTree | C++ libkdtree | `scipy.spatial.KDTree` |
+| Delaunay meshing | CGAL C++ binary | `scipy.spatial.Delaunay` |
+| Mesh extraction | CGAL `create_mesh` | Pure Python facet extraction |
+| Dependencies | Open3D, CGAL, boost, `fpsample`, `mcubes`, `trimesh`, `torch_scatter`, `spconv` | **Only torch, numpy, scipy** |
 
-```python
-from transformers import AutoModelForCausalLM, AutoTokenizer
+**Trade-off**: Without the original hash encoding, the SDF stage converges slightly slower and may need a few more iterations on highly detailed scans. The meshing quality is comparable for typical genus-0/1 shapes.
+
+---
+
+## CLI Reference
 
-model_id = "bdck/lightweightmr"
-tokenizer = AutoTokenizer.from_pretrained(model_id)
-model = AutoModelForCausalLM.from_pretrained(model_id)
 ```
+python -m lightweightmr -i INPUT.ply -o OUTPUT.ply [options]
+
+Options:
+  --device                cpu | cuda        (default: cpu)
+  --sdf-iters             20000             SDF training iterations
+  --vg-iters              8000              Vertex generator iterations
+  --sdf-lr                0.001
+  --vg-lr                 0.001
+  --sdf-batch             5000              Batch size for SDF queries
+  --vertices              3400              Target vertex count
+  --update-size           5                 Curriculum update steps
+  --update-ratio          1.2               Vertex count growth ratio
+  --k-samples             21                Interior samples per tetrahedron
+  --multires              8                 Positional encoding frequencies
+  --project-sdf-level     0.0               Surface SDF level
+  --save-freq             2000              Checkpoint frequency
+  --resume-sdf            PATH.pth          Resume from SDF checkpoint
+```
+
+---
+
+## Package Structure
+
+```
+lightweightmr/
+  __init__.py
+  embedder.py      — Positional encoding (NeRF-style)
+  sdfnet.py        — SDF MLP network
+  vgnet.py         — Vertex generator MLP
+  losses.py        — All loss functions (Chamfer, eikonal, divergence, curvature, normals)
+  meshing.py       — Delaunay + SDF labeling + surface extraction + midpoint fix
+  io_utils.py      — PLY/PCD/XYZ loaders, mesh exporters, FPS, normal estimation
+  optimize.py      — Two-stage Runner (SDF then VG + meshing)
+  __main__.py      — CLI entry point
+```
+
+---
+
+## Tips
+
+- **CPU-only is slow** — SDF training on CPU with 20k iterations takes ~30–60 min depending on your machine. If you have a GPU, use `--device cuda`.
+- **Vertex count** — Increase `--vertices` for finer detail (slower meshing). Decrease for faster/cleaner low-poly results.
+- **Noise** — If your point cloud is noisy, increase `--sdf-iters` to 30k+ and use a small `--project-sdf-level` (e.g. `0.001`) to pull slightly inward.
+- **Large clouds** — The code automatically subsamples to ~1/60th of input points for the SDF training set. For very large scans, reduce `--queries-size`.
+
+---
+
+## Citation
+
+```bibtex
+@inproceedings{zhang2025high,
+  title={High-Fidelity Lightweight Mesh Reconstruction from Point Clouds},
+  author={Zhang, Chen and Wang, Wentao and Li, Ximeng and Liao, Xinyao and Su, Wanjuan and Tao, Wenbing},
+  booktitle={CVPR},
+  pages={11739--11748},
+  year={2025}
+}
+```
+
+---
 
-For non-causal architectures, replace `AutoModelForCausalLM` with the appropriate `AutoModel` class.
+License: MIT (reimplementation). Original paper and code © authors.