docs: geometry-central Vergleich als optionalen Track einarbeiten
All checks were successful
C++ Tests / test-fast (push) Successful in 2m1s
C++ Tests / test-cgal (push) Has been skipped

- 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 <noreply@anthropic.com>
This commit is contained in:
Tarik Moussa
2026-05-18 01:56:16 +02:00
parent d0dd1bad3b
commit d25f3cafe6
3 changed files with 145 additions and 2 deletions

View File

@@ -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 |

View File

@@ -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<double> 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 BobenkoSpringborn 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

View File

@@ -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 810. 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
(GillespieSpringbornCrane 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 GillespieSpringbornCrane
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, GaussBonnet,
Variationsprinzip von BobenkoSpringborn 2004).
---
## ◼ New research — Phase 10+
No direct Java reference implementation exists for these items.