From d25f3cafe6cdcba559e2592acc4a1221b019ffa3 Mon Sep 17 00:00:00 2001 From: Tarik Moussa Date: Mon, 18 May 2026 01:56:16 +0200 Subject: [PATCH] docs: geometry-central Vergleich als optionalen Track einarbeiten MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - phases.md: neue Sektion "Optional/Hypothetisch — geometry-central Cross-Comparison" mit GC-1 (Output-Vergleich, sofort möglich), GC-2 (Intrinsic Delaunay Pre-Conditioning, nach Phase 8) und GC-3 (Ptolemäischer Flip-Solver, hypothetisch Phase 10+) - validation.md: neuer Abschnitt 9 mit Vergleichstabelle, Normalisierungs- abgleich, Zeitplan und Springborn-2020-Einordnung - references.md: Gillespie–Springborn–Crane SIGGRAPH 2021 + Sharp 2019 als geometry-central-Referenzen eingetragen; Klarstellung zu Springborn 2020 - validation.md: Testzähler 170→173 / 11 skips→1 skip korrigiert Co-Authored-By: Claude Sonnet 4.6 --- doc/math/references.md | 21 +++++++++++++ doc/math/validation.md | 69 ++++++++++++++++++++++++++++++++++++++++-- doc/roadmap/phases.md | 57 ++++++++++++++++++++++++++++++++++ 3 files changed, 145 insertions(+), 2 deletions(-) diff --git a/doc/math/references.md b/doc/math/references.md index 0ec3064..bffce3e 100644 --- a/doc/math/references.md +++ b/doc/math/references.md @@ -26,6 +26,27 @@ Java reference implementation: [github.com/varylab/conformallab](https://github. --- +## geometry-central cross-reference *(optional comparison track)* + +> Diese Referenzen beziehen sich auf eine alternative Implementierung desselben +> mathematischen Problems. Sie sind keine Voraussetzung für conformallab++, +> aber relevant für Kreuz-Validierung und mögliche algorithmische Adoptionen +> (→ GC-1/2/3 im Phasen-Roadmap, → Abschnitt 9 in `validation.md`). + +| Reference | Relevanz | +|---|---| +| **Gillespie, Springborn, Crane** — *Discrete Conformal Equivalence of Polyhedral Surfaces*, ACM SIGGRAPH 2021. DOI: [10.1145/3450626.3459763](https://doi.org/10.1145/3450626.3459763) | Implementiert in **geometry-central**. Erweitert Springborn 2020 um intrinsische Triangulierungen und Ptolemäische Flips. Löst dasselbe DCE-Problem wie conformallab++, aber mit anderem Algorithmus. | +| **Sharp, Soliman, Crane** — *Navigating Intrinsic Triangulations*, ACM SIGGRAPH 2019 | Algorithmische Grundlage für `SignpostIntrinsicTriangulation` in geometry-central — relevant für GC-2 (optionales Pre-Conditioning). | + +**Hinweis zu Springborn 2020:** +Das Papier *"Ideal Hyperbolic Polyhedra and Discrete Uniformization"* +(Springborn, Discrete & Computational Geometry 2020) ist **in conformallab++ +bereits implementiert** — es ist die direkte Referenz für den HyperIdeal-Geometriemodus +(`hyper_ideal_geometry.hpp`). Die geometry-central Implementierung (Gillespie 2021) +baut auf diesem Papier auf und ergänzt es um Ptolemäische Flips. + +--- + ## Phase 10 references (future research) | Reference | Relevant for | diff --git a/doc/math/validation.md b/doc/math/validation.md index de52fef..26b9873 100644 --- a/doc/math/validation.md +++ b/doc/math/validation.md @@ -14,7 +14,7 @@ cmake --build build --target conformallab_cgal_tests ctest --test-dir build -R cgal --output-on-failure ``` -All 170 tests pass (11 skipped by design — see `doc/api/tests.md`). +All 173 tests pass (1 skipped by design — see `doc/api/tests.md`). --- @@ -191,11 +191,76 @@ These are the **holonomy consistency** checks implemented in `test_phase7.cpp` --- +## 9 — Cross-validation with geometry-central *(optional / hypothetical)* + +> **Hinweis:** Dieser Abschnitt beschreibt eine mögliche externe Kreuz-Validierung, +> die keine Voraussetzung für die Korrektheit der Implementierung ist. +> Sie ist interessant, weil geometry-central denselben mathematischen Kern +> implementiert (Gillespie, Springborn, Crane — SIGGRAPH 2021, aufbauend auf +> Springborn 2020), aber mit einer anderen algorithmischen Strategie +> (Ptolemäische Flips + intrinsische Triangulierungen statt Newton auf der +> Original-Triangulierung). + +### Welche Outputs sind vergleichbar? + +| Output | conformallab++ | geometry-central | Vergleichbar? | +|---|---|---|---| +| u-Vektor (Skalierungsparameter) | `res.x` | `u` nach Yamabe flow | ✓ nach Normalisierung | +| UV-Koordinaten | `layout.uv[v]` | konforme Parametrisierung | ✓ bis auf Möbius-Transformation | +| Gauss-Bonnet Defekt | `gauss_bonnet_sum()` | implizit via Krümmungsfluss | ✓ (analytisch identisch) | +| Anzahl Newton-Iterationen | `res.iterations` | Yamabe-Schritte | ~ (anderer Algorithmus) | +| Period-Matrix τ | `pd.tau_reduced` | **nicht vorhanden** | ✗ | +| Möbius-Holonomie | `hol.T_a, T_b` | **nicht vorhanden** | ✗ | + +### Normalisierungsabgleich + +Der u-Vektor in conformallab++ hat einen Freiheitsgrad (globale additive Konstante — +Eichfreiheit nach Pin-Fixierung). geometry-central kann eine andere Konvention nutzen. +Vor dem Vergleich normalisieren: + +```cpp +// conformallab++: u zentrieren +double mean_u = std::accumulate(x.begin(), x.end(), 0.0) / x.size(); +std::vector x_norm(x.size()); +for (int i = 0; i < x.size(); ++i) x_norm[i] = x[i] - mean_u; + +// Dann mit geometry-central u-Vektor (ebenfalls zentriert) vergleichen: +// max|x_norm[i] - gc_u[i]| < 1e-8 → identischer Konvergenzpunkt +``` + +### Wann ist der Vergleich sinnvoll? + +| Zeitpunkt | Was ist möglich | +|---|---| +| **Jetzt (Phase 7)** | Manueller Vergleich mit denselben `.off`/`.obj` Testnetzen | +| **Nach Phase 8** | Automatisiertes Vergleichsskript (Python oder separates C++-Binary) | +| **Phase 10 (Forschung)** | Algorithmus-Vergleich: Newton vs. Ptolemäische Flips auf schwierigen Netzen | + +### Voraussetzungen für einen fairen Vergleich + +1. Identische Eingabenetze (OFF/OBJ, gleiche Vertex-Orientierung) +2. Gleiche Gauss-Bonnet-Zielkrümmungen (Θᵥ = 2π für alle v, geschlossene Fläche) +3. u-Normalisierung abgeglichen (zentriert, gleiche Eichfixierung) +4. Konvergenztoleranz synchronisiert (max. Gradientnorm < 1e-8) + +### Verbindung zur Literatur + +Das Springborn 2020-Papier ("Ideal Hyperbolic Polyhedra and Discrete Uniformization") +ist **in conformallab++ bereits implementiert** — es ist die mathematische Grundlage +für den HyperIdeal-Geometriemodus (Phase 2/3). Die geometry-central Implementierung +basiert auf der Weiterentwicklung von Gillespie, Springborn & Crane (2021), die +denselben Variationsprinzip von Bobenko–Springborn 2004 verwendet, aber zusätzlich +Ptolemäische Flips einsetzt, um die Triangulierung während der Optimierung zu +verbessern — eine Idee, die in conformallab++ noch nicht implementiert ist (→ GC-2 +im Phasen-Roadmap). + +--- + ## 8 — Checklist for an independent reviewer Run these in order to validate the implementation: -- [ ] `ctest --test-dir build -R cgal --output-on-failure` → 170 tests pass, 11 skip +- [ ] `ctest --test-dir build -R cgal --output-on-failure` → 173 tests pass, 1 skip - [ ] `cgal.GaussBonnet.*` all pass → topology is correctly read from mesh - [ ] `cgal.EuclideanFunctional.GradientCheck_*` pass → energy = integral of gradient - [ ] `cgal.PeriodMatrix.TauInFundamentalDomain_*` pass → SL(2,ℤ) reduction correct diff --git a/doc/roadmap/phases.md b/doc/roadmap/phases.md index 795affa..a05dad5 100644 --- a/doc/roadmap/phases.md +++ b/doc/roadmap/phases.md @@ -93,6 +93,63 @@ Java features from `de.varylab.discreteconformal` not yet in C++: --- +## ◼ Optional / Hypothetical — geometry-central Cross-Comparison + +> **Status: keine geplante Phase — rein explorativ.** +> Diese Punkte sind keine Voraussetzung für Phase 8–10. Sie sind +> interessant, weil geometry-central (Keenan Crane, CMU) auf denselben +> mathematischen Grundlagen wie conformallab++ aufbaut — insbesondere auf +> **Springborn 2020** und der direkten Weiterentwicklung durch +> **Gillespie, Springborn & Crane (SIGGRAPH 2021)**. +> Der entscheidende Unterschied: geometry-central löst dasselbe Problem +> (diskrete konforme Äquivalenz) mit **intrinsischen Triangulierungen + +> Ptolemäischen Flips**, während conformallab++ **Newton auf der +> Original-Triangulierung** anwendet. + +``` +GC-1 [optional, jetzt möglich] + Mathematischer Output-Vergleich + → gleiche Testnetze (cathead.obj, brezel.obj, torus_4x4.off) in + beide Bibliotheken laden + → UV-Koordinaten, u-Vektor, Residualnorm vergleichen + → Normalisierungskonventionen abgleichen (u-Mittelwert, Skalierung) + Ziel: unabhängige Kreuz-Validierung der Konvergenzpunkte. + Aufwand: kleines Python/C++ Vergleichsskript, kein Bibliotheks-Umbau. + +GC-2 [optional, sinnvoll nach Phase 8] + Intrinsic Delaunay Pre-Conditioning + → Vor dem Newton-Solver: geometry-central SignpostIntrinsicTriangulation + auf die Eingabe anwenden + → Ptolemäische Flips konditionieren die Hessian-Matrix vor + → Hypothese: weniger Newton-Iterationen auf nicht-Delaunay-Eingaben + → Implementierbar als optionaler cmake-Flag: -DWITH_GC_PRECOND=ON + Abhängigkeit: geometry-central als optionale externe Abhängigkeit + (header-only Teile genügen für den Flip-Algorithmus). + +GC-3 [hypothetisch, Phase 10+ Forschung] + Ptolemäische Flip-basierter Solver als alternativer Backend + → Statt Newton: Ptolemäische Flips + penultimate-step Normalisierung + (Gillespie–Springborn–Crane 2021 Algorithmus) + → Vergleich: Konvergenzradius, Robustheit auf pathologischen Netzen, + numerische Stabilität auf hohen Genus-Flächen + → Für conformallab++ interessant, weil der Newton-Ansatz auf + stark nicht-Delaunay Netzen (z.B. nach Remeshing) instabil + werden kann. + Keine Implementierung geplant — Konzeptnotiz für Phase 10-Forschung. +``` + +**Verbindung zur Literatur:** +Das Springborn 2020-Papier ("Ideal Hyperbolic Polyhedra and Discrete +Uniformization") ist in conformallab++ als HyperIdeal-Geometriemodus +bereits implementiert (Phase 2/3). Die Gillespie–Springborn–Crane +2021-Erweiterung — die geometry-central implementiert — ergänzt dies um +intrinsische Triangulierungen und macht den Algorithmus robust gegen +schlechte Eingangs-Triangulierungen. Beide teilen denselben +mathematischen Kern (diskrete konforme Äquivalenz, Gauss–Bonnet, +Variationsprinzip von Bobenko–Springborn 2004). + +--- + ## ◼ New research — Phase 10+ No direct Java reference implementation exists for these items.