# AutoRemesher GUI Mode vs Headless CLI Mode: Technical Implementation Guide

> Discover the AutoRemesher GUI vs Headless CLI modes. Learn how to implement batch operations and server-side automation with this technical guide.

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

---

**AutoRemesher runs as an interactive Qt application when launched without arguments, but switches to silent background processing when it detects the `--input` flag, enabling batch operations and server-side automation without initializing any graphical widgets.**

The huxingyi/autoremesher repository implements a dual-interface architecture that exposes the same quad mesh remeshing engine through either a visual desktop application or a command-line tool. Understanding the difference between AutoRemesher GUI mode and headless CLI mode helps you choose the appropriate workflow for visual prototyping versus automated pipeline integration.

## How Mode Selection Works

The entry point in [`src/main.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/main.cpp) determines the execution path by checking for the presence of command-line arguments. At line 129, the application evaluates `bool headlessMode = parser.isSet("input");` to decide whether to initialize a `QApplication` with a visible window or to run silently.

If `headlessMode` evaluates to false, the program creates a standard Qt event loop and instantiates the main window. If true, it bypasses the GUI initialization entirely and delegates processing to the headless pipeline. This branching occurs before any mesh data is loaded, ensuring that headless environments never attempt to allocate windowing resources.

## GUI Mode: Interactive Visual Workflow

When you launch the executable without parameters, AutoRemesher initializes a full `QApplication` and constructs the `MainWindow` class as shown at lines 162-175 of [`src/main.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/main.cpp):

```cpp
MainWindow *mainWindow = new MainWindow();
mainWindow->show();

```

In this mode, users interact with **sliders and controls** for parameters like *Target Quads*, *Edge Scaling*, and *Sharp Edge* thresholds. The 3D viewport renders the input mesh and final quad mesh result. Progress indication appears via a `QProgressBar` at the top of the window, with optional Windows taskbar integration.

The GUI workflow follows this sequence:
1. Click **Open** to load an OBJ file through a file dialog
2. Adjust remeshing parameters using visual controls
3. Click **Regenerate** to execute the `QuadMeshGenerator` algorithm on a background thread
4. Visualize results in the viewport and click **Save** to write the output file

## Headless CLI Mode: Automated Batch Processing

Headless mode activates when you provide the `--input` argument. The `parseHeadlessArgs` function at lines 54-71 of [`src/main.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/main.cpp) validates parameters including `--output`, `--target-quads`, `--edge-scaling`, `--sharp-edge`, `--smooth-normal`, `--adaptivity`, and `--report`.

Rather than creating visible widgets, the program instantiates `MainWindow` only as a logic controller and immediately calls `setHeadlessParams` (lines 706-718 in [`src/mainwindow.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/mainwindow.cpp)) to configure the processing pipeline. The `runHeadless()` method (lines 744-792) executes the identical remeshing algorithm used in GUI mode but redirects output to `stdout`.

When processing completes, the `headlessFinished` lambda at lines 165-176 prints a structured report:

```

=== AutoRemesher Report ===
Input: model.obj
Output: result.obj
Quads: 39520
Non-quads: 120
Vertices: 10234
Time: 12.34 seconds
==========================

```

The `saveMeshToFile` function (lines 221-241 in [`src/mainwindow.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/mainwindow.cpp)) handles writing the output mesh to the path specified by `--output`, while optional statistical summaries write to the `--report` file path.

## Key Differences in Implementation

**Initialization Path**
- **GUI mode**: Creates `QApplication`, initializes OpenGL viewport, and enters the Qt event loop
- **Headless mode**: Skips window creation, configures parameters via `setHeadlessParams`, and calls `runHeadless()` directly

**Parameter Input**
- **GUI mode**: Values read from `QSlider` and `QSpinBox` widgets in real-time
- **Headless mode**: Arguments parsed by `parseHeadlessArgs` with validation for required paths

**Progress Reporting**
- **GUI mode**: Visual `QProgressBar` updates and taskbar integration
- **Headless mode**: Textual output to standard output stream upon completion via `headlessFinished`

**File I/O**
- **GUI mode**: `QFileDialog` for manual selection; user triggers save via button click
- **Headless mode**: Automatic read/write using paths provided in `--input` and `--output` flags

## Running AutoRemesher in Both Modes

### Interactive GUI Session

Launch the binary without arguments to open the visual interface:

```bash
./AutoRemesher

```

Once the window appears:
1. Select **File > Open** to load `model.obj`
2. Adjust **Target Quads** to 40000 and **Edge Scaling** to 1.2
3. Click **Regenerate** to process
4. Select **File > Save** to export `remeshed.obj`

### Headless Batch Operation

Execute remeshing without displaying a window:

```bash
./AutoRemesher \
    --input highres_scan.obj \
    --output game_ready.obj \
    --target-quads 50000 \
    --edge-scaling 1.0 \
    --sharp-edge 100 \
    --smooth-normal 30 \
    --adaptivity 0.8 \
    --report statistics.txt

```

This command processes `highres_scan.obj` using the specified topology targets, writes the result to `game_ready.obj`, and saves a detailed metrics report to [`statistics.txt`](https://github.com/huxingyi/autoremesher/blob/main/statistics.txt) without requiring a display server.

## Shared Core Architecture

Both modes utilize the identical remeshing implementation in [`src/quadmeshgenerator.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/quadmeshgenerator.cpp). The `MainWindow` class serves as the abstraction layer: in GUI mode, it responds to user events and slot signals; in headless mode, it functions as a state machine that executes the pipeline sequentially.

The [`src/mainwindow.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/mainwindow.cpp) file contains both the visual event handlers and the headless orchestration methods (`setHeadlessParams` and `runHeadless`), ensuring algorithmic consistency across interfaces. File I/O utilities in [`src/util.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/util.cpp) support both modes with common loading and saving routines.

## Summary

- **AutoRemesher GUI mode** provides an interactive Qt-based environment with real-time parameter adjustment, 3D visualization, and manual file management, ideal for artistic iteration and parameter tuning.
- **Headless CLI mode** disables all graphical components when `--input` is detected, accepting configuration via command-line flags and emitting structured text reports, designed for server deployment and automated asset pipelines.
- Both modes invoke the same `QuadMeshGenerator` algorithm through `MainWindow::runHeadless()` or the GUI's **Regenerate** action, guaranteeing identical mesh output quality regardless of interface.
- The entry point in [`src/main.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/main.cpp) uses `parser.isSet("input")` to branch before window initialization, ensuring headless mode requires no display server or windowing system.

## Frequently Asked Questions

### Can AutoRemesher run on a headless server without a display?

Yes. When launched with the `--input` flag, the application detects headless mode before initializing any `QApplication` windowing resources. The program runs entirely on the CPU without requiring X11, Wayland, or any display server, making it suitable for remote servers and CI/CD environments.

### Does headless CLI mode support all remeshing parameters available in the GUI?

Yes. The `parseHeadlessArgs` function in [`src/main.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/main.cpp) exposes all major parameters including `--target-quads`, `--edge-scaling`, `--sharp-edge`, `--smooth-normal`, and `--adaptivity`. These map directly to the slider controls found in the GUI interface, ensuring feature parity between modes.

### How do I process multiple meshes automatically with AutoRemesher?

Use the headless CLI mode within a shell loop or build system. Because the executable exits with a status code after completing `saveMeshToFile`, you can chain operations: `for f in *.obj; do ./AutoRemesher --input "$f" --output "out/$f"; done`. Each invocation runs independently without GUI overhead, allowing true batch processing.

### Why does the headless mode still instantiate MainWindow if it has no GUI?

The `MainWindow` class serves as the application controller in both modes. In headless operation, it acts as a state manager that holds the `QuadMeshGenerator` instance and file I/O logic through `setHeadlessParams` and `runHeadless()`. This design avoids code duplication while keeping the remeshing algorithm decoupled from Qt's view components.