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.

Micro levels: guide chapter, performance figures (33M-1B), CHANGELOG; faster micro picking

islandmed6991c7dec17e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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-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/images/micro-300m.jpg b/docs/guide/images/micro-300m.jpg
new file mode 100644
index 00000000..44e04351
Binary files /dev/null and b/docs/guide/images/micro-300m.jpg differ
diff --git a/docs/guide/index.md b/docs/guide/index.md
index 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 help
diff --git a/docs/guide/micro-levels.md b/docs/guide/micro-levels.md
new file mode 100644
index 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.
+
+![A sphere with 335 million micro triangles: surface noise, a Clay Buildup band, Crease and Dam Standard lines (Micro 4, 420 MB)](images/micro-300m.jpg)
+
+> **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.md
index 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.md
index 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 usable
under 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, and
diff --git a/src/core/Micro.cpp b/src/core/Micro.cpp
index 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, const
const 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