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
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.mdindex 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-31Speed first: big brushes on dense meshes take a third less time per frame, trail the pen by half as far and nodiff --git a/docs/guide/retopology.md b/docs/guide/retopology.mdindex 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 barreplaces the button, and **Cancel** stops it. The result replaces the SubTool, and the sculpt as it was iskept 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 GuidesDraw 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 theeyes and the mouth, loops around the shoulders, elbows and knees, a line down the middle of a muscle.@@ -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.cppindex 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, floatif (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 QRstd::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 evenfor (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.cppindex 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 curvatureconst 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.cppindex 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;