274 lines
19 KiB
HTML
274 lines
19 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
||
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
|
||
<meta name="generator" content="Doxygen 1.17.0"/>
|
||
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
||
<title>conformallab++: conformallab++</title>
|
||
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
||
<script type="text/javascript" src="dynsections.js"></script>
|
||
<script type="text/javascript" src="codefolding.js"></script>
|
||
<script type="text/javascript" src="clipboard.js"></script>
|
||
<link href="navtree.css" rel="stylesheet" type="text/css"/>
|
||
<script type="text/javascript" src="navtreedata.js"></script>
|
||
<script type="text/javascript" src="navtree.js"></script>
|
||
<script type="text/javascript" src="cookie.js"></script>
|
||
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
||
<script type="text/javascript" src="search/searchdata.js"></script>
|
||
<script type="text/javascript" src="search/search.js"></script>
|
||
<script type="module">
|
||
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
|
||
const theme = 'default';
|
||
mermaid.initialize({ startOnLoad: true, theme: theme });
|
||
</script>
|
||
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
||
</head>
|
||
<body>
|
||
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
||
<div id="titlearea">
|
||
<table cellspacing="0" cellpadding="0">
|
||
<tbody>
|
||
<tr id="projectrow">
|
||
<td id="projectalign">
|
||
<div id="projectname">conformallab++<span id="projectnumber"> 0.7.0</span>
|
||
</div>
|
||
<div id="projectbrief">Discrete conformal maps on triangle meshes — C++17 reimplementation of ConformalLab (TU Berlin)</div>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
<!-- end header part -->
|
||
<!-- Generated by Doxygen 1.17.0 -->
|
||
<script type="text/javascript">
|
||
let searchBox = new SearchBox("searchBox", "search/",'.html');
|
||
</script>
|
||
<script type="text/javascript">
|
||
document.addEventListener('DOMContentLoaded', codefold.init);
|
||
</script>
|
||
<script type="text/javascript" src="menudata.js"></script>
|
||
<script type="text/javascript" src="menu.js"></script>
|
||
<script type="text/javascript">
|
||
document.addEventListener('DOMContentLoaded', () => {
|
||
initMenu('',true);
|
||
init_search();
|
||
});
|
||
</script>
|
||
<div id="main-nav-mobile">
|
||
<div class="sm sm-dox"><input id="main-menu-state" type="checkbox"/>
|
||
<label class="main-menu-btn" for="main-menu-state">
|
||
<span class="main-menu-btn-icon"></span> Toggle main menu visibility</label>
|
||
<span id="searchBoxPos1" style="position:absolute;right:8px;top:8px;height:36px;"></span>
|
||
</div>
|
||
</div><!-- main-nav-mobile -->
|
||
<div id="main-nav">
|
||
<ul class="sm sm-dox" id="main-menu">
|
||
<li id="searchBoxPos2" style="float:right">
|
||
<div id="MSearchBox" class="MSearchBoxInactive">
|
||
<span class="left">
|
||
<span id="MSearchSelect" class="search-icon" onmouseover="return searchBox.OnSearchSelectShow()" onmouseout="return searchBox.OnSearchSelectHide()"><span class="search-icon-dropdown"></span></span>
|
||
<input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
|
||
onfocus="searchBox.OnSearchFieldFocus(true)"
|
||
onblur="searchBox.OnSearchFieldFocus(false)"
|
||
onkeyup="searchBox.OnSearchFieldChange(event)"/>
|
||
</span><span class="right">
|
||
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><div id="MSearchCloseImg" class="close-icon"></div></a>
|
||
</span>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</div><!-- main-nav -->
|
||
</div><!-- top -->
|
||
<div id="side-nav" class="ui-resizable side-nav-resizable">
|
||
<div id="nav-tree">
|
||
<div id="nav-tree-contents">
|
||
<div id="nav-sync" class="sync"></div>
|
||
</div>
|
||
</div>
|
||
<div id="splitbar" style="-moz-user-select:none;"
|
||
class="ui-resizable-handle">
|
||
</div>
|
||
</div>
|
||
<script type="text/javascript">
|
||
document.addEventListener('DOMContentLoaded',() => { initNavTree('index.html','',''); });
|
||
</script>
|
||
<div id="container">
|
||
<div id="doc-content">
|
||
<!-- window showing the filter options -->
|
||
<div id="MSearchSelectWindow"
|
||
onmouseover="return searchBox.OnSearchSelectShow()"
|
||
onmouseout="return searchBox.OnSearchSelectHide()"
|
||
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
||
</div>
|
||
|
||
<!-- iframe showing the search results (closed by default) -->
|
||
<div id="MSearchResultsWindow">
|
||
<div id="MSearchResults">
|
||
<div class="SRPage">
|
||
<div id="SRIndex">
|
||
<div id="SRResults"></div>
|
||
<div class="SRStatus" id="Loading">Loading...</div>
|
||
<div class="SRStatus" id="Searching">Searching...</div>
|
||
<div class="SRStatus" id="NoMatches">No Matches</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<div><div class="header">
|
||
<div class="headertitle"><div class="title">conformallab++ </div></div>
|
||
</div><!--header-->
|
||
<div class="contents">
|
||
<div class="textblock"><p><a class="anchor" id="md__r_e_a_d_m_e"></a></p>
|
||
<p><a href="https://git.eulernest.eu/conformallab/ConformalLabpp/actions"><img src="https://git.eulernest.eu/conformallab/ConformalLabpp/actions/workflows/cpp-tests.yml/badge.svg" alt="CI" style="pointer-events: none;" class="inline"/></a> [<img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" style="pointer-events: none;" class="inline"/>](LICENSE) <a href="https://depositonce.tu-berlin.de/items/8e2988b2-d991-45b5-aad5-9fb7988f3b2f"><img src="https://img.shields.io/badge/doi-Sechelmann%202016-blue" alt="DOI" class="inline"/></a></p>
|
||
<p>C++17 reimplementation of <a href="https://github.com/varylab/conformallab">ConformalLab</a> — Stefan Sechelmann's Java research library for discrete conformal geometry (TU Berlin). The long-term goal is a <b>CGAL package</b> for discrete conformal maps.</p>
|
||
<p>Algorithmic foundation: </p><blockquote class="doxtable">
|
||
<p>Stefan Sechelmann — <em>Variational Methods for Discrete Surface Parameterization: Applications and Implementation</em>, TU Berlin 2016. DOI: <a href="https://depositonce.tu-berlin.de/items/8e2988b2-d991-45b5-aad5-9fb7988f3b2f">10.14279/depositonce-5415</a> · CC BY-SA 4.0 · <a href="https://github.com/varylab/conformallab">Java original</a> · <a href="https://sechel.de/">sechel.de</a> </p>
|
||
</blockquote>
|
||
<p><b>Status:</b> v0.9.0 — Phases 1–9a complete, Phase 8b-Lite CGAL API surface. Newton solvers for <b>five</b> 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. Full test suite passing, 0 skipped — see <a href="doc/api/tests.md"><span class="tt">doc/api/tests.md</span></a> for the per-suite breakdown.</p>
|
||
<hr />
|
||
<h1 class="doxsection"><a class="anchor" id="autotoc_md2"></a>
|
||
Quick start</h1>
|
||
<div class="fragment"><div class="line">git clone https://codeberg.org/TMoussa/ConformalLabpp && cd ConformalLabpp</div>
|
||
<div class="line"> </div>
|
||
<div class="line"># Fast tests — no system dependencies</div>
|
||
<div class="line">cmake -S code -B build && cmake --build build --target conformallab_tests -j$(nproc)</div>
|
||
<div class="line">ctest --test-dir build --output-on-failure</div>
|
||
<div class="line"> </div>
|
||
<div class="line"># CGAL tests headless (apt install libboost-dev / brew install boost)</div>
|
||
<div class="line">cmake -S code -B build -DWITH_CGAL_TESTS=ON</div>
|
||
<div class="line">cmake --build build --target conformallab_cgal_tests -j$(nproc)</div>
|
||
<div class="line">ctest --test-dir build -R "^cgal\." --output-on-failure</div>
|
||
<div class="line"> </div>
|
||
<div class="line"># Full build with CLI + viewer (requires Wayland/X11 dev headers)</div>
|
||
<div class="line">cmake -S code -B build -DWITH_CGAL=ON && cmake --build build -j$(nproc)</div>
|
||
<div class="line">./bin/conformallab_core -i input.off -g euclidean -o layout.off -j result.json</div>
|
||
<div class="line"> </div>
|
||
<div class="line"># API documentation (requires doxygen: brew/apt install doxygen)</div>
|
||
<div class="line">cmake --build build --target doc</div>
|
||
<div class="line">open doc/doxygen/html/index.html</div>
|
||
</div><!-- fragment --><hr />
|
||
<h1 class="doxsection"><a class="anchor" id="autotoc_md4"></a>
|
||
Minimal usage</h1>
|
||
<div class="fragment"><div class="line"><span class="preprocessor">#include "conformal_mesh.hpp"</span></div>
|
||
<div class="line"><span class="preprocessor">#include "mesh_io.hpp"</span></div>
|
||
<div class="line"><span class="preprocessor">#include "euclidean_functional.hpp"</span></div>
|
||
<div class="line"><span class="preprocessor">#include "gauss_bonnet.hpp"</span></div>
|
||
<div class="line"><span class="preprocessor">#include "newton_solver.hpp"</span></div>
|
||
<div class="line"><span class="preprocessor">#include "layout.hpp"</span></div>
|
||
<div class="line"> </div>
|
||
<div class="line"><span class="keyword">using namespace </span>conformallab;</div>
|
||
<div class="line"> </div>
|
||
<div class="line">ConformalMesh mesh = load_mesh(<span class="stringliteral">"input.off"</span>);</div>
|
||
<div class="line">EuclideanMaps maps = setup_euclidean_maps(mesh);</div>
|
||
<div class="line">compute_euclidean_lambda0_from_mesh(mesh, maps);</div>
|
||
<div class="line"> </div>
|
||
<div class="line"><span class="comment">// Assign DOFs — pin first vertex (gauge fix)</span></div>
|
||
<div class="line"><span class="keyword">auto</span> vit = mesh.vertices().begin();</div>
|
||
<div class="line">maps.v_idx[*vit++] = -1;</div>
|
||
<div class="line"><span class="keywordtype">int</span> idx = 0;</div>
|
||
<div class="line"><span class="keywordflow">for</span> (; vit != mesh.vertices().end(); ++vit) maps.v_idx[*vit] = idx++;</div>
|
||
<div class="line"> </div>
|
||
<div class="line"><span class="comment">// Natural equilibrium target: x* = 0 by construction</span></div>
|
||
<div class="line">std::vector<double> x0(idx, 0.0);</div>
|
||
<div class="line"><span class="keyword">auto</span> G0 = euclidean_gradient(mesh, x0, maps);</div>
|
||
<div class="line"><span class="keywordflow">for</span> (<span class="keyword">auto</span> v : mesh.vertices())</div>
|
||
<div class="line"> <span class="keywordflow">if</span> (maps.v_idx[v] >= 0) maps.theta_v[v] -= G0[maps.v_idx[v]];</div>
|
||
<div class="line"> </div>
|
||
<div class="line">check_gauss_bonnet(mesh, maps);</div>
|
||
<div class="line">NewtonResult res = newton_euclidean(mesh, x0, maps);</div>
|
||
<div class="line">Layout2D layout = euclidean_layout(mesh, res.x, maps);</div>
|
||
</div><!-- fragment --><hr />
|
||
<h1 class="doxsection"><a class="anchor" id="autotoc_md6"></a>
|
||
Documentation</h1>
|
||
<table class="markdownTable">
|
||
<tr class="markdownTableHead">
|
||
<th class="markdownTableHeadNone"></th><th class="markdownTableHeadNone"></th></tr>
|
||
<tr class="markdownTableRowOdd">
|
||
<td class="markdownTableBodyNone"><b>Getting started</b> — build modes, single-test invocation, CLI, Docker </td><td class="markdownTableBodyNone"><a href="doc/getting-started.md">doc/getting-started.md</a> </td></tr>
|
||
<tr class="markdownTableRowEven">
|
||
<td class="markdownTableBodyNone"><b>Pipeline API</b> — all three geometries, holonomy, serialisation </td><td class="markdownTableBodyNone"><a href="doc/api/pipeline.md">doc/api/pipeline.md</a> </td></tr>
|
||
<tr class="markdownTableRowOdd">
|
||
<td class="markdownTableBodyNone"><b>Public headers</b> — all public headers with descriptions </td><td class="markdownTableBodyNone"><a href="doc/api/headers.md">doc/api/headers.md</a> </td></tr>
|
||
<tr class="markdownTableRowEven">
|
||
<td class="markdownTableBodyNone"><b>Test suites</b> — per-suite breakdown and counts (single source of truth) </td><td class="markdownTableBodyNone"><a href="doc/api/tests.md">doc/api/tests.md</a> </td></tr>
|
||
<tr class="markdownTableRowOdd">
|
||
<td class="markdownTableBodyNone"><b>Extending</b> — new functionals, geometry modes, porting from Java </td><td class="markdownTableBodyNone"><a href="doc/api/extending.md">doc/api/extending.md</a> </td></tr>
|
||
<tr class="markdownTableRowEven">
|
||
<td class="markdownTableBodyNone"><b>Processing unit contracts</b> — preconditions / provides table </td><td class="markdownTableBodyNone"><a href="doc/api/contracts.md">doc/api/contracts.md</a> </td></tr>
|
||
<tr class="markdownTableRowOdd">
|
||
<td class="markdownTableBodyNone"><b>CGAL package design</b> — Phase 8 target, YAML pipeline </td><td class="markdownTableBodyNone"><a href="doc/api/cgal-package.md">doc/api/cgal-package.md</a> </td></tr>
|
||
<tr class="markdownTableRowEven">
|
||
<td class="markdownTableBodyNone"><b>Architecture & pipeline diagram</b> </td><td class="markdownTableBodyNone"><a href="doc/architecture/overall_pipeline.md">doc/architecture/overall_pipeline.md</a> </td></tr>
|
||
<tr class="markdownTableRowOdd">
|
||
<td class="markdownTableBodyNone"><b>geometry-central comparison</b> — shared core, demarcation, adoption candidates, scientific added value </td><td class="markdownTableBodyNone"><a href="doc/architecture/geometry-central-comparison.md">doc/architecture/geometry-central-comparison.md</a> </td></tr>
|
||
<tr class="markdownTableRowEven">
|
||
<td class="markdownTableBodyNone"><b>Design decisions</b> — key architectural choices + rationale </td><td class="markdownTableBodyNone"><a href="doc/architecture/design-decisions.md">doc/architecture/design-decisions.md</a> </td></tr>
|
||
<tr class="markdownTableRowOdd">
|
||
<td class="markdownTableBodyNone"><b>Project structure</b> — directory tree + build targets </td><td class="markdownTableBodyNone"><a href="doc/architecture/project-structure.md">doc/architecture/project-structure.md</a> </td></tr>
|
||
<tr class="markdownTableRowEven">
|
||
<td class="markdownTableBodyNone"><b>Discrete conformal theory</b> — mathematical background for collaborators </td><td class="markdownTableBodyNone"><a href="doc/math/discrete-conformal-theory.md">doc/math/discrete-conformal-theory.md</a> </td></tr>
|
||
<tr class="markdownTableRowOdd">
|
||
<td class="markdownTableBodyNone"><b>Validation</b> — known analytic results + how to verify them </td><td class="markdownTableBodyNone"><a href="doc/math/validation.md">doc/math/validation.md</a> </td></tr>
|
||
<tr class="markdownTableRowEven">
|
||
<td class="markdownTableBodyNone"><b>Validation protocol</b> — concrete commands with expected outputs </td><td class="markdownTableBodyNone"><a href="doc/math/validation-protocol.md">doc/math/validation-protocol.md</a> </td></tr>
|
||
<tr class="markdownTableRowOdd">
|
||
<td class="markdownTableBodyNone"><b>Tutorial: add a new functional</b> — step-by-step Inversive-Distance port </td><td class="markdownTableBodyNone"><a href="doc/tutorials/add-inversive-distance.md">doc/tutorials/add-inversive-distance.md</a> </td></tr>
|
||
<tr class="markdownTableRowEven">
|
||
<td class="markdownTableBodyNone"><b>Declarative YAML pipeline</b> — concept, token vocabulary, 5 examples </td><td class="markdownTableBodyNone"><a href="doc/concepts/declarative-pipeline.md">doc/concepts/declarative-pipeline.md</a> </td></tr>
|
||
<tr class="markdownTableRowOdd">
|
||
<td class="markdownTableBodyNone"><b>Geometry modes</b> — Euclidean / Spherical / HyperIdeal comparison </td><td class="markdownTableBodyNone"><a href="doc/math/geometry-modes.md">doc/math/geometry-modes.md</a> </td></tr>
|
||
<tr class="markdownTableRowEven">
|
||
<td class="markdownTableBodyNone"><b>References</b> — all papers by module </td><td class="markdownTableBodyNone"><a href="doc/math/references.md">doc/math/references.md</a> </td></tr>
|
||
<tr class="markdownTableRowOdd">
|
||
<td class="markdownTableBodyNone"><b>Software landscape</b> — how conformallab++ relates to libigl, CGAL, geometry-central </td><td class="markdownTableBodyNone"><a href="doc/math/software-landscape.md">doc/math/software-landscape.md</a> </td></tr>
|
||
<tr class="markdownTableRowEven">
|
||
<td class="markdownTableBodyNone"><b>Novelty statement</b> — unique features, target audience, what this is not </td><td class="markdownTableBodyNone"><a href="doc/math/novelty-statement.md">doc/math/novelty-statement.md</a> </td></tr>
|
||
<tr class="markdownTableRowOdd">
|
||
<td class="markdownTableBodyNone"><b>Complexity & scalability</b> — O() analysis, measured timings on real meshes, HyperIdeal bottleneck </td><td class="markdownTableBodyNone"><a href="doc/math/complexity.md">doc/math/complexity.md</a> </td></tr>
|
||
<tr class="markdownTableRowEven">
|
||
<td class="markdownTableBodyNone"><b>Roadmap</b> — Phases 1–10 </td><td class="markdownTableBodyNone"><a href="doc/roadmap/phases.md">doc/roadmap/phases.md</a> </td></tr>
|
||
<tr class="markdownTableRowOdd">
|
||
<td class="markdownTableBodyNone"><b>Java parity table</b> — what is ported, what is planned </td><td class="markdownTableBodyNone"><a href="doc/roadmap/java-parity.md">doc/roadmap/java-parity.md</a> </td></tr>
|
||
<tr class="markdownTableRowEven">
|
||
<td class="markdownTableBodyNone"><b>Contributing</b> — language policy, test standards, release flow </td><td class="markdownTableBodyNone"><a href="doc/contributing.md">doc/contributing.md</a> </td></tr>
|
||
<tr class="markdownTableRowOdd">
|
||
<td class="markdownTableBodyNone"><b>Claude Code context</b> </td><td class="markdownTableBodyNone"><a href="CLAUDE.md">CLAUDE.md</a> </td></tr>
|
||
</table>
|
||
<hr />
|
||
<h1 class="doxsection"><a class="anchor" id="autotoc_md8"></a>
|
||
Citing</h1>
|
||
<p>If you use conformallab++ in your research, please cite it using the metadata in <a href="CITATION.cff"><span class="tt">CITATION.cff</span></a>. GitHub and Codeberg show a "Cite this repository" button that generates BibTeX and APA automatically.</p>
|
||
<p>The primary algorithmic source is:</p>
|
||
<blockquote class="doxtable">
|
||
<p>Stefan Sechelmann — <em>Variational Methods for Discrete Surface Parameterization: Applications and Implementation</em>, TU Berlin 2016. DOI: <a href="https://depositonce.tu-berlin.de/items/8e2988b2-d991-45b5-aad5-9fb7988f3b2f">10.14279/depositonce-5415</a> </p>
|
||
</blockquote>
|
||
<hr />
|
||
<h1 class="doxsection"><a class="anchor" id="autotoc_md10"></a>
|
||
Bugs & questions</h1>
|
||
<ul>
|
||
<li><b>Bug reports / feature requests:</b> <a href="https://git.eulernest.eu/conformallab/ConformalLabpp/issues">Gitea Issues</a></li>
|
||
<li><b>Code mirror (read-only):</b> <a href="https://codeberg.org/TMoussa/ConformalLabpp">Codeberg</a></li>
|
||
<li><b>Contact:</b> Tarik Moussa · <a href="#" onclick="location.href='mai'+'lto:'+'Tar'+'ik'+'.mo'+'us'+'sa9'+'5@'+'gma'+'il'+'.co'+'m'; return false;">Tarik<span class="obfuscator">.nosp@m.</span>.mou<span class="obfuscator">.nosp@m.</span>ssa95<span class="obfuscator">.nosp@m.</span>@gma<span class="obfuscator">.nosp@m.</span>il.co<span class="obfuscator">.nosp@m.</span>m</a></li>
|
||
</ul>
|
||
<hr />
|
||
<h1 class="doxsection"><a class="anchor" id="autotoc_md12"></a>
|
||
License</h1>
|
||
<p>conformallab++ is released under the MIT License (see [LICENSE](LICENSE)). <br />
|
||
Copyright © 2024–2026 Tarik Moussa. <br />
|
||
The dissertation (Sechelmann 2016) is CC BY-SA 4.0. </p>
|
||
</div></div><!-- PageDoc -->
|
||
<a href="doxygen_crawl.html"></a>
|
||
</div><!-- contents -->
|
||
</div><!-- doc-content -->
|
||
</div><!-- container -->
|
||
<!-- start footer part -->
|
||
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
||
<ul>
|
||
<li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.17.0 </li>
|
||
</ul>
|
||
</div>
|
||
</body>
|
||
</html>
|