feat(p1): CLI extensions + quality measures + stereographic layout

Implement Phase-Session P1 quick wins (4 independent additions):

9h.1: Add --tol and --max-iter CLI options to conformallab_core
  - Newton solver tolerance [default 1e-8]
  - Newton iteration limit [default 200]
  - Thread both through run_euclidean / run_spherical / run_hyper_ideal
  - Update CLI parameter table in documentation

9h.2: Add -g cp_euclidean and -g inversive_distance geometry routes
  - run_cp_euclidean() & run_inversive_distance() pipelines (~60 lines each)
  - Face-based DOF assignment for CP-Euclidean
  - Vertex-based DOF assignment for Inversive-Distance
  - Both integrated into CLI geometry validator (IsMember)

9g.1: Create conformal_quality.hpp with validation measures
  - IsothermicityMeasure: metric anisotropy (conformality deviation)
  - DiscreteConformalEquivalenceMeasure: length-cross-ratio residuals
  - FlippedTriangles: detects inverted/degenerate triangles
  - LengthCrossRatio: discrete conformal invariant computation
  - ConvergenceUtility: aggregated convergence statistics (max/mean/sum)
  - Ported from Java: plugin/visualizer + convergence utilities
  - Includes sanity tests validating finite outputs on valid layouts

9d.3: Create stereographic_layout.hpp for S² → ℂ projection
  - Stereographic projection from north pole: S² → ℂ ∪ {∞}
  - Inverse projection: ℂ → S² for round-trip validation
  - Möbius centring: centres the 2-D point cloud at origin
  - stereographic_layout(Layout3D) -> Layout2D conversion
  - Round-trip tests: south pole, equator, random sphere points
  - Tests: projection/inverse consistency, north pole handling

Test results: 336/336 CGAL tests pass (272 pre-existing + 64 new from all phases)
- conformal_quality.cpp: 13 new tests (measures, isothermic, dce, convergence)
- stereographic_layout.cpp: 10 new tests (projection, inverse, round-trip, layout)

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

code/include/conformal_quality.hpp

@@ -0,0 +1,384 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
+// conformal_quality.hpp
+//
+// Phase 9g.1 — Quantitative correctness metrics for computed conformal maps.
+//
+// Measures the quality and validity of a discrete conformal map layout:
+// - IsothermicityMeasure: pointwise deviation from conformality (metric anisotropy).
+// - DiscreteConformalEquivalenceMeasure: per-edge length-cross-ratio residual.
+// - FlippedTriangles: detects inverted/degenerate triangles in 2-D layouts.
+// - LengthCrossRatio: the discrete conformal invariant (per-edge).
+// - ConvergenceUtility: aggregated convergence measures (max, mean, sum of cross-ratios).
+//
+// Mathematical references:
+//   Springborn-Schröder-Pinkall 2008: discrete conformal invariant theory.
+//   Bobenko-Springborn 2004: variational foundation.
+//
+// Java sources (ported from):
+//   plugin/visualizer/IsothermicityMeasure.java
+//   plugin/visualizer/DiscreteConformalEquivalencemMeasure.java
+//   plugin/visualizer/FlippedTriangles.java
+//   heds/adapter/types/LengthCrossRatio.java
+//   convergence/ConvergenceUtility.java
+
+#pragma once
+
+#include "conformal_mesh.hpp"
+#include "layout.hpp"
+#include <Eigen/Dense>
+#include <vector>
+#include <cmath>
+#include <algorithm>
+
+namespace conformallab {
+
+// ────────────────────────────────────────────────────────────────────────────
+// LengthCrossRatio — the discrete conformal invariant
+// ────────────────────────────────────────────────────────────────────────────
+
+/// Compute the cross-ratio q = (a·c)/(b·d) of the four edges of a
+/// quadrilateral formed by two adjacent triangles sharing an edge.
+/// Input: edge lengths a, b, c, d in order around the quad.
+/// Returns the cross-ratio q.
+inline double length_cross_ratio(double a, double b, double c, double d)
+{
+    const double denom = b * d;
+    if (denom < 1e-16) return 0.0;  // degenerate edge
+    return (a * c) / denom;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// IsothermicityMeasure — pointwise metric anisotropy
+// ────────────────────────────────────────────────────────────────────────────
+
+/// Evaluate the isothermicity measure at a single vertex in a 2-D layout.
+/// Isothermicity is the local conformality condition: the metric tensor
+/// is a positive scalar multiple of the identity (no anisotropy).
+/// Measure: pointwise deviation from a conformal map.
+/// Returns the anisotropy ratio (1.0 = isotropic / conformal).
+inline double isothermicity_measure_at_vertex(
+    const ConformalMesh&          mesh,
+    Vertex_index                  v,
+    const Layout2D&               layout)
+{
+    // Collect all halfedges emanating from v.
+    std::vector<Halfedge_index> hs;
+    for (auto h : CGAL::halfedges_around_source(v, mesh))
+        hs.push_back(h);
+
+    if (hs.empty()) return 1.0;
+
+    // Compute metric tensor components at v via edge pairs.
+    // For a conformal map, the metric g = λ²I (λ > 0 scale factor, I identity).
+    // Compute an empirical metric from the layout: edges adjacent to v
+    // span the tangent space.
+    double g11 = 0.0, g12 = 0.0, g22 = 0.0;
+    int n_edges = 0;
+
+    for (std::size_t i = 0; i < hs.size(); ++i) {
+        auto h1 = hs[i];
+        auto h2 = hs[(i + 1) % hs.size()];
+
+        Vertex_index v2 = mesh.target(h1);  // = mesh.source(h2)
+        Vertex_index v3 = mesh.target(h2);
+
+        const auto& p1 = layout.uv[v.idx()];
+        const auto& p2 = layout.uv[v2.idx()];
+        const auto& p3 = layout.uv[v3.idx()];
+
+        // Two edge vectors from v.
+        double e1x = p2.x() - p1.x(), e1y = p2.y() - p1.y();
+        double e2x = p3.x() - p1.x(), e2y = p3.y() - p1.y();
+
+        // Metric tensor as outer product (unnormalised).
+        g11 += e1x * e1x;
+        g12 += e1x * e1y;
+        g22 += e1y * e1y;
+
+        // Also accumulate e2 contribution (for a rotationally averaged metric).
+        g11 += e2x * e2x;
+        g12 += e2x * e2y;
+        g22 += e2y * e2y;
+
+        n_edges += 2;
+    }
+
+    if (n_edges <= 0) return 1.0;
+
+    g11 /= n_edges;
+    g12 /= n_edges;
+    g22 /= n_edges;
+
+    // Eigenvalues of g: λ_± = (g11 + g22 ± √((g11-g22)² + 4g12²)) / 2.
+    double trace = g11 + g22;
+    double det = g11 * g22 - g12 * g12;
+
+    if (trace < 1e-16 || det < 1e-16) return 1.0;  // degenerate
+
+    double disc = (g11 - g22) * (g11 - g22) + 4.0 * g12 * g12;
+    disc = std::sqrt(disc);
+
+    double lambda_max = (trace + disc) / 2.0;
+    double lambda_min = (trace - disc) / 2.0;
+
+    if (lambda_min < 1e-16) return 1.0;  // degenerate
+
+    // Anisotropy: λ_max / λ_min (conformal ⟺ ratio ≈ 1).
+    return lambda_max / lambda_min;
+}
+
+/// Compute the isothermicity measure for the entire layout.
+/// Returns a vector of anisotropy ratios, one per vertex.
+inline std::vector<double> isothermicity_measure(
+    const ConformalMesh&          mesh,
+    const Layout2D&               layout)
+{
+    std::vector<double> result;
+    result.reserve(mesh.number_of_vertices());
+    for (auto v : mesh.vertices())
+        result.push_back(isothermicity_measure_at_vertex(mesh, v, layout));
+    return result;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// DiscreteConformalEquivalenceMeasure — length-cross-ratio residual
+// ────────────────────────────────────────────────────────────────────────────
+
+/// Evaluate the discrete conformal equivalence condition at a single edge.
+/// For an edge e = (i,j), form the quad with the two adjacent triangles:
+/// compute the cross-ratio q from the layout edge lengths.
+/// The conformal condition is: q + 1/q = 2 (i.e. q = 1, isotropic scaling).
+/// Measure: |q + 1/q - 2| (residual; 0 = conformal).
+inline double discrete_conformal_equivalence_at_edge(
+    const ConformalMesh&          mesh,
+    Edge_index                    e,
+    const Layout2D&               layout)
+{
+    // Find the two halfedges for this edge.
+    auto h = mesh.halfedge(e);
+
+    // Get the four vertices of the quad formed by the two adjacent triangles.
+    Vertex_index v1 = mesh.source(h);
+    Vertex_index v2 = mesh.target(h);
+    Vertex_index v3 = mesh.source(mesh.next(h));
+    Vertex_index v4 = mesh.source(mesh.next(mesh.opposite(h)));
+
+    // Compute edge lengths from the layout.
+    auto dist = [&layout](Vertex_index u1, Vertex_index u2) {
+        const auto& p1 = layout.uv[u1.idx()];
+        const auto& p2 = layout.uv[u2.idx()];
+        double dx = p1.x() - p2.x();
+        double dy = p1.y() - p2.y();
+        return std::sqrt(dx * dx + dy * dy);
+    };
+
+    double a = dist(v1, v3);  // opposite to v4
+    double b = dist(v1, v4);  // opposite to v3
+    double c = dist(v2, v3);  // opposite to v4
+    double d = dist(v2, v4);  // opposite to v3
+
+    // Cross-ratio q = (a·c)/(b·d).
+    double q = length_cross_ratio(a, b, c, d);
+
+    // Conformal condition: q + 1/q = 2 (only satisfied when q = 1).
+    if (q < 1e-16) return 1.0;  // degenerate
+    double residual = q + 1.0 / q - 2.0;
+    return std::abs(residual);
+}
+
+/// Compute the discrete conformal equivalence measure for all edges.
+/// Returns a vector of residuals, one per edge.
+inline std::vector<double> discrete_conformal_equivalence_measure(
+    const ConformalMesh&          mesh,
+    const Layout2D&               layout)
+{
+    std::vector<double> result;
+    result.reserve(mesh.number_of_edges());
+    for (auto e : mesh.edges())
+        result.push_back(discrete_conformal_equivalence_at_edge(mesh, e, layout));
+    return result;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// FlippedTriangles — embedded validity check
+// ────────────────────────────────────────────────────────────────────────────
+
+/// Check if a single triangle is flipped or degenerate in the 2-D layout.
+/// A triangle is valid iff its signed area > 0 (positive orientation).
+/// Degenerate: signed area ≈ 0 (collinear or nearly collinear vertices).
+/// Returns true if the triangle is flipped or degenerate.
+inline bool is_flipped_triangle(
+    const ConformalMesh&          mesh,
+    Face_index                    f,
+    const Layout2D&               layout)
+{
+    // Extract the three vertices of the triangle.
+    auto h = mesh.halfedge(f);
+    Vertex_index v1 = mesh.source(h);
+    Vertex_index v2 = mesh.source(mesh.next(h));
+    Vertex_index v3 = mesh.source(mesh.next(mesh.next(h)));
+
+    const auto& p1 = layout.uv[v1.idx()];
+    const auto& p2 = layout.uv[v2.idx()];
+    const auto& p3 = layout.uv[v3.idx()];
+
+    // Signed area (× 2): (p2 - p1) × (p3 - p1) in ℝ².
+    double signed_area_2x = (p2.x() - p1.x()) * (p3.y() - p1.y())
+                          - (p2.y() - p1.y()) * (p3.x() - p1.x());
+
+    // Positive area: valid orientation. Zero or negative: flipped/degenerate.
+    return signed_area_2x <= 1e-14;
+}
+
+/// Count the number of flipped or degenerate triangles in the layout.
+/// Returns the count (0 = valid layout).
+inline int flipped_triangles(
+    const ConformalMesh&          mesh,
+    const Layout2D&               layout)
+{
+    int count = 0;
+    for (auto f : mesh.faces())
+        if (is_flipped_triangle(mesh, f, layout))
+            count++;
+    return count;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// ConvergenceUtility — aggregated convergence measures
+// ────────────────────────────────────────────────────────────────────────────
+
+/// Aggregated cross-ratio statistics for a layout.
+struct CrossRatioStats {
+    double max_cross_ratio;      ///< max of (q + 1/q) over all edges
+    double mean_cross_ratio;     ///< mean of (q + 1/q)
+    double sum_cross_ratio;      ///< sum of (q + 1/q)
+
+    double max_multi_ratio;      ///< max per-face product of cross-ratios
+    double mean_multi_ratio;     ///< mean per-face product
+    double sum_multi_ratio;      ///< sum of per-face products
+
+    double max_scale_invariant_circumradius;  ///< max of R/√A per face
+    double mean_scale_invariant_circumradius; ///< mean of R/√A
+    double sum_scale_invariant_circumradius;  ///< sum of R/√A
+};
+
+/// Compute convergence statistics for a layout.
+/// - Cross-ratio (q + 1/q) per edge; aggregated max/mean/sum.
+/// - Multi-ratio: per-face product ∏(q + 1/q) for the 3 edges of each face.
+///   (Multi-ratio = 1 iff all edges are conformal.)
+/// - Scale-invariant circumradius: R/√A per face (mesh quality metric).
+inline CrossRatioStats convergence_utility(
+    const ConformalMesh&          mesh,
+    const Layout2D&               layout)
+{
+    CrossRatioStats stats = {};
+
+    std::vector<double> cross_ratios;
+    std::vector<double> multi_ratios;
+    std::vector<double> scale_inv_circumradii;
+
+    auto dist = [&layout](Vertex_index u1, Vertex_index u2) {
+        const auto& p1 = layout.uv[u1.idx()];
+        const auto& p2 = layout.uv[u2.idx()];
+        double dx = p1.x() - p2.x();
+        double dy = p1.y() - p2.y();
+        return std::sqrt(dx * dx + dy * dy);
+    };
+
+    // Per-face metrics.
+    for (auto f : mesh.faces()) {
+        auto h = mesh.halfedge(f);
+        Vertex_index v1 = mesh.source(h);
+        Vertex_index v2 = mesh.source(mesh.next(h));
+        Vertex_index v3 = mesh.source(mesh.next(mesh.next(h)));
+
+        const auto& p1 = layout.uv[v1.idx()];
+        const auto& p2 = layout.uv[v2.idx()];
+        const auto& p3 = layout.uv[v3.idx()];
+
+        // Signed area.
+        double signed_area_2x = (p2.x() - p1.x()) * (p3.y() - p1.y())
+                              - (p2.y() - p1.y()) * (p3.x() - p1.x());
+        double area = std::abs(signed_area_2x) / 2.0;
+
+        if (area < 1e-16) continue;  // degenerate
+
+        // Three edge lengths of the triangle.
+        double a = dist(v1, v2);
+        double b = dist(v2, v3);
+        double c = dist(v3, v1);
+
+        // Circumradius R = abc / (4·Area).
+        double circum_radius = (a * b * c) / (4.0 * area);
+
+        // Scale-invariant: R / √A.
+        double scale_inv_cr = circum_radius / std::sqrt(area);
+        scale_inv_circumradii.push_back(scale_inv_cr);
+
+        // Three cross-ratios (per edge/angle of the triangle).
+        // For each edge, form the quad with the opposite vertex and its neighbors.
+        double multi_product = 1.0;
+        for (int ei = 0; ei < 3; ++ei) {
+            auto he = mesh.halfedge(f);
+            for (int k = 0; k < ei; ++k) he = mesh.next(he);
+
+            Vertex_index eu1 = mesh.source(he);
+            Vertex_index eu2 = mesh.target(he);
+            Vertex_index eu3 = mesh.source(mesh.next(he));
+            Vertex_index eu4 = mesh.source(mesh.next(mesh.opposite(he)));
+
+            double ea = dist(eu1, eu3);
+            double eb = dist(eu1, eu4);
+            double ec = dist(eu2, eu3);
+            double ed = dist(eu2, eu4);
+
+            double q = length_cross_ratio(ea, eb, ec, ed);
+            if (q > 1e-16) {
+                double qf = q + 1.0 / q;
+                cross_ratios.push_back(qf);
+                multi_product *= qf;
+            }
+        }
+        multi_ratios.push_back(multi_product);
+    }
+
+    // Aggregate statistics.
+    if (!cross_ratios.empty()) {
+        auto [min_it, max_it] = std::minmax_element(cross_ratios.begin(), cross_ratios.end());
+        stats.max_cross_ratio = *max_it;
+        stats.mean_cross_ratio = 0.0;
+        for (double v : cross_ratios) stats.mean_cross_ratio += v;
+        stats.mean_cross_ratio /= static_cast<double>(cross_ratios.size());
+        stats.sum_cross_ratio = 0.0;
+        for (double v : cross_ratios) stats.sum_cross_ratio += v;
+    }
+
+    if (!multi_ratios.empty()) {
+        auto [min_it, max_it] = std::minmax_element(multi_ratios.begin(), multi_ratios.end());
+        stats.max_multi_ratio = *max_it;
+        stats.mean_multi_ratio = 0.0;
+        for (double v : multi_ratios) stats.mean_multi_ratio += v;
+        stats.mean_multi_ratio /= static_cast<double>(multi_ratios.size());
+        stats.sum_multi_ratio = 0.0;
+        for (double v : multi_ratios) stats.sum_multi_ratio += v;
+    }
+
+    if (!scale_inv_circumradii.empty()) {
+        auto [min_it, max_it] = std::minmax_element(scale_inv_circumradii.begin(),
+                                                     scale_inv_circumradii.end());
+        stats.max_scale_invariant_circumradius = *max_it;
+        stats.mean_scale_invariant_circumradius = 0.0;
+        for (double v : scale_inv_circumradii)
+            stats.mean_scale_invariant_circumradius += v;
+        stats.mean_scale_invariant_circumradius /= static_cast<double>(scale_inv_circumradii.size());
+        stats.sum_scale_invariant_circumradius = 0.0;
+        for (double v : scale_inv_circumradii)
+            stats.sum_scale_invariant_circumradius += v;
+    }
+
+    return stats;
+}
+
+}  // namespace conformallab