docs: full Java library scan — new phases 9d/9e/10d–10g + parity table
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 <noreply@anthropic.com>
This commit is contained in:
Tarik Moussa
@@ -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)
|
Note: items marked as *new research* (e.g. Inversive Distance, HyperIdeal Hessian variants)
|
||||||
are tracked separately in `doc/roadmap/research-track.md`.
|
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 | — |
|
## Java packages not yet in the roadmap — 2026 full-library scan
|
||||||
| `CuttingUtility` | Advanced cutting (beyond tree-cotree) | 9c |
|
|
||||||
| `HyperellipticUtility` | Hyperelliptic surfaces | 10 |
|
A complete scan of the Java source tree (`de.varylab.discreteconformal`) revealed the
|
||||||
| `LaplaceUtility` | Discrete Laplace operators | 9 / infrastructure |
|
following packages and classes not yet covered by Phases 1–9c or the Phase-10 plan.
|
||||||
| `ConformalStructureUtility` | Conformal structure extraction | 10 |
|
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 |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
@@ -129,6 +129,89 @@ mesh type.
|
|||||||
layer, +1 week integration.
|
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
|
## ◼ Optional / Hypothetical — geometry-central Cross-Comparison
|
||||||
|
|||||||
Reference in New Issue
Block a user