# How to Integrate AutoRemesher as a Library into Your Custom Application

> Integrate AutoRemesher as a C++ library into your custom application. Learn how to include the header, link dependencies, and instantiate the AutoRemesher class for mesh processing.

- Repository: [Jeremy HU/autoremesher](https://github.com/huxingyi/autoremesher)
- Tags: how-to-guide
- Published: 2026-07-11

---

**You can integrate AutoRemesher as a static or shared C++ library by including the `<AutoRemesher/autoremesher.h>` header, linking against its third-party dependencies (Geogram, libigl, isotropicremesher, and Intel TBB), and instantiating the `AutoRemesher` class with your vertex and triangle data.**

The **huxingyi/autoremesher** repository provides a standalone automatic quad remeshing engine designed for integration into custom pipelines. While the project ships with a reference GUI, its core functionality is exposed through a minimal C++ API in the `AutoRemesher` namespace, allowing you to integrate AutoRemesher as a library into game engines, DCC tools, or batch processing applications without pulling in heavy UI dependencies.

## Understanding the AutoRemesher Library Architecture

### Core Public Interface

The public API surface is intentionally small to simplify integration. According to the source code in `huxingyi/autoremesher`, you only need to include four primary headers located in `src/AutoRemesher/`:

- **[`autoremesher.h`](https://github.com/huxingyi/autoremesher/blob/main/autoremesher.h)** – Defines the main `AutoRemesher` class, which handles configuration, execution, and result access.
- **[`vector3.h`](https://github.com/huxingyi/autoremesher/blob/main/vector3.h)** – Provides the `Vector3` type used for all input and output geometry.
- **[`vector2.h`](https://github.com/huxingyi/autoremesher/blob/main/vector2.h)** – Supplies 2-D vector utilities used internally by parameterization helpers.
- **[`quadextractor.h`](https://github.com/huxingyi/autoremesher/blob/main/quadextractor.h)** – Exposes the `QuadExtractor` helper that generates clean quad topology from the internal mesh.

The engine wraps the underlying isotropic remeshing algorithm via [`src/AutoRemesher/isotropicremesher.h`](https://github.com/huxingyi/autoremesher/blob/main/src/AutoRemesher/isotropicremesher.h), which provides a bridge to the third-party **isotropicremesher** library shipped in `thirdparty/isotropicremesher/`.

### Third-Party Dependencies

When you integrate AutoRemesher as a library, you must link against the following components bundled under `thirdparty/`:

- **Geogram** – Geometry processing utilities (mesh structures, AABB trees).
- **libigl** – Topology checking and mesh processing helpers.
- **isotropicremesher** – The core isotropic remeshing algorithm.
- **Intel TBB** – Parallel execution framework required for multi-threading.

All headers are referenced transitively through [`autoremesher.h`](https://github.com/huxingyi/autoremesher/blob/main/autoremesher.h), but your build system must link the compiled binaries for TBB and the remeshing libraries.

## Step-by-Step Integration Workflow

### Step 1: Prepare Input Geometry

The `AutoRemesher` constructor expects two standard vectors: vertices as `std::vector<AutoRemesher::Vector3>` and triangles as `std::vector<std::vector<size_t>>`. The `Vector3` type is defined in [`src/AutoRemesher/vector3.h`](https://github.com/huxingyi/autoremesher/blob/main/src/AutoRemesher/vector3.h) and is compatible with raw float arrays.

```cpp
#include <AutoRemesher/autoremesher.h>
#include <vector>

// Load your mesh data (example: parsing an OBJ file)
std::vector<AutoRemesher::Vector3> verts = {
    {0.0f, 0.0f, 0.0f},
    {1.0f, 0.0f, 0.0f},
    {1.0f, 1.0f, 0.0f}
};
std::vector<std::vector<size_t>> tris = {
    {0, 1, 2}
};

// Instantiate the remesher
AutoRemesher::AutoRemesher remesher(verts, tris);

```

### Step 2: Configure Remeshing Parameters

The `AutoRemesher` class exposes setters to control the algorithm before execution:

- **`setTargetTriangleCount(size_t)`** – Desired output triangle count before quad extraction.
- **`setScaling(double)`** – Uniform scale factor applied to the input geometry.
- **`setModelType(ModelType)`** – Choose `AutoRemesher::ModelType::Organic` or `Artistic` to tune behavior.
- **`setGradientAdaptivity(double)`** – Controls how the mesh adapts to curvature (default 1.0).
- **`setSharpEdgeDegrees(double)`** – Angle threshold for detecting sharp edges (e.g., 90.0).
- **`setSmoothNormalDegrees(double)`** – Threshold for normal smoothing (e.g., 0.0).

Configure these prior to calling `remesh()`, which triggers the internal pipeline including `initializeVoxelSize()` and `resample()`.

### Step 3: Build and Link the Library

To integrate AutoRemesher as a library, compile the implementation files in `src/AutoRemesher/` into a static or shared library and link against the third-party dependencies. The critical source files are:

- [`src/AutoRemesher/autoremesher.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/AutoRemesher/autoremesher.cpp) (core implementation)
- [`src/AutoRemesher/vector3.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/AutoRemesher/vector3.cpp)
- [`src/AutoRemesher/vector2.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/AutoRemesher/vector2.cpp)
- [`src/AutoRemesher/quadextractor.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/AutoRemesher/quadextractor.cpp)
- [`src/AutoRemesher/parameterizer.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/AutoRemesher/parameterizer.cpp)

## Complete Integration Examples

### Basic Command-Line Application

This minimal example demonstrates the complete workflow from initialization to result extraction:

```cpp
// main.cpp
#include <AutoRemesher/autoremesher.h>
#include <iostream>

// Progress callback (optional)
void progressCallback(void* tag, float progress, const char* status) {
    std::cout << "Progress: " << progress * 100.0f << "% – " << status << '\n';
}

int main() {
    // Load a mesh (replace with your own loader)
    std::vector<AutoRemesher::Vector3> verts = {/* ... */};
    std::vector<std::vector<size_t>> tris = {/* ... */};

    // Create the remesher instance
    AutoRemesher::AutoRemesher remesher(verts, tris);
    remesher.setTargetTriangleCount(50000);   // Desired triangle count
    remesher.setScaling(1.0);                  // No scaling
    remesher.setProgressHandler(progressCallback);
    remesher.setModelType(AutoRemesher::ModelType::Organic);
    remesher.setGradientAdaptivity(1.0);
    remesher.setSharpEdgeDegrees(90.0);
    remesher.setSmoothNormalDegrees(0.0);

    // Run the algorithm
    if (!remesher.remesh()) {
        std::cerr << "Remeshing failed!\n";
        return 1;
    }

    // Retrieve results
    const auto& outVerts = remesher.remeshedVertices();
    const auto& outQuads = remesher.remeshedQuads();

    // …write `outVerts`/`outQuads` to your own file format
    std::cout << "Remeshing succeeded – " << outQuads.size()
              << " quads generated.\n";
    return 0;
}

```

### CMake Build Configuration

Use this [`CMakeLists.txt`](https://github.com/huxingyi/autoremesher/blob/main/CMakeLists.txt) to build AutoRemesher as a static library and link it to your application:

```cmake

# CMakeLists.txt (your project)

cmake_minimum_required(VERSION 3.14)
project(MyApp LANGUAGES CXX)

# -------------------------------------------------

# AutoRemesher – add the source tree as a static lib

# -------------------------------------------------

add_subdirectory(${CMAKE_SOURCE_DIR}/thirdparty/isotropicremesher)
add_subdirectory(${CMAKE_SOURCE_DIR}/thirdparty/geogram)   # optional, if you use its API

add_subdirectory(${CMAKE_SOURCE_DIR}/thirdparty/libigl)    # optional

# Gather the core source files (the .cpp files that implement AutoRemesher)

set(AUTOREMESHER_SRC
    ${CMAKE_SOURCE_DIR}/src/AutoRemesher/autoremesher.cpp   # <‑‑ core implementation

    ${CMAKE_SOURCE_DIR}/src/AutoRemesher/vector3.cpp
    ${CMAKE_SOURCE_DIR}/src/AutoRemesher/vector2.cpp
    ${CMAKE_SOURCE_DIR}/src/AutoRemesher/quadextractor.cpp
    ${CMAKE_SOURCE_DIR}/src/AutoRemesher/parameterizer.cpp
)

add_library(autoremesher STATIC ${AUTOREMESHER_SRC})
target_include_directories(autoremesher PUBLIC
    ${CMAKE_SOURCE_DIR}/include               # Public headers

    ${CMAKE_SOURCE_DIR}/src                   # Private headers

    ${CMAKE_SOURCE_DIR}/thirdparty/isotropicremesher
    ${CMAKE_SOURCE_DIR}/thirdparty/geogram
    ${CMAKE_SOURCE_DIR}/thirdparty/libigl
)
target_link_libraries(autoremesher
    PRIVATE tbb                              # Intel TBB

    PRIVATE isotropicremesher                # third‑party static lib

    # If you use geogram/libigl you may need to link their libs as well

)

# -------------------------------------------------

# Your application

# -------------------------------------------------

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE autoremesher)

```

### Qt GUI Integration

For Qt applications, connect the progress callback to a `QProgressBar` using `QMetaObject::invokeMethod` to ensure thread-safe UI updates:

```cpp
void MyWidget::runRemesher() {
    // …prepare vertices/tris as before
    AutoRemesher::AutoRemesher rm(v, f);
    rm.setProgressHandler([](void* tag, float p, const char* s){
        QMetaObject::invokeMethod(
            static_cast<MyWidget*>(tag),
            [p, s](QProgressBar* bar){
                bar->setValue(static_cast<int>(p * 100));
                bar->setFormat(QString::fromUtf8(s));
            },
            Qt::QueuedConnection,
            Q_ARG(QProgressBar*, progressBar));
    }, this);
    rm.remesh();
}

```

## Key Implementation Details

### The Quad Remeshing Pipeline

When you call `remesh()`, the `AutoRemesher` class executes a four-stage pipeline:

1. **Voxel Size Initialization** – `initializeVoxelSize()` computes an adaptive voxel size based on the average edge length of the input mesh (calculated in `calculateAverageEdgeLength`).
2. **Isotropic Resampling** – `resample()` repeatedly subdivides the mesh to reach the target triangle count while respecting sharp-edge and smooth-normal thresholds. This stage invokes the `IsotropicRemesher` class from the third-party library.
3. **Quad Extraction** – `QuadExtractor` (defined in [`src/AutoRemesher/quadextractor.h`](https://github.com/huxingyi/autoremesher/blob/main/src/AutoRemesher/quadextractor.h)) processes the isotropic result to generate a clean quad-only mesh.
4. **Result Storage** – Final vertices and quads are stored in `remeshedVertices` and `remeshedQuads` vectors, accessible via `remeshedVertices()` and `remeshedQuads()` accessors.

### Progress Reporting Mechanism

The library supports per-thread progress reporting through the `AutoRemesherProgressHandler` callback type. The signature is:

```cpp
void progressCallback(void* userData, float progress, const char* statusMessage);

```

Set your handler using `setProgressHandler(callback, userData)`. The `progress` value ranges from 0.0 to 1.0, and `statusMessage` provides human-readable stage descriptions (e.g., "Resampling", "Extracting quads").

## Summary

- **Include** the `<AutoRemesher/autoremesher.h>` header and link against Intel TBB, isotropicremesher, Geogram, and libigl to integrate AutoRemesher as a library.
- **Instantiate** the `AutoRemesher` class with `std::vector<Vector3>` vertices and `std::vector<std::vector<size_t>>` triangle indices.
- **Configure** the algorithm using setters like `setTargetTriangleCount()`, `setSharpEdgeDegrees()`, and `setModelType()` before calling `remesh()`.
- **Retrieve** results via `remeshedVertices()` and `remeshedQuads()` after successful execution.
- **Implement** an `AutoRemesherProgressHandler` callback to report progress during the pipeline execution.

## Frequently Asked Questions

### What input formats does AutoRemesher support when used as a library?

AutoRemesher does not parse file formats directly. You must load mesh data (e.g., from OBJ, STL, or FBX files) into memory as `std::vector<AutoRemesher::Vector3>` for vertices and `std::vector<std::vector<size_t>>` for face indices, then pass these vectors to the `AutoRemesher` constructor.

### Is the AutoRemesher class thread-safe for processing multiple meshes concurrently?

While AutoRemesher uses Intel TBB internally for parallel computation, individual `AutoRemesher` instances maintain internal state and progress handlers that are not thread-safe across instances. Process different meshes on separate threads by creating one instance per thread, or protect shared instances with external synchronization.

### Can I adjust the quad density after initialization?

Yes. Call `setTargetTriangleCount()` with a new value before invoking `remesh()`. The algorithm will resample the input geometry to match the new target count during the `resample()` phase. You can also call `initializeVoxelSize()` manually if you need to override the automatic voxel size calculation.

### How do I preserve sharp features like creases and corners?

Use `setSharpEdgeDegrees()` to define the dihedral angle threshold (e.g., 90.0 degrees) above which edges are considered sharp. Additionally, adjust `setSmoothNormalDegrees()` to control whether vertex normals are interpolated across those edges. These parameters are respected during the `IsotropicRemesher` phase to ensure geometric fidelity.