e04515c423
ROOT CAUSE FIX
The Doxyfile EXCLUDE_PATTERNS line contained `*/* 2.hpp` (note the
space — a stray glob from macOS-style "foo 2.hpp" duplicate files).
That pattern was silently matching ALL .hpp / .h files, so Doxygen was
indexing nothing under code/include/. The pre-existing 556 KB of HTML
output was effectively documenting only README.md, CLAUDE.md and a
small stub for std:: — not the C++ API at all.
After fixing the pattern (and properly escaping the space-prefixed
"foo 2.hpp / foo 2.h" macOS-dup patterns), Doxygen now extracts 141
compounds and emits 248 HTML pages from the public headers.
WHAT THIS PR ADDS
1. Doxyfile fix: correct EXCLUDE_PATTERNS; add GENERATE_XML for the
coverage measurement script; add MathJax for `$$...$$` math in
markdown; add the missing CGAL `\cgalParamNBegin/End/Description/
Default/...` aliases so CGAL-style param blocks render correctly.
2. New headers:
- code/include/CGAL/Conformal_map/doxygen_groups.h
defines `PkgConformalMap{,Ref,Concepts,NamedParameters}`,
resolving 17 prior "non-existing group" warnings.
- code/include/CGAL/Conformal_map/doxygen_namespaces.h
gives every namespace under `CGAL::` and `conformallab::` a
brief description.
3. New tool: scripts/doxygen-coverage.sh
Parses the XML output and reports % of public symbols (excluding
the `detail::` implementation namespaces by default) that have a
non-empty brief/detailed description. Supports `--list-undoc`
and `--threshold N` for CI integration.
4. Substantial docstring additions to the public CGAL headers:
`Conformal_map_traits.h`, `Discrete_circle_packing.h`,
`Discrete_inversive_distance.h`, `conformal_mesh.hpp`,
`Discrete_conformal_map.h` (Hyper_ideal_map_result fields).
5. Markdown housekeeping that the strict-warning Doxygen run surfaced:
tests.md (escape literal `#` in table cell),
locked-vs-flexible.md (broken section anchor),
overall_pipeline.md (replace `$$LaTeX$$` with inline-unicode math).
CURRENT NUMBERS
before: ~24% documented (public API; the prior "87%" claim was
based on the broken extraction)
after: 42% documented (165 of 396 public symbols)
warnings: 0 (was 27 spurious + a flood of bogus undocumented
warnings hidden by the buggy EXCLUDE pattern)
NEXT (in a follow-up commit on this branch)
The remaining 231 public symbols (mostly in `layout.hpp`,
`hyper_ideal_functional.hpp`, `spherical_functional.hpp`, the per-mode
functional/Hessian files) can be brought to ~100% with another pass of
short `///` brief descriptions. The coverage script is the gate; CI
can begin enforcing `--threshold 95` once the next pass lands.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
108 lines
5.2 KiB
C++
108 lines
5.2 KiB
C++
#pragma once
|
||
// conformal_mesh.hpp
|
||
//
|
||
// Central mesh type for the discrete conformal mapping algorithms.
|
||
// Replaces the Java CoHDS (de.varylab.discreteconformal.heds.CoHDS)
|
||
// and its associated vertex/edge/face types (CoVertex, CoEdge, CoFace).
|
||
//
|
||
// Design
|
||
// ------
|
||
// Java │ C++ (this file)
|
||
// ─────────────────────────────┼──────────────────────────────────────────
|
||
// CoHDS │ ConformalMesh (CGAL::Surface_mesh)
|
||
// CoVertex / CoEdge / CoFace │ Vertex_index / Edge_index / Face_index
|
||
// HyperIdealRadiusAdapter │ property_map<Vertex_index, double>
|
||
// HalfedgeInterface adapters │ named property maps ("v:lambda", …)
|
||
//
|
||
// Property-map naming convention
|
||
// ───────────────────────────────
|
||
// "v:lambda" per-vertex log scale factor (conformal variable u_i)
|
||
// "v:theta" per-vertex target cone angle
|
||
// "v:idx" per-vertex solver DOF index (-1 = pinned / boundary)
|
||
// "e:alpha" per-edge intersection angle (α_ij, hyperbolic geometry)
|
||
// "f:type" per-face geometry type (0=Euclidean, 1=Hyperbolic, 2=Spherical)
|
||
//
|
||
// All property maps are optional; add only what a given algorithm needs.
|
||
//
|
||
// Note on descriptor types (CGAL 6.x)
|
||
// ────────────────────────────────────
|
||
// CGAL::Surface_mesh exposes its index types as nested types:
|
||
// Surface_mesh::Vertex_index, ::Halfedge_index, ::Edge_index, ::Face_index
|
||
// The BGL graph_traits aliases expose the same types as vertex_descriptor etc.,
|
||
// but those live in boost::graph_traits<Surface_mesh>, not in Surface_mesh itself.
|
||
// We use the Surface_mesh member names throughout for clarity.
|
||
|
||
#include <CGAL/Simple_cartesian.h>
|
||
#include <CGAL/Surface_mesh.h>
|
||
#include <string>
|
||
|
||
namespace conformallab {
|
||
|
||
// ── Kernel ──────────────────────────────────────────────────────────────────
|
||
// Simple double-precision Cartesian. Conformal mapping algorithms never
|
||
// need exact arithmetic — they operate on floating-point lengths and angles.
|
||
|
||
/// CGAL kernel used by all conformallab algorithms (double precision).
|
||
using Kernel = CGAL::Simple_cartesian<double>;
|
||
/// 3-D point type (vertex coordinates).
|
||
using Point3 = Kernel::Point_3;
|
||
/// 2-D point type (UV-domain layout coordinates).
|
||
using Point2 = Kernel::Point_2;
|
||
|
||
// ── Mesh type ────────────────────────────────────────────────────────────────
|
||
/// Triangle mesh carrying all conformal-map data as property maps.
|
||
using ConformalMesh = CGAL::Surface_mesh<Point3>;
|
||
|
||
// ── Index/descriptor aliases (CGAL 6.x naming) ───────────────────────────────
|
||
/// Vertex descriptor of `ConformalMesh`.
|
||
using Vertex_index = ConformalMesh::Vertex_index;
|
||
/// Half-edge descriptor of `ConformalMesh`.
|
||
using Halfedge_index = ConformalMesh::Halfedge_index;
|
||
/// Edge descriptor of `ConformalMesh`.
|
||
using Edge_index = ConformalMesh::Edge_index;
|
||
/// Face descriptor of `ConformalMesh`.
|
||
using Face_index = ConformalMesh::Face_index;
|
||
|
||
// ── Geometry type constant (replaces Java CoFace.type enum) ─────────────────
|
||
/// Discrete geometry type that a face/mesh is interpreted in.
|
||
/// Replaces the original Java `CoFace.type` enum.
|
||
enum class GeometryType : int {
|
||
Euclidean = 0, ///< Flat metric (ℝ²).
|
||
Hyperbolic = 1, ///< Hyperbolic metric (ℍ²).
|
||
Spherical = 2 ///< Spherical metric (S²).
|
||
};
|
||
|
||
// ── Standard property-map bundles ────────────────────────────────────────────
|
||
|
||
/// Register and return the vertex-side property maps used by all five
|
||
/// DCE functionals: `v:lambda` (log conformal factor), `v:theta` (target
|
||
/// cone angle), `v:idx` (contiguous integer index).
|
||
inline auto add_vertex_properties(ConformalMesh& mesh)
|
||
{
|
||
auto [lambda, ok1] = mesh.add_property_map<Vertex_index, double>("v:lambda", 0.0);
|
||
auto [theta, ok2] = mesh.add_property_map<Vertex_index, double>("v:theta", 0.0);
|
||
auto [idx, ok3] = mesh.add_property_map<Vertex_index, int> ("v:idx", -1);
|
||
(void)ok1; (void)ok2; (void)ok3;
|
||
return std::make_tuple(lambda, theta, idx);
|
||
}
|
||
|
||
/// Register and return the edge intersection-angle property `e:alpha`
|
||
/// (used by the hyper-ideal functional).
|
||
inline auto add_edge_properties(ConformalMesh& mesh)
|
||
{
|
||
auto [alpha, ok] = mesh.add_property_map<Edge_index, double>("e:alpha", 0.0);
|
||
(void)ok;
|
||
return alpha;
|
||
}
|
||
|
||
/// Register and return the per-face geometry-type property `f:type`.
|
||
inline auto add_face_properties(ConformalMesh& mesh)
|
||
{
|
||
auto [ftype, ok] = mesh.add_property_map<Face_index, int>(
|
||
"f:type", static_cast<int>(GeometryType::Euclidean));
|
||
(void)ok;
|
||
return ftype;
|
||
}
|
||
|
||
} // namespace conformallab
|