What to Do When the AutoRemesher GUI Won't Start: Troubleshooting Guide

When the AutoRemesher GUI won't start, the issue typically stems from missing Qt platform plugins, insufficient OpenGL 3.3 support, or unintentional activation of headless mode via command-line arguments.

The open-source AutoRemesher application by huxingyi/autoremesher provides automatic quad remeshing for 3D models through both a graphical interface and command-line interface. When the GUI fails to launch, the problem usually occurs during the initialization sequence defined in src/main.cpp, before the MainWindow is ever instantiated. Understanding the specific failure points in the startup code helps you resolve environment configuration issues quickly.

Common Causes of Startup Failure

Missing Qt Platform Plugins (Linux)

The application aborts immediately if Qt cannot load its platform plugin, typically xcb on Linux systems. In src/main.cpp at line 22, the code creates the QApplication instance: QApplication app(argc, argv);. If the platform plugin is missing, the process terminates here with an error like "Could not find or load the Qt platform plugin 'xcb'" before reaching the MainWindow constructor.

OpenGL 3.3 Compatibility Issues

AutoRemesher requires an OpenGL 3.3 core profile context. The code in src/main.cpp (lines 33-36) explicitly sets this requirement:

QSurfaceFormat format;
format.setVersion(3, 3);
format.setProfile(QSurfaceFormat::OpenGLContextProfile::CoreProfile);
QSurfaceFormat::setDefaultFormat(format);

If your graphics driver cannot provide OpenGL 3.3, the window creation fails and the program exits silently.

Accidental Headless Mode Activation

Supplying the --input argument triggers headless mode, which processes models without displaying the GUI. At line 29 of src/main.cpp, the code checks bool headlessMode = parser.isSet("input"); and skips the MainWindow instantiation if this flag is present.

Missing Runtime Libraries

The executable requires Qt5 (Core, Gui, Widgets, OpenGL), system OpenGL libraries, and on Windows, the Visual C++ redistributable. The .pro file lists these dependencies, but missing DLLs or shared objects will prevent startup entirely.

How to Diagnose the Problem

1. Launch from a terminal to capture Qt's error messages printed to stderr. Plugin loading failures and OpenGL initialization errors appear in the console output.

2. Check OpenGL support by running glxinfo | grep "OpenGL version" on Linux or using the OpenGL Extensions Viewer on Windows/macOS. The reported version must be at least 3.3.

3. Test headless mode to verify the binary integrity: run with --input model.obj --output test.obj. If this works but the GUI doesn't, you have a graphics or Qt platform issue.

4. Inspect library dependencies using ldd ./autoremesher | grep Qt on Linux or Dependency Walker on Windows to confirm all Qt libraries are found.

Step-by-Step Solutions

Fix Qt Platform Plugin Errors (Linux)

Install the required XCB plugins and dependencies:

sudo apt-get install libxcb-xinerama0 libxcb-icccm4 libxcb-image0 \
                     libxcb-keysyms1 libxcb-render-util0 libxcb-shape0 \
                     libxcb-xkb1 libqt5gui5 libqt5core5a

If plugins are installed but not found, explicitly set the path:

export QT_QPA_PLATFORM_PLUGIN_PATH=/usr/lib/qt5/plugins/platforms
./autoremesher

Ensure OpenGL 3.3 Support

Linux: Install Mesa drivers for Intel/AMD or proprietary drivers for NVIDIA:

# Intel/AMD

sudo apt-get install mesa-utils libgl1-mesa-dri

# NVIDIA

sudo apt-get install nvidia-driver

Windows: Download the latest drivers from your GPU vendor (NVIDIA, AMD, or Intel).

macOS: Use macOS 10.14+ on Metal-compatible hardware; Qt automatically handles the OpenGL compatibility layer.

Verify Command-Line Arguments

Remove the --input flag if you intend to use the GUI. To run in headless mode intentionally (useful for servers or batch processing):

./autoremesher --input path/to/model.obj \
               --output result.obj \
               --target-quads 40000 \
               --report log.txt

Check Runtime Dependencies

On Linux, verify library resolution:

ldd ./autoremesher | grep -i "not found"

On Windows, place the following DLLs in the same directory as autoremesher.exe:

• Qt5Core.dll
• Qt5Gui.dll
• Qt5Widgets.dll
• Qt5OpenGL.dll

Rebuild with Fallback OpenGL (Advanced)

If you cannot obtain OpenGL 3.3, modify src/main.cpp lines 33-36 to request OpenGL 2.1:

QSurfaceFormat format = QSurfaceFormat::defaultFormat();
format.setProfile(QSurfaceFormat::OpenGLContextProfile::CompatibilityProfile);
format.setVersion(2, 1);
QSurfaceFormat::setDefaultFormat(format);

Recompile with qmake && make. Note that this may reduce visual quality or 3D viewport performance.

Summary

• Missing Qt plugins are the most common Linux startup failure; install libxcb-* packages and verify QT_QPA_PLATFORM_PLUGIN_PATH.
• OpenGL 3.3 is mandatory for the GUI; update drivers or modify src/main.cpp to use OpenGL 2.1 if hardware is incompatible.
• Headless mode bypasses the GUI entirely when using the --input flag; remove this argument to launch the interface.
• Check console output when diagnosing, as Qt prints critical plugin and context errors to stderr before the GUI appears.
• Reference src/main.cpp to understand that initialization fails at QApplication creation (line 22) or OpenGL setup (lines 33-36) before MainWindow loads.

Frequently Asked Questions

Why does AutoRemesher crash immediately without showing a window?

The crash typically occurs during QApplication initialization in src/main.cpp (line 22) when Qt cannot load its platform plugin, or during OpenGL context creation (lines 33-36) if your driver lacks OpenGL 3.3 support. Run the application from a terminal to view the specific error message printed to stderr.

Can I use AutoRemesher without a display or GUI?

Yes. Pass the --input and --output arguments to activate headless mode, as implemented in src/main.cpp at line 29. This is ideal for remote servers or automated pipelines: ./autoremesher --input model.obj --output result.obj --target-quads 50000.

How do I check if my system supports OpenGL 3.3?

On Linux, run glxinfo | grep "OpenGL version". The output must show version 3.3 or higher. On Windows, use the OpenGL Extensions Viewer from the Realtech VR website. macOS users need Metal-compatible hardware running macOS 10.14 or later.

Where are error logs stored if the GUI never appears?

While the LogBrowser in src/mainwindow.cpp (lines 71-76) captures logs for the GUI, startup failures occur before this initialization. However, you can capture early Qt messages by running in headless mode with the --report flag: ./autoremesher --input model.obj --report startup.log. Check this file for initialization errors.

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