f6722d7e84
Replaces the hand-maintained `doc/api/headers.md` with a generated one
sourced from each header's `\file` brief and the public symbols
extracted by Doxygen into XML. The CI workflow regenerates it on every
push to main that touches the public headers.
New files
─────────
* scripts/gen-headers-md.py — parses doc/doxygen/xml/*.xml, groups
headers by directory (CGAL public / CGAL internals / Core), and
writes a markdown table with header path, first-sentence brief, and
the public symbols declared at file scope. Skips `detail::`
namespaces and template-specialisation duplicates.
* scripts/regen-docs.sh — convenience wrapper:
doxygen → gen-headers-md.py → coverage report.
Workflow changes
────────────────
.gitea/workflows/doxygen-pages.yml now:
1. Runs `bash scripts/doxygen-coverage.sh` as an informational step
(no fail threshold yet — the script supports `--threshold N` for
when we're ready).
2. Re-runs `python3 scripts/gen-headers-md.py` and warns if the
file drifted from what's in main (operator should run
`regen-docs.sh` locally before pushing).
Doxyfile hygiene
────────────────
`HTML_TIMESTAMP` was removed in Doxygen 1.10 → replaced with the new
`TIMESTAMP = NO` to silence the obsolete-tag warning.
Effect on the reviewer-facing landing pages
───────────────────────────────────────────
Every improvement to a `\file` brief at the top of a public header now
flows automatically into both:
* the Doxygen HTML at https://tmoussa.codeberg.page/ConformalLabpp/
* the markdown landing at doc/api/headers.md (rendered by Codeberg
in the repo view)
…so writers have a single source of truth (the C++ source) and
readers see the same words in both surfaces.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
6.7 KiB
6.7 KiB
Public Headers (code/include/)
All algorithms are header-only. Include the headers you need directly — there is no compiled library to link against (only GTest for tests and CGAL/Eigen for the CGAL-dependent headers).
This page is regenerated from Doxygen XML on every push to
main that touches a public header (see
.gitea/workflows/doxygen-pages.yml and scripts/gen-headers-md.py).
To improve a description, edit the \file brief at the top of
the corresponding header, then re-run bash scripts/regen-docs.sh.
CGAL public API (<CGAL/...>)
| Header | Brief | Public symbols |
|---|---|---|
CGAL/Conformal_layout.h |
Thin CGAL-style wrapper around the legacy euclidean_layout(), spherical_layout() and hyper_ideal_layout() functions defined in code/include/layout.hpp. | Layout2D, Layout3D, HolonomyData, CutGraph |
CGAL/Conformal_map_traits.h |
Defines the ConformalMapTraits concept and the default model Default_conformal_map_traits<TriangleMesh, K> for the package. | (no public symbols) |
CGAL/Discrete_circle_packing.h |
User-facing entry for the face-based circle-packing functional of Bobenko-Pinkall-Springborn 2010. | Circle_packing_result |
CGAL/Discrete_conformal_map.h |
User-facing entry point for the Discrete_conformal_map package. | Conformal_map_result, Hyper_ideal_map_result |
CGAL/Discrete_inversive_distance.h |
User-facing entry for the vertex-based inversive-distance circle- packing functional of Luo (2004), with the Bowers-Stephenson (2004) initialisation. | (no public symbols) |
CGAL internals (<CGAL/Conformal_map/...>)
| Header | Brief | Public symbols |
|---|---|---|
CGAL/Conformal_map/doxygen_groups.h |
Copyright (c) 2024-2026 Tarik Moussa. | (no public symbols) |
CGAL/Conformal_map/doxygen_namespaces.h |
Copyright (c) 2024-2026 Tarik Moussa. | (no public symbols) |
CGAL/Conformal_map/internal/parameters.h |
Copyright (c) 2024-2026 Tarik Moussa. | (no public symbols) |
Core (conformallab namespace, <...>)
| Header | Brief | Public symbols |
|---|---|---|
clausen.hpp |
Clausen integral, Lobachevsky function, and Im(Li2). | (no public symbols) |
conformal_mesh.hpp |
conformal_mesh.hpp Central mesh type for the discrete conformal mapping algorithms. | (no public symbols) |
constants.hpp |
constants.hpp Single source of truth for mathematical constants used throughout conformallab++. | (no public symbols) |
cp_euclidean_functional.hpp |
cp_euclidean_functional.hpp Phase 9a.1 — Circle-Packing Euclidean functional (CP-Euclidean). | CPEuclideanMaps |
cut_graph.hpp |
cut_graph.hpp Phase 6 — Tree-cotree algorithm for computing a cut graph of a triangulated surface. | CutGraph |
discrete_elliptic_utility.hpp |
Ported from de.varylab.discreteconformal.util.DiscreteEllipticUtility (Java). | (no public symbols) |
euclidean_functional.hpp |
euclidean_functional.hpp Energy and gradient of the Euclidean discrete conformal functional (EuclideanCyclicFunctional) evaluated on a ConformalMesh. | EuclideanMaps, EuclideanResult |
euclidean_geometry.hpp |
euclidean_geometry.hpp Corner-angle formula for Euclidean triangles in the discrete conformal (log-length) parametrisation. | EuclideanFaceAngles |
euclidean_hessian.hpp |
euclidean_hessian.hpp Analytical Hessian of the Euclidean discrete conformal energy — the cotangent-Laplace operator. | EuclCotWeights |
fundamental_domain.hpp |
fundamental_domain.hpp Phase 7 — Fundamental domain polygon for closed surfaces. | FundamentalDomain |
gauss_bonnet.hpp |
gauss_bonnet.hpp Phase 6 — Gauss–Bonnet consistency check for prescribed target angles. | (no public symbols) |
hyper_ideal_functional.hpp |
hyper_ideal_functional.hpp Energy and gradient of the hyper-ideal discrete conformal map functional evaluated on a ConformalMesh (CGAL::Surface_mesh). | HyperIdealMaps, HyperIdealResult, FaceAngleOutputs, FaceAngles |
hyper_ideal_geometry.hpp |
hyper_ideal_geometry.hpp Pure-math building blocks for the hyper-ideal discrete conformal map. | (no public symbols) |
hyper_ideal_hessian.hpp |
hyper_ideal_hessian.hpp Phase 4a — Hessian of the hyper-ideal discrete conformal functional. | (no public symbols) |
hyper_ideal_utility.hpp |
Hyperbolic tetrahedron volume formulas. | (no public symbols) |
hyper_ideal_visualization_utility.hpp |
Port of the static helper HyperIdealVisualizationPlugin.getEuclideanCircleFromHyperbolic() from de.varylab.discreteconformal.plugin. | (no public symbols) |
inversive_distance_functional.hpp |
inversive_distance_functional.hpp Phase 9a.2 — Inversive-distance circle-packing functional (Luo 2004). | InversiveDistanceMaps |
layout.hpp |
layout.hpp Phase 5/6/7 — Layout / embedding: DOF vector → vertex coordinates in the target geometry via BFS-trilateration. | MobiusMap, Layout2D, Layout3D, HolonomyData |
matrix_utility.hpp |
4x4 mapping matrix from corresponding point pairs. | (no public symbols) |
mesh_builder.hpp |
mesh_builder.hpp Factory functions that build simple reference meshes for testing and examples. | (no public symbols) |
mesh_io.hpp |
mesh_io.hpp Phase 4b — CGAL::IO wrappers for ConformalMesh. | (no public symbols) |
mesh_utils.hpp |
mesh_utils.hpp Conversions between CGAL::Surface_mesh and Eigen matrices. | (no public symbols) |
newton_solver.hpp |
newton_solver.hpp Phase 4a — Newton solver for all three discrete conformal functionals. | NewtonResult |
p2_utility.hpp |
2-D projective geometry utilities for the Euclidean signature. | (no public symbols) |
period_matrix.hpp |
period_matrix.hpp Phase 7 — Period matrix for closed surfaces with Euclidean (flat) metric. | PeriodData |
projective_math.hpp |
Projective and hyperbolic geometry utilities. | (no public symbols) |
serialization.hpp |
serialization.hpp Phase 5 — Save and load conformal map results in JSON and XML formats. | (no public symbols) |
spherical_functional.hpp |
spherical_functional.hpp Energy and gradient of the spherical discrete conformal functional evaluated on a ConformalMesh (CGAL::Surface_mesh). | SphericalMaps, SphericalResult |
spherical_geometry.hpp |
spherical_geometry.hpp Pure-math building blocks for the spherical discrete conformal map. | SphericalFaceAngles |
spherical_hessian.hpp |
spherical_hessian.hpp Analytical Hessian of the spherical discrete conformal energy — the spherical cotangent-Laplace operator. | SpherCotWeights |
viewer_utils.h |
(undocumented — add a \file brief at the top of the header) |
(no public symbols) |