A C++ tool for mesh simplification using Quadric Error Metrics (QEM) with UV-aware edge collapses, heightmap baking, and UV island leap-map generation for real-time relief mapping.
relief.cpp takes a high-resolution 3D mesh and produces:
- A simplified mesh via QEM, with configurable UV seam handling strategies.
- A displacement heightmap encoding the signed distance from the simplified surface to the original.
- An offset map (
Offset_Map) that encodes UV-space translations and rotations needed to continue a relief-mapping ray across UV island boundaries.
- QEM Simplification — Garland & Heckbert quadric error minimization with UV coordinates propagated through collapses.
- UV Seam Strategies — Four boundary modes selectable at runtime:
None— no seam constraints.Constraint— soft penalty quadric perpendicular to the seam plane.LockSeamVertices— seam vertices are never collapsed.SyncSeamTwins— paired seam vertices are collapsed in sync, preserving UV continuity.
- Envelope Constraint — optional guarantee that the simplified mesh never protrudes outside the original surface.
- Heightmap Baking — per-texel signed displacement computed in UV space using multi-threaded rasterization.
- Offset Map Baking — per-texel leap data for UV island boundary traversal during relief mapping.
- OBJ and glTF I/O — load and save meshes in both formats (glTF with embedded textures).
- Qt/OpenGL GUI — interactive viewer for the mesh, heightmap, and relief result.
| Dependency | Version | Notes |
|---|---|---|
| CMake | ≥ 3.16 | Build system |
| C++ compiler | C++17 | GCC, Clang, or MSVC |
| Eigen3 | ≥ 3.3 | Auto-fetched if not found |
| TinyGLTF | v2.9.3 | Auto-fetched |
| Qt6 | 6.x | Core, Gui, OpenGL, OpenGLWidgets, Widgets |
| OpenGL | any | System library |
| glm | ≥ 1.0.1 | Auto-fetched if not found |
Qt6 and OpenGL are only required when building the GUI (BUILD_APP=ON, the default).
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)To build only the core library without the Qt GUI:
cmake -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_APP=OFF
cmake --build build -j$(nproc)The resulting executable is build/gui/gui.
Launch the GUI and open an OBJ or glTF mesh. The interface exposes:
- Target face count for simplification.
- UV seam boundary mode.
- Envelope constraint toggle.
- Heightmap resolution and output path.
- Offset map resolution and seam band width (in texels).
- Include UV error in the QEM collapse cost function.
- Use surface curvature to determine the post-collapse UV position instead of linear interpolation.