Upload README.md

README.md

@@ -1,118 +1,214 @@
+# LightweightMR — Mesh from Point Cloud (Beginner Guide)
+
+> **TL;DR** — Give it a `.ply` / `.pcd` / `.xyz` file full of 3D points, and it spits out a nice triangle mesh (`.ply` or `.obj`).
+>
+> Only depends on **PyTorch + NumPy + SciPy**. No CUDA compiling, no Open3D, no CGAL.
+
 ---
-tags:
-- ml-intern
----
-# 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.)
+## 🧭 What does this actually do?
+
+Imagine you have a laser scan of a statue — millions of dots floating in space. This code turns those dots into a **solid surface** made of triangles.
+
+It does this in **two stages**:
+
+```
+Point Cloud          Stage 1: Learn SDF           Stage 2: Mesh
+(just dots)    →   (learn a "distance field")  →  (triangles!)
+```
+
+### Stage 1 — Learning a Distance Field (SDF)
+The code trains a small neural network to answer:
+
+> *"For any random 3D point, how far is it from the surface, and which side is it on?"*
+
+Positive = outside, negative = inside, zero = exactly on the surface.
+
+It learns this purely from your point cloud — no camera images, no manual labels.
 
-Input: **PLY / PCD / XYZ point cloud**  
-Output: **Triangle mesh (PLY / OBJ)**
+### Stage 2 — Building the Mesh
+Now that the network knows inside vs. outside, the code:
+
+1. Sprinkles candidate vertices near the surface
+2. Uses another tiny network to nudge them onto high-detail areas (curvature)
+3. Projects them exactly onto the zero-distance surface
+4. Builds a **3D Delaunay triangulation** (like connecting dots with tetrahedra)
+5. Labels each tetrahedron as "inside" or "outside"
+6. The walls between inside/outside *are* your surface → extracted as triangles
+7. Cleans up non-manifold edges by adding midpoints
 
 ---
 
-## Quick Start
+## 🚀 Quick Start (5 minutes)
+
+### 1. Install
 
 ```bash
-# Install
 pip install torch numpy scipy
+```
+
+That's it. No C++ compilers, no 2 GB dependencies.
 
-# Run
-python -m lightweightmr -i myscan.ply -o mesh.ply
+### 2. Try on a synthetic sphere (no data needed)
+
+We included a tiny script that makes a fake point cloud so you can see it work immediately:
+
+```bash
+# Download / clone the repo files, then:
+python example/make_sphere.py        # creates example/sphere.ply (3000 points)
+python -m lightweightmr -i example/sphere.ply -o example/sphere_mesh.ply --device cpu
 ```
 
-Or use the Python API:
+The second command will:
+- Print progress bars for SDF training (~20k steps)
+- Print progress bars for vertex generation (~8k steps)
+- Save `example/sphere_mesh.ply`
 
-```python
-from lightweightmr.optimize import Runner
+**On CPU this takes ~20–40 minutes.** On a CUDA GPU (`--device cuda`) it's ~2–4 minutes.
+
+### 3. Use your own scan
 
-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")
+```bash
+python -m lightweightmr -i myscan.ply -o mymesh.ply --device cpu
 ```
 
+Supported inputs: `.ply` (ASCII or binary), `.pcd`, `.xyz`
+
 ---
 
-## Two-Stage Pipeline
+## 📂 What files do I need?
 
-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.
+You only need the `lightweightmr/` folder (9 Python files). Nothing else.
+
+```
+lightweightmr/
+  __init__.py          # package marker
+  __main__.py          # CLI (the command you run)
+  optimize.py          # the two-stage runner (Stage 1 + Stage 2)
+  sdfnet.py            # neural network for distance field
+  vgnet.py             # neural network for vertex placement
+  losses.py            # math that teaches the networks
+  meshing.py           # Delaunay + surface extraction
+  embedder.py          # positional encoding (helps the networks)
+  io_utils.py          # loading PLY/PCD/XYZ, saving meshes
+```
 
 ---
 
-## Differences from Original
+## ⚙️ CLI Options Explained
 
-| 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** |
+| Flag | Default | What it means |
+|------|---------|---------------|
+| `-i` / `--input` | **required** | Your point cloud file |
+| `-o` / `--output` | **required** | Output mesh file (`.ply` or `.obj`) |
+| `--device` | `cpu` | `cpu` or `cuda`. GPU is much faster. |
+| `--sdf-iters` | `20000` | How long to train the distance field. More = better quality on noisy scans. |
+| `--vg-iters` | `8000` | How long to train vertex placement. |
+| `--vertices` | `3400` | Target number of vertices in final mesh. More = finer detail, slower. |
+| `--k-samples` | `21` | Samples per tetrahedron when labeling inside/outside. Higher = cleaner mesh, slower. |
+| `--save-freq` | `2000` | Save a checkpoint every N iterations (so you can resume). |
+| `--resume-sdf` | — | Path to a `.pth` checkpoint to skip Stage 1. |
 
-**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.
+### Common recipes
 
----
+**Fast preview (lower quality):**
+```bash
+python -m lightweightmr -i scan.ply -o mesh.ply --sdf-iters 5000 --vg-iters 2000 --vertices 800
+```
 
-## CLI Reference
+**High quality (slower):**
+```bash
+python -m lightweightmr -i scan.ply -o mesh.ply --sdf-iters 40000 --vg-iters 12000 --vertices 10000
+```
 
+**Resume after Stage 1 crash:**
+```bash
+python -m lightweightmr -i scan.ply -o mesh.ply --resume-sdf output/sdf_checkpoints/sdf_final.pth
 ```
-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
+
+---
+
+## 🐍 Python API (for scripts)
+
+If you want to call it from your own code instead of the command line:
+
+```python
+from lightweightmr.optimize import Runner
+
+runner = Runner(
+    pointcloud_path="myscan.ply",
+    out_dir="./output",
+    device="cpu",          # or "cuda"
+    sdf_iters=20_000,
+    vg_iters=8_000,
+    vertices_size=3_400,
+)
+
+# Run both stages
+vertices, faces = runner.run(mesh_path="mymesh.ply")
+
+# Or run stages separately:
+runner.train_sdf()                       # Stage 1
+verts = runner.train_vg()                # Stage 2
+v, f = runner.generate_mesh(verts, save_path="mymesh.ply")
 ```
 
 ---
 
-## Package Structure
+## 🧪 Understanding the Output
+
+After running, you'll see a new folder `./output/` with:
 
 ```
-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
+output/
+  sdf_checkpoints/
+    sdf_final.pth          # trained distance field (can resume from this)
 ```
 
+And your chosen output file (`-o mesh.ply`) contains the mesh.
+
+You can view `.ply` meshes with:
+- **Blender** (free, drag & drop)
+- **MeshLab** (free)
+- **Windows 3D Viewer**
+
 ---
 
-## Tips
+## 🛠️ Troubleshooting
 
-- **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`.
+| Problem | Likely cause | Fix |
+|---------|--------------|-----|
+| Takes forever | CPU training | Use `--device cuda` if you have a GPU |
+| Output mesh has holes | Not enough vertices | Increase `--vertices` |
+| Noisy / wobbly mesh | Noisy input + too few SDF iters | Increase `--sdf-iters` to `30000+` |
+| `ModuleNotFoundError` | Missing dependency | `pip install torch numpy scipy` |
+| `ValueError` on `.ply` | Binary PLY variant we don't parse | Convert to ASCII PLY in MeshLab/Blender |
 
 ---
 
-## Citation
+## 📖 How is this different from the original paper?
+
+The original CVPR 2025 code is **powerful but heavy** — it needs:
+- CUDA-compiled hash encoders
+- CGAL (C++ geometry library)
+- Open3D, `torch_scatter`, `spconv`, `fpsample`, `mcubes`, `trimesh`
+
+This reimplementation replaces all of that with pure Python + PyTorch + SciPy:
+
+| Original | This version |
+|----------|--------------|
+| CUDA hash grid | Positional encoding (slower but no compile) |
+| PointTransformerV3 vertex generator | Simple MLP (faster, no extra deps) |
+| CGAL Delaunay + meshing | SciPy Delaunay + our own surface extractor |
+| C++ KDTree | SciPy KDTree |
+
+**Trade-off:** The SDF stage may need a few more iterations on very detailed scans, but the output quality is comparable for most shapes.
+
+---
+
+## 📚 Citation
+
+If you use this, cite the original paper:
 
 ```bibtex
 @inproceedings{zhang2025high,
@@ -127,23 +223,3 @@ lightweightmr/
 ---
 
 License: MIT (reimplementation). Original paper and code © authors.
-
-<!-- ml-intern-provenance -->
-## Generated by ML Intern
-
-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
-
-## Usage
-
-```python
-from transformers import AutoModelForCausalLM, AutoTokenizer
-
-model_id = "bdck/lightweightmr"
-tokenizer = AutoTokenizer.from_pretrained(model_id)
-model = AutoModelForCausalLM.from_pretrained(model_id)
-```
-
-For non-causal architectures, replace `AutoModelForCausalLM` with the appropriate `AutoModel` class.