Free, open-source 3D sculpting for Linux, macOS and Windows: dense meshes, remeshing, painting, built-in AI (image/text to 3D), Send to Unreal, game-ready LODs, Gaussian splats and OpenUSD.
C++ 3d3d-sculptingcppdear-imguidigital-sculptingfbxgame-developmentgaussian-splattinggltfimage-to-3dmcpopenglopenusdsculptingtext-to-3dunreal-engine
// SculptForge - open source digital sculpting
// SPDX-License-Identifier: GPL-3.0-or-later
//
// QRemesh (Tool > Remesh / Tool > Geometry > QRemesh QRemesh): automatic quad retopology. Two
// methods: QRemesh 2, the default (an integer-grid map, core/QRemesh2.cpp), and the legacy one described here,
// which shares the steps around it (symmetry, guides, pieces, attributes). The legacy method is a field-aligned method
// after Instant Field-Aligned Meshes (Jakob, Tarini, Panozzo, Sorkine-Hornung, SIGGRAPH Asia 2015; the
// reference code is BSD-3, this is a fresh implementation of the parts we need):
//
// 1. A multi-resolution hierarchy of the surface's vertex graph (greedy edge matching, ~halving per level).
// 2. A smooth 4-RoSy orientation field (where the quad edges point), solved coarse to fine.
// 3. A position field: per vertex the nearest corner of a local quad lattice with the wanted edge length,
// made consistent across neighbours (also coarse to fine). Size Variation scales the lattice with the
// curvature; vertex paint can ask for more (red) or fewer (blue) polygons.
// 4. Extraction: vertices whose lattice corners coincide merge, lattice-neighbours become edges, the graph's
// faces are traced in each vertex's tangent plane, and every face (quad, or the odd triangle / pentagon
// around a field singularity) is split into quads, so the result is all quads and closed (2-manifold)
// where the sculpt is.
// 5. The quads are relaxed and snapped back onto the sculpt; the target count is met by adjusting the
// lattice size and extracting again.
//
// QRemesh Guides (curves drawn on the surface) constrain the fields the same way: a lattice line along each
// curve, and the orientation turned towards it over a falloff (core/QRemeshGuides.h).
// Follow Face Groups constrains the fields to the face group borders, so edge loops run along them (and the result
// keeps the groups). Symmetry remeshes one half (cut at the plane) and mirrors it, welded on the seam; the plane
// is the model's own (found from it, so a model away from the origin works), and a model that isn't
// mirror-symmetric is remeshed whole instead. Separate pieces are kept: small ones (eyes, rivets) are remeshed
// on their own with a few dozen quads at least. Parts thinner than a quad keep both sides (clusters facing
// apart don't merge) and hard edges keep their loops and corners.
#pragma once
#include "core/Mesh.h"
#include "core/QRemeshGuides.h"
#include <functional>
#include <string>
namespace sf {
class CommandRegistry;
struct Document;
// QRemesh's methods. V2 (the default): a curvature-aligned cross field and an integer-grid map, poles only where
// the field needs them, guides as exact edge loops, the result at the target density (core/QRemesh2.cpp).
// Legacy: the 0.9 method (Instant Meshes style position field, extracted at twice the spacing and split).
enum class QRemeshMethod { V2 = 0, Legacy = 1 };
struct QRemeshOptions {
QRemeshMethod method = QRemeshMethod::V2;
int targetQuads = 5000; // the classic Target Quads Count (here in polygons, not thousands)
float adaptive = 0.5f; // Size Variation: 0 = even quads, 1 = sizes follow the curvature strongly
bool keepGroups = false; // edge loops along face group borders; the result keeps the groups
bool detectEdges = true; // hard edges (faces meeting at more than 50 degrees) get an edge loop
bool useVertexPaint = false; // red vertex paint: up to 4x the density, blue: down to 1/4
int symmetryAxis = -1; // -1 none, 0 X, 1 Y, 2 Z
// The mirror plane's position along the axis. symmetryAuto: the plane is found from the model (the world
// origin's plane when the model is symmetric about it, else the model's own middle, as for an off-centre
// model), otherwise symmetryCenter is used as given.
bool symmetryAuto = true;
float symmetryCenter = 0.0f;
int smoothIterations = 6;
uint32_t seed = 1; // the field's random start (the result is deterministic for a seed)
// QRemesh Guides (core/QRemeshGuides.h), in the source's space: an edge loop runs along each curve and the
// edge flow turns to follow it. guideStrength (Guide Strength, 0..1): how far around a curve the
// flow follows it (0 = only the loop on the curve itself, 1 = about six quads to each side).
std::vector<QRemeshGuide> guides;
float guideStrength = 0.5f;
// Measure the result against the source after remeshing (QRemeshStats::quality): poles, valences, angles and the
// distance to the sculpt. Costs a closest-point query per vertex of both.
bool measureQuality = true;
};
// How good a quad mesh is (the quality report shown after QRemesh).
struct QuadQuality {
size_t vertices = 0, quads = 0, triangles = 0;
size_t poles = 0; // inside vertices with other than four edges
size_t valence[8] = {}; // inside vertices by edge count: [2] .. [6], [7] = 7 or more
size_t boundaryPoles = 0; // vertices on open edges with other than three edges
float angleDeviation = 0.0f; // mean |corner angle - 90| over the quads, degrees
float angleDeviationMax = 0.0f; // 99th percentile, degrees
float edgeLengthCv = 0.0f; // spread of the edge lengths (standard deviation / mean)
float hausdorff = 0.0f; // symmetric Hausdorff distance to the source, in % of the bounding-box diagonal
float meanDistance = 0.0f; // mean distance to the source, same units
bool measured = false; // distances filled in
};
// Valences and angles of `mesh` (faces as exported); with `source`, also the distances to it.
QuadQuality quadQuality(const Mesh& mesh, const Mesh* source = nullptr);
struct QRemeshStats {
size_t quads = 0, triangles = 0; // faces of the result (triangles only for degenerate leftovers)
size_t boundaryEdges = 0, nonManifoldEdges = 0;
int attempts = 0; // extractions run to approach the target count
float edgeLength = 0; // mean quad edge length
int symmetryAxis = -1; // the axis asked for (-1: none)
bool symmetryUsed = false; // false when symmetry was asked for but the model isn't mirror-symmetric
float symmetryCenter = 0.0f; // the plane used (with symmetryUsed)
float asymmetry = 0.0f; // the model's mirror mismatch about that plane, in mean quad edges
size_t pieces = 0; // separate pieces of the source (small ones are remeshed on their own)
size_t guides = 0; // QRemesh Guides used
size_t guidesSkipped = 0; // guides left out: mostly off the surface (the Part moved since)
double seconds = 0;
QRemeshMethod method = QRemeshMethod::V2;
size_t fallbackPieces = 0; // V2: pieces it couldn't do well, remeshed with the legacy method
size_t singularities = 0; // V2: cross-field singularities (poles the layout needs)
QuadQuality quality; // with measureQuality
};
// Fraction 0..1 of the whole job; return false to cancel. Called from the thread running qremesh.
using QRemeshProgress = std::function<bool(float fraction)>;
// Retopologises `source` (its evaluated positions: sculpt layers are baked; hidden parts are remeshed too)
// into `out`: all quads (as triangle pairs, Mesh::quadPartners), mask and vertex paint interpolated from the
// sculpt, face groups with Follow Face Groups. False with `error` set on failure or cancel.
bool qremesh(const Mesh& source, const QRemeshOptions& options, Mesh& out, std::string& error,
const QRemeshProgress& progress = {}, QRemeshStats* stats = nullptr);
// Edge-manifold check used by the tests and the status line: faces as exported (quads counted once).
struct TopologyReport {
size_t faces = 0, quads = 0, triangles = 0;
size_t boundaryEdges = 0; // edges with one face
size_t nonManifoldEdges = 0; // edges with more than two faces, or two faces wound the same way
size_t nonManifoldVertices = 0; // vertices whose faces form more than one fan
bool manifold() const { return nonManifoldEdges == 0 && nonManifoldVertices == 0; }
float quadFraction() const { return faces ? float(quads) / float(faces) : 0.0f; }
};
TopologyReport topologyReport(const Mesh& mesh);
// Puts a qremesh result into the active Part as one undo step. keepOriginal: first a hidden copy of the
// Part as it was goes right below it ("<name> Original"), ready to ProjectAll the detail back from.
// Returns the status message.
std::string applyQRemesh(Document& doc, Mesh result, bool keepOriginal, const QRemeshStats& stats);
// The quality report as text for the status line ("" when empty).
std::string qualitySummary(const QuadQuality& quality);
// qremesh (core/RetopoCommands.cpp) and project_all (core/Projection.h).
void registerRetopoCommands(CommandRegistry& registry);
} // namespace sf