chore/docs: Onboarding-Sprint für externe Mathematiker
- 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>
This commit is contained in:
Tarik Moussa
128
doc/math/software-landscape.md
Normal file
128
doc/math/software-landscape.md
Normal file
@@ -0,0 +1,128 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user