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–Bücking 2009; block-diagonal period matrices with 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 (Crane et al. 2017 BFF; Bonneel et al. 2015 Stripe Patterns) | not on the roadmap as ports; documented in references.md as comparison points / inspiration |
— |
| Schläfli-based variational machinery (Rivin–Springborn 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: Crane et al. 2018; Springborn 2019; Bobenko–Bücking 2009; Rivin–Springborn 1999. Polygon Laplacians: Alexa–Wardetzky 2011; Alexa 2020. Integrable and practical-flattening context: Springborn–Veselov 2015; Crane et al. 2017 (BFF); Bonneel et al. 2015 (Stripe Patterns).
- +1 RESEARCH phase with no Java parent — Phase 9f (polygon Laplacian on non-triangular meshes, Alexa-Wardetzky 2011 / Alexa 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 testsOne-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_mapnamed 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 / Alexa 2020); optimal cone placement (Crane et al. 2018); Schläfli identity (Rivin–Springborn 1999); hyperbolic polyhedra (Springborn 2019); polyhedral period matrices (Bobenko–Bücking 2009); integrable cluster dynamics (Springborn–Veselov 2015); BFF (Crane et al. 2017); stripe patterns (Bonneel et al. 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–Springborn 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 |