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
Micro levels: guide chapter, performance figures (33M-1B), CHANGELOG; faster micro picking
islandmed6991c7dec17e
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 067543ea..91f2ef2f 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,25 @@ All notable changes to SculptForge are listed here. The format follows## [Unreleased]+### Added+- **Micro levels: hundreds of millions of sculptable polygons** (**Tool > Geometry > Micro**, `micro_*`+ commands). Above the highest subdivision level a SubTool can carry a micro level: per triangle a regular grid of+ 16-bit heights along the interpolated normal of the smooth (Phong-tessellated) base, instead of a mesh.+ 300 million micro triangles take 374 MB (1.25 bytes each; the whole app about 0.8 GB), where a mesh of that size+ would need about 27 GB. Unlike ZBrush's HD Geometry the whole model is sculptable at once.+ - Brushes: Standard, Clay, Clay Buildup, Smooth, Inflate, Flatten, Trim, Layer, Pinch / Crease / Dam Standard+ (as height sharpening), Mask; symmetry, Focal Shift, pressure and the mask apply. Big brushes are evaluated on+ a coarser grid and interpolated (scale-adaptive). Move reshapes the base below the micro level and the detail+ rides along (dual scale); "Move along normals" moves the micro surface itself.+ - Viewport: the micro surface is evaluated on the GPU per frame, with a level of detail per cluster and a+ triangle budget (2M on a laptop profile, 8M on a workstation, `RenderSettings::renderTriangleBudget`), crack+ free; the shading keeps every micro detail. 300M micro triangles orbit at 70+ fps with 4x antialiasing (M1 Pro).+ - Bake Micro (to a mesh), Export Displacement (32-bit EXR or 16-bit PNG, scalar or vector, over the base UVs).+ - Undo: a packed journal per stroke (tiles in Morton order, each tile's change predicted and packed).+ - Very large levels stay out of core in a sparse memory-mapped file (only what you touch is in memory).+ - Projects: format 7 when a SubTool has a micro level (others stay format 6 for older versions).+ - `sculptforge --bench-micro --bench-sizes 33,100,300` measures it. Guide chapter "Micro levels".+## [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/images/micro-300m.jpg b/docs/guide/images/micro-300m.jpgnew file mode 100644index 00000000..44e04351Binary files /dev/null and b/docs/guide/images/micro-300m.jpg differdiff --git a/docs/guide/index.md b/docs/guide/index.mdindex 6a712cab..42f9e3f8 100644--- a/docs/guide/index.md+++ b/docs/guide/index.md@@ -33,34 +33,35 @@ You can read it inside SculptForge (**Help > User Guide**, or <kbd>Shift</kbd>+<15. [Sculpt layers and blend shapes](layers.md)16. [Facial shapes and live face](facial-shapes.md)17. [Subdivision levels](subdivision-levels.md)-18. [Dynamic topology](dynamic-topology.md)-19. [Moving, rotating and posing (Gizmo 3D)](gizmo.md)-20. [Subdivide, remesh, decimate and LODs](geometry.md)-21. [Quad retopology and detail projection](retopology.md)+18. [Micro levels: hundreds of millions of polygons](micro-levels.md)+19. [Dynamic topology](dynamic-topology.md)+20. [Moving, rotating and posing (Gizmo 3D)](gizmo.md)+21. [Subdivide, remesh, decimate and LODs](geometry.md)+22. [Quad retopology and detail projection](retopology.md)## AI and capture-22. [Image and text to 3D](generate-3d.md)-23. [Gaussian splats](splats.md)-24. [Scan an object into a splat](scan-to-splat.md)-25. [From scan to sculptable mesh](scan-to-sculptable.md)-26. [Phone capture and AR](phone-capture.md)+23. [Image and text to 3D](generate-3d.md)+24. [Gaussian splats](splats.md)+25. [Scan an object into a splat](scan-to-splat.md)+26. [From scan to sculptable mesh](scan-to-sculptable.md)+27. [Phone capture and AR](phone-capture.md)## Files and pipelines-27. [Baking normal and displacement maps](baking.md)-28. [Exporting, Unreal and ZBrush](exporting.md)-29. [Working with Blender](blender.md)-30. [Projects, autosave and QuickSave](projects.md)-31. [Scripting and automation](scripting.md)-32. [SculptForge for studios](studios.md)+28. [Baking normal and displacement maps](baking.md)+29. [Exporting, Unreal and ZBrush](exporting.md)+30. [Working with Blender](blender.md)+31. [Projects, autosave and QuickSave](projects.md)+32. [Scripting and automation](scripting.md)+33. [SculptForge for studios](studios.md)## Reference-33. [Keyboard and mouse](shortcuts.md)-34. [Performance and big meshes](performance.md)-35. [Troubleshooting and FAQ](troubleshooting.md)-36. [Glossary](glossary.md)+34. [Keyboard and mouse](shortcuts.md)+35. [Performance and big meshes](performance.md)+36. [Troubleshooting and FAQ](troubleshooting.md)+37. [Glossary](glossary.md)## Getting helpdiff --git a/docs/guide/micro-levels.md b/docs/guide/micro-levels.mdnew file mode 100644index 00000000..f31d5973--- /dev/null+++ b/docs/guide/micro-levels.md@@ -0,0 +1,94 @@+# Micro levels: hundreds of millions of polygons++Subdivision levels store every vertex of every level. That is what lets you step down and reshape, but it costs+about 90 bytes per triangle: a 300 million triangle model would need 27 GB. **Micro levels** go past the highest+subdivision level without a mesh: each triangle of that level carries a regular grid of heights, one 16-bit number+per point, and the micro triangles are worked out on the fly by the brushes and by the graphics card. 300 million+micro triangles take about 0.4 GB, sculpt in real time and draw at 60+ frames per second.++++> **ZBrush:** HD Geometry also goes past the subdivision levels, but you sculpt it one small region at a time.+> A micro level is the whole model, all the time: every brush stroke, every view, every SubTool at once.++## Making a micro level++1. Divide the SubTool to a comfortable highest level (0.3 to 2 million triangles is the sweet spot).+2. In **Tool > Geometry**, set the **Micro** slider. Each step is four times the triangles: the label shows the+ total (Micro 4 on a 1.2 million triangle level is 300 million micro triangles).+3. Click **Divide to Micro**. The surface stays exactly as smooth as before; the micro level starts flat on it.++The micro level sits on the highest subdivision level, so step up to it first. While a micro level exists you+can't change subdivision levels (Bake it or delete it first).++| Micro level | Micro triangles per triangle | Memory per micro triangle |+|---|---|---|+| 3 | 64 | 1.4 bytes |+| 4 | 256 | 1.2 bytes |+| 5 | 1,024 | 1.1 bytes |+| 6, 7 | 4,096, 16,384 | 1.05 bytes |++For the smoothest view, prefer a higher micro level on fewer base triangles: 300 million as Micro 5 on 300,000+triangles draws faster than Micro 4 on 1.2 million.++## Sculpting++These brushes work on micro levels: **Standard**, **Clay**, **Clay Buildup**, **Smooth**, **Inflate**,+**Flatten**, **Trim**, **Layer**, **Pinch**, **Crease**, **Dam Standard** and **Mask** (with+<kbd>Ctrl</kbd>). Symmetry, Focal Shift, pressure and the mask work as usual, and every stroke is one undo step.++- A micro level stores one height per point, so it moves the surface in and out, never sideways. **Pinch**,+ **Crease** and **Dam Standard** sharpen the height profile instead of pulling points together (the result+ looks the same for creases and folds).+- **Move** reshapes the level below the micro level (the base) and the micro detail rides along on it, in its own+ frame: drag an ear back without smearing the pores. To move the micro surface itself along its normals, tick+ **Move along normals**.+- Big brushes are evaluated on a coarser grid (about 50 points across the brush) and the change is spread+ smoothly over the points in between, so a brush that covers half the model costs about as much as a small one.+ The detail under it is kept.+- Brushes that slide the surface (Snake Hook, Nudge, VDM stamps) and custom recipe brushes don't apply to micro+ levels; recipe brushes act as Standard.++Polypaint, sculpt layers, polygroup colours and the wireframe aren't shown on micro levels yet.++## Baking down and exporting++- **Bake Micro** makes a regular mesh of the micro level in a new SubTool (the micro level stays). `micro_bake+ level=3` bakes a coarser micro level; `replace=true` replaces this SubTool instead. UVs, polygroups, hidden faces+ and the micro mask carry over.+- **Export Displacement** writes a 32-bit EXR displacement map over the base UVs (needs UVs) next to the project:+ the height of the micro surface above the flat base triangles, along the interpolated normal. `micro_export_displacement+ path=detail.png type=vector` writes a vector map (object space) or a 16-bit PNG (mid-grey = 0; the message says+ the scale).++Projects keep micro levels (project format 7; projects without one are still written as format 6, so older+versions open them). Untouched areas take almost no room in the file.++## Very large levels and laptops++A micro level that would take more than a quarter of the computer's memory is kept **out of core**: in a file in+the cache folder (`~/.cache/sculptforge`), of which only the parts you sculpt or look at stay in memory. A+billion micro triangles then fit on a 16 GB machine. The status line under the slider says when a level is out+of core. `SF_MICRO_OUT_OF_CORE=1` forces it (for testing); `SF_MICRO_SWAP_DIR` picks the folder.++How many triangles a frame draws for micro levels follows the machine: the view lowers the detail of far and+small areas until a frame fits the budget (2 million on a laptop profile, 8 million on a workstation).++## Scripting++| Command | What it does |+|---|---|+| `micro_divide level=4` or `micro_divide triangles=300` | Add a micro level (by level, or about this many million micro triangles) |+| `micro_delete` | Remove it (undoable) |+| `micro_info` | Level, micro triangles, memory, displacement range |+| `micro_bake level=4 replace=false` | Bake down to a mesh |+| `micro_export_displacement path=disp.exr size=4096 type=scalar` | Displacement map over the base UVs |+| `micro_noise amplitude=0.0015 scale=120` | Procedural surface noise over the whole micro level |++`sculptforge --bench-micro --bench-sizes 33,100,300` measures memory, brush and frame times on your computer.++## See also++- [Subdivision levels](subdivision-levels.md)+- [Performance](performance.md)+- [Baking normal and displacement maps](baking.md)diff --git a/docs/guide/subdivision-levels.md b/docs/guide/subdivision-levels.mdindex c659f77f..2056b471 100644--- a/docs/guide/subdivision-levels.md+++ b/docs/guide/subdivision-levels.md@@ -150,3 +150,8 @@ you come back takes a moment longer (about 0.1 s at that size) while the level i> **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.++## Past the highest level++For more detail than the computer can hold as a mesh (hundreds of millions of polygons), add a micro level on+top of the highest level: see [Micro levels](micro-levels.md).diff --git a/docs/performance.md b/docs/performance.mdindex 2856f75d..65c73410 100644--- a/docs/performance.md+++ b/docs/performance.md@@ -12,6 +12,69 @@ sculptforge-cli --bench ... # the same without the GPU (CI,Machine for all figures: Apple M1 Pro (8 performance + 2 efficiency cores, 32 GB unified memory, 30 GB usableunder Asahi Linux), integrated GPU, Mesa 26.1 (OpenGL 4.6). How the benchmark works is described under v0.5 below.+## Micro-displacement levels: 300M-1B sculptable triangles (feat/micromesh)++```+sculptforge --bench-micro --bench-sizes 33,100,300 [--bench-micro-level 5] [--bench-brushes TEXT]+sculptforge-cli --bench-micro ... # without the GPU: memory, brush and shading times+```++A micro level (core/Micro.h) stores the surface above the highest subdivision level as one 16-bit height per+point of a regular grid on each base triangle, along the interpolated normal of the Phong-tessellated base.+Micro triangles are never stored: brushes evaluate them on the CPU, the renderer in its vertex shader+(render/MicroRenderer.h). The benchmark divides a bench sphere to the size, sculpts strokes of 30 dabs with X+symmetry (two dabs a step) and orbits. M1 Pro, Release; the machine was shared with other jobs during these runs+(load average 10-20), so treat single rows as +/-30%.++Memory and frames:++| | 33M (Micro 4) | 104M (Micro 4) | 299M (Micro 4) | 299M (Micro 5) | **1.02B (Micro 5)** |+|---|---:|---:|---:|---:|---:|+| Base triangles | 130k | 406k | 1.2M | 292k | 995k |+| Micro level in memory | 42 MB | 130 MB | 374 MB | 332 MB | 1131 MB |+| per micro triangle / micro vertex | 1.25 / 2.50 B | 1.25 / 2.50 B | 1.25 / 2.50 B | 1.11 / 2.22 B | 1.11 / 2.22 B |+| Process RSS, everything | 263 MB | 432 MB | 801 MB | 710 MB | **1713 MB** |+| GPU buffers | 125 MB | 392 MB | 1128 MB | 997 MB | 3398 MB |+| Divide to micro | 5 ms | 32 ms | 60 ms | 29 ms | 93 ms |+| First shading + upload | 0.1 s | 0.7 s | 1.2 s | 1.7 s | 5.1 s |+| Orbit, 4x AA | 8.3 ms | 9.7 ms | 14.0 ms | 8.9 ms | 13.4 ms |+| Orbit, no AA / moving | 5.0 / 2.9 ms | 6.6 / 4.7 ms | 10.4 / 4.5 ms | 6.2 / 4.1 ms | 11.3 / 5.0 ms |+| Triangles drawn (still / moving) | 4.3M / 1.1M | 3.9M / 1.0M | 3.4M / 0.9M | 3.4M / 0.9M | 3.0M / 0.8M |+| Save / open project | 31 / 61 ms | 71 / 100 ms | 217 / 285 ms | 187 / 264 ms | 649 / 489 ms |++The same 300M as a plain mesh would need about 27 GB (90 B per triangle, see 33M below). The frame time follows+the triangle budget and the number of base triangles on screen, not the micro triangle count: 33M at Micro 4+and 299M at Micro 5 (130k and 292k base triangles) both draw in 8-9 ms. Patches of one or four triangles are+drawn unrolled (gl_VertexID), not instanced: instancing them cost 21 ms a moving frame at 299M, unrolled 4.4 ms.++Brushes, per dab step (both mirrors), GPU upload included:++| | 33M | 104M | 299M (Micro 4) | 299M (Micro 5) | 1.02B (Micro 5) |+|---|---:|---:|---:|---:|---:|+| Standard (r 0.12, ~64 px) | 2.4 ms | 11 ms | 13 ms | 17 ms | 39 ms |+| Standard, 300 px (r 0.56) | 13.5 ms | 56 ms | 115 ms | 48 ms | 283 ms |+| Smooth (large, r 0.4) | 9.4 ms | 21 ms | 50 ms | 44 ms | 54 ms |+| Move, 300 px (base cage) | 13 ms | 19 ms | 58 ms (45 after the pick fix) | 22 ms | 55 ms |+| Undo step, Standard stroke (30 dabs) | 0.6 MB | 1.7 MB | 4.7 MB | 3.4 MB | 11.2 MB |++Scale-adaptive brushes: a dab is evaluated on grid points `stride` apart (about 48 across its radius) and+interpolated in between, so the evaluation (the "kernel" column of the report) stays bounded; writing the+interpolated values, stitching and the GPU upload still grow with the points under the brush. The 300 px grab+(Move) deforms the base cage and doesn't touch the micro level at all: 20 ms at 31M against 45 ms at 299M (Micro 4,+ten times the base triangles) in one run; at Micro 5 (2.4x the base) 22 ms. Picking at 299M went from 37 to 11 ms+once the candidates were filtered by their own displacement range along the ray.++Undo journal: tiles in Morton order, each the stroke's change predicted from its neighbour and packed (minimum ++bit width): about a third of whole tiles. A short stroke stays under the 500 KB target (10 dabs of r 0.15 at+5M: 31 KB); the benchmark's 30-dab strokes over 300M are 2-5 MB, limited by the rounding noise each dab leaves+(2-4 bits per point). A whole-surface edit (micro_noise) keeps whole tiles.++What a frame still costs: the CPU shading (normals, curvature) of what a dab changed, about 20 ns per grid point,+within a budget per frame (TierConfig::shadeBudgetPoints, 3M: the rest of a big dab's normals follow over the next+frames); the first full shading of a level (1-5 s). Candidates: shading on the GPU from the displacement texture+(needs the edge neighbours in the fragment shader), and storing the coarse part of big strokes on a coarse grid+(multires-style) so a 300 px dab writes thousands of points instead of millions.+## Next version: big brushes on dense meshes (feat/perf-pass)What a user feels on a heavy model is a large brush: how far it trails the pointer, how long a frame takes, anddiff --git a/src/core/Micro.cpp b/src/core/Micro.cppindex 0cdb88aa..3531a773 100644--- a/src/core/Micro.cpp+++ b/src/core/Micro.cpp@@ -485,6 +485,20 @@ bool microRaycast(const Mesh& m, const BVH& bvh, const glm::vec3& origin, constconst float reach = mm.bulgeMax + float(mm.rangeMax) * mm.step;std::vector<uint32_t> cand;bvh.queryTriangles(m, base.position, 2.0f * reach + 1e-7f, cand);+ // Only the triangles whose own reach (their bulge and displacement range) the ray passes through.+ const glm::vec3 inv(1.0f / (std::abs(dir.x) > 1e-20f ? dir.x : 1e-20f), 1.0f / (std::abs(dir.y) > 1e-20f ? dir.y : 1e-20f),+ 1.0f / (std::abs(dir.z) > 1e-20f ? dir.z : 1e-20f));+ std::erase_if(cand, [&](uint32_t t) {+ if (t == base.triangle) return false;+ MicroTriangle T;+ T.set(m, t, mm.n);+ const float grow = triangleBulge(T) + float(mm.triRange[t]) * mm.step;+ const glm::vec3 lo = glm::min(T.p[0], glm::min(T.p[1], T.p[2])) - grow, hi = glm::max(T.p[0], glm::max(T.p[1], T.p[2])) + grow;+ const glm::vec3 t0 = (lo - origin) * inv, t1 = (hi - origin) * inv;+ const glm::vec3 tn = glm::min(t0, t1), tf = glm::max(t0, t1);+ const float enter = std::max({tn.x, tn.y, tn.z, 0.0f}), leave = std::min({tf.x, tf.y, tf.z});+ return enter > leave;+ });if (std::find(cand.begin(), cand.end(), base.triangle) == cand.end()) cand.push_back(base.triangle);constexpr size_t kMaxCandidates = 4096;if (cand.size() > kMaxCandidates) { // a huge displacement range: rank by distance and keep the nearest