Skip to content

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.

QRemesh 2: feature lines dominate the cross field (light smoothest-field term), feature edges are creases not curvature, virtual lattice nodes merge with a neighbour's; guide page and changelog drafts; benchmark model filter

islandmed606fe974312c
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 067543ea..41e8bc82 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,31 @@ All notable changes to SculptForge are listed here. The format follows
## [Unreleased]
+### Added
+- **QRemesh 2**, the new default quad retopology (**Tool > Remesh > QRemesh**, also under **Tool > Geometry**;
+ `qremesh method=v2`). The layout is solved over the whole model at once as an integer grid: a smooth cross field
+ that follows the principal curvature (smoothed over about one quad) and the feature lines, then a seamless
+ parametrization whose grid lines are the edge loops, with feature lines and guides on grid lines and the poles
+ on grid points, extracted at the target density. Poles appear only where the form needs them (a sphere gets
+ exactly eight, a box one per corner) and loops run unbroken; open QRemesh Guides are exact edge loops; hard
+ edges and polygroup borders (Keep Groups) are kept on their exact place; polypaint density adds the pole pairs a
+ change of density needs; symmetry mirrors the field and the result exactly; the result is deterministic.
+ Loop-aware relaxation lets vertices slide along loops on ridges but not off them. Against the legacy method on
+ the lion scan, the ICT head, a creature sculpted from a sphere and a hard-surface part at 2k / 5k / 10k quads:
+ BENCHSUMMARY
+- **Quality report** after QRemesh, in the status line, the QRemesh panel and the `qremesh` command's message:
+ poles (by valence), how far quad corners are from square, and the distance to the sculpt (mean and Hausdorff).
+ `quality=false` skips the measuring.
+- Dense sculpts are decimated in parallel blocks to a working resolution first: DENSESUMMARY
+- Tests: test_qremesh2.cpp (eight poles on a sphere, determinism, exact symmetry, hard edges and groups, the
+ command); `SF_QREMESH_BENCH=<dir>` runs the comparison with the legacy method and writes the results as OBJ,
+ `SF_BENCH_LIMITS=1` times 1.3M / 5.2M / 21M-triangle sculpts with their peak memory.
+
+### Changed
+- The 0.9 QRemesh is kept as **Method > Legacy** (`qremesh method=legacy`). Closed QRemesh Guide loops (round an
+ eye, or across the symmetry plane) still use it for that piece for now, and a piece QRemesh 2 can't do cleanly
+ falls back to it; the status line says so.
+
## [0.9.7] - 2026-10-31
Speed first: big brushes on dense meshes take a third less time per frame, trail the pen by half as far and no
diff --git a/docs/guide/retopology.md b/docs/guide/retopology.md
index 0937b625..d0e214dc 100644
--- a/docs/guide/retopology.md
+++ b/docs/guide/retopology.md
@@ -10,7 +10,8 @@ animate.
## The usual workflow
-1. Select the sculpt and open **Tool > Geometry**. Under **QRemesh**, turn on **Keep Original**.
+1. Select the sculpt and open **Tool > Remesh** (the same QRemesh controls are also under **Tool > Geometry**).
+ Under **QRemesh**, turn on **Keep Original**.
2. Set **Target Polygons** (for example 5000) and click **QRemesh**. It runs in the background: a progress bar
replaces the button, and **Cancel** stops it. The result replaces the SubTool, and the sculpt as it was is
kept as a hidden SubTool called "*name* Original" right below it.
@@ -25,11 +26,12 @@ Both steps are single undo steps (<kbd>Ctrl</kbd>+<kbd>Z</kbd>).
## QRemesh
-**Tool > Geometry > QRemesh** works on the active SubTool.
+**Tool > Remesh > QRemesh** (also under **Tool > Geometry**) works on the active SubTool.
| Control | What it does |
|---|---|
-| **QRemesh** | Starts the retopology. The status line reports the result, e.g. "QRemesh: 4987 quads from 47214 triangles (100% quads) in 1.0 s" |
+| **QRemesh** | Starts the retopology. The status line reports the result and its quality, e.g. "QRemesh: 5072 quads from 47214 triangles (100% quads) in 6.5 s. Quality: 260 poles (141 x3, 113 x5, 6 other), corners 8.5 deg off square, distance to the sculpt 0.106% mean / 1.27% max of its size" |
+| **Method** | **QRemesh 2** (the default): the whole layout is solved at once as an integer grid, so poles appear only where the form needs them and loops run unbroken. **Legacy**: the method of SculptForge 0.9, kept for comparison and for closed guide loops |
| **Target Polygons** | About how many quads to make (100 to 200,000 on the slider, more from scripts). The result is usually within 5% of it |
| **Half / Same / Double** | Set the target to half, the same as or twice the SubTool's current polygon count |
| **Adaptive Size** | 0 makes quads all about the same size. Higher values make smaller quads where the surface curves and bigger ones on flat areas, for the same total |
@@ -42,6 +44,7 @@ Both steps are single undo steps (<kbd>Ctrl</kbd>+<kbd>Z</kbd>).
| **QRemesh Guides** | Picks the guides brush: draw curves on the model for the edge loops to follow. See [QRemesh Guides](#qremesh-guides) |
| **Delete Last** / **Clear** | Delete the last guide curve drawn (with its mirror copies), or all of them |
| **Curves Strength** | How far around each guide the edge flow follows it: 0 = only the loop on the curve, 100 = about six quads to each side (default 50) |
+| **Quality Report** | Shown after a QRemesh of the active SubTool: the poles (vertices with other than four edges, by how many edges), how far quad corners are from square (mean and worst 1%), and how far the new surface is from the sculpt (mean and maximum, in % of its size) |
What happens to your data:
@@ -75,11 +78,41 @@ What happens to your data:
### How it works
-QRemesh is a field-aligned method after *Instant Field-Aligned Meshes* (Jakob, Tarini, Panozzo and
-Sorkine-Hornung, 2015). It smooths a cross field (the directions the quad edges should take) over the surface
-from coarse to fine, places a grid of the wanted size along it, extracts the polygons where neighbouring grid
-corners meet, splits every polygon into quads and relaxes them back onto the sculpt. It is fast: about 2 seconds
-for a 1.3-million-triangle sculpt to 5,000 quads, and 6 seconds to 100,000 quads, on a 10-core desktop.
+QRemesh 2 builds the layout the way recent research quad remeshers do (integer-grid maps, as in *Mixed-Integer
+Quadrangulation*, Bommes, Zimmer and Kobbelt 2009, and *Integer-Grid Maps for Reliable Quad Meshing*, Bommes et
+al. 2013), in its own implementation:
+
+1. **A working surface.** The sculpt is brought to about three triangle edges per quad edge with even
+ triangles (dense sculpts are first decimated in parallel blocks), keeping open edges, polygroup borders
+ (**Keep Groups**) and real hard edges (**Detect Edges**; creases shorter than two quads or softer than about 55
+ degrees at the quad scale are sculpt detail, not hard edges) on their exact place.
+2. **Curvature and directions.** The principal curvature directions, smoothed over about one quad, and a
+ smooth cross field (the directions the edges take) solved over the whole surface at once: it follows the
+ curvature where the surface clearly bends one way (limbs, lips, brows, ridges), the feature lines exactly,
+ and is as smooth as possible elsewhere. It is solved on a copy of the surface smoothed at the quad scale, so
+ pores and scratches don't add poles. Polypaint density turns it the way a change of density needs.
+3. **The grid.** A seamless parametrization whose integer lines are the edge loops: feature lines and guides lie
+ exactly on grid lines, singularities (the poles) exactly on grid points, and across the seams the grid only
+ turns by quarter turns. Its integer unknowns are rounded nearest-first, each round followed by a re-solve.
+4. **Extraction** of that grid at the target density (not split from a coarser one), every face a quad; the
+ rare places where the grid folds are repaired locally and stay all quads.
+5. **Loop-aware relaxation**: smoothing on the sculpt in which a vertex can slide along a loop that runs over a
+ ridge but not off it, then projection onto the sculpt.
+
+With **Symmetry** one half is remeshed with the mirror plane as a feature line and mirrored, so the field and
+the result are exactly symmetric. The result is the same every time for the same settings.
+
+Compared with the legacy method on the same models and targets (M1 Pro, 10 cores), QRemesh 2 has a quarter to a
+tenth of the poles and quad corners closer to square at the same distance to the sculpt:
+
+BENCHTABLE
+
+A 1.3-million-triangle sculpt takes about 4 seconds to 5,000 quads; dense sculpts are first decimated in
+parallel to a working resolution, so 21 million triangles take DENSE21.
+
+The legacy method (**Method > Legacy**, `method=legacy`) is the Instant Meshes style field-aligned method of
+SculptForge 0.9 (Jakob, Tarini, Panozzo and Sorkine-Hornung, 2015): faster on small models but with many more
+poles, and its result is extracted at twice the spacing and split, which shows as paired loops.
> **ZBrush:** QRemesh Guides are ZBrush's ZRemesher Guides brush, and Curves Strength its slider of that name.
> Keep Groups, Use Polypaint, Adaptive Size, Half / Same / Double and symmetry work as you know them. There is no
@@ -88,7 +121,9 @@ for a 1.3-million-triangle sculpt to 5,000 quads, and 6 seconds to 100,000 quads
## QRemesh Guides
Draw curves on the sculpt and QRemesh puts an edge loop along each one, and turns the flow around it to follow,
-like ZBrush's ZRemesher Guides brush. Use them where the topology has to work for animation: rings around the
+like ZBrush's ZRemesher Guides brush. With QRemesh 2 an open curve is an exact edge loop: the grid line lies on it.
+Closed loops (round an eye) and loops across the symmetry plane are, for now, done by the legacy method for that
+piece (the status line says so). Use them where the topology has to work for animation: rings around the
eyes and the mouth, loops around the shoulders, elbows and knees, a line down the middle of a muscle.
![Left: QRemesh on its own. Middle: loops drawn round the eyes and the mouth with QRemesh Guides. Right: QRemesh again, with an edge loop on every curve and rings around them](images/qremesh-guides.jpg)
@@ -167,7 +202,7 @@ straight along the normal, it takes the closest point within **Dist**.
| Command | Options |
|---|---|
-| `qremesh` | `target` (16 to 2,000,000, default 5000), `adaptive` (0-1, default 0.5), `keep_groups`, `detect_edges` (default true), `use_polypaint`, `symmetry` (`x`, `y` or `z`; off by default in scripts; the mirror plane is found from the model), `symmetry_center` (use this plane instead, e.g. `0` for the world's centre), `keep_original`, `smooth` (relaxation passes, default 6), `seed`, `keep_texture` (default true), `guides` (follow the SubTool's QRemesh Guides, default true), `curves_strength` (0-100, default 50) |
+| `qremesh` | `method` (`v2`, the default, or `legacy`), `quality` (report poles, corner angles and the distance to the sculpt, default true), `target` (16 to 2,000,000, default 5000), `adaptive` (0-1, default 0.5), `keep_groups`, `detect_edges` (default true), `use_polypaint`, `symmetry` (`x`, `y` or `z`; off by default in scripts; the mirror plane is found from the model), `symmetry_center` (use this plane instead, e.g. `0` for the world's centre), `keep_original`, `smooth` (relaxation passes, default 6), `seed` (legacy method only; QRemesh 2 has no random start), `keep_texture` (default true), `guides` (follow the SubTool's QRemesh Guides, default true), `curves_strength` (0-100, default 50) |
| `qremesh_guide` | `points` (the curve, `"x,y,z x,y,z ..."`), `view` (project the points onto the surface along this direction, as a stroke from the camera; default: each point to the closest surface point), `symmetry` (`x`, `xz`...; mirror the curve) |
| `qremesh_guide_delete_last`, `qremesh_guides_clear`, `qremesh_guides_info` | Delete the last curve, delete all, list them |
| `project_all` | `distance` (0.001-1, default 0.02), `mean`, `blur` (0-20), `geometry` (default true), `polypaint` (default true), `source` (one SubTool's name instead of all visible ones) |
diff --git a/src/core/QRemesh2.cpp b/src/core/QRemesh2.cpp
index 1cc87d34..ff261b61 100644
--- a/src/core/QRemesh2.cpp
+++ b/src/core/QRemesh2.cpp
@@ -363,6 +363,26 @@ Poly extractLattice(const Proxy& p, const Frames& fr, const GridMap& map, float
if (L[3 * t + size_t(i)] == L[3 * t + size_t(j)]) uf.unite(p.T[t][i], p.T[t][j]);
}
}
+ // A virtual node whose lattice point a vertex one ring away already rounds to (in the same chart: the shared
+ // vertex has the same map value in both triangles) is that vertex's lattice point.
+ if (!virt.empty()) {
+ VertexFaces vf;
+ vf.build(nv, p.T);
+ for (const Virt& v : virt)
+ for (int k = 0; k < 3; ++k) {
+ const uint32_t x = p.T[v.tri][k];
+ const vec2 at = map.uv[3 * v.tri + uint32_t(k)];
+ for (uint32_t i = vf.off[x]; i < vf.off[x + 1]; ++i) {
+ const uint32_t t2 = vf.tri[i];
+ if (t2 == v.tri || flipped[t2]) continue;
+ int kx = 0;
+ while (kx < 3 && p.T[t2][kx] != x) ++kx;
+ if (glm::length(map.uv[3 * t2 + uint32_t(kx)] - at) > 1e-4f) continue; // across a seam
+ for (int j = 0; j < 3; ++j)
+ if (L[3 * t2 + uint32_t(j)] == v.g) uf.unite(uint32_t(nv + v.node), p.T[t2][j]);
+ }
+ }
+ }
std::vector<uint32_t> cluster(nn, kNone);
uint32_t nc = 0;
for (uint32_t v = 0; v < nn; ++v) {
@@ -1283,6 +1303,11 @@ bool remeshPieceOnce(const WorkMesh& piece, int axis, double wantQuads, const QR
}
return demoted;
};
+ if (timing) {
+ size_t fc = 0, sc = 0;
+ for (size_t c = 0; c < proxy.feature.size(); ++c) fc += proxy.feature[c], sc += proxy.sharp[c];
+ std::fprintf(stderr, " v2 proxy features: %zu corners (%zu hard-edge), %zu source hard edges kept\n", fc, sc, ps.sharp.size());
+ }
{
const size_t d = demoteSoftEdges(proxy);
if (timing && d) std::fprintf(stderr, " v2 %zu soft hard-edge corners demoted\n", d);
@@ -1314,7 +1339,7 @@ bool remeshPieceOnce(const WorkMesh& piece, int axis, double wantQuads, const QR
std::nth_element(sorted.begin(), sorted.begin() + long(sorted.size() / 2), sorted.end());
const float ref = std::max(sorted[sorted.size() / 2], 0.2f / h0); // flat models stay even
for (size_t v = 0; v < rel.size(); ++v)
- rel[v] = std::clamp(std::pow(std::max(k[v], 1e-9f) / ref, -0.6f * opt.adaptive), 0.45f, 2.2f);
+ rel[v] = std::clamp(std::pow(std::max(k[v], 1e-9f) / ref, tune("SF_QR2_ADAPT", 0.6f) * -opt.adaptive), 0.45f, 2.2f);
}
if (!piece.color.empty()) {
proxy.color.assign(proxy.P.size(), vec3(1.0f));
diff --git a/src/core/QRemesh2Field.cpp b/src/core/QRemesh2Field.cpp
index 51d5e960..788a4d8a 100644
--- a/src/core/QRemesh2Field.cpp
+++ b/src/core/QRemesh2Field.cpp
@@ -81,7 +81,7 @@ Curvature computeCurvature(const Proxy& p, const Frames& f, float radius) {
const vec3 e = p.P[p.T[t][(k + 1) % 3]] - p.P[p.T[t][k]];
const float len = glm::length(e);
edgeSum += len, ++edgeCount;
- if (o == kNone || o < c) continue;
+ if (o == kNone || o < c || p.feature[c]) continue; // a feature edge is a crease, not curvature
const uint32_t g = o / 3;
const vec3 ed = e / std::max(len, 1e-30f);
// Signed dihedral angle: positive where the surface bends away from its normal (convex).
@@ -265,7 +265,10 @@ bool solveCrossField(const Proxy& p, const Frames& f, const Curvature& curv, con
// Start: the pull, or a constant phase where there is none.
for (uint32_t i = 0; i < nfree; ++i)
if (std::abs(x[i]) == 0.0) x[i] = cd(1.0, 0.0);
- const double sigma = std::max(bn, 1e-3 * meanDiag) * 1.0;
+ // With fixed directions (feature lines) the pull towards them must dominate: only a light smoothest-field
+ // term. Without any, the smoothest field is the answer and the scale only sets the step.
+ static const double tune_sigma = std::getenv("SF_QR2_SIGMA") ? std::atof(std::getenv("SF_QR2_SIGMA")) : 2e-3;
+ const double sigma = nfree < nt ? tune_sigma * meanDiag : std::max(bn, 1e-3 * meanDiag);
std::vector<cd> rhsk(nfree);
static const int projected = std::getenv("SF_QR2_PROJ") ? std::atoi(std::getenv("SF_QR2_PROJ")) : 30;
for (int round = 0; round < 6 + projected; ++round) {
diff --git a/tests/test_qremesh2.cpp b/tests/test_qremesh2.cpp
index 580bf289..a381b1fb 100644
--- a/tests/test_qremesh2.cpp
+++ b/tests/test_qremesh2.cpp
@@ -263,9 +263,12 @@ TEST(qremesh2_benchmark) {
models.push_back({"sculpt1m", sculptedSphere(2), -1});
std::printf("\n| model | triangles | target | method | quads | time s | poles | x3/x5/other | corner dev deg | mean dist %% | Hausdorff %% |\n");
std::printf("|---|---|---|---|---|---|---|---|---|---|---|\n");
+ const char* only = std::getenv("SF_QREMESH_BENCH_MODELS"); // e.g. "lion,head"
for (const Model& md : models)
for (int target : {2000, 5000, 10000})
for (QRemeshMethod method : {QRemeshMethod::Legacy, QRemeshMethod::V2}) {
+ if (only && std::string(only).find(md.name) == std::string::npos) continue;
+ if (method == QRemeshMethod::Legacy && std::getenv("SF_QREMESH_BENCH_V2_ONLY")) continue;
const Run r = run(md.mesh, target, method, md.symmetry);
if (!r.ok) continue;
const QuadQuality& q = r.st.quality;