review: usability audit v0.10.0 — all 11 findings resolved #34
Reference in New Issue
Block a user
No description provided.
Delete Branch "review/usability-audit-2026-05-31"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Summary
Documentation and usability review of v0.10.0 — all 11 findings resolved.
Audit document:
doc/reviewer/usability-audit-2026-05-31.mdFindings (11/11 ✅)
example_flatten.cpp: real conformal flattening with Θ_v=2π (cathead: 5 Newton iters, u_v range≈2.96)example_cgal_api.cpp: first runnable CGAL public API examplecontracts.md: check/enforce_gauss_bonnet HyperIdeal restriction + newton_hyper_ideal preconditions correctedDiscrete_conformal_map.h: stale\fileblock rewritten, lists all 5 entry functionsgetting-started.md: LOW_MEMORY_BUILD Mode 4 section addedlayout.hpp: Layout2D.uv/.halfedge_uv index semantics + no-compaction precondition documentedgetting-started.md: CLI parameter reference table (7 flags)phases.md: Phase 9h — CLI extensions (--tol/--max-iter + Phase-9a models), effort estimates + implementation sketchesNew files
code/examples/example_flatten.cpp— primary use case, real conformal mapcode/examples/example_cgal_api.cpp— CGAL public API demoTest plan
/test-cgalon the Pi/quality-gates🤖 Generated with Claude Code
External documentation and usability review of v0.10.0. 9 findings covering documentation correctness, API usability, and new-user experience. Critical: U1 — All examples show trivial identity map (natural theta), not real conformal flattening — new users see no-op output U2 — CGAL public API has zero runnable examples Medium: U3 — contracts.md incorrect: check_gauss_bonnet row missing HyperIdeal restriction (deleted overload after Finding-B) U4 — README still shows v0.9.0 (current: v0.10.0, 277 tests) U5 — Discrete_conformal_map.h header comment describes Phase-8a state; all 5 entry functions already implemented U6 — New gauge-vertex overload (Finding-D) not reflected in README or examples — old verbose loop still shown Minor: U7 — CONFORMALLAB_LOW_MEMORY_BUILD absent from getting-started.md U8 — CONFORMALLAB_LOW_MEMORY_BUILD absent from README table U9 — Layout2D.uv index semantics undocumented (v.idx() contract) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>Finding-U1 and Finding-U2 from doc/reviewer/usability-audit-2026-05-31.md. The existing examples (example_euclidean, example_layout, example_hyper_ideal) all used the "natural theta" pattern which makes x*=0 trivially the equilibrium — u_v ≈ 0 everywhere, no deformation. A new user following these examples saw solver output but not conformal geometry. New: example_flatten.cpp - PRIMARY USE CASE: conformally flatten a mesh to the plane - Sets Θ_v = 2π for all interior vertices (flat target) - Pins boundary vertices (no Gauss-Bonnet check for open meshes) - Demonstrates non-trivial u_v (cathead.obj: range ≈ 2.96, 5 Newton iters) - Documents the difference from "natural theta" explicitly New: example_cgal_api.cpp - Demonstrates CGAL::discrete_conformal_map_euclidean (Discrete_conformal_map.h) - First runnable CGAL public API example; contrast with internal API - Documents the "natural theta" default behaviour and explains why u_v=0 - Explains when to use CGAL API vs internal API Both examples registered in code/examples/CMakeLists.txt and compile cleanly with -DWITH_CGAL=ON. Updated: - example_euclidean.cpp: prominent "TESTING CONVENTION" warning - example_layout.cpp: same warning on set_natural_theta helper - doc/getting-started.md: example_flatten is now the recommended "start here" example; note on natural-theta behaviour added Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>U10: CLI has no parameter reference in README or getting-started.md. Documents all 7 current flags with defaults in the audit file so a future session can add the table to getting-started.md. U11: Three useful CLI gaps documented as a roadmap item: - --tol / --max-iter: Newton solver tuning, currently hardcoded - -g cp_euclidean / -g inversive_distance: Phase-9a models not reachable from CLI despite being fully implemented in the library Each item has an effort estimate (~30 min / ~2 h) and concrete acceptance criteria so a future session can pick it up cold. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>Finding-U3 from doc/reviewer/usability-audit-2026-05-31.md. Three concrete errors corrected: 1. check_gauss_bonnet() row (was: implies all map types work) → now: 'EuclideanMaps/SphericalMaps only' — HyperIdealMaps overload is = delete (compile error since external-audit Finding-B fix) 2. enforce_gauss_bonnet() row (same issue) → same restriction note added 3. newton_hyper_ideal() preconditions (was: 'lambda0 initialised') → WRONG: HyperIdeal computes lengths from b_v, a_e via zeta functions internally; lambda0 plays no role. Correct precondition: 'no lambda0 needed · no GB pre-check' → Added explanation: strictly convex energy (Springborn 2020 Thm 1.3) → Newton converges for any targets without a pre-check Gauss-Bonnet prose section also updated: - Examples now show EuclideanMaps/SphericalMaps explicitly - HyperIdeal compile-error note added with the correct hyperbolic identity Σ(2π-Θ_v) - Area = 2π·χ and why no pre-check is needed - Open-mesh note added (GB identity does not hold for boundary meshes) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>U4 (README.md:17) — status line: v0.9.0 → v0.10.0, test count 0 → 277 U5 (Discrete_conformal_map.h:6-16) — \file Doxygen block rewritten: was: 'provides a single function … Spherical/hyperbolic scheduled for Phase 8b.2' now: lists all three discrete_conformal_map_* functions already present, plus pointers to the circle-packing companion headers U7 (getting-started.md) — new 'Mode 4 — Low-memory build' section added after Mode 3; shows CONFORMALLAB_LOW_MEMORY_BUILD=ON with -j1 and explains the -O0 / no PCH / batch-1 tradeoffs for Raspberry Pi / ≤ 4 GB runners U8 (README.md compile-time modes) — LOW_MEMORY_BUILD entry added to the compile-time workflow code block with a one-line explanation and the mandatory -j1 note Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>U9 (layout.hpp + example_layout.cpp) Layout2D.uv and .halfedge_uv now have explicit Doxygen docs stating: - indexing: v.idx() / h.idx() (raw integer index) - length: mesh.number_of_vertices() / number_of_halfedges() - precondition: no vertex removal / collect_garbage() after loading - access pattern example in the doc comment example_layout.cpp: access site comment + static_cast<size_t>(v.idx()) U10 (getting-started.md) New 'CLI parameter reference' table (7 rows) added directly below the CLI usage examples; cross-references --help as the canonical source U11 (doc/roadmap/phases.md) New Phase 9h 'CLI usability extensions' section inserted before Phase 10: 9h.1 --tol / --max-iter solver-tuning params (~30 min, no deps) 9h.2 -g cp_euclidean / -g inversive_distance (~2-4 h, needs 9a ✅) Each sub-task has effort estimate, implementation sketch, and acceptance criteria so a future session can pick it up cold. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>The Pi runner (3-4 GB RAM, swap heavily loaded) OOMs when /ci-all triggers test-cgal + quality-gates + doc-build + links simultaneously: four Docker containers start at once after test-fast completes, each consuming 150-400 MB, exhausting available RAM. Fix: /ci-all removed from all three workflow files. Each keyword now triggers exactly one job — no parallel container competition. Safe workflow: one keyword per commit. Typical sequence: git commit -m 'fix: ... /test-cgal' → CGAL tests (~5 min) git commit -m 'chore: /quality-gates' → style checks (~30 s) CLAUDE.md: CI table updated with Pi-runner warning note. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>