### Command-Line Tool: Example with Scaling and Threads

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

A practical example of using the HexHex tool with shorthand flags for input/output, specifying a scaling factor, number of threads, and enabling report generation.

```bash
# Example: extract with scaling, 4 threads, save report
HexHex -i mesh.hexex -o hex.ovmb --scale 2 --nthreads 4 --report report.json
```

--------------------------------

### Build HexHex on MacOS

Source: https://github.com/cgg-bern/libhexhex/blob/main/README.md

Install dependencies using Homebrew and then use CMake to build the project. The `jemalloc` library is optional.

```console
brew install cmake pkgconf jemalloc # (`jemalloc` is optional)
cmake -B build .
cmake --build build
```

--------------------------------

### C API: hexhex_extract_simple Example

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Demonstrates the usage of the hexhex_extract_simple function to convert a single tetrahedron into a hex mesh. Memory allocated for vpos and hex_vertices must be freed by the caller.

```c
#include <HexHex/c_api.h>
#include <stdlib.h>
#include <stdio.h>

/*
 * Inputs:
 *   n_vertices      – number of tet mesh vertices
 *   vpos            – flat array of 3*n_vertices doubles (x0,y0,z0, x1,y1,z1, ...)
 *   n_tets          – number of tetrahedra
 *   tet_vertices    – flat array of 4*n_tets uint32_t vertex indices
 *   tet_igm         – flat array of 3*4*n_tets doubles:
 *                     for each tet, 4 parameter triples (one per corner),
 *                     corner order matches tet_vertices order
 *
 * Returns:
 *   struct HexMesh {
 *       size_t    n_vertices;
 *       double   *vpos;         // malloc'd: 3 * n_vertices doubles
 *       size_t    n_hexes;
 *       uint32_t *hex_vertices; // malloc'd: 8 * n_hexes uint32_t indices
 *   };
 */

// Single-tet example: one tetrahedron with identity IGM
size_t   n_verts = 4;
double   vpos[]  = {
    0.0, 0.0, 0.0,   // v0
    1.0, 0.0, 0.0,   // v1
    0.0, 1.0, 0.0,   // v2
    0.0, 0.0, 1.0    // v3
};
uint32_t tet_verts[] = {0, 1, 2, 3};

// IGM: 4 corners × 3 doubles, here a simple scaled identity map
double tet_igm[] = {
    0.0, 0.0, 0.0,   // corner 0 parameter
    1.0, 0.0, 0.0,   // corner 1 parameter
    0.0, 1.0, 0.0,   // corner 2 parameter
    0.0, 0.0, 1.0    // corner 3 parameter
};

struct HexMesh hm = hexhex_extract_simple(
    n_verts, vpos,
    1, tet_verts,
    tet_igm
);

printf("Output: %zu vertices, %zu hexes\n", hm.n_vertices, hm.n_hexes);
for (size_t i = 0; i < hm.n_hexes; ++i) {
    printf("Hex %zu: ", i);
    for (int k = 0; k < 8; ++k)
        printf("%u ", hm.hex_vertices[8*i+k]);
    printf("\n");
}

// Caller is responsible for freeing
free(hm.vpos);
free(hm.hex_vertices);

```

--------------------------------

### Configure Test Executable Properties

Source: https://github.com/cgg-bern/libhexhex/blob/main/tests/CMakeLists.txt

Sets properties for the test executable, including disabling the install rpath and configuring runtime output directories for different build configurations.

```cmake
# For the unittest we don't want the install rpath as set by acg_add_executable
set_target_properties (hexhex_unittests PROPERTIES  BUILD_WITH_INSTALL_RPATH 0 )

# Set output directory to ${BINARY_DIR}/Build
set (OUTPUT_DIR "${CMAKE_BINARY_DIR}/Build/${ACG_PROJECT_BINDIR}")
set_target_properties(hexhex_unittests PROPERTIES RUNTIME_OUTPUT_DIRECTORY ${OUTPUT_DIR})

foreach(CONFIG ${CMAKE_CONFIGURATION_TYPES})
    string(TOUPPER ${CONFIG} UPCONFIG)
    set_target_properties(hexhex_unittests PROPERTIES RUNTIME_OUTPUT_DIRECTORY_${UPCONFIG} ${OUTPUT_DIR})
endforeach()
```

--------------------------------

### Build HexHex on macOS

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Builds the HexHex library on macOS using CMake. Assumes Homebrew is installed for dependencies like cmake and pkgconf. jemalloc is optional.

```bash
# macOS
brew install cmake pkgconf jemalloc   # jemalloc is optional
cmake -B build .
cmake --build build
# Produces: ./build/Build/bin/HexHex
```

--------------------------------

### Hierarchical Timing with ScopedStopWatch

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Use ScopedStopWatch to measure execution time of code blocks. The timer starts when the object is created and stops when it goes out of scope. The root stopwatch can be printed to display the timing tree.

```cpp
#include <HexHex/Utils/Stopwatches.hh>

{
    HexHex::ScopedStopWatch timer{HexHex::sw::root};
    HexHex::HexExtractor he(tetmesh, igm);
    he.extract(config);
}

// Print tree of timings to stdout
std::cout << HexHex::sw::root << "\n";

```

--------------------------------

### Command-Line Tool Usage

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Demonstrates how to use the HexHex binary for mesh conversion with various options.

```APIDOC
## Command-Line Tool

The `HexHex` binary wraps the full pipeline with file I/O.

```bash
# Minimal usage
HexHex --in TetMesh.ovmb --out-hex HexMesh.ovmb

# Full options
HexHex \
    --in          input.hexex        \   # input tet mesh + IGM (.hexex | .ovm | .ovmb)
    --out-hex     output.ovmb        \   # output hex mesh (.ovmb | .ovm | .mesh)
    --out-pwl     pwl_mesh.ovmb      \   # optional piecewise-linear mesh (enables PWL extraction)
    --report      report.json        \   # JSON report with timings and statistics
    --config      config.json        \   # JSON config file (see Config struct)
    --scale       2                  \   # IGM scaling factor (positive integer)
    --nthreads    8                      # number of OpenMP threads

# Example: extract with scaling, 4 threads, save report
HexHex -i mesh.hexex -o hex.ovmb --scale 2 --nthreads 4 --report report.json
```
```

--------------------------------

### Command-Line Tool: Full Options

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Illustrates the comprehensive options available for the HexHex command-line tool, including input/output files, reporting, configuration, scaling, and threading.

```bash
# Full options
HexHex \
    --in          input.hexex        \
    --out-hex     output.ovmb        \
    --out-pwl     pwl_mesh.ovmb      \
    --report      report.json        \
    --config      config.json        \
    --scale       2                  \
    --nthreads    8
```

--------------------------------

### Loading Config from JSON

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Demonstrates how to load HexHex configuration parameters from a JSON file.

```APIDOC
### Loading Config from JSON

```cpp
// config.json
// {
//   "num_threads": 8,
//   "igm_scaling_factor": 2,
//   "verbose": false,
//   "extract_piecewise_linear_edges": true,
//   "extract_piecewise_linear_faces": true,
//   "sanitize_igm": true,
//   "sanitization_epsilon": 0.01,
//   "assert_igm_validity": true,
//   "rasterization_epsilon": 1e-6
// }

HexHex::Config config;
bool ok = HexHex::loadConfig("config.json", config);
if (!ok) {
    std::cerr << "Failed to load config\n";
}
```
```

--------------------------------

### Fetch and Configure Google Test

Source: https://github.com/cgg-bern/libhexhex/blob/main/tests/CMakeLists.txt

Fetches the Google Test framework from GitHub and makes it available for use. Includes a Windows-specific setting to force shared CRT linking.

```cmake
if (NOT TARGET GTest::gtest_main)
    FetchContent_Declare( googletest
        GIT_REPOSITORY https://github.com/google/googletest.git
        GIT_TAG        v1.17.x
        )
    if(WIN32)
        # avoid linking errors, cf https://stackoverflow.com/questions/12540970/how-to-make-gtest-build-mdd-instead-of-mtd-by-default-using-cmake
        set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
    endif()
    FetchContent_MakeAvailable(googletest)
endif()

include(GoogleTest)
```

--------------------------------

### Loading Input from File

Source: https://github.com/cgg-bern/libhexhex/blob/main/README.md

Shows how to load tetrahedral mesh and integer grid map data from various file formats using `loadInputFromFile`.

```APIDOC
## Loading the Input from a File

The function
```cpp
std::optional<ParametrizedMesh> mesh = HexHex::loadInputFromFile(filename);
```
can be used to load a tet mesh and IGM from a .hexex file, .ovm file, or .ovmb file. If the mesh is loaded from a .ovm or .ovmb file, the mesh is expected to store the integer-grid map as a `HalfFaceProperty<Vec3d>` named `HexHex::Parametrization`.
```

--------------------------------

### Direct HexExtractor Usage (Option 1)

Source: https://github.com/cgg-bern/libhexhex/blob/main/README.md

Demonstrates using the `HexExtractor` class directly with an OVM tetrahedral mesh and a generic IntegerGridMapT.

```APIDOC
## Using the HexExtractor directly

You can also use the internal HexExtractor class directly. For this, you have two options.

1. OVM Tetrahedral Mesh and Template Integer Grid Map
    The igm must implement the subscript operators igm[CellHandle][VertexHandle]
    ```cpp
    HexHex::TetrahedralMesh tetmesh = ...
    IntegerGridMapT igm = ...
    HexHex::HexExtractor he(tetmesh, igm);
    auto result = he.extract();
    ```
```

--------------------------------

### Command-Line Tool: Minimal Usage

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Basic command to convert a tet mesh to a hex mesh using the HexHex binary. Input and output file formats are specified.

```bash
# Minimal usage
HexHex --in TetMesh.ovmb --out-hex HexMesh.ovmb
```

--------------------------------

### Load HexHex Configuration from JSON

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Load runtime parameters for HexHex extraction from a JSON file. Ensure the JSON file contains valid keys corresponding to `HexHex::Config` members.

```json
// config.json
// {
//   "num_threads": 8,
//   "igm_scaling_factor": 2,
//   "verbose": false,
//   "extract_piecewise_linear_edges": true,
//   "extract_piecewise_linear_faces": true,
//   "sanitize_igm": true,
//   "sanitization_epsilon": 0.01,
//   "assert_igm_validity": true,
//   "rasterization_epsilon": 1e-6
// }

```

```cpp
#include <HexHex/HexHex.hh>
#include <iostream>

HexHex::Config config;
bool ok = HexHex::loadConfig("config.json", config);
if (!ok) {
    std::cerr << "Failed to load config\n";
}

```

--------------------------------

### Load Parametrized Tet Mesh from File

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Load a tetrahedral mesh and its IGM from a file using `loadInputFromFile`. Supported formats include `.hexex`, `.ovm`, and `.ovmb`. Check the returned optional for success.

```cpp
#include <HexHex/Utils/FileAccessor.hh>

// Returns std::optional<HexHex::ParametrizedMesh>
auto result = HexHex::loadInputFromFile("mesh.hexex");
if (!result.has_value()) {
    std::cerr << "Load failed\n";
    return 1;
}
HexHex::TetrahedralMesh& tetmesh = result->mesh;
HexHex::HFParam&         igm     = result->igm;

std::cout << "Loaded " << tetmesh.n_vertices() << " vertices, "
          << tetmesh.n_cells() << " tets\n";

// For .ovm / .ovmb files the mesh must contain a persistent
// HalfFacePropertyT<Vec3d> named HexHex::PropertyNames::HexHexParam
```

--------------------------------

### Load Input Mesh from File

Source: https://github.com/cgg-bern/libhexhex/blob/main/README.md

Load a tetrahedral mesh and IGM from various file formats (.hexex, .ovm, .ovmb). For .ovm/.ovmb files, the IGM is expected to be stored as a `HalfFaceProperty<Vec3d>` named `HexHex::Parametrization`.

```cpp
std::optional<ParametrizedMesh> mesh = HexHex::loadInputFromFile(filename);
```

--------------------------------

### Copy Test Data and Create Results Directory

Source: https://github.com/cgg-bern/libhexhex/blob/main/tests/CMakeLists.txt

Copies test data files to the output directory and creates a subdirectory for test results.

```cmake
file(COPY "${CMAKE_CURRENT_SOURCE_DIR}/testdata/" DESTINATION "${OUTPUT_DIR}/testdata")
file(MAKE_DIRECTORY ${OUTPUT_DIR}/Results)
```

--------------------------------

### Direct HexExtractor Usage (Option 2)

Source: https://github.com/cgg-bern/libhexhex/blob/main/README.md

Shows how to use the `HexExtractor` class directly with an OVM tetrahedral mesh and a HalfFaceProperty for the IGM.

```APIDOC
2. OVM Tetrahedral Mesh with HalfFaceProperty
    ```cpp
    HexHex::TetrahedralMesh tetmesh = ...
    HexHex::HalfFaceProp<HexHex::Vec3d> igm = ...
    HexHex::HexExtractor he(tetmesh, igm);
    auto result = he.extract();
    ```
```

--------------------------------

### Build Executable and Link Libraries

Source: https://github.com/cgg-bern/libhexhex/blob/main/tools/minimum_example/CMakeLists.txt

Defines the main executable and links it against OpenVolumeMesh and HexHex libraries. Also disables OpenVolumeMesh debug output by defining NDEBUG.

```cmake
cmake_minimum_required(VERSION 3.14)


add_executable (minimum_example main.cc)
target_link_libraries(minimum_example OpenVolumeMesh::OpenVolumeMesh HexHex::HexHex)

# disable OpenVolumeMesh debug output:
target_compile_definitions(minimum_example PUBLIC NDEBUG)
```

--------------------------------

### Add Google Test Tests

Source: https://github.com/cgg-bern/libhexhex/blob/main/tests/CMakeLists.txt

Configures the test executable to run Google Tests with specific arguments for color output and XML reporting, setting the working directory for the tests.

```cmake
gtest_add_tests(TARGET hexhex_unittests
    EXTRA_ARGS "--gtest_color=yes;--gtest_output=xml"
    WORKING_DIRECTORY "${OUTPUT_DIR}"
    )
```

--------------------------------

### Low-Level Hex Extraction with HexExtractor (HalfFacePropertyT)

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Utilize the `HexExtractor` class for fine-grained control over the extraction process. This constructor variant accepts an `OVM::HalfFacePropertyT` for the input mesh.

```cpp
#include <HexHex/HexExtractor.hh>
#include <iostream>

HexHex::TetrahedralMesh tetmesh = /* ... build or load tet mesh ... */;
HexHex::HFParam igm = tetmesh.request_halfface_property<HexHex::Vec3d>(
    HexHex::PropertyNames::HexHexParam);
// ... fill igm values ...

HexHex::HexExtractor he(tetmesh, igm);

bool ok = he.extract(HexHex::Config{
    .extract_piecewise_linear_edges = false,
    .extract_piecewise_linear_faces = false,
    .verbose      = true,
    .num_threads  = 4,
    .igm_scaling_factor = 1,
});

if (ok && !he.hasDetectedError()) {
    const HexHex::HexahedralMesh& out = he.getOutputMesh();
    std::cout << "Extracted " << out.n_cells() << " hex cells\n";

    // Take ownership of output mesh
    auto hexmesh_ptr = he.takeOutputMesh();

    // Access the JSON report
    auto report = he.getHexHexReport();
    std::cout << report.dump(4) << "\n";
}

```

--------------------------------

### Embed HexHex in a CMake Project

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Demonstrates how to integrate the HexHex library into another CMake project using FetchContent. Links the HexHex library to a target.

```cmake
# Embedding HexHex in another CMake project
FetchContent_Declare(hexhex
    GIT_REPOSITORY https://github.com/cgg-bern/libHexHex
    GIT_TAG        main
)
FetchContent_MakeAvailable(hexhex)
target_link_libraries(my_target PRIVATE HexHex::HexHex)
```

--------------------------------

### Generate Test Meshes (Cube and Cylinder)

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Utilize built-in functions like `createCube` and `createCylinder` to generate parametrized tetrahedral meshes for testing and prototyping. The resolution of tet and hex cells can be specified.

```cpp
#include <HexHex/Utils/TestMeshes.hh>

// Create a cube tet mesh of T×T×T×6 tets whose IGM maps to H×H×H hex cells
unsigned int T = 2; // tet grid resolution
unsigned int H = 3; // desired hex grid resolution
HexHex::ParametrizedMesh cube = HexHex::createCube(T, H);

std::cout << "Tets: " << cube.mesh.n_cells() << "\n"; // 2*2*2*6 = 48

// Extract the hex mesh from it
auto result = HexHex::extractHexMesh(cube.mesh, cube.igm);
std::cout << "Hexes: " << result.hex_mesh->n_cells() << "\n"; // H^3 = 27

// Create a cylindrical tet mesh with a given edge valence
unsigned int valence = 5, hexScale = 1;
HexHex::ParametrizedMesh cylinder = HexHex::createCylinder(valence, hexScale);

// Randomize transition functions for stress testing
HexHex::randomizeTransitions(cube);
auto result2 = HexHex::extractHexMesh(cube.mesh, cube.igm);
```

--------------------------------

### HexHex Core Types and Typedefs

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Includes common mesh, vector, parameter, and handle types from the HexHex namespace. Shows how to request a half-face property for the IGM input.

```cpp
#include <HexHex/Utils/Typedefs.hh>

// Mesh types
HexHex::TetrahedralMesh  tetmesh;   // OVM::TetrahedralGeometryKernel<Vec3d, ...>
HexHex::HexahedralMesh   hexmesh;   // OVM::GeometryKernel<Vec3d, HexahedralMeshTopologyKernel>
HexHex::PolyhedralMesh   pwlmesh;   // OVM::GeometryKernel<Vec3d, TopologyKernel>

// Vector and parameter types
HexHex::Vec3d    pos(1.0, 2.0, 3.0);   // 3D double vector (position or IGM parameter)
HexHex::Vec3i    idx(1, 2, 3);          // 3D integer vector
HexHex::Parameter p = pos;              // alias for Vec3d – IGM parameter value

// Handle types (wrappers around integer indices)
HexHex::VertexHandle   vh;
HexHex::EdgeHandle     eh;
HexHex::HalfEdgeHandle heh;
HexHex::FaceHandle     fh;
HexHex::HalfFaceHandle hfh;
HexHex::CellHandle     ch;

// IGM half-face property (input format expected by extractHexMesh)
// Each (non-boundary) halfface stores the parameter of the vertex opposite to it
// within its incident tet cell.
HexHex::HFParam igm = tetmesh.request_halfface_property<HexHex::Vec3d>(
    HexHex::PropertyNames::HexHexParam);
```

--------------------------------

### C API - hexhex_extract_simple()

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Provides a plain-C interface for extracting hex meshes from tet meshes. Memory allocated by this function must be freed by the caller.

```APIDOC
## C API – `hexhex_extract_simple()`

A minimal plain-C interface for use from C, Python, Rust, or any FFI-capable language. Memory for `vpos` and `hex_vertices` in the returned struct is allocated with `malloc` and must be freed by the caller.

```c
#include <HexHex/c_api.h>
#include <stdlib.h>
#include <stdio.h>

/*
 * Inputs:
 *   n_vertices      – number of tet mesh vertices
 *   vpos            – flat array of 3*n_vertices doubles (x0,y0,z0, x1,y1,z1, ...)
 *   n_tets          – number of tetrahedra
 *   tet_vertices    – flat array of 4*n_tets uint32_t vertex indices
 *   tet_igm         – flat array of 3*4*n_tets doubles:
 *                     for each tet, 4 parameter triples (one per corner),
 *                     corner order matches tet_vertices order
 *
 * Returns:
 *   struct HexMesh {
 *       size_t    n_vertices;
 *       double   *vpos;         // malloc'd: 3 * n_vertices doubles
 *       size_t    n_hexes;
 *       uint32_t *hex_vertices; // malloc'd: 8 * n_hexes uint32_t indices
 *   };
 */

// Single-tet example: one tetrahedron with identity IGM
size_t   n_verts = 4;
double   vpos[]  = {
    0.0, 0.0, 0.0,   // v0
    1.0, 0.0, 0.0,   // v1
    0.0, 1.0, 0.0,   // v2
    0.0, 0.0, 1.0    // v3
};
uint32_t tet_verts[] = {0, 1, 2, 3};

// IGM: 4 corners × 3 doubles, here a simple scaled identity map
double tet_igm[] = {
    0.0, 0.0, 0.0,   // corner 0 parameter
    1.0, 0.0, 0.0,   // corner 1 parameter
    0.0, 1.0, 0.0,   // corner 2 parameter
    0.0, 0.0, 1.0    // corner 3 parameter
};

struct HexMesh hm = hexhex_extract_simple(
    n_verts, vpos,
    1, tet_verts,
    tet_igm
);

printf("Output: %zu vertices, %zu hexes\n", hm.n_vertices, hm.n_hexes);
for (size_t i = 0; i < hm.n_hexes; ++i) {
    printf("Hex %zu: ", i);
    for (int k = 0; k < 8; ++k)
        printf("%u ", hm.hex_vertices[8*i+k]);
    printf("\n");
}

// Caller is responsible for freeing
free(hm.vpos);
free(hm.hex_vertices);
```
```

--------------------------------

### HexHex Command Line Tool Usage

Source: https://github.com/cgg-bern/libhexhex/blob/main/README.md

Use the HexHex command-line tool to extract hexahedral meshes. Specify input and output files using `--in` and `--out-hex` flags. Supported formats include .ovmb.

```console
HexHex --in TetMesh.ovmb --out-hex HexMesh.ovmb
```

--------------------------------

### Define and Link Test Executable

Source: https://github.com/cgg-bern/libhexhex/blob/main/tests/CMakeLists.txt

Defines the unit test executable and links it against the main library and the Google Test framework.

```cmake
add_executable(hexhex_unittests
    cellextraction_test.cc
    common.cc
    c_api_test.cc
    gridisomorphism_test.cc
    predicate_test.cc
    navigation_test.cc
    unittest.cc
    )
target_link_libraries(hexhex_unittests PUBLIC GTest::gtest_main)
target_link_libraries(hexhex_unittests PUBLIC HexHex::HexHex)
```

--------------------------------

### Saving Output to File

Source: https://github.com/cgg-bern/libhexhex/blob/main/README.md

Illustrates how to save the extracted hexahedral mesh to different file formats using `saveOutputToFile`.

```APIDOC
## Saving the Output to a File

The output hex mesh can be stored to the .ovm, .ovmb or to .mesh format.

```cpp
bool successful_saving = HexHex::saveOutputToFile(filename, *result.hex_mesh);
```
```

--------------------------------

### Configure Hex Mesh Extraction

Source: https://github.com/cgg-bern/libhexhex/blob/main/README.md

Create and modify a `HexHex::Config` object to customize runtime parameters for `extractHexMesh`. Options include enabling piecewise linear edge/face extraction and setting the number of threads.

```cpp
auto config = HexHex::Config();
config.extract_piecewise_linear_edges = true; // (default false)
config.extract_piecewise_linear_edges = true; // (default false)
config.num_threads = 8; // (default 1)
...
HexHex::extractHexMesh(tetmesh, igm, config);
```

--------------------------------

### HexExtractor Constructor with HalfFacePropertyT

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Initializes the HexExtractor using a tetrahedral mesh and its HalfFacePropertyT IGM.

```APIDOC
### Constructor with `HalfFacePropertyT`

```cpp
#include <HexHex/HexExtractor.hh>

HexHex::TetrahedralMesh tetmesh = /* ... build or load tet mesh ... */;
HexHex::HFParam igm = tetmesh.request_halfface_property<HexHex::Vec3d>(
    HexHex::PropertyNames::HexHexParam);
// ... fill igm values ...

HexHex::HexExtractor he(tetmesh, igm);

bool ok = he.extract(HexHex::Config{
    .extract_piecewise_linear_edges = false,
    .extract_piecewise_linear_faces = false,
    .verbose      = true,
    .num_threads  = 4,
    .igm_scaling_factor = 1,
});

if (ok && !he.hasDetectedError()) {
    const HexHex::HexahedralMesh& out = he.getOutputMesh();
    std::cout << "Extracted " << out.n_cells() << " hex cells\n";

    // Take ownership of output mesh
    auto hexmesh_ptr = he.takeOutputMesh();

    // Access the JSON report
    auto report = he.getHexHexReport();
    std::cout << report.dump(4) << "\n";
}
```
```

--------------------------------

### HexExtractor with HalfFaceProperty

Source: https://github.com/cgg-bern/libhexhex/blob/main/README.md

Instantiate the `HexExtractor` with an OVM tetrahedral mesh and a `HalfFaceProperty<HexHex::Vec3d>` for the IGM.

```cpp
HexHex::TetrahedralMesh tetmesh = ...
HexHex::HalfFaceProp<HexHex::Vec3d> igm = ...
HexHex::HexExtractor he(tetmesh, igm);
auto result = he.extract();
```

--------------------------------

### Config Object for Extraction

Source: https://github.com/cgg-bern/libhexhex/blob/main/README.md

Explains how to use the `Config` object to customize runtime parameters for mesh extraction, such as enabling piecewise linear edge extraction or setting the number of threads.

```APIDOC
## Config Object

The extract methods can take in an optional config object containing some runtime parameters.

```cpp
auto config = HexHex::Config();
config.extract_piecewise_linear_edges = true; // (default false)
config.extract_piecewise_linear_edges = true; // (default false)
config.num_threads = 8; // (default 1)
...
HexHex::extractHexMesh(tetmesh, igm, config);
```
```

--------------------------------

### loadInputFromFile

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Loads a tetrahedral mesh and its IGM from a file. Supported formats include .hexex, .ovm, and .ovmb. Returns an optional ParametrizedMesh.

```APIDOC
## loadInputFromFile()

Loads a tet mesh plus its IGM from a file. Supported formats: `.hexex`, `.ovm`, `.ovmb`.

```cpp
#include <HexHex/Utils/FileAccessor.hh>

// Returns std::optional<HexHex::ParametrizedMesh>
auto result = HexHex::loadInputFromFile("mesh.hexex");
if (!result.has_value()) {
    std::cerr << "Load failed\n";
    return 1;
}
HexHex::TetrahedralMesh& tetmesh = result->mesh;
HexHex::HFParam&         igm     = result->igm;

std::cout << "Loaded " << tetmesh.n_vertices() << " vertices, "
          << tetmesh.n_cells() << " tets\n";

// For .ovm / .ovmb files the mesh must contain a persistent
// HalfFacePropertyT<Vec3d> named HexHex::PropertyNames::HexHexParam
```
```

--------------------------------

### Save Hex Mesh to File

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Write a generated `HexahedralMesh` to a file using `saveOutputToFile`. Supports binary `.ovmb` (recommended), ASCII `.ovm`, and `.mesh` formats.

```cpp
#include <HexHex/Utils/FileAccessor.hh>

// Binary OVM format (recommended – compact and preserves all properties)
bool ok = HexHex::saveOutputToFile("output.ovmb", *result.hex_mesh);

// ASCII OVM format
ok = HexHex::saveOutputToFile("output.ovm", *result.hex_mesh);

// Medit .mesh format (1-based vertex indices, standard for FEM tools)
ok = HexHex::saveOutputToFile("output.mesh", *result.hex_mesh);

if (!ok) {
    std::cerr << "Failed to save hex mesh\n";
}
```

--------------------------------

### Save Output Hex Mesh to File

Source: https://github.com/cgg-bern/libhexhex/blob/main/README.md

Save the extracted hex mesh to a file in .ovm, .ovmb, or .mesh format.

```cpp
bool successful_saving = HexHex::saveOutputToFile(filename, *result.hex_mesh);
```

--------------------------------

### Simple Hex Mesh Extraction

Source: https://github.com/cgg-bern/libhexhex/blob/main/README.md

Demonstrates the basic usage of the `extractHexMesh` function to convert a tetrahedral mesh and an integer grid map into a hexahedral mesh.

```APIDOC
## Simple Use Case

To extract a Hex Mesh, simply call
```cpp
HexHex::TetrahedralMesh tetmesh = ...
HexHex::HalfFaceProp<HexHex::Vec3d> igm = ...
auto result = HexHex::extractHexMesh(tetmesh, igm);
```
using a OpenVolumeMesh as input. In the igm property, each (non-boundary) halfface is expected to store the vertex parameter of its opposing vertex in its incident cell.
```

--------------------------------

### Configure Runtime Parameters for HexHex

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Set various tunable parameters for the HexHex extraction process. These control aspects like edge and face extraction, verbosity, threading, and sanitization.

```cpp
#include <HexHex/Config.hh>

HexHex::Config config;

config.extract_piecewise_linear_edges = false; // extract PWL edge arcs (default: false)
config.extract_piecewise_linear_faces = false; // extract PWL face patches; also enables edges (default: false)
config.verbose                        = true;  // print progress to stdout (default: true)
config.num_threads                    = 4;     // OpenMP thread count (default: 1)
config.igm_scaling_factor             = 2;     // scale IGM by N -> N³× more hex cells (default: 1)
config.sanitize_igm                   = true;  // enforce IGM validity constraints (default: true, highly recommended)
config.sanitization_epsilon           = 1e-2;  // warn if a parameter is moved by ≥ this amount (default: 1e-2)
config.assert_igm_validity            = true;  // validate IGM after sanitization (default: true)
config.rasterization_epsilon          = 1e-6;  // tet inflation for rasterization (default: 1e-6)
config.hf_transition_prop_name        = "HalffaceTransiton"; // AlgoHex property name for transitions
config.e_valence_prop_name            = "edge_valance";      // AlgoHex property name for edge valences

```

--------------------------------

### Error Handling - HexHexMessage and HexExtractor::hasDetectedError()

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Explains how errors and warnings are reported using the `HexHexMessage` hierarchy and accessed via `HexExtractor::hasDetectedError()`.

```APIDOC
## Error Handling – `HexHexMessage` and `HexExtractor::hasDetectedError()`

Errors and warnings are reported through the `HexHexMessage` hierarchy and printed to `stderr`. Fatal errors set an error flag accessible via `hasDetectedError()`.

```cpp
#include <HexHex/Utils/HexHexError.hh>
#include <HexHex/HexExtractor.hh>

HexHex::HexExtractor he(tetmesh, igm);
he.extract(config);

if (he.hasDetectedError()) {
    std::cerr << "Extraction encountered errors – output mesh may be incomplete\n";
}

// Error message types emitted internally:
// HHM_FlippedOrDegenerateTet     – invalid input (Error)
// HHM_LargeSanitizationFix       – large IGM correction (Warning)
// HHM_IsolatedTetVertex          – disconnected vertex in input (Error)
// HHM_MissingHexVertex           – algorithm failed to place a vertex (Error)
// HHM_DuplicateHexVertex(ch)     – duplicate vertex in cell ch (Error)
// HHM_FoundNoOppositePropeller   – topology tracing failure (Warning)
// HHM_FoundNoOppositeBlade       – topology tracing failure (Warning)
// HHM_PropellerOppositesDifferentBlades(l1, l2) – blade count mismatch (Warning)
```
```

--------------------------------

### HexHex::extractHexMesh()

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

The high-level C++ entry point for mesh extraction. It internally creates a HexExtractor, runs the full pipeline, and returns the results.

```APIDOC
## `extractHexMesh()` – High-Level C++ Entry Point

The recommended single-call API. Constructs a `HexExtractor` internally, runs the full pipeline, and returns an `HexHexOutput`.

```cpp
#include <HexHex/HexHex.hh>
#include <HexHex/Utils/FileAccessor.hh>

// --- Load a parametrized tet mesh from file ---
auto maybe_mesh = HexHex::loadInputFromFile("my_tetmesh.hexex");
if (!maybe_mesh.has_value()) {
    std::cerr << "Could not load input\n";
    return 1;
}

// --- Configure ---
HexHex::Config config;
config.num_threads  = 8;
config.igm_scaling_factor = 1;
config.extract_piecewise_linear_faces = true; // also enables edges

// --- Extract ---
auto result = HexHex::extractHexMesh(maybe_mesh->mesh, maybe_mesh->igm, config);

// --- Use results ---
if (result.success) {
    HexHex::saveOutputToFile("output.ovmb", *result.hex_mesh);

    if (result.piecewise_linear_mesh) {
        OpenVolumeMesh::IO::ovmb_write("output_pwl.ovmb",
                                       *result.piecewise_linear_mesh);
    }
    std::cout << result.report.dump(4) << "\n"; // JSON report with timings
}
```
```

--------------------------------

### HexExtractor with Integer Grid Map Template

Source: https://github.com/cgg-bern/libhexhex/blob/main/README.md

Instantiate the `HexExtractor` with an OVM tetrahedral mesh and a template integer grid map. The IGM must implement subscript operators for cell and vertex handles.

```cpp
HexHex::TetrahedralMesh tetmesh = ...
IntegerGridMapT igm = ...
HexHex::HexExtractor he(tetmesh, igm);
auto result = he.extract();
```

--------------------------------

### HexExtractor Constructor with Template IGM

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Initializes the HexExtractor using a tetrahedral mesh and a cell-indexed map type for the IGM.

```APIDOC
### Constructor with Template IGM (CellVertexMap)

```cpp
// Any type where igm[CellHandle][VertexHandle] -> Vec3d works:
OVM::CellPropertyT<std::map<HexHex::VertexHandle, HexHex::Vec3d>> cell_igm_prop =
    tetmesh.request_cell_property<std::map<HexHex::VertexHandle, HexHex::Vec3d>>("my_igm");
// ... populate cell_igm_prop ...

HexHex::HexExtractor he(tetmesh, cell_igm_prop);
he.extract();
```
```

--------------------------------

### Set Public Compile Options for HexHex CLI

Source: https://github.com/cgg-bern/libhexhex/blob/main/tools/HexHex/CMakeLists.txt

Applies public compile options to the HexHex CLI target. These options will be propagated to targets that link against HexHex_cli.

```cmake
target_compile_options(HexHex_cli PUBLIC)
```

--------------------------------

### HexHex Core Types and Typedefs

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

This section details the core types and typedefs available in the HexHex namespace, which are aliases for OpenVolumeMesh classes and handle types.

```APIDOC
## Core Types and Typedefs

All public types live in the `HexHex` namespace. They alias OpenVolumeMesh (OVM) classes and OVM handle types.

```cpp
#include <HexHex/Utils/Typedefs.hh>

// Mesh types
HexHex::TetrahedralMesh  tetmesh;   // OVM::TetrahedralGeometryKernel<Vec3d, ...>
HexHex::HexahedralMesh   hexmesh;   // OVM::GeometryKernel<Vec3d, HexahedralMeshTopologyKernel>
HexHex::PolyhedralMesh   pwlmesh;   // OVM::GeometryKernel<Vec3d, TopologyKernel>

// Vector and parameter types
HexHex::Vec3d    pos(1.0, 2.0, 3.0);   // 3D double vector (position or IGM parameter)
HexHex::Vec3i    idx(1, 2, 3);          // 3D integer vector
HexHex::Parameter p = pos;              // alias for Vec3d – IGM parameter value

// Handle types (wrappers around integer indices)
HexHex::VertexHandle   vh;
HexHex::EdgeHandle     eh;
HexHex::HalfEdgeHandle heh;
HexHex::FaceHandle     fh;
HexHex::HalfFaceHandle hfh;
HexHex::CellHandle     ch;

// IGM half-face property (input format expected by extractHexMesh)
// Each (non-boundary) halfface stores the parameter of the vertex opposite to it
// within its incident tet cell.
HexHex::HFParam igm = tetmesh.request_halfface_property<HexHex::Vec3d>(
    HexHex::PropertyNames::HexHexParam);
```
```

--------------------------------

### Define HexHex CLI Executable

Source: https://github.com/cgg-bern/libhexhex/blob/main/tools/HexHex/CMakeLists.txt

Defines the main executable for the HexHex CLI tool and links necessary libraries. Ensure OpenVolumeMesh, HexHex, and CLI11 are available as CMake targets.

```cmake
cmake_minimum_required(VERSION 3.14)

add_executable (HexHex_cli main.cc)
target_link_libraries(HexHex_cli OpenVolumeMesh::OpenVolumeMesh HexHex::HexHex CLI11::CLI11)
```

--------------------------------

### HexHex Version Macros

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Access HexHex version information using predefined macros. These macros are generated at build time and can be used for static assertions or to display the version string.

```cpp
#include <HexHex/Config/Version.hh>  // generated at build time from Version.hh.in

static_assert(HEXHEX_VERSION_MAJOR == 0);
static_assert(HEXHEX_VERSION_MINOR == 5);
static_assert(HEXHEX_VERSION_PATCH == 0);

std::cout << "HexHex version: " << HEXHEX_VERSION << "\n"; // "0.5.0"

```

--------------------------------

### saveOutputToFile

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Writes an HexahedralMesh to a file. Supported formats include .ovm, .ovmb (binary), and .mesh. Returns a boolean indicating success.

```APIDOC
## saveOutputToFile()

Writes an `HexahedralMesh` to file. Supported formats: `.ovm`, `.ovmb` (binary), `.mesh`.

```cpp
#include <HexHex/Utils/FileAccessor.hh>

// Binary OVM format (recommended – compact and preserves all properties)
bool ok = HexHex::saveOutputToFile("output.ovmb", *result.hex_mesh);

// ASCII OVM format
ok = HexHex::saveOutputToFile("output.ovm", *result.hex_mesh);

// Medit .mesh format (1-based vertex indices, standard for FEM tools)
ok = HexHex::saveOutputToFile("output.mesh", *result.hex_mesh);

if (!ok) {
    std::cerr << "Failed to save hex mesh\n";
}
```
```

--------------------------------

### createCube

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Generates a parametrized tetrahedral mesh representing a cube. Useful for testing and prototyping.

```APIDOC
## createCube

Built-in parametrized mesh generators for testing and prototyping.

```cpp
#include <HexHex/Utils/TestMeshes.hh>

// Create a cube tet mesh of T×T×T×6 tets whose IGM maps to H×H×H hex cells
unsigned int T = 2; // tet grid resolution
unsigned int H = 3; // desired hex grid resolution
HexHex::ParametrizedMesh cube = HexHex::createCube(T, H);

std::cout << "Tets: " << cube.mesh.n_cells() << "\n"; // 2*2*2*6 = 48

// Extract the hex mesh from it
auto result = HexHex::extractHexMesh(cube.mesh, cube.igm);
std::cout << "Hexes: " << result.hex_mesh->n_cells() << "\n"; // H^3 = 27
```
```

--------------------------------

### Low-Level Hex Extraction with HexExtractor (CellVertexMap)

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

An alternative constructor for `HexExtractor` that accepts any cell-indexed map type implementing `map[CellHandle][VertexHandle] -> Vec3d` for the input mesh's IGM.

```cpp
// Any type where igm[CellHandle][VertexHandle] -> Vec3d works:
OVM::CellPropertyT<std::map<HexHex::VertexHandle, HexHex::Vec3d>> cell_igm_prop = 
    tetmesh.request_cell_property<std::map<HexHex::VertexHandle, HexHex::Vec3d>>("my_igm");
// ... populate cell_igm_prop ...

HexHex::HexExtractor he(tetmesh, cell_igm_prop);
he.extract();

```

--------------------------------

### Error Handling: Checking for Extraction Errors

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Demonstrates how to check for errors during mesh extraction using HexExtractor::hasDetectedError(). Errors and warnings are printed to stderr.

```cpp
#include <HexHex/Utils/HexHexError.hh>
#include <HexHex/HexExtractor.hh>

HexHex::HexExtractor he(tetmesh, igm);
he.extract(config);

if (he.hasDetectedError()) {
    std::cerr << "Extraction encountered errors – output mesh may be incomplete\n";
}

// Error message types emitted internally:
// HHM_FlippedOrDegenerateTet     – invalid input (Error)
// HHM_LargeSanitizationFix       – large IGM correction (Warning)
// HHM_IsolatedTetVertex          – disconnected vertex in input (Error)
// HHM_MissingHexVertex           – algorithm failed to place a vertex (Error)
// HHM_DuplicateHexVertex(ch)     – duplicate vertex in cell ch (Error)
// HHM_FoundNoOppositePropeller   – topology tracing failure (Warning)
// HHM_FoundNoOppositeBlade       – topology tracing failure (Warning)
// HHM_PropellerOppositesDifferentBlades(l1, l2) – blade count mismatch (Warning)

```

--------------------------------

### Create and Use ParametrizedMesh Container

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Use the `ParametrizedMesh` struct to conveniently bundle a tetrahedral mesh and its IGM. It can be constructed manually or obtained from mesh generators.

```cpp
#include <HexHex/Utils/ParametrizedMesh.hh>

// Constructing manually:
HexHex::TetrahedralMesh mesh;
HexHex::HFParam igm = mesh.request_halfface_property<HexHex::Vec3d>(
    HexHex::PropertyNames::HexHexParam);
mesh.set_persistent(igm);

// ... populate mesh and igm ...

HexHex::ParametrizedMesh pm(std::move(mesh), std::move(igm));

// Pass directly to extraction:
auto output = HexHex::extractHexMesh(pm.mesh, pm.igm);
```

--------------------------------

### Save Parametrized Tet Mesh to .hexex

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

Serialize a tetrahedral mesh and its IGM to the plain-text `.hexex` format using `saveInputToHEXEX`. This format is human-readable and suitable for debugging.

```cpp
#include <HexHex/Utils/FileAccessor.hh>

HexHex::TetrahedralMesh tetmesh = /* ... */;
HexHex::HFParam         igm     = /* ... */;

bool ok = HexHex::saveInputToHEXEX("exported.hexex", tetmesh, igm);
if (!ok) {
    std::cerr << "Failed to save .hexex file\n";
}

/*
 * .hexex plain-text format:
 *
 * <n_vertices>
 * x0 y0 z0
 * ...
 * <n_cells>
 * v0 v1 v2 v3  px0 py0 pz0  px1 py1 pz1  px2 py2 pz2  px3 py3 pz3
 * ...
 *
 * Each cell line: 4 vertex indices followed by 4 IGM parameter triples
 * (parameter of vertex i = value stored on halfface opposite to vertex i).
 */
```

--------------------------------

### HexHex::Config Structure

Source: https://context7.com/cgg-bern/libhexhex/llms.txt

The Config struct holds all tunable parameters for the hex extraction process. It can be serialized to JSON and loaded from a file.

```APIDOC
## `struct Config` – Runtime Parameters

`Config` controls every tunable aspect of the extraction. It is JSON-serializable via `nlohmann::json` and can be loaded from a `.json` file with `loadConfig()`.

```cpp
#include <HexHex/Config.hh>

HexHex::Config config;

config.extract_piecewise_linear_edges = false; // extract PWL edge arcs (default: false)
config.extract_piecewise_linear_faces = false; // extract PWL face patches; also enables edges (default: false)
config.verbose                        = true;  // print progress to stdout (default: true)
config.num_threads                    = 4;     // OpenMP thread count (default: 1)
config.igm_scaling_factor             = 2;     // scale IGM by N -> N³× more hex cells (default: 1)
config.sanitize_igm                   = true;  // enforce IGM validity constraints (default: true, highly recommended)
config.sanitization_epsilon           = 1e-2;  // warn if a parameter is moved by >= this amount (default: 1e-2)
config.assert_igm_validity            = true;  // validate IGM after sanitization (default: true)
config.rasterization_epsilon          = 1e-6;  // tet inflation for rasterization (default: 1e-6)
config.hf_transition_prop_name        = "HalffaceTransiton"; // AlgoHex property name for transitions
config.e_valence_prop_name            = "edge_valance";      // AlgoHex property name for edge valences
```
```