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.

Merge Gizmo 3D (move, scale, rotate, posing)

islandmed4c9a026f4760
diff --cc CHANGELOG.md
index 26c64103,f1f00ba3..57ae862a
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -6,25 -6,33 +6,52 @@@ All notable changes to SculptForge are
## [Unreleased]
+### Subdivision levels (multiresolution)
+- Divide (Tool > Geometry, Ctrl+D, `subdiv_divide`) adds a subdivision level per SubTool and keeps the lower
+ ones: Catmull-Clark on meshes with quads (quads stay quads), Loop on triangle meshes, flat with Smt off.
+- Lower Res / Higher Res (Shift+D / D, `subdiv_lower`, `subdiv_higher`) and the SDiv slider (`subdiv_level`)
+ step between levels. Detail is stored per level as a displacement in the local frame of the smoothed level
+ below, so reshaping a low level carries it along; edits at a high level are restricted (full weighting) to
+ the lower ones. Round trips without edits are bit-for-bit.
+- Mask, polypaint, paint layers, polygroups, hidden faces and UVs follow the levels (copied down, interpolated or
+ inherited up where they changed); sculpt layers have their own detail per level; the texture is shared.
+- Del Lower, Del Higher (`subdiv_delete_lower`, `subdiv_delete_higher`) and Reconstruct Subdiv
+ (`subdiv_reconstruct`: finds the lower level of a regular Catmull-Clark or Loop subdivision, keeping the mesh
+ and its vertex order). `subdiv_info` lists the levels; `subdiv_export` writes the visible SubTools at another
+ level (e.g. the base cage) in any export format.
+- Each level change is one undo step, as is each stroke at any level; level edits share unchanged levels
+ copy-on-write. The two levels left last keep their topology and BVH, so stepping back and forth is instant
+ (1-45 ms at 6.5M triangles).
+- Projects save every level (project format 4). The SubTool list shows "SDiv n/m".
+- Ctrl+D now runs Divide; the one-way Subdivide stays in Tool > Geometry and as `subdivide`.
+
+ ### Gizmo 3D (moving, scaling, rotating and posing)
+ - Gizmo 3D modes, as in ZBrush: W Move, E Scale, R Rotate, Q back to Draw (top shelf, Transform palette, F3).
+ Move has axis arrows, plane squares and a view-plane centre; Rotate has axis rings and a view ring; Scale has
+ axis boxes and a uniform centre. Shift snaps (15 degrees, a round grid step, 10%). The amount shows beside the
+ gizmo while dragging. Dragging off the handles still navigates; Ctrl still masks.
+ - Transforms move the active SubTool, or only its unmasked part: partly masked vertices move partly, hidden ones
+ never. Falloff eases the movement in over a distance from the mask's edge (measured along the surface, as a
+ share of the size) for soft joints when posing. With symmetry on, a masked transform is mirrored across the
+ symmetry plane.
+ - Pivot: follows the centre of what moves; Alt+drag the gizmo to move it (or turn its axes) without the model,
+ Alt+click the model or To Surface to put it on the surface, Reset; World or Surface axes (Y along the normal,
+ turning with rotations). The gizmo follows undo / redo of its own steps and is saved in projects (`gizmo` key,
+ no format bump).
+ - Gizmo 3D panel: pivot, options and numeric Move / Rotate / Scale with Apply; All SubTools (Transpose All, one
+ undo step per SubTool).
+ - `transform` command (translate, rotate, scale, pivot, orient, masked, falloff, symmetry, all); each gizmo drag
+ is echoed to the console as the command that repeats it.
+ - One undo step per drag that restores positions bit for bit. Sculpt layers move with the surface (the base and
+ every layer's offsets). Topology, quads, UVs, textures, polypaint and polygroups are untouched.
+ - Fast on big meshes: a drag recomputes from the drag's start (no drift), transforms only the moving vertices
+ through a per-weight lookup table on several threads, turns normals of rigid parts and recomputes only where
+ the movement varies, uploads only the changed vertex range and refits the BVH once on release. On 1.3M
+ triangles: about 2 ms to transform and 7 ms to upload per drag frame, 20-40 ms on release.
+
+ ### Changed
+ - Wireframe (PolyF) is Shift+F only: W is now the Gizmo 3D's Move, as in ZBrush.
+
## [0.4.2] - 2026-10-23
### Texture painting on UV maps
diff --cc CMakeLists.txt
index d133e502,add7587b..8468ac32
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@@ -162,7 -162,7 +164,8 @@@ if(SCULPTFORGE_BUILD_APP
src/app/PanelPolypaint.cpp
src/app/PanelPaintLayers.cpp
src/app/PanelTexture.cpp
+ src/app/PanelGeometry.cpp
+ src/app/Gizmo.cpp
src/app/PanelGoz.cpp
src/app/PanelProject.cpp
src/app/PanelSubTools.cpp
diff --cc docs/guide/glossary.md
index 61a7d129,2ddca587..63709019
--- a/docs/guide/glossary.md
+++ b/docs/guide/glossary.md
@@@ -80,10 -79,12 +81,13 @@@ for what is planned
| Console | The script console (backtick key): every action appears as a script line |
| Ctrl help | Hold <kbd>Ctrl</kbd> and point at a control to see what it does, its shortcut and its command |
| Gaussian splat | A 3D capture made of soft coloured blobs (from phone scanning apps). Load one as a reference, convert it to a mesh, or turn a sculpt into splats. See [Gaussian splats](splats.md) |
+ | Falloff (Gizmo 3D) | How far a gizmo move eases in from the mask's edge, as a share of the SubTool's size: a soft joint when posing. See [Gizmo 3D](gizmo.md#posing-a-limb) |
| Generate 3D | Turn an image or a description into a sculptable model. See [Image and text to 3D](generate-3d.md) |
+ | Gizmo 3D | The Move / Scale / Rotate handles (<kbd>W</kbd> <kbd>E</kbd> <kbd>R</kbd>) for placing and posing a SubTool or its unmasked part. See [Gizmo 3D](gizmo.md) |
| LOD chain | A series of lighter copies of a model (LOD0, LOD1...) for game engines. See [Geometry](geometry.md#lod-chains) |
| MCP | Model Context Protocol: `sculptforge-cli --mcp` lets AI agents such as Claude run SculptForge commands |
+ | Pivot | The point the Gizmo 3D turns and scales about. <kbd>Alt</kbd>+click the model to put it there. See [The pivot](gizmo.md#the-pivot) |
+| Subdivide | One-way subdivision without levels (**Tool > Geometry > Subdivide**, `subdivide`); **Divide** keeps the levels |
| Send to Unreal | Export and import a model into a running Unreal Editor in one step (<kbd>Ctrl</kbd>+<kbd>U</kbd>) |
| Shelves, palettes, trays | The interface around the canvas: shelves hold the most-used controls, palettes hold everything, trays hold pinned palettes. See [The interface](interface.md) |
| Studio brush folder | A shared, read-only brush folder for a team (`SCULPTFORGE_BRUSH_PATH`). See [For studios](studios.md) |
diff --cc docs/guide/index.md
index d98c186c,5e625dec..df54ebb9
--- a/docs/guide/index.md
+++ b/docs/guide/index.md
@@@ -26,29 -26,29 +26,30 @@@ You can read it inside SculptForge (**H
8. [Masking](masking.md)
9. [Polygroups and visibility](polygroups.md)
10. [SubTools](subtools.md)
-11. [Moving, rotating and posing (Gizmo 3D)](gizmo.md)
-12. [Polypaint and materials](polypaint.md)
-13. [Texture painting](texture-painting.md)
-14. [Sculpt layers and blend shapes](layers.md)
-15. [Subdivide, remesh, decimate and LODs](geometry.md)
+11. [Polypaint and materials](polypaint.md)
+12. [Texture painting](texture-painting.md)
+13. [Sculpt layers and blend shapes](layers.md)
+14. [Subdivision levels](subdivision-levels.md)
- 15. [Subdivide, remesh, decimate and LODs](geometry.md)
++15. [Moving, rotating and posing (Gizmo 3D)](gizmo.md)
++16. [Subdivide, remesh, decimate and LODs](geometry.md)
## AI and capture
--16. [Image and text to 3D](generate-3d.md)
--17. [Gaussian splats](splats.md)
++17. [Image and text to 3D](generate-3d.md)
++18. [Gaussian splats](splats.md)
## Files and pipelines
--18. [Exporting, Unreal and ZBrush](exporting.md)
--19. [Projects, autosave and QuickSave](projects.md)
--20. [Scripting and automation](scripting.md)
--21. [SculptForge for studios](studios.md)
++19. [Exporting, Unreal and ZBrush](exporting.md)
++20. [Projects, autosave and QuickSave](projects.md)
++21. [Scripting and automation](scripting.md)
++22. [SculptForge for studios](studios.md)
## Reference
--22. [Keyboard and mouse](shortcuts.md)
--23. [Troubleshooting and FAQ](troubleshooting.md)
--24. [Glossary](glossary.md)
++23. [Keyboard and mouse](shortcuts.md)
++24. [Troubleshooting and FAQ](troubleshooting.md)
++25. [Glossary](glossary.md)
## Getting help
diff --cc docs/guide/whats-new.md
index e0b33bad,99a93257..29f90747
--- a/docs/guide/whats-new.md
+++ b/docs/guide/whats-new.md
@@@ -7,25 -7,24 +7,43 @@@ chapter opens by itself the first time
## Next version (in development)
+### Subdivision levels
+
+Sculpt one model at several resolutions, as with ZBrush's SDiv: big forms low, fine detail high, and back down
+without losing anything.
+
+- **Divide** (<kbd>Ctrl</kbd>+<kbd>D</kbd>) adds a level and keeps the ones below. Quads stay quads
+ (Catmull-Clark); **Smt** off divides without smoothing.
+- **Lower Res** / **Higher Res** (<kbd>Shift</kbd>+<kbd>D</kbd> / <kbd>D</kbd>) and the **SDiv** slider step
+ between levels. Detail sculpted high rides along when you reshape low, and edits high show up softened below.
+ Stepping back and forth is instant, even at millions of polygons.
+- Mask, polypaint, paint layers, polygroups, hidden faces, UVs and sculpt layers follow the levels.
+- **Del Lower**, **Del Higher** and **Reconstruct Subdiv** (find the lower levels of a model subdivided
+ elsewhere). Undo walks back through strokes and level changes; projects save every level; the SubTool list
+ shows "SDiv 3/5".
+- <kbd>Ctrl</kbd>+<kbd>D</kbd> now divides with levels; the old one-way **Subdivide** is still in
+ **Tool > Geometry**.
+
+See [Subdivision levels](subdivision-levels.md).
+
+ ### Gizmo 3D: move, scale, rotate and pose
+
+ ZBrush's Gizmo 3D, with the same keys: <kbd>W</kbd> Move, <kbd>E</kbd> Scale, <kbd>R</kbd> Rotate, <kbd>Q</kbd>
+ back to Draw (also on the top shelf and in the **Transform** palette).
+
+ - **Handles over the model.** Arrows, plane squares and a free-move centre; axis rings and a view ring; axis
+ boxes and a uniform centre. <kbd>Shift</kbd> snaps to 15 degrees, the grid or 10% steps.
+ - **Only the unmasked part moves**, so posing is: mask the body, <kbd>Alt</kbd>+click the shoulder to put the
+ pivot there, raise **Falloff** for a soft joint, turn the arm. With X symmetry both arms move together.
+ - **Pivot tools**: <kbd>Alt</kbd>+drag the gizmo to move it alone, **Reset**, **To Surface**, World or Surface
+ axes.
+ - **Numeric entry** in the Gizmo 3D panel, **All SubTools** (Transpose All), one undo step per drag, sculpt
+ layers move with the surface, and the `transform` command for scripts.
+ - Fast on big models: a drag frame on 1.3 million triangles takes about 10 ms.
+
+ <kbd>W</kbd> no longer toggles the wireframe: use <kbd>Shift</kbd>+<kbd>F</kbd> (as in ZBrush) or **PolyF** on the
+ right shelf. See [Moving, rotating and posing](gizmo.md).
+
## Version 0.4.2
### Texture painting on UV maps
diff --cc docs/project-format.md
index 3b122c15,b2a1f419..37da5e20
--- a/docs/project-format.md
+++ b/docs/project-format.md
@@@ -4,11 -4,13 +4,13 @@@ A `.sfproj` is an uncompressed ("stored
read by `loadProject` (src/core/Project.cpp). Commands: `save_project path=...`,
`open_project path=...`; `open` also recognises `.sfproj`.
-## Layout (version 3)
-- `manifest.json`: always first. `format` = `"SculptForge project"`, `version` (integer, currently 3),
+## Layout (version 4)
+- `manifest.json`: always first. `format` = `"SculptForge project"`, `version` (integer, currently 4),
`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`).
+ `render`, `brush`, `symmetry`, `gizmo`). `gizmo` (added in 0.5 without a version bump; older readers
+ ignore it) holds the Gizmo 3D's `pivot`, `pivot_placed`, `orient_surface`, `axis_x` / `axis_y` (its
+ surface axes), `use_mask`, `all_subtools` and `falloff`.
- Each `subtools[i]` holds `name`, `visible` (bool), `mesh`, `layers`, `active_layer` (sculpt layer
strokes go into, -1 = base) and, for a mesh that came from ZBrush, `goz_name` (the GoZ object name
that `goz_send` / `goz_receive` match on).
diff --cc docs/ui-design.md
index c65fdb3a,d1a019a9..17174d69
--- a/docs/ui-design.md
+++ b/docs/ui-design.md
@@@ -171,8 -171,8 +171,8 @@@ Every palette's body is one function `v
| **Script** | Show console (`` ` ``), Run script file..., Copy session as script, Clear console |
| **Splats** | `drawSplatSection` body (info, clean, transform, to mesh, save, clear) |
| **Stroke** | Stroke type (Dots, DragRect, Spray, LazyMouse) and its settings (spray scatter, lazy radius) |
-| **Tool** | The ZBrush "Tool" palette. Header: active SubTool name + tri count, `[Open] [Save] [Import]`. Sub-palettes (collapsing headers, one open at a time, Shift+click for more): **SubTool** (SubTools panel body), **Layers** (Layers / Blend Shapes body), **Geometry** (Subdivide Ctrl+D, Decimate, `cmd:decimate`), **Remesh** (Voxel remesh + resolution, the "DynaMesh" analogue), **Masking** (`drawMaskingSection`), **Polygroups** (`drawPolygroupsSection`), **Visibility** (Show all, Invert visibility, Delete hidden), **Export** (Game Ready panel body: LODs, Unreal, GLB/LOD chain), **Display** (wireframe, show mask/groups, material colour) |
+| **Tool** | The ZBrush "Tool" palette. Header: active SubTool name + tri count, `[Open] [Save] [Import]`. Sub-palettes (collapsing headers, one open at a time, Shift+click for more): **SubTool** (SubTools panel body), **Layers** (Layers / Blend Shapes body), **Geometry** (Lower Res / Higher Res, SDiv slider, Del Lower / Del Higher, Reconstruct Subdiv, Divide Ctrl+D + Smt, Subdivide, Decimate, `cmd:decimate`), **Remesh** (Voxel remesh + resolution, the "DynaMesh" analogue), **Masking** (`drawMaskingSection`), **Polygroups** (`drawPolygroupsSection`), **Visibility** (Show all, Invert visibility, Delete hidden), **Export** (Game Ready panel body: LODs, Unreal, GLB/LOD chain), **Display** (wireframe, show mask/groups, material colour) |
- | **Transform** | Symmetry X / Y / Z (X), Frame (F), Solo (`cmd:subtool_solo`), Wireframe |
+ | **Transform** | Draw / Move / Scale / Rotate (Q W E R, Gizmo 3D: pivot, World / Surface axes, Mask, All SubTools, Falloff, numeric entry; `cmd:transform`), Symmetry X / Y / Z (X), Frame (F), Solo (`cmd:subtool_solo`), Wireframe |
ZBrush has no separate top-level SubTool / Layer / Masking / Polygroups palettes, so they are **Tool** sub-palettes only. The Mesh and View menus disappear, and their items move to Tool > Geometry/Remesh and Render. Palettes are sorted by name at registration, so a new palette lands in alphabetical order automatically.
diff --cc src/app/UiTest.cpp
index 0596ab5c,f76fb2b3..45e2f823
--- a/src/app/UiTest.cpp
+++ b/src/app/UiTest.cpp
@@@ -56,7 -62,9 +62,10 @@@
// texture_painted (texels of the texture composite that aren't white),
// texture_mean_r / texture_mean_g / texture_mean_b (mean composite, sRGB 0-255),
// auto_uv_running
+// sdiv (the current subdivision level, 1 = base; 0 without levels), sdiv_levels (0 = none)
+ // gizmo_mode (0 Draw, 1 Move, 2 Scale, 3 Rotate), gizmo_hover (handle under the cursor,
+ // 0 = none, in gizmo_drag's order from 1), gizmo_falloff, pivot_x / pivot_y / pivot_z,
+ // center_x / center_y / center_z and size_x / size_y / size_z (active mesh bounds)
// (mesh values are the active SubTool's)
// snapshot remember the active mesh's vertices (for the moved* values)
// remember VALUE NAME keep VALUE's current value as $NAME
diff --cc src/core/Commands.cpp
index 17982ce8,9f1c1b11..2060f7a3
--- a/src/core/Commands.cpp
+++ b/src/core/Commands.cpp
@@@ -8,7 -8,7 +8,8 @@@
#include "core/EnginePresets.h"
#include "core/ImageTo3D.h"
#include "core/Masking.h"
+#include "core/Multires.h"
+ #include "core/MeshTransform.h"
#include "core/PathStroke.h"
#include "core/Polygroups.h"
#include "core/SubTools.h"
@@@ -755,7 -754,7 +756,8 @@@ CommandRegistry::CommandRegistry()
registerMaskingCommands(*this);
registerPolygroupCommands(*this);
registerSubToolCommands(*this);
+ registerSubdivCommands(*this); // subdiv_* (core/MultiresCommands.cpp)
+ registerTransformCommands(*this); // transform (core/MeshTransform.h)
registerPaintCommands(*this); // core/Polypaint.cpp
registerGozCommands(*this); // goz_import/export/send/receive, export_stl (io/GozCommands.cpp)
registerProjectCommands(*this); // keep last (core/Project.cpp)
diff --cc src/core/Undo.cpp
index bfdf822f,7873593b..75e7c92e
--- a/src/core/Undo.cpp
+++ b/src/core/Undo.cpp
@@@ -9,8 -9,8 +9,9 @@@ namespace sf
size_t UndoRecord::approxBytes() const {
size_t bytes = positions.bytes() + mask.bytes() + colors.bytes() + paintAlpha.bytes() + hidden.bytes() +
polygroups.bytes() + (paint ? paint->bytes() : 0) +
- (textureTiles ? textureTiles->bytes() : 0) + (texture ? texture->bytes() : 0);
+ (textureTiles ? textureTiles->bytes() : 0) + (texture ? texture->bytes() : 0) +
+ (subdiv ? subdiv->bytes() : 0);
+ for (const auto& l : layerOffsets) bytes += l.bytes();
if (mesh)
bytes += mesh->vertexCount() * ((2 + (mesh->base.empty() ? 0 : 1 + mesh->layers.size())) * sizeof(glm::vec3) +
8 * sizeof(uint32_t)) +
diff --cc tests/ui/whats_new.sfui
index 9c62159b,a590ecba..a0548e4c
--- a/tests/ui/whats_new.sfui
+++ b/tests/ui/whats_new.sfui
@@@ -4,7 -4,6 +4,8 @@@ click "Help##palette.help
click "What's New##help.whats_new"
expect_value guide_open == 1
expect_guide whats-new.md
+expect_text "Version 0.4.2"
expect_text "Next version (in development)"
+expect_text "Subdivision levels"
+ expect_text "Gizmo 3D: move, scale, rotate and pose"
shot whats-new