ConformalLabpp/doc/getting-started.md

Getting Started

Prerequisites

Tool	Minimum	Notes
C++ compiler (GCC or Clang)	C++17	GCC 11+ or Clang 14+ recommended
CMake	3.20
Boost headers	1.70	Only for -DWITH_CGAL_TESTS=ON or -DWITH_CGAL=ON
Wayland/X11 dev headers	—	Only for -DWITH_CGAL=ON (viewer)

All other dependencies (Eigen 3.4, CGAL 6.1.1, libigl 2.6, GLFW 3.4, GTest 1.14) are bundled as tarballs in code/deps/tarballs/ and extracted automatically at CMake configure time. No internet access is required at build time (except GTest, fetched via FetchContent from GitHub).

Install Boost on your system:

# Ubuntu / Debian
apt install libboost-dev

# macOS
brew install boost

---

Clone

git clone https://codeberg.org/TMoussa/ConformalLabpp
cd ConformalLabpp

---

Build modes

Three modes with increasing dependencies:

Mode 1 — Fast tests (default, no system dependencies)

Pure-math tests: Clausen functions, hyper-ideal geometry, matrix utilities.

cmake -S code -B build
cmake --build build --target conformallab_tests -j$(nproc)
ctest --test-dir build --output-on-failure

Expected: 36 tests pass.

Mode 2 — CGAL tests, headless (recommended for CI and development)

Full CGAL test suite. Requires Boost headers only — no display, no Wayland, no GLFW.

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

Expected: 173 tests pass, 1 skipped (intentional stub for analytic HyperIdeal Hessian, Phase 9b).

Mode 3 — Full local build (CLI app + interactive viewer)

Requires Wayland or X11 development packages (wayland-scanner, libx11-dev, etc.). Automatically enables the viewer library (GLFW + libigl).

cmake -S code -B build -DWITH_CGAL=ON
cmake --build build -j$(nproc)

Note: -DWITH_CGAL=ON implies -DWITH_VIEWER=ON. Do not use this in headless environments — it will fail with Failed to find wayland-scanner.

---

Running a single test

# By GTest filter (fastest, full output)
./build/conformallab_cgal_tests --gtest_filter="NewtonSolver*"
./build/conformallab_tests       --gtest_filter="Clausen*"

# By CTest regex
ctest --test-dir build -R "cgal.NewtonSolver" --output-on-failure

All CGAL tests have the prefix cgal. in CTest (set in tests/cgal/CMakeLists.txt via TEST_PREFIX "cgal.").

---

First run — CLI app

After a full build (-DWITH_CGAL=ON):

# Euclidean conformal layout
./bin/conformallab_core -i input.off -g euclidean -o layout.off -j result.json

# Spherical layout
./bin/conformallab_core -i input.off -g spherical -o sphere.off

# Hyperbolic layout (HyperIdeal)
./bin/conformallab_core -i input.off -g hyper_ideal -o hyperbolic.off

# Show input mesh in interactive viewer
./bin/conformallab_core -i input.off -s

# All options
./bin/conformallab_core --help

Example programs

./build/examples/example_layout    [input.off] [layout.off] [result.json]
./build/examples/example_euclidean [input.off] [output.off]
./build/examples/example_hyper_ideal [input.off] [output.off]
./build/examples/example_viewer    [input.off]   # interactive, requires WITH_VIEWER

example_layout.cpp is the best starting point — it shows the complete pipeline in ~120 lines.

Expected output of example_euclidean on the built-in quad-strip mesh:

[example_euclidean] No input file given — using make_quad_strip().
[example_euclidean] Mesh: 6 vertices, 4 faces.
[example_euclidean] DOFs: 5 (1 vertex pinned).
[example_euclidean] Solving Newton system…
[example_euclidean] Converged in 1 iterations.  ||G||_inf = 0
[example_euclidean] Per-vertex conformal factors u_i:
  v0  u = 0  (pinned)
  v1  u = -1.38778e-17       ← ≈ 0 (machine epsilon)
  ...
[example_euclidean] Mesh saved to: /tmp/conformallab_euclidean_out.off

Convergence in 1 iteration is expected: the "natural equilibrium" construction sets x* = 0, so a small perturbation (-0.05) needs only one Newton step.

Quick automated start (no interactive build needed):

bash scripts/try_it.sh

This clones nothing (run from inside the repo), builds the CGAL test suite, runs all 173+36 tests, and prints a summary. See scripts/try_it.sh for details.

---

Known issues

macOS Finder duplicates

macOS Finder sometimes creates duplicate files named foo 2.hpp when copying the repository. These cause confusing compile errors ("redefinition of …").

Fix (run once from the repo root):

find code/include -name "* 2.*" -delete
find code/include -name "*\ 2.*" -delete

Files without a 2 suffix are always canonical — the duplicates are safe to delete.

First build is slow

The first CMake configure extracts four tarballs (Eigen 3.4, CGAL 6.1.1, libigl 2.6, GLFW 3.4) and downloads GTest via FetchContent. Allow 30–90 seconds for the first configure. Subsequent builds are fast (< 10 s incremental).

---

Rebuilding the CI Docker image

The CI runner is a self-hosted Raspberry Pi (ARM64). After changes to .gitea/docker/Dockerfile.ci-cpp:

docker buildx build \
  --platform linux/arm64 \
  -f .gitea/docker/Dockerfile.ci-cpp \
  -t git.eulernest.eu/conformallab/ci-cpp:latest \
  --push \
  .gitea/docker/