b57528d92f
Brings doc/roadmap/ to the same operational level as doc/reviewer/ by adding the two missing structural files and updating existing docs to close the gap identified in the system review. New files: - doc/roadmap/phase-orchestration.md — master phase table (model assignments, session IDs, status, review-gate checklist); mirrors finding-orchestration.md - doc/roadmap/session-prompts.md — copy-paste-ready prompts for P1–P4 (Haiku/Sonnet/Opus) + universal Opus review gate; mirrors reviewer/session-prompts.md Updated files: - CLAUDE.md: roadmap section now lists porting-status.md, phase-orchestration.md, session-prompts.md; reviewer section adds finding-orchestration.md and session-prompts.md; agentic-workflow section has direct "S3 is next / P1 is next" entry points so agents don't need to derive the next action from scratch - doc/roadmap/phases.md: Current-focus table at the top (7 tracks, next session per track, gating); cross-links to geometry-central-comparison.md, software-landscape.md, complexity.md added in GC and 9b-analytic sections - doc/roadmap/porting-status.md: snapshot date updated to 2026-05-31 (post S1+S2); test count replaced by reference to doc/api/tests.md; §4 gains four new solver rows (newton_core refactor, NewtonStatus enum, diagnostics, selectable clamp mode); §7 gains four new research-extension rows from S1/S2 - doc/roadmap/research-track.md: header companion-docs section links to novelty-statement.md, software-landscape.md, and phase-orchestration.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
737 lines
41 KiB
Markdown
737 lines
41 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.
|
||
|
||
---
|
||
|
||
## ◼ Current focus (as of 2026-06-01)
|
||
|
||
> **Agent entry point.** Read this box first. For model assignments, priority
|
||
> order, and ready-to-paste prompts, see
|
||
> [`phase-orchestration.md`](phase-orchestration.md) and
|
||
> [`session-prompts.md`](session-prompts.md).
|
||
> Audit-finding sessions run in parallel from `doc/reviewer/`.
|
||
|
||
| Track | Next session | Gating |
|
||
|---|---|---|
|
||
| **Audit findings** | S3: H3/H4/H5/V5/V6 — Sonnet → Opus review | None — start now |
|
||
| **Phase quick-wins** | P1: 9g.1 + 9h.1 + 9h.2 + 9d.3 — Haiku → Opus review | None — start now |
|
||
| **Research: Decorated DCE** | P2: Phase 12 — Sonnet → Opus review | None — start now |
|
||
| **Circle pattern + convergence** | P3: 9e + 9d.4 + 9g.2 — Sonnet → Opus review | None — start now |
|
||
| **Research: Analytic Hessian** | P4: Phase 9b-analytic — Opus | ⏸ awaiting reviewer Q3 |
|
||
| **Java port: genus > 1** | P5: Phase 9c — Opus | ⏸ awaiting reviewer Q4 + G0 |
|
||
| **CGAL packaging** | S6 (audit system) — Opus | ⛔ blocked on G0 (author reply pending) |
|
||
|
||
---
|
||
|
||
## ◼ 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
|
||
```
|
||
|
||
---
|
||
|
||
## ◼ Phase 9 — Mixed: remaining Java port + first research extensions
|
||
|
||
> **Audit 2026-05-21:** Phase 9 was originally framed as "remaining
|
||
> porting", but a closer look at the local Java repository revealed:
|
||
> several Phase-9 items are **not** in Java at all (`InversiveDistanceFunctional`
|
||
> does not exist; `HyperIdealFunctional.java:295-298` declares `hasHessian()=false`).
|
||
> The plan below now distinguishes Java-port items from research items.
|
||
> Full research catalogue: [`research-track.md`](research-track.md).
|
||
|
||
```
|
||
9a — Circle-packing functionals (split 2026-05-19)
|
||
─────────────────────────────────────────────────────
|
||
|
||
9a.1 CPEuclideanFunctional (Java port)
|
||
→ cp_euclidean_functional.hpp
|
||
Java source: CPEuclideanFunctional.java (260 lines)
|
||
Mathematical reference: Bobenko-Pinkall-Springborn 2010
|
||
Status: 🟡 PR #8 open, 10 tests passing.
|
||
|
||
9a.2 Inversive-distance functional (RESEARCH, not a port)
|
||
→ inversive_distance_functional.hpp
|
||
Java source: NONE. Empirically verified.
|
||
Mathematical reference: Luo 2004 + Bowers-Stephenson 2004 + Glickenstein 2011
|
||
Status: 🟡 PR #8 open, 11 tests passing.
|
||
Cross-validation: G_id(0) = G_eu(0) at 1e-10 (Glickenstein §5).
|
||
|
||
9b — HyperIdeal Hessian (RESEARCH — Java has no Hessian at all)
|
||
─────────────────────────────────────────────────────────────────
|
||
|
||
9b Block-FD HyperIdeal Hessian
|
||
→ Replace full FD in hyper_ideal_hessian.hpp
|
||
Java source: NONE (HyperIdealFunctional.java:295-298 declares
|
||
hasHessian()==false; Java has NO Hessian).
|
||
Algorithm: per-face 6×6 block, scatter to global sparse matrix.
|
||
Status: 🟡 PR #9 open, 7 tests passing, ~96× speed-up measured.
|
||
|
||
9b-analytic Full analytic HyperIdeal Hessian via Schläfli identity
|
||
→ planned, see research-track.md + session-prompts.md §P4
|
||
Mathematical source: Springborn 2020 §4 + Schläfli 1858/60
|
||
+ Rivin, Schlenker 1999 "The Schläfli formula in
|
||
Einstein manifolds with boundary" (ERA-AMS 5, 18–23)
|
||
+ Cho-Kim 1999 + Glickenstein 2011 §4
|
||
Algorithm: explicit chain rule through (bᵢ,aₑ) → ℓᵢⱼ → ζ₁₃/ζ₁₄/ζ₁₅ → αᵢⱼ/βᵢ
|
||
Includes: 805-line LaTeX derivation in doc/math/hyperideal-hessian-derivation.md.
|
||
Effort: 10–14 days net. Trigger: profiling on V > 5000.
|
||
Complexity / scaling context: doc/math/complexity.md.
|
||
⏸ GATED: awaiting reviewer Q3 answer ("worth ~2 weeks at your mesh sizes?").
|
||
|
||
9c — Genus g > 1 fundamental domain (Java port + research extensions)
|
||
──────────────────────────────────────────────────────────────────────
|
||
|
||
9c 4g-polygon boundary walk (genus g > 1)
|
||
→ Extend compute_fundamental_domain() beyond genus 1
|
||
Java sources: FundamentalPolygonUtility.java (698 lines)
|
||
+ CanonicalFormUtility.java (532 lines)
|
||
+ CuttingUtility / SurgeryUtility (~800 lines)
|
||
+ SurfaceCurveUtility.java (360 lines, 2026-05-28
|
||
scan) — curve operations on the surface (cut-path
|
||
tracing / fundamental-domain boundary); supporting
|
||
infrastructure for the polygon construction.
|
||
Mathematical source: Poincaré 1882 + Sechelmann 2016 §5
|
||
Research component: bridging to conformallab++ cut_graph.hpp
|
||
+ holonomy infrastructure.
|
||
† PRECISION PREREQUISITE: the canonicalisation composes products of
|
||
hyperbolic isometry generators, whose entries grow exponentially.
|
||
double fails to verify the group relation ∏gᵢ = Id; Java uses
|
||
MathContext(50) (RnBig/PnBig/P2Big). Port a LOCALIZED high-precision
|
||
substrate (boost::multiprecision::cpp_dec_float_50 or MPFR mpreal)
|
||
inside the uniformization module only — NOT the core or the Eigen
|
||
solver. See CLAUDE.md Phase-9 note + java-parity.md exception.
|
||
Effort: ~2 weeks for fundamental polygon, +2 weeks for surgery
|
||
layer, +1 week integration, +~3 days high-precision substrate.
|
||
```
|
||
|
||
9d — Cone metrics + sphere utilities (Java port + research extension)
|
||
────────────────────────────────────────────────────────────────────
|
||
|
||
```
|
||
9d.1 ConesUtility (Java port: unwrapper/ConesUtility.java)
|
||
→ cone_singularities.hpp
|
||
Fills the "⚠️ data structure only" gap in java-parity.md:
|
||
- Detect interior cone vertices (angle deficit ≠ 0)
|
||
- BFS path from cone to mesh boundary → cut edge set
|
||
- Auto-placement: conjugate gradient on Θ-gradient magnitude
|
||
- Quantization: snap cone angles to π/2, π/3, π/6 for
|
||
quad / triangle / hexagonal atlas targets
|
||
Java reference: unwrapper/ConesUtility.java
|
||
Mathematical reference: Troyanov 1991 + Springborn 2020 §3
|
||
|
||
9d.2 Non-Euclidean cone extensions (RESEARCH, not in Java)
|
||
→ extend ConesUtility to HyperIdeal + Spherical modes
|
||
Java source: NONE — Java ConesUtility is Euclidean-only.
|
||
Mathematical reference:
|
||
Bobenko, Lutz 2025 "Decorated Discrete Conformal Equivalence in
|
||
Non-Euclidean Geometries" (Discrete & Comput. Geom. 2025,
|
||
arXiv:2310.17529) §3 — decorated DCE framework unifying cone
|
||
singularities and cusps in hyperbolic + spherical geometry.
|
||
Soliman, Slepčev, Crane 2018 "Optimal Cone Singularities
|
||
for Conformal Flattening" (ACM TOG 37(4), Art. 105) — L¹-optimal
|
||
automatic cone placement; directly applicable to 9d.2 algorithm.
|
||
Status: 🔲 planned
|
||
|
||
9d.3 StereographicUnwrapper + SphereUtility (Java port)
|
||
→ stereographic_layout.hpp
|
||
Stereographic projection S²→ℂ∪{∞} + Möbius centering for
|
||
genus-0 surfaces. Converts spherical DCE output to a flat 2-D atlas.
|
||
Java reference: unwrapper/StereographicUnwrapper.java (266 lines)
|
||
Note (2026-05-28 visualisation scan): plugin/algorithm/
|
||
StereographicTextureProjection.java (88 lines) is the texture
|
||
front-end of this same math — no separate item. The supporting
|
||
math/CP1 + ComplexUtility.stereographic are deliberately NOT
|
||
ported (redundant with std::complex + the existing MobiusMap,
|
||
see porting-status.md).
|
||
Optional companion: MercatorTextureProjection.java (47 lines) —
|
||
a distinct cylindrical conformal display projection; small
|
||
nice-to-have for the sphere-visualisation bucket, not required.
|
||
|
||
9d.4 MobiusCenteringFunctional (Java port, optional upgrade)
|
||
→ integrate into layout.hpp normalise_hyperbolic()
|
||
Variational Möbius centering via Lorentz geometry:
|
||
E = Σ log(-⟨x,p⟩/√(-⟨x,x⟩))
|
||
Supplies gradient + Hessian — replaces iterative Fréchet mean.
|
||
Java reference: functional/MobiusCenteringFunctional.java
|
||
```
|
||
|
||
9e — Circle pattern layout (Java port — complement to Phase 9a.1)
|
||
────────────────────────────────────────────────────────────────────
|
||
|
||
```
|
||
9e CirclePatternLayout + CirclePatternUtility (Java port)
|
||
→ circle_pattern_layout.hpp
|
||
Phase 9a.1 ported the CPEuclidean energy + solver; this phase
|
||
adds the embedding step (ρ values → actual vertex positions in ℝ²).
|
||
- CirclePatternUtility: compute per-face radii ρ via NTR solver
|
||
- CirclePatternLayout: embed from ρ values (intersection-angle model)
|
||
- CPEuclideanRotation: rotation-invariant CP functional variant
|
||
Java references: unwrapper/circlepattern/CirclePattern{Layout,Utility}.java
|
||
unwrapper/circlepattern/CPEuclideanRotation.java
|
||
Mathematical reference: Bobenko-Springborn 2004 variational principle
|
||
+ Bobenko-Hoffmann-Springborn 2006 "Minimal
|
||
surfaces from circle patterns" (Discrete &
|
||
Comput. Geom. 35, 2006).
|
||
```
|
||
|
||
9f — Polygon Laplacian (RESEARCH — no Java equivalent)
|
||
──────────────────────────────────────────────────────
|
||
|
||
```
|
||
9f Discrete Laplacian on general polygonal meshes
|
||
→ polygon_laplacian.hpp
|
||
Java source: NONE
|
||
Mathematical reference:
|
||
Alexa, Wardetzky 2011 "Discrete Laplacians on General Polygonal
|
||
Meshes" (ACM SIGGRAPH 2011) — virtual-node construction,
|
||
polygon cotangent weights extending the Pinkall-Polthier formula.
|
||
Bunge, Herholz, Kazhdan, Botsch 2020 "Polygon Laplacian Made
|
||
Simple" (Computer Graphics Forum 39(2), 303–313) — virtual-vertex
|
||
construction with error analysis. (DEC alternative: de Goes,
|
||
Butts, Desbrun 2020, ACM TOG 39(4).)
|
||
Enables: DCE energy evaluation on quad-dominant / Voronoi /
|
||
polygon meshes without forced triangulation.
|
||
Replaces euclidean_hessian.hpp for non-triangular inputs.
|
||
Status: 🔲 planned (pure research, no Java source)
|
||
Effort: medium (~2 weeks core + tests; +1 week Newton integration).
|
||
|
||
9g — Conformal quality measures (Java port — 2026-05-28 scan)
|
||
──────────────────────────────────────────────────────────────────
|
||
|
||
9g.1 Quantitative correctness metrics for a computed conformal map
|
||
→ conformal_quality.hpp
|
||
Lifts the measure math out of the jReality plugin + convergence
|
||
layers (the math is GUI-independent). High value / low effort:
|
||
these directly strengthen the validation story for the already-
|
||
shipped genus-0/1 pipeline (doc/math/validation.md).
|
||
- IsothermicityMeasure (113 lines) — pointwise deviation
|
||
from conformality (anisotropy of the induced metric).
|
||
- DiscreteConformalEquivalencemMeasure (82 lines) — per-edge
|
||
length-cross-ratio residual vs. the conformal-equivalence
|
||
condition.
|
||
- FlippedTriangles (17 lines) — detects inverted /
|
||
degenerate triangles in a 2-D layout (embedding-validity check).
|
||
- LengthCrossRatio (12 lines) — the discrete conformal
|
||
invariant itself (per-edge), shared input for the two measures.
|
||
- ConvergenceUtility measures (~110 lines, math/float only — no
|
||
Mathematica/jReality deps): getMaxMeanSumCrossRatio
|
||
(q=(a·c)/(b·d), qfun=(q+1/q)/2−1), getMaxMeanSumMultiRatio
|
||
(per-face product, =1 iff conformal), and
|
||
getMaxMeanSumScaleInvariantCircumRadius (R/√A, scale-invariant
|
||
mesh-quality). The operational counterpart of LengthCrossRatio.
|
||
Java references:
|
||
plugin/visualizer/IsothermicityMeasure.java
|
||
plugin/visualizer/DiscreteConformalEquivalencemMeasure.java
|
||
plugin/visualizer/FlippedTriangles.java
|
||
heds/adapter/types/LengthCrossRatio.java
|
||
convergence/ConvergenceUtility.java
|
||
Mathematical reference: Springborn-Schröder-Pinkall 2008
|
||
(length cross-ratio = discrete conformal invariant).
|
||
Status: 🔲 planned (Java port; no new theory).
|
||
Effort: small (~3 days incl. gradient-free tests). No
|
||
dependencies — can land before 9a–9f.
|
||
|
||
9g.2 Period-matrix convergence study (validation experiment — optional)
|
||
→ tests/cgal/test_period_matrix_convergence.cpp (experiment, not
|
||
a library feature)
|
||
Empirical validation for the already-shipped period_matrix.hpp +
|
||
discrete_elliptic_utility.hpp: generate a genus-1 elliptic mesh
|
||
with a known analytic τ, then refine / subdivide / add Gaussian
|
||
vertex noise and plot |τ_computed − τ_expected| → 0.
|
||
Java reference: convergence/* (~1400 lines) — a CLI harness
|
||
(joptsimple) that drives the same study. Do NOT port the
|
||
harness: it depends on Mathematica via JLink and on jReality's
|
||
OBJ reader + LoopLinear subdivision. Port only the *method*:
|
||
- subdivision → igl::loop (libigl already available)
|
||
- noise → trivial (vᵢ += σ·N(0,1))
|
||
- error metric → the 9g.1 quality measures + τ residual
|
||
Status: 🔲 optional (raises empirical confidence in genus-1 τ;
|
||
no new library surface). Effort: small (~2–3 days).
|
||
```
|
||
|
||
9h — CLI usability extensions (infrastructure — no Java equivalent)
|
||
──────────────────────────────────────────────────────────────────
|
||
|
||
Identified by usability-audit-2026-05-31 (Finding-U11). Two independent
|
||
sub-tasks; either can land independently.
|
||
|
||
```
|
||
9h.1 Newton solver tuning parameters (~30 min)
|
||
Currently hardcoded in all three run_*() helpers:
|
||
tol = 1e-8, max_iter = 200
|
||
Add to conformallab_cli.cpp:
|
||
app.add_option("--tol", tol, "Newton gradient tolerance [1e-8]");
|
||
app.add_option("--max-iter", max_iter, "Newton iteration limit [200]");
|
||
Thread both through run_euclidean / run_spherical / run_hyper_ideal.
|
||
Update getting-started.md CLI parameter table.
|
||
Status: 🔲 planned. Effort: ~30 min. No dependencies.
|
||
|
||
9h.2 Phase-9a models in CLI (~2–4 hours)
|
||
The CP-Euclidean and Inversive-Distance functionals are fully
|
||
implemented in the library and exposed via the CGAL public API
|
||
(Discrete_circle_packing.h, Discrete_inversive_distance.h), but
|
||
a CLI user cannot reach them. Add:
|
||
-g cp_euclidean → run_cp_euclidean()
|
||
-g inversive_distance → run_inversive_distance()
|
||
Following the existing run_euclidean() pattern (~60 lines each).
|
||
Add both geometry strings to the CLI::IsMember validator.
|
||
Update README + getting-started.md parameter table.
|
||
Status: 🔲 planned. Effort: ~2–4 h. Requires: 9a complete ✅.
|
||
Java reference: none (both functionals are research / literature ports).
|
||
```
|
||
|
||
---
|
||
|
||
## ◼ New research directions — Phases 10d–10g (2026 library scan)
|
||
|
||
These were identified by a full scan of the Java source tree in 2026.
|
||
They extend significantly beyond the Java port into new mathematical territory.
|
||
|
||
```
|
||
10d CircleDomainUnwrapper (Koebe–Andreev–Thurston)
|
||
→ circle_domain_unwrapper.hpp
|
||
Conformal map of a multiply-connected planar region onto a
|
||
canonical disk-with-holes (classical complex-analysis result).
|
||
Java reference: unwrapper/CircleDomainUnwrapper.java (570 lines)
|
||
Mathematical basis: Koebe–Andreev–Thurston + Beardon–Stephenson 1990
|
||
|
||
10e Quasi-isothermic maps
|
||
→ quasiisothermic.hpp
|
||
Generalisation of conformal maps for meshes where exact conformality
|
||
is unachievable (high Gaussian curvature, coarse triangulation).
|
||
Includes: Delaunay pre-conditioning, discrete Beltrami field,
|
||
sin-condition functional, Lawson-correspondence parameterization.
|
||
Java references: unwrapper/quasiisothermic/ (~1 200 lines total)
|
||
Mathematical basis: Lam 2015 + Bohle–Lam–Pinkall–Reitebuch 2015
|
||
|
||
10f Koebe polyhedra
|
||
→ koebe_polyhedron.hpp
|
||
Koebe–Andreev–Thurston theorem: realize every 3-connected planar
|
||
graph as a convex polyhedron with edges tangent to the unit sphere.
|
||
Connects circle packing with 3-D convex geometry.
|
||
Java reference: unwrapper/koebe/KoebePolyhedron.java (321 lines)
|
||
Mathematical basis: Koebe 1936 + Thurston 1997 (lecture notes)
|
||
|
||
10g Cyclic-symmetry functionals
|
||
→ cyclic_functional.hpp
|
||
Euclidean and hyperbolic DCE functionals reduced to a cyclic-symmetry
|
||
quotient — dramatically reduces DOFs for ornamental / symmetric surfaces.
|
||
Java references: functional/EuclideanCyclicFunctional.java
|
||
functional/HyperbolicCyclicFunctional.java (~530 lines)
|
||
```
|
||
|
||
---
|
||
|
||
## ◼ Optional / Hypothetical — geometry-central Cross-Comparison
|
||
|
||
> **Status: no planned phase — purely exploratory.**
|
||
> These items are not prerequisites for Phase 8–10. They are
|
||
> of interest because geometry-central (Keenan Crane, CMU) is built on the same
|
||
> mathematical foundations as conformallab++ — in particular
|
||
> **Springborn 2020** and its direct extension by
|
||
> **Gillespie, Springborn & Crane (SIGGRAPH 2021)**.
|
||
> The key difference: geometry-central solves the same problem
|
||
> (discrete conformal equivalence) using **intrinsic triangulations +
|
||
> Ptolemaic flips**, while conformallab++ applies **Newton on the
|
||
> original triangulation**.
|
||
|
||
```
|
||
GC-1 [optional, possible now]
|
||
Mathematical output comparison
|
||
→ load the same test meshes (cathead.obj, brezel.obj, torus_4x4.off) into
|
||
both libraries
|
||
→ compare UV coordinates, u-vector, residual norm
|
||
→ align normalisation conventions (u mean, scaling)
|
||
Goal: independent cross-validation of convergence points.
|
||
Effort: small Python/C++ comparison script, no library restructuring.
|
||
|
||
GC-2 [optional, useful after Phase 8]
|
||
Intrinsic Delaunay pre-conditioning
|
||
→ before the Newton solver: apply geometry-central SignpostIntrinsicTriangulation
|
||
to the input
|
||
→ Ptolemaic flips pre-condition the Hessian matrix
|
||
→ hypothesis: fewer Newton iterations on non-Delaunay inputs
|
||
→ implementable as an optional cmake flag: -DWITH_GC_PRECOND=ON
|
||
Dependency: geometry-central as an optional external dependency
|
||
(header-only parts suffice for the flip algorithm).
|
||
|
||
GC-3 [hypothetical, Phase 10+ research]
|
||
Ptolemaic flip-based solver as an alternative backend
|
||
→ instead of Newton: Ptolemaic flips + penultimate-step normalisation
|
||
(Gillespie–Springborn–Crane 2021 algorithm)
|
||
→ comparison: convergence radius, robustness on pathological meshes,
|
||
numerical stability on high-genus surfaces
|
||
→ relevant for conformallab++ because the Newton approach can become
|
||
unstable on strongly non-Delaunay meshes (e.g. after remeshing).
|
||
No implementation planned — conceptual note for Phase 10 research.
|
||
```
|
||
|
||
**Connection to the literature:**
|
||
The Springborn 2020 paper ("Ideal Hyperbolic Polyhedra and Discrete
|
||
Uniformization") is already implemented in conformallab++ as the HyperIdeal
|
||
geometry mode (Phase 2/3). The Gillespie–Springborn–Crane
|
||
2021 extension — implemented in geometry-central — augments this with
|
||
intrinsic triangulations and makes the algorithm robust against
|
||
poor input triangulations. Both share the same
|
||
mathematical core (discrete conformal equivalence, Gauss–Bonnet,
|
||
variational principle of Bobenko–Springborn 2004).
|
||
|
||
Full architecture-level comparison (overlap analysis, adoption rationale,
|
||
scientific value): [`doc/architecture/geometry-central-comparison.md`](../architecture/geometry-central-comparison.md).
|
||
Software landscape (libigl, CGAL, pmp-library, geometry-central):
|
||
[`doc/math/software-landscape.md`](../math/software-landscape.md).
|
||
|
||
---
|
||
|
||
## ◼ Phase 10 — Genus g ≥ 2 (research with partial Java support)
|
||
|
||
Most Phase-10 items have partial Java references (utility classes for
|
||
forms and homology) but the **assembly** into a working uniformization
|
||
pipeline is research. Full catalogue with primary literature:
|
||
[`research-track.md`](research-track.md).
|
||
|
||
```
|
||
Phase 10 Global uniformization for genus g ≥ 2
|
||
|
||
10a Discrete holomorphic and harmonic 1-forms
|
||
→ Integrate basis 1-forms ωᵢ along b-cycles of the cut graph.
|
||
Mathematical reference: Bobenko-Springborn 2004 §6 + Mercat 2001.
|
||
Knöppel, Crane, Pinkall, Schröder 2015 "Stripe
|
||
Patterns on Surfaces" (ACM SIGGRAPH 2015) —
|
||
application of discrete holomorphic 1-forms to
|
||
direction field design; provides an independent
|
||
C++ reference implementation (geometry-central)
|
||
for cross-validating the Phase 10a computation.
|
||
Java sources (partial, port-with-research):
|
||
CanonicalBasisUtility.java 337 lines (homology basis)
|
||
HomologyUtility.java 122 lines
|
||
HomotopyUtility.java 57 lines (2026-05-28 scan) —
|
||
reconstructs the explicit generator *cycles* (bridge edge +
|
||
tree path via HomologyUtility.findCycle). NOT covered by
|
||
cut_graph.hpp, which yields only the 2g cut *edges*; the closed
|
||
loops are needed to integrate 1-forms along b-cycles.
|
||
DualityUtility.java 308 lines
|
||
DiscreteHarmonicFormUtility.java 657 lines
|
||
DiscreteHolomorphicFormUtility.java 285 lines
|
||
Prerequisite — DEC operator layer (2026-05-28 scan, previously
|
||
unrecorded): the four utilities above are built on the discrete-
|
||
exterior-calculus primitives in heds/dec/ (DEC.java 76 lines,
|
||
AbstractDECOperator, DECPairing, DualChain, DualForm — the d / ⋆ /
|
||
primal-dual pairing operators). Port this thin operator layer
|
||
first; the form utilities assume it exists. Effort: ~3 days.
|
||
Effort: ~6 weeks net (1 DEC layer + 4 utility ports + 1 integration).
|
||
|
||
10b Siegel period matrix Ω ∈ H_g (g×g complex symmetric, Im(Ω) > 0)
|
||
→ Ωᵢⱼ = ∫_{bⱼ} ωᵢ
|
||
→ Reduction to Siegel fundamental domain via Sp(2g,ℤ).
|
||
Mathematical reference: Bobenko-Springborn 2004 + Gottschling 1959.
|
||
Bobenko, Mercat, Schmies 2009/2011 "Conformal
|
||
Structures / Period Matrices of Polyhedral
|
||
Surfaces" (arXiv:0909.1305) + Bobenko, Bücking 2021
|
||
"Convergence of discrete period matrices ..."
|
||
(Math. Phys. Anal. Geom. 24, Art. 23) — discrete
|
||
period matrix Ωᵢⱼ on polyhedral surfaces + convergence.
|
||
Bobenko, Lutz 2024 IMRN "Decorated Discrete Conformal
|
||
Maps and Convex Polyhedral Cusps" — uniformization
|
||
theorem connecting cusps ↔ hyperideal vertices
|
||
(bridges Phase 2/3 HyperIdeal geometry to 10b).
|
||
Pinkall, Springborn 2021 "A discrete version of
|
||
Liouville's theorem on conformal maps"
|
||
(Geom. Dedicata 214, 389–398; arXiv:1911.00966) —
|
||
proves uniqueness/rigidity of the discrete conformal
|
||
structure; justifies that Ω is a conformal invariant.
|
||
Java partial reference: DiscreteRiemannUtility.java (186 lines).
|
||
Requires: 10a.
|
||
Effort: ~1 week net after 10a.
|
||
|
||
10b' Alternative methods (parallel research track)
|
||
→ HyperbolicCyclicFunctional (Java, 530 lines) — completes the
|
||
classical three-mode set with hyperbolic energy.
|
||
→ Quasi-isothermic parametrisation (Lawson correspondence):
|
||
QuasiisothermicUtility.java + SinConditionApplication.java
|
||
(~1 200 Java lines combined).
|
||
→ MobiusCenteringFunctional (Java, 289 lines) — sphere centering.
|
||
→ StereographicUnwrapper (Java, 266 lines) — projects the
|
||
spherical layout S²→ℂ via stereographic projection plus a
|
||
Möbius centring step. Closes the visualisation gap from
|
||
`discrete_conformal_map_spherical()` (currently outputs
|
||
Point_3 on S²; many downstream uses want a 2-D atlas).
|
||
Effort: small (~3 days).
|
||
Each independent; can be tackled in any order.
|
||
|
||
10c Full uniformization for genus g ≥ 2
|
||
→ Embedding as H²/Γ with Γ ⊂ PSL(2,ℝ) a Fuchsian group.
|
||
Mathematical reference: Sechelmann 2016 §6 (discrete instance);
|
||
Bers 1960 (continuous theory).
|
||
Lutz 2023 "Canonical Tessellations of Decorated
|
||
Hyperbolic Surfaces" (Geom. Dedicata 217,
|
||
arXiv:2206.13461) — canonical Delaunay tessellations
|
||
in Penner coordinates; unifies the decorated
|
||
framework with the fundamental domain construction.
|
||
Bobenko, Lutz 2024 IMRN (arXiv:2305.10988) —
|
||
discrete uniformization theorem for decorated
|
||
piecewise Euclidean surfaces.
|
||
Born, Bücking, Springborn 2015 "Quasiconformal
|
||
distortion of projective transformations and discrete
|
||
conformal maps" (arXiv:1505.01341) — error estimates for
|
||
the discrete-to-smooth conformal approximation;
|
||
quantifies how well H²/Γ approximates the smooth
|
||
hyperbolic metric.
|
||
Java reference: NONE — Java has the polygon + period matrix
|
||
pieces but does not assemble them into
|
||
a Fuchsian-group representation.
|
||
Status: **fully new research.**
|
||
Requires: 10a + 10b + Phase 9c.
|
||
|
||
⚠️ SCOPE BOUNDARY (was 10c delivers vs. was offen bleibt):
|
||
10c as scoped here builds the *infrastructure* — Fuchsian-group
|
||
representation + H²/Γ embedding on the Sechelmann/Bobenko-Springborn
|
||
uniformisation path. The Lutz-SPECIFIC algorithms it references
|
||
(canonical Delaunay tessellation in Penner coordinates, Epstein-Penner
|
||
convex-hull construction, Weeks-flip extension, polyhedral realisation)
|
||
are NOT delivered automatically by reaching 10c — they sit ON TOP of
|
||
this infrastructure and are their own implementation effort.
|
||
→ that effort is split out as **Phase 13** (Chain B capstone).
|
||
10c = runway; Phase 13 = the Lutz algorithms that land on it.
|
||
|
||
10c' Optional Java-port additions (low priority)
|
||
→ KoebePolyhedron.java (321 lines) — Koebe-Andreev-Thurston
|
||
circle packings. Adds a fifth DCE method.
|
||
Rigidity: Bowers, Bowers, Lutz 2026 "Rigidity of Koebe Polyhedra
|
||
and Inversive Distance Circle Packings" (arXiv:2601.22903)
|
||
— theoretical uniqueness backing the KAT construction.
|
||
→ ElectrostaticSphereFunctional (127 lines) — sphere
|
||
distribution baseline.
|
||
→ CirclePatternLayout / CirclePatternUtility — face-circle
|
||
pattern layouts.
|
||
None of these are required for the genus-g uniformization
|
||
pipeline; they extend the breadth of methods.
|
||
```
|
||
|
||
---
|
||
|
||
## ◼ Phase 11+ — Specialised applications (optional, deferred)
|
||
|
||
> **Status:** out-of-scope for v1.0 but recorded here so that future
|
||
> contributors don't re-discover them. Both items live in the Java
|
||
> repo as plugin sub-packages and would benefit from porting *only*
|
||
> after Phase 10 is complete (they require the period-matrix and
|
||
> fundamental-domain infrastructure to be in place first).
|
||
|
||
```
|
||
11a Schottky uniformisation
|
||
Java plugin: plugin/schottky/* (~12 Java files, ~3 000 LoC)
|
||
Mathematical basis: Schottky group — discrete subgroup
|
||
Γ ⊂ PSL(2,ℂ) generated by hyperbolic loxodromic
|
||
elements, fundamental domain a sphere with
|
||
2g disjoint discs removed.
|
||
Use case: "handlebody" uniformisation, complement of
|
||
Phase 10c's Fuchsian-group representation
|
||
(Schottky represents Riemann surfaces as
|
||
quotients of domains in S² rather than of H²).
|
||
Requires: Phase 10b (period matrix) + working
|
||
Möbius-group machinery from Phase 7.
|
||
Effort: very large (4–6 weeks) — significant Java
|
||
code, complex-analytic algorithms,
|
||
substantial test design.
|
||
|
||
11b Riemann maps (planar conformal mapping)
|
||
Java plugin: plugin/riemannmap/* (~6 Java files, ~1 500 LoC)
|
||
Mathematical basis: Riemann mapping theorem — every simply
|
||
connected proper subdomain of ℂ is conformally
|
||
equivalent to the unit disc. Discrete version
|
||
via circle packing or Schwarz-Christoffel-like
|
||
formulae.
|
||
Use case: Texture mapping of bounded planar regions;
|
||
classical conformal mapping for engineering
|
||
applications (electrostatics, fluid flow).
|
||
Requires: Phase 10b' QuasiisothermicUtility or the
|
||
CP-Euclidean machinery from Phase 9a.1
|
||
(depending on the chosen discrete-Riemann
|
||
algorithm).
|
||
Effort: large (3–4 weeks) — smaller than Schottky
|
||
but still substantial. Heavy on
|
||
visualisation; consider porting only the
|
||
algorithmic core.
|
||
|
||
11c Multiply-connected planar conformal maps (CircleDomainUnwrapper)
|
||
Java source: unwrapper/CircleDomainUnwrapper.java (570 LoC)
|
||
Mathematical basis: Riemann mapping theorem for multiply-
|
||
connected domains — every n-connected planar
|
||
region is conformally equivalent to a disk
|
||
with (n−1) round holes (Koebe's "general
|
||
uniformization theorem", 1909).
|
||
Use case: Classical complex-analysis problems —
|
||
conformal mapping of an annulus, a torus
|
||
slit on a plane, fluid flow around obstacles,
|
||
electrostatics with multiple conductors.
|
||
**A use-case class conformallab++ does not
|
||
currently cover.**
|
||
Requires: Phase 10b' QuasiisothermicUtility or the
|
||
CP-Euclidean machinery from Phase 9a.1.
|
||
Effort: large (~2 weeks).
|
||
|
||
All three items are tracked here so the project memory is preserved;
|
||
none of them are roadmap commitments. See `research-track.md` for the
|
||
formal research-versus-port classification before starting any.
|
||
```
|
||
|
||
---
|
||
|
||
## ◼ Phase 12 — Decorated DCE & geometric transition (RESEARCH, near-term)
|
||
|
||
> **Note on ordering:** despite the higher number, Phase 12 is *near-term
|
||
> and independent* of Phases 9c–11. It builds ONLY on already-landed code
|
||
> and is the **short path (Chain A)** to a first Lutz-adjacent scientific
|
||
> result. It does **not** require the genus-g≥2 chain (9c/10a/10b/10c) or
|
||
> the holonomy-bug fix — those gate Phase 13 (Chain B), not this.
|
||
|
||
```
|
||
12 Decorated DCE & geometric transition (no Java parent)
|
||
→ Numerical demonstration of the Bobenko-Lutz "master theory":
|
||
one discrete conformal invariant, continuously deformable across
|
||
Euclidean / spherical / hyperbolic background geometry.
|
||
Mathematical reference:
|
||
Bobenko, Lutz 2025 "Decorated Discrete Conformal Equivalence in
|
||
Non-Euclidean Geometries" (Discrete & Comput. Geom.;
|
||
arXiv:2310.17529) §3 — Penner-coordinate decoration unifying the
|
||
three background geometries; continuous deformation at fixed
|
||
discrete conformal invariant.
|
||
Lutz 2024 PhD thesis (depositonce-20357) — full proofs.
|
||
Builds on (✅ already landed):
|
||
inversive_distance functional (9a.2), hyper_ideal (Springborn 2020),
|
||
spherical functional — the decoration is a RE-PARAMETRISATION of
|
||
these, not a new solver.
|
||
Does NOT require: 9c / 10a / 10b / holonomy-bug fix.
|
||
Scope:
|
||
1. Decoration layer: per-vertex circle/horocycle radius as Penner
|
||
coordinate; map ↔ existing inversive distance I_ij (classical
|
||
formula ℓ²=r_i²+r_j²+2r_ir_jη).
|
||
2. Transition driver: deform background curvature κ ∈ {+,0,−} while
|
||
holding the discrete conformal invariant fixed; solve per geometry.
|
||
3. Validation harness producing example galleries.
|
||
Acceptance criteria:
|
||
- Decoration round-trip I_ij ↔ (r_i,r_j,ℓ) at machine precision.
|
||
- At κ=0: bit-for-bit match with existing euclidean/inversive path.
|
||
- Gauss-Bonnet per geometry; invariant constant across the κ-transition
|
||
to tol (numerical witness of the Bobenko-Lutz master theorem).
|
||
- Cross-geometry: one test surface solved in all three backgrounds
|
||
shares the invariant.
|
||
Effort: medium (functionals exist; reparametrisation + driver + tests).
|
||
Status: 🔲 planned (proposed 2026-05-29).
|
||
```
|
||
|
||
---
|
||
|
||
## ◼ Phase 13 — Decorated canonical tessellations & polyhedral realisation (Chain B capstone)
|
||
|
||
> **This is the genus-g≥2 Lutz contribution.** It sits ON TOP of the
|
||
> infrastructure built by Phases 9c + 10a + 10b + 10c (see the 10c SCOPE
|
||
> BOUNDARY note above) and implements Lutz's *specific* algorithms that the
|
||
> 10c "runway" does not deliver by itself.
|
||
|
||
```
|
||
13 Decorated canonical tessellations + polyhedral realisation (no Java parent)
|
||
→ Canonical Delaunay tessellation of a decorated hyperbolic surface
|
||
in Penner coordinates, its dual decomposition, and the polyhedral
|
||
realisation of the uniformised genus-g≥2 surface.
|
||
Mathematical reference:
|
||
Lutz 2023 "Canonical Tessellations of Decorated Hyperbolic Surfaces"
|
||
(Geom. Dedicata 217; arXiv:2206.13461) — canonical (weighted-
|
||
Delaunay-analogue) tessellation + dual; Epstein-Penner convex-hull
|
||
construction in Minkowski space; Weeks-flip extension.
|
||
Bobenko, Lutz 2024 IMRN (arXiv:2305.10988) — discrete uniformization
|
||
theorem for decorated surfaces (cusps ↔ hyperideal vertices).
|
||
Lutz 2024 PhD thesis (depositonce-20357) — polyhedral realisation +
|
||
complete proofs for 9d.2 / 10b / 10c / 13.
|
||
Rigidity backing: Bowers, Bowers, Lutz 2026 (arXiv:2601.22903).
|
||
PREREQUISITES (the "given Voraussetzungen" — all must be in place):
|
||
✅ cut_graph.hpp (2g seams) — landed
|
||
🔲 Phase 9c — 4g-gon fundamental domain
|
||
🔲 Phase 10a — holomorphic/harmonic 1-forms
|
||
🔲 Phase 10b — Siegel period matrix Ω ∈ H_g
|
||
🔲 Phase 10c — Fuchsian-group representation / H²/Γ embedding
|
||
🔲 holonomy-bug fix — detail::spherical_holonomy /
|
||
detail::hyperbolic_holonomy (+ cpp_dec_float_50 for the
|
||
group-relation product ∏gᵢ = Id); see research-track.md §9c.
|
||
🟡 Phase 12 — decoration layer (Penner coords) is reused here;
|
||
strongly recommended to land Phase 12 first so the Penner-
|
||
coordinate machinery already exists.
|
||
Scope:
|
||
1. Penner-coordinate weighted-Delaunay (canonical) tessellation +
|
||
dual decomposition on the H²/Γ embedding from 10c.
|
||
2. Epstein-Penner convex-hull construction (Minkowski space) to
|
||
obtain the canonical decomposition; Weeks-flip to reach it.
|
||
3. Polyhedral realisation of the uniformised surface.
|
||
Acceptance criteria:
|
||
- Canonical tessellation is unique & flip-stable (Weeks-flip
|
||
terminates; result independent of start triangulation).
|
||
- Decoration / Penner-coordinate consistency with Phase 12 layer.
|
||
- Gauss-Bonnet + holonomy closure ∏[a_i,b_i] = Id (high precision).
|
||
- Rigidity witness: Newton finds the unique realisation on the
|
||
tangency-case test set (Bowers-Bowers-Lutz 2026).
|
||
Effort: very large (depends on the full 9c/10a/10b/10c chain landing
|
||
first; the Lutz algorithms themselves ≈ several weeks on top).
|
||
Status: 🔲 planned (Chain B capstone; gated on prerequisites above).
|
||
```
|