From 8e9ec9eccfb091bf5c9a2ac66f8990773ddd121e Mon Sep 17 00:00:00 2001 From: Tarik Moussa Date: Mon, 25 May 2026 23:17:48 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20full=20Java=20library=20scan=20?= =?UTF-8?q?=E2=80=94=20new=20phases=209d/9e/10d=E2=80=9310g=20+=20parity?= =?UTF-8?q?=20table?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Complete scan of all de.varylab.discreteconformal packages (functional/, unwrapper/, unwrapper/circlepattern/, unwrapper/koebe/, unwrapper/quasiisothermic/, uniformization/, util/) against the current roadmap. New items added to java-parity.md: - ConesUtility: cone detection, BFS cut, auto-placement, quantization (9d) - MobiusCenteringFunctional: variational Lösung über Lorentz-Geometrie (9d) - ElectrostaticSphereFunctional: Initialisierungsheuristik auf S² (9d) - StereographicUnwrapper + SphereUtility: S²→ℂ atlas für genus-0 (9d) - CirclePatternLayout + CirclePatternUtility + CPEuclideanRotation (9e) - CutAndGlueUtility, StitchingUtility, PathUtility (9c additions) - DualityUtility: Hodge-Stern + dual cycles — prerequisite 10a - HyperellipticUtility + HyperIdealHyperellipticUtility (10b) - CircleDomainUnwrapper: Koebe-Andreev-Thurston (10d) - quasiisothermic/ package: QI maps + DBF + sin-condition (10e) - KoebePolyhedron (10f) - EuclideanCyclicFunctional + HyperbolicCyclicFunctional (10g) - "Do not port" table: ColtIterationReporter, PETSc wrappers, etc. New phases added to phases.md: - Phase 9d: ConesUtility + StereographicUnwrapper + MobiusCenteringFunctional - Phase 9e: CirclePatternLayout (complement to already-ported 9a.1) - Phase 10d: CircleDomainUnwrapper (Koebe-Andreev-Thurston) - Phase 10e: quasi-isothermic maps - Phase 10f: Koebe polyhedra - Phase 10g: cyclic-symmetry functionals Co-Authored-By: Claude Sonnet 4.6 --- doc/roadmap/java-parity.md | 93 ++++++++++++++++++++++++++++++++++---- doc/roadmap/phases.md | 83 ++++++++++++++++++++++++++++++++++ 2 files changed, 168 insertions(+), 8 deletions(-) diff --git a/doc/roadmap/java-parity.md b/doc/roadmap/java-parity.md index d50b304..28e0b30 100644 --- a/doc/roadmap/java-parity.md +++ b/doc/roadmap/java-parity.md @@ -67,14 +67,91 @@ They are candidates for Phase 9 or Phase 10. Note: items marked as *new research* (e.g. Inversive Distance, HyperIdeal Hessian variants) are tracked separately in `doc/roadmap/research-track.md`. -| `HomotopyUtility` | Homotopy generators | 9c | -| `SpanningTreeUtility` | Spanning tree algorithms | 8 / infrastructure | -| `SurgeryUtility` | Mesh surgery (cut/glue) | — | -| `StitchingUtility` | Seam stitching | — | -| `CuttingUtility` | Advanced cutting (beyond tree-cotree) | 9c | -| `HyperellipticUtility` | Hyperelliptic surfaces | 10 | -| `LaplaceUtility` | Discrete Laplace operators | 9 / infrastructure | -| `ConformalStructureUtility` | Conformal structure extraction | 10 | + +--- + +## Java packages not yet in the roadmap — 2026 full-library scan + +A complete scan of the Java source tree (`de.varylab.discreteconformal`) revealed the +following packages and classes not yet covered by Phases 1–9c or the Phase-10 plan. +Organised by value / effort. + +### Functional package (`de.varylab.discreteconformal.functional`) + +| Java class | What it does | Proposed phase | +|---|---|---| +| `ConesUtility` (in `unwrapper/`) | Cone singularity detection, BFS-path cutting from cone to boundary, auto-placement via conjugate gradient, quantization to π/2 / π/3 / π/6 — fills the "⚠️ data structure only" gap in the parity table | **9d** | +| `MobiusCenteringFunctional` | Variational Möbius centering via Lorentz geometry: E = Σ log(−⟨x,p⟩/√(−⟨x,x⟩)). Supplies full gradient + Hessian — more principled than the iterative Fréchet mean in `normalise_hyperbolic()` | **9d** | +| `ElectrostaticSphereFunctional` | Repulsive electrostatic energy on S² (E = Σ 0.5/d² + sphere constraint). Useful as initialization heuristic for spherical uniformization | **9d** (optional) | +| `EuclideanCyclicFunctional` | Euclidean DCE functional reduced to a cyclic-symmetry quotient — reduces DOFs for surfaces with cyclic symmetry group | **10g** | +| `HyperbolicCyclicFunctional` | Hyperbolic analogue of above | **10g** | + +### Circle pattern package (`de.varylab.discreteconformal.unwrapper.circlepattern`) + +| Java class | What it does | Proposed phase | +|---|---|---| +| `CirclePatternUtility` | Computes circle pattern radii (ρ per face) via Newton trust-region on CPEuclidean energy — the solver side | **9e** | +| `CirclePatternLayout` | Embeds a circle pattern in the plane from the ρ values — the layout side. Required complement to `cp_euclidean_functional.hpp` already ported in 9a.1 | **9e** | +| `CPEuclideanRotation` | Rotation-invariant variant of the CP-Euclidean functional | **9e** | + +### Uniformization package (`de.varylab.discreteconformal.uniformization`) + +| Java class | What it does | Proposed phase | +|---|---|---| +| `CutAndGlueUtility` | Mesh surgery beyond tree-cotree: arbitrary cut paths, gluing cut surfaces back together — needed for genus g > 1 canonical polygon construction | **9c** (add to existing plan) | +| `VisualizationUtility` | Java/jReality specific — do not port | — | +| `Uniformizer` | High-level pipeline driver — already covered by our CLI + pipeline API | — | + +### Unwrapper package — additional classes + +| Java class | What it does | Proposed phase | +|---|---|---| +| `StereographicUnwrapper` | Stereographic projection S²→ℂ∪{∞} + Möbius centring — converts spherical DCE output to 2-D atlas for genus-0 | **9d** | +| `SphereUtility` | Sphere-specific utilities (area centroid, antipodal, normalization helpers) | **9d** | +| `CircleDomainUnwrapper` | Conformal map of multiply-connected planar region onto disk-with-holes (Koebe-Andreev-Thurston) | **10d** | + +### Quasi-isothermic package (`de.varylab.discreteconformal.unwrapper.quasiisothermic`) + +Quasi-isothermic maps generalize conformal maps to meshes where exact conformality is impossible. +Entirely absent from the current roadmap. + +| Java class | What it does | Proposed phase | +|---|---|---| +| `QuasiisothermicDelaunay` | Delaunay-conformal triangulation as QI preprocessing | **10e** | +| `QuasiisothermicLayout` | Embedding from quasi-isothermic DOFs | **10e** | +| `QuasiisothermicUtility` | Lawson-correspondence parameterization (~800 lines) | **10e** | +| `DBFSolution` | Discrete Beltrami field solution | **10e** | +| `SinConditionApplication` | Sin-condition functional for QI maps | **10e** | +| `ConformalStructureUtility` | Conformal structure extraction from QI solution | **10e** | + +### Koebe package (`de.varylab.discreteconformal.unwrapper.koebe`) + +| Java class | What it does | Proposed phase | +|---|---|---| +| `KoebePolyhedron` | Koebe–Andreev–Thurston theorem: realization of every 3-connected planar graph as a convex polyhedron with edges tangent to the unit sphere (321 lines) | **10f** | + +### Util package — additional classes not yet in roadmap + +| Java class | What it does | Proposed phase | +|---|---|---| +| `DualityUtility` | Hodge-star operator + dual cycles via cotangent weights — **prerequisite for Phase 10a** (discrete holomorphic forms need the dual mesh) | **10a prerequisite** (consider 9c) | +| `HyperellipticUtility` | Hyperelliptic surfaces (genus g ≥ 2 with Z₂ symmetry) — period matrix has block-diagonal structure | **10b** | +| `HyperIdealHyperellipticUtility` | HyperIdeal variant for hyperelliptic surfaces | **10b** | +| `PathUtility` | Mesh path operations — supporting infrastructure for Phase 9c homology basis | **9c** | +| `LaplaceUtility` | Discrete Laplace operators (cotangent + combinatorial) | **9 / infrastructure** | +| `EdgeUtility` | Edge orientation and classification helpers | **infrastructure** | +| `StitchingUtility` | Seam stitching after cut-and-glue | **9c** | + +### Do not port — Java-specific or superseded + +| Java class | Reason | +|---|---| +| `ColtIterationReporterImpl` | Colt sparse matrix library — replaced by Eigen | +| `NodeIndexComparator` | Java Comparator — replaced by `std::less` | +| `SimpleMatrixPrintUtility` | Debug print — Eigen `.format()` is sufficient | +| `EuclideanUnwrapperPETSc` / `SphericalNormalizerPETSc` | PETSc solver binding — replaced by Eigen | +| `Search` | CoHDS-specific graph search — replaced by CGAL halfedge iteration | +| `SparseUtility` | Colt sparse matrix utils — replaced by Eigen | --- diff --git a/doc/roadmap/phases.md b/doc/roadmap/phases.md index e177d54..7fb34d6 100644 --- a/doc/roadmap/phases.md +++ b/doc/roadmap/phases.md @@ -129,6 +129,89 @@ mesh type. layer, +1 week 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