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

examples: add real conformal-flattening + CGAL-API examples (U1+U2)

Browse Source 
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>
This commit is contained in:
Tarik Moussa
2026-05-31 01:35:37 +02:00
parent fb9a15ab4a
commit 02a3745b67
7 changed files with 434 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
code/examples/CMakeLists.txt
View File

@@ -42,6 +42,22 @@ target_include_directories(example_layout SYSTEM PRIVATE ${EXAMPLE_INCLUDES})
target_include_directories(example_layout PRIVATE ${EXAMPLE_PRIVATE_INCLUDES})
target_compile_definitions(example_layout PRIVATE ${EXAMPLE_DEFS})
# ── example_flatten (primary use case: real conformal flattening) ─────────────
# Demonstrates Θ_v = 2π → non-trivial conformal map; contrast with
# example_euclidean which uses "natural theta" (u_v ≈ 0, testing trick).
add_executable(example_flatten example_flatten.cpp)
target_include_directories(example_flatten SYSTEM PRIVATE ${EXAMPLE_INCLUDES})
target_include_directories(example_flatten PRIVATE ${EXAMPLE_PRIVATE_INCLUDES})
target_compile_definitions(example_flatten PRIVATE ${EXAMPLE_DEFS})
# ── example_cgal_api (CGAL public API: one-call interface) ────────────────────
# Demonstrates CGAL::discrete_conformal_map_euclidean from
# <CGAL/Discrete_conformal_map.h>; contrast with example_flatten (internal API).
add_executable(example_cgal_api example_cgal_api.cpp)
target_include_directories(example_cgal_api SYSTEM PRIVATE ${EXAMPLE_INCLUDES})
target_include_directories(example_cgal_api PRIVATE ${EXAMPLE_PRIVATE_INCLUDES})
target_compile_definitions(example_cgal_api PRIVATE ${EXAMPLE_DEFS})
# ── example_viewer (requires WITH_VIEWER) ─────────────────────────────────────
if(WITH_VIEWER)
add_executable(example_viewer example_viewer.cpp)