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.

Kelvinlets: 4% cutoff, at most 8 pieces a frame, 0.5% move floor; dense-mesh numbers in docs/performance.md

islandmed4765c64c6390
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2352781f..b84eb36e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,7 +17,7 @@ All notable changes to SculptForge are listed here. The format follows
incompressible clay that bulges around the thumb (100); **Sharpness** a tighter, cusped peak with the same
reach. Symmetry (the twist mirrors as a pseudovector), masks, hidden parts, sculpt layers, pressure and undo work
as with every brush. Each move touches only the points inside an adaptive cutoff (where the move is still more
- than 2% of its largest, the last part faded smoothly to 0), evaluates the kernel from a radial table, works out a
+ than 4% of its largest, the last part faded smoothly to 0), evaluates the kernel from a radial table, works out a
fast drag in pieces in one pass, and passes on only what moved to undo, normals and the BVH. KelvinGrab and
DetailClone are on the bottom shelf; all five are in the brush picker, the LightBox and the `stroke` command.
- **Capture from view** (<kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>C</kbd>, askNK's request): drag a square (Shift: a
diff --git a/docs/guide/sculpting.md b/docs/guide/sculpting.md
index f2d8ddb9..91525c17 100644
--- a/docs/guide/sculpting.md
+++ b/docs/guide/sculpting.md
@@ -367,9 +367,10 @@ exactly), pen pressure scales it, and like every brush they respect symmetry, th
layers, and each stroke is one undo step. They don't remesh with dynamic topology on (like Move).
> **How it stays fast:** a Kelvinlet's influence never quite reaches zero, so each move works out how far its
-> effect is still bigger than a few thousandths of the brush radius and only touches the points inside that
-> distance, fading the last part smoothly to nothing. A fast drag between two frames is worked out in small pieces
-> in one pass, so the brush keeps up on meshes of tens of millions of triangles (see
+> effect is still more than 4% of its largest (about twice the brush radius) and only touches the points inside
+> that distance, fading the last part smoothly to nothing. A fast drag between two frames is worked out in small
+> pieces in one pass. Because it reaches further than Move, it costs more: on models of 20 million triangles and
+> up, keep the brush small or step down a subdivision level for big elastic moves (see
> [Performance](performance.md)).
## Capture an alpha or a VDM from the model
diff --git a/docs/performance.md b/docs/performance.md
index 2856f75d..f005c269 100644
--- a/docs/performance.md
+++ b/docs/performance.md
@@ -12,6 +12,71 @@ 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.
+## Kelvinlet brushes and Capture from view (feat/kelvinlet-alpha)
+
+Measured with the stroke the app draws itself, on the benchmark sphere at 5M, 21M and 33M triangles (with
+subdivision levels, X symmetry on), Move as the reference in the same session:
+
+```
+SF_MEASURE_BRUSH=KelvinGrab sculptforge --run "new_bench_sphere millions=21" --measure-stroke 3,50
+SF_KELVIN_LOG=1 ... # per move: pieces, vertices, kernel / normals / BVH ms, renderer sync so far
+```
+
+**Caveat: the machine was shared** with several other builds and test runs (load average 14-57 on 10 cores, noted
+per row), and the tiling window manager sometimes gave the window half the size (those runs were thrown away:
+every figure here is with the full window, circle radius 176 px). Each figure is the better of two runs. Treat them
+as an upper bound and as a comparison with Move in the same conditions, not as clean numbers.
+
+Frame time while drawing the fast two-turn circle (mean / worst, ms), 50 px and 300 px brush (300 px is as big as
+the sphere on screen: a whole-model grab):
+
+| Mesh | Brush | Move | KelvinGrab | KelvinTwist | KelvinScale | load |
+|---|---|---:|---:|---:|---:|---:|
+| 5M | 50 px | 12.6 / 34 | **14.2 / 27** | **14.6 / 30** | 35.8 / 64 | 17-25 |
+| 5M | 300 px | 71 / 121 | 197 / 283 | 124 / 165 | 120 / 203 | 20-27 |
+| 21M | 50 px | 16.1 / 54 | 43.8 / 173 | 35.2 / 78 | 77.6 / 194 | 14-19 |
+| 21M | 300 px | 290 / 431 | 1297 / 1694 | 968 / 1505 | 935 / 1593 | 21-58 |
+| 33M | 50 px | 21.0 / 53 | 179 / 390 | 110 / 177 | 279 / 729 | 32-40 |
+| 33M | 300 px | 403 / 548 | (no frame in 3 s) | (no frame in 3 s) | 1546 / 3078 | 18-33 |
+
+A quieter moment (load ~19) gave KelvinGrab at 21M / 50 px **38.5 / 47.9 ms** (Move 28): about 850 000 vertices
+a move in 2 pieces, kernel 10 ms, normals 10-12 ms, BVH 3-4 ms, renderer sync about 15 ms a frame.
+
+What it costs and why:
+
+- A Kelvinlet never reaches zero, so the brush works out each move's own cutoff: the distance past which the move
+ is below 4% of its peak, the field faded smoothly to zero over the last 30% of it. That is about twice the
+ brush radius, so a Kelvinlet touches roughly 4x the area Move does, and with X symmetry twice that. This is what
+ makes the surface move with no edge; it is also the cost.
+- What was done to keep it interactive: the kernel comes from a 2048-entry radial table with the window folded in
+ (a lookup and a lerp per vertex instead of three square roots and divisions per scale); a fast drag between two
+ frames is integrated in up to 8 pieces inside one pass (one BVH query, one move, one normal and BVH update),
+ not one dab per piece (the first version: 470 ms frames at 5M / 50 px, now 14 ms); only vertices that move more
+ than 0.5% of the step go on to undo, normals, the BVH and the GPU (the rest add up to under 0.5% of the drag);
+ when few of the queried vertices moved, normals and the BVH are updated around those only.
+- Where it still falls short: on 21M+ meshes a fast drag makes frames slower, a slow frame makes the next move
+ longer (more pieces, a larger region), and the brush trails the pointer. A whole-model Kelvinlet at 21M-33M
+ (300 px) runs at about 1 frame a second. Next steps, not done here: carry the part of a long move past about
+ one radius over to the next frame (bounded work per frame, the grab catches up), a coarser cutoff while the
+ region is above a vertex budget, and sparse GPU uploads of only the moved vertices (the stroke pipeline work in
+ feat/zero-latency).
+
+The core per-move cost on its own (`sculptforge_tests kelvinlet_grab_dense_mesh_timing`, 1.3M triangles, r 0.3,
+no renderer): about 1.6-3.4 ms a move for 13 000-27 000 vertices, depending on the load.
+
+Capture from view (`sculptforge-cli`, a VDM horn and a DamStandard cut sculpted on the sphere, square half size
+0.15 unless noted):
+
+| Mesh | Height alpha 256 / 1024 px | VDM 256 px (points) | VDM, half size 0.4 (points) |
+|---|---:|---:|---:|
+| 21M (load ~20) | 18 / 106 ms | 117 ms (50 k) | 1329 ms (456 k) |
+| 33M (load ~21) | 55 / 240 ms | 439 ms (76 k) | 3852 ms (696 k) |
+
+The alpha is a z-buffer of the triangles under the square plus a box-blur high pass (three box blurs: the
+1024 px alpha went from 652 to 106 ms at 21M). The VDM is region finding (flood fill over the vertices near the
+square), a quadric fit to its outer band, and implicit fairing by conjugate gradients (90-270 iterations); on a
+large patch the serial flood fill and adjacency build dominate and are the next thing to parallelize.
+
## 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/app/PanelKelvinlet.cpp b/src/app/PanelKelvinlet.cpp
index f04654b8..1e9621b3 100644
--- a/src/app/PanelKelvinlet.cpp
+++ b/src/app/PanelKelvinlet.cpp
@@ -81,15 +81,15 @@ void App::kelvinTo(float x, float y) {
step.center = grabLast_;
step.delta = delta * amount;
step.travel = delta;
- step.substeps = std::clamp(int(std::ceil(glm::length(delta) / (0.4f * kelvinRadius_))), 1, 16);
+ step.substeps = std::clamp(int(std::ceil(glm::length(delta) / (0.4f * kelvinRadius_))), 1, 8);
static const bool log = std::getenv("SF_KELVIN_LOG") != nullptr;
const SculptTimings before = doc_.sculptor.timings;
doc_.sculptor.kelvinletStep(doc_.mesh, doc_.bvh, strokeBrush_, step, symmetry_);
if (log) {
const SculptTimings& t = doc_.sculptor.timings;
- SDL_Log("kelvin: %d pieces, %llu vertices, kernel %.1f normals %.1f bvh %.1f ms", step.substeps,
+ SDL_Log("kelvin: %d pieces, %llu vertices, kernel %.1f normals %.1f bvh %.1f ms (renderer sync so far %.0f ms in %llu frames)", step.substeps,
(unsigned long long)(t.vertices - before.vertices), t.kernelMs - before.kernelMs,
- t.normalsMs - before.normalsMs, t.bvhMs - before.bvhMs);
+ t.normalsMs - before.normalsMs, t.bvhMs - before.bvhMs, perf_.strokeSyncMs, (unsigned long long)perf_.strokeFrames);
}
grabLast_ = target;
} else {
diff --git a/src/core/Kelvinlet.cpp b/src/core/Kelvinlet.cpp
index 9ffb06d7..6babdb15 100644
--- a/src/core/Kelvinlet.cpp
+++ b/src/core/Kelvinlet.cpp
@@ -209,12 +209,12 @@ void Sculptor::kelvinletSingle(Mesh& mesh, BVH& bvh, const KelvinletKernel& k, c
case KelvinletKind::Scale: amount = std::abs(s.logScale), moveScale = amount * s.radius; break;
}
if (!(amount > 0.0f)) return;
- // Adaptive cutoff: where this step's displacement falls below epsilon = 2% of its largest (the window takes the
+ // Adaptive cutoff: where this step's displacement falls below epsilon = 4% of its largest (the window takes the
// rest smoothly to 0), so a slow drag of tiny steps still moves the surface and a fast one doesn't drag the whole
// mesh into the pass.
float peak = 0.0f;
for (int i = 0; i <= 32; ++i) peak = std::max(peak, k.envelope(1.5f * s.radius * float(i) / 32.0f));
- const float epsilon = std::max(0.02f * amount * peak, 1e-7f * s.radius);
+ const float epsilon = std::max(0.04f * amount * peak, 1e-7f * s.radius);
const float cut = k.cutoff(amount, epsilon, 3.0f * s.radius);
if (!(cut > 0.0f)) return;
// Grab: the load point travels from `center` to `center + travel` in `substeps` pieces, each a linear Kelvinlet
@@ -289,8 +289,8 @@ void Sculptor::kelvinletSingle(Mesh& mesh, BVH& bvh, const KelvinletKernel& k, c
}
}, 2048);
// Only what moves noticeably this step goes on (undo, normals, the BVH): the far part of the region moves
- // less than 0.2% of the step, which adds up to less than 0.2% of the whole drag.
- const float keep = 2e-3f * moveScale, keep2 = keep * keep;
+ // less than 0.5% of the step, which adds up to less than 0.5% of the whole drag.
+ const float keep = 5e-3f * moveScale, keep2 = keep * keep;
const size_t total = verts_.size();
size_t kept = 0;
for (size_t i = 0; i < total; ++i)