ConformalLabpp/doc/api/cgal-package.md

Phase 8 — CGAL Package Design

Status: planned. This document describes the target architecture for Phase 8. No code has been written yet. The design is informed by the CGAL package submission guidelines at https://www.cgal.org/developers.html

---

Goal

Integrate conformallab++ into the CGAL library as a proper CGAL package: Discrete_conformal_map. The package must satisfy all CGAL submission requirements: traits-class design, Doxygen documentation, CGAL-format test suite, and coverage of the CGAL coding conventions.

---

8a — Traits class & concepts

The current code is tightly coupled to CGAL::Surface_mesh<Point3>. Phase 8a introduces a traits class that separates the mesh type from the algorithm:

// TODO(Phase 8a): implement this header
// include/CGAL/Conformal_map_traits.h

template<
    typename MeshType,      // any CGAL halfedge mesh
    typename KernelType,    // CGAL kernel
    typename ScalarType = double
>
struct Conformal_map_traits {
    using Mesh   = MeshType;
    using Kernel = KernelType;
    using FT     = ScalarType;
    // ... vertex/edge/face descriptor types
    // ... property map access
};

Concept checks will ensure any user-provided mesh satisfies the halfedge mesh concept.

---

8b — Public header hierarchy

A clean public API separate from the internal implementation:

include/CGAL/
  Discrete_conformal_map.h        ← single user-facing include
  Conformal_map_traits.h
  Conformal_newton_solver.h
  Conformal_layout.h
  Conformal_cut_graph.h
  conformal_map_package.h         ← PackageDescription

All existing include/*.hpp headers remain as internal implementation details, not part of the public CGAL API.

---

8c — CGAL-style documentation

doc/Conformal_map/
  PackageDescription.txt
  User_manual.md
  Reference_manual.md
  fig/                            ← pipeline diagrams, mathematical figures

All public functions and concepts require Doxygen comments following the CGAL style.

---

8d — CGAL test format

test/Conformal_map/
  CMakeLists.txt                  ← CGAL-format, uses find_package(CGAL)
  test_euclidean_functional.cpp
  test_newton_solver.cpp
  ...

The existing GTest suite remains. CGAL-format tests are added alongside as a separate target, following the CGAL test infrastructure conventions.

---

8e — Declarative YAML pipeline

A lightweight YAML format for reproducible experiments. The CLI accepts --pipeline experiment.yml; the validator checks require/provide tokens before execution.

Example:

pipeline:
  name: flat_torus_period
  geometry: euclidean

  input:
    source: data/torus.off

  steps:
    - id: setup
      unit: setup_euclidean_maps
      provide: [maps_initialised]

    - id: gauss_bonnet
      unit: enforce_gauss_bonnet
      require: [maps_initialised]
      provide: [gauss_bonnet_satisfied]

    - id: solve
      unit: newton_euclidean
      require: [gauss_bonnet_satisfied]
      params:
        tol: 1.0e-10
        max_iter: 200
      provide: [x_converged]

    - id: cut
      unit: compute_cut_graph
      require: [mesh_closed]
      provide: [cut_graph]

    - id: layout
      unit: euclidean_layout
      require: [x_converged, cut_graph]
      params:
        normalise: true
      provide: [layout_uv, holonomy]

    - id: period
      unit: compute_period_matrix
      require: [holonomy]
      provide: [tau]

  output:
    layout: out/torus_layout.off
    json:   out/torus_result.json
    tau:    out/torus_tau.txt

The contract table in contracts.md defines the valid require/provide token vocabulary.

---

TODO

• Design Conformal_map_traits.h interface (8a)
• Define concept requirements for MeshType (8a)
• Create include/CGAL/ header skeleton (8b)
• Write PackageDescription.txt (8c)
• Port GTest tests to CGAL format (8d)
• Implement YAML validator (8e)
• CLI: --pipeline flag (8e)