How to Use AutoRemesher CLI for Batch Processing: A Complete Guide

AutoRemesher runs in headless mode when you supply the --input flag, allowing you to process OBJ files via command line and script batch operations using standard shell loops.

The AutoRemesher CLI provides a powerful way to automate quad-remeshing workflows without launching the graphical interface. According to the huxingyi/autoremesher source code, the command-line interface is implemented as a standard executable that switches to headless operation when specific flags are detected. This architecture makes AutoRemesher CLI ideal for batch processing large datasets of 3D models.

Understanding the AutoRemesher CLI Architecture

The CLI implementation resides in src/main.cpp, where command-line arguments are parsed and transformed into execution parameters. When the --input (-i) option is present, the program initializes a HeadlessParams struct (defined at lines 54-71 in src/main.cpp) and switches to non-interactive mode.

Headless Mode Activation

The application detects CLI usage through the option parser declared at lines 87-124 in src/main.cpp. Upon detection, it creates a MainWindow object configured for headless operation (line 65) and invokes the runHeadless() method declared at line 9 in src/mainwindow.h. When remeshing completes, the headlessFinished signal emits statistics that are printed to stdout or written to a report file (lines 73-82 in src/main.cpp).

The actual remeshing logic resides in src/AutoRemesher/autoremesher.h and src/AutoRemesher/autoremesher.cpp, which handle parameter validation and algorithm execution independently of the UI layer.

Essential CLI Parameters and Options

AutoRemesher CLI accepts several long-form options to control the remeshing behavior:

• -i / --input: Path to the source OBJ file (triggers headless mode)
• -o / --output: Destination path for the remeshed OBJ file
• --target-quads: Desired number of quadrilateral faces
• --edge-scaling: Scale factor for edge lengths (affects density)
• --sharp-edge: Threshold angle in degrees for preserving sharp edges
• --smooth-normal: Threshold for smooth normal calculation
• --adaptivity: Value between 0 and 1 controlling mesh adaptivity
• --report: Optional path for a plain-text statistics report

Single-File Processing Example

To process a single model with specific quality parameters, invoke the executable with the required input and output paths:

autoremesher \
    -i path/to/input.obj \
    -o path/to/output.obj \
    --target-quads 30000 \
    --edge-scaling 1.5 \
    --sharp-edge 80 \
    --smooth-normal 5 \
    --adaptivity 0.8 \
    --report batch_report.txt

This command reads the input geometry, generates approximately 30,000 quads with the specified edge scaling and sharpness preservation, and writes a completion report to batch_report.txt.

Batch Processing Strategies

Because AutoRemesher CLI operates as a standard executable, you can integrate it into any shell scripting environment. The following patterns demonstrate efficient batch processing across different operating systems.

Bash Loop for Linux and macOS

Process every OBJ file in a directory and store results in a sibling remeshed folder:

#!/usr/bin/env bash
INPUT_DIR=./models
OUT_DIR=./remeshed
mkdir -p "$OUT_DIR"

for src in "$INPUT_DIR"/*.obj; do
    base=$(basename "$src" .obj)
    autoremesher \
        -i "$src" \
        -o "$OUT_DIR/${base}_quad.obj" \
        --target-quads 40000 \
        --edge-scaling 1.2 \
        --sharp-edge 85 \
        --adaptivity 0.9
done

This script iterates through all .obj files, maintaining the base filename while appending _quad to each output.

Windows Batch Processing

For Windows CMD environments, use the following equivalent batch file:

@echo off
set INPUT_DIR=.\models
set OUT_DIR=.\remeshed
if not exist "%OUT_DIR%" mkdir "%OUT_DIR%"

for %%F in ("%INPUT_DIR%\*.obj") do (
    set "NAME=%%~nF"
    autoremesher ^
        -i "%%F" ^
        -o "%OUT_DIR%\%NAME%_quad.obj" ^
        --target-quads 40000 ^
        --edge-scaling 1.2 ^
        --sharp-edge 85 ^
        --adaptivity 0.9
)

Note the use of %%~nF to extract the filename without extension, and the ^ line continuation characters.

Aggregating Reports

To generate a consolidated report across an entire batch, instruct the CLI to write individual reports and concatenate them afterward:

#!/usr/bin/env bash
REPORT=full_report.txt
: > "$REPORT"   # truncate

for src in models/*.obj; do
    out="remeshed/$(basename "$src" .obj)_quad.obj"
    rep="remeshed/$(basename "$src" .obj)_report.txt"
    autoremesher -i "$src" -o "$out" --report "$rep"
    cat "$rep" >> "$REPORT"
    echo "----" >> "$REPORT"
done

This approach creates per-file statistics while building a master log documenting the entire batch operation.

Summary

• AutoRemesher CLI activates headless mode when the --input flag is provided, as implemented in src/main.cpp.
• The CLI architecture separates argument parsing (lines 87-124) from execution via the runHeadless() method in src/mainwindow.h.
• Batch processing relies on standard shell scripting—use Bash for Unix systems and batch files for Windows.
• Quality parameters like --target-quads, --edge-scaling, and --sharp-edge can be adjusted per-job or standardized across an entire batch.
• Report aggregation enables automated quality assurance by combining individual --report outputs into consolidated logs.

Frequently Asked Questions

What input formats does AutoRemesher CLI support?

AutoRemesher CLI currently supports OBJ files as the primary input format. The parser expects standard Wavefront OBJ geometry with vertex positions and face indices. When using batch processing, ensure all files in your input directory have the .obj extension and conform to the specification.

How do I adjust the quality of the remeshing in batch mode?

Modify the --target-quads parameter to control mesh density and --adaptivity to influence how evenly sized the resulting quads appear. For preserving hard edges in mechanical models, increase the --sharp-edge threshold value (measured in degrees). These parameters accept floating-point values and can be passed identically in every iteration of a batch loop.

Can I run AutoRemesher CLI on a server without a display?

Yes. The CLI operates in headless mode when the --input flag is present, requiring no X11, Wayland, or other display server. This design makes it suitable for remote servers and automated render farms. The MainWindow object is instantiated in a non-GUI state specifically to support display-less environments.

Where does the CLI write error messages during batch processing?

Error messages and progress statistics are written to stdout by default. When the --report option is specified, completion statistics are also written to the designated file path. For batch operations, redirect stderr to a log file using 2> errors.log in Bash or 2> errors.txt in Windows batch to capture any processing failures across the entire dataset.

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