Files
ConformalLabpp/doc/roadmap/phases.md
Tarik Moussa 068df474b1 docs: integrate publication analysis — Alexa, Bobenko, Springborn, Crane, Lutz
Add phases 9d / 9e / 9f and literature citations derived from a systematic
review of the five authors' publication lists (Tier 1 / 2 / 3 analysis).

phases.md:
  - Phase 9d: ConesUtility port (9d.1) + non-Euclidean cone extensions
    (9d.2, RESEARCH) + StereographicUnwrapper (9d.3)
  - Phase 9e: CirclePatternLayout + CirclePatternUtility (Java port)
  - Phase 9f: Polygon Laplacian on non-triangular meshes (Alexa 2011/2020,
    RESEARCH — no Java equivalent)
  - Phase 9b-analytic: add Rivin-Springborn 1999 as Schläfli source
  - Phase 10b: add Bobenko-Bücking 2009 + Bobenko-Lutz 2024 IMRN
  - Phase 10c: add Lutz 2023 (canonical tessellations) + Bobenko-Lutz 2024
  - Phase 10c' KoebePolyhedron: add Bowers-Bowers-Lutz 2026 rigidity result

references.md:
  - Crane et al. 2018 Optimal Cone Singularities (Phase 9d.2)
  - Bobenko-Lutz 2025 Discrete & Comput. Geom. (Phase 9d.2)
  - Bobenko-Lutz 2024 IMRN (Phase 10b/c)
  - Lutz 2023 Geom. Dedicata (Phase 10c)
  - Lutz PhD thesis TU Berlin 2024 (Phases 9d.2, 10b, 10c)
  - Bowers-Bowers-Lutz 2026 (Phase 9b-analytic + 10c')
  - Alexa-Wardetzky 2011 + Alexa 2020 (Phase 9f)
  - Bobenko-Bücking 2009 (Phase 10b)
  - Rivin-Springborn 1999 (Phase 9b-analytic)

research-track.md:
  - New entry: Phase 9d.2 non-Euclidean cone extensions (Bobenko-Lutz 2025
    + Crane 2018), with acceptance criteria
  - New entry: Phase 9f polygon Laplacian (Alexa-Wardetzky 2011 / Alexa 2020),
    with acceptance criteria

java-parity.md:
  - Split cone-metrics row into Euclidean (9d.1 port) and non-Euclidean
    (9d.2 research) with literature references
  - Add ConesUtility to "utility classes not yet ported" table

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-26 11:15:09 +02:00

488 lines
25 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Development Roadmap
> **Legend:** ✅ complete · 🔲 planned
>
> **Porting / research boundary:**
> Phases 17 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 17
```
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 GaussBonnet 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
Mathematical source: Springborn 2020 §4 + Schläfli 1858/60
+ Rivin, Springborn 1999 "The Schläfli formula in
Einstein manifolds with boundary" (ERA-AMS 5)
+ Cho-Kim 1999 + Glickenstein 2011 §4
Algorithm: explicit chain rule through (bᵢ,aₑ) → ℓᵢⱼ → ζ₁₃/ζ₁₄/ζ₁₅ → αᵢⱼ/βᵢ
Includes: short LaTeX correctness note in doc/math/.
Effort: 1014 days net. Trigger: profiling on V > 5000.
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)
Mathematical source: Poincaré 1882 + Sechelmann 2016 §5
Research component: bridging to conformallab++ cut_graph.hpp
+ holonomy infrastructure.
Effort: ~2 weeks for fundamental polygon, +2 weeks for surgery
layer, +1 week integration.
9d — Cone singularities + sphere atlas (Java port + research extension)
────────────────────────────────────────────────────────────────────────
9d.1 ConesUtility (Java port — Euclidean only)
→ cones_utility.hpp
Java source: ConesUtility.java (~200 lines)
Mathematical reference: Troyanov 1991 + Springborn 2020 §3
Port scope: prescribed cone angles Θᵥ ≠ 2π in Euclidean mode.
Status: 🔲 planned
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.
Crane, Soliman, Ben-Chen, Schröder 2018 "Optimal Cone Singularities
for Conformal Flattening" (ACM SIGGRAPH 2018) — L¹-optimal
automatic cone placement; directly applicable to 9d.2 algorithm.
Status: 🔲 planned
9d.3 StereographicUnwrapper (Java port)
→ stereo_unwrapper.hpp
Java source: StereographicUnwrapper.java (266 lines)
Converts spherical DCE output (Point_3 on S²) to a 2-D atlas
via stereographic projection + Möbius centring.
Closes the visualisation gap from discrete_conformal_map_spherical().
Effort: small (~3 days).
Status: 🔲 planned
9e — CirclePatternLayout (Java port)
─────────────────────────────────────
9e CirclePatternLayout + CirclePatternUtility (Java port)
→ circle_pattern_layout.hpp
Java sources: CirclePatternLayout.java + CirclePatternUtility.java
+ CPEuclideanRotation.java
Mathematical reference: Bobenko-Springborn 2004 variational principle
+ Bobenko-Hoffmann-Springborn 2006 "Minimal
surfaces from circle patterns" (Discrete &
Comput. Geom. 35, 2006).
Status: 🔲 planned
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.
Alexa 2020 "Discrete Laplacians on General Polygonal Meshes"
(ACM TOG 39, 2020) — extended journal treatment, error bounds.
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).
```
9d — Cone metrics + sphere utilities (Java port — 2026 library scan)
────────────────────────────────────────────────────────────────────
```
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
9d.2 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)
9d.3 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
```
---
## ◼ New research directions — Phases 10d10g (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 (KoebeAndreevThurston)
→ 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: KoebeAndreevThurston + BeardonStephenson 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 + BohleLamPinkallReitebuch 2015
10f Koebe polyhedra
→ koebe_polyhedron.hpp
KoebeAndreevThurston 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 810. 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
(GillespieSpringbornCrane 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 GillespieSpringbornCrane
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, GaussBonnet,
variational principle of BobenkoSpringborn 2004).
---
## ◼ 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.
Java sources (partial, port-with-research):
CanonicalBasisUtility.java 337 lines (homology basis)
HomologyUtility.java 122 lines
DualityUtility.java 308 lines
DiscreteHarmonicFormUtility.java 657 lines
DiscreteHolomorphicFormUtility.java 285 lines
Effort: ~6 weeks net (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, Bücking 2009 "Conformal Structures and
Period Matrices of Polyhedral Surfaces" — discrete
period matrix Ωᵢⱼ on polyhedral surfaces.
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).
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.
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.
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 circle polyhedra
and hyperideal polyhedra: the tangency case" (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 (46 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 (34 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 (n1) 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.
```