# conformallab++ — Reviewer Preview

A C++17 header-only implementation of discrete conformal equivalence solvers on triangle meshes, built around CGAL's `Surface_mesh` and Eigen. v0.9.0 ships five DCE solvers (Euclidean / Spherical / HyperIdeal / CP-Euclidean / Inversive-Distance) plus the layout, holonomy, period-matrix, cut-graph and serialisation infrastructure.

Audience. Active researcher in discrete differential geometry — specifically the decorated DCE / Penner coordinates / canonical Delaunay tessellations / hyperideal polyhedra line — treated as a peer most likely to use conformallab++ as numerical infrastructure for their own future experiments, not merely to evaluate it.

This page is a temporary preview combining two unmerged PRs so the integrated state is reviewable before any merge happens. Once the PRs land on `main`, the publish URL serves the `main`-branch view.

## TL;DR — orient yourself #

Headline. 259/259 tests pass (0 skipped); 100 % Doxygen coverage on the public API; 14 of 15 quality gates green (1 SKIP — local CGAL-version-matrix has no tarballs); library is verified-standalone (Eigen + CGAL + Boost, all header-only, no runtime deps).

Pick a time budget; each path is a sequence of anchor links.

### ⏱ 5 minutes — minimum to know what's here

- §1 Research alignments (10-row table)
- §3 What's new (delta since last publish)
- → Doxygen HTML index

### 📖 20 minutes — to prepare for the meeting

- 5-min path above, plus:
- §2 Seven questions at a glance
- briefing.md (1 page)
- questions.md (the full text of Q1–Q7)
- §4 How to actually use this

### 🔬 60+ minutes — deep dive

- 20-min path above, plus:
- roadmap/phases.md (full per-phase plan)
- hyperideal-hessian-derivation.md (805-line Schläfli derivation)
- locked-vs-flexible.md (12 architecture decisions to push back on)
- §6 Quality + test proof points

## 1. Research alignments — where this could be infrastructure for your work #

Most rows match an active publication line in discrete differential geometry. Rows marked no Java parent are research-only phases the reader can shape at design stage. The Phase column links to the per-phase entry in `doc/roadmap/`.

Reader's research thread | What this snapshot has | Phase
--- | --- | ---
Decorated DCE in non-Euclidean geometries | five DCE solvers + traits scaffolding; non-Euclidean cone extension scoped in research-track with acceptance criteria | 9d.2 RESEARCH
Canonical Delaunay tessellations of decorated hyperbolic surfaces | cut-graph + period matrix + hyperbolic-disk layout as scaffolding; canonical-tessellation algorithm itself outlined | 10c planned
Hyperideal polyhedra rigidity | HyperIdeal functional + 805-line analytic Hessian derivation note (Schläfli identity) | 9b-analytic derived; 10c′ KAT planned
Optimal cone placement / non-Euclidean cone metrics | cone-singularity port via `ConesUtility` scoped; non-Euclidean extension is the research delta | 9d.1 port + 9d.2 RESEARCH
Polygon Laplacian on general (non-triangular) meshes | no Java parent — first phase the reader can influence at design stage | 9f RESEARCH
Quasi-isothermic maps (Lawson correspondence, ~800 lines, discrete Beltrami-field solver) | scoped as a 6-class Java port: `QuasiisothermicLayout`, `DBFSolution`, `SinConditionApplication`, `QuasiisothermicDelaunay`, `QuasiisothermicUtility`, `ConformalStructureUtility` | 10e planned
Higher-genus + hyperelliptic surfaces (Bobenko–Mercat–Schmies 2011 / Bobenko–Bücking 2021 period matrices; block-diagonal Z₂ symmetry) | port of `HyperellipticUtility` + `HyperIdealHyperellipticUtility` scoped; existing period-matrix code as scaffolding | 10b planned
Möbius centring as a variational problem (Lorentz energy, full gradient + Hessian) | currently iterative Fréchet mean in `normalise_hyperbolic()`; the principled variational alternative is scoped via the Java `MobiusCenteringFunctional` port | 9d.4 planned
Boundary-First / interactive flattening (Sawhney–Crane 2017 BFF; Knöppel–Crane–Pinkall–Schröder 2015 Stripe Patterns) | not on the roadmap as ports; documented in `references.md` as comparison points / inspiration | —
Schläfli-based variational machinery (Rivin–Schlenker 1999) | derivation done; implementation gated on the reader's view of whether the ~6× speedup over our block-FD path matters at their mesh sizes | 9b-analytic ready

## 2. Seven questions at a glance #

The full text of each question lives in questions.md. The first two are research-oriented and benefit most from this specific reader; the rest are scoped so "A / B / either" is a sufficient answer.

Q | Topic | Track
--- | --- | ---
Q1 | Research-track alignment — which of 6 candidate phases (9d.2 / 9f / 10c+10c′ / 10e / 10b / 9d.4) would unblock concrete experiments you want to run? | research
Q2 | Decorated-DCE API surface — named parameter, separate `decorated_*` solvers, or property-map auto-detect? | research
Q3 | Phase 9b-analytic Hessian — is the ~6× speedup worth ~2 weeks at your mesh sizes? | porting
Q4 | Phase 9c (4g-polygon canonical form) — port literally or re-derive from Springborn 2020 §5? | porting
Q5 | geometry-central cross-validation (GC-1) — would you co-author? | collaboration
Q6 | CGAL submission packaging — one package or several? | process
Q7 | The "no" question — is there one of the 12 architecture decisions you would push back on? | process

## 3. What's new on this snapshot #

Since the previous publish, four threads converged:

- +6 phases from a full Java-library scan (9d cones + 9d.4 variational Möbius centring / 9e circle-pattern layout / 10d Koebe circle-domain / 10e quasi-isothermic / 10f Koebe polyhedra / 10g cyclic-symmetry). See java-parity.md for the reverse table.
- +13 literature citations integrated into the per-phase roadmap with explicit acceptance criteria. 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: Soliman–Slepčev–Crane 2018; Pinkall–Springborn 2021 (discrete Liouville); Bobenko–Mercat–Schmies 2011 / Bobenko–Bücking 2021; Rivin–Schlenker 1999. Polygon Laplacians: Alexa–Wardetzky 2011; Bunge et al. 2020. Integrable and practical-flattening context: Born–Bücking–Springborn 2015; Sawhney–Crane 2017 (BFF); Knöppel et al. 2015 (Stripe Patterns).
- +1 RESEARCH phase with no Java parent — Phase 9f (polygon Laplacian on non-triangular meshes, Alexa-Wardetzky 2011 / Bunge et al. 2020) — the first phase a reviewer can shape at design stage.
- output_uv_map now covers 4 of 5 DCE solvers (Inversive-Distance added; CP-Euclidean deferred to Phase 9c with a clear runtime error).

## 4. How you'd actually use this #

The library is header-only and standalone. Two-minute build + smoke test:

    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 solvers + layouts (adds Boost headers as 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

One-call entry to compute a Euclidean discrete conformal map and a UV-layout in a single shot:

    #include <CGAL/Surface_mesh.h>
    #include <CGAL/Discrete_conformal_map.h>

    CGAL::Surface_mesh<K::Point_3> mesh = ...;        // your mesh
    auto uv = mesh.add_property_map<V_idx, K::Point_2>("uv").first;

    auto r = CGAL::discrete_conformal_map_euclidean(
        mesh,
        CGAL::parameters::output_uv_map(uv)
                       | CGAL::parameters::gradient_tolerance(1e-12));
    // r.u_per_vertex, r.iterations, r.gradient_norm now populated.

For adding your own functional or layout — pointer chain

- add-inversive-distance.md — step-by-step recipe for a sixth DCE model, used in real for the existing 9a.2 port.
- block-fd-hessian.md — per-face block-FD pattern (96× over full-FD).
- add-output-uv-map.md — `output_uv_map` named parameter + pipe-operator chaining.
- For your decorated-DCE work specifically: see Q2 of the reviewer questions — three candidate API shapes, picking one would let us sketch a prototype in the week after the meeting.

## 5. Documents to read next #

The four document folders most useful to a researcher. Click each folder for the per-document table.

📋 Meeting materials — `doc/reviewer/` (read first)

Document | What it covers
--- | ---
`briefing.md` | One-page orientation: research alignments (10-row table), what's new on this snapshot, the seven questions.
`questions.md` | Full text of Q1–Q7. Q1 lists 6 candidate phases (9d.2 / 9f / 10c+10c′ / 10e / 10b / 9d.4); Q2 covers the decorated-DCE API surface; Q3–Q4 are porting decisions; Q5–Q6 project management; Q7 the open invitation to push back.

🗺️ Roadmap — `doc/roadmap/` (where everything fits)

Document | What it covers
--- | ---
`phases.md` +6 phases | Per-phase plan including the 6 new Java-scan phases (9d / 9e / 10d / 10e / 10f / 10g + 9d.4) and the 3 new research-only entries (9d.2 / 9f / 10c′).
`research-track.md` +2 RESEARCH | Items beyond Java parity, with explicit acceptance criteria: non-Euclidean cone extensions (9d.2), polygon Laplacian on non-triangular meshes (9f), geometry-central cross-validation (GC-1).
`java-parity.md` full scan | Reverse table: every class in the Java original, where it lives in our port (or which phase will absorb it), or why it is intentionally not ported (the do-not-port list — Colt, PETSc, jReality wrappers).
`porting-status.md` | Operational snapshot: 25 kLoC Java breakdown, 5-DCE-model status matrix, things Java doesn't have.

📚 Mathematics & literature — `doc/math/`

Document | What it covers
--- | ---

`references.md` +13 refs

Per-phase literature index. 13 new citations added: decorated DCE in non-Euclidean geometries (Bobenko–Lutz 2025); canonical tessellations (Lutz 2023 / 2024); hyperideal polyhedra rigidity (Bowers–Bowers–Lutz 2026); polygon Laplacians (Alexa–Wardetzky 2011 / Bunge et al. 2020); optimal cone placement (Soliman–Slepčev–Crane 2018); Schläfli identity (Rivin–Schlenker 1999); discrete Liouville theorem (Pinkall–Springborn 2021); polyhedral period matrices (Bobenko–Mercat–Schmies 2011 / Bobenko–Bücking 2021); quasiconformal distortion (Born–Bücking–Springborn 2015); BFF (Sawhney–Crane 2017); stripe patterns (Knöppel–Crane–Pinkall–Schröder 2015).

`hyperideal-hessian-derivation.md` | Full LaTeX-formatted derivation of the analytic HyperIdeal Hessian via the Schläfli identity (805 lines, 8 sections + 2 appendices). Cited sources: Schläfli 1858, Milnor 1982, Vinberg 1993, Cho–Kim 1999, Glickenstein 2011, Rivin–Schlenker 1999, Springborn 2020.

🏗️ Architecture, dependencies & auto-generated reference

Document | What it covers
--- | ---
`locked-vs-flexible.md` | 12 architecture decisions classified 🔴 load-bearing / 🟡 semi-fixed / 🟢 opportunistic + a "Known limitations" table. Q7 of the reviewer questions points here to push back on anything.
`dependencies.md` | What's required (Eigen + CGAL + Boost headers) vs optional; per-tool install hints; standalone-verification recipe.
`code/deps/THIRD-PARTY-LICENSES.md` | Per-vendored-dep SPDX with MIT-compatibility analysis (LGPL §3 vs §4 distinction for header-only consumption of CGAL).
Doxygen HTML | 259 pages, 0 warnings, 100 % public-API coverage (396 / 396 symbols). MathJax enabled for inline formulas.
`api/headers.md` | Auto-generated table of every public header with brief + symbols; regenerated on every push to main.
`api/tests.md` | Per-suite test breakdown (single source of truth). 259 tests, 0 skipped.

## 6. Quality & tests — proof points #

Suite | Tests | Status
--- | --- | ---
Non-CGAL (pure-math) | 23 | PASS 0 skipped
CGAL (Surface_mesh + Phase 8b-Lite) | 236 | PASS 0 skipped
Total | 259 | 0 failures

Quality gates — 14 of 15 PASS, 1 SKIP (full breakdown)

Run with `bash scripts/quality/run-all.sh`. Four ★ gates are required in CI on every PR; the rest are local-only and skip gracefully on a partial dev environment.

Gate | Where | Result | Detail
--- | --- | --- | ---
License headers ★ | CI | PASS | 66/66 files carry MIT SPDX
CGAL conventions (6 rules) ★ | CI | PASS | 0/6 violations across 6 CGAL public headers
codespell ★ | CI | PASS | 0 typos
shellcheck ★ (strict) | CI | PASS | 0 findings across 16 shell scripts
clang-format drift | local | PASS | 0 drift against `.clang-format`
cmake-format / cmake-lint | local | PASS | 0 drift, 0 lint findings
cppcheck | local | PASS | warning+ severity clean
Markdown links | CI | PASS | internal links resolve
Sanitizers (ASan + UBSan) | local | PASS | 23/23 tests pass under instrumentation
clang-tidy | local | PASS | 35 headers, 0 findings
Coverage (gcov + lcov) | local | DEGRADED | 23/23 tests run instrumented; lcov-on-macOS toolchain mismatch (works on Linux CI)
Multi-compiler | local | PASS | AppleClang 17 + brew LLVM 22
Reproducible build | local | PASS | byte-identical test binaries between 2 builds
Doxygen coverage | CI | PASS | 396 / 396 public symbols (100 %)
CGAL version matrix | local | SKIP | no CGAL tarballs under `~/cgal/` (graceful)
test-count consistency ★ | CI | PASS | `tests.md` totals match ctest reality
End-to-end smoke (try_it.sh) ★ | CI | PASS | full configure + build + ctest + Euclidean example on a bundled mesh

## 7. Source & navigation #

Repo (this snapshot) | codeberg.org/TMoussa/ConformalLabpp/branch/main
Default branch | codeberg.org/TMoussa/ConformalLabpp (main)
Doxygen HTML | 259 pages, 0 warnings, 100 % coverage
Origin (private) | `git.eulernest.eu/conformallab/ConformalLabpp`