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.

Levels polish: UI test, guide and project-format docs, benchmark

islandmedf7856f2d4775
diff --git a/docs/guide/geometry.md b/docs/guide/geometry.md
index ef6523e2..13e7dd3d 100644
--- a/docs/guide/geometry.md
+++ b/docs/guide/geometry.md
@@ -51,8 +51,9 @@ multiplies the triangle count by four and rounds off the shape slightly, like ZB
- Each quad becomes four quads; triangles become four triangles.
- SculptForge refuses to subdivide past 50 million triangles.
-> **Note:** Subdivide replaces the mesh with a denser one and drops any [subdivision levels](subdivision-levels.md)
-> (undo brings them back). Dynamic topology is on the roadmap.
+> **Note:** Subdivide replaces the mesh with a denser one and drops any [subdivision levels](subdivision-levels.md):
+> it subdivides the level you are on, which becomes the new base, and the status line says so (undo brings the
+> levels back). Voxel Remesh, Decimate and QRemesh do the same. Dynamic topology is on the roadmap.
> **Tip:** The title strip shows the vertex and triangle counts of the whole scene. A few million triangles sculpt
> smoothly on a recent GPU; go up a level only when you need finer detail.
diff --git a/docs/guide/gizmo.md b/docs/guide/gizmo.md
index 819fd588..d0a898f9 100644
--- a/docs/guide/gizmo.md
+++ b/docs/guide/gizmo.md
@@ -106,7 +106,8 @@ part.
A transform only changes where the vertices are. Polygroups, quads, UVs, polypaint, textures, the mask and
the topology stay as they are. [Sculpt layers](layers.md) move with the surface: the base and every layer's
offsets are transformed together, so a layer you sculpted on a forearm stays on it after posing, and layer
-sliders keep working. Projects save the result, and the gizmo's pivot and options too.
+sliders keep working. With [subdivision levels](subdivision-levels.md) you can pose at a low level: the detail of
+the higher levels, sculpt layers included, turns with it when you step back up. Projects save the result, and the gizmo's pivot and options too.
## Scripting
diff --git a/docs/guide/subdivision-levels.md b/docs/guide/subdivision-levels.md
index 2b2073f2..e6acb984 100644
--- a/docs/guide/subdivision-levels.md
+++ b/docs/guide/subdivision-levels.md
@@ -62,7 +62,7 @@ What happens to your sculpting when you change level:
| | When you change it at one level |
|---|---|
| Shape | Carried up as detail, softened down (see above) |
-| Sculpt layers | Each layer has its own detail on every level; weights apply to all levels. See [Layers](layers.md) |
+| Sculpt layers | Each layer has its own detail on every level, kept relative to the surface like the shape's: rotate or reshape a low level and a layer's wrinkles turn and bend with it. Weights apply to all levels. See [Layers](layers.md) |
| Mask | Copied down to the vertices below, interpolated up where it changed |
| Polypaint and paint layers | As the mask: paint at a low level for broad colour, at a high level for detail. Painting low only changes the higher levels where you painted |
| Polygroups, hidden faces | Copied down to the parent faces, inherited up by the faces they contain |
@@ -99,12 +99,17 @@ keeping the dense mesh exactly as it was. Press it again for more levels.
Del Higher and Reconstruct are single undo steps. Steps share the levels they didn't change, so they cost
little memory.
- **Projects** (`.sfproj`) save every level of every SubTool and open at the level you saved at. They use
- project format 4, so older SculptForge versions ask you to update before opening them.
+ project format 5 (sculpt-layer detail relative to the surface), so older SculptForge versions ask you to update
+ before opening them. Projects saved with format 4 open as before and are converted as they load.
- **Exports and GoZ** write the current level. To write another one, step to it first, or use the
`subdiv_export` command (`subdiv_export path=base.obj level=1` writes the base cage of every visible SubTool,
in any export format). LODs and **Send to Unreal** start from the current level too.
-- **Tools that rebuild the mesh** (Voxel Remesh, Decimate, Subdivide, Delete hidden, merging and splitting
- SubTools) make a new mesh without levels. Undo brings the levels back.
+- **Tools that rebuild the mesh** (Voxel Remesh, Decimate, QRemesh, Subdivide, Delete hidden, merging and
+ splitting SubTools) work on the level you are on, including what you just sculpted there, and make a new mesh
+ without levels: that level becomes the new base. The status line says so, e.g. *Subdivision levels removed:
+ SDiv 3 of 5 kept as the new base (undo restores them)*. <kbd>Ctrl</kbd>+<kbd>Z</kbd> brings every level back,
+ at the level you were on. Merging and splitting SubTools can't be undone (as in ZBrush), so step to the level
+ you want to keep first, or save before.
> **Note:** **Subdivide** (in **Tool > Geometry**, below Divide) is still there: it replaces the mesh with a
> denser one and keeps no levels. Use Divide unless you want exactly that.
@@ -137,7 +142,9 @@ Measured on an Apple M1 Pro (Asahi Linux), a cube divided four times to 6.5 mill
| Memory for all levels | 120 MB | 480 MB |
SculptForge keeps the two levels you visited last ready to show, so going back and forth between a low and a
-high level (the usual rhythm) is instant.
+high level (the usual rhythm) is instant. Only the active SubTool keeps them: selecting another SubTool frees
+that memory (50-170 MB for a SubTool with 1.8 million triangles at the top), and the first level change after
+you come back takes a moment longer (about 0.1 s at that size) while the level is prepared again.
> **ZBrush:** Divide, Smt, Lower Res, Higher Res, SDiv, Del Lower, Del Higher and Reconstruct Subdiv work as in
> ZBrush. Not yet: Freeze SubDivision Levels, Cage, Rstr, Suv (UV smoothing on divide) and creased edges.
diff --git a/docs/guide/subtools.md b/docs/guide/subtools.md
index b97568e9..f2f1e8ef 100644
--- a/docs/guide/subtools.md
+++ b/docs/guide/subtools.md
@@ -92,7 +92,9 @@ The up and down arrow buttons under the list move the active SubTool one place u
they are.
Merging keeps every attribute, gives each original mesh its own polygroups (so you can split them again later) and
-matches sculpt layers by name. The merged SubTool starts with an empty undo history.
+matches sculpt layers by name. The merged SubTool starts with an empty undo history. A SubTool with
+[subdivision levels](subdivision-levels.md) is merged (or split) at the level it is on, which becomes the base of
+the result; the status line names the SubTools that lost their levels.
> **Tip:** Merge first when you want one [voxel remesh](geometry.md#voxel-remesh) to fuse several pieces into a
> single watertight surface.
diff --git a/docs/project-format.md b/docs/project-format.md
index 37da5e20..4a27f856 100644
--- a/docs/project-format.md
+++ b/docs/project-format.md
@@ -4,8 +4,8 @@ A `.sfproj` is an uncompressed ("stored") ZIP (src/io/Zip.cpp) written by `saveP
read by `loadProject` (src/core/Project.cpp). Commands: `save_project path=...`,
`open_project path=...`; `open` also recognises `.sfproj`.
-## Layout (version 4)
-- `manifest.json`: always first. `format` = `"SculptForge project"`, `version` (integer, currently 4),
+## Layout (version 5)
+- `manifest.json`: always first. `format` = `"SculptForge project"`, `version` (integer, currently 5),
`app_version`, then `subtools` (one entry per SubTool, in list order), `active_subtool` (index),
`brushes` (recipe JSON), `active_brush` (name), optional `splats`, and app-owned keys (`camera`,
`render`, `brush`, `symmetry`, `gizmo`). `gizmo` (added in 0.5 without a version bump; older readers
@@ -62,11 +62,15 @@ silently dropping the paint. Version 1 and 2 files load unchanged.
SubTool's own `mesh` is) and `levels` (base first). Each level has `mesh` / `layers` / `paint_layers` as above
under `subtools/i/subdiv/<k>/` (or `same_as_mesh: true` for the current level when it equals the SubTool's
mesh), `stale` (positions to be re-evaluated from the level below), `detail` (f32 x3 per vertex: displacement
-in the local frame of the subdivided level below), `layer_detail` (one per sculpt layer, world space) and, from
+in the local frame of the subdivided level below), `layer_detail` (one per sculpt layer: the layer's offsets
+minus the subdivided offsets of the level below, in the same local frames as `detail`; version 4 stored them in
+world space, and readers convert those when loading a version 4 file, evaluating stale levels on the way) and, from
level 1 up, `topology`: `catmull_clark`, `smooth`, `pairing` (u32 per coarse triangle: the quad pairs the level
was divided with) and `vertex_child` / `edge_child` / `face_child` (u32: the fine vertex of each coarse vertex,
edge, in edge order, and polygon). Edges and polygons are rebuilt from the coarse level, so the maps must match;
-levels that don't fit refuse the file. Readers that don't know `subdiv` load the current level.
+levels that don't fit refuse the file. Readers that don't know `subdiv` load the current level. Version 5 (the
+local-frame `layer_detail`) was introduced so a sculpt layer's detail turns with a rotated or reshaped low level;
+version 4 readers would misread it, so they refuse version 5 files.
Loading replaces the scene: every SubTool comes back with its name, visibility, attributes, layers,
active layer and GoZ name, the saved active SubTool is selected, every SubTool starts with an empty
@@ -77,7 +81,7 @@ selects the first one.
## Version 1
Version 1 files (SculptForge 0.2 and earlier) have one mesh at the top level instead of `subtools`:
`mesh` and `layers` as above (blobs under `mesh/` and `layers/`) and `active_layer`. They still load,
-as a single SubTool called "Sculpt". Saving always writes the current version (4).
+as a single SubTool called "Sculpt". Saving always writes the current version (5).
## Compatibility rules
- Unknown keys and files are ignored. Unknown **top-level** keys are kept in
diff --git a/src/core/Document.cpp b/src/core/Document.cpp
index 12754545..b2f2459c 100644
--- a/src/core/Document.cpp
+++ b/src/core/Document.cpp
@@ -157,7 +157,7 @@ void Document::replaceMeshUndoable(Mesh m, std::string label) {
if (mesh.multires && !m.multires) {
// A tool rebuilt the mesh from the current level: the levels go, the undo step keeps them.
if (const std::string note = subdivDroppedNote(mesh); !note.empty())
- notice += (notice.empty() ? "" : "; ") + note + " (Undo brings them back)";
+ notice += (notice.empty() ? "" : "; ") + note + " (undo restores them)";
subdivReleaseCache(mesh);
}
UndoRecord r;
diff --git a/src/core/Project.cpp b/src/core/Project.cpp
index 9cb496ba..f8789053 100644
--- a/src/core/Project.cpp
+++ b/src/core/Project.cpp
@@ -386,9 +386,9 @@ bool readTexture(Reader& r, const Json& tj, Mesh& m, std::string& error) {
return true;
}
-// Subdivision levels (core/Multires.h) are the SubTool key "subdiv" (format 4): the current level and every
-// level's mesh (as "mesh" / "layers" / "paint_layers"), details and topology (scheme, Smt, quad pairing and child
-// maps). The SubTool's own "mesh" is the current level, so readers that don't know levels load what was shown.
+// Subdivision levels (core/Multires.h) are the SubTool key "subdiv" (format 4; sculpt-layer details in local
+// frames from format 5): the current level and every level's mesh (as "mesh" / "layers" / "paint_layers"),
+// details and topology (scheme, Smt, quad pairing and child maps). The SubTool's own "mesh" is the current level, so readers that don't know levels load what was shown.
// A current level identical to that mesh is not written twice ("same_as_mesh").
Json writeSubdiv(Writer& w, const std::string& prefix, const Mesh& m) {
Json out = Json::object();
diff --git a/tests/test_multires_polish.cpp b/tests/test_multires_polish.cpp
index ce0a14d2..d7e0d385 100644
--- a/tests/test_multires_polish.cpp
+++ b/tests/test_multires_polish.cpp
@@ -116,6 +116,10 @@ TEST(multires_bench_select_and_step) {
run(d, "subdiv_higher");
const double eval = msSince(t0);
std::printf(" with a sculpt layer: step down folding a layer stroke in %.1f ms, step up re-evaluating %.1f ms\n", fold, eval);
+ stroke(d, "-0.3,0,2", "Inflate", 0.3); // on the base, at the top
+ t0 = std::chrono::steady_clock::now();
+ run(d, "subdiv_lower");
+ std::printf(" step down folding a base stroke in (one layer) %.1f ms\n", msSince(t0));
}
// Every tool that rebuilds the mesh works on the current level (pending edits included), says the levels were
@@ -148,7 +152,7 @@ TEST(multires_rebuilding_tools_drop_levels_and_undo_restores_them) {
const CommandResult r = run(d, c.command, c.args);
CHECK(r.ok);
CHECK(contains(r.message, "Subdivision levels removed: SDiv 2 of 3 kept as the new base"));
- CHECK(contains(r.message, "Undo"));
+ CHECK(contains(r.message, "undo restores them"));
CHECK(subdivLevelCount(d.mesh) == 0);
CHECK(d.notice.empty());
// Made from the current level, with the pending stroke.
diff --git a/tests/ui/levels_rebuild.sfui b/tests/ui/levels_rebuild.sfui
new file mode 100644
index 00000000..a9f3b085
--- /dev/null
+++ b/tests/ui/levels_rebuild.sfui
@@ -0,0 +1,64 @@
+# Subdivision levels and the tools that rebuild the mesh (Decimate, Subdivide, Remesh, QRemesh, Delete Hidden,
+# merging and splitting SubTools): they work on the current level, the status line says the levels were removed
+# and which one became the base, and Ctrl+Z brings every level back. Selecting another SubTool and coming back
+# still steps between the levels.
+run new_sphere subdivisions=1
+run subtool_append type=cube name=Box
+run subtool_delete index=0
+orbit 140 -70
+key f
+click "Geometry##tool.geometry"
+click "Geometry/Reconstruct Subdiv"
+click "Geometry/Reconstruct Subdiv"
+expect_value sdiv_levels == 3
+expect_value sdiv == 1
+
+# Up to SDiv 2 and sculpt there (an edit not folded into the levels yet).
+key d
+expect_value sdiv == 2
+expect_value triangles == 6912
+snapshot
+stroke 0.3 0.4 0.7 0.5
+expect_value moved > 10
+
+# Decimate at SDiv 2: half of SDiv 2's triangles, and the status line says what happened to the levels.
+click "Geometry/Decimate"
+expect_value sdiv_levels == 0
+expect_value triangles < 6912
+expect_value triangles > 1000
+expect_status "Subdivision levels removed: SDiv 2 of 3 kept as the new base"
+expect_text "No subdivision levels"
+shot decimated
+
+# Undo: all three levels again, at SDiv 2 with the stroke.
+key ctrl+z
+expect_value sdiv_levels == 3
+expect_value sdiv == 2
+expect_value triangles == 6912
+expect_text "SDiv 2 / 3"
+shot levels-back
+
+# Subdivide (the flat one, without levels) from SDiv 2: four times its triangles.
+click "Geometry/Subdivide"
+expect_value triangles == 27648
+expect_value sdiv_levels == 0
+expect_status "Subdivision levels removed: SDiv 2 of 3 kept as the new base"
+key ctrl+z
+expect_value sdiv_levels == 3
+expect_value sdiv == 2
+
+# Another SubTool and back: the levels step as before (the cached levels of the SubTool left are freed).
+run subtool_append type=sphere name=Eye
+expect_value sdiv_levels == 0
+run subtool_select name=Box
+expect_value sdiv == 2
+key d
+expect_value sdiv == 3
+expect_value triangles == 27648
+key shift+d
+key shift+d
+expect_value sdiv == 1
+expect_value triangles == 1728
+key d
+expect_value sdiv == 2
+shot after-switching