Merge pull request 'feat(geometry): pn_geometry.hpp — Pn projective-metric substrate (jReality port)' (#31) from feat/pn-geometry-substrate into main

doc/roadmap/java-parity.md

@@ -43,6 +43,22 @@ as the reference implementation for expected behaviour, edge cases, and test cas
 
 ---
 
+## Infrastructure / support layers
+
+These are not algorithmic phases but shared geometry substrates that multiple phases
+depend on.  Porting them once unblocks all downstream consumers.
+
+| Java library | What it provides | C++ status | Notes |
+|---|---|---|---|
+| **`de.jreality.math.Pn`** | Projective-metric primitives: inner product, norm, distance, geodesic interpolation in Euclidean / Elliptic / Hyperbolic signatures | ⚠️ **partial** → `pn_geometry.hpp` (2026-05-30) | 6 functions (~30 LOC) cover the entire surface used by the Java algorithmic core (27 files, ≈106 imports). Unblocks: HyperbolicLayout, SphericalLayout, FundamentalPolygon (9c), KoebePolyhedron (10c'), quasi-isothermic (10e), hyperelliptic θ, CircleDomain (11c). |
+| **`de.jreality.math.Rn`** | Real vector / matrix utilities (add, sub, scale, dot, norm, …) | ⚠️ partial → Eigen | The Rn surface used in the core (16 distinct methods) maps directly onto Eigen VectorXd / MatrixXd operations. No separate port needed; call-sites replace `Rn.foo(a,b)` with Eigen expressions inline. |
+| **`de.jreality.math.Matrix`** | 4×4 matrix wrapper (times, print) | ✅ → Eigen `Matrix4d` | `Matrix.times` = matrix multiplication; call-sites replace it with Eigen `operator*`. No separate port needed. |
+| **`de.jreality.math.P2`** | Projective plane geometry: `lineFromPoints`, `pointFromLines`, `projectP3ToP2`, `makeDirectIsometryFromFrames`, `imbedMatrixP2InP3`, `chopConvexPolygonWithLine` | ⚠️ **port inline with Phase 9c** | Used almost exclusively by `FundamentalPolygonUtility` + `CanonicalFormUtility` + `SurfaceCurveUtility` (all Phase 9c). Port these ~5 functions as a `p2_geometry.hpp` at the start of the Phase 9c session, not before. `lineFromPoints` / `pointFromLines` = cross products in ℙ²; `makeDirectIsometryFromFrames` = direct isometry from two point-pairs (~25 LOC). |
+| **`de.jreality.math.MatrixBuilder`** | Isometry construction: `rotateFromTo`, `translateFromTo` in Euclidean / Hyperbolic models | ❌ not yet | Used only by `HyperIdealHyperellipticUtility` (hyperelliptic θ). Port on demand when that utility is needed. |
+| **conformallab XML types** (`de.varylab.conformallab.types.*`) | JAXB-generated persistence format for Java GUI state (`HalfedgeEmbedding`, `UniformizationData`, …) | ❌ not planned | GUI / persistence layer, not an algorithmic substrate. conformallab++ has its own serialisation (`serialization.hpp`). Asset-specific parsers (e.g. for `lawson_curve_source.xml`) are added on demand, not as a general port. |
+
+---
+
 ## Java utility classes not yet ported
 
 These exist in `de.varylab.discreteconformal.util` in the Java library.
@@ -52,8 +68,8 @@ They are candidates for Phase 9 or Phase 10.
 |---|---|---|
 | `ConesUtility` (~200 lines) | Prescribed cone angles Θᵥ ≠ 2π — Euclidean mode only | 9d.1 |
 | `CPEuclideanFunctional` | Face-based circle-packing energy (BPS 2010) | 9a.1 |
-| `FundamentalPolygonUtility` (698 lines) | Construction + canonicalisation of 4g-gons for genus-g | 9c |
-| `CanonicalFormUtility` (532 lines) | High-level wrapper for 9c — drives canonicalisation pipeline | 9c |
+| `FundamentalPolygonUtility` (698 lines) | Construction + canonicalisation of 4g-gons for genus-g. **⚠️ jReality dependency:** uses `P2.makeDirectIsometryFromFrames`, `P2.projectP3ToP2`, `P2.imbedMatrixP2InP3` → port these as `p2_geometry.hpp` at the start of the Phase 9c session (see Infrastructure table above). Also uses `P2Big.*` (high-precision counterparts) + requires `cpp_dec_float_50` for the group-relation product ∏gᵢ = Id. | 9c |
+| `CanonicalFormUtility` (532 lines) | High-level wrapper for 9c — drives canonicalisation pipeline. **⚠️ jReality dependency:** same `P2.*` methods as above via `FundamentalPolygonUtility`. | 9c |
 | `CuttingUtility` + `SurgeryUtility` (~800 lines) | Mesh cuts and gluing operations needed for fundamental domains | 9c (foundation) |
 | `DiscreteHarmonicFormUtility` (657 lines) | Discrete harmonic 1-forms via cotangent Laplacian (Hodge theory) | 10a prerequisite |
 | `DiscreteHolomorphicFormUtility` (285 lines) | Holomorphic differentials via Mercat complex structure | 10a (Bobenko-Springborn 2004 §6) |