Mesh Untangling

Untangling Surfaces Through Shape and Mesh Repulsion

Forward Untangling  →  Intersection-Aware Shape Recovery

Mesh Untangling v1.0.0 accompanies Untangling Surfaces via Shape and Mesh Repulsion. It provides a CUDA pipeline for removing self-intersections and recovering shape.

✨ Pipeline

Stage	Tool	Result
Forward Flow	mesh-untangle	An intersection-free deformed.obj
Reverse Flow	reverse-flow	A shape-recovered final.obj

🛠️ Build

Requirements

• Linux with an NVIDIA GPU
• CUDA Toolkit and cuDSS
• CMake and a C++20 compiler
• Assimp
• CGAL with GMP and MPFR

Install Assimp and CGAL on Ubuntu or Debian:

sudo apt update
sudo apt install -y libassimp-dev libcgal-dev libgmp-dev libmpfr-dev

Set up the Python 3.12 utilities:

python3.12 -m venv .venv-release
source .venv-release/bin/activate
python -m pip install --require-hashes -r requirements-release.txt

Configure and build:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

➡️ Forward Flow

Run one configuration:

build/bin/Release/mesh-untangle --headless path/to/config.json

Or run directly from a mesh without shape recovery:

python3 scripts/pipeline.py path/to/mesh.obj \
  --output output/my-run \
  --no-reverse-flow

Configuration examples live in configs/.

⬅️ Reverse Flow

Run shape recovery over case folders containing reference.obj and deformed.obj:

build/bin/Release/reverse-flow output/my-run

Results are written to <case>/reverse-flow/final.obj. Run reverse-flow --help for solver options.

🔍 Check Intersections

List self-intersecting face pairs with exact CGAL arithmetic:

build/bin/Release/cgal-intersection-check \
  --obj path/to/mesh.obj \
  --exact \
  --dump-pairs

Mesh Health Check

Check an OBJ before running the solvers:

build/bin/Release/mesh-health-check path/to/mesh.obj --strict

📊 Benchmarking

Benchmark Datasets

The 343-case benchmark uses five dataset directories:

1. ISIR Benchmark (Instant-3D) — 60 cases.
2. SMAL (SMAL) — 49 articulated animal meshes.
3. Analytic Surfaces (math) — 26 analytically constructed surfaces.
4. Microsoft Rocketbox (Microsoft-Rocketbox) — 140 selected assets, each reduced to its largest connected component.
5. SCAPE (SCAPE) — 68 self-intersecting meshes.

Download the redistributable 166-case subset—Analytic Surfaces and Microsoft Rocketbox—from the Mesh Untangling Benchmark on Hugging Face. ISIR, SMAL, and SCAPE must be acquired separately from their respective owners. Contact us about the detailed setup for these datasets.

Install the Hugging Face CLI if needed: python3 -m pip install --upgrade huggingface_hub. Then run the public subset directly:

hf download AppledoreM/Mesh-Untangling-Benchmark \
  --repo-type dataset \
  --local-dir benchmark-data

python3 scripts/run_untangle_benchmark.py \
  --data-root benchmark-data/data \
  --output-root output/public-benchmark \
  --forward-flow-binary build/bin/Release/mesh-untangle \
  --reverse-flow-binary build/bin/Release/reverse-flow \
  --case 'math/*' \
  --case 'Microsoft-Rocketbox/*'

Run from the repository root, keep the case globs quoted, and choose a new --output-root.

Run the ordered 343-case manifest benchmark:

python3 scripts/run_untangle_benchmark.py \
  --data-root /path/to/data \
  --output-root output/release-v1.0.0 \
  --forward-flow-binary build/bin/Release/mesh-untangle \
  --reverse-flow-binary build/bin/Release/reverse-flow

The output directory must not already exist.

Cases, hashes, templates, and settings are in benchmark/datasets.json.

Check Benchmark Intersections

python3 scripts/validate_release_intersections.py \
  --manifest benchmark/datasets.json \
  --output-root output/release-v1.0.0 \
  --cgal-binary build/bin/Release/cgal-intersection-check \
  --summary output/release-v1.0.0/exact-intersections.json

🧰 Other Utilities

Utility	Purpose
scripts/pipeline.py	Run forward and reverse flow
scripts/validate_dataset_manifest.py	Check inputs, hashes, and templates
scripts/obj_patch.py	Copy optimized vertices into an OBJ

Use python3 <script> --help for the complete options of each utility.

⚖️ License

Mesh Untangling is released under the Apache License 2.0. Third-party dependencies keep their own licenses.

Important

A binary linked against the GPL edition of CGAL is governed by GPL-3.0-or-later unless you hold an appropriate commercial CGAL license. Review dependency terms before redistributing binaries.

📝 Citation

If this software contributes to your work, please cite:

Jiří Minarčík, Michael Liu, Keenan Crane, and Minchen Li. 2026. Untangling Surfaces via Shape and Mesh Repulsion. ACM Transactions on Graphics 45, 4, Article 163. https://doi.org/10.1145/3811382

@article{Minarcik2026Untangling,
  author  = {Jiří Minarčík and Michael Liu and Keenan Crane and Minchen Li},
  title   = {Untangling Surfaces via Shape and Mesh Repulsion},
  journal = {ACM Transactions on Graphics},
  volume  = {45},
  number  = {4},
  pages   = {163},
  year    = {2026},
  doi     = {10.1145/3811382}
}

Machine-readable metadata is available in CITATION.cff.