c5efc3d3cc
- LICENSE: Copyright Tarik Moussa <Tarik.moussa95@gmail.com> (war user2595) - CITATION.cff: maschinenlesbares Zitat mit 3 Primärreferenzen (Sechelmann 2016, Springborn 2020, Bobenko–Springborn 2004) - scripts/try_it.sh: Clone→Build→Test→Beispiel in einem Skript - doc/math/software-landscape.md: Landkarte aller relevanten Tools, Problem-A vs. Problem-B Abgrenzung, vollständige Feature-Matrix - doc/math/novelty-statement.md: formales Alleinstellungsmerkmal, Zielgruppen, was dieses Projekt nicht ist - code/CMakeLists.txt: cmake --install Target für Header-only-Library - doc/getting-started.md: Testzähler 158→173, Beispiel-Output, try_it.sh - README.md: CI/License/DOI-Badges, Cite-Abschnitt, Issue-Tracker-Link, Copyright, neue Doku-Einträge software-landscape + novelty-statement Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
5.7 KiB
Software Landscape — Discrete Conformal Geometry Tools
Purpose. A mathematician evaluating conformallab++ needs to know how it relates to existing tools. This document maps the full landscape and explains why no existing library covers the same ground.
1 — The two problems that look the same but are not
The term "conformal parameterization" covers two fundamentally different problems:
Problem A — Conformal distortion minimization (LSCM / ABF++ / ARAP)
Find a UV map u: V → ℝ² that minimises a measure of angle distortion. This is an unconstrained or lightly constrained optimisation over UV coordinates. The solution depends on the embedding in ℝ³ and is not unique — it minimises distortion but does not assign the surface to a canonical conformal class.
Tools: libigl, CGAL Surface_parameterization, pmp-library, Blender, MeshLab.
Problem B — Discrete conformal equivalence (DCE)
Find scale factors u ∈ ℝᵛ such that the rescaled metric ℓ̃ᵢⱼ = e^{(uᵢ+uⱼ)/2} · ℓᵢⱼ has prescribed cone angles Θᵥ at every vertex. This is a variational problem on the intrinsic metric — independent of any embedding. The solution is unique (up to a global Möbius transformation) and places the surface in its canonical position in Teichmüller space.
Tools: conformallab++, geometry-central (partial), original Java ConformalLab.
This distinction matters. A UV map from LSCM minimises distortion but cannot be used to compute the period matrix τ ∈ ℍ. A DCE solution can.
2 — Full comparison table
| Library | Lang | DCE solver | Spherical | HyperIdeal | Cut graph | Holonomy | Period τ | Open source |
|---|---|---|---|---|---|---|---|---|
| conformallab++ | C++17 | Newton (quad.) | ✓ | ✓ | ✓ (tree-cotree) | ✓ SU(1,1) | ✓ SL(2,ℤ) | ✓ MIT |
| Java ConformalLab | Java 8 | Newton | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ LGPL |
| geometry-central | C++17 | Newton / Yamabe | ✗ | ✓ (partial) | ✗ | ✗ | ✗ | ✓ MIT |
| libigl | C++14 | LSCM / ARAP¹ | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ MPL-2 |
| CGAL Parameterization | C++ | LSCM / Orbifold¹ | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ GPL/LGPL |
| pmp-library | C++17 | harmonic / param.¹ | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ MIT |
| OpenFlipper | C++ | LSCM plugin¹ | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ LGPL |
| Matlab geom. toolbox | MATLAB | LSCM / ABF++¹ | ✗ | ✗ | ✗ | ✗ | ✗ | commercial |
¹ These are Problem-A methods (distortion minimisation), not DCE.
3 — Detailed comparison: conformallab++ vs. Java ConformalLab
conformallab++ is a C++17 reimplementation of the Java library:
| Aspect | Java ConformalLab | conformallab++ |
|---|---|---|
| Language | Java 8 | C++17 |
| Mesh type | Custom CoHDS halfedge |
CGAL::Surface_mesh |
| Build system | Maven | CMake |
| Test framework | JUnit 4 | GTest + CGAL test format |
| Static linking | JVM required | standalone binary |
| CGAL integration | none | native (target: CGAL package) |
| Inversive distance | ✓ | planned (Phase 9a) |
| Analytic HI Hessian | ✓ | planned (Phase 9b) |
| Genus g>1 domain | ✓ partial | planned (Phase 9c) |
| Siegel matrix Ω | partial | planned (Phase 10b) |
| All three modes | ✓ | ✓ |
| Period matrix τ | ✓ | ✓ |
| Holonomy | ✓ | ✓ |
Phase parity: Phases 1–7 of conformallab++ cover all core Java features.
Phases 9–10 will complete the remaining items. See doc/roadmap/java-parity.md
for the full feature-by-feature table.
4 — Detailed comparison: conformallab++ vs. geometry-central
geometry-central (Keenan Crane, CMU) is the closest external peer. Both implement DCE but diverge significantly in scope and algorithm.
| Dimension | conformallab++ | geometry-central |
|---|---|---|
| Solver | Newton, quadratic convergence | Newton or Yamabe flow |
| Triangulation | Fixed original mesh | Intrinsic + Ptolemaic flips |
| Spherical geometry | ✓ (NSD Hessian, sign flip) | ✗ |
| Cut graph | ✓ tree-cotree, 2g seams | ✗ |
| Holonomy | ✓ SU(1,1) Möbius maps | ✗ |
| Period matrix | ✓ τ ∈ ℍ, SL(2,ℤ)-reduced | ✗ |
| Fundamental domain | ✓ genus 1 complete | ✗ |
| Mesh backend | CGAL Surface_mesh |
gc ManifoldSurfaceMesh |
| CGAL integration | ✓ (target: package) | ✗ |
For a full analysis including adoption candidates and scientific added value,
see doc/architecture/geometry-central-comparison.md.
5 — What Problem-A tools cannot do
The following tasks require DCE (Problem B) and cannot be done with LSCM/ARAP:
| Task | Requires |
|---|---|
| Compute the period matrix τ of a torus | DCE + holonomy + period matrix |
| Classify a surface in Teichmüller space | DCE |
| Construct a flat metric with prescribed cone angles | DCE |
| Tile a surface by a lattice (fundamental domain) | DCE + cut graph + holonomy |
| Compare two surfaces conformally | DCE (same conformal class ↔ same τ) |
| Uniformize a hyperbolic surface (genus g ≥ 2) | HyperIdeal DCE |
| Compute holomorphic differentials (Phase 10) | DCE + cut graph + integration |
6 — When to use which tool
| Goal | Recommended tool |
|---|---|
| Fast UV unwrapping for texture mapping | libigl LSCM or pmp-library |
| Angle-preserving parameterization, distortion study | CGAL Surface_parameterization |
| Discrete conformal equivalence, research | conformallab++ |
| DCE with maximum numerical robustness on bad meshes | geometry-central (+ Ptolemaic flips) |
| Full Teichmüller pipeline (τ, holonomy, domain) | conformallab++ only |
| Interactive exploration (viewer) | conformallab++ (-DWITH_CGAL=ON) |
| Java ecosystem / existing ConformalLab workflow | Java ConformalLab |