14134b99ce
README.md: reduced from 703 to ~75 lines — what/why, status, quick start, minimal usage example, navigation table to doc/ files. doc/architecture/overall_pipeline.md: trimmed — roadmap, extension points, declarative pipeline YAML, and references sections removed (each now has its own dedicated file). Replaced with a link table. New files: doc/getting-started.md — build modes, single-test invocation, CLI doc/api/pipeline.md — full pipeline API with code for all 3 geometries doc/api/extending.md — new functionals, geometry modes, Java porting guide doc/api/contracts.md — processing unit preconditions/provides table doc/api/cgal-package.md — Phase 8 CGAL package design + YAML pipeline (TODO) doc/math/geometry-modes.md — Euclidean/Spherical/HyperIdeal comparison doc/math/references.md — all papers by module doc/roadmap/phases.md — Phases 1–10 with porting/research boundary doc/roadmap/java-parity.md — Java vs C++ feature parity table doc/contributing.md — language policy, test standards, release flow Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
164 lines
3.9 KiB
Markdown
164 lines
3.9 KiB
Markdown
# 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:
|
|
|
|
```cpp
|
|
// 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:
|
|
|
|
```yaml
|
|
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](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)
|