docs(reviewer): baustein D — close Java-scan + lit-integration gaps

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 <noreply@anthropic.com>
This commit is contained in:
Tarik Moussa
2026-05-26 06:18:26 +02:00
committed by Tarik Moussa
parent 9be11eca4e
commit 0c520046fb
2 changed files with 56 additions and 27 deletions

View File

@@ -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** (BowersBowersLutz 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** (AlexaWardetzky 2011; Alexa 2020) | no Java parent; first phase a reviewer can shape at design stage | **9f** RESEARCH (planned) |
| **Polygon Laplacian on general meshes** (AlexaWardetzky 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** (BobenkoBü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** (RivinSpringborn 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 (BobenkoLutz 2024 IMRN;
BobenkoLutz 2025 DCG; Lutz 2023 Geom. Dedicata; Lutz 2024 PhD;
BowersBowersLutz 2026; Crane et al. 2018; AlexaWardetzky 2011;
Alexa 2020; RivinSpringborn 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:
BobenkoLutz 2024 IMRN; BobenkoLutz 2025 *DCG*; Lutz 2023
*Geom. Dedicata*; Lutz 2024 PhD; BowersBowersLutz 2026. Cones,
polyhedra, period matrices: Crane et al. 2018; Springborn 2019
(hyperbolic polyhedra); BobenkoBücking 2009; RivinSpringborn 1999.
Polygon Laplacians: AlexaWardetzky 2011; Alexa 2020. Integrable +
practical-flattening context: SpringbornVeselov 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).

View File

@@ -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 LaplaceBeltrami 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 LaplaceBeltrami 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` | BobenkoBü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).
---