docs: restructure documentation into focused files
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>
This commit is contained in:
Tarik Moussa
@@ -388,177 +388,14 @@ Normalise PCA centring Rodrigues to N pole weighted Möbius centrin
|
||||
|
||||
---
|
||||
|
||||
## Extension points
|
||||
## Further documentation
|
||||
|
||||
### Adding a new functional
|
||||
|
||||
1. Create `my_functional.hpp` with a `Maps` struct and `evaluate_my_functional()`.
|
||||
2. The gradient must satisfy: `G_v = Σ(angle contributions) − theta_v[v]`.
|
||||
3. Verify with a finite-difference gradient check (copy any `GradientCheck_*` test).
|
||||
4. Pass to `solve_linear_system(H, -G)` or write a thin `newton_my` wrapper.
|
||||
|
||||
### Adding a new geometry mode
|
||||
|
||||
Implement `trilaterate_my()` with the correct local placement formula,
|
||||
then follow the same BFS structure as `euclidean_layout` (see `layout.hpp`).
|
||||
The priority BFS, holonomy tracking, and `halfedge_uv` population are geometry-agnostic.
|
||||
|
||||
### Adding a new processing unit
|
||||
|
||||
Declare its preconditions and capabilities explicitly (see table above).
|
||||
The pipeline validation is currently manual (documented contracts); a
|
||||
compile-time or runtime check is a natural Phase 8 extension.
|
||||
|
||||
---
|
||||
|
||||
## Declarative pipeline (target for Phase 8)
|
||||
|
||||
A lightweight YAML description for reproducible experiments:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Each unit declares `require` (preconditions) and `provide` (capabilities).
|
||||
A pipeline is valid if for every step, all `require` keys are satisfied by the
|
||||
accumulated `provide` set of all preceding steps.
|
||||
This mirrors exactly the contract table in this document.
|
||||
|
||||
---
|
||||
|
||||
## Development Roadmap
|
||||
|
||||
> **Grenze Portierung / neue Forschung:**
|
||||
> Phase 1–7 sind direkte Portierungen aus dem Java-Original (Sechelmann 2016).
|
||||
> Ab Phase 8 geht die Arbeit über den Umfang der Java-Bibliothek hinaus.
|
||||
> — Phase 8 (CGAL-Paket) ist **Infrastruktur**, kein neuer Algorithmus.
|
||||
> — Phase 9 (Inversive-Distance, Analytischer Hessian, 4g-Polygon) ist **Portierung** ausstehender Java-Features.
|
||||
> — Phase 10+ ist **eigenständige Forschung**, die über das Java-Original hinausgeht.
|
||||
|
||||
---
|
||||
|
||||
### ◼ Portierungsphase abgeschlossen — Phase 1–7
|
||||
|
||||
```
|
||||
Phase 1 Clausen / Lobachevsky / ImLi₂ ✅
|
||||
Phase 2 Hyper-ideal Geometrie (ζ, lᵢⱼ, αᵢⱼ, σᵢ) ✅
|
||||
Phase 3 CGAL-Infrastruktur + alle drei Funktionale (E/S/H) ✅
|
||||
Phase 4 Newton-Solver (SimplicialLDLT + SparseQR-Fallback) ✅ 68 Tests
|
||||
Phase 5 Priority-BFS-Layout + CLI + JSON/XML ✅ 95 Tests
|
||||
Phase 6 Gauss–Bonnet, Tree-Cotree-Schnittgraph, Normalisierung ✅ 121 Tests
|
||||
Phase 7 MobiusMap, halfedge_uv, Möbius-Holonomie, Periodenmatrix,
|
||||
Fundamentalbereich (Genus 1), Java-Parität abgeschlossen ✅ 158 Tests
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ◼ Infrastruktur (über Java-Bibliothek hinaus) — Phase 8: CGAL-Paket
|
||||
|
||||
```
|
||||
8a Traits-Klasse & Konzepte → include/CGAL/Conformal_map_traits.h
|
||||
8b Öffentliche CGAL-Header-Hierarchie → include/CGAL/Discrete_conformal_map.h etc.
|
||||
8c Dokumentation im CGAL-Stil → doc/Conformal_map/PackageDescription.txt
|
||||
8d CGAL-Testformat → test/Conformal_map/
|
||||
8e Declarative YAML-Pipeline → pipeline validator (require/provide tokens)
|
||||
```
|
||||
|
||||
See the [Declarative pipeline](#declarative-pipeline-target-for-phase-8) section above
|
||||
for the YAML schema that Phase 8e will validate at runtime.
|
||||
|
||||
---
|
||||
|
||||
### ◼ Ausstehende Portierung (Java-Features noch nicht übertragen) — Phase 9
|
||||
|
||||
```
|
||||
9a Inversive-Distance-Funktional (Luo 2004)
|
||||
→ InversiveDistanceMaps + functional + Hessian
|
||||
→ discrete uniformization via inversive distances
|
||||
9b Analytischer HyperIdeal-Hessian (ζ-Kette)
|
||||
→ replace FD Hessian in hyper_ideal_hessian.hpp
|
||||
→ reduces Newton iterations for large meshes
|
||||
9c 4g-Polygon-Randlauf (Genus g > 1)
|
||||
→ extend compute_fundamental_domain() beyond genus 1
|
||||
→ algorithm outline already in fundamental_domain.hpp as TODO(Phase 9)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ◼ Neue Forschung (über das Java-Original hinaus) — Phase 10+
|
||||
|
||||
```
|
||||
Phase 10 Globale Uniformisierung Genus g ≥ 2
|
||||
10a Holomorphe Differentiale auf diskreten Flächen
|
||||
→ discrete harmonic 1-forms; integration along cut graph cycles
|
||||
10b Siegel-Periodenmatrix Ω ∈ H_g (g×g komplex-symmetrisch, Im(Ω) > 0)
|
||||
→ extend compute_period_matrix() to genus g ≥ 2
|
||||
→ requires holomorphic differentials from 10a
|
||||
10c Vollständige Uniformisierung
|
||||
→ uniformize arbitrary genus-g surface to canonical constant-curvature metric
|
||||
→ depends on 10a + 10b
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Recommended reading
|
||||
|
||||
### Primary source — the dissertation this library implements
|
||||
|
||||
| | |
|
||||
| Topic | Document |
|
||||
|---|---|
|
||||
| **Sechelmann** — *Variational Methods for Discrete Surface Parameterization: Applications and Implementation*, TU Berlin 2016 | The mathematical foundation of the entire library: discrete conformal equivalence, variational angle-sum functionals, Newton solver, uniformization, period matrices. DOI: [10.14279/depositonce-5415](https://depositonce.tu-berlin.de/items/8e2988b2-d991-45b5-aad5-9fb7988f3b2f) |
|
||||
| **Java original** — [github.com/varylab/conformallab](https://github.com/varylab/conformallab) | Reference implementation in Java — the direct source for all algorithms ported to C++ |
|
||||
|
||||
### Further references
|
||||
|
||||
| Source | Relevance in conformallab++ |
|
||||
|--------|----------------------------|
|
||||
| Springborn — *Ideal Hyperbolic Polyhedra and Discrete Uniformization* (2020) | HyperIdeal functional; ζ₁₃/ζ₁₄/ζ₁₅ in `hyper_ideal_geometry.hpp` |
|
||||
| Pinkall, Polthier — *Computing Discrete Minimal Surfaces* (1993) | Cotangent-Laplace Hessian in `euclidean_hessian.hpp` |
|
||||
| Bobenko, Springborn — *Variational Principles for Circle Patterns* (2004) | Angle-sum variational framework used throughout |
|
||||
| Luo — *Combinatorial Yamabe Flow on Surfaces* (2004) | Inversive-distance functional (not yet ported) |
|
||||
| Erickson, Whittlesey — *Greedy Optimal Homotopy Generators* (SODA 2005) | Tree-cotree algorithm in `cut_graph.hpp` |
|
||||
| Extending the library (new functionals, geometry modes, Java porting guide) | [api/extending.md](../api/extending.md) |
|
||||
| Processing unit contracts (preconditions / provides table) | [api/contracts.md](../api/contracts.md) |
|
||||
| Phase 8 CGAL package design + declarative pipeline YAML | [api/cgal-package.md](../api/cgal-package.md) |
|
||||
| Three geometry modes in detail | [math/geometry-modes.md](../math/geometry-modes.md) |
|
||||
| References and papers | [math/references.md](../math/references.md) |
|
||||
| Development roadmap (Phases 1–10) | [roadmap/phases.md](../roadmap/phases.md) |
|
||||
| Java vs. C++ feature parity table | [roadmap/java-parity.md](../roadmap/java-parity.md) |
|
||||
|
||||
Reference in New Issue
Block a user