02a3745b67
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>
73 lines
4.0 KiB
CMake
73 lines
4.0 KiB
CMake
# examples/CMakeLists.txt
|
|
#
|
|
# Example programs for conformallab++.
|
|
# All examples require -DWITH_CGAL=ON.
|
|
# example_viewer additionally requires -DWITH_VIEWER=ON.
|
|
#
|
|
# Run after building:
|
|
# ./build/examples/example_euclidean [input.off] [output.off]
|
|
# ./build/examples/example_hyper_ideal [input.off] [output.off]
|
|
# ./build/examples/example_viewer [input.off] (requires WITH_VIEWER)
|
|
|
|
# ── Shared include paths for all examples ─────────────────────────────────────
|
|
set(EXAMPLE_INCLUDES
|
|
${CMAKE_SOURCE_DIR}/deps/eigen-3.4.0
|
|
${CMAKE_SOURCE_DIR}/deps/CGAL-6.1.1/include
|
|
${CMAKE_SOURCE_DIR}/deps/single_includes
|
|
${Boost_INCLUDE_DIRS}
|
|
)
|
|
set(EXAMPLE_PRIVATE_INCLUDES
|
|
${CMAKE_SOURCE_DIR}/include
|
|
)
|
|
set(EXAMPLE_DEFS
|
|
CGAL_DISABLE_GMP
|
|
CGAL_DISABLE_MPFR
|
|
)
|
|
|
|
# ── example_euclidean ─────────────────────────────────────────────────────────
|
|
add_executable(example_euclidean example_euclidean.cpp)
|
|
target_include_directories(example_euclidean SYSTEM PRIVATE ${EXAMPLE_INCLUDES})
|
|
target_include_directories(example_euclidean PRIVATE ${EXAMPLE_PRIVATE_INCLUDES})
|
|
target_compile_definitions(example_euclidean PRIVATE ${EXAMPLE_DEFS})
|
|
|
|
# ── example_hyper_ideal ───────────────────────────────────────────────────────
|
|
add_executable(example_hyper_ideal example_hyper_ideal.cpp)
|
|
target_include_directories(example_hyper_ideal SYSTEM PRIVATE ${EXAMPLE_INCLUDES})
|
|
target_include_directories(example_hyper_ideal PRIVATE ${EXAMPLE_PRIVATE_INCLUDES})
|
|
target_compile_definitions(example_hyper_ideal PRIVATE ${EXAMPLE_DEFS})
|
|
|
|
# ── example_layout ───────────────────────────────────────────────────────────
|
|
add_executable(example_layout example_layout.cpp)
|
|
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)
|
|
target_include_directories(example_viewer SYSTEM PRIVATE
|
|
${EXAMPLE_INCLUDES}
|
|
${CMAKE_SOURCE_DIR}/deps/libigl-2.6.0/include
|
|
${CMAKE_SOURCE_DIR}/deps/libigl-glad/include
|
|
)
|
|
target_include_directories(example_viewer PRIVATE ${EXAMPLE_PRIVATE_INCLUDES})
|
|
target_compile_definitions(example_viewer PRIVATE ${EXAMPLE_DEFS})
|
|
target_link_libraries(example_viewer PRIVATE viewer)
|
|
endif()
|