conformallab/ConformalLabpp

Fork 0

Files

Tarik Moussa b235666725

C++ Tests / test-fast (push) Successful in 2m15s

Details

C++ Tests / test-cgal (push) Has been skipped

Details

docs: Doxygen-API + Validierungsprotokoll + Porting-Tutorial

Für einen Mathematiker der unabhängig validieren und eigene Forschung
einbringen möchte.

Doxygen-Kommentare (code/include/):
  newton_solver.hpp — newton_euclidean(), newton_spherical(), newton_hyper_ideal()
    je mit \param, \return, \note, \see inkl. mathematischer Begründung
    (Konvexität, Vorzeichenkonvention, SparseQR-Fallback-Erklärung)
  layout.hpp — euclidean_layout(), spherical_layout(), hyper_ideal_layout()
    mit vollständiger Parameter-Doku, halfedge_uv-Semantik, Poincaré-Disk-Note

Neues Dokument:
  doc/math/validation-protocol.md
    7 reproduzierbare Checks mit konkreten Befehlen und erwartetem Output:
    0. 170 Tests, 1 Skip
    1. Gauss–Bonnet exakt (1e-10)
    2. FD-Gradientencheck < 1e-6 für alle 3 Geometrien
    3. Newton-Konvergenz < 50 Iterationen
    4. τ ∈ SL(2,ℤ)-Fundamentaldomäne (3 Invarianten)
    5. Möbius-Arithmetik (Inverse, Compose, from_three)
    6. End-to-End-Pipeline
    7. Manueller τ-Check für torus_4x4.off (Codebeispiel)

Neues Tutorial:
  doc/tutorials/add-inversive-distance.md
    Vollständiger Step-by-Step-Port von Phase 9a (Luo 2004):
    Header anlegen, Energie/Gradient implementieren, FD-Check,
    Newton-Wrapper, CMakeLists, Java-Referenzvergleich, Checkliste.

doc/getting-started.md:
  Abschnitt "Known issues": macOS-Finder-Duplikate (rm-Befehl),
  Warnung "First build 30–90s" (Tarball-Extraktion)

README.md:
  Zwei neue Links in der Dokumentationstabelle (validation-protocol,
  tutorial)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-18 01:19:44 +02:00

4.3 KiB

Raw Blame History

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: 158 tests pass, 2 skipped (intentional stubs for Phase 9 items).

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.

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/

4.3 KiB Raw Blame History Unescape Escape