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.8 KB
Raw Blame
// SculptForge - open source digital sculpting
// SPDX-License-Identifier: GPL-3.0-or-later
#include "core/Masking.h"

#include "core/Commands.h"
#include "core/VertexPaint.h"
#include "core/ScreenSelect.h"
#include "core/Sculpt.h"
#include "core/ThreadPool.h"

#include <algorithm>
#include <cctype>
#include <cmath>
#include <functional>
#include <string>
#include <vector>

namespace sf {

namespace {

// Applies `next` (old mask -> new value of vertex v) to every visible vertex,
// double-buffered so each pass reads the previous one.
template <class F>
bool maskPass(Mesh& mesh, F next) {
    const uint32_t n = static_cast<uint32_t>(mesh.vertexCount());
    std::vector<float>& mask = mesh.ensureMask();
    std::vector<float> out(mask);
    const bool anyHidden = mesh.hasHidden();
    bool changed = false;
    for (uint32_t v = 0; v < n; ++v) {
        if (anyHidden && mesh.vertexHidden(v)) continue;
        const float m = std::clamp(next(mask, v), 0.0f, 1.0f);
        if (m != mask[v]) {
            out[v] = m;
            changed = true;
        }
    }
    if (changed) {
        mask.swap(out);
        mesh.markAllDirty();
    }
    return changed;
}

float neighbourAverage(const Mesh& mesh, const std::vector<float>& mask, uint32_t v) {
    auto ring = mesh.neighbors(v);
    if (ring.empty()) return mask[v];
    float sum = 0.0f;
    for (uint32_t u : ring) sum += mask[u];
    return sum / static_cast<float>(ring.size());
}

template <class F>
bool repeatPass(Mesh& mesh, int iterations, F next) {
    bool changed = false;
    for (int i = 0; i < std::max(1, iterations); ++i) {
        if (!maskPass(mesh, next)) break;
        changed = true;
    }
    return changed;
}


float smoothstep01(float e0, float e1, float x) {
    float t = std::clamp((x - e0) / std::max(e1 - e0, 1e-6f), 0.0f, 1.0f);
    return t * t * (3.0f - 2.0f * t);
}

} // namespace

bool symmetryArg(const Args& a, const Mesh& mesh, Symmetry& sym, std::string& error) {
    sym = Symmetry{false, false, false};
    for (char c : argString(a, "symmetry")) {
        const char l = char(std::tolower(static_cast<unsigned char>(c)));
        if (l == 'x') sym.x = true;
        else if (l == 'y') sym.y = true;
        else if (l == 'z') sym.z = true;
        else {
            error = "symmetry takes the axes x, y and z";
            return false;
        }
    }
    const double radial = argNumber(a, "radial", 1.0);
    if (!(radial >= 1.0 && radial <= double(Symmetry::kMaxRadial)) || radial != std::floor(radial)) {
        error = "radial takes a whole number of copies, 1 (off) to " + std::to_string(Symmetry::kMaxRadial);
        return false;
    }
    sym.radial = int(radial);
    sym.radialEnabled = sym.radial > 1;
    std::string axis = argString(a, "radial_axis");
    if (axis.empty()) axis = "y";
    for (char& c : axis) c = char(std::tolower(static_cast<unsigned char>(c)));
    if (axis != "x" && axis != "y" && axis != "z") {
        error = "radial_axis takes x, y or z";
        return false;
    }
    sym.radialAxis = axis[0] - 'x';
    sym.local = argBool(a, "local", false);
    if (sym.local) sym.pivot = symmetryPivot(mesh);
    return true;
}

bool symmetryCopiesArg(const Args& a, const Mesh& mesh, std::vector<SymCopy>& copies, std::string& error) {
    Symmetry sym;
    if (!symmetryArg(a, mesh, sym, error)) return false;
    copies = Sculptor::copies(sym);
    return true;
}

std::vector<ParamSpec> radialSymmetryParams() {
    return {{"radial", ParamSpec::Type::Number,
             "Radial symmetry: this many copies turned evenly around radial_axis (2-64; default 1, off). With "
             "mirror axes too, each mirror image gets its copies.",
             false},
            {"radial_axis", ParamSpec::Type::String, "The axis radial copies turn around: x, y or z (default y).", false},
            {"local", ParamSpec::Type::Bool,
             "Local symmetry: mirror planes and the radial axis go through the Part's centre instead of the world "
             "origin (default false).",
             false}};
}

bool maskClear(Mesh& mesh) {
    if (!mesh.hasMask()) return false;
    const bool changed = std::any_of(mesh.mask.begin(), mesh.mask.end(), [](float m) { return m != 0.0f; });
    mesh.clearMask();
    mesh.markAllDirty();
    return changed;
}

bool maskAll(Mesh& mesh) {
    return maskPass(mesh, [](const std::vector<float>&, uint32_t) { return 1.0f; });
}

bool maskInvert(Mesh& mesh) {
    return maskPass(mesh, [](const std::vector<float>& m, uint32_t v) { return 1.0f - m[v]; });
}

bool maskBlur(Mesh& mesh, int iterations) {
    if (!mesh.hasMask()) return false;
    return repeatPass(mesh, iterations, [&](const std::vector<float>& m, uint32_t v) {
        return 0.5f * m[v] + 0.5f * neighbourAverage(mesh, m, v);
    });
}

bool maskSharpen(Mesh& mesh, int iterations) {
    if (!mesh.hasMask()) return false;
    return repeatPass(mesh, iterations, [&](const std::vector<float>& m, uint32_t v) {
        // Unsharp step (away from the neighbour average) plus a mild contrast boost around 0.5.
        float s = m[v] + (m[v] - neighbourAverage(mesh, m, v));
        return (s - 0.5f) * 1.25f + 0.5f;
    });
}

bool maskGrow(Mesh& mesh, int iterations) {
    if (!mesh.hasMask()) return false;
    return repeatPass(mesh, iterations, [&](const std::vector<float>& m, uint32_t v) {
        float r = m[v];
        for (uint32_t u : mesh.neighbors(v)) r = std::max(r, m[u]);
        return r;
    });
}

bool maskShrink(Mesh& mesh, int iterations) {
    if (!mesh.hasMask()) return false;
    return repeatPass(mesh, iterations, [&](const std::vector<float>& m, uint32_t v) {
        float r = m[v];
        for (uint32_t u : mesh.neighbors(v)) r = std::min(r, m[u]);
        return r;
    });
}

float vertexConcavity(const Mesh& mesh, uint32_t v) {
    auto ring = mesh.neighbors(v);
    if (ring.empty()) return 0.0f;
    const glm::vec3& p = mesh.positions[v];
    glm::vec3 avg(0.0f);
    float edge = 0.0f;
    for (uint32_t u : ring) {
        avg += mesh.positions[u];
        edge += glm::distance(p, mesh.positions[u]);
    }
    avg /= static_cast<float>(ring.size());
    edge /= static_cast<float>(ring.size());
    if (edge <= 1e-12f) return 0.0f;
    return glm::dot(mesh.normals[v], avg - p) / edge;
}

bool maskByCavity(Mesh& mesh, float strength, float threshold) {
    const uint32_t n = static_cast<uint32_t>(mesh.vertexCount());
    if (n == 0) return false;
    strength = std::clamp(strength, 0.0f, 1.0f);
    // One smoothing pass over the raw concavity keeps single noisy vertices out.
    std::vector<float> raw(n), cav(n);
    for (uint32_t v = 0; v < n; ++v) raw[v] = vertexConcavity(mesh, v);
    for (uint32_t v = 0; v < n; ++v) cav[v] = 0.5f * raw[v] + 0.5f * neighbourAverage(mesh, raw, v);
    constexpr float kRamp = 0.15f; // concavity above the threshold at which the mask is full
    return maskPass(mesh, [&](const std::vector<float>&, uint32_t v) {
        return strength * smoothstep01(threshold, threshold + kRamp, cav[v]);
    });
}

bool maskByPeaks(Mesh& mesh, float strength, float threshold) {
    const uint32_t n = static_cast<uint32_t>(mesh.vertexCount());
    if (n == 0) return false;
    strength = std::clamp(strength, 0.0f, 1.0f);
    std::vector<float> raw(n), cav(n);
    for (uint32_t v = 0; v < n; ++v) raw[v] = vertexConcavity(mesh, v);
    for (uint32_t v = 0; v < n; ++v) cav[v] = 0.5f * raw[v] + 0.5f * neighbourAverage(mesh, raw, v);
    constexpr float kRamp = 0.15f; // (as maskByCavity)
    return maskPass(mesh, [&](const std::vector<float>&, uint32_t v) {
        return strength * smoothstep01(threshold, threshold + kRamp, -cav[v]);
    });
}

bool maskByColor(Mesh& mesh, const glm::vec3& color, float tolerance, float strength, bool add) {
    if (mesh.vertexCount() == 0) return false;
    tolerance = std::clamp(tolerance, 0.001f, 1.0f);
    strength = std::clamp(strength, 0.0f, 1.0f);
    const glm::vec3 c = glm::clamp(color, glm::vec3(0.0f), glm::vec3(1.0f));
    return maskPass(mesh, [&](const std::vector<float>& m, uint32_t v) {
        const float d = glm::distance(mesh.colorAt(v, glm::vec3(1.0f)), c) / 1.7320508f;
        const float w = strength * (1.0f - smoothstep01(tolerance * 0.8f, tolerance, d));
        return add ? std::max(m[v], w) : w;
    });
}

bool maskByFacing(Mesh& mesh, const glm::vec3& direction, float angleDeg, float strength, bool add) {
    if (mesh.vertexCount() == 0 || mesh.normals.size() != mesh.vertexCount()) return false;
    const float len = glm::length(direction);
    if (!(len > 1e-9f)) return false;
    const glm::vec3 dir = direction / len;
    angleDeg = std::clamp(angleDeg, 1.0f, 180.0f);
    strength = std::clamp(strength, 0.0f, 1.0f);
    const float full = std::max(0.0f, angleDeg - 15.0f); // fully masked inside this angle
    return maskPass(mesh, [&](const std::vector<float>& m, uint32_t v) {
        const float a = std::acos(std::clamp(glm::dot(mesh.normals[v], dir), -1.0f, 1.0f)) * 57.29578f;
        const float w = strength * (1.0f - smoothstep01(full, angleDeg, a));
        return add ? std::max(m[v], w) : w;
    });
}

bool maskByFaceGroup(Mesh& mesh, uint32_t group, bool add) {
    const uint32_t n = static_cast<uint32_t>(mesh.vertexCount());
    if (n == 0) return false;
    std::vector<uint8_t> inGroup(n, 0);
    bool found = false;
    for (uint32_t t = 0; t < mesh.triangleCount(); ++t) {
        if (mesh.facegroupAt(t) != group || mesh.triangleHidden(t)) continue;
        const glm::uvec3& tri = mesh.triangles[t];
        inGroup[tri.x] = inGroup[tri.y] = inGroup[tri.z] = 1;
        found = true;
    }
    if (!found && add) return false;
    return maskPass(mesh, [&](const std::vector<float>& m, uint32_t v) {
        return inGroup[v] ? 1.0f : add ? m[v] : 0.0f;
    });
}

std::vector<uint8_t> borderVertices(const Mesh& mesh, bool facegroups) {
    const uint32_t n = static_cast<uint32_t>(mesh.vertexCount());
    std::vector<uint8_t> border(n, 0);
    poolFor(n, [&](size_t b, size_t e) {
        std::vector<uint32_t> corners;
        for (size_t i = b; i < e; ++i) {
            const uint32_t v = uint32_t(i);
            corners.clear();
            bool mixed = false, seenGroup = false;
            uint32_t group = 0;
            for (uint32_t t : mesh.vertexTriangles(v)) {
                const glm::uvec3& tri = mesh.triangles[t];
                for (int k = 0; k < 3; ++k)
                    if (tri[k] != v) corners.push_back(tri[k]);
                if (!facegroups || mesh.triangleHidden(t)) continue;
                const uint32_t g = mesh.facegroupAt(t);
                if (seenGroup && g != group) mixed = true;
                group = g;
                seenGroup = true;
            }
            if (corners.empty()) continue; // a loose vertex is no border
            // Each edge v-u of a closed surface belongs to two of v's triangles, so u is listed twice; once is open.
            std::sort(corners.begin(), corners.end());
            bool open = false;
            for (size_t c = 0; c < corners.size() && !open;) {
                size_t d = c + 1;
                while (d < corners.size() && corners[d] == corners[c]) ++d;
                open = d - c == 1;
                c = d;
            }
            border[v] = (open || mixed) ? 1 : 0;
        }
    });
    return border;
}

bool maskBorder(Mesh& mesh, int rings, bool facegroups, bool soft, float strength, bool add, size_t* found) {
    const uint32_t n = static_cast<uint32_t>(mesh.vertexCount());
    if (found) *found = 0;
    if (n == 0) return false;
    rings = std::clamp(rings, 1, 20);
    strength = std::clamp(strength, 0.0f, 1.0f);
    // Ring index of each vertex from the border (0 = on it), out to rings - 1; -1 beyond.
    const std::vector<uint8_t> border = borderVertices(mesh, facegroups);
    std::vector<int8_t> ring(n, -1);
    std::vector<uint32_t> frontier, next;
    for (uint32_t v = 0; v < n; ++v)
        if (border[v]) {
            ring[v] = 0;
            frontier.push_back(v);
        }
    if (found) *found = frontier.size();
    if (frontier.empty()) return false;
    for (int r = 1; r < rings && !frontier.empty(); ++r) {
        next.clear();
        for (uint32_t v : frontier)
            for (uint32_t u : mesh.neighbors(v))
                if (ring[u] < 0) {
                    ring[u] = int8_t(r);
                    next.push_back(u);
                }
        frontier.swap(next);
    }
    return maskPass(mesh, [&](const std::vector<float>& m, uint32_t v) {
        float value = 0.0f;
        if (ring[v] >= 0) value = strength * (soft ? 1.0f - float(ring[v]) / float(rings) : 1.0f);
        return add ? std::max(m[v], value) : value;
    });
}

namespace {

// Vertex v, or one of its mirror images, projects inside the shape.
bool inShape(const Mesh& mesh, const glm::mat4& viewProj, const ScreenPolygon& shape,
             const std::vector<SymCopy>& mirrors, uint32_t v, const glm::mat4* invViewProj = nullptr) {
    // With `invViewProj` (Front faces only), the point's normal must face the viewer: against the view ray
    // through it, which works for perspective and orthographic views alike.
    auto facing = [&](const glm::vec3& n, glm::vec2 ndc) {
        if (!invViewProj || v >= mesh.normals.size()) return true;
        const glm::vec4 a = *invViewProj * glm::vec4(ndc, -1.0f, 1.0f), b = *invViewProj * glm::vec4(ndc, 1.0f, 1.0f);
        return glm::dot(n, glm::vec3(b) / b.w - glm::vec3(a) / a.w) < 0.0f;
    };
    glm::vec2 ndc;
    const glm::vec3 n = v < mesh.normals.size() ? mesh.normals[v] : glm::vec3(0.0f);
    if (projectToNdc(viewProj, mesh.positions[v], ndc) && shape.contains(ndc) && facing(n, ndc)) return true;
    for (const SymCopy& m : mirrors)
        if (!m.identity() && projectToNdc(viewProj, m.point(mesh.positions[v]), ndc) && shape.contains(ndc) &&
            facing(m.dir(n), ndc))
            return true;
    return false;
}

} // namespace

bool maskInShape(Mesh& mesh, const glm::mat4& viewProj, const ScreenPolygon& shape, float strength, bool unmask,
                 const std::vector<SymCopy>& mirrors, bool frontFacesOnly) {
    if (mesh.vertexCount() == 0 || !shape.valid()) return false;
    const float s = std::clamp(strength, 0.0f, 1.0f);
    const glm::mat4 inv = glm::inverse(viewProj);
    return maskPass(mesh, [&](const std::vector<float>& m, uint32_t v) {
        if (!inShape(mesh, viewProj, shape, mirrors, v, frontFacesOnly ? &inv : nullptr)) return m[v];
        return unmask ? m[v] * (1.0f - s) : m[v] + (1.0f - m[v]) * s;
    });
}

bool shapeCoversMesh(const Mesh& mesh, const glm::mat4& viewProj, const ScreenPolygon& shape,
                     const std::vector<SymCopy>& mirrors) {
    if (!shape.valid()) return false;
    const bool anyHidden = mesh.hasHidden();
    for (uint32_t v = 0; v < uint32_t(mesh.vertexCount()); ++v)
        if (!(anyHidden && mesh.vertexHidden(v)) && inShape(mesh, viewProj, shape, mirrors, v)) return true;
    return false;
}

void Sculptor::dabMask(Mesh& mesh, const BVH& bvh, const DabParams& p, Symmetry sym) {
    if (!active_) return;
    const float s = std::clamp(p.strength, 0.0f, 1.0f) * std::clamp(p.pressure, 0.0f, 1.0f);
    if (s <= 0.0f) return;
    if (microReady(mesh)) { // the micro level's own mask, per grid point (core/MicroSculpt.cpp)
        const double k0 = micro_.findMs + micro_.kernelMs + micro_.stitchMs;
        for (const SymCopy& mirror : copies(sym))
            micro_.dab(mesh, bvh, BrushType::Standard, mirror.point(p.center), mirror.dir(p.viewDir), p.radius, 1.0f, p.invert,
                       p.focal, mirror.dir(p.alphaUp), true, s);
        timings.kernelMs += micro_.findMs + micro_.kernelMs + micro_.stitchMs - k0;
        ++timings.dabs;
        return;
    }
    auto clock = std::chrono::steady_clock::now();
    std::vector<float>& mask = mesh.ensureMask();
    for (const SymCopy& mirror : copies(sym)) {
        const glm::vec3 center = mirror.point(p.center), viewDir = mirror.dir(p.viewDir);
        brushRegion(mesh, bvh, center, viewDir, p.radius, p.connectedOnly, p.viewFalloff, verts_, connected_);
        // New values in parallel; recording and writing them in order.
        weights_.resize(verts_.size());
        poolFor(verts_.size(), [&](size_t b, size_t e) {
            for (size_t i = b; i < e; ++i) {
                const uint32_t v = verts_[i];
                weights_[i] = -1.0f; // unchanged
                if (p.frontFacesOnly && glm::dot(mesh.normals[v], viewDir) > 0.0f) continue;
                const float a = s * brushFalloff(brushDistance(mesh.positions[v], center, viewDir, p.viewFalloff), p.radius, p.focal);
                if (a <= 0.0f) continue;
                const float m = p.invert ? mask[v] * (1.0f - a) : mask[v] + (1.0f - mask[v]) * a;
                if (m != mask[v]) weights_[i] = m;
            }
        });
        for (size_t i = 0; i < verts_.size(); ++i) {
            if (weights_[i] < 0.0f) continue;
            const uint32_t v = verts_[i];
            recordMask(mesh, v);
            mask[v] = weights_[i];
            mesh.markDirty(v);
        }
        timings.vertices += verts_.size();
    }
    timings.kernelMs += lapMs(clock);
    ++timings.dabs;
}

void registerMaskingCommands(CommandRegistry& registry) {
    using T = ParamSpec::Type;
    // Wraps a mask operation as an undoable command.
    auto add = [&registry](std::string name, std::string label, std::string description, std::vector<ParamSpec> params,
                           std::function<bool(Mesh&, const Args&)> op) {
        registry.add({std::move(name), std::move(description), std::move(params),
                      [label, op](Document& doc, const Args& a) -> CommandResult {
                          if (doc.mesh.vertexCount() == 0) return {false, "The mesh is empty"};
                          UndoRecord record = UndoRecord::captureMask(doc.mesh, label);
                          if (!op(doc.mesh, a)) return {true, label + ": mask unchanged"};
                          doc.undo.push(std::move(record));
                          doc.modified = true;
                          return {true, label};
                      }});
    };
    const ParamSpec iterations{"iterations", T::Number, "Number of passes (1-100). Default 1.", false};
    auto iters = [](const Args& a) { return std::clamp(int(argNumber(a, "iterations", 1)), 1, 100); };

    add("mask_clear", "Clear Mask", "Remove the mask so every vertex can be sculpted again.", {},
        [](Mesh& m, const Args&) { return maskClear(m); });
    add("mask_all", "Mask All", "Mask every visible vertex (protects the whole mesh from brushes).", {},
        [](Mesh& m, const Args&) { return maskAll(m); });
    add("mask_invert", "Invert Mask", "Invert the mask of visible vertices: masked becomes free and vice versa.", {},
        [](Mesh& m, const Args&) { return maskInvert(m); });
    add("mask_blur", "Blur Mask", "Soften the mask edges by averaging with neighbouring vertices.", {iterations},
        [iters](Mesh& m, const Args& a) { return maskBlur(m, iters(a)); });
    add("mask_sharpen", "Sharpen Mask", "Tighten soft mask edges, pushing values towards fully masked or free.",
        {iterations}, [iters](Mesh& m, const Args& a) { return maskSharpen(m, iters(a)); });
    add("mask_grow", "Grow Mask", "Expand the masked region by one edge ring per iteration.", {iterations},
        [iters](Mesh& m, const Args& a) { return maskGrow(m, iters(a)); });
    add("mask_shrink", "Shrink Mask", "Contract the masked region by one edge ring per iteration.", {iterations},
        [iters](Mesh& m, const Args& a) { return maskShrink(m, iters(a)); });
    add("mask_by_cavity", "Mask by Cavity",
        "Mask concave areas (creases, folds, pores), replacing the current mask - e.g. to protect detail while smoothing.",
        {{"strength", T::Number, "Mask value in the deepest cavities (0-1). Default 1.", false},
         {"threshold", T::Number,
          "Concavity above which vertices get masked (-1 to 1; 0 = anything concave, higher = only deep creases). "
          "Default 0.02.",
          false}},
        [](Mesh& m, const Args& a) {
            return maskByCavity(m, float(argNumber(a, "strength", 1.0)),
                                std::clamp(float(argNumber(a, "threshold", 0.02)), -1.0f, 1.0f));
        });
    add("mask_by_peaks", "Mask by Peaks",
        "Mask convex areas (ridges, peaks, sharp edges), replacing the current mask - e.g. to work only in the "
        "valleys, or to protect edges.",
        {{"strength", T::Number, "Mask value on the sharpest peaks (0-1). Default 1.", false},
         {"threshold", T::Number,
          "Convexity above which vertices get masked (-1 to 1; 0 = anything convex, higher = only sharp ridges). "
          "Default 0.02.",
          false}},
        [](Mesh& m, const Args& a) {
            return maskByPeaks(m, float(argNumber(a, "strength", 1.0)),
                               std::clamp(float(argNumber(a, "threshold", 0.02)), -1.0f, 1.0f));
        });
    add("mask_by_color", "Mask by Colour",
        "Mask the vertices whose vertex paint is close to a colour (unpainted meshes are white).",
        {{"color", T::String, "The colour by name or #rrggbb (or give r, g, b).", false},
         {"r", T::Number, "Red 0-1 (sRGB), instead of color.", false},
         {"g", T::Number, "Green 0-1 (sRGB).", false},
         {"b", T::Number, "Blue 0-1 (sRGB).", false},
         {"tolerance", T::Number, "How different a colour may be and still count (0-1). Default 0.15.", false},
         {"strength", T::Number, "Mask value (0-1). Default 1.", false},
         {"add", T::Bool, "Add to the current mask instead of replacing it. Default false.", false}},
        [](Mesh& m, const Args& a) {
            glm::vec3 c(1.0f);
            std::string err;
            if (!colorArg(a, c, err)) return false;
            return maskByColor(m, c, float(argNumber(a, "tolerance", 0.15)), float(argNumber(a, "strength", 1.0)),
                               argBool(a, "add", false));
        });
    add("mask_by_facing", "Mask by Facing",
        "Mask the vertices whose surface faces a direction (within an angle): e.g. 0 0 1 masks what faces the front "
        "view, 0 1 0 what faces up.",
        {{"x", T::Number, "Direction x.", true},
         {"y", T::Number, "Direction y.", true},
         {"z", T::Number, "Direction z.", true},
         {"angle", T::Number, "Largest angle from the direction, in degrees (1-180). Default 60.", false},
         {"strength", T::Number, "Mask value (0-1). Default 1.", false},
         {"add", T::Bool, "Add to the current mask instead of replacing it. Default false.", false}},
        [](Mesh& m, const Args& a) {
            const glm::vec3 d(float(argNumber(a, "x", 0)), float(argNumber(a, "y", 0)), float(argNumber(a, "z", 1)));
            return maskByFacing(m, d, float(argNumber(a, "angle", 60)), float(argNumber(a, "strength", 1.0)),
                                argBool(a, "add", false));
        });
    add("mask_by_facegroup", "Mask by Face Group",
        "Mask the vertices of one face group (meshes without face groups are all group 0).",
        {{"group", T::Number, "Face Group id.", true},
         {"add", T::Bool, "Add to the current mask instead of replacing it. Default false.", false}},
        [](Mesh& m, const Args& a) {
            return maskByFaceGroup(m, uint32_t(std::max(0.0, argNumber(a, "group", 0))), argBool(a, "add", false));
        });

    registry.add(
        {"mask_border",
         "Mask from the mesh border (Blender: Mask from mesh boundary): mask the vertices on open edges - and, with "
         "face groups, where face groups meet - plus edge rings inside them, so sculpting keeps the border in place. "
         "Replaces the mask unless add is set. A closed mesh has no open edges and masks nothing.",
         {{"rings", T::Number, "Width of the mask in edge rings from the border (1-20; 1 = the border vertices only). "
                               "Default 1.",
           false},
          {"facegroups", T::Bool, "Also mask face group borders. Default false.",
           false},
          {"soft", T::Bool, "Fade the mask from the border towards the innermost ring. Default false.", false},
          {"strength", T::Number, "Mask value on the border (0-1). Default 1.", false},
          {"add", T::Bool, "Add to the current mask instead of replacing it. Default false.", false}},
         [](Document& doc, const Args& a) -> CommandResult {
             if (doc.mesh.vertexCount() == 0) return {false, "The mesh is empty"};
             const std::string label = "Mask Border";
             const bool facegroups = argBool(a, "facegroups", false);
             UndoRecord record = UndoRecord::captureMask(doc.mesh, label);
             size_t found = 0;
             const bool changed =
                 maskBorder(doc.mesh, int(argNumber(a, "rings", 1)), facegroups, argBool(a, "soft", false),
                            float(argNumber(a, "strength", 1.0)), argBool(a, "add", false), &found);
             if (found == 0)
                 return {true, facegroups ? "No open edges or face group borders: the mesh is closed and one face group"
                                          : "No open edges: the mesh is closed"};
             if (!changed) return {true, label + ": mask unchanged"};
             doc.undo.push(std::move(record));
             doc.modified = true;
             return {true, label + ": " + std::to_string(found) + " border vertices"};
         }});

    // MaskRect / MaskLasso. Bad arguments are errors, unlike the "mask unchanged" of a selection that misses.
    const ParamSpec unmask{"unmask", T::Bool, "Unmask the inside instead. Default false.", false};
    const ParamSpec strength{"strength", T::Number, "How much to mask or unmask (0-1). Default 1.", false};
    const ParamSpec viewProj{"view_proj", T::String, "Optional 16 numbers: column-major view-projection matrix.",
                             false};
    const ParamSpec symmetry{"symmetry", T::String,
                             "Mirror axes, e.g. \"x\" or \"xz\": the mirror image of the shape is selected too, as the "
                             "brushes mirror (default none).",
                             false};
    const ParamSpec clearOutside{"clear_outside", T::Bool,
                                 "When the shape covers none of the model, clear the mask instead (like Ctrl+drag on "
                                 "the background). Default false.",
                                 false};
    const ParamSpec frontFaces{"front_faces_only", T::Bool,
                               "Only vertices facing the viewer: the far side of the model, and folds turned away, "
                               "are left as they are (#91.3). Default false.",
                               false};
    auto selection = [&registry](std::string name, std::string description, std::vector<ParamSpec> params,
                                 std::function<bool(const Args&, std::vector<glm::vec2>&, std::string&)> shape) {
        registry.add(
            {std::move(name), std::move(description), std::move(params),
             [shape](Document& doc, const Args& a) -> CommandResult {
                 if (doc.mesh.vertexCount() == 0) return {false, "The mesh is empty"};
                 glm::mat4 vp;
                 std::vector<glm::vec2> points;
                 std::string error;
                 if (!viewProjArg(doc.mesh, a, vp, error) || !shape(a, points, error)) return {false, error};
                 std::vector<SymCopy> mirrors;
                 if (!symmetryCopiesArg(a, doc.mesh, mirrors, error)) return {false, error};
                 const ScreenPolygon polygon(points);
                 const bool unmask = argBool(a, "unmask", false);
                 if (argBool(a, "clear_outside", false) && !shapeCoversMesh(doc.mesh, vp, polygon, mirrors)) {
                     UndoRecord record = UndoRecord::captureMask(doc.mesh, "Clear Mask");
                     if (!maskClear(doc.mesh)) return {true, "Clear Mask: mask unchanged"};
                     doc.undo.push(std::move(record));
                     doc.modified = true;
                     return {true, "Clear Mask"};
                 }
                 const std::string label = unmask ? "Unmask" : "Mask";
                 UndoRecord record = UndoRecord::captureMask(doc.mesh, label);
                 if (!maskInShape(doc.mesh, vp, polygon, float(argNumber(a, "strength", 1.0)), unmask, mirrors,
                                  argBool(a, "front_faces_only", false)))
                     return {true, label + ": mask unchanged"};
                 doc.undo.push(std::move(record));
                 doc.modified = true;
                 return {true, label};
             }});
    };
    selection(
        "mask_rect",
        "Rectangle mask selection: mask the visible vertices inside a screen rectangle, "
        "or unmask them. Coordinates are normalised (-1..1, y up) in the given view; without a view the rectangle "
        "spans the mesh seen from the front (+Z).",
        {{"x0", T::Number, "Rectangle left (-1..1). Default -1.", false},
         {"y0", T::Number, "Rectangle bottom (-1..1). Default -1.", false},
         {"x1", T::Number, "Rectangle right (-1..1). Default 1.", false},
         {"y1", T::Number, "Rectangle top (-1..1). Default 1.", false},
         unmask,
         strength,
         viewProj,
         symmetry,
         clearOutside,
         frontFaces},
        [](const Args& a, std::vector<glm::vec2>& points, std::string&) {
            const float x0 = float(argNumber(a, "x0", -1)), y0 = float(argNumber(a, "y0", -1));
            const float x1 = float(argNumber(a, "x1", 1)), y1 = float(argNumber(a, "y1", 1));
            points = {{x0, y0}, {x1, y0}, {x1, y1}, {x0, y1}};
            return true;
        });
    selection(
        "mask_lasso",
        "Lasso mask selection: mask the visible vertices inside a screen polygon, or "
        "unmask them. Points are normalised (-1..1, y up) in the given view; without a view they span the mesh "
        "seen from the front (+Z).",
        {{"points", T::String, "The lasso: at least 3 points as \"x0 y0 x1 y1 ...\" (-1..1, y up).", true},
         unmask,
         strength,
         viewProj,
         symmetry,
         clearOutside,
         frontFaces},
        lassoArg);
}

} // namespace sf