conformallab/ConformalLabpp
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

feat: output_uv_map for InversiveDistance, error for CP-Euclidean, reviewer trio

Browse Source 
Three reviewer-meeting deliverables in one commit.

(1) output_uv_map for the two remaining DCE entries
    ─────────────────────────────────────────────────
    * Discrete_inversive_distance.h: full implementation.  After Newton,
      reconstruct effective Euclidean edge lengths from the converged
      log-radii via the Bowers-Stephenson identity
      `ℓᵢⱼ² = rᵢ² + rⱼ² + 2·Iᵢⱼ·rᵢ·rⱼ`, populate a temporary
      EuclideanMaps with `lambda0 = log(ℓᵢⱼ²)`, and reuse the existing
      `euclidean_layout(mesh, 0, eucl)` priority-BFS.  Per-vertex
      Point_2 coordinates written into the user-supplied pmap.
      Optional `normalise_layout(true)` applies the canonical PCA
      centroid + major-axis rotation, same as the other 3 entries.

    * Discrete_circle_packing.h: throws std::runtime_error with a
      clear pointer to Phase 9c rather than silently producing
      nonsense.  CP-Euclidean is face-based; the faithful output is a
      per-face circle packing in ℝ², not a per-vertex Point_2 map.
      A true layout requires BPS-2010 §6 (~150 lines, on the porting
      roadmap as Phase 9c).  Failing loudly is the honest default.

    Tests: 2 new cases in test_cgal_phase8b_lite.cpp
    (OutputUvMap_InversiveDistance_PopulatesPmap;
    OutputUvMap_CPEuclidean_ThrowsClearly).  Both green.
    Suite total now 259 (was 257, +2).  CGAL subtotal: 234 → 236.

(2) Reviewer meeting documents
    ──────────────────────────
    New directory doc/reviewer/ with three files:

    * briefing.md  — one-page orientation for the reviewer.
      What the project is, where to look first
      (https://tmoussa.codeberg.page/ConformalLabpp/), the headline
      evidence (tests/coverage/sanitizers/license), what we want from
      them, what's deferred and why, and the 5 questions in a separate
      file.

    * questions.md — the 5 concrete decisions we want their second
      opinion on:
        Q1 Phase 9c (port-literal vs re-derive)
        Q2 Phase 9b-analytic (worth ~2 weeks for ~6× speedup?)
        Q3 CP-Euclidean output_uv_map (build now or defer?)
        Q4 CGAL submission strategy (one package or five?)
        Q5 geometry-central cross-validation co-authorship
      Plus an explicit "what would you say no to?" question at the
      bottom — negative feedback is the highest-value information.

    * agenda.md   — my own internal playbook (NOT to be sent).
      60-min flow: 5-min thank-you, 10-min architecture tour,
      30-min for Q1-Q5 in the order Q4-Q1-Q2-Q5-Q3, 5-min "no"
      question, 5-min wrap-up.  Includes post-meeting memo template
      to fill out in the 30 min after.

    * README.md    — index for the directory; says which file goes
      to whom and when to send.

(3) locked-vs-flexible.md known-limitations update
    ─────────────────────────────────────────────
    "output_uv_map covers 3 of 5 entries" → "covers 4 of 5".
    CP-Euclidean's throws-clearly behaviour documented as a Phase 9c
    deliverable rather than a passive gap.

Bonus: extended .codespellrc ignore list (acknowledgement, the
British-English spelling I used in agenda.md).

Verifications on this commit:
  259/259 tests pass (0 skipped)
  scripts/check-test-counts.sh:                OK (23 + 236 = 259)
  scripts/quality/license-headers.sh:          OK (66/66 SPDX)
  python3 scripts/quality/cgal-conventions.py: OK (0/6 violations)
  scripts/quality/codespell.sh:                OK (0 typos)
  scripts/quality/shellcheck.sh:               OK (0 findings)
  python3 scripts/check-markdown-links.py:     OK (143/143)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Tarik Moussa
2026-05-24 21:15:19 +02:00
committed by Tarik Moussa
parent 32253a8f5e
commit f25174ed69
10 changed files with 554 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
code/include/CGAL/Discrete_circle_packing.h
View File

@@ -34,6 +34,8 @@ class (Strategy C of the Phase 8b architecture audit).
#include "../cp_euclidean_functional.hpp"
#include "../newton_solver.hpp"
#include <stdexcept>
namespace CGAL {
// ── Default traits for CP-Euclidean ───────────────────────────────────────────
@@ -186,6 +188,45 @@ auto discrete_circle_packing_euclidean(
result.iterations = nr.iterations;
result.gradient_norm = nr.grad_inf_norm;
result.converged = nr.converged;
// ── output_uv_map (Phase 8b-Lite extension) ────────────────────────────
//
// The CP-Euclidean functional carries one DOF per *face* (the log of the
// face-circle radius `ρ_f = log R_f`), not per vertex. A faithful
// layout therefore produces a circle packing in ℝ² — each face f is
// mapped to a circle of radius `R_f` at some centre `c_f`, with
// adjacent circles meeting at the prescribed intersection angle `θ_e`.
// That is a per-face output, not the per-vertex Point_2 that
// `output_uv_map` is typed for.
//
// For Phase 8b-Lite we deliberately don't fake it. If the caller
// supplies `output_uv_map(pmap)` we throw `std::runtime_error` with a
// clear pointer to Phase 9c (BPS-2010 §6 face-based circle-packing
// layout, ~150 lines, on the porting roadmap). Failing loudly is
// better than silently writing zeros.
//
// Users who want a UV-like coordinate today can:
// 1. Solve a Euclidean DCE on the same mesh (vertex DOFs),
// 2. Use `discrete_inversive_distance_map(... output_uv_map(pmap))`,
// 3. Or compute face-centre positions by hand from `result.rho_per_face`
// + the per-edge `θ_e` values, plus a priority-BFS of their own.
{
auto uv_param = parameters::get_parameter(
np, Conformal_map::internal_np::output_uv_map);
constexpr bool has_uv = !std::is_same_v<
decltype(uv_param), internal_np::Param_not_found>;
if constexpr (has_uv) {
throw std::runtime_error(
"CGAL::discrete_circle_packing_euclidean: the "
"`output_uv_map(...)` named parameter is not yet supported "
"for face-based CP-Euclidean. The faithful output is a "
"circle packing in the plane (per-face), not per-vertex "
"UVs. Tracked as Phase 9c; "
"see doc/architecture/locked-vs-flexible.md and "
"doc/tutorials/add-output-uv-map.md.");
}
}
return result;
}

48
code/include/CGAL/Discrete_inversive_distance.h
View File

@@ -207,6 +207,54 @@ auto discrete_inversive_distance_map(
result.iterations = nr.iterations;
result.gradient_norm = nr.grad_inf_norm;
result.converged = nr.converged;
// ── Optional layout step (Phase 8b-Lite extension) ─────────────────────
//
// If the caller supplied `output_uv_map(pmap)`, lay out the converged
// packing in ℝ² and write per-vertex `Point_2` coordinates into `pmap`.
//
// Method: the converged Inversive-Distance radii `r_i = exp(u_i)`
// together with the fixed per-edge `I_ij` constants determine effective
// Euclidean edge lengths via the Bowers-Stephenson identity
// ℓᵢⱼ² = rᵢ² + rⱼ² + 2·Iᵢⱼ·rᵢ·rⱼ
// so we can populate a temporary `EuclideanMaps` whose `lambda0` carries
// `log(ℓᵢⱼ²)` per edge and then reuse `euclidean_layout(mesh, 0, eucl)`
// — the existing priority-BFS trilateration on the resulting triangle
// metric. All vertex/edge DOF indices stay at −1 (pinned), so the empty
// DOF vector `0` produces lengths driven purely by `lambda0`.
auto uv_param = parameters::get_parameter(
np, Conformal_map::internal_np::output_uv_map);
constexpr bool has_uv = !std::is_same_v<
decltype(uv_param), internal_np::Param_not_found>;
if constexpr (has_uv) {
if (nr.converged) {
auto eucl = ::conformallab::setup_euclidean_maps(mesh);
for (auto e : mesh.edges()) {
auto h = mesh.halfedge(e);
const double u_i = result.u_per_vertex[mesh.source(h).idx()];
const double u_j = result.u_per_vertex[mesh.target(h).idx()];
const double I = maps.I_e[e];
const double l2 = ::conformallab::id_detail::edge_length_squared(u_i, u_j, I);
eucl.lambda0[e] = (l2 > 0.0) ? std::log(l2) : -30.0;
}
// Empty DOF vector: every vertex is pinned (idx=-1), so the
// layout depends purely on the lambda0 we just computed.
std::vector<double> zero;
auto layout = ::conformallab::euclidean_layout(mesh, zero, eucl);
const bool do_norm = parameters::choose_parameter(
parameters::get_parameter(np, Conformal_map::internal_np::normalise_layout),
false);
if (do_norm) ::conformallab::normalise_euclidean(layout);
for (auto v : mesh.vertices()) {
const auto& uv = layout.uv[v.idx()];
put(uv_param, v,
typename Traits::Kernel::Point_2(uv.x(), uv.y()));
}
}
}
return result;
}