From 0c520046fb61e964bdb234144b922b350175592d Mon Sep 17 00:00:00 2001 From: Tarik Moussa Date: Tue, 26 May 2026 06:18:26 +0200 Subject: [PATCH] =?UTF-8?q?docs(reviewer):=20baustein=20D=20=E2=80=94=20cl?= =?UTF-8?q?ose=20Java-scan=20+=20lit-integration=20gaps?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Earlier baustein B (`07c653c`) added a 6-row Research-Alignments table + a "what's new" banner, but only surfaced ~75 % of what the four Java-scan + literature-integration commits (`f854f0e`, `979f30c`, `e8a118f`, `8daee1b`) had introduced. This commit closes the gaps identified in the lückenprüfung: Research-Alignments table grows from 6 → 10 rows ───────────────────────────────────────────────── * +quasi-isothermic maps (Phase 10e, Java port — 6 classes incl. discrete Beltrami-field solver, Lawson correspondence ~800 lines) * +higher-genus + hyperelliptic surfaces (Phase 10b — `HyperellipticUtility` + Bobenko–Bücking 2009) * +Möbius centring as variational problem (Phase 9d.4 — replaces the iterative Fréchet-mean fallback in `normalise_hyperbolic()`) * +Boundary-First / interactive flattening row (Crane 2017 BFF; Stripe Patterns 2015) — listed for comparison even though it is not on the porting roadmap, so the reader sees we know about it * table caption clarifies that some rows are RESEARCH-only (no Java parent) and some are planned ports "What's new" banner ─────────────────── * citation count corrected from "+9" to "+13" — the four Tier-2 papers added in commit `e8a118f` (Springborn 2019, Springborn–Veselov 2015, Crane 2017 BFF, Bonneel et al. 2015 Stripe Patterns) are now named * phase count of "+6 phases" kept, but +Phase 9d.4 (Möbius centring) and +Phase 10e (quasi-isothermic) are now called out explicitly so the reader knows what is in the count * cross-link to `java-parity.md` for the reverse table (every Java class → C++ destination or *do-not-port* rationale) questions.md / Q1 ───────────────── * expand the table from 3 to 6 candidate phases — adding 10e (quasi- isothermic), 10b (hyperelliptic), and 9d.4 (Möbius centring) as options alongside the existing 9d.2 / 9f / 10c+10c′ * track column distinguishes RESEARCH-only from planned-port * +Question C — "is there a seventh line we are missing?" — invites the reader to flag a research thread we have not scoped yet Pages hub will be refreshed to v5 in a follow-up step (separate from the in-repo commit, lives only on the codeberg `pages` branch). Co-Authored-By: Claude Opus 4.7 --- doc/reviewer/briefing.md | 48 +++++++++++++++++++++++++++------------ doc/reviewer/questions.md | 35 ++++++++++++++++++---------- 2 files changed, 56 insertions(+), 27 deletions(-) diff --git a/doc/reviewer/briefing.md b/doc/reviewer/briefing.md index e15f85a..e147b06 100644 --- a/doc/reviewer/briefing.md +++ b/doc/reviewer/briefing.md @@ -36,7 +36,9 @@ shows static quality-gate status. ## Research alignments — where this library could be infrastructure for your work The current snapshot already contains, or has roadmap entries for, -the following: +the following. Most rows match an active publication line in +discrete differential geometry; a few (marked *no Java parent*) are +research-only phases the reader can shape at design stage. | Your research thread | What this snapshot has | Phase | |---|---|---| @@ -44,27 +46,43 @@ the following: | **Canonical Delaunay tessellations of decorated hyperbolic surfaces** (Lutz 2023, *Geom. Dedicata*; Lutz 2024 PhD thesis) | cut-graph + period matrix + hyperbolic-disk layout as scaffolding; canonical-tessellation algorithm itself outlined | **10c** planned | | **Hyperideal polyhedra rigidity** (Bowers–Bowers–Lutz 2026) | HyperIdeal functional + analytic Hessian derivation (805-line LaTeX note) | **9b-analytic** derived; **10c′** KAT planned | | **Optimal cone placement / non-Euclidean cone metrics** (Crane et al. 2018) | Cone-singularity port via `ConesUtility` scoped; the *non-Euclidean* extension is the research delta | **9d.1** port + **9d.2** RESEARCH | -| **Polygon Laplacian on general meshes** (Alexa–Wardetzky 2011; Alexa 2020) | no Java parent; first phase a reviewer can shape at design stage | **9f** RESEARCH (planned) | +| **Polygon Laplacian on general meshes** (Alexa–Wardetzky 2011; Alexa 2020) | *no Java parent* — first phase a reviewer can shape at design stage | **9f** RESEARCH (planned) | +| **Quasi-isothermic maps** (generalising conformality where exact conformality is impossible — Lawson-correspondence parameterisation) | scoped as a 6-class port (~800 lines) from the Java original: `QuasiisothermicLayout`, `DBFSolution` (discrete Beltrami field), `SinConditionApplication`, `QuasiisothermicDelaunay`, `QuasiisothermicUtility`, `ConformalStructureUtility` | **10e** planned | +| **Higher-genus + hyperelliptic surfaces** (Bobenko–Bücking 2009 on polyhedral surfaces; period matrices with block-diagonal Z₂ structure) | port of `HyperellipticUtility` + `HyperIdealHyperellipticUtility` scoped; existing period-matrix code as scaffolding | **10b** planned | +| **Möbius centring for Poincaré-disk layouts** as a variational problem (Lorentz geometry: `E = Σ log(−⟨x,p⟩/√(−⟨x,x⟩))`) | currently we use iterative Fréchet mean in `normalise_hyperbolic()`; the principled variational alternative is scoped via the Java `MobiusCenteringFunctional` port (full gradient + Hessian) | **9d.4** planned | +| **Boundary-First / interactive flattening** (Crane et al. 2017 BFF; Bonneel et al. 2015 *Stripe Patterns on Surfaces*) | not on the roadmap as ports; documented in [`references.md`](../math/references.md) as comparison points / inspiration for future API design | — | | **Schläfli-based variational machinery** (Rivin–Springborn 1999) | derivation done, implementation gated on your view of whether the ~6× speedup over our block-FD path matters at your mesh sizes | **9b-analytic** ready to implement | -See [`doc/roadmap/research-track.md`](../roadmap/research-track.md) -for the per-phase acceptance criteria and -[`doc/roadmap/phases.md`](../roadmap/phases.md) for the porting plan. +See [`doc/roadmap/phases.md`](../roadmap/phases.md) for the per-phase +porting plan, [`doc/roadmap/research-track.md`](../roadmap/research-track.md) +for the items beyond Java parity with explicit acceptance criteria, +and [`doc/roadmap/java-parity.md`](../roadmap/java-parity.md) for the +reverse table (every Java class → C++ destination or *do-not-port* +rationale). ## What's new on this snapshot (since the previous publish) -- **+6 new porting-roadmap phases** (9d cones / 9e circle-pattern - layout / 10d Koebe circle-domain / 10e quasi-isothermic / 10f Koebe - polyhedra / 10g cyclic-symmetry quotients) derived from a full - Java-library scan. -- **+9 literature citations** integrated into the roadmap, all - Tier-1/2 in the research line above (Bobenko–Lutz 2024 IMRN; - Bobenko–Lutz 2025 DCG; Lutz 2023 Geom. Dedicata; Lutz 2024 PhD; - Bowers–Bowers–Lutz 2026; Crane et al. 2018; Alexa–Wardetzky 2011; - Alexa 2020; Rivin–Springborn 1999). -- **Phase 9f** (polygon Laplacian on general meshes) added as +- **+6 new porting-roadmap phases** (9d cones + 9d.4 Möbius centring / + 9e circle-pattern layout / 10d Koebe circle-domain / 10e + quasi-isothermic / 10f Koebe polyhedra / 10g cyclic-symmetry + quotients) derived from a full Java-library scan. See `phases.md` + for the per-phase plan and `java-parity.md` for the reverse table. +- **+13 literature citations** integrated into the roadmap, all + Tier-1/2. Decorated-DCE / canonical-tessellation / hyperideal line: + Bobenko–Lutz 2024 IMRN; Bobenko–Lutz 2025 *DCG*; Lutz 2023 + *Geom. Dedicata*; Lutz 2024 PhD; Bowers–Bowers–Lutz 2026. Cones, + polyhedra, period matrices: Crane et al. 2018; Springborn 2019 + (hyperbolic polyhedra); Bobenko–Bücking 2009; Rivin–Springborn 1999. + Polygon Laplacians: Alexa–Wardetzky 2011; Alexa 2020. Integrable + + practical-flattening context: Springborn–Veselov 2015 (cluster + dynamics); Crane et al. 2017 (BFF); Bonneel et al. 2015 (Stripe + Patterns). +- **Phase 9f** (polygon Laplacian on non-triangular meshes) added as RESEARCH-only — no Java parent — so you can influence its design before it exists. +- **Phase 10e** (quasi-isothermic maps) and **Phase 9d.4** (variational + Möbius centring) newly scoped from the Java scan; both touch + research lines adjacent to decorated DCE. - **`output_uv_map`** now covers 4 of 5 DCE solvers (Inversive-Distance added; CP-Euclidean deferred to Phase 9c with a clear runtime error rather than silent failure). diff --git a/doc/reviewer/questions.md b/doc/reviewer/questions.md index 131fa15..9d09c85 100644 --- a/doc/reviewer/questions.md +++ b/doc/reviewer/questions.md @@ -21,18 +21,22 @@ These are the seven items that would benefit most from a second opinion. --- -## Q1 — Research-track alignment: which RESEARCH phase would unblock concrete experiments you want to run? +## Q1 — Research-track alignment: which RESEARCH or planned phase would unblock concrete experiments you want to run? -Three phases in `doc/roadmap/research-track.md` are research-only -(no Java parent, no immediate user request), but each maps onto a -recognised live research line and each has explicit acceptance -criteria: +The roadmap now contains six phases close to live research lines, +each with concrete acceptance criteria (or, for the Java-port phases, +a clear specification from the Java original). Three are RESEARCH-only +(no Java parent, no immediate user request); three are Java-port +phases whose existence is settled but whose priority is open: -| Phase | What it would add | Closest published line | -|---|---|---| -| **9d.2** | Decorated DCE in non-Euclidean (spherical + hyperbolic) geometries; Penner coordinates as first-class DOF; automatic cone placement for non-Euclidean targets | Decorated DCE in non-Euclidean geometries (2025, *Discrete Comput. Geom.*); optimal cone singularities for Euclidean flattening (2018, *SIGGRAPH*) | -| **9f** | Discrete Laplace–Beltrami on **non-triangular** polygonal meshes (virtual-node / generalised cotangent), making DCE work on quad / Voronoi tessellations without re-triangulation | Polygon Laplacians (2011 *SIGGRAPH* + 2020 *TOG*) | -| **10c + 10c′** | Canonical Delaunay tessellations of decorated hyperbolic surfaces; Koebe polyhedron realisation (KAT) with rigidity-aware Newton | Canonical tessellations of decorated hyperbolic surfaces (2023, *Geom. Dedicata*); rigidity of circle / hyperideal polyhedra (2026, preprint) | +| Phase | Track | What it would add | Closest published line | +|---|---|---|---| +| **9d.2** | RESEARCH | Decorated DCE in non-Euclidean (spherical + hyperbolic) geometries; Penner coordinates as first-class DOF; automatic cone placement for non-Euclidean targets | Decorated DCE in non-Euclidean geometries (2025, *Discrete Comput. Geom.*); optimal cone singularities for Euclidean flattening (2018, *SIGGRAPH*) | +| **9f** | RESEARCH | Discrete Laplace–Beltrami on **non-triangular** polygonal meshes (virtual-node / generalised cotangent), making DCE work on quad / Voronoi tessellations without re-triangulation | Polygon Laplacians (2011 *SIGGRAPH* + 2020 *TOG*) | +| **10c + 10c′** | planned | Canonical Delaunay tessellations of decorated hyperbolic surfaces; Koebe polyhedron realisation (KAT) with rigidity-aware Newton | Canonical tessellations of decorated hyperbolic surfaces (2023, *Geom. Dedicata*); rigidity of circle / hyperideal polyhedra (2026, preprint) | +| **10e** | planned | Quasi-isothermic maps (~800 lines Lawson-correspondence) — generalises conformality to meshes where exact conformality is impossible. Six new classes including a discrete Beltrami-field solver. | Java original `QuasiisothermicUtility` line; no obvious single-paper reference in the existing literature index | +| **10b** | planned | Hyperelliptic surfaces (genus g ≥ 2 with Z₂ symmetry); period matrices with block-diagonal structure; Penner-coordinate variant via `HyperIdealHyperellipticUtility` | Bobenko–Bücking 2009 *Conformal Structures and Period Matrices of Polyhedral Surfaces* | +| **9d.4** | planned | Möbius centring of Poincaré-disk layouts as a *variational* problem (Lorentz energy with full gradient + Hessian), replacing today's iterative Fréchet-mean fallback in `normalise_hyperbolic()` | Java original `MobiusCenteringFunctional`; closest published context: decorated-DCE Möbius normalisation, also used in canonical-tessellation post-processing | **Question A:** which of these (if any) would unblock concrete numerical experiments you have wanted to run but currently have no @@ -42,10 +46,17 @@ reference implementation for? target the *next* milestone after Phase 9c, or is there a different order that would serve your research better? +**Question C:** is there a *seventh* line we are missing — a research +thread close to your own where you would want infrastructure that the +table above does not yet cover? + Context: [`research-track.md`](../roadmap/research-track.md) §"Non-Euclidean -cone extensions" and §"Polygon Laplacian"; the integrated literature -sits in [`math/references.md`](../math/references.md). +cone extensions" and §"Polygon Laplacian"; +[`phases.md`](../roadmap/phases.md) for the per-phase porting plan; +[`java-parity.md`](../roadmap/java-parity.md) for the reverse Java +class table; the integrated literature sits in +[`math/references.md`](../math/references.md). ---