How to Integrate AutoRemesher as a Library into Your Custom Application

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 – Defines the main AutoRemesher class, which handles configuration, execution, and result access.
• vector3.h – Provides the Vector3 type used for all input and output geometry.
• vector2.h – Supplies 2-D vector utilities used internally by parameterization helpers.
• 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, 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, 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 and is compatible with raw float arrays.

#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 (core implementation)
• src/AutoRemesher/vector3.cpp
• src/AutoRemesher/vector2.cpp
• src/AutoRemesher/quadextractor.cpp
• src/AutoRemesher/parameterizer.cpp

Complete Integration Examples

Basic Command-Line Application

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

// 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 to build AutoRemesher as a static library and link it to your application:

# 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:

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) 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:

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}