# 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 ``` --- ## β—Ό 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: 10–14 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 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). --- ## β—Ό 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 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). Springborn 2019 "A discrete version of Liouville's theorem on conformal maps" (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. Springborn, Veselov 2015 "Quasiconformal distortion of projective transformations and discrete conformal maps" (Int. Math. Res. Not.) β€” 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. 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 (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. ```