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.

45.9 KB
Raw Blame
// SculptForge - open source digital sculpting
// SPDX-License-Identifier: GPL-3.0-or-later
#include "core/Vdm.h"
#include "core/Masking.h"

#include "core/BrushLibrary.h"
#include "core/Pack.h"
#include "core/Commands.h"
#include "core/Document.h"
#include "core/PathStroke.h"
#include "core/Primitives.h"
#include "core/Sculpt.h"
#include "core/ThreadPool.h"

#include "tinyexr.h"

#include <algorithm>
#include <cctype>
#include <cmath>
#include <cstdlib>
#include <cstring>
#include <filesystem>
#include <fstream>
#include <iterator>
#include <sstream>

namespace sf {

namespace fs = std::filesystem;

namespace {

constexpr int kMaxVdmSide = 2048;
constexpr char kSfvdmMagic[8] = {'S', 'F', 'V', 'D', 'M', '1', '\n', '\0'};

fs::path utf8Path(const std::string& s) { return fs::path(std::u8string(s.begin(), s.end())); }
std::string pathString(const fs::path& p) {
    const std::u8string s = p.u8string();
    return std::string(s.begin(), s.end());
}
std::string lower(std::string s) {
    std::transform(s.begin(), s.end(), s.begin(), [](unsigned char c) { return char(std::tolower(c)); });
    return s;
}
std::string extensionOf(const std::string& path) { return lower(pathString(utf8Path(path).extension())); }
std::string stemOf(const std::string& path) { return pathString(utf8Path(path).stem()); }

bool readBytes(const std::string& path, std::vector<unsigned char>& out, size_t limit, std::string& error) {
    std::ifstream f(utf8Path(path), std::ios::binary);
    if (!f) {
        error = "Can't open " + path;
        return false;
    }
    f.seekg(0, std::ios::end);
    const std::streamoff size = f.tellg();
    if (size < 0 || size_t(size) > limit) {
        error = path + " is too large";
        return false;
    }
    f.seekg(0);
    out.resize(size_t(size));
    if (size > 0 && !f.read(reinterpret_cast<char*>(out.data()), size)) {
        error = "Can't read " + path;
        return false;
    }
    return true;
}

bool writeBytes(const std::string& path, const void* data, size_t size, std::string& error) {
    std::error_code ec;
    const fs::path p = utf8Path(path);
    if (p.has_parent_path()) fs::create_directories(p.parent_path(), ec);
    std::ofstream f(p, std::ios::binary | std::ios::trunc);
    if (!f || !f.write(static_cast<const char*>(data), std::streamsize(size))) {
        error = "Can't write " + path;
        return false;
    }
    return true;
}

float smooth01(float t) {
    t = std::clamp(t, 0.0f, 1.0f);
    return t * t * (3.0f - 2.0f * t);
}

void applyImport(VectorDisplacement& vdm, const VdmImportOptions& opt) {
    for (glm::vec3& v : vdm.vectors) {
        if (opt.swapYZ) std::swap(v.y, v.z);
        if (opt.flipX) v.x = -v.x;
        if (opt.flipY) v.y = -v.y;
        if (opt.flipZ) v.z = -v.z;
        v *= opt.scale;
    }
}

// --- Procedural maps: f(x, y) is where the point (x, y, 0) of the flat square goes (x, y in -1..1). ---

template <class F>
VectorDisplacement generate(std::string name, int size, F&& f) {
    VectorDisplacement m;
    m.name = std::move(name);
    m.builtin = true;
    m.width = m.height = std::max(size, 8);
    m.vectors.resize(size_t(m.width) * size_t(m.height));
    poolFor(size_t(m.height), [&](size_t b, size_t e) {
        for (size_t row = b; row < e; ++row)
            for (int col = 0; col < m.width; ++col) {
                const float x = (float(col) + 0.5f) / float(m.width) * 2.0f - 1.0f;
                const float y = 1.0f - (float(row) + 0.5f) / float(m.height) * 2.0f;
                m.vectors[row * size_t(m.width) + size_t(col)] = f(x, y) - glm::vec3(x, y, 0.0f);
            }
    }, 16);
    return m;
}

// A tube grown out of the disc of radius `base`: the disc's rim stays put, its centre becomes the tip. The
// centre line bends toward +Y (`bend` radians over `length`; < 0 length digs in instead of rising); the cross
// section flattens to `flat` (along the bend) and tapers with `power`.
struct Tube {
    float base = 0.62f, length = 1.0f, bend = 1.1f, flat = 1.0f, power = 1.3f, rise = 1.6f;
};

glm::vec3 tubePoint(const Tube& h, float x, float y) {
    const float rho = std::sqrt(x * x + y * y);
    if (rho >= h.base) return {x, y, 0.0f};
    const float theta = std::atan2(y, x);
    const float s = 1.0f - rho / h.base;          // 0 at the rim, 1 at the tip
    const float len = std::abs(h.length);
    const float t = len * std::pow(s, h.rise);    // arc length: slow at first, a soft fillet into the surface
    const float depth = h.length < 0.0f ? -1.0f : 1.0f;
    const float kappa = h.bend / len;
    const float phi = kappa * t;
    glm::vec3 c(0.0f, 0.0f, t * depth);
    if (std::abs(kappa) > 1e-5f) c = glm::vec3(0.0f, (1.0f - std::cos(phi)) / kappa, depth * std::sin(phi) / kappa);
    const glm::vec3 e1(1.0f, 0.0f, 0.0f), e2(0.0f, std::cos(phi), -depth * std::sin(phi));
    const float radius = h.base * std::pow(1.0f - s, h.power);
    const float flat = 1.0f + (h.flat - 1.0f) * smooth01(s / 0.3f);
    return c + radius * (std::cos(theta) * e1 + flat * std::sin(theta) * e2);
}

} // namespace

// ---------------------------------------------------------------------------
// VectorDisplacement
// ---------------------------------------------------------------------------

glm::vec3 VectorDisplacement::sample(float u, float v) const {
    if (empty() || u < -1.0f || u > 1.0f || v < -1.0f || v > 1.0f) return glm::vec3(0.0f);
    // Pixel centres span the square, as BrushAlpha::sample.
    const float px = std::clamp((u * 0.5f + 0.5f) * float(width) - 0.5f, 0.0f, float(width - 1));
    const float py = std::clamp((0.5f - v * 0.5f) * float(height) - 0.5f, 0.0f, float(height - 1));
    const int x0 = int(px), y0 = int(py);
    const int x1 = std::min(x0 + 1, width - 1), y1 = std::min(y0 + 1, height - 1);
    const float tx = px - float(x0), ty = py - float(y0);
    auto at = [&](int x, int y) { return vectors[size_t(y) * size_t(width) + size_t(x)]; };
    const glm::vec3 a = glm::mix(at(x0, y0), at(x1, y0), tx);
    const glm::vec3 b = glm::mix(at(x0, y1), at(x1, y1), tx);
    return glm::mix(a, b, ty);
}

float VectorDisplacement::extent() const {
    float m = 0.0f;
    for (const glm::vec3& v : vectors) m = std::max(m, glm::length(v));
    return m;
}

uint64_t VectorDisplacement::hash() const {
    uint64_t h = 0xcbf29ce484222325ull;
    auto mix = [&h](const void* data, size_t n) {
        const auto* p = static_cast<const unsigned char*>(data);
        for (size_t i = 0; i < n; ++i) h = (h ^ p[i]) * 0x100000001b3ull;
    };
    mix(&width, sizeof width);
    mix(&height, sizeof height);
    mix(vectors.data(), vectors.size() * sizeof(glm::vec3));
    return h;
}

// ---------------------------------------------------------------------------
// Files
// ---------------------------------------------------------------------------

bool decodeVdmExr(const unsigned char* bytes, size_t size, VectorDisplacement& out, std::string& error,
                  const VdmImportOptions& opt) {
    if (!bytes || size == 0 || IsEXRFromMemory(bytes, size) != TINYEXR_SUCCESS) {
        error = "Not an OpenEXR file";
        return false;
    }
    float* rgba = nullptr;
    int w = 0, h = 0;
    const char* err = nullptr;
    // tinyexr reads the R, G, B (and A) channels, or a single channel into all four.
    if (LoadEXRFromMemory(&rgba, &w, &h, bytes, size, &err) != TINYEXR_SUCCESS) {
        error = std::string("Can't read the EXR: ") + (err ? err : "unknown error");
        if (err) FreeEXRErrorMessage(err);
        return false;
    }
    if (w <= 0 || h <= 0 || w > kMaxVdmSide || h > kMaxVdmSide) {
        std::free(rgba);
        error = "The EXR must be 1 to " + std::to_string(kMaxVdmSide) + " pixels a side";
        return false;
    }
    // Grayscale (one channel, so R = G = B = A): a height map along the normal.
    EXRVersion version;
    EXRHeader header;
    InitEXRHeader(&header);
    bool gray = false;
    if (ParseEXRVersionFromMemory(&version, bytes, size) == TINYEXR_SUCCESS &&
        ParseEXRHeaderFromMemory(&header, &version, bytes, size, nullptr) == TINYEXR_SUCCESS) {
        gray = header.num_channels == 1;
        FreeEXRHeader(&header);
    }
    out.width = w;
    out.height = h;
    out.vectors.resize(size_t(w) * size_t(h));
    for (size_t i = 0; i < out.vectors.size(); ++i) {
        const float* p = rgba + i * 4;
        glm::vec3 v = gray ? glm::vec3(0.0f, 0.0f, p[0]) : glm::vec3(p[0], p[1], p[2]);
        for (int k = 0; k < 3; ++k)
            if (!std::isfinite(v[k])) v[k] = 0.0f;
        out.vectors[i] = v;
    }
    std::free(rgba);
    applyImport(out, opt);
    return true;
}

bool readVdmExr(const std::string& path, VectorDisplacement& out, std::string& error, const VdmImportOptions& opt) {
    std::vector<unsigned char> bytes;
    if (!readBytes(path, bytes, size_t(1) << 30, error)) return false;
    if (!decodeVdmExr(bytes.data(), bytes.size(), out, error, opt)) {
        error = path + ": " + error;
        return false;
    }
    out.name = stemOf(path);
    out.path = path;
    out.builtin = false;
    return true;
}

bool encodeVdmExr(const VectorDisplacement& vdm, std::vector<unsigned char>& out, std::string& error) {
    if (vdm.empty()) {
        error = "The VDM is empty";
        return false;
    }
    std::vector<float> rgb(vdm.vectors.size() * 3);
    for (size_t i = 0; i < vdm.vectors.size(); ++i) {
        rgb[i * 3] = vdm.vectors[i].x;
        rgb[i * 3 + 1] = vdm.vectors[i].y;
        rgb[i * 3 + 2] = vdm.vectors[i].z;
    }
    unsigned char* buffer = nullptr;
    const char* err = nullptr;
    const int n = SaveEXRToMemory(rgb.data(), vdm.width, vdm.height, 3, 0, &buffer, &err);
    if (n <= 0 || !buffer) {
        error = std::string("Can't encode the EXR: ") + (err ? err : "unknown error");
        if (err) FreeEXRErrorMessage(err);
        std::free(buffer);
        return false;
    }
    out.assign(buffer, buffer + n);
    std::free(buffer);
    return true;
}

bool writeVdmExr(const std::string& path, const VectorDisplacement& vdm, std::string& error) {
    std::vector<unsigned char> bytes;
    return encodeVdmExr(vdm, bytes, error) && writeBytes(path, bytes.data(), bytes.size(), error);
}

bool readVdmFile(const std::string& path, VectorDisplacement& out, std::string& error) {
    std::vector<unsigned char> b;
    if (!readBytes(path, b, size_t(kMaxVdmSide) * kMaxVdmSide * 12 + 4096, error)) return false;
    auto u32 = [&](size_t at) {
        return uint32_t(b[at]) | uint32_t(b[at + 1]) << 8 | uint32_t(b[at + 2]) << 16 | uint32_t(b[at + 3]) << 24;
    };
    if (b.size() < 20 || std::memcmp(b.data(), kSfvdmMagic, 8) != 0) {
        error = path + " is not a SculptForge VDM (.sfvdm)";
        return false;
    }
    const uint32_t w = u32(8), h = u32(12), nameLen = u32(16);
    if (w == 0 || h == 0 || w > uint32_t(kMaxVdmSide) || h > uint32_t(kMaxVdmSide) || nameLen > 1024 ||
        b.size() != 20 + size_t(nameLen) + size_t(w) * h * 12) {
        error = path + " is damaged (bad size)";
        return false;
    }
    out.name.assign(reinterpret_cast<const char*>(b.data() + 20), nameLen);
    if (out.name.empty()) out.name = stemOf(path);
    out.width = int(w);
    out.height = int(h);
    out.vectors.resize(size_t(w) * h);
    const unsigned char* p = b.data() + 20 + nameLen;
    for (size_t i = 0; i < out.vectors.size(); ++i)
        for (int k = 0; k < 3; ++k) {
            const uint32_t bits = uint32_t(p[0]) | uint32_t(p[1]) << 8 | uint32_t(p[2]) << 16 | uint32_t(p[3]) << 24;
            p += 4;
            float f;
            std::memcpy(&f, &bits, 4);
            out.vectors[i][k] = std::isfinite(f) ? f : 0.0f;
        }
    out.path = path;
    out.builtin = false;
    return true;
}

bool writeVdmFile(const std::string& path, const VectorDisplacement& vdm, std::string& error) {
    if (vdm.empty()) {
        error = "The VDM is empty";
        return false;
    }
    std::vector<unsigned char> b(kSfvdmMagic, kSfvdmMagic + 8);
    auto put = [&b](uint32_t v) {
        for (int k = 0; k < 4; ++k) b.push_back(uint8_t(v >> (8 * k)));
    };
    const std::string name = vdm.name.substr(0, 1024);
    put(uint32_t(vdm.width));
    put(uint32_t(vdm.height));
    put(uint32_t(name.size()));
    b.insert(b.end(), name.begin(), name.end());
    b.reserve(b.size() + vdm.vectors.size() * 12);
    for (const glm::vec3& v : vdm.vectors)
        for (int k = 0; k < 3; ++k) {
            uint32_t bits;
            std::memcpy(&bits, &v[k], 4);
            put(bits);
        }
    return writeBytes(path, b.data(), b.size(), error);
}

bool isVdmFile(const std::string& path) {
    const std::string ext = extensionOf(path);
    return ext == ".sfvdm" || ext == ".exr";
}

bool loadVdm(const std::string& path, VectorDisplacement& out, std::string& error, const VdmImportOptions& opt) {
    if (extensionOf(path) == ".sfvdm") {
        if (!readVdmFile(path, out, error)) return false;
        applyImport(out, opt);
        return true;
    }
    return readVdmExr(path, out, error, opt);
}

// ---------------------------------------------------------------------------
// Built-ins
// ---------------------------------------------------------------------------

VectorDisplacement makeHornVdm(int size) {
    Tube h; // a horn that curls over toward the stamp's top
    h.base = 0.62f;
    h.length = 1.05f;
    h.bend = 1.15f;
    h.power = 1.25f;
    return generate("Horn", size, [&](float x, float y) { return tubePoint(h, x, y); });
}

VectorDisplacement makeEarCurlVdm(int size) {
    Tube h; // a flattened, blunt flap that curls right over: an ear rim, a fin, a leaf
    h.base = 0.58f;
    h.length = 1.2f;
    h.bend = 2.6f;
    h.flat = 0.42f;
    h.power = 0.75f;
    h.rise = 1.4f;
    return generate("Ear Curl", size, [&](float x, float y) {
        // The flap leans back toward the stamp's bottom first, so the curl sits over the middle.
        glm::vec3 p = tubePoint(h, x, y + 0.12f);
        p.y -= 0.12f;
        return p;
    });
}

VectorDisplacement makeScalesVdm(int size) {
    // Overlapping scales in staggered rows; each lip is pushed toward the stamp's bottom over the next row.
    struct Scale {
        glm::vec2 c;
        float r;
    };
    std::vector<Scale> scales;
    const float r = 0.25f;
    for (int row = 0; row < 3; ++row) {
        const float y = 0.42f - 0.38f * float(row);
        const int n = row == 1 ? 4 : 3;
        for (int i = 0; i < n; ++i) {
            const float x = (float(i) - float(n - 1) * 0.5f) * 0.38f;
            scales.push_back({glm::vec2(x, y), r});
        }
    }
    return generate("Scales", size, [&](float x, float y) {
        glm::vec3 best(x, y, 0.0f);
        float bestZ = 0.0f;
        for (const Scale& s : scales) {
            const glm::vec2 q = (glm::vec2(x, y) - s.c) / s.r;
            const float d = glm::length(q * glm::vec2(1.0f, 0.85f));
            if (d >= 1.0f) continue;
            const float plateau = smooth01((1.0f - d) / 0.28f);
            const float front = 0.55f + 0.45f * std::clamp((1.0f - q.y) * 0.5f, 0.0f, 1.0f); // higher at the lip
            const float z = 0.13f * plateau * front * (1.0f - 0.3f * d * d);
            if (z <= bestZ) continue;
            bestZ = z;
            best = glm::vec3(x, y - 0.075f * plateau, z); // the lip slides past its edge: an overhang
        }
        return best;
    });
}

VectorDisplacement makeNostrilVdm(int size) {
    Tube h; // a socket that dives in and bends under its top rim
    h.base = 0.6f;
    h.length = -0.75f;
    h.bend = 1.0f;
    h.power = 0.9f;
    h.rise = 1.35f;
    return generate("Nostril", size, [&](float x, float y) {
        glm::vec3 p = tubePoint(h, x, y);
        const float rho = std::sqrt(x * x + y * y);
        if (rho >= h.base) return p;
        // A raised rim that leans in over the opening.
        const float s = 1.0f - rho / h.base;
        const float bump = std::sin(3.14159265f * std::clamp(s / 0.42f, 0.0f, 1.0f));
        const glm::vec2 radial = rho > 1e-6f ? glm::vec2(x, y) / rho : glm::vec2(0.0f);
        p += glm::vec3(-radial * (0.09f * bump), 0.12f * bump);
        return p;
    });
}

namespace {

// 1 inside the stamp, 0 from 0.95 radii out: the generated maps below leave the square's rim where it was.
float rimFade(float x, float y) { return 1.0f - smooth01((std::sqrt(x * x + y * y) - 0.55f) / 0.4f); }

// Distance from p to the segment a-b, and the closest point on it.
float toSegment(glm::vec2 p, glm::vec2 a, glm::vec2 b, glm::vec2& closest) {
    const glm::vec2 v = b - a;
    const float t = std::clamp(glm::dot(p - a, v) / std::max(glm::dot(v, v), 1e-12f), 0.0f, 1.0f);
    closest = a + v * t;
    return glm::length(p - closest);
}

// A smooth, repeatable wiggle (sums of sines) for crack and wrinkle lines.
float wiggle(float t, float seed) {
    return 0.6f * std::sin(t * 3.1f + seed) + 0.3f * std::sin(t * 7.3f + seed * 2.1f) + 0.1f * std::sin(t * 17.0f + seed);
}

} // namespace

VectorDisplacement makeRivetVdm(int size) {
    // A domed head on a short neck, its rim bulging out over the plate a little.
    return generate("Rivet", size, [](float x, float y) {
        const float rho = std::sqrt(x * x + y * y), r = 0.42f;
        if (rho >= r + 0.2f) return glm::vec3(x, y, 0.0f);
        const glm::vec2 radial = rho > 1e-6f ? glm::vec2(x, y) / rho : glm::vec2(0.0f);
        if (rho < r) {
            const float s = rho / r;
            const float z = 0.06f + 0.24f * std::sqrt(std::max(0.0f, 1.0f - s * s)); // head on a 0.06 neck
            const float out = 0.07f * smooth01((s - 0.55f) / 0.45f);                    // the rim overhangs
            return glm::vec3(glm::vec2(x, y) + radial * out, z);
        }
        // The neck: from under the rim down to the plate.
        const float t = (rho - r) / 0.2f;
        const float z = 0.06f * (1.0f - smooth01(t));
        const float in = -0.04f * (1.0f - t) * (1.0f - smooth01(t));
        return glm::vec3(glm::vec2(x, y) + radial * in, z);
    });
}

VectorDisplacement makeStitchesVdm(int size) {
    // Three raised thread bars across a seam (drag along the seam: the stamp's Y); the threads draw the two sides
    // of the seam together, so the skin bunches toward it.
    return generate("Stitches", size, [](float x, float y) {
        const float fade = rimFade(x, y);
        float z = -0.06f * (1.0f - smooth01(std::abs(x) / 0.08f)); // the seam line itself
        for (int k = -1; k <= 1; ++k) {
            const float cy = float(k) * 0.33f;
            glm::vec2 c;
            const float d = toSegment(glm::vec2(x, y), glm::vec2(-0.32f, cy - 0.08f), glm::vec2(0.32f, cy + 0.08f), c);
            z = std::max(z, 0.11f * std::sqrt(std::max(0.0f, 1.0f - smooth01(d / 0.07f))));
        }
        const float gather = -0.1f * std::tanh(x / 0.12f) * std::exp(-x * x / 0.12f);
        return glm::vec3(x + gather * fade, y, z * fade);
    });
}

VectorDisplacement makeSkinFoldVdm(int size) {
    // A heavy roll of skin hanging over a crease (the stamp's bottom, -Y), as over an eyelid or a belly.
    return generate("Skin Fold", size, [](float x, float y) {
        const float crease = -0.15f + 0.25f * x * x;
        const float d = y - crease; // above the crease > 0
        const float fade = rimFade(x, y);
        const float roll = d > 0.0f ? std::exp(-d * d / 0.08f) : std::exp(-d * d / 0.004f);
        const float z = 0.22f * roll - 0.06f * std::exp(-d * d / 0.003f); // a deep line where it folds under
        const float hang = d > 0.0f ? -0.16f * std::exp(-d * d / 0.03f) : 0.0f; // slides down over the crease
        return glm::vec3(x, y + hang * fade, z * fade);
    });
}

VectorDisplacement makeWrinkleVdm(int size) {
    // A fine crease: skin pinched in from both sides and pressed down along a slightly wavy line (along X).
    return generate("Wrinkle Line", size, [](float x, float y) {
        const float line = 0.06f * wiggle(x * 1.2f, 0.7f);
        const float d = y - line;
        const float along = smooth01((0.8f - std::abs(x)) / 0.35f); // tapered ends
        const float fade = rimFade(x, y) * along;
        const float pinch = -0.12f * std::tanh(d / 0.06f) * std::exp(-d * d / 0.05f);
        const float z = -0.18f * std::exp(-d * d / 0.002f) + 0.04f * std::exp(-d * d / 0.03f);
        return glm::vec3(x, y + pinch * fade, z * fade);
    });
}

VectorDisplacement makeCrackVdm(int size) {
    // A jagged crack (along Y) whose sides split apart and break downward into it.
    return generate("Crack", size, [](float x, float y) {
        const float line = 0.12f * wiggle(y * 1.6f, 2.3f);
        const float d = x - line;
        const float along = smooth01((0.85f - std::abs(y)) / 0.3f);
        const float fade = rimFade(x, y) * along;
        const float width = 0.03f + 0.03f * (0.5f + 0.5f * std::sin(y * 9.0f));
        const float split = 0.09f * std::tanh(d / width) * std::exp(-d * d / 0.04f); // the sides move apart
        const float z = -0.28f * std::exp(-d * d / (width * width)) + 0.02f * std::exp(-d * d / 0.02f);
        return glm::vec3(x + split * fade, y, z * fade);
    });
}

VectorDisplacement makeRockLedgeVdm(int size) {
    // A stepped shelf of rock strata whose upper layer juts out over the one below (toward -Y): an overhang.
    return generate("Rock Ledge", size, [](float x, float y) {
        const float fade = rimFade(x, y);
        const float edge = -0.05f + 0.05f * wiggle(x * 2.0f, 4.1f);
        const float t = smooth01((y - edge) / 0.18f); // 0 below the ledge, 1 on top
        const float lip = std::exp(-(y - edge - 0.1f) * (y - edge - 0.1f) / 0.01f);
        const float z = 0.2f * t + 0.03f * wiggle(x * 4.0f + y * 3.0f, 1.3f) * t;
        const float jut = -0.14f * lip; // the lip pushed out over the lower layer
        return glm::vec3(x, y + jut * fade, z * fade);
    });
}

const std::vector<std::shared_ptr<const VectorDisplacement>>& builtinVdms() {
    static const std::vector<std::shared_ptr<const VectorDisplacement>> all = [] {
        std::vector<std::shared_ptr<const VectorDisplacement>> v;
        v.push_back(std::make_shared<const VectorDisplacement>(makeHornVdm()));
        v.push_back(std::make_shared<const VectorDisplacement>(makeEarCurlVdm()));
        v.push_back(std::make_shared<const VectorDisplacement>(makeScalesVdm()));
        v.push_back(std::make_shared<const VectorDisplacement>(makeNostrilVdm()));
        // #43: six more, made here in code like the four above (no files).
        v.push_back(std::make_shared<const VectorDisplacement>(makeRivetVdm()));
        v.push_back(std::make_shared<const VectorDisplacement>(makeStitchesVdm()));
        v.push_back(std::make_shared<const VectorDisplacement>(makeSkinFoldVdm()));
        v.push_back(std::make_shared<const VectorDisplacement>(makeWrinkleVdm()));
        v.push_back(std::make_shared<const VectorDisplacement>(makeCrackVdm()));
        v.push_back(std::make_shared<const VectorDisplacement>(makeRockLedgeVdm()));
        return v;
    }();
    return all;
}

std::shared_ptr<const VectorDisplacement> builtinVdm(const std::string& name) {
    for (const auto& v : builtinVdms())
        if (lower(v->name) == lower(name)) return v;
    return nullptr;
}

// ---------------------------------------------------------------------------
// Create VDM from a plane
// ---------------------------------------------------------------------------

Mesh makeVdmPlane(int cells) {
    Mesh m = makePlane(std::clamp(cells, 2, 2000), 2.0f);
    // UVs from the flat start: u along +X, v up the top view (toward -Z).
    m.uvs.resize(m.triangles.size() * 3);
    for (size_t t = 0; t < m.triangles.size(); ++t)
        for (int k = 0; k < 3; ++k) {
            const glm::vec3 p = m.positions[m.triangles[t][k]];
            m.uvs[t * 3 + size_t(k)] = glm::vec2((p.x + 1.0f) * 0.5f, (1.0f - p.z) * 0.5f);
        }
    // The border stays where it is, so the stamp blends into any surface.
    auto& mask = m.ensureMask(0.0f);
    for (uint32_t v = 0; v < m.vertexCount(); ++v) {
        const glm::vec3 p = m.positions[v];
        if (std::max(std::abs(p.x), std::abs(p.z)) > 1.0f - 1e-4f) mask[v] = 1.0f;
    }
    return m;
}

bool captureVdm(const Mesh& mesh, int size, VectorDisplacement& out, std::string& error) {
    if (!mesh.hasUvs() || mesh.uvs.size() != mesh.triangles.size() * 3) {
        error = "The mesh has no UVs to say where each point started: start from Brush > Vector Displacement > New VDM plane";
        return false;
    }
    size = std::clamp(size, 16, kMaxVdmSide);
    out = VectorDisplacement{};
    out.width = out.height = size;
    out.vectors.assign(size_t(size) * size_t(size), glm::vec3(0.0f));
    const float fs = float(size);
    // Rows in parallel: each band rasterizes the triangles that reach it, so no texel is written twice at once.
    const size_t bands = size_t(std::min(size, 64));
    std::vector<std::vector<uint32_t>> inBand(bands);
    for (uint32_t t = 0; t < mesh.triangleCount(); ++t) {
        float lo = 1e9f, hi = -1e9f;
        for (int k = 0; k < 3; ++k) {
            const float py = (1.0f - mesh.uvs[size_t(t) * 3 + size_t(k)].y) * fs - 0.5f;
            lo = std::min(lo, py);
            hi = std::max(hi, py);
        }
        const int r0 = std::max(0, int(std::ceil(lo))), r1 = std::min(size - 1, int(std::floor(hi)));
        if (r0 > r1) continue;
        const size_t b0 = size_t(r0) * bands / size_t(size), b1 = size_t(r1) * bands / size_t(size);
        for (size_t b = b0; b <= b1; ++b) inBand[b].push_back(t);
    }
    poolFor(bands, [&](size_t bb, size_t be) {
        for (size_t band = bb; band < be; ++band) {
            const int rowLo = int(band * size_t(size) / bands), rowHi = int((band + 1) * size_t(size) / bands) - 1;
            for (uint32_t t : inBand[band]) {
                glm::vec2 q[3];
                glm::vec3 d[3];
                for (int k = 0; k < 3; ++k) {
                    const glm::vec2 uv = mesh.uvs[size_t(t) * 3 + size_t(k)];
                    q[k] = glm::vec2(uv.x * fs - 0.5f, (1.0f - uv.y) * fs - 0.5f);
                    const glm::vec3 p = mesh.positions[mesh.triangles[t][k]];
                    // Tangent axes of the plane (see makeVdmPlane) minus where the point started.
                    d[k] = glm::vec3(p.x, -p.z, p.y) - glm::vec3(uv.x * 2.0f - 1.0f, uv.y * 2.0f - 1.0f, 0.0f);
                }
                const float area = (q[1].x - q[0].x) * (q[2].y - q[0].y) - (q[2].x - q[0].x) * (q[1].y - q[0].y);
                if (std::abs(area) < 1e-12f) continue;
                const int x0 = std::max(0, int(std::ceil(std::min({q[0].x, q[1].x, q[2].x}) - 1e-4f)));
                const int x1 = std::min(size - 1, int(std::floor(std::max({q[0].x, q[1].x, q[2].x}) + 1e-4f)));
                const int y0 = std::max(rowLo, int(std::ceil(std::min({q[0].y, q[1].y, q[2].y}) - 1e-4f)));
                const int y1 = std::min(rowHi, int(std::floor(std::max({q[0].y, q[1].y, q[2].y}) + 1e-4f)));
                for (int y = y0; y <= y1; ++y)
                    for (int x = x0; x <= x1; ++x) {
                        const glm::vec2 c{float(x), float(y)};
                        auto edge = [&](int a, int b) {
                            return ((q[b].x - q[a].x) * (c.y - q[a].y) - (c.x - q[a].x) * (q[b].y - q[a].y)) / area;
                        };
                        const float w0 = edge(1, 2), w1 = edge(2, 0), w2 = edge(0, 1);
                        if (w0 < -1e-4f || w1 < -1e-4f || w2 < -1e-4f) continue;
                        out.vectors[size_t(y) * size_t(size) + size_t(x)] = d[0] * w0 + d[1] * w1 + d[2] * w2;
                    }
            }
        }
    }, 1, 1);
    return true;
}

// ---------------------------------------------------------------------------
// The brush (Sculptor::dabVdmSingle)
// ---------------------------------------------------------------------------

void Sculptor::dabVdmSingle(Mesh& mesh, BVH& bvh, const DabParams& p, float handedness) {
    auto clock = std::chrono::steady_clock::now();
    const VectorDisplacement* vdm = p.vdm && !p.vdm->empty() ? p.vdm : builtinVdms().front().get();
    // The stamp is the brush's square, so the corners reach out to radius x sqrt(2).
    brushRegion(mesh, bvh, p.center, p.viewDir, p.radius * 1.4143f, p.connectedOnly, p.viewFalloff, verts_, connected_);
    if (verts_.empty()) return;
    const auto& pos = mesh.positions;
    const auto& nrm = mesh.normals;
    if (p.frontFacesOnly) {
        std::erase_if(verts_, [&](uint32_t v) { return glm::dot(nrm[v], p.viewDir) > 0.0f; });
        if (verts_.empty()) return;
    }
    // Area normal under the brush (inside its radius, smoothstep weighted): per-block partials summed in
    // block order, so it doesn't depend on the thread count.
    constexpr size_t kBlock = 4096;
    std::vector<glm::vec3> parts((verts_.size() + kBlock - 1) / kBlock, glm::vec3(0.0f));
    poolFor(verts_.size(), [&](size_t b, size_t e) {
        glm::vec3 acc(0.0f);
        for (size_t i = b; i < e; ++i)
            acc += nrm[verts_[i]] * brushFalloff(glm::distance(pos[verts_[i]], p.center), p.radius);
        parts[b / kBlock] = acc;
    }, kBlock);
    glm::vec3 n(0.0f);
    for (const glm::vec3& part : parts) n += part;
    n = glm::length(n) > 1e-12f ? glm::normalize(n) : -p.viewDir;

    // Tangent frame: Z = the surface, Y = the stamp's top (screen up or the drag), X = right. A mirrored pass
    // flips X too, so the mirrored stamp is the exact mirror image (a mirror swaps the handedness of a cross).
    glm::vec3 up = p.alphaUp - n * glm::dot(p.alphaUp, n);
    if (glm::length(up) < 1e-6f) {
        const glm::vec3 helper = std::abs(n.x) < 0.9f ? glm::vec3(1, 0, 0) : glm::vec3(0, 1, 0);
        up = helper - n * glm::dot(helper, n);
    }
    up = glm::normalize(up);
    const glm::vec3 right = glm::cross(up, n) * handedness;

    const float r = p.radius;
    // Intensity 50 (the default) presses the map at its own size; 100 doubles it. Alt digs the shape in
    // (Blender's convention: X and Y stay, Z flips).
    const float amount = 2.0f * std::clamp(p.strength, 0.0f, 1.0f) * std::clamp(p.pressure, 0.0f, 1.0f) * r;
    const float zSign = p.invert ? -1.0f : 1.0f;
    scratch_.resize(verts_.size());
    poolFor(verts_.size(), [&](size_t b, size_t e) {
        for (size_t i = b; i < e; ++i) {
            const glm::vec3 o = pos[verts_[i]] - p.center;
            const float u = glm::dot(o, right) / r, v = glm::dot(o, up) / r;
            const float edge = 1.0f - std::max(std::abs(u), std::abs(v));
            if (edge <= 0.0f) {
                scratch_[i] = glm::vec3(0.0f);
                continue;
            }
            const glm::vec3 d = vdm->sample(u, v) * (amount * smooth01(edge / 0.03f)); // maps whose border isn't 0 fade out
            scratch_[i] = right * d.x + up * d.y + n * (d.z * zSign);
        }
    }, kBlock);
    displaceAll(mesh, verts_, scratch_);
    finishDab(mesh, bvh, clock);
}

// ---------------------------------------------------------------------------
// Library
// ---------------------------------------------------------------------------

std::string vdmFileName(const std::string& name) {
    std::string f = brushFileName(name);
    return f.substr(0, f.size() - std::strlen(".sfbrush")) + ".sfvdm";
}

int findVdm(const Document& doc, const std::string& name) {
    for (size_t i = 0; i < doc.vdms.size(); ++i)
        if (lower(doc.vdms[i]->name) == lower(name)) return int(i);
    return -1;
}

std::shared_ptr<const VectorDisplacement> addVdm(Document& doc, VectorDisplacement vdm) {
    auto shared = std::make_shared<const VectorDisplacement>(std::move(vdm));
    const int i = findVdm(doc, shared->name);
    if (i >= 0) doc.vdms[size_t(i)] = shared;
    else doc.vdms.push_back(shared);
    doc.brushVdm = shared;
    return shared;
}

void loadVdmLibrary(Document& doc, const BrushLibraryPaths& paths, std::vector<std::string>& messages) {
    const std::string current = doc.brushVdm ? doc.brushVdm->name : std::string();
    doc.vdms = builtinVdms();
    auto scan = [&](const std::string& dir, bool user, const std::string& pack = {}) {
        std::vector<std::string> files;
        std::error_code ec;
        for (fs::directory_iterator it(utf8Path(dir), ec), end; !ec && it != end; it.increment(ec)) {
            std::error_code fileEc;
            if (extensionOf(pathString(it->path())) == ".sfvdm" && it->is_regular_file(fileEc))
                files.push_back(pathString(it->path()));
        }
        std::sort(files.begin(), files.end());
        for (const std::string& f : files) {
            VectorDisplacement v;
            std::string err;
            if (!readVdmFile(f, v, err)) {
                messages.push_back("Skipped " + f + ": " + err);
                continue;
            }
            if (!pack.empty()) {
                // A pack's VDM never replaces another: it gets the pack's name after its own.
                if (findVdm(doc, v.name) >= 0) v.name += " (" + pack + ")";
                if (findVdm(doc, v.name) >= 0) continue;
            }
            const int i = findVdm(doc, v.name);
            auto shared = std::make_shared<const VectorDisplacement>(std::move(v));
            if (i < 0) doc.vdms.push_back(shared);
            else if (user || doc.vdms[size_t(i)]->builtin) doc.vdms[size_t(i)] = shared; // user > studio > built-in
        }
    };
    for (const std::string& dir : paths.studioDirs) scan(dir, false);
    for (const auto& p : paths.packs)
        if (p.vdm && !packsSafeMode()) scan(p.dir, false, p.pack);
    if (!paths.userDir.empty()) scan(paths.userDir, true);
    const int i = findVdm(doc, current);
    doc.brushVdm = i >= 0 ? doc.vdms[size_t(i)] : doc.vdms.front();
}

// ---------------------------------------------------------------------------
// Commands
// ---------------------------------------------------------------------------

namespace {

VdmImportOptions importOptions(const Args& a) {
    VdmImportOptions o;
    o.swapYZ = argBool(a, "swap_yz", false);
    o.flipX = argBool(a, "flip_x", false);
    o.flipY = argBool(a, "flip_y", false);
    o.flipZ = argBool(a, "flip_z", false);
    o.scale = float(std::clamp(argNumber(a, "scale", 1.0), -100.0, 100.0));
    return o;
}

// Saves `vdm` into the user library (when there is one); returns the note for the status line.
std::string saveToLibrary(VectorDisplacement& vdm) {
    const std::string dir = brushLibraryPaths().userDir;
    if (dir.empty()) return " (not saved: no brush library)";
    const std::string file = pathString(utf8Path(dir) / utf8Path(vdmFileName(vdm.name)));
    std::string err;
    if (!writeVdmFile(file, vdm, err)) return " (not saved: " + err + ")";
    vdm.path = file;
    return "";
}

} // namespace

void registerVdmCommands(CommandRegistry& registry) {
    using T = ParamSpec::Type;
    const std::vector<ParamSpec> importParams = {
        {"swap_yz", T::Bool, "Swap the map's Y and Z (G and B) channels, for maps made with Y as the normal.", false},
        {"flip_x", T::Bool, "Negate X (R).", false},
        {"flip_y", T::Bool, "Negate Y (G).", false},
        {"flip_z", T::Bool, "Negate Z (B).", false},
        {"scale", T::Number, "Multiply every vector (default 1).", false},
    };
    std::vector<ParamSpec> setParams = {
        {"name", T::String, "A built-in (horn, ear curl, scales, nostril) or library VDM, by name.", false},
        {"path", T::String, "A vector displacement map: 32/16-bit OpenEXR (Blender's format) or .sfvdm. Overrides name.", false},
        {"save", T::Bool, "Keep a loaded file in the brush library (default true).", false},
    };
    setParams.insert(setParams.end(), importParams.begin(), importParams.end());
    registry.add({"vdm_set",
                  "Choose the vector displacement map the VDM brush stamps: a built-in, a library VDM, or an EXR file "
                  "(RGB = XYZ in the brush's tangent space: X right, Y up, Z out of the surface, in brush radii).",
                  setParams,
                  [](Document& doc, const Args& a) -> CommandResult {
                      const std::string path = argString(a, "path");
                      if (!path.empty()) {
                          VectorDisplacement v;
                          std::string err;
                          if (!loadVdm(path, v, err, importOptions(a))) return {false, err};
                          std::string note;
                          if (argBool(a, "save", true) && extensionOf(path) == ".exr") note = saveToLibrary(v);
                          const std::string msg = "VDM '" + v.name + "' (" + std::to_string(v.width) + "x" +
                                                  std::to_string(v.height) + ")" + note;
                          addVdm(doc, std::move(v));
                          return {true, msg};
                      }
                      const std::string name = argString(a, "name", "horn");
                      const int i = findVdm(doc, name);
                      if (i < 0) return {false, "No VDM called " + name + " (vdm_list shows them)"};
                      doc.brushVdm = doc.vdms[size_t(i)];
                      return {true, "VDM '" + doc.brushVdm->name + "'"};
                  }});
    registry.add({"vdm_list", "List the vector displacement maps (built-in and library); * marks the brush's.", {},
                  [](Document& doc, const Args&) -> CommandResult {
                      std::string s;
                      for (const auto& v : doc.vdms) {
                          if (!s.empty()) s += ", ";
                          s += (v == doc.brushVdm ? "*" : "") + v->name;
                      }
                      return {true, s};
                  }});
    registry.add({"vdm_export",
                  "Save the VDM brush's map as a 32-bit float OpenEXR (for Blender's VDM brushes) or .sfvdm.",
                  {{"path", T::String, "File to write (.exr or .sfvdm).", true},
                   {"name", T::String, "Which VDM (default: the brush's).", false}},
                  [](Document& doc, const Args& a) -> CommandResult {
                      const std::string path = argString(a, "path");
                      std::shared_ptr<const VectorDisplacement> v = doc.brushVdm;
                      if (const std::string name = argString(a, "name"); !name.empty()) {
                          const int i = findVdm(doc, name);
                          if (i < 0) return {false, "No VDM called " + name};
                          v = doc.vdms[size_t(i)];
                      }
                      if (!v) return {false, "No VDM"};
                      std::string err;
                      const bool ok = extensionOf(path) == ".sfvdm" ? writeVdmFile(path, *v, err) : writeVdmExr(path, *v, err);
                      if (!ok) return {false, err};
                      return {true, "Exported VDM '" + v->name + "' to " + path};
                  }});
    registry.add({"vdm_new_plane",
                  "Add a VDM plane to sculpt a new vector displacement brush on: a flat "
                  "2 x 2 grid seen from the top, its border masked; the other Parts are hidden. Then vdm_capture.",
                  {{"resolution", T::Number, "Quads per side (16-1024). Default 256; divide it for finer detail.", false}},
                  [](Document& doc, const Args& a) -> CommandResult {
                      const int res = std::clamp(int(argNumber(a, "resolution", 256)), 16, 1024);
                      for (auto& s : doc.parts) s.visible = false;
                      doc.addPart(makeVdmPlane(res), doc.uniquePartName("VDM Plane"));
                      doc.activePartInfo().visible = true;
                      doc.modified = true;
                      return {true, "VDM plane (" + std::to_string(res) + " x " + std::to_string(res) +
                                        "): sculpt it from the top, then Create VDM"};
                  }});
    registry.add({"vdm_capture",
                  "Create a VDM brush from the active VDM plane: how far each point moved from the flat grid becomes "
                  "a new vector displacement map in the brush library.",
                  {{"name", T::String, "Name of the new VDM (default 'My VDM').", false},
                   {"resolution", T::Number, "Map size in pixels (16-2048, default 256; Blender suggests 512 or less).", false},
                   {"exr", T::String, "Also write it as a 32-bit OpenEXR here, for Blender.", false},
                   {"save", T::Bool, "Keep it in the brush library (default true).", false}},
                  [](Document& doc, const Args& a) -> CommandResult {
                      VectorDisplacement v;
                      std::string err;
                      if (!captureVdm(doc.mesh, int(argNumber(a, "resolution", 256)), v, err)) return {false, err};
                      v.name = argString(a, "name", "My VDM");
                      if (v.name.empty()) v.name = "My VDM";
                      if (builtinVdm(v.name)) v.name += " (mine)";
                      std::string note;
                      if (argBool(a, "save", true)) note = saveToLibrary(v);
                      if (const std::string exr = argString(a, "exr"); !exr.empty()) {
                          if (!writeVdmExr(exr, v, err)) return {false, err};
                          note += ", EXR " + exr;
                      }
                      const std::string msg = "Created VDM '" + v.name + "' (" + std::to_string(v.width) + " px)" + note;
                      addVdm(doc, std::move(v));
                      return {true, msg};
                  }});
    registry.add({"vdm_stamp",
                  "Press the VDM brush once (like a Drag Stamp click): at the surface point a ray along `view` through "
                  "`point` hits, `radius` in world units, its top turned by `angle` from the view's up. One undo step.",
                  {{"point", T::String, "x,y,z the ray goes through.", true},
                   {"view", T::String, "x,y,z view direction into the scene (default 0,0,-1).", false},
                   {"radius", T::Number, "Brush radius in world units (default 4% of the model's size).", false},
                   {"angle", T::Number, "Rotation in degrees, counter-clockwise on screen (default 0).", false},
                   {"strength", T::Number, "Intensity 0-1 (default 0.5 = the map's own size; 1 doubles it).", false},
                   {"invert", T::Bool, "Dig the shape in (Alt).", false},
                   {"symmetry", T::String, "Mirror axes, e.g. \"x\" or \"xz\" (default none).", false}},
                  [](Document& doc, const Args& a) -> CommandResult {
                      glm::vec3 point, view(0.0f, 0.0f, -1.0f);
                      if (!parseVec3(argString(a, "point"), point)) return {false, "Bad point (expected x,y,z)"};
                      if (a.count("view") && !parseVec3(argString(a, "view"), view)) return {false, "Bad view (expected x,y,z)"};
                      if (glm::length(view) < 1e-6f) return {false, "The view direction must not be zero"};
                      view = glm::normalize(view);
                      if (doc.mesh.triangleCount() == 0) return {false, "The active Part is empty"};
                      doc.syncBvh();
                      const AABB box = doc.mesh.bounds();
                      const float diag = std::max(glm::length(box.extent()), 1e-4f);
                      RayHit hit;
                      const glm::vec3 origin = point - view * (glm::dot(point - box.center(), view) + diag);
                      if (!doc.bvh.raycast(doc.mesh, origin, view, hit)) return {false, "The ray misses the surface"};
                      const glm::vec3 helper = std::abs(view.y) > 0.9f ? glm::vec3(0.0f, 0.0f, -1.0f) : glm::vec3(0.0f, 1.0f, 0.0f);
                      const glm::vec3 right = glm::normalize(glm::cross(view, helper));
                      const glm::vec3 up = glm::cross(right, view);
                      const float angle = float(argNumber(a, "angle", 0.0)) * 3.14159265f / 180.0f;
                      DabParams p;
                      p.center = hit.position;
                      p.viewDir = view;
                      p.radius = float(argNumber(a, "radius", 0.0));
                      if (!(p.radius > 0.0f)) p.radius = diag * 0.04f;
                      p.strength = float(std::clamp(argNumber(a, "strength", 0.5), 0.0, 1.0));
                      p.invert = argBool(a, "invert", false);
                      p.alphaUp = up * std::cos(angle) - right * std::sin(angle);
                      p.vdm = doc.brushVdm.get();
                      Symmetry sym{false, false, false};
                      std::string symError;
                      if (!symmetryArg(a, doc.mesh, sym, symError)) return {false, symError};
                      if (!doc.sculptor.beginStroke(doc.mesh, "VDM", doc.activeLayer))
                          return {false, "Active layer weight is 0 - raise it to sculpt into the layer"};
                      doc.sculptor.dab(doc.mesh, doc.bvh, BrushType::Vdm, p, sym);
                      UndoRecord r = doc.sculptor.endStroke();
                      if (!r.empty()) doc.undo.push(std::move(r));
                      return {true, "Stamped VDM '" + (doc.brushVdm ? doc.brushVdm->name : std::string("Horn")) + "'"};
                  }});
    registry.add({"vdm_delete", "Delete a VDM from your brush library (built-ins and studio VDMs stay).",
                  {{"name", T::String, "The VDM to delete.", true}},
                  [](Document& doc, const Args& a) -> CommandResult {
                      const int i = findVdm(doc, argString(a, "name"));
                      if (i < 0) return {false, "No VDM called " + argString(a, "name")};
                      const auto v = doc.vdms[size_t(i)];
                      const std::string dir = brushLibraryPaths().userDir;
                      std::error_code ec;
                      const bool inLibrary = !v->builtin && !v->path.empty() && !dir.empty() &&
                                             fs::equivalent(utf8Path(v->path).parent_path(), utf8Path(dir), ec);
                      if (v->builtin) return {false, v->name + " is built in"};
                      if (!v->path.empty() && !inLibrary) return {false, v->name + " isn't in your brush library"};
                      if (!v->path.empty() && !fs::remove(utf8Path(v->path), ec))
                          return {false, "Can't delete " + v->path};
                      doc.vdms.erase(doc.vdms.begin() + i);
                      if (doc.brushVdm == v) doc.brushVdm = doc.vdms.front();
                      // A studio or built-in VDM of the same name comes back on the next library load.
                      return {true, "Deleted VDM '" + v->name + "'"};
                  }});
}

} // namespace sf