ConformalLabpp/doc/math/software-landscape.md

# Software Landscape — Discrete Conformal Geometry Tools

> **Purpose.** A mathematician evaluating conformallab++ needs to know how it
> relates to existing tools.  This document maps the full landscape and explains
> why no existing library covers the same ground.

---

## 1 — The two problems that look the same but are not

The term "conformal parameterization" covers two fundamentally different problems:

### Problem A — Conformal distortion minimization (LSCM / ABF++ / ARAP)

Find a UV map u: V → ℝ² that *minimises* a measure of angle distortion.
This is an unconstrained or lightly constrained optimisation over UV coordinates.
The solution depends on the embedding in ℝ³ and is **not unique** — it minimises
distortion but does not assign the surface to a canonical conformal class.

Tools: **libigl, CGAL Surface_parameterization, pmp-library, Blender, MeshLab**.

### Problem B — Discrete conformal equivalence (DCE)

Find scale factors u ∈ ℝᵛ such that the rescaled metric
ℓ̃ᵢⱼ = e^{(uᵢ+uⱼ)/2} · ℓᵢⱼ has prescribed cone angles Θᵥ at every vertex.
This is a variational problem on the *intrinsic metric* — independent of any
embedding.  The solution is **unique** (up to a global Möbius transformation)
and places the surface in its canonical position in Teichmüller space.

Tools: **conformallab++, geometry-central (partial), original Java ConformalLab**.

> **This distinction matters.**  A UV map from LSCM minimises distortion but
> cannot be used to compute the period matrix τ ∈ ℍ.  A DCE solution can.

---

## 2 — Full comparison table

| Library | Lang | DCE solver | Spherical | HyperIdeal | Cut graph | Holonomy | Period τ | Open source |
|---|---|---|---|---|---|---|---|---|
| **conformallab++** | C++17 | Newton (quad.) | ✓ | ✓ | ✓ (tree-cotree) | ✓ SU(1,1) | ✓ SL(2,ℤ) | ✓ MIT |
| Java ConformalLab | Java 8 | Newton | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ LGPL |
| geometry-central | C++17 | Newton / Yamabe | ✗ | ✓ (partial) | ✗ | ✗ | ✗ | ✓ MIT |
| libigl | C++14 | LSCM / ARAP¹ | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ MPL-2 |
| CGAL Parameterization | C++ | LSCM / Orbifold¹ | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ GPL/LGPL |
| pmp-library | C++17 | harmonic / param.¹ | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ MIT |
| OpenFlipper | C++ | LSCM plugin¹ | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ LGPL |
| Matlab geom. toolbox | MATLAB | LSCM / ABF++¹ | ✗ | ✗ | ✗ | ✗ | ✗ | commercial |

¹ These are Problem-A methods (distortion minimisation), not DCE.

---

## 3 — Detailed comparison: conformallab++ vs. Java ConformalLab

conformallab++ is a C++17 reimplementation of the Java library:

| Aspect | Java ConformalLab | conformallab++ |
|---|---|---|
| Language | Java 8 | C++17 |
| Mesh type | Custom `CoHDS` halfedge | `CGAL::Surface_mesh` |
| Build system | Maven | CMake |
| Test framework | JUnit 4 | GTest + CGAL test format |
| Static linking | JVM required | standalone binary |
| CGAL integration | none | native (target: CGAL package) |
| Inversive distance | ✓ | planned (Phase 9a) |
| Analytic HI Hessian | ✓ | planned (Phase 9b) |
| Genus g>1 domain | ✓ partial | planned (Phase 9c) |
| Siegel matrix Ω | partial | planned (Phase 10b) |
| All three modes | ✓ | ✓ |
| Period matrix τ | ✓ | ✓ |
| Holonomy | ✓ | ✓ |

**Phase parity:** Phases 1–7 of conformallab++ cover all core Java features.
Phases 9–10 will complete the remaining items.  See `doc/roadmap/java-parity.md`
for the full feature-by-feature table.

---

## 4 — Detailed comparison: conformallab++ vs. geometry-central

geometry-central (Keenan Crane, CMU) is the closest external peer.
Both implement DCE but diverge significantly in scope and algorithm.

| Dimension | conformallab++ | geometry-central |
|---|---|---|
| **Solver** | Newton, quadratic convergence | Newton or Yamabe flow |
| **Triangulation** | Fixed original mesh | Intrinsic + Ptolemaic flips |
| **Spherical geometry** | ✓ (NSD Hessian, sign flip) | ✗ |
| **Cut graph** | ✓ tree-cotree, 2g seams | ✗ |
| **Holonomy** | ✓ SU(1,1) Möbius maps | ✗ |
| **Period matrix** | ✓ τ ∈ ℍ, SL(2,ℤ)-reduced | ✗ |
| **Fundamental domain** | ✓ genus 1 complete | ✗ |
| **Mesh backend** | CGAL `Surface_mesh` | gc `ManifoldSurfaceMesh` |
| **CGAL integration** | ✓ (target: package) | ✗ |

For a full analysis including adoption candidates and scientific added value,
see `doc/architecture/geometry-central-comparison.md`.

---

## 5 — What Problem-A tools cannot do

The following tasks require DCE (Problem B) and cannot be done with LSCM/ARAP:

| Task | Requires |
|---|---|
| Compute the period matrix τ of a torus | DCE + holonomy + period matrix |
| Classify a surface in Teichmüller space | DCE |
| Construct a flat metric with prescribed cone angles | DCE |
| Tile a surface by a lattice (fundamental domain) | DCE + cut graph + holonomy |
| Compare two surfaces conformally | DCE (same conformal class ↔ same τ) |
| Uniformize a hyperbolic surface (genus g ≥ 2) | HyperIdeal DCE |
| Compute holomorphic differentials (Phase 10) | DCE + cut graph + integration |

---

## 6 — When to use which tool

| Goal | Recommended tool |
|---|---|
| Fast UV unwrapping for texture mapping | libigl LSCM or pmp-library |
| Angle-preserving parameterization, distortion study | CGAL Surface_parameterization |
| Discrete conformal equivalence, research | **conformallab++** |
| DCE with maximum numerical robustness on bad meshes | geometry-central (+ Ptolemaic flips) |
| Full Teichmüller pipeline (τ, holonomy, domain) | **conformallab++** only |
| Interactive exploration (viewer) | conformallab++ (`-DWITH_CGAL=ON`) |
| Java ecosystem / existing ConformalLab workflow | Java ConformalLab |