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.

29.7 KB
Raw Blame
// SculptForge - open source digital sculpting
// SPDX-License-Identifier: GPL-3.0-or-later
//
// Kelvinlet brushes (core/Kelvinlet.h): the kernels (normalization, multi-scale far-field cancellation,
// incompressibility, exact twist, pinch without folding), the brushes on meshes (symmetry, mask, undo, sculpt
// layers, adaptive cutoff, bulge with Squash), Detail Clone, and Alpha / VDM from the viewport
// (core/ViewCapture.h) with its commands. Timing checks run with SF_BENCH_LIMITS=1.
#include "TestHarness.h"

#include "core/Commands.h"
#include "core/Kelvinlet.h"
#include "core/PathStroke.h"
#include "core/Primitives.h"
#include "core/Sculpt.h"
#include "core/ThreadPool.h"
#include "core/Vdm.h"
#include "core/ViewCapture.h"

#include <algorithm>
#include <chrono>
#include <cmath>
#include <cstdlib>
#include <filesystem>

using namespace sf;

namespace {

bool run(Document& d, const std::string& name, const Args& args = {}) {
    static CommandRegistry registry;
    const CommandResult r = registry.execute(d, name, args);
    if (!r.ok) std::printf("  %s: %s\n", name.c_str(), r.message.c_str());
    return r.ok;
}

uint32_t nearest(const Mesh& m, const glm::vec3& p) {
    uint32_t best = 0;
    for (uint32_t v = 1; v < m.vertexCount(); ++v)
        if (glm::distance(m.positions[v], p) < glm::distance(m.positions[best], p)) best = v;
    return best;
}

KelvinletSettings squash(float s, float sharp = 0.0f) {
    KelvinletSettings k;
    k.squash = s;
    k.sharpness = sharp;
    return k;
}

// Numerical divergence of the grab field at r.
float divergence(const KelvinletKernel& k, const glm::vec3& r, const glm::vec3& f) {
    const float h = 1e-3f;
    float div = 0.0f;
    for (int a = 0; a < 3; ++a) {
        glm::vec3 e(0.0f);
        e[a] = h;
        div += (kelvinletGrab(k, r + e, f)[a] - kelvinletGrab(k, r - e, f)[a]) / (2.0f * h);
    }
    return div;
}

PathStroke pathAlongX(float x0, float x1, float radius, float y = 0.0f) {
    PathStroke st;
    st.points = {glm::vec3(x0, y, 2.0f), glm::vec3(x1, y, 2.0f)};
    st.view = glm::vec3(0.0f, 0.0f, -1.0f);
    st.radius = radius;
    st.strength = 0.5f;
    st.curve = false;
    return st;
}

} // namespace

TEST(kelvinlet_kernels_are_normalized_and_localized) {
    for (float sq : {0.0f, 0.5f, 1.0f})
        for (float sharp : {0.0f, 1.0f}) {
            const KelvinletSettings s = squash(sq, sharp);
            for (bool tight : {false, true}) {
                const KelvinletKernel k = makeKelvinletKernel(KelvinletKind::Grab, 0.2f, s, tight);
                // The grabbed point moves exactly with the cursor.
                const glm::vec3 d(0.03f, -0.01f, 0.02f);
                CHECK(glm::length(kelvinletGrab(k, glm::vec3(0.0f), d) - d) < 1e-5f);
                // The far-field terms cancel: sum w = 0 (1/r) and, for three scales, sum w e^2 = 0 (1/r^3).
                float sw = 0.0f, swe = 0.0f;
                for (int i = 0; i < k.scales; ++i) sw += k.w[i], swe += k.w[i] * k.eps[i] * k.eps[i];
                CHECK(std::abs(sw) < 1e-5f);
                if (k.scales == 3) CHECK(std::abs(swe) < 1e-5f * k.eps[2] * k.eps[2]);
                // About half way at half the radius (the Move brush's footprint), almost nothing at 3 radii.
                const float half = glm::length(kelvinletGrab(k, glm::vec3(0.1f, 0.0f, 0.0f), glm::vec3(0, 0, 1)));
                if (sharp == 0.0f && !tight) CHECK(half > 0.15f && half < 0.8f);
                CHECK(k.envelope(0.6f) < 0.03f);
                // The cutoff grows with the step and stays inside the search range.
                const float small = k.cutoff(0.001f, 0.0006f, 0.8f), big = k.cutoff(0.05f, 0.0006f, 0.8f);
                CHECK(small > 0.0f && small < big && big <= 0.8f);
            }
            for (KelvinletKind kind : {KelvinletKind::Twist, KelvinletKind::Scale}) {
                const KelvinletKernel k = makeKelvinletKernel(kind, 0.2f, s);
                CHECK(std::abs(k.profile(0.0f) - 1.0f) < 1e-5f);
                CHECK(k.profile(0.6f * 0.6f) < 0.01f);
            }
        }
    // Sharpness gives a tighter peak with the same far field.
    const KelvinletKernel soft = makeKelvinletKernel(KelvinletKind::Grab, 0.2f, squash(0.5f, 0.0f));
    const KelvinletKernel sharp = makeKelvinletKernel(KelvinletKind::Grab, 0.2f, squash(0.5f, 1.0f));
    CHECK(sharp.envelope(0.08f) < soft.envelope(0.08f));
}

TEST(kelvinlet_squash_is_poissons_ratio) {
    // Incompressible clay (Squash 1, nu = 0.49) is nearly divergence free; rubber (Squash 0) is not.
    const KelvinletKernel clay = makeKelvinletKernel(KelvinletKind::Grab, 0.2f, squash(1.0f));
    const KelvinletKernel rubber = makeKelvinletKernel(KelvinletKind::Grab, 0.2f, squash(0.0f));
    const glm::vec3 f(0.0f, 0.0f, 0.05f);
    float dc = 0.0f, dr = 0.0f;
    for (const glm::vec3 r : {glm::vec3(0.05f, 0.0f, 0.05f), glm::vec3(0.1f, 0.05f, -0.08f), glm::vec3(0.0f, 0.12f, 0.1f)}) {
        dc += std::abs(divergence(clay, r, f));
        dr += std::abs(divergence(rubber, r, f));
    }
    CHECK(dc < 0.1f * dr);
    // Pressing a flat sheet in: incompressible clay bulges up around the dent, more than rubber does.
    auto bulge = [](float sq) {
        Document d = makeDoc(makePlane(160, 2.0f));
        d.sculptor.kelvinlet.squash = sq;
        CHECK(d.sculptor.beginStroke(d.mesh, "KelvinGrab"));
        DabParams p;
        p.center = glm::vec3(0.0f);
        p.viewDir = glm::vec3(0.0f, -1.0f, 0.0f);
        p.radius = 0.25f;
        p.strength = 0.5f;
        p.strokeDelta = glm::vec3(0.0f, -0.15f, 0.0f);
        d.sculptor.dab(d.mesh, d.bvh, BrushType::KelvinGrab, p, Symmetry{false, false, false});
        d.undo.push(d.sculptor.endStroke());
        float up = 0.0f;
        for (const glm::vec3& q : d.mesh.positions) up = std::max(up, q.y);
        const float centre = d.mesh.positions[nearest(d.mesh, glm::vec3(0.0f, -0.15f, 0.0f))].y;
        CHECK(centre < -0.12f); // the thumb pushed the centre down with it
        return up;
    };
    const float clayUp = bulge(1.0f), rubberUp = bulge(0.0f);
    CHECK(clayUp > 0.0f);
    CHECK(clayUp > rubberUp * 1.3f);
}

TEST(kelvinlet_twist_is_a_rotation_and_scale_never_folds) {
    const KelvinletKernel tw = makeKelvinletKernel(KelvinletKind::Twist, 0.2f, KelvinletSettings{});
    const glm::vec3 axis(0.0f, 0.0f, 1.0f);
    for (const glm::vec3 r : {glm::vec3(0.05f, 0.0f, 0.0f), glm::vec3(0.1f, 0.1f, 0.03f), glm::vec3(0.3f, -0.2f, 0.1f)}) {
        const glm::vec3 moved = r + kelvinletTwist(tw, r, axis, 2.5f);
        CHECK(std::abs(glm::length(moved) - glm::length(r)) < 1e-5f); // stays on its shell
        CHECK(std::abs(moved.z - r.z) < 1e-6f);                       // and its height along the axis
    }
    // The centre turns by the full angle.
    const glm::vec3 nearCentre(1e-4f, 0.0f, 0.0f);
    const glm::vec3 m = nearCentre + kelvinletTwist(tw, nearCentre, axis, 0.5f);
    CHECK(std::abs(std::atan2(m.y, m.x) - 0.5f) < 1e-3f);
    // A hard pinch keeps the order of points along a ray (no folding through the centre).
    const KelvinletKernel sc = makeKelvinletKernel(KelvinletKind::Scale, 0.2f, KelvinletSettings{});
    float last = 0.0f;
    for (int i = 1; i <= 100; ++i) {
        const glm::vec3 r(0.006f * float(i), 0.0f, 0.0f);
        const float len = glm::length(r + kelvinletScale(sc, r, -4.0f));
        CHECK(len > last);
        last = len;
    }
    const glm::vec3 r(0.01f, 0.0f, 0.0f);
    CHECK(glm::length(r + kelvinletScale(sc, r, std::log(2.0f))) > 0.019f); // doubles at the centre
}

TEST(kelvinlet_grab_on_a_sphere_symmetry_mask_undo) {
    Document d = makeDoc(makeIcosphere(5, 1.0f));
    const auto start = d.mesh.positions;
    // Mask the -Y half.
    auto& mask = d.mesh.ensureMask(0.0f);
    for (uint32_t v = 0; v < d.mesh.vertexCount(); ++v)
        if (d.mesh.positions[v].y < -0.05f) mask[v] = 1.0f;
    PathStroke st = pathAlongX(0.4f, 0.75f, 0.25f, 0.3f);
    st.symmetry = Symmetry{true, false, false};
    std::string err;
    CHECK(strokePath(d, nullptr, BrushType::KelvinGrab, st, err) > 0);
    size_t moved = 0;
    float worstMirror = 0.0f, maskedMove = 0.0f, rimMove = 0.0f, maxMove = 0.0f;
    for (uint32_t v = 0; v < d.mesh.vertexCount(); ++v) {
        const glm::vec3 dv = d.mesh.positions[v] - start[v];
        maxMove = std::max(maxMove, glm::length(dv));
        if (glm::length(dv) > 1e-6f) ++moved;
        if (mask[v] == 1.0f) maskedMove = std::max(maskedMove, glm::length(dv));
        // At the edge of what moved (a moved vertex next to one that didn't), it moved next to nothing.
        if (mask[v] == 0.0f && glm::length(dv) > 0.0f)
            for (uint32_t n : d.mesh.neighbors(v))
                if (mask[n] == 0.0f && d.mesh.positions[n] == start[n]) rimMove = std::max(rimMove, glm::length(dv));
    }
    CHECK(moved > 200);
    CHECK(moved < d.mesh.vertexCount()); // the cutoff left the far side alone
    CHECK(maskedMove == 0.0f);
    CHECK(maxMove > 0.1f);
    // No hard falloff edge: the field fades to nothing before the cutoff.
    CHECK(rimMove < 0.01f * maxMove);
    // Symmetry: compare each vertex of the +X half with its start-mirror.
    {
        Mesh ref = makeIcosphere(5, 1.0f);
        BVH bvh;
        bvh.build(ref);
        int checked = 0;
        for (uint32_t v = 0; v < ref.vertexCount() && checked < 400; v += 7) {
            const glm::vec3 p = ref.positions[v];
            if (p.x < 0.2f) continue;
            std::vector<uint32_t> near;
            bvh.queryVertices(ref, glm::vec3(-p.x, p.y, p.z), 1e-4f, near);
            if (near.size() != 1) continue;
            const glm::vec3 a = d.mesh.positions[v] - p, b = d.mesh.positions[near[0]] - ref.positions[near[0]];
            worstMirror = std::max(worstMirror, glm::length(a - glm::vec3(-b.x, b.y, b.z)));
            ++checked;
        }
        CHECK(checked > 50);
        CHECK(worstMirror < 1e-4f);
    }
    CHECK(d.undo.canUndo());
    d.undo.undo(d.mesh, d.bvh);
    float back = 0.0f;
    for (uint32_t v = 0; v < d.mesh.vertexCount(); ++v) back = std::max(back, glm::distance(d.mesh.positions[v], start[v]));
    CHECK(back < 1e-6f);
}

TEST(kelvinlet_brushes_write_into_sculpt_layers) {
    Document d = makeDoc(makeIcosphere(4, 1.0f));
    CHECK(run(d, "layer_add", {{"name", std::string("Elastic")}}));
    const auto start = d.mesh.positions;
    for (BrushType type : {BrushType::KelvinGrab, BrushType::KelvinTwist, BrushType::KelvinScale, BrushType::KelvinSnake}) {
        std::string err;
        CHECK(strokePath(d, nullptr, type, pathAlongX(0.0f, 0.3f, 0.3f), err) > 0);
    }
    float layerSum = 0.0f;
    for (const glm::vec3& o : d.mesh.layers.back().delta) layerSum += glm::length(o);
    CHECK(layerSum > 0.1f);
    // Turning the layer off puts the base back.
    CHECK(run(d, "layer_set_weight", {{"index", 0.0}, {"weight", 0.0}}));
    float worst = 0.0f;
    for (uint32_t v = 0; v < d.mesh.vertexCount(); ++v) worst = std::max(worst, glm::distance(d.mesh.positions[v], start[v]));
    CHECK(worst < 1e-4f);
}

TEST(kelvinlet_twist_and_snake_strokes) {
    // Twist turns the surface around the view axis (clockwise for a drag to the right).
    Document d = makeDoc(makePlane(120, 2.0f));
    const auto start = d.mesh.positions;
    PathStroke st;
    st.points = {glm::vec3(0.0f, 1.0f, 0.0f), glm::vec3(0.2f, 1.0f, 0.0f)};
    st.view = glm::vec3(0.0f, -1.0f, 0.0f);
    st.radius = 0.4f;
    st.strength = 0.5f;
    st.curve = false;
    std::string err;
    CHECK(strokePath(d, nullptr, BrushType::KelvinTwist, st, err) > 0);
    const uint32_t v = nearest(d.mesh, glm::vec3(0.1f, 0.0f, 0.0f));
    const glm::vec3 a = start[v], b = d.mesh.positions[v];
    CHECK(std::abs(glm::length(b) - glm::length(a)) < 1e-3f); // a rotation in the sheet
    CHECK(std::abs(b.y) < 1e-6f);
    CHECK(glm::length(b - a) > 0.02f);
    // Scale: a drag to the left pinches toward the press point, to the right swells.
    for (float dir : {-1.0f, 1.0f}) {
        Document sc = makeDoc(makePlane(120, 2.0f));
        PathStroke ps = st;
        ps.points = {glm::vec3(0.0f, 1.0f, 0.0f), glm::vec3(0.2f * dir, 1.0f, 0.0f)};
        CHECK(strokePath(sc, nullptr, BrushType::KelvinScale, ps, err) > 0);
        const uint32_t q = nearest(makePlane(120, 2.0f), glm::vec3(0.1f, 0.0f, 0.05f));
        const float r0 = glm::length(start[q]), r1 = glm::length(sc.mesh.positions[q]);
        std::printf("  scale %+.0f: %.4f -> %.4f\n", dir, r0, r1);
        CHECK(dir < 0.0f ? r1 < r0 * 0.9f : r1 > r0 * 1.1f);
    }
    // Snake pulls a tapering horn straight out of a sphere.
    Document s = makeDoc(makeIcosphere(6, 1.0f));
    PathStroke pull;
    pull.points = {glm::vec3(0.0f, 0.0f, 2.0f), glm::vec3(0.0f, 0.0f, 2.0f)};
    // (headless Snake follows the path in the view plane: pull out to the right of a side view)
    pull.points = {glm::vec3(0.0f, 0.9f, 2.0f), glm::vec3(0.0f, 1.6f, 2.0f)};
    pull.view = glm::vec3(0.0f, 0.0f, -1.0f);
    pull.radius = 0.2f;
    pull.strength = 0.5f;
    pull.curve = false;
    CHECK(strokePath(s, nullptr, BrushType::KelvinSnake, pull, err) > 0);
    float top = 0.0f;
    for (const glm::vec3& p : s.mesh.positions) top = std::max(top, p.y);
    std::printf("  snake: tip at %.3f\n", top);
    CHECK(top > 1.3f); // pulled well out of the unit sphere
}

// A round dome (Z only), so each stamp is one peak.
std::shared_ptr<const VectorDisplacement> domeVdm() {
    VectorDisplacement v;
    v.name = "Dome";
    v.width = v.height = 64;
    v.vectors.resize(64 * 64);
    for (int y = 0; y < 64; ++y)
        for (int x = 0; x < 64; ++x) {
            const float u = (float(x) + 0.5f) / 32.0f - 1.0f, w = (float(y) + 0.5f) / 32.0f - 1.0f;
            const float d2 = u * u + w * w;
            v.vectors[size_t(y) * 64 + size_t(x)] = glm::vec3(0.0f, 0.0f, d2 < 0.5f ? 0.3f * (1.0f - d2 / 0.5f) : 0.0f);
        }
    return std::make_shared<const VectorDisplacement>(std::move(v));
}

TEST(detail_clone_stamps_along_the_stroke) {
    Document d = makeDoc(makePlane(200, 2.0f));
    d.brushVdm = domeVdm();
    d.sculptor.kelvinlet.cloneSpacing = 1.0f;
    PathStroke st;
    st.points = {glm::vec3(-0.6f, 1.0f, 0.0f), glm::vec3(0.6f, 1.0f, 0.0f)};
    st.view = glm::vec3(0.0f, -1.0f, 0.0f);
    st.radius = 0.1f;
    st.strength = 0.5f;
    st.curve = false;
    std::string err;
    CHECK(strokePath(d, nullptr, BrushType::DetailClone, st, err) > 0);
    // Count the separate stamps: height peaks along x.
    constexpr int kBins = 120;
    float height[kBins] = {};
    for (const glm::vec3& p : d.mesh.positions) {
        const int b = std::clamp(int((p.x + 1.0f) / 2.0f * kBins), 0, kBins - 1);
        height[b] = std::max(height[b], p.y);
    }
    float top = 0.0f;
    for (float h : height) top = std::max(top, h);
    int peaks = 0;
    for (int i = 1; i + 1 < kBins; ++i)
        if (height[i] > 0.4f * top && height[i] >= height[i - 1] && height[i] > height[i + 1]) ++peaks;
    std::printf("  detail clone: %d stamps, top %.3f\n", peaks, top);
    CHECK(top > 0.02f);
    CHECK(peaks >= 5 && peaks <= 8); // 1.2 long, a stamp every 0.2
    // A click stamps once.
    Document c = makeDoc(makePlane(120, 2.0f));
    c.brushVdm = builtinVdm("horn");
    PathStroke click = st;
    click.points = {glm::vec3(0.0f, 1.0f, 0.0f)};
    click.radius = 0.3f;
    CHECK(strokePath(c, nullptr, BrushType::DetailClone, click, err) == 1);
    float h = 0.0f;
    for (const glm::vec3& p : c.mesh.positions) h = std::max(h, p.y);
    CHECK(h > 0.05f);
}

TEST(capture_height_alpha_from_view) {
    Document d = makeDoc(makePlane(160, 2.0f));
    // A bump in the middle.
    PathStroke st;
    st.points = {glm::vec3(0.0f, 1.0f, 0.0f)};
    st.view = glm::vec3(0.0f, -1.0f, 0.0f);
    st.radius = 0.3f;
    st.strength = 1.0f;
    std::string err;
    for (int i = 0; i < 4; ++i) CHECK(strokePath(d, nullptr, BrushType::Standard, st, err) == 1);
    d.syncBvh();
    const CaptureFrame f = makeCaptureFrame(glm::vec3(0.0f), glm::vec3(0.0f, -1.0f, 0.0f), glm::vec3(0.0f, 0.0f, -1.0f), 0.5f);
    CaptureOptions opt;
    opt.resolution = 128;
    opt.smoothing = 0.0f;
    BrushAlpha a;
    CaptureInfo info;
    CHECK(captureHeightAlpha(d.mesh, d.bvh, f, opt, a, err, &info));
    CHECK(a.width == 128 && a.height == 128);
    CHECK(a.sample(0.0f, 0.0f) > 0.9f);
    CHECK(a.sample(0.95f, 0.95f) < 0.05f);
    CHECK(info.depthRange > 0.01f);
    opt.invert = true;
    CHECK(captureHeightAlpha(d.mesh, d.bvh, f, opt, a, err));
    CHECK(a.sample(0.0f, 0.0f) < 0.1f);
    // Nothing under the square: an error.
    const CaptureFrame off = makeCaptureFrame(glm::vec3(5.0f, 0.0f, 0.0f), glm::vec3(0.0f, -1.0f, 0.0f), glm::vec3(0.0f, 0.0f, -1.0f), 0.2f);
    CHECK(!captureHeightAlpha(d.mesh, d.bvh, off, opt, a, err) && !err.empty());
    // The command makes it the brush alpha and saves the PNG.
    const std::string png = tempPath("sf_capture_alpha.png");
    std::filesystem::remove(png);
    CHECK(run(d, "capture_alpha", {{"point", std::string("0,1,0")}, {"view", std::string("0,-1,0")}, {"size", 0.5},
                                   {"path", png}, {"name", std::string("Bump")}}));
    CHECK(d.brushAlpha.name == "Bump" && !d.brushAlpha.empty());
    CHECK(std::filesystem::exists(png));
    Image img;
    CHECK(Image::load(png, img, err) && img.width == 256);
}

TEST(capture_vdm_from_view_round_trips_a_stamp) {
    // Stamp an asymmetric, leaning VDM on a grid, capture it from the top, stamp the capture on a fresh grid:
    // the same shape comes back, sideways lean included (fairing a grid with its rim held finds its start).
    auto source = builtinVdm("ear curl");
    Document a = makeDoc(makePlane(200, 2.0f));
    a.brushVdm = source;
    const Args stamp = {{"point", std::string("0,1,0")}, {"view", std::string("0,-1,0")}, {"radius", 0.5}};
    CHECK(run(a, "vdm_stamp", stamp));
    a.syncBvh();
    const CaptureFrame f = makeCaptureFrame(glm::vec3(0.0f), glm::vec3(0.0f, -1.0f, 0.0f), glm::vec3(0.0f, 0.0f, -1.0f), 0.5f);
    CaptureOptions opt;
    opt.resolution = 256;
    opt.smoothing = 1.0f;
    opt.edgeFade = 0.03f;
    VectorDisplacement captured;
    CaptureInfo info;
    std::string err;
    CHECK(captureVdmFromView(a.mesh, a.bvh, f, opt, captured, err, &info));
    CHECK(info.vertices > 1000);
    CHECK(info.maxOffset > 0.1f);
    Document b = makeDoc(makePlane(200, 2.0f));
    b.brushVdm = std::make_shared<const VectorDisplacement>(captured);
    CHECK(run(b, "vdm_stamp", stamp));
    double err2 = 0.0, ref2 = 0.0, lateral = 0.0;
    const Mesh flat = makePlane(200, 2.0f);
    for (uint32_t v = 0; v < flat.vertexCount(); ++v) {
        const glm::vec3 da = a.mesh.positions[v] - flat.positions[v], db = b.mesh.positions[v] - flat.positions[v];
        err2 += double(glm::dot(da - db, da - db));
        ref2 += double(glm::dot(da, da));
        lateral += double(da.x * da.x + da.z * da.z);
    }
    CHECK(lateral > 0.05 * ref2); // the source really leans sideways
    const double rel = std::sqrt(err2 / std::max(ref2, 1e-12));
    std::printf("  capture_vdm round trip: relative RMS error %.3f, %zu points, %d CG iterations\n", rel, info.vertices,
                info.iterations);
    CHECK(rel < 0.2);
    // The command adds it to the VDMs and makes it the brush's.
    const size_t before = a.vdms.size();
    CHECK(run(a, "capture_vdm", {{"point", std::string("0,1,0")}, {"view", std::string("0,-1,0")}, {"size", 0.5},
                                 {"name", std::string("Ear Copy")}, {"save", false}, {"resolution", 64.0}}));
    CHECK(a.vdms.size() == before + 1 && a.brushVdm && a.brushVdm->name == "Ear Copy");
}

TEST(capture_vdm_on_a_curved_surface_keeps_only_the_detail) {
    // A horn on a sphere: the sphere's dome stays in the base (the quadric), so the map is the horn alone.
    Document d = makeDoc(makeIcosphere(7, 1.0f));
    d.brushVdm = builtinVdm("horn");
    CHECK(run(d, "vdm_stamp", {{"point", std::string("0,0,2")}, {"view", std::string("0,0,-1")}, {"radius", 0.15}}));
    d.syncBvh();
    const CaptureFrame f = makeCaptureFrame(glm::vec3(0.0f, 0.0f, 1.0f), glm::vec3(0.0f, 0.0f, -1.0f), glm::vec3(0.0f, 1.0f, 0.0f), 0.4f);
    CaptureOptions opt;
    opt.resolution = 128;
    VectorDisplacement v;
    std::string err;
    CHECK(captureVdmFromView(d.mesh, d.bvh, f, opt, v, err));
    float centre = 0.0f, band = 0.0f;
    for (int y = 0; y < v.height; ++y)
        for (int x = 0; x < v.width; ++x) {
            const float u = (float(x) + 0.5f) / float(v.width) * 2.0f - 1.0f, w = 1.0f - (float(y) + 0.5f) / float(v.height) * 2.0f;
            const float m = glm::length(v.vectors[size_t(y) * size_t(v.width) + size_t(x)]);
            const float d2 = std::max(std::abs(u), std::abs(w));
            if (d2 < 0.3f) centre = std::max(centre, m);
            else if (d2 > 0.5f && d2 < 0.8f) band = std::max(band, m);
        }
    std::printf("  horn on a sphere: centre %.3f, outer band %.4f (radii)\n", centre, band);
    CHECK(centre > 0.2f);
    CHECK(band < 0.15f * centre); // (what is left: the sphere is not quite a quadric over so wide a square)
}

TEST(kelvinlet_lattice_proxy_matches_the_exact_field) {
    // The far field interpolated from the lattice against the exact kernel everywhere: the error metric is the largest
    // difference over all vertices as a fraction of the largest displacement (and of the brush radius).
    for (BrushType type : {BrushType::KelvinGrab, BrushType::KelvinTwist, BrushType::KelvinScale}) {
        std::vector<glm::vec3> result[2], start;
        for (int pass = 0; pass < 2; ++pass) {
            Document d = makeDoc(makeIcosphere(7, 1.0f));
            start = d.mesh.positions;
            d.sculptor.kelvinlet.proxyMinVertices = pass == 0 ? size_t(1) << 40 : 0;
            d.syncBvh();
            CHECK(d.sculptor.beginStroke(d.mesh, "proxy"));
            KelvinletStep step;
            step.center = glm::normalize(glm::vec3(0.5f, 0.0f, 0.86f)); // (off the mirror plane: a twist there cancels)
            step.radius = 0.4f;
            step.delta = step.travel = glm::vec3(0.12f, 0.05f, 0.0f);
            step.substeps = 3;
            step.axis = glm::vec3(0.0f, 0.0f, 1.0f);
            step.angle = 0.4f;
            step.logScale = -0.3f;
            d.sculptor.kelvinletStep(d.mesh, d.bvh, type, step, Symmetry{true, false, false});
            d.undo.push(d.sculptor.endStroke());
            result[pass] = d.mesh.positions;
        }
        float worst = 0.0f, biggest = 0.0f;
        for (size_t v = 0; v < start.size(); ++v) {
            worst = std::max(worst, glm::distance(result[0][v], result[1][v]));
            biggest = std::max(biggest, glm::distance(result[0][v], start[v]));
        }
        std::printf("  %s lattice proxy: worst error %.2e = %.3f%% of the largest move, %.3f%% of the radius\n",
                    brushName(type), worst, 100.0f * worst / biggest, 100.0f * worst / 0.4f);
        // The step's own size: how far it moves the centre (the 0.5% floor below which a vertex's move is skipped is
        // part of both runs' difference, so the bound is against it).
        const float stepSize = type == BrushType::KelvinGrab ? glm::length(glm::vec3(0.12f, 0.05f, 0.0f))
                               : type == BrushType::KelvinTwist ? 0.4f * 0.4f
                                                                : 0.3f * 0.4f;
        std::printf("    = %.3f%% of the step\n", 100.0f * worst / stepSize);
        CHECK(biggest > 0.01f);
        CHECK(worst < 0.01f * stepSize); // under 1% of the step
    }
}

TEST(kelvinlet_tightens_its_cutoff_over_the_vertex_budget) {
    auto touched = [](size_t budget) {
        Document d = makeDoc(makeIcosphere(7, 1.0f));
        d.sculptor.kelvinlet.vertexBudget = budget;
        d.syncBvh();
        CHECK(d.sculptor.beginStroke(d.mesh, "budget"));
        KelvinletStep step;
        step.center = glm::vec3(0.0f, 0.0f, 1.0f);
        step.radius = 0.5f;
        step.delta = glm::vec3(0.01f, 0.0f, 0.0f);
        uint64_t last = 0;
        for (int i = 0; i < 3; ++i) { // (the first move measures the density, the next ones predict from it)
            const uint64_t before = d.sculptor.timings.vertices;
            d.sculptor.kelvinletStep(d.mesh, d.bvh, BrushType::KelvinGrab, step, Symmetry{false, false, false});
            last = d.sculptor.timings.vertices - before;
        }
        const bool over = d.sculptor.kelvinletOverBudget();
        d.undo.push(d.sculptor.endStroke());
        return std::make_pair(last, over);
    };
    const auto [free, freeOver] = touched(size_t(1) << 40);
    const auto [tight, tightOver] = touched(10000);
    std::printf("  vertices a move: %llu without a budget, %llu with a 10k budget\n", (unsigned long long)free,
                (unsigned long long)tight);
    CHECK(!freeOver && tightOver);
    CHECK(tight < free);
}

TEST(kelvinlet_deferred_far_field_matches_the_immediate_one) {
    // A drag of ten moves with the far field deferred to the lattice (every move) against all of it at once: after
    // the stroke's end the two surfaces agree within a small fraction of the drag. Undo puts everything back.
    for (BrushType type : {BrushType::KelvinGrab, BrushType::KelvinTwist}) {
        std::vector<glm::vec3> result[2], start;
        size_t deferredTouched = 0, immediateTouched = 0;
        for (int pass = 0; pass < 2; ++pass) {
            Document d = makeDoc(makeIcosphere(7, 1.0f));
            start = d.mesh.positions;
            d.sculptor.kelvinlet.deferMinVertices = pass == 0 ? size_t(1) << 40 : 2000;
            d.syncBvh();
            CHECK(d.sculptor.beginStroke(d.mesh, "far"));
            KelvinletStep step;
            step.center = glm::normalize(glm::vec3(0.4f, 0.1f, 0.9f));
            step.radius = 0.35f;
            step.delta = glm::vec3(0.03f, 0.01f, 0.0f);
            step.axis = glm::vec3(0.0f, 0.0f, 1.0f);
            step.angle = 0.08f;
            for (int i = 0; i < 10; ++i) {
                const uint64_t before = d.sculptor.timings.vertices;
                d.sculptor.kelvinletStep(d.mesh, d.bvh, type, step, Symmetry{true, false, false});
                (pass == 0 ? immediateTouched : deferredTouched) += d.sculptor.timings.vertices - before;
                if (type == BrushType::KelvinGrab) step.center += step.delta;
            }
            CHECK(pass == 0 || d.sculptor.kelvinletFarPending());
            d.sculptor.flushDetailClone(d.mesh, d.bvh, Symmetry{true, false, false}); // the stroke's end
            CHECK(!d.sculptor.kelvinletFarPending());
            d.undo.push(d.sculptor.endStroke());
            result[pass] = d.mesh.positions;
            if (pass == 1) {
                d.undo.undo(d.mesh, d.bvh);
                float back = 0.0f;
                for (size_t v = 0; v < start.size(); ++v) back = std::max(back, glm::distance(d.mesh.positions[v], start[v]));
                CHECK(back < 1e-6f);
            }
        }
        float worst = 0.0f, biggest = 0.0f;
        size_t at = 0;
        for (size_t v = 0; v < start.size(); ++v) {
            const float e = glm::distance(result[0][v], result[1][v]);
            if (e > worst) worst = e, at = v;
            biggest = std::max(biggest, glm::distance(result[0][v], start[v]));
        }
        std::printf("  (worst at %.3f from the first centre, moved %.4f / %.4f)\n",
                    glm::distance(start[at], glm::normalize(glm::vec3(0.4f, 0.1f, 0.9f))),
                    glm::distance(result[0][at], start[at]), glm::distance(result[1][at], start[at]));
        std::printf("  %s deferred far field: worst %.2e = %.2f%% of the largest move (%.3f%% of the radius); "
                    "vertex moves %zu deferred vs %zu at once\n",
                    brushName(type), worst, 100.0f * worst / biggest, 100.0f * worst / 0.35f, deferredTouched, immediateTouched);
        // (Part of it is the reference's own floor: it skips vertices that move under 0.5% of a step.) Smooth, and
        // under 2.5% of the radius: about a pixel for a 50 px brush.
        CHECK(worst < 0.025f * 0.35f);
        CHECK(deferredTouched < immediateTouched);
    }
}

TEST(kelvinlet_is_deterministic_with_threads) {
    std::vector<glm::vec3> result[2];
    for (int pass = 0; pass < 2; ++pass) {
        ThreadPool::shared().setSerial(pass == 0);
        Document d = makeDoc(makeIcosphere(6, 1.0f));
        std::string err;
        for (BrushType t : {BrushType::KelvinGrab, BrushType::KelvinTwist, BrushType::KelvinScale, BrushType::KelvinSnake}) {
            PathStroke st = pathAlongX(-0.2f, 0.3f, 0.5f, 0.1f);
            st.symmetry = Symmetry{true, false, false};
            CHECK(strokePath(d, nullptr, t, st, err) > 0);
        }
        result[pass] = d.mesh.positions;
    }
    ThreadPool::shared().setSerial(false);
    CHECK(result[0] == result[1]);
}

TEST(kelvinlet_grab_dense_mesh_timing) {
    // ~2.6M triangles: one drag step of a large elastic grab. Limits only with SF_BENCH_LIMITS=1.
    Document d = makeDoc(makeIcosphere(8, 1.0f));
    d.syncBvh();
    CHECK(d.sculptor.beginStroke(d.mesh, "KelvinGrab"));
    KelvinletStep step;
    step.center = glm::vec3(0.0f, 0.0f, 1.0f);
    step.radius = 0.3f;
    step.delta = glm::vec3(0.01f, 0.005f, 0.0f);
    step.viewDir = glm::vec3(0.0f, 0.0f, -1.0f);
    double worst = 0.0, total = 0.0;
    for (int i = 0; i < 10; ++i) {
        const auto t0 = std::chrono::steady_clock::now();
        d.sculptor.kelvinletStep(d.mesh, d.bvh, BrushType::KelvinGrab, step, Symmetry{false, false, false});
        const double ms = std::chrono::duration<double, std::milli>(std::chrono::steady_clock::now() - t0).count();
        worst = std::max(worst, ms);
        total += ms;
        step.center += step.delta;
    }
    const SculptTimings tm = d.sculptor.timings;
    std::printf("  (kernel %.1f, normals %.1f, BVH %.1f ms in all)\n", tm.kernelMs, tm.normalsMs, tm.bvhMs);
    d.undo.push(d.sculptor.endStroke());
    std::printf("  KelvinGrab r=0.3 on %u triangles: %.1f ms per step (worst %.1f), %llu vertices a step\n",
                d.mesh.triangleCount(), total / 10.0, worst,
                (unsigned long long)(d.sculptor.timings.vertices / std::max<uint64_t>(1, d.sculptor.timings.dabs)));
    if (std::getenv("SF_BENCH_LIMITS")) CHECK(total / 10.0 < 60.0);
}