88a99d8bd1
Math / code: - layout.hpp: add explanatory comment for Möbius deck transformation (from_three with z1=w1, z2=w2 encodes T fixing cut-edge endpoints) - layout.hpp: document spherical holonomy limitation — Vector2d stores only (x,y) of 3-D position diff; full SO(3) representation deferred Gradient sign convention (CLAUDE.md was wrong): - Euclidean and Spherical both use G_v = Θ_v − actual (target minus actual) - HyperIdeal uses G_v = actual − Θ_v - Hessian sign differs: Euclidean PSD, Spherical NSD → −H, HyperIdeal PSD Test counts (were inconsistent across all files): - Actual: 176 CGAL tests, 2 GTEST_SKIP (not 173/170/174, not 1 skip) - The 2 skips are EuclideanFunctional + SphericalFunctional Hessian gradient checks (Java @Ignore ports) — not HyperIdeal Hessian as previously stated - doc/api/tests.md: add missing SmokeEuclidean suite (3 tests), EuclideanLayout (2), SphericalLayout (1), fix GaussBonnet 8→12, MeshIO 9→6, Layout 8→6, EuclideanFunctional 11→12, HomologyGenerators no longer a GTEST_SKIP stub (live test on brezel2.obj) - doc/roadmap/phases.md: Phase 7 cumulative 158→176 tests - doc/roadmap/phases.md: Phase 3 clarified — HyperIdeal Hessian is FD - CLAUDE.md: suite count 28→34, test ref 173+36→174+36 - scripts/try_it.sh: expected output 173/1 skipped → 174/2 skipped CI table (CLAUDE.md): - test-cgal now triggers on pull requests only (not main/dev pushes) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
176 lines
7.6 KiB
Markdown
176 lines
7.6 KiB
Markdown
# Development Roadmap
|
||
|
||
> **Legend:** ✅ complete · 🔲 planned
|
||
>
|
||
> **Porting / research boundary:**
|
||
> Phases 1–7 are direct ports of the Java original and its dissertation.
|
||
> From Phase 8 onwards the work goes beyond the scope of the Java library.
|
||
> Phase 8 (CGAL package) is infrastructure. Phase 9 is porting of remaining Java features.
|
||
> Phase 10+ is independent research with no direct Java reference implementation.
|
||
|
||
---
|
||
|
||
## ◼ Porting complete — Phases 1–7
|
||
|
||
```
|
||
Phase 1 Clausen / Lobachevsky / ImLi₂ special functions ✅
|
||
Phase 2 Hyper-ideal geometry (ζ, lᵢⱼ, αᵢⱼ, σᵢ, σᵢⱼ) ✅
|
||
Phase 3 CGAL Surface_mesh infrastructure + all three functionals
|
||
(Euclidean, Spherical, HyperIdeal)
|
||
+ analytical Hessians for Euclidean + Spherical
|
||
(HyperIdeal Hessian: symmetric FD — analytic deferred to 9b) ✅
|
||
Phase 4 Newton solver (SimplicialLDLT + SparseQR fallback)
|
||
+ Mesh I/O (OFF/OBJ/PLY) + example programs ✅ 68 tests
|
||
Phase 5 Priority-BFS layout + CLI app + JSON/XML serialisation ✅ 95 tests
|
||
Phase 6 Gauss–Bonnet check/enforce, tree-cotree cut graph (2g),
|
||
exact hyperbolic trilateration, layout normalisation ✅ 121 tests
|
||
Phase 7 MobiusMap, halfedge_uv, Möbius holonomy (SU(1,1)),
|
||
period matrix τ∈ℍ + SL(2,ℤ) reduction,
|
||
fundamental domain parallelogram + tiling ✅ 176 tests
|
||
```
|
||
|
||
---
|
||
|
||
## ◼ Infrastructure — Phase 8: CGAL Package
|
||
|
||
Goal: conformallab++ as a standalone CGAL package, submission-ready, fulfilling all
|
||
CGAL package conventions with a traits-class design compatible with any CGAL-conforming
|
||
mesh type.
|
||
|
||
```
|
||
8a Traits class & concepts
|
||
→ include/CGAL/Conformal_map_traits.h
|
||
Separates MeshType, KernelType, ScalarType from the algorithm.
|
||
Enables use with any CGAL-compatible mesh, not just Surface_mesh.
|
||
→ Concept checks via static_assert / CGAL_concept_check
|
||
|
||
8b Public CGAL header hierarchy
|
||
→ include/CGAL/Discrete_conformal_map.h (user-facing entry header)
|
||
→ include/CGAL/Conformal_newton_solver.h
|
||
→ include/CGAL/Conformal_layout.h
|
||
→ include/CGAL/Conformal_cut_graph.h
|
||
All existing include/conformallab/*.hpp remain as implementation details.
|
||
|
||
8c CGAL-style documentation
|
||
→ doc/Conformal_map/PackageDescription.txt
|
||
→ doc/Conformal_map/fig/ (pipeline diagrams)
|
||
→ Doxygen comments on all public concepts and functions
|
||
→ User_manual.md + Reference_manual.md
|
||
|
||
8d CGAL test format
|
||
→ test/Conformal_map/CMakeLists.txt (CGAL-style CMake)
|
||
Existing GTest tests remain; CGAL-format tests are added alongside.
|
||
|
||
8e Declarative YAML pipeline
|
||
→ Lightweight YAML format for reproducible experiments
|
||
(specification in doc/api/cgal-package.md)
|
||
→ Validator: checks require/provide tokens before execution
|
||
→ CLI integration: conformallab_core --pipeline experiment.yml
|
||
```
|
||
|
||
---
|
||
|
||
## ◼ Remaining porting — Phase 9
|
||
|
||
Java features from `de.varylab.discreteconformal` not yet in C++:
|
||
|
||
```
|
||
9a Inversive-distance functional (Luo 2004 / Bowers–Stephenson)
|
||
→ inversive_distance_functional.hpp
|
||
Follows the exact same pattern as the three existing functionals.
|
||
→ newton_inversive_distance()
|
||
→ New test suite: test_inversive_distance.cpp
|
||
|
||
9b Analytic HyperIdeal Hessian
|
||
→ Replace FD Hessian in hyper_ideal_hessian.hpp
|
||
Direct differentiation through the chain:
|
||
(bᵢ, aₑ) → lᵢⱼ → ζ₁₃/ζ₁₄/ζ₁₅ → αᵢⱼ / βᵢ
|
||
Relevant for meshes > 500 DOFs (current FD Hessian is slow there).
|
||
|
||
9c 4g-polygon boundary walk (genus g > 1)
|
||
→ Extend compute_fundamental_domain() beyond genus 1
|
||
Algorithm outline already in fundamental_domain.hpp as TODO(Phase 9).
|
||
Java reference: FundamentalDomainUtility.java
|
||
```
|
||
|
||
---
|
||
|
||
## ◼ 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.
|
||
|
||
```
|
||
Phase 10 Global uniformization for genus g ≥ 2
|
||
|
||
10a Discrete holomorphic differentials
|
||
Integrate basis 1-forms ωᵢ along b-cycles of the cut graph.
|
||
Mathematical basis: Bobenko–Springborn (2004), §6.
|
||
Java partial reference: DiscreteHolomorphicFormUtility.java
|
||
|
||
10b Siegel period matrix Ω ∈ H_g (g×g complex symmetric, Im(Ω) > 0)
|
||
Ωᵢⱼ = ∫_{bⱼ} ωᵢ
|
||
Reduction to Siegel fundamental domain via Sp(2g,ℤ).
|
||
Requires: 10a
|
||
|
||
10c Full uniformization for genus g ≥ 2
|
||
Embedding as H²/Γ with Γ ⊂ PSL(2,ℝ) a Fuchsian group.
|
||
Requires: 10a + 10b + stable cut graph for g ≥ 2 (Phase 9c)
|
||
```
|