| --- |
| 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.) |
|
|
| Input: **PLY / PCD / XYZ point cloud** |
| Output: **Triangle mesh (PLY / OBJ)** |
|
|
| --- |
|
|
| ## 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") |
| ``` |
|
|
| --- |
|
|
| ## Two-Stage Pipeline |
|
|
| 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. |
|
|
| --- |
|
|
| ## Differences from Original |
|
|
| | 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** | |
|
|
| **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 |
|
|
| ``` |
| 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} |
| } |
| ``` |
|
|
| --- |
|
|
| 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. |
|
|
