52604d8544
doc/concepts/declarative-pipeline.md — vollständige Design-Spezifikation:
1. Kernidee: Processing Units mit expliziten require/provide-Contracts
2. Token-Vokabular: 30 Tokens in 7 Kategorien
input, setup, Gauss-Bonnet, solver, topology, layout, period/domain/output
3. YAML-Schema: Vollständige Syntax inkl. Parameterdefaults aller Units
4. Validierungsalgorithmus: monoton wachsendes provided-Set, Pre-Execution-Check
5. 5 vollständige Beispiele:
A — Euklidische Uniformisierung Torus (τ-Ausgabe)
B — Sphärische Uniformisierung (cathead.obj)
C — Hyperbolische Uniformisierung Torus (Poincaré-Disk)
D — Volle Pipeline mit Periodenmatrix + 5×5-Kachelung
E — Absichtlich fehlerhaftes Beispiel mit Validator-Fehlermeldungen
6. C++-Mapping: alle YAML-Unit-Namen → C++-Funktionen + Header
7. Implementierungsplan (Phase 8e): pipeline.hpp + CLI-App + YAML-Abhängigkeit
8. Design-Entscheidungen: YAML vs. JSON/TOML, explizit vs. auto-inference,
linear vs. DAG, eine Geometrie pro Datei
doc/api/cgal-package.md: Link zum Konzeptdokument ergänzt.
README.md: Link in Dokumentationstabelle ergänzt.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
167 lines
4.1 KiB
Markdown
167 lines
4.1 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.
|
|
|
|
**Full concept & design specification:** [doc/concepts/declarative-pipeline.md](../concepts/declarative-pipeline.md)
|
|
— token vocabulary, validation algorithm, 5 complete examples, implementation plan.
|
|
|
|
Abbreviated 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)
|