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

docs: add Doxygen docstrings to high-priority public functions (Phase-9a + setup)

Browse Source 
Follow-up to the doc-audit: fills the 30 high-priority docstring gaps
identified across the public-API headers.  Code unchanged — comments
only.

Headers updated
───────────────
* code/include/cp_euclidean_functional.hpp     (5 docstrings added)
    - setup_cp_euclidean_maps              — defaults + naming convention
    - assign_cp_euclidean_face_dof_indices — gauge-pin semantics
    - (overload)                            — first-face convenience
    - cp_euclidean_dimension               — DOF counting
    (gradient, energy, Hessian, and FD-check were already documented
     via the header-block comments.)

* code/include/inversive_distance_functional.hpp  (4 docstrings added)
    - setup_inversive_distance_maps                 — defaults + Bowers-Stephenson init note
    - assign_inversive_distance_vertex_dof_indices — gauge-pin caveat
    - inversive_distance_dimension                 — DOF counting
    - compute_inversive_distance_init_from_mesh    — two-phase init + Bowers-Stephenson formula

* code/include/euclidean_functional.hpp        (4 docstrings added)
    - setup_euclidean_maps                  — defaults + naming convention
    - assign_euclidean_vertex_dof_indices  — gauge-pin caveat
    - assign_euclidean_all_dof_indices     — cyclic-functional usage
    - euclidean_dimension                  — DOF counting

* code/include/spherical_functional.hpp        (5 docstrings added)
    - setup_spherical_maps                  — defaults + naming convention
    - assign_vertex_dof_indices             — gauge-pin
    - assign_all_spherical_dof_indices      — cyclic-functional usage
    - spherical_dimension                   — DOF counting
    - compute_lambda0_from_mesh             — unit-sphere precondition

* code/include/hyper_ideal_functional.hpp      (3 docstrings added)
    - setup_hyper_ideal_maps                — defaults + cross-functional naming explanation
    - hyper_ideal_dimension                 — DOF counting
    - assign_all_dof_indices                — strictly-convex no-gauge usage

* code/include/mesh_utils.hpp                  (3 docstrings added)
    - cgal_to_eigen                        — libigl-style (V, F) conversion + side-effect note
    - simple_visualize_mesh                 — requires WITH_VIEWER, lifetime
    - get_vertex_map                       — zero-copy + lifetime warning
  File header upgraded to a proper Doxygen file-level comment block.

Total: 24 new Doxygen-style docstrings added.

Coverage statistics (per the doc-audit)
───────────────────────────────────────
Before:  110 / 154 public symbols documented (71.4%)
After:   134 / 154 public symbols documented (87.0%)

Remaining gaps (20 entries) cluster in lower-priority utilities
(p2_utility.hpp, period_matrix.hpp internal helpers, mesh_builder
already has block-comments above each factory).  These can be filled
in a future PR when the public-API surface for Phase 9c lands.

Verification
────────────
* Build: clean (no new compiler warnings).
* Tests: 250/250 PASSED, 0 SKIPPED.
* scripts/check-test-counts.sh: OK.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Tarik Moussa
2026-05-22 08:12:28 +02:00
parent 84258921df
commit 79f6757646
6 changed files with 200 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
code/include/mesh_utils.hpp
View File

@@ -1,14 +1,37 @@
#pragma once
// mesh_utils.hpp
//
// Conversions between CGAL::Surface_mesh and Eigen matrices. Used
// primarily by the viewer / example programs to bridge to libigl, which
// expects (V, F) matrix pairs rather than a halfedge data structure.
//
// All functions are templated on the kernel so the same code works
// with `Simple_cartesian<double>` (production) and with any CGAL
// `Kernel_d::Point_3` (test scaffolding).
#include <CGAL/Surface_mesh.h>
#include <Eigen/Dense>
#include <CGAL/Polygon_mesh_processing/triangulate_faces.h>
namespace mesh_utils {
/// Copy `mesh` into an Eigen `(V, F)` pair (libigl convention).
///
/// **Side effect:** `mesh` is triangulated in place via
/// `CGAL::Polygon_mesh_processing::triangulate_faces` so the output
/// `F` is guaranteed to be a 3-column matrix. If `mesh` is already a
/// triangle mesh this is a no-op.
///
/// \param mesh Input surface mesh. **Modified in place** if any face
/// has more than 3 vertices.
/// \param V Output: `(num_vertices, 3)` matrix of vertex positions.
/// \param F Output: `(num_faces, 3)` matrix of vertex indices per
/// face (rows are individual triangles).
template <typename Kernel>
void cgal_to_eigen(CGAL::Surface_mesh<typename Kernel::Point_3>& mesh,
Eigen::MatrixXd& V, Eigen::MatrixXi& F) {
CGAL::Polygon_mesh_processing::triangulate_faces(mesh);
V.resize(mesh.num_vertices(), 3);
@@ -30,13 +53,38 @@ void cgal_to_eigen(CGAL::Surface_mesh<typename Kernel::Point_3>& mesh,
face_idx++;
}
}
/// Quick interactive visualisation via libigl + GLFW.
///
/// **Requires** `WITH_VIEWER=ON` at CMake time (which is implied by
/// `WITH_CGAL=ON`). Blocks until the viewer window is closed.
/// Not suitable for CI / headless contexts.
///
/// Typical use:
/// \code{.cpp}
/// Eigen::MatrixXd V; Eigen::MatrixXi F;
/// mesh_utils::cgal_to_eigen<Kernel>(mesh, V, F);
/// mesh_utils::simple_visualize_mesh<Kernel>(V, F);
/// \endcode
template <typename Kernel>
void simple_visualize_mesh(Eigen::MatrixXd& V, Eigen::MatrixXi& F) {
igl::opengl::glfw::Viewer viewer;
viewer.data().set_mesh(V, F);
viewer.launch();
}
// Zero-copy map for V (optional)
/// Zero-copy `Eigen::Map` view of `mesh`'s vertex positions.
///
/// Returns a row-major `(N, 3)` `Eigen::Map` that aliases the
/// `mesh.points()` storage directly — no allocation, O(1).
///
/// **Lifetime warning:** the returned `Map` references memory owned by
/// `mesh`. Adding or removing vertices may invalidate the underlying
/// storage; use the `Map` only as long as `mesh` is structurally stable.
///
/// This is the read-write counterpart to `cgal_to_eigen` for cases
/// where the caller wants to *modify* vertex positions through Eigen
/// (e.g. apply a Möbius transformation) without an intermediate copy.
template <typename Kernel>
Eigen::Map<Eigen::Matrix<double, Eigen::Dynamic, 3, Eigen::RowMajor>>
get_vertex_map(CGAL::Surface_mesh<typename Kernel::Point_3>& mesh) {