diff --git a/README.md b/README.md index 1b94fa8..04d24f1 100644 --- a/README.md +++ b/README.md @@ -81,6 +81,7 @@ Layout2D layout = euclidean_layout(mesh, res.x, maps); | **Processing unit contracts** — preconditions / provides table | [doc/api/contracts.md](doc/api/contracts.md) | | **CGAL package design** — Phase 8 target, YAML pipeline | [doc/api/cgal-package.md](doc/api/cgal-package.md) | | **Architecture & pipeline diagram** | [doc/architecture/overall_pipeline.md](doc/architecture/overall_pipeline.md) | +| **geometry-central comparison** — shared core, demarcation, adoption candidates, scientific added value | [doc/architecture/geometry-central-comparison.md](doc/architecture/geometry-central-comparison.md) | | **Design decisions** — key architectural choices + rationale | [doc/architecture/design-decisions.md](doc/architecture/design-decisions.md) | | **Project structure** — directory tree + build targets | [doc/architecture/project-structure.md](doc/architecture/project-structure.md) | | **Discrete conformal theory** — mathematical background for collaborators | [doc/math/discrete-conformal-theory.md](doc/math/discrete-conformal-theory.md) | diff --git a/doc/architecture/geometry-central-comparison.md b/doc/architecture/geometry-central-comparison.md new file mode 100644 index 0000000..40a78b4 --- /dev/null +++ b/doc/architecture/geometry-central-comparison.md @@ -0,0 +1,281 @@ +# conformallab++ vs. geometry-central — Detailed Comparison + +> **Purpose of this document.** +> conformallab++ and geometry-central (CMU, Keenan Crane's group) both implement +> discrete conformal equivalence of triangulated surfaces. They share the same +> mathematical core but diverge in algorithmic strategy, scope, and target audience. +> This document maps the overlap precisely, identifies what cannot and should not be +> adopted, and explains where a side-by-side study creates scientific added value. + +--- + +## 1 — Shared mathematical foundation + +Both libraries implement the following chain: + +``` +Input mesh M → edge lengths ℓᵢⱼ → solve for u ∈ ℝᵛ + such that ℓ̃ᵢⱼ = e^{(uᵢ+uⱼ)/2} · ℓᵢⱼ satisfies Σα_v(u) = Θᵥ ∀v +``` + +The variational framework that makes this a well-posed optimisation problem goes +back to **Bobenko & Springborn (2004)**. The hyperbolic (HyperIdeal) geometry is +from **Springborn (2020)**. The geometry-central implementation (Gillespie, +Springborn & Crane, SIGGRAPH 2021) is an explicit extension of Springborn 2020 +to intrinsic triangulations. + +**Key consequence:** the *mathematical problem* is identical. Any difference in +output is either a normalization convention or a bug in one of the two libraries — +making cross-validation directly meaningful. + +--- + +## 2 — Algorithmic comparison + +| Dimension | conformallab++ | geometry-central (Gillespie 2021) | +|---|---|---| +| **Solver** | Newton–Raphson, analytical Hessian | Newton or Yamabe gradient flow (user choice) | +| **Convergence** | Quadratic (8–20 iterations on typical meshes) | Newton: quadratic; Yamabe: linear (~hundreds of steps) | +| **Triangulation** | Fixed throughout — operates on original `Surface_mesh` | Ptolemaic flips applied before/during solve to reach intrinsic Delaunay | +| **Hessian** | SimplicialLDLT + SparseQR fallback; analytical for Euclidean/Spherical, FD for HyperIdeal | Assembled on the current (possibly flipped) triangulation | +| **Mesh backend** | CGAL `Surface_mesh` | geometry-central `ManifoldSurfaceMesh` | +| **Geometry modes** | Euclidean ✓ · Spherical ✓ · HyperIdeal ✓ | Euclidean ✓ · Hyperbolic ✓ · Spherical ✗ | +| **Open meshes** | ✓ (boundary DOFs pinned) | ✓ | + +### Why Newton on a fixed triangulation works well + +The Euclidean and HyperIdeal energies are strictly convex after gauge-fixing. +Newton therefore converges from u=0 in 8–20 iterations for any reasonable mesh. +The Hessian is the cotangent Laplacian (Euclidean) or its hyperbolic analog — +well-conditioned on Delaunay meshes, but can degrade on strongly non-Delaunay inputs. + +### What Ptolemaic flips add + +A Ptolemaic flip replaces diagonal AC with BD in a quadrilateral under the constraint +that the Ptolemy relation + +``` +AC · BD = AB · CD + AD · BC +``` + +holds. This is *conformal-class-preserving* — the new λ₀ values represent the same +discrete conformal structure. The gain: the flipped triangulation is intrinsic +Delaunay, which bounds the off-diagonal Hessian entries and prevents ill-conditioning +on pathological inputs. + +**This is the only genuine algorithmic advantage geometry-central has for the shared +sub-problem.** It costs nothing mathematically and buys robustness on bad meshes. + +--- + +## 3 — Feature matrix: what exists where + +| Feature | conformallab++ | geometry-central | Notes | +|---|---|---|---| +| Discrete conformal equivalence (Euclidean) | ✓ | ✓ | Shared core | +| Discrete conformal equivalence (Hyperbolic/HyperIdeal) | ✓ (Springborn 2020 formulation) | ✓ (Gillespie 2021 extension) | Mathematically equivalent | +| Discrete conformal equivalence (Spherical) | ✓ | ✗ | Unique to conformallab++ | +| Analytical Hessian (Euclidean & Spherical) | ✓ | ✓ | | +| Analytical Hessian (HyperIdeal) | FD (Phase 9b: analytical planned) | ✓ | gc has analytical version | +| Gauss–Bonnet check & enforce | ✓ | implicit in solver | | +| Tree-cotree cut graph (2g seam edges) | ✓ | ✗ | Required for period matrix | +| Priority-BFS layout in ℝ²/S²/Poincaré disk | ✓ | partial (conformal param only) | | +| Möbius holonomy SU(1,1) | ✓ | ✗ | Unique to conformallab++ | +| Period matrix τ ∈ ℍ + SL(2,ℤ) reduction | ✓ | ✗ | Unique to conformallab++ | +| Fundamental domain + tiling | ✓ | ✗ | Unique to conformallab++ | +| Intrinsic Delaunay triangulation | ✗ | ✓ | gc has via SignpostIntrinsicTriangulation | +| Ptolemaic flips | ✗ | ✓ | gc's robustness mechanism | +| Heat method (geodesic distances) | ✗ | ✓ | Auxiliary tool in gc | +| YAML/declarative pipeline | ✓ (Phase 8e spec) | ✗ | | +| CGAL-package submission | ✓ (Phase 8 target) | ✗ | | +| JSON/XML serialisation | ✓ | ✗ | | +| CLI app | ✓ | ✗ | | +| Inversive distance functional (Luo 2004) | ✗ (Phase 9a) | ✗ | Neither has it yet | +| Siegel period matrix Ω (genus g≥2) | ✗ (Phase 10b) | ✗ | | + +--- + +## 4 — What should be adopted — and what should not + +### Adopt: Ptolemaic pre-conditioning (GC-2, after Phase 8) + +**What:** a single preprocessing pass that Delaunay-izes the input triangulation +via Ptolemaic flips, updates λ₀ accordingly, then hands off to the existing +Newton pipeline unchanged. + +**Why it fits:** +- Preserves the conformal class — mathematically sound +- Drop-in before `compute_euclidean_lambda0_from_mesh()`, no interface change +- Does not touch cut graph, holonomy, period matrix +- ~200 lines of code, one new test suite + +**Interface sketch:** +```cpp +// include/preprocessing_delaunay.hpp (Phase GC-2) +void ptolemy_delaunay(ConformalMesh& mesh, EuclideanMaps& maps); +// Flips edges until all faces satisfy the Delaunay condition. +// Updates maps.lambda0[e] via the Ptolemy relation after each flip. +// Prerequisite: compute_euclidean_lambda0_from_mesh() already called. +// Postcondition: mesh is an intrinsic Delaunay triangulation of the same surface. +``` + +### Adopt partially: analytical HyperIdeal Hessian + +geometry-central has a closed-form Hessian for the hyperbolic energy. +conformallab++ currently uses finite differences (Phase 9b plans analytical). +The geometry-central implementation can serve as a reference for Phase 9b — +not a code copy, but a mathematical cross-check. + +### Do not adopt: full intrinsic triangulations as architecture + +**SignpostIntrinsicTriangulation** is geometry-central's core data structure. +It tracks vertex positions as (face, barycentric coordinates) rather than 3D points. +Replacing `CGAL::Surface_mesh` with this would require: + +1. Rewriting the cut graph algorithm (which works on halfedges of the *original* mesh + and must survive across flips — non-trivial bookkeeping) +2. Tracking seam edges through flip events for holonomy computation +3. Abandoning the CGAL package target (Phase 8) — CGAL's mesh concepts are extrinsic +4. Losing the 3D layout output (Poincaré disk, sphere) which clients depend on + +**Verdict:** the architecture incompatibility is fundamental, not incidental. +The period matrix pipeline requires a stable topological cut that does not survive +arbitrary flip sequences. This is not a solvable engineering problem within the +current project scope — it would be a different project. + +### Do not adopt: Yamabe flow + +Newton converges in 8–20 iterations; Yamabe flow needs hundreds. +The only reason to use Yamabe flow is when the Hessian is indefinite (which happens +in the Spherical case — and conformallab++ already handles this with the correct +sign flip in the energy). There is no mesh type where Yamabe flow beats Newton +on metrics that conformallab++ targets. + +--- + +## 5 — Where cross-comparison creates scientific added value + +### 5.1 — Independent cross-validation of the shared core + +The discrete conformal equivalence problem for Euclidean and HyperIdeal geometry +is implemented independently in two codebases, by different groups, with different +algorithms. Agreement on: + +- the u-vector (after normalization) +- UV coordinates (up to Möbius transformation) +- the residual ‖G(u*)‖ at convergence + +would constitute **mutual validation without ground truth**. This is the same +methodology used in numerical PDE literature to validate independent solvers. + +**Concrete protocol:** +``` +For each test mesh (cathead.obj, brezel.obj, torus_4x4.off, torus_hex_6x6.off): + 1. Load into both libraries with identical vertex ordering + 2. Run conformallab++ Newton solver → u_clab, UV_clab + 3. Run geometry-central solver → u_gc, UV_gc + 4. Normalize both (subtract mean, divide by scale) + 5. Report max|u_clab[v] - u_gc[v]| and mean conformal distortion difference +``` + +Expected: agreement to ≤ 1e-8 on well-conditioned meshes. Discrepancy would +indicate a bug or a normalization mismatch worth investigating. + +### 5.2 — Convergence study: Newton with vs. without Ptolemaic pre-conditioning + +Hypothesis: on non-Delaunay meshes (e.g. a torus refined by subdivision without +re-meshing), Ptolemaic Delaunay pre-conditioning reduces Newton iteration count. + +**Measurable quantities:** +- Newton iterations to ‖G‖ < 1e-8 +- Hessian condition number κ(H) at u = 0 +- Wall-clock time + +This comparison requires only GC-2 to be implemented in conformallab++ and would +answer the question: *how bad does a mesh have to be before Ptolemaic pre-conditioning +pays off?* + +**Publication potential:** a short note or conference contribution comparing the +two approaches on a systematic mesh quality benchmark would be self-contained and +novel — neither library has published this comparison. + +### 5.3 — Period matrix and holonomy as differentiating contribution + +geometry-central deliberately stops at the conformal parameterization. The period +matrix τ and Möbius holonomy computation in conformallab++ extend the pipeline into +Teichmüller theory territory that geometry-central does not address. + +This is the strongest scientific differentiator: conformallab++ can compute + +``` +τ = ω_b / ω_a ∈ ℍ, SL(2,ℤ)-reduced +``` + +for any closed genus-1 surface, and (in Phase 10) the Siegel matrix Ω for genus g≥2. +No other open-source C++ library does this. Cross-comparison with geometry-central +makes this gap explicit and positions conformallab++ as the more complete tool for +Teichmüller-theoretic applications. + +### 5.4 — Spherical geometry as unique contribution + +The Spherical geometry mode (angle sums → 4π on a sphere, NSD Hessian with sign +flip) has no counterpart in geometry-central. A mathematician interested in +conformal maps on surfaces of positive curvature (constant curvature +1) has no +alternative in open-source C++. + +### 5.5 — Validation of Springborn 2020 in two independent implementations + +Springborn 2020 ("Ideal Hyperbolic Polyhedra and Discrete Uniformization") is the +shared theoretical reference for both the HyperIdeal geometry mode in conformallab++ +(Phase 2/3) and the hyperbolic component of Gillespie 2021 in geometry-central. +Cross-checking the ζ-function values (ζ₁₃, ζ₁₄, ζ₁₅) and the resulting angle sums +on the same meshes would validate both implementations of the paper — a service to +the discrete geometry community. + +--- + +## 6 — Demarcation: where the comparison ends + +| Topic | conformallab++ | geometry-central | Comparable? | +|---|---|---|---| +| u-vector at convergence | ✓ | ✓ | ✓ after normalization | +| UV parameterization | ✓ | ✓ | ✓ up to Möbius | +| Convergence speed (iterations) | ✓ | ✓ (Newton mode) | ✓ direct | +| HyperIdeal angle sums | ✓ | ✓ | ✓ | +| Spherical angle sums | ✓ | ✗ | ✗ | +| Period matrix τ | ✓ | ✗ | ✗ | +| Holonomy T_a, T_b | ✓ | ✗ | ✗ | +| Fundamental domain | ✓ | ✗ | ✗ | +| Intrinsic Delaunay quality | not tracked | ✓ | — | +| Mesh topology handling | CGAL halfedge | gc manifold mesh | not comparable | +| Scalability (large meshes) | not benchmarked yet | benchmarked in paper | comparable if same mesh | + +The comparison is meaningful and complete for the **shared conformal core**. +It ends where conformallab++ continues into Teichmüller theory (holonomy, τ, +fundamental domain) — that region has no counterpart in geometry-central and +must be validated by analytic invariants alone (→ `doc/math/validation.md`). + +--- + +## 7 — Practical roadmap for the comparison + +| Step | When | What | Effort | +|---|---|---|---| +| **GC-1a** | Now | Manual UV comparison on cathead.obj — run both, diff u-vectors | 1 day | +| **GC-1b** | Now | Add normalization utility to conformallab++ (`normalize_u_vector()`) | 2h | +| **GC-1c** | After Phase 8 | Automated comparison script (Python or small C++ binary) | 2 days | +| **GC-2** | After Phase 8 | `ptolemy_delaunay()` preprocessing pass | 1 week | +| **GC-bench** | After GC-2 | Convergence study: Newton ± Ptolemaic pre-conditioning on 10 meshes | 1 week | +| **GC-paper** | Phase 10 | Short note on the comparison — period matrix as differentiator | — | + +--- + +## 8 — References + +| Reference | Role in this comparison | +|---|---| +| **Bobenko, Springborn** — *Variational Principles for Circle Patterns*, Trans. AMS (2004) | Shared variational foundation for all three geometry modes | +| **Springborn** — *Ideal Hyperbolic Polyhedra and Discrete Uniformization*, DCG (2020) | Mathematical basis for HyperIdeal in conformallab++ AND for Gillespie 2021 | +| **Gillespie, Springborn, Crane** — *Discrete Conformal Equivalence of Polyhedral Surfaces*, SIGGRAPH (2021) | geometry-central implementation; introduces Ptolemaic flips | +| **Sharp, Soliman, Crane** — *Navigating Intrinsic Triangulations*, SIGGRAPH (2019) | geometry-central `SignpostIntrinsicTriangulation` — basis for GC-2 | +| **Sechelmann** — doctoral thesis, TU Berlin (2016) | conformallab++ primary source; covers period matrix, holonomy, all three modes |