feat: output_uv_map for InversiveDistance, error for CP-Euclidean, reviewer trio
Three reviewer-meeting deliverables in one commit.
(1) output_uv_map for the two remaining DCE entries
─────────────────────────────────────────────────
* Discrete_inversive_distance.h: full implementation. After Newton,
reconstruct effective Euclidean edge lengths from the converged
log-radii via the Bowers-Stephenson identity
`ℓᵢⱼ² = rᵢ² + rⱼ² + 2·Iᵢⱼ·rᵢ·rⱼ`, populate a temporary
EuclideanMaps with `lambda0 = log(ℓᵢⱼ²)`, and reuse the existing
`euclidean_layout(mesh, 0, eucl)` priority-BFS. Per-vertex
Point_2 coordinates written into the user-supplied pmap.
Optional `normalise_layout(true)` applies the canonical PCA
centroid + major-axis rotation, same as the other 3 entries.
* Discrete_circle_packing.h: throws std::runtime_error with a
clear pointer to Phase 9c rather than silently producing
nonsense. CP-Euclidean is face-based; the faithful output is a
per-face circle packing in ℝ², not a per-vertex Point_2 map.
A true layout requires BPS-2010 §6 (~150 lines, on the porting
roadmap as Phase 9c). Failing loudly is the honest default.
Tests: 2 new cases in test_cgal_phase8b_lite.cpp
(OutputUvMap_InversiveDistance_PopulatesPmap;
OutputUvMap_CPEuclidean_ThrowsClearly). Both green.
Suite total now 259 (was 257, +2). CGAL subtotal: 234 → 236.
(2) Reviewer meeting documents
──────────────────────────
New directory doc/reviewer/ with three files:
* briefing.md — one-page orientation for the reviewer.
What the project is, where to look first
(https://tmoussa.codeberg.page/ConformalLabpp/), the headline
evidence (tests/coverage/sanitizers/license), what we want from
them, what's deferred and why, and the 5 questions in a separate
file.
* questions.md — the 5 concrete decisions we want their second
opinion on:
Q1 Phase 9c (port-literal vs re-derive)
Q2 Phase 9b-analytic (worth ~2 weeks for ~6× speedup?)
Q3 CP-Euclidean output_uv_map (build now or defer?)
Q4 CGAL submission strategy (one package or five?)
Q5 geometry-central cross-validation co-authorship
Plus an explicit "what would you say no to?" question at the
bottom — negative feedback is the highest-value information.
* agenda.md — my own internal playbook (NOT to be sent).
60-min flow: 5-min thank-you, 10-min architecture tour,
30-min for Q1-Q5 in the order Q4-Q1-Q2-Q5-Q3, 5-min "no"
question, 5-min wrap-up. Includes post-meeting memo template
to fill out in the 30 min after.
* README.md — index for the directory; says which file goes
to whom and when to send.
(3) locked-vs-flexible.md known-limitations update
─────────────────────────────────────────────
"output_uv_map covers 3 of 5 entries" → "covers 4 of 5".
CP-Euclidean's throws-clearly behaviour documented as a Phase 9c
deliverable rather than a passive gap.
Bonus: extended .codespellrc ignore list (acknowledgement, the
British-English spelling I used in agenda.md).
Verifications on this commit:
259/259 tests pass (0 skipped)
scripts/check-test-counts.sh: OK (23 + 236 = 259)
scripts/quality/license-headers.sh: OK (66/66 SPDX)
python3 scripts/quality/cgal-conventions.py: OK (0/6 violations)
scripts/quality/codespell.sh: OK (0 typos)
scripts/quality/shellcheck.sh: OK (0 findings)
python3 scripts/check-markdown-links.py: OK (143/143)
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Tarik Moussa
committed by
Tarik Moussa
Tarik Moussa
parent
32253a8f5e
commit
f25174ed69
@@ -64,9 +64,9 @@ All tests have CTest prefix `cgal.` (set via `TEST_PREFIX "cgal."` in CMakeLists
|
||||
| `InversiveDistanceFunctional` | `test_inversive_distance_functional.cpp` | 11 | Phase 9a.2 — Luo-2004 vertex-based packing (from literature) |
|
||||
| `HyperIdealHessian` | `test_hyper_ideal_hessian.cpp` | 7 | Phase 9b — block-FD vs full-FD cross-validation + PSD + speed-up |
|
||||
| `NewtonPhase9a` | `test_newton_phase9a.cpp` | 7 | Phase 9a-Newton — convergence for the two new circle-packing solvers |
|
||||
| `CGALPhase8bLite` | `test_cgal_phase8b_lite.cpp` | 15 | Phase 8b-Lite — CGAL entries for all 5 DCE models + `output_uv_map` + pipe-operator chaining |
|
||||
| `CGALPhase8bLite` | `test_cgal_phase8b_lite.cpp` | 17 | Phase 8b-Lite — CGAL entries for all 5 DCE models + `output_uv_map` (Euclidean, Spherical, HyperIdeal, Inversive-Distance) + CP-Euclidean throws-clearly + pipe-operator chaining |
|
||||
|
||||
**Total: 234 tests, 0 skipped.**
|
||||
**Total: 236 tests, 0 skipped.**
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -258,7 +258,7 @@ mechanical next step rather than a missing piece of theory.
|
||||
|
||||
| Limitation | Status | Effort to close |
|
||||
|---|---|---|
|
||||
| **`output_uv_map` covers 3 of 5 entries** — Euclidean, Spherical, HyperIdeal are wired to call the appropriate `*_layout()` after Newton. CP-Euclidean (face-based) and Inversive-Distance (vertex-based) entries still require the user to call `*_layout()` by hand. | tutorial + plumbing in place; just needs to be copy-pasted into the two remaining entry headers | ~0.5 day |
|
||||
| **`output_uv_map` covers 4 of 5 entries** — Euclidean, Spherical, HyperIdeal, **and Inversive-Distance** (new on the structural-tests branch) are wired to call the appropriate `*_layout()` after Newton. CP-Euclidean is face-based: the faithful output is a per-face circle packing, not a per-vertex `Point_2`, so the entry deliberately throws `std::runtime_error` with a helpful message rather than silently producing nonsense. Implementing a true CP-Euclidean circle-packing layout (BPS-2010 §6, ~150 lines) is tracked as Phase 9c. | Inversive-Distance via Bowers-Stephenson edge-length reconstruction + euclidean_layout reuse; CP-Euclidean deferred to Phase 9c | ID closed; CP-Euclidean ~3 days (genuinely new algorithm, not just plumbing) |
|
||||
| **Named-parameter chaining: `\|`-operator only, no `.a().b().c()`.** Member-style chaining would need a patch to CGAL's upstream `parameters_interface.h`, which we treat as a read-only vendored dependency. The pipe operator is documented, ADL-discoverable, and equivalent in expressive power. | pipe shipped, member-chain deferred until upstream extension point exists | ~2 days (only if upstream PR is accepted) |
|
||||
| **Phase 9b-analytic: derivation complete, code uses block-FD.** The Schläfli-based analytic HyperIdeal Hessian is fully derived in [`hyperideal-hessian-derivation.md`](../math/hyperideal-hessian-derivation.md) (805 lines, all sign pitfalls covered). The shipped code still uses per-face block-FD (already 96× faster than the legacy full-FD path). | research-ready writeup; implementation gated on the reviewer's view of whether the additional ~6× is worth it | ~2 weeks |
|
||||
| **Doxygen `WARN_IF_UNDOCUMENTED = NO`.** With `EXTRACT_ALL = YES`, every symbol is in the generated HTML — live at <https://tmoussa.codeberg.page/ConformalLabpp/> (auto-published from `main` by `.gitea/workflows/doxygen-pages.yml`) — but symbols without explicit doc comments show only their signature. Public API surface (entry functions, named-parameter helpers, traits typedefs) has hand-written Doxygen; internal helpers vary. | clean (0 warnings) under current policy; not yet enforced "no undocumented symbol"; pursued on a separate branch | ~3 days to drive `WARN_IF_UNDOCUMENTED = YES` to zero |
|
||||
|
||||
28
doc/reviewer/README.md
Normal file
28
doc/reviewer/README.md
Normal file
@@ -0,0 +1,28 @@
|
||||
# Reviewer meeting materials
|
||||
|
||||
A single landing page for the three documents associated with the
|
||||
external-reviewer meeting (Springborn/Bobenko alumnus, May 2026).
|
||||
|
||||
| Document | Audience | Purpose |
|
||||
|---|---|---|
|
||||
| [`briefing.md`](briefing.md) | **the reviewer** | one-page orientation: what the project is, where to look first, what we want from them |
|
||||
| [`questions.md`](questions.md) | **the reviewer** | the 5 concrete decisions we want their opinion on (skim before the meeting) |
|
||||
| [`agenda.md`](agenda.md) | **me** | my own meeting playbook: timing, order, the "no" question, post-meeting memo template |
|
||||
|
||||
After the meeting, a fourth file `2026-XX-XX-meeting-notes.md` should
|
||||
land here too — the memo template at the bottom of `agenda.md` is the
|
||||
suggested structure.
|
||||
|
||||
## When to send to the reviewer
|
||||
|
||||
- **briefing.md** + **questions.md**: as part of the meeting-confirmation
|
||||
email, ~5 business days before the meeting. Subject line: *"Pre-read
|
||||
for our conformallab++ chat (~15 min)"*.
|
||||
- **agenda.md**: never send. This is internal scaffolding.
|
||||
|
||||
## Quick links the reviewer should bookmark
|
||||
|
||||
- 🌐 Reviewer-hub landing page: <https://tmoussa.codeberg.page/ConformalLabpp/>
|
||||
- 📦 Source: <https://codeberg.org/TMoussa/ConformalLabpp>
|
||||
- 📝 Architecture decisions: [`../architecture/locked-vs-flexible.md`](../architecture/locked-vs-flexible.md)
|
||||
- 📐 Schläfli derivation (for Q2): [`../math/hyperideal-hessian-derivation.md`](../math/hyperideal-hessian-derivation.md)
|
||||
114
doc/reviewer/agenda.md
Normal file
114
doc/reviewer/agenda.md
Normal file
@@ -0,0 +1,114 @@
|
||||
# Reviewer meeting — agenda (for me)
|
||||
|
||||
> **Audience.** Myself, before the meeting. Not shared with the
|
||||
> reviewer (they have [`briefing.md`](briefing.md) and
|
||||
> [`questions.md`](questions.md) instead).
|
||||
>
|
||||
> **Purpose.** Keep the conversation on the high-stakes items
|
||||
> without slipping into detail-tour mode.
|
||||
|
||||
**Length:** ~60 min (default; willing to extend if conversation is
|
||||
productive).
|
||||
|
||||
## Opening — 5 min
|
||||
|
||||
- **Thank-you** + ~30 s on why I value their time specifically
|
||||
(Springborn/Bobenko background = best-positioned audience for
|
||||
this material).
|
||||
- **Confirm format**: they've read `briefing.md`? Yes → skip ahead.
|
||||
No → take 3 min to walk through it together via the reviewer-hub
|
||||
URL.
|
||||
|
||||
## §1 Architectural tour — 10 min
|
||||
|
||||
Goal: they leave §1 with a mental map of what's where.
|
||||
|
||||
1. Open <https://tmoussa.codeberg.page/ConformalLabpp/>.
|
||||
2. Click through:
|
||||
- Doxygen → `discrete_conformal_map_euclidean` (the canonical entry,
|
||||
shows the named-parameter pattern + traits).
|
||||
- `locked-vs-flexible.md` § Summary table.
|
||||
- `dependencies.md` § TL;DR.
|
||||
3. **Don't** demo running the test suite live unless they ask —
|
||||
they can verify the green badges later.
|
||||
|
||||
**Cue to move on**: when they have no more "where is X?" questions.
|
||||
|
||||
## §2 The five questions — 30 min
|
||||
|
||||
Goal: get clear answers to as many of the 5 questions in
|
||||
[`questions.md`](questions.md) as possible. Order matters:
|
||||
|
||||
1. **Q4 first** (CGAL submission strategy — single package vs five).
|
||||
This sets the framing for the rest. ~5 min.
|
||||
2. **Q1** (Phase 9c port-literal vs re-derive). ~5 min.
|
||||
3. **Q2** (Phase 9b-analytic — is the 6× speedup worth ~2 weeks?).
|
||||
May trigger longer math discussion; cap at 10 min and offer to
|
||||
continue async.
|
||||
4. **Q5** (GC-1 cross-validation co-authorship). ~5 min.
|
||||
5. **Q3** (CP-Euclidean output_uv_map). ~5 min.
|
||||
|
||||
**Trap to avoid**: don't relitigate any of the already-made decisions
|
||||
(e.g. Surface_mesh as default, Eigen as backend) unless they bring it
|
||||
up under "anything you'd say no to". Move forward, not sideways.
|
||||
|
||||
## §3 The "no" question — 5 min
|
||||
|
||||
Last paragraph of [`questions.md`](questions.md): *"Is there one
|
||||
architecture decision where you think 'no, that's the wrong call'?"*
|
||||
|
||||
Ask explicitly. Wait. Don't fill silence. Negative feedback at this
|
||||
phase is the highest-value information of the entire meeting.
|
||||
|
||||
## §4 Wrap-up — 5 min
|
||||
|
||||
- **Summarise**: 1 sentence per Q1–Q5 answer.
|
||||
- **Next steps**:
|
||||
- Items they offered to help on (if any) → I'll send a follow-up
|
||||
email within 48 h.
|
||||
- Items they flagged as worth changing → I'll write a one-page
|
||||
plan + send for sign-off before starting work.
|
||||
- **Cadence**: do they want a periodic update? Once-a-quarter? When
|
||||
hitting Phase 9c milestone?
|
||||
- **Citation**: ask whether they want acknowledgement in the
|
||||
CGAL submission's `THANKS.md`.
|
||||
|
||||
## Material I have ready (in tabs)
|
||||
|
||||
1. <https://tmoussa.codeberg.page/ConformalLabpp/>
|
||||
2. <https://codeberg.org/TMoussa/ConformalLabpp> (source)
|
||||
3. Local terminal in the repo (for any "show me X" requests)
|
||||
4. `doc/math/hyperideal-hessian-derivation.md` open in editor
|
||||
(for Q2)
|
||||
5. `doc/architecture/locked-vs-flexible.md` open at "Summary table"
|
||||
6. This file, [`questions.md`](questions.md), and
|
||||
[`briefing.md`](briefing.md) for backstop.
|
||||
|
||||
## After the meeting
|
||||
|
||||
- 30-min decompression — don't take notes during the meeting beyond
|
||||
bullet-tracking of Q1–Q5 answers; write up a full memo in the 30 min
|
||||
AFTER.
|
||||
- Memo template:
|
||||
```
|
||||
Date: ____
|
||||
Reviewer: ____
|
||||
Duration: ____ min
|
||||
|
||||
Q1 answer: ____
|
||||
Q2 answer: ____
|
||||
Q3 answer: ____
|
||||
Q4 answer: ____
|
||||
Q5 answer: ____
|
||||
"No" pointer: ____
|
||||
|
||||
Action items:
|
||||
[ ] (within 48 h) ____
|
||||
[ ] (within 2 wks) ____
|
||||
[ ] (longer term) ____
|
||||
|
||||
Cadence agreed: ____
|
||||
```
|
||||
|
||||
- Store the memo at `doc/reviewer/2026-XX-XX-meeting-notes.md`
|
||||
(gitignored if confidential, otherwise committed).
|
||||
112
doc/reviewer/briefing.md
Normal file
112
doc/reviewer/briefing.md
Normal file
@@ -0,0 +1,112 @@
|
||||
# Reviewer briefing — conformallab++
|
||||
|
||||
> **Audience.** External reviewer with a discrete-conformal-geometry
|
||||
> background (Springborn / Bobenko alumnus, ~30 minutes lead-time
|
||||
> before the meeting).
|
||||
>
|
||||
> **Purpose of this document.** A single page they can read once
|
||||
> before the meeting and feel oriented — what the project is, what
|
||||
> we want from them, and where to look first.
|
||||
|
||||
## In one paragraph
|
||||
|
||||
`conformallab++` is a C++17 header-only re-implementation of the Java
|
||||
library [`ConformalLab`](https://github.com/varylab/conformallab)
|
||||
(Sechelmann 2016, TU Berlin), built around CGAL's `Surface_mesh` and
|
||||
Eigen. v0.9.0 ships five Discrete Conformal Equivalence (DCE) solvers
|
||||
— Euclidean, Spherical, HyperIdeal, Circle-Packing Euclidean
|
||||
(BPS 2010, face-based), Inversive-Distance (Luo 2004, vertex-based) —
|
||||
plus the Newton infrastructure, layout (priority-BFS trilateration in
|
||||
ℝ², S², Poincaré disk), Möbius holonomy, period matrix, cut graph, and
|
||||
JSON/XML serialisation. Long-term goal: a CGAL package.
|
||||
|
||||
## Where to start (one URL, 5 minutes)
|
||||
|
||||
**👉 https://tmoussa.codeberg.page/ConformalLabpp/**
|
||||
|
||||
The landing page is a hand-curated reviewer hub, not an auto-generated
|
||||
index. It links to the Doxygen API, the key markdown documents, and
|
||||
shows static quality-gate status.
|
||||
|
||||
## What's true about this snapshot
|
||||
|
||||
| Claim | Concrete evidence |
|
||||
|---|---|
|
||||
| **Library is header-only and standalone** | Verification recipe in `doc/architecture/dependencies.md`: `env -i PATH=… cmake … && ctest` passes with zero quality tools installed. |
|
||||
| **Tests: 259 pass, 0 skipped** | `bash scripts/check-test-counts.sh` enforces this against `doc/api/tests.md`; CI fails on drift. |
|
||||
| **Doxygen: 100 % public-API coverage, 0 warnings** | `bash scripts/doxygen-coverage.sh --threshold 100` is in CI. |
|
||||
| **License hygiene: 66/66 files carry MIT SPDX** | `bash scripts/quality/license-headers.sh` is in CI (strict). |
|
||||
| **Build reproducibility: byte-identical between runs** | `bash scripts/quality/reproducible-build.sh` (local, ~6 min). |
|
||||
| **Sanitizers (ASan + UBSan) clean on fast suite** | `bash scripts/quality/sanitizers.sh` (local, ~3 min). |
|
||||
| **CGAL conventions: 6 rules, 0 violations** | `python3 scripts/quality/cgal-conventions.py` (CI required). |
|
||||
|
||||
## What we want from you
|
||||
|
||||
Five concrete questions are in
|
||||
[`doc/reviewer/questions.md`](questions.md) — please skim them
|
||||
beforehand. They are deliberately scoped: each can be answered with
|
||||
"go this way" / "no, go that way" / "either is fine".
|
||||
|
||||
The high-stakes ones:
|
||||
|
||||
1. **Phase 9c (4g-polygon)** — port the Java implementation literally,
|
||||
or re-derive from Springborn 2020 §5?
|
||||
2. **Phase 9b-analytic** — is the ~6× speedup over our current block-FD
|
||||
Hessian (full Schläfli-based analytic) worth ~2 weeks? Working-mesh
|
||||
size that justifies it?
|
||||
3. **CGAL submission strategy** — submit as a single package or split
|
||||
the five DCE solvers into separate packages?
|
||||
|
||||
## What's deliberately deferred (so we can discuss with you first)
|
||||
|
||||
| Item | Why deferred |
|
||||
|---|---|
|
||||
| Phase 9b-analytic (Schläfli-based HyperIdeal Hessian) | derivation done (805-line LaTeX doc), implementation depends on your opinion of payoff |
|
||||
| Phase 9c (fundamental-polygon utility, 4g-polygon canonical form) | algorithm choice up to you |
|
||||
| Cross-validation against geometry-central (GC-1) | potential paper, scope depends on your interest |
|
||||
| CP-Euclidean `output_uv_map` (per-face circle packing) | needs the BPS-2010 §6 layout algorithm, ~3 days |
|
||||
| `.a().b().c()` member-style named-parameter chaining | requires patching CGAL upstream; pipe-operator (`a | b | c`) shipped instead |
|
||||
|
||||
These are all flagged in
|
||||
[`doc/architecture/locked-vs-flexible.md`](../architecture/locked-vs-flexible.md)
|
||||
§"Known limitations".
|
||||
|
||||
## Architectural decisions you might want to challenge
|
||||
|
||||
12 decisions classified 🔴 load-bearing / 🟡 semi-fixed / 🟢 opportunistic
|
||||
in [`doc/architecture/locked-vs-flexible.md`](../architecture/locked-vs-flexible.md).
|
||||
The ones most worth your time:
|
||||
|
||||
- **#1 Surface_mesh as default** — 🔴 ~3 weeks to change. Are you OK
|
||||
with this default, or should we wire Polyhedron_3 / OpenMesh now?
|
||||
- **#6 Eigen as linear-algebra back-end** — 🔴 ~2 weeks to change. Are
|
||||
the Eigen sparse solvers (SparseCholesky + SparseQR fallback)
|
||||
sufficient for the mesh sizes you've seen, or should we look at
|
||||
CHOLMOD / PETSc?
|
||||
- **#7 Strategy C** (one Default trait per functional, not a unified
|
||||
trait) — 🟡 ~1 week to refactor. CGAL convention agrees; do you?
|
||||
|
||||
## How to actually run something
|
||||
|
||||
```bash
|
||||
git clone https://codeberg.org/TMoussa/ConformalLabpp && cd ConformalLabpp
|
||||
cmake -S code -B build && cmake --build build --target conformallab_tests
|
||||
ctest --test-dir build # ~2 s, 23 pure-math tests
|
||||
# CGAL tests (adds Boost as a system dep):
|
||||
cmake -S code -B build -DWITH_CGAL_TESTS=ON
|
||||
cmake --build build --target conformallab_cgal_tests -j
|
||||
ctest --test-dir build # ~3 min, 236 CGAL tests
|
||||
```
|
||||
|
||||
A more end-to-end recipe lives in `scripts/try_it.sh` (also run in CI).
|
||||
|
||||
## Meeting logistics
|
||||
|
||||
- **Format**: video call (you suggested), ~60 min
|
||||
- **Materials needed on your side**: just a browser to follow the
|
||||
reviewer-hub URL.
|
||||
- **Materials I'll have ready**: a screen-share-able terminal with
|
||||
the repo open, my own agenda in `doc/reviewer/agenda.md`, and the
|
||||
questions doc above.
|
||||
|
||||
Looking forward.
|
||||
153
doc/reviewer/questions.md
Normal file
153
doc/reviewer/questions.md
Normal file
@@ -0,0 +1,153 @@
|
||||
# Questions for the external reviewer
|
||||
|
||||
> Please skim this before the meeting. Each question is scoped so that
|
||||
> "do A" / "do B" / "either is fine" is a sufficient answer; deeper
|
||||
> dives are welcome but not required.
|
||||
|
||||
These are the five decisions that would benefit most from a second
|
||||
opinion. Items 1-3 affect the porting roadmap directly; 4-5 affect
|
||||
the long-term goal (CGAL submission).
|
||||
|
||||
---
|
||||
|
||||
## Q1 — Phase 9c (4g-polygon canonical form): port-literal vs re-derive?
|
||||
|
||||
The Java original has two utility classes:
|
||||
|
||||
- `FundamentalPolygonUtility` (~600 lines)
|
||||
- `CanonicalFormUtility` (~900 lines)
|
||||
|
||||
that together compute the canonical 4g-polygon for a higher-genus
|
||||
surface from its cut graph.
|
||||
|
||||
We can either:
|
||||
|
||||
- **(A) Port literally** (~2 weeks). Faithful, predictable, fixes
|
||||
the Java algorithm in C++. Down-side: we inherit the Java code's
|
||||
ad-hoc style and edge-case handling.
|
||||
- **(B) Re-derive from Springborn 2020 §5** (~3 weeks). Uses our
|
||||
existing `cut_graph.hpp` + holonomy infrastructure cleanly.
|
||||
Down-side: longer; potential for new bugs not seen by the Java
|
||||
original's test cases.
|
||||
|
||||
**Question**: which route do you prefer, and is there a Springborn-era
|
||||
reference implementation (Mathematica notebook, paper appendix) we
|
||||
should cross-validate against?
|
||||
|
||||
Context: `doc/roadmap/phases.md` §Phase 9c, `doc/roadmap/porting-status.md`.
|
||||
|
||||
---
|
||||
|
||||
## Q2 — Phase 9b-analytic Hessian: implement now or later?
|
||||
|
||||
We have:
|
||||
|
||||
- **Done**: per-face block-FD Hessian (96× faster than naive full-FD).
|
||||
- **Derived but not implemented**: analytic Hessian via the Schläfli
|
||||
identity, expected ~6× further speedup over block-FD.
|
||||
- **Derivation document**:
|
||||
[`doc/math/hyperideal-hessian-derivation.md`](../math/hyperideal-hessian-derivation.md)
|
||||
(805 lines, all sign pitfalls covered, references Schläfli 1858,
|
||||
Milnor 1982, Vinberg 1993, Cho-Kim 1999, Glickenstein 2011,
|
||||
Springborn 2020).
|
||||
|
||||
**Question**:
|
||||
|
||||
- At what mesh size does the ~6× become user-visible enough to
|
||||
justify ~2 weeks of implementation work?
|
||||
- Are you aware of subtleties in the Schläfli-based derivation our
|
||||
document might be missing?
|
||||
|
||||
If the answer is "implement", we'd target Phase 9b-analytic right
|
||||
after the meeting.
|
||||
|
||||
---
|
||||
|
||||
## Q3 — `output_uv_map` for CP-Euclidean: build now or defer?
|
||||
|
||||
For CP-Euclidean (face-based DOFs, BPS 2010) the natural output is a
|
||||
**per-face circle packing** in ℝ² — not a per-vertex `Point_2` map
|
||||
the way the other four DCE entries produce.
|
||||
|
||||
Today the entry throws `std::runtime_error` with a helpful pointer if
|
||||
the caller passes `output_uv_map(...)`. A faithful layout would be
|
||||
~150 lines implementing BPS-2010 §6.
|
||||
|
||||
**Question**: do *your* CP-Euclidean use cases need a UV-like output,
|
||||
or are the face circle radii themselves the deliverable? The answer
|
||||
shapes whether Phase 9c gets it now or later.
|
||||
|
||||
---
|
||||
|
||||
## Q4 — CGAL submission strategy: one package or five?
|
||||
|
||||
For the long-term CGAL submission:
|
||||
|
||||
- **(A) One package** "Discrete_conformal_map" — single entry header,
|
||||
five solver functions, one set of named parameters. Easier for
|
||||
users to find; harder to compartmentalise reviews.
|
||||
- **(B) Five packages** "Discrete_*" — each DCE model is its own
|
||||
CGAL package with its own concept + reference manual. More
|
||||
ceremony for users; more familiar review surface for CGAL editors.
|
||||
|
||||
Today the code is structured per-functional (Strategy C — see
|
||||
[`locked-vs-flexible.md`](../architecture/locked-vs-flexible.md) §7).
|
||||
Either submission packaging is achievable from this base.
|
||||
|
||||
**Question**: what's the CGAL editor convention for related-but-distinct
|
||||
algorithms — Polygon_mesh_processing as one example (one package, many
|
||||
algorithms), vs Triangulation_2/Triangulation_3/Periodic_*/Hyperbolic_*
|
||||
as another (multiple packages for related algorithms)?
|
||||
|
||||
---
|
||||
|
||||
## Q5 — geometry-central cross-validation (GC-1)
|
||||
|
||||
Two libraries solve the DCE problem from opposite algorithmic
|
||||
directions:
|
||||
|
||||
- **conformallab++**: Newton on the fixed mesh (no intrinsic flips).
|
||||
- **geometry-central**: Ptolemy flips on an intrinsic triangulation.
|
||||
|
||||
An automated comparison on common meshes would be:
|
||||
|
||||
- A nice paper (the disagreement modes are interesting in their own
|
||||
right).
|
||||
- A confidence-building tool for both libraries (we benefit from
|
||||
catching corner-case bugs, they benefit from cross-validation
|
||||
against a Newton baseline).
|
||||
- ~3 days of plumbing (CMake-fetch geometry-central, write 5 common
|
||||
test meshes, compare `u_per_vertex` to a tolerance).
|
||||
|
||||
**Question**: would you be interested in co-authoring such a comparison
|
||||
note (with us doing the implementation)? Or do you know someone in
|
||||
the Crane group who would?
|
||||
|
||||
---
|
||||
|
||||
## Things you do *not* need to comment on (unless you want)
|
||||
|
||||
- C++ style choices captured in `.clang-format` + `.clang-tidy`.
|
||||
- Test framework choice (GTest).
|
||||
- License (MIT, with vendored deps catalogued in
|
||||
[`code/deps/THIRD-PARTY-LICENSES.md`](../../code/deps/THIRD-PARTY-LICENSES.md)).
|
||||
- Build system (CMake ≥ 3.20, header-only consumer + optional
|
||||
CLI/Viewer).
|
||||
|
||||
These are conscious decisions matched to CGAL conventions and aren't
|
||||
load-bearing in the sense that revisiting them later is cheap.
|
||||
|
||||
---
|
||||
|
||||
## What I'm hoping you'll say "no" to
|
||||
|
||||
This is a deliberately blunt question because positive feedback is
|
||||
nice but negative feedback is rarer and more valuable:
|
||||
|
||||
**Looking at any of the 12 architecture decisions in
|
||||
[`locked-vs-flexible.md`](../architecture/locked-vs-flexible.md), is
|
||||
there one where you think "no, that's the wrong call, here's why"?**
|
||||
|
||||
The 🔴 load-bearing decisions are the most consequential to revisit,
|
||||
because waiting longer makes them more expensive. No is the most
|
||||
useful answer.
|
||||
Reference in New Issue
Block a user