How to Enable Adaptivity for Quad Density in AutoRemesher

AutoRemesher supports curvature-based adaptivity for quad density through a floating-point value between 0 (uniform quads) and 1 (maximum refinement), configurable via both the GUI slider and the --adaptivity command-line flag.

AutoRemesher is an open-source automatic quad remeshing library that converts triangular meshes into high-quality quadrilateral meshes. Enabling adaptivity for quad density allows the algorithm to concentrate quad elements in high-curvature regions while using larger quads in flat areas, significantly improving mesh efficiency and detail distribution.

Understanding the Adaptivity Parameter

The adaptivity setting controls how aggressively AutoRemesher varies quad size based on surface curvature. This value is stored as a floating-point number in the range 0 → 1:

• 0.0: Produces uniform quad size across the entire mesh, ignoring curvature entirely.
• 1.0: Full adaptivity, generating finer quads in high-curvature zones and larger quads in flat regions.
• 0.0–1.0: Intermediate scaling where the algorithm raises the curvature-derived scaling factor to the power of -adaptivity.

According to the source code in src/AutoRemesher/parameterizer.cpp, the scaling multiplier is calculated as std::pow(normalized, -m_adaptivity) and clamped between 0.3 and 3.0 to prevent extreme distortion.

Enabling Adaptivity via the GUI

In the graphical interface, the adaptivity control resides in MainWindow as a floating-point slider. The implementation in src/mainwindow.cpp (lines 198–205) defines the widget with a range of 0 to 1 and connects it to the m_adaptivity member variable:

// From src/mainwindow.cpp
m_adaptivityWidget = new QSlider(Qt::Horizontal);
m_adaptivityWidget->setRange(0, 100);  // Represents 0.0 to 1.0
connect(m_adaptivityWidget, &QSlider::valueChanged, this, [=](int value) {
    m_adaptivity = value / 100.0;
});

To enable adaptivity in the GUI, move the Adaptivity slider to the desired level (default is 1.0). The change takes effect on the next remeshing operation.

Enabling Adaptivity via Command Line

For headless operation, AutoRemesher accepts the --adaptivity flag defined in src/main.cpp (lines 22–25). The value is parsed into the HeadlessParams struct (lines 69–70):

// Command-line option declaration in src/main.cpp
options.add_options()
    ("adaptivity", "Adaptivity factor (0-1)", cxxopts::value<double>()->default_value("1.0"));

Run the tool with your desired adaptivity value:

autoremesher -i model.obj -o model_remeshed.obj --adaptivity 0.75

This stores the value in HeadlessParams.adaptivity, which is later passed to the AutoRemesher::Parameters struct consumed by the remeshing engine.

How Adaptivity Influences Quad Generation

The core logic resides in AutoRemesher::Parameterizer::computeFaceScalingField within src/AutoRemesher/parameterizer.cpp. When m_adaptivity is greater than 0, the algorithm:

1. Estimates curvature per vertex from angle differences between adjacent normals (lines 50–66).
2. Computes an average curvature across the mesh (lines 73–77).
3. Calculates a normalized curvature value for each triangle and raises it to the power of -m_adaptivity (line 93).

// Excerpt from src/AutoRemesher/parameterizer.cpp
double normalized = faceCurvature / averageCurvature;
double multiplier = std::pow(normalized, -m_adaptivity);
multiplier = std::clamp(multiplier, minRatio, maxRatio);  // minRatio=0.3, maxRatio=3.0
faceScaling[i] = multiplier;

The resulting faceScaling values drive the quad-cover algorithm, biasing it toward smaller quads where curvature is high and larger quads where curvature is low.

Practical Implementation Examples

Programmatically Setting Adaptivity in C++

To set adaptivity from within a C++ application using the AutoRemesher library:

#include "AutoRemesher/autoremesher.h"

void configureAdaptiveRemeshing(AutoRemesher::Parameters& params) {
    params.adaptivity = 1.0;  // Full curvature adaptivity
}

Headless Batch Processing

Process multiple models with custom adaptivity settings:

# Modest adaptivity for preservation of sharp features

autoremesher -i input.obj -o output.obj --target-quads 40000 --adaptivity 0.3

# High adaptivity for detailed curvature capture

autoremesher -i sculpt.obj -o sculpt_quad.obj --adaptivity 0.9

Accessing the Scaling Computation

When extending the parameterizer, you can inspect the scaling logic directly:

// From src/AutoRemesher/parameterizer.cpp lines 90-97
if (m_adaptivity > 0.0 && !vertices.empty()) {
    double normalized = faceCurvature / averageCurvature;
    double multiplier = std::pow(normalized, -m_adaptivity);
    faceScaling[i] = std::clamp(multiplier, 0.3, 3.0);
}

Summary

• Adaptivity range: Float values from 0.0 (uniform) to 1.0 (full curvature adaptation).
• GUI method: Adjust the Adaptivity slider in MainWindow, implemented in src/mainwindow.cpp (lines 198–205).
• CLI method: Use --adaptivity <value> parsed in src/main.cpp (lines 22–25, 69–70).
• Core logic: Curvature-based scaling occurs in AutoRemesher::Parameterizer::computeFaceScalingField within src/AutoRemesher/parameterizer.cpp, using std::pow(normalized, -m_adaptivity).
• Effect: Values closer to 1.0 produce finer quads in high-curvature regions while maintaining larger elements in flat areas.

Frequently Asked Questions

What is the default adaptivity value in AutoRemesher?

The default adaptivity value is 1.0 (full adaptivity), as defined in the command-line option parser in src/main.cpp and reflected in the GUI slider default state. This ensures maximum detail preservation in curved regions out of the box.

How does adaptivity affect remeshing performance?

Higher adaptivity values (closer to 1.0) may increase computation time slightly due to the additional curvature analysis in computeFaceScalingField, but the primary performance impact comes from the increased quad density in high-curvature regions rather than the scaling calculation itself.

Can I set adaptivity values outside the 0-1 range?

While the GUI constrains values to 0–1 and the CLI uses this range by convention, the underlying std::pow calculation in src/AutoRemesher/parameterizer.cpp technically accepts any float. However, values outside 0–1 produce extreme scaling factors that violate the internal clamping limits (0.3 to 3.0), effectively hitting the clamps and providing no additional benefit.

Which source file contains the curvature calculation logic?

The curvature estimation and scaling factor computation reside in src/AutoRemesher/parameterizer.cpp, specifically within the AutoRemesher::Parameterizer::computeFaceScalingField method (lines 40–99). This function calculates per-vertex curvature from normal angles and applies the adaptivity exponent to generate the final face scaling field.

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