# conformallab++ [![CI](https://git.eulernest.eu/conformallab/ConformalLabpp/actions/workflows/cpp-tests.yml/badge.svg)](https://git.eulernest.eu/conformallab/ConformalLabpp/actions) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![DOI](https://img.shields.io/badge/doi-Sechelmann%202016-blue)](https://depositonce.tu-berlin.de/items/8e2988b2-d991-45b5-aad5-9fb7988f3b2f) [![API docs](https://img.shields.io/badge/API%20docs-Doxygen-orange)](https://tmoussa.codeberg.page/ConformalLabpp/) 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:** v0.10.0 — Phases 1–9b complete, Phase 8b-Lite CGAL API surface. Newton solvers for **five** DCE models (Euclidean / Spherical / HyperIdeal / CP-Euclidean / Inversive-Distance), 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. 277 tests passing, 0 skipped — see [`doc/api/tests.md`](doc/api/tests.md) for the per-suite breakdown. --- ## 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) # Conformal flattening (Θ_v = 2π target). Closed meshes pin one vertex + # enforce Gauss-Bonnet; open meshes pin the boundary and flatten the interior. ./bin/conformallab_core -i code/data/off/torus_8x8.off -g euclidean -v \ -o layout.off -j result.json # topology: closed, free DOFs=63, genus=1 # Euclidean: converged=yes iter=3 |grad|_inf≈5e-15 ./bin/conformallab_core -i code/data/obj/cathead.obj -g euclidean -v -o cat.off # topology: open (boundary pinned), free DOFs=119 # Euclidean: converged=yes iter=4 # API documentation (requires doxygen: brew/apt install doxygen) cmake --build build --target doc open doc/doxygen/html/index.html ``` ### Compile-time workflow modes The default build (PCH + Unity Build + Dense→Core trims) takes ~47 s clean for the full CGAL test target. Five opt-in modes cover other iteration scenarios: ```bash # Configure-only, no compile. ~1 s configure, 0 s build — emits # compile_commands.json for IDE / clangd; skips the GTest fetch. cmake -S code -B build -DBUILD_TESTING=OFF # Header smoke check: per-public-header isolated compile. ~12 s full, # ~0.1 s after touching one header. "Does my refactor still parse?" cmake -S code -B build -DBUILD_TESTING=OFF -DCONFORMALLAB_HEADERS_CHECK=ON cmake --build build --target headers_check # Dev iteration: PCH on, Unity off. Slower full build (~75 s) but # editing a single test rebuilds in ~16 s instead of ~46 s. cmake -S code -B build -DWITH_CGAL_TESTS=ON -DCONFORMALLAB_DEV_BUILD=ON # Fast CI tests: -O0 -g for the test executables only (library / # install targets keep -O3). Linux + g++ typically ~40 % faster # build at the cost of 5–15× slower test RUN. Neutral on macOS. cmake -S code -B build -DWITH_CGAL_TESTS=ON -DCONFORMALLAB_FAST_TEST_BUILD=ON # Low-memory build: -O0, no PCH, unity batch 1, --no-keep-memory linker. # Drops cc1plus peak from ~700 MB to ~150 MB per TU. Use on Raspberry Pi # or any runner with ≤ 4 GB RAM. Always build with -j1. cmake -S code -B build -DWITH_CGAL_TESTS=ON -DCONFORMALLAB_LOW_MEMORY_BUILD=ON cmake --build build --target conformallab_cgal_tests -j1 # Pristine measurement: disable both performance levers, e.g. for # scripts/quality/coverage.sh that needs every TU compiled fresh. cmake -S code -B build -DWITH_CGAL_TESTS=ON \ -DCONFORMALLAB_USE_PCH=OFF -DCMAKE_UNITY_BUILD=OFF ``` ccache is detected automatically when present on `PATH`; disable with `-DCONFORMALLAB_USE_CCACHE=OFF`. Full mode matrix + measurements in [`doc/architecture/compile-time.md`](doc/architecture/compile-time.md). --- ## 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 as gauge fix, index the rest 0..n-1 auto gauge = *mesh.vertices().begin(); int n = assign_euclidean_vertex_dof_indices(mesh, maps, gauge); // Natural equilibrium target: x* = 0 by construction std::vector x0(static_cast(n), 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 | | | |---|---| | **API reference (Doxygen HTML)** — every public class, function and named-parameter helper | https://tmoussa.codeberg.page/ConformalLabpp/ | | **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) | | **Public headers** — all public headers with descriptions | [doc/api/headers.md](doc/api/headers.md) | | **Test suites** — per-suite breakdown and counts (single source of truth) | [doc/api/tests.md](doc/api/tests.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-central comparison** — shared core, demarcation, adoption candidates, scientific added value | [doc/architecture/geometry-central-comparison.md](doc/architecture/geometry-central-comparison.md) | | **Design decisions** — key architectural choices + rationale | [doc/architecture/design-decisions.md](doc/architecture/design-decisions.md) | | **Project structure** — directory tree + build targets | [doc/architecture/project-structure.md](doc/architecture/project-structure.md) | | **CI / CD** — two-forge topology, runners, trigger keywords, mirror | [doc/architecture/ci-cd.md](doc/architecture/ci-cd.md) | | **Discrete conformal theory** — mathematical background for collaborators | [doc/math/discrete-conformal-theory.md](doc/math/discrete-conformal-theory.md) | | **Validation** — known analytic results + how to verify them | [doc/math/validation.md](doc/math/validation.md) | | **Validation protocol** — concrete commands with expected outputs | [doc/math/validation-protocol.md](doc/math/validation-protocol.md) | | **Tutorial: add a new functional** — step-by-step Inversive-Distance port | [doc/tutorials/add-inversive-distance.md](doc/tutorials/add-inversive-distance.md) | | **Declarative YAML pipeline** — concept, token vocabulary, 5 examples | [doc/concepts/declarative-pipeline.md](doc/concepts/declarative-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) | | **Software landscape** — how conformallab++ relates to libigl, CGAL, geometry-central | [doc/math/software-landscape.md](doc/math/software-landscape.md) | | **Novelty statement** — unique features, target audience, what this is not | [doc/math/novelty-statement.md](doc/math/novelty-statement.md) | | **Complexity & scalability** — O() analysis, measured timings on real meshes, HyperIdeal bottleneck | [doc/math/complexity.md](doc/math/complexity.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) | --- ## Citing If you use conformallab++ in your research, please cite it using the metadata in [`CITATION.cff`](CITATION.cff). GitHub and Codeberg show a "Cite this repository" button that generates BibTeX and APA automatically. The primary algorithmic source is: > 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) --- ## Bugs & questions - **Bug reports / feature requests:** [Gitea Issues](https://git.eulernest.eu/conformallab/ConformalLabpp/issues) - **Code mirror (read-only):** [Codeberg](https://codeberg.org/TMoussa/ConformalLabpp) - **Contact:** Tarik Moussa · Tarik.moussa95@gmail.com --- ## License conformallab++ is released under the MIT License (see [LICENSE](LICENSE)). Copyright © 2024–2026 Tarik Moussa. The dissertation (Sechelmann 2016) is CC BY-SA 4.0.