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>
95 lines
4.1 KiB
Markdown
95 lines
4.1 KiB
Markdown
# conformallab++
|
||
|
||
C++17 reimplementation of [ConformalLab](https://github.com/varylab/conformallab) —
|
||
Stefan Sechelmann's Java research library for discrete conformal geometry (TU Berlin).
|
||
The long-term goal is a **CGAL package** for discrete conformal maps.
|
||
|
||
Algorithmic foundation:
|
||
> Stefan Sechelmann — *Variational Methods for Discrete Surface Parameterization: Applications and Implementation*, TU Berlin 2016.
|
||
> DOI: [10.14279/depositonce-5415](https://depositonce.tu-berlin.de/items/8e2988b2-d991-45b5-aad5-9fb7988f3b2f) · CC BY-SA 4.0 ·
|
||
> [Java original](https://github.com/varylab/conformallab) · [sechel.de](https://sechel.de/)
|
||
|
||
**Status:** Phase 7 complete. Newton solver for all three geometries (Euclidean / Spherical / HyperIdeal), priority-BFS layout in ℝ²/S²/Poincaré disk, Gauss–Bonnet, tree-cotree cut graph, Möbius holonomy, period matrix (genus 1), fundamental domain, halfedge_uv texture atlas, JSON/XML serialisation, CLI app. **158 CGAL tests + 36 non-CGAL tests.**
|
||
|
||
---
|
||
|
||
## Quick start
|
||
|
||
```bash
|
||
git clone https://codeberg.org/TMoussa/ConformalLabpp && cd ConformalLabpp
|
||
|
||
# Fast tests — no system dependencies
|
||
cmake -S code -B build && cmake --build build --target conformallab_tests -j$(nproc)
|
||
ctest --test-dir build --output-on-failure
|
||
|
||
# CGAL tests headless (apt install libboost-dev / brew install boost)
|
||
cmake -S code -B build -DWITH_CGAL_TESTS=ON
|
||
cmake --build build --target conformallab_cgal_tests -j$(nproc)
|
||
ctest --test-dir build -R "^cgal\." --output-on-failure
|
||
|
||
# Full build with CLI + viewer (requires Wayland/X11 dev headers)
|
||
cmake -S code -B build -DWITH_CGAL=ON && cmake --build build -j$(nproc)
|
||
./bin/conformallab_core -i input.off -g euclidean -o layout.off -j result.json
|
||
```
|
||
|
||
---
|
||
|
||
## Minimal usage
|
||
|
||
```cpp
|
||
#include "conformal_mesh.hpp"
|
||
#include "mesh_io.hpp"
|
||
#include "euclidean_functional.hpp"
|
||
#include "gauss_bonnet.hpp"
|
||
#include "newton_solver.hpp"
|
||
#include "layout.hpp"
|
||
|
||
using namespace conformallab;
|
||
|
||
ConformalMesh mesh = load_mesh("input.off");
|
||
EuclideanMaps maps = setup_euclidean_maps(mesh);
|
||
compute_euclidean_lambda0_from_mesh(mesh, maps);
|
||
|
||
// Assign DOFs — pin first vertex (gauge fix)
|
||
auto vit = mesh.vertices().begin();
|
||
maps.v_idx[*vit++] = -1;
|
||
int idx = 0;
|
||
for (; vit != mesh.vertices().end(); ++vit) maps.v_idx[*vit] = idx++;
|
||
|
||
// Natural equilibrium target: x* = 0 by construction
|
||
std::vector<double> x0(idx, 0.0);
|
||
auto G0 = euclidean_gradient(mesh, x0, maps);
|
||
for (auto v : mesh.vertices())
|
||
if (maps.v_idx[v] >= 0) maps.theta_v[v] -= G0[maps.v_idx[v]];
|
||
|
||
check_gauss_bonnet(mesh, maps);
|
||
NewtonResult res = newton_euclidean(mesh, x0, maps);
|
||
Layout2D layout = euclidean_layout(mesh, res.x, maps);
|
||
```
|
||
|
||
---
|
||
|
||
## Documentation
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Getting started** — build modes, single-test invocation, CLI, Docker | [doc/getting-started.md](doc/getting-started.md) |
|
||
| **Pipeline API** — all three geometries, holonomy, serialisation | [doc/api/pipeline.md](doc/api/pipeline.md) |
|
||
| **Extending** — new functionals, geometry modes, porting from Java | [doc/api/extending.md](doc/api/extending.md) |
|
||
| **Processing unit contracts** — preconditions / provides table | [doc/api/contracts.md](doc/api/contracts.md) |
|
||
| **CGAL package design** — Phase 8 target, YAML pipeline | [doc/api/cgal-package.md](doc/api/cgal-package.md) |
|
||
| **Architecture & pipeline diagram** | [doc/architecture/overall_pipeline.md](doc/architecture/overall_pipeline.md) |
|
||
| **Geometry modes** — Euclidean / Spherical / HyperIdeal comparison | [doc/math/geometry-modes.md](doc/math/geometry-modes.md) |
|
||
| **References** — all papers by module | [doc/math/references.md](doc/math/references.md) |
|
||
| **Roadmap** — Phases 1–10 | [doc/roadmap/phases.md](doc/roadmap/phases.md) |
|
||
| **Java parity table** — what is ported, what is planned | [doc/roadmap/java-parity.md](doc/roadmap/java-parity.md) |
|
||
| **Contributing** — language policy, test standards, release flow | [doc/contributing.md](doc/contributing.md) |
|
||
| **Claude Code context** | [CLAUDE.md](CLAUDE.md) |
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
conformallab++ is released under the MIT License (see [LICENSE](LICENSE)).
|
||
The dissertation (Sechelmann 2016) is CC BY-SA 4.0.
|