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.
C++ 3d3d-sculptingcppdear-imguidigital-sculptingfbxgame-developmentgaussian-splattinggltfimage-to-3dmcpopenglopenusdsculptingtext-to-3dunreal-engine
Masking: Ctrl mask strokes and mask_* commands
islandmedbee9890de0ef
diff --git a/CMakeLists.txt b/CMakeLists.txtindex 4e439795..6d3ff221 100644--- a/CMakeLists.txt+++ b/CMakeLists.txt@@ -41,6 +41,7 @@ add_library(sculptforge_core STATICsrc/core/Splats.cppsrc/core/Voxel.cppsrc/core/EnginePresets.cpp+ src/core/Masking.cppsrc/io/ObjIO.cppsrc/io/FbxIO.cppthird_party/ufbx/ufbx.c@@ -103,6 +104,7 @@ if(SCULPTFORGE_BUILD_APP)src/app/main.cppsrc/app/App.cppsrc/app/Demo.cpp+ src/app/PanelMasking.cppsrc/render/GL.cppsrc/render/Camera.cppsrc/render/Renderer.cppdiff --git a/src/app/App.cpp b/src/app/App.cppindex 2125f4ba..aadb467b 100644--- a/src/app/App.cpp+++ b/src/app/App.cpp@@ -460,8 +460,15 @@ void App::onMouseDown(float x, float y, Uint8 button) {doc_.syncBvh();if (button == SDL_BUTTON_LEFT) {RayHit hit;+ const bool maskMod = ctrlDown(mod) && !(mod & SDL_KMOD_SHIFT);if (previewLod_ < 0 && pick(x, y, hit)) {- beginStroke(x, y, hit);+ if (maskMod) beginMaskStroke(x, y);+ else beginStroke(x, y, hit);+ } else if (maskMod && !(mod & SDL_KMOD_ALT) && previewLod_ < 0) {+ drag_ = Drag::MaskCanvas; // click inverts, drag clears (or zooms without a mask)+ maskCanvasX_ = x;+ maskCanvasY_ = y;+ maskCanvasMoved_ = false;} else {// Dragging on empty space navigates (ZBrush style).drag_ = (mod & SDL_KMOD_ALT) ? Drag::Pan : ctrlDown(mod) ? Drag::Zoom : Drag::Orbit;@@ -484,12 +491,14 @@ void App::onMouseMove(float x, float y, float dx, float dy, bool fromPen) {case Drag::Orbit: camera_.orbit(dx, dy); break;case Drag::Pan: camera_.pan(dx, dy, float(h)); break;case Drag::Zoom: camera_.zoom(-dy * 0.05f); break;+ case Drag::MaskCanvas: maskCanvasMove(x, y); break;case Drag::None: break;}}void App::onMouseUp() {if (drag_ == Drag::Stroke) endStroke();+ if (drag_ == Drag::MaskCanvas) maskCanvasRelease();drag_ = Drag::None;}@@ -564,7 +573,7 @@ void App::beginStroke(float x, float y, const RayHit& hit) {}void App::strokeTo(float x, float y) {- const BrushRecipe* recipe = strokeBrush_ == BrushType::Smooth ? nullptr : activeRecipe();+ const BrushRecipe* recipe = strokeBrush_ == BrushType::Smooth || strokeMask_ ? nullptr : activeRecipe();if (strokeBrush_ == BrushType::Move && !recipe) {int w = 0, h = 0;SDL_GetWindowSize(window_, &w, &h);@@ -596,7 +605,7 @@ void App::strokeTo(float x, float y) {}void App::dabAt(float x, float y) {- const BrushRecipe* recipe = strokeBrush_ == BrushType::Smooth ? nullptr : activeRecipe();+ const BrushRecipe* recipe = strokeBrush_ == BrushType::Smooth || strokeMask_ ? nullptr : activeRecipe();if (recipe && recipe->jitter > 0.0f) {// Deterministic per-stroke scatter (xorshift).auto rnd = [this] {@@ -623,6 +632,11 @@ void App::dabAt(float x, float y) {p.pressure = pressureStrength_ ? pressure : 1.0f;p.invert = strokeInvert_;p.frontFacesOnly = frontFacesOnly_;+ if (strokeMask_) {+ p.strength = maskStrength_;+ doc_.sculptor.dabMask(doc_.mesh, doc_.bvh, p, symmetry_);+ return;+ }if (recipe) {p.strokeDelta = haveLastDab_ ? hit.position - lastDabHit_ : glm::vec3(0.0f);lastDabHit_ = hit.position;@@ -634,6 +648,7 @@ void App::dabAt(float x, float y) {}void App::endStroke() {+ strokeMask_ = false;UndoRecord r = doc_.sculptor.endStroke();if (!r.empty()) {doc_.undo.push(std::move(r));@@ -866,7 +881,11 @@ void App::drawUi() {"Smooth Hold Shift while sculpting\n""Rotate Left drag on background / right drag\n""Pan Alt + left drag background / middle drag\n"- "Zoom Mouse wheel / Ctrl + left drag background\n"+ "Zoom Mouse wheel / Ctrl + middle drag\n"+ " (Ctrl + left drag background when nothing is masked)\n"+ "Paint mask Hold Ctrl while stroking (Ctrl+Alt erases)\n"+ "Invert mask Ctrl + click background\n"+ "Clear mask Ctrl + drag background\n""Brush size [ and ]\n""Brushes 1-8\n""Symmetry X X\n"@@ -1628,6 +1647,8 @@ void App::drawToolPanel() {if (penSeen_) ImGui::Text("Pen pressure: %.2f", penPressure_);else ImGui::TextDisabled("No pen detected");+ drawMaskingSection();+ImGui::SeparatorText("Mesh");if (ImGui::Button("Subdivide (Ctrl+D)", ImVec2(-1, 0))) runCommand("subdivide");if (ImGui::Button("Voxel remesh", ImVec2(ImGui::GetContentRegionAvail().x * 0.5f, 0)))@@ -1704,7 +1725,10 @@ void App::drawBrushCursor() {const float r = radiusPx_ * (pressureSize_ && lastInputPen_ ? std::max(penPressure_, 0.05f) : 1.0f);const ImVec2 c(mouseX_, mouseY_);const bool inverted = invertToggle_ != ((SDL_GetModState() & SDL_KMOD_ALT) != 0);- const ImU32 col = activeBrush() == BrushType::Smooth ? IM_COL32(120, 200, 255, 200)+ const SDL_Keymod mod = SDL_GetModState();+ const bool masking = drag_ == Drag::Stroke ? strokeMask_ : ctrlDown(mod) && !(mod & SDL_KMOD_SHIFT);+ const ImU32 col = masking ? IM_COL32(230, 230, 230, 200)+ : activeBrush() == BrushType::Smooth ? IM_COL32(120, 200, 255, 200): inverted ? IM_COL32(255, 110, 110, 200): IM_COL32(255, 190, 120, 200);dl->AddCircle(c, r, col, 64, 1.5f);diff --git a/src/app/App.h b/src/app/App.hindex e6de675a..7d5b6267 100644--- a/src/app/App.h+++ b/src/app/App.h@@ -58,7 +58,7 @@ public:void queueFile(FileAction action, std::string path);private:- enum class Drag { None, Stroke, Orbit, Pan, Zoom };+ enum class Drag { None, Stroke, Orbit, Pan, Zoom, MaskCanvas };void handleEvent(const SDL_Event& e);void onMouseDown(float x, float y, Uint8 button);@@ -229,6 +229,20 @@ private:const Mesh* lastDisplayed_ = nullptr;std::mutex pendingMutex_;std::vector<PendingFile> pendingFiles_;++ // Masking (PanelMasking.cpp): Ctrl strokes paint mask, Ctrl+Alt erases;+ // Ctrl+click on the background inverts it, Ctrl+drag there clears it.+ void drawMaskingSection();+ void beginMaskStroke(float x, float y);+ void maskCanvasMove(float x, float y);+ void maskCanvasRelease();+ bool strokeMask_ = false; // the current stroke edits the mask+ float maskStrength_ = 1.0f;+ int maskIterations_ = 1;+ float cavityThreshold_ = 0.02f;+ int maskGroup_ = 0;+ float maskCanvasX_ = 0.0f, maskCanvasY_ = 0.0f;+ bool maskCanvasMoved_ = false;};} // namespace sfdiff --git a/src/app/PanelMasking.cpp b/src/app/PanelMasking.cppnew file mode 100644index 00000000..fbeea803--- /dev/null+++ b/src/app/PanelMasking.cpp@@ -0,0 +1,94 @@+// SculptForge - open source digital sculpting+// SPDX-License-Identifier: GPL-3.0-or-later+//+// Masking: Ctrl mask strokes, the Ctrl + background gestures and the+// "Masking" section of the Tools panel. The operations themselves are the+// mask_* commands (core/Masking.cpp).+#include "app/App.h"++#include <algorithm>+#include <cmath>++namespace sf {++namespace {++constexpr float kMaskDragThresholdPx = 4.0f; // movement that turns a Ctrl+click into a drag++bool anyMasked(const Mesh& mesh) {+ return std::any_of(mesh.mask.begin(), mesh.mask.end(), [](float m) { return m > 0.0f; });+}++} // namespace++void App::beginMaskStroke(float x, float y) {+ // Masks are not layered, so the stroke always targets the base (its weight is never 0).+ strokeInvert_ = (SDL_GetModState() & SDL_KMOD_ALT) != 0; // Ctrl+Alt erases+ if (!doc_.sculptor.beginStroke(doc_.mesh, strokeInvert_ ? "Unmask" : "Mask", -1)) return;+ strokeMask_ = true;+ strokeBrush_ = BrushType::Standard;+ haveLastDab_ = false;+ drag_ = Drag::Stroke;+ lastX_ = x;+ lastY_ = y;+ residual_ = 0.0f;+ dabAt(x, y);+}++// ZBrush convention: Ctrl+drag on the background clears the mask. With+// nothing masked the drag zooms instead, as it did before masking existed.+void App::maskCanvasMove(float x, float y) {+ if (maskCanvasMoved_) return;+ if (std::hypot(x - maskCanvasX_, y - maskCanvasY_) < kMaskDragThresholdPx) return;+ maskCanvasMoved_ = true;+ if (anyMasked(doc_.mesh)) runCommand("mask_clear");+ else drag_ = Drag::Zoom;+}++void App::maskCanvasRelease() {+ if (!maskCanvasMoved_) runCommand("mask_invert"); // Ctrl+click on the background+}++void App::drawMaskingSection() {+ ImGui::SeparatorText("Masking");+ ImGui::Checkbox("Show mask", &renderSettings_.showMask);+ ImGui::SameLine();+ ImGui::TextDisabled("(Ctrl paints, Ctrl+Alt erases)");+ ImGui::SetNextItemWidth(-1);+ ImGui::SliderFloat("##maskstrength", &maskStrength_, 0.01f, 1.0f, "mask strength %.2f");++ const ImGuiStyle& style = ImGui::GetStyle();+ const float third = (ImGui::GetContentRegionAvail().x - 2 * style.ItemSpacing.x) / 3.0f;+ const float half = (ImGui::GetContentRegionAvail().x - style.ItemSpacing.x) * 0.5f;+ if (ImGui::Button("Clear##mask", ImVec2(third, 0))) runCommand("mask_clear");+ if (ImGui::IsItemHovered()) ImGui::SetTooltip("Unmask everything (Ctrl + drag background)");+ ImGui::SameLine();+ if (ImGui::Button("Invert##mask", ImVec2(third, 0))) runCommand("mask_invert");+ if (ImGui::IsItemHovered()) ImGui::SetTooltip("Ctrl + click background");+ ImGui::SameLine();+ if (ImGui::Button("All##mask", ImVec2(third, 0))) runCommand("mask_all");++ const Args passes = {{"iterations", double(maskIterations_)}};+ if (ImGui::Button("Blur##mask", ImVec2(half, 0))) runCommand("mask_blur", passes);+ ImGui::SameLine();+ if (ImGui::Button("Sharpen##mask", ImVec2(half, 0))) runCommand("mask_sharpen", passes);+ if (ImGui::Button("Grow##mask", ImVec2(half, 0))) runCommand("mask_grow", passes);+ ImGui::SameLine();+ if (ImGui::Button("Shrink##mask", ImVec2(half, 0))) runCommand("mask_shrink", passes);+ ImGui::SetNextItemWidth(-1);+ ImGui::SliderInt("##maskpasses", &maskIterations_, 1, 20, "passes %d");++ if (ImGui::Button("By cavity", ImVec2(half, 0)))+ runCommand("mask_by_cavity", {{"strength", double(maskStrength_)}, {"threshold", double(cavityThreshold_)}});+ if (ImGui::IsItemHovered()) ImGui::SetTooltip("Mask creases and folds (replaces the mask; uses the mask strength)");+ ImGui::SameLine();+ ImGui::SetNextItemWidth(-1);+ ImGui::SliderFloat("##cavitythreshold", &cavityThreshold_, -0.2f, 0.5f, "threshold %.2f");+ if (ImGui::Button("By polygroup", ImVec2(half, 0))) runCommand("mask_by_polygroup", {{"index", double(maskGroup_)}});+ if (ImGui::IsItemHovered()) ImGui::SetTooltip("Mask one polygroup (replaces the mask)");+ ImGui::SameLine();+ ImGui::SetNextItemWidth(-1);+ if (ImGui::InputInt("##maskgroup", &maskGroup_)) maskGroup_ = std::max(0, maskGroup_);+}++} // namespace sfdiff --git a/src/core/Commands.cpp b/src/core/Commands.cppindex 22da76d6..8e099f57 100644--- a/src/core/Commands.cpp+++ b/src/core/Commands.cpp@@ -5,6 +5,7 @@#include "core/Decimate.h"#include "core/EnginePresets.h"#include "core/ImageTo3D.h"+#include "core/Masking.h"#include "core/Primitives.h"#include "core/Splats.h"#include "core/Voxel.h"@@ -596,6 +597,8 @@ CommandRegistry::CommandRegistry() {<< b.max.y << ", " << b.max.z << ")";return {true, s.str()};}});++ registerMaskingCommands(*this);}void CommandRegistry::add(Command cmd) { commands_.push_back(std::move(cmd)); }diff --git a/src/core/Masking.cpp b/src/core/Masking.cppnew file mode 100644index 00000000..7322b7f7--- /dev/null+++ b/src/core/Masking.cpp@@ -0,0 +1,235 @@+// SculptForge - open source digital sculpting+// SPDX-License-Identifier: GPL-3.0-or-later+#include "core/Masking.h"++#include "core/Commands.h"+#include "core/Sculpt.h"++#include <algorithm>+#include <cmath>+#include <functional>++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 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 maskByPolygroup(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.polygroupAt(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;+ });+}++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;+ std::vector<float>& mask = mesh.ensureMask();+ for (const glm::vec3& mirror : mirrors(sym)) {+ const glm::vec3 center = p.center * mirror, viewDir = p.viewDir * mirror;+ brushVertices(mesh, bvh, center, p.radius, verts_);+ for (uint32_t v : verts_) {+ if (p.frontFacesOnly && glm::dot(mesh.normals[v], viewDir) > 0.0f) continue;+ const float a = s * brushFalloff(glm::distance(mesh.positions[v], center), p.radius);+ 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]) continue;+ recordMask(mesh, v);+ mask[v] = m;+ mesh.markDirty(v);+ }+ }+}++void registerMaskingCommands(CommandRegistry& registry) {+ using T = ParamSpec::Type;+ // Wraps a mask operation as an undoable command.+ auto add = [®istry](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_polygroup", "Mask by Polygroup",+ "Mask the vertices of one polygroup (meshes without polygroups are all group 0).",+ {{"index", T::Number, "Polygroup id.", true},+ {"add", T::Bool, "Add to the current mask instead of replacing it. Default false.", false}},+ [](Mesh& m, const Args& a) {+ return maskByPolygroup(m, uint32_t(std::max(0.0, argNumber(a, "index", 0))), argBool(a, "add", false));+ });+}++} // namespace sfdiff --git a/src/core/Masking.h b/src/core/Masking.hnew file mode 100644index 00000000..af6334cf--- /dev/null+++ b/src/core/Masking.h@@ -0,0 +1,44 @@+// SculptForge - open source digital sculpting+// SPDX-License-Identifier: GPL-3.0-or-later+//+// ZBrush-style masking. Mask strokes are Sculptor::dabMask (see Sculpt.h);+// the whole-mesh operations below edit Mesh::mask in place. They never touch+// fully hidden vertices (except clear, which frees the mask), mark the+// changed vertices dirty for the renderer and return false when nothing+// changed. The mask_* commands wrap them with an undo step.+#pragma once++#include "core/Mesh.h"++#include <cstdint>++namespace sf {++class CommandRegistry;++bool maskClear(Mesh& mesh);+bool maskAll(Mesh& mesh);+bool maskInvert(Mesh& mesh);+// Averages each value with its neighbours `iterations` times (softens edges).+bool maskBlur(Mesh& mesh, int iterations);+// Pushes values towards 0 or 1 and tightens soft edges (inverse of blur).+bool maskSharpen(Mesh& mesh, int iterations);+// Grows / shrinks the masked region by one edge ring per iteration.+bool maskGrow(Mesh& mesh, int iterations);+bool maskShrink(Mesh& mesh, int iterations);++// Per-vertex concavity: the offset of the neighbour average along the normal,+// relative to the mean edge length. > 0 in cavities, < 0 on convex areas, ~0 flat.+float vertexConcavity(const Mesh& mesh, uint32_t v);+// Masks concave areas: vertices whose concavity exceeds `threshold` get up to+// `strength` (0-1), with a soft ramp above the threshold. Replaces the mask.+bool maskByCavity(Mesh& mesh, float strength, float threshold);+// Masks every vertex touching a visible triangle of polygroup `group`.+// With `add` the existing mask is kept, otherwise it is replaced.+bool maskByPolygroup(Mesh& mesh, uint32_t group, bool add);++// Registers mask_clear, mask_all, mask_invert, mask_blur, mask_sharpen,+// mask_grow, mask_shrink, mask_by_cavity and mask_by_polygroup.+void registerMaskingCommands(CommandRegistry& registry);++} // namespace sfdiff --git a/src/core/Sculpt.h b/src/core/Sculpt.hindex 2aa1f97c..ee1b7496 100644--- a/src/core/Sculpt.h+++ b/src/core/Sculpt.h@@ -97,6 +97,12 @@ private:std::vector<float> weights_;std::vector<GrabEntry> grab_;std::vector<uint32_t> grabVerts_;++public:+ // Mask brush (Ctrl in the app; defined in Masking.cpp): raises the mask+ // under the brush towards 1, or lowers it towards 0 when p.invert is set.+ // Ignores the existing mask (it edits it) but skips hidden vertices.+ void dabMask(Mesh& mesh, const BVH& bvh, const DabParams& p, Symmetry sym);};} // namespace sfdiff --git a/tests/test_masking.cpp b/tests/test_masking.cppnew file mode 100644index 00000000..5798753f--- /dev/null+++ b/tests/test_masking.cpp@@ -0,0 +1,268 @@+// SculptForge - open source digital sculpting+// SPDX-License-Identifier: GPL-3.0-or-later+//+// Masking: mask strokes (symmetry, erase, undo), the mask_* commands and+// brushes honouring a painted mask.+#include "TestHarness.h"++#include "core/Commands.h"+#include "core/Masking.h"+#include "core/Primitives.h"+#include "core/Sculpt.h"++#include <algorithm>+#include <cmath>++using namespace sf;++namespace {++const CommandRegistry& registry() {+ static CommandRegistry r;+ return r;+}++size_t countMasked(const Mesh& m, float above = 0.5f) {+ if (!m.hasMask()) return 0;+ return size_t(std::count_if(m.mask.begin(), m.mask.end(), [&](float x) { return x > above; }));+}++// Mask = 1 on vertices with x > `edge`, 0 elsewhere.+void maskHalf(Mesh& m, float edge = 0.0f) {+ m.ensureMask();+ for (uint32_t v = 0; v < m.vertexCount(); ++v) m.mask[v] = m.positions[v].x > edge ? 1.0f : 0.0f;+}++void maskStroke(Document& d, const glm::vec3& center, float radius, bool erase, Symmetry sym, float strength = 1.0f) {+ DabParams p;+ p.center = center;+ p.viewDir = -glm::normalize(center);+ p.radius = radius;+ p.strength = strength;+ p.invert = erase;+ CHECK(d.sculptor.beginStroke(d.mesh, erase ? "Unmask" : "Mask"));+ for (int i = 0; i < 3; ++i) d.sculptor.dabMask(d.mesh, d.bvh, p, sym);+ UndoRecord r = d.sculptor.endStroke();+ if (!r.empty()) d.undo.push(std::move(r));+}++} // namespace++TEST(mask_stroke_paints_with_symmetry_and_undoes) {+ Document d = makeDoc(makeIcosphere(4));+ const std::vector<glm::vec3> before = d.mesh.positions;+ maskStroke(d, glm::vec3(0.7f, 0.0f, 0.714f), 0.3f, false, Symmetry{true, false, false});+ CHECK(d.mesh.hasMask());+ CHECK(d.mesh.positions == before); // masking never moves vertices+ bool right = false, left = false, farAway = true;+ for (uint32_t v = 0; v < d.mesh.vertexCount(); ++v) {+ const glm::vec3& x = d.mesh.positions[v];+ if (glm::distance(x, glm::vec3(0.7f, 0.0f, 0.714f)) < 0.05f) right |= d.mesh.mask[v] > 0.9f;+ if (glm::distance(x, glm::vec3(-0.7f, 0.0f, 0.714f)) < 0.05f) left |= d.mesh.mask[v] > 0.9f;+ if (x.z < -0.2f) farAway &= d.mesh.mask[v] == 0.0f;+ }+ CHECK(right && left && farAway);+ const std::vector<float> painted = d.mesh.mask;++ CHECK(d.undo.undo(d.mesh, d.bvh));+ CHECK(countMasked(d.mesh, 0.0f) == 0);+ CHECK(d.undo.redo(d.mesh, d.bvh));+ CHECK(d.mesh.mask == painted);++ // Erasing (Ctrl+Alt) on one side only, without symmetry.+ maskStroke(d, glm::vec3(0.7f, 0.0f, 0.714f), 0.3f, true, Symmetry{false, false, false});+ bool rightErased = true, leftKept = false;+ for (uint32_t v = 0; v < d.mesh.vertexCount(); ++v) {+ const glm::vec3& x = d.mesh.positions[v];+ if (glm::distance(x, glm::vec3(0.7f, 0.0f, 0.714f)) < 0.05f) rightErased &= d.mesh.mask[v] < 0.1f;+ if (glm::distance(x, glm::vec3(-0.7f, 0.0f, 0.714f)) < 0.05f) leftKept |= d.mesh.mask[v] > 0.9f;+ }+ CHECK(rightErased && leftKept);+ CHECK(d.undo.undo(d.mesh, d.bvh));+ CHECK(d.mesh.mask == painted);+}++TEST(mask_stroke_soft_strength_and_hidden) {+ Document d = makeDoc(makeIcosphere(4));+ maskStroke(d, glm::vec3(0, 0, 1), 0.4f, false, Symmetry{false, false, false}, 0.2f);+ const float peak = *std::max_element(d.mesh.mask.begin(), d.mesh.mask.end());+ CHECK(peak > 0.2f && peak < 0.9f); // low strength builds up gradually++ // Hidden triangles' vertices are never masked.+ Document h = makeDoc(makeIcosphere(4));+ h.mesh.ensureHidden();+ for (uint32_t t = 0; t < h.mesh.triangleCount(); ++t) {+ const auto& tri = h.mesh.triangles[t];+ h.mesh.hidden[t] = uint8_t((h.mesh.positions[tri.x].x + h.mesh.positions[tri.y].x + h.mesh.positions[tri.z].x) > 0.0f);+ }+ h.bvh.build(h.mesh);+ maskStroke(h, glm::vec3(0, 0, 1), 0.5f, false, Symmetry{false, false, false});+ bool hiddenUntouched = true, visiblePainted = false;+ for (uint32_t v = 0; v < h.mesh.vertexCount(); ++v) {+ if (h.mesh.vertexHidden(v)) hiddenUntouched &= h.mesh.maskAt(v) == 0.0f;+ else visiblePainted |= h.mesh.maskAt(v) > 0.5f;+ }+ CHECK(hiddenUntouched && visiblePainted);+}++TEST(painted_mask_protects_from_brushes) {+ Document d = makeDoc(makeIcosphere(4));+ maskStroke(d, glm::vec3(0, 0, 1), 0.5f, false, Symmetry{false, false, false});+ CHECK(registry().execute(d, "mask_sharpen", {{"iterations", 10.0}}).ok); // soft edge -> exactly 0 or 1+ const std::vector<glm::vec3> before = d.mesh.positions;+ DabParams p;+ p.center = glm::vec3(0, 0, 1);+ p.radius = 0.9f;+ p.strength = 1.0f;+ for (BrushType type : {BrushType::Standard, BrushType::Clay, BrushType::Inflate, BrushType::Smooth}) {+ d.sculptor.beginStroke(d.mesh, "Sculpt");+ for (int i = 0; i < 3; ++i) d.sculptor.dab(d.mesh, d.bvh, type, p, Symmetry{false, false, false});+ d.undo.push(d.sculptor.endStroke());+ }+ bool maskedStill = true, freeMoved = false;+ for (uint32_t v = 0; v < d.mesh.vertexCount(); ++v) {+ if (d.mesh.mask[v] >= 1.0f) maskedStill &= d.mesh.positions[v] == before[v];+ else if (d.mesh.mask[v] == 0.0f) freeMoved |= d.mesh.positions[v] != before[v];+ }+ CHECK(countMasked(d.mesh, 0.999f) > 0);+ CHECK(maskedStill && freeMoved);+}++TEST(mask_commands_registered) {+ const std::string schema = registry().toolSchemaJson();+ for (const char* name : {"mask_clear", "mask_all", "mask_invert", "mask_blur", "mask_sharpen", "mask_grow",+ "mask_shrink", "mask_by_cavity", "mask_by_polygroup"}) {+ CHECK(registry().find(name) != nullptr);+ CHECK(schema.find(std::string("\"") + name + "\"") != std::string::npos);+ }+}++TEST(mask_all_invert_clear_undo) {+ Document d = makeDoc(makeIcosphere(3));+ const size_t n = d.mesh.vertexCount();+ CHECK(registry().execute(d, "mask_all").ok);+ CHECK(countMasked(d.mesh) == n);+ CHECK(d.modified);+ CHECK(registry().execute(d, "mask_invert").ok);+ CHECK(countMasked(d.mesh, 0.0f) == 0);+ CHECK(registry().execute(d, "mask_invert").ok);+ CHECK(countMasked(d.mesh) == n);+ CHECK(registry().execute(d, "mask_clear").ok);+ CHECK(!d.mesh.hasMask()); // clearing frees the attribute+ CHECK(registry().execute(d, "undo").ok);+ CHECK(countMasked(d.mesh) == n);+ CHECK(registry().execute(d, "undo").ok);+ CHECK(countMasked(d.mesh, 0.0f) == 0);+ CHECK(registry().execute(d, "redo").ok);+ CHECK(countMasked(d.mesh) == n);++ // A no-op adds no undo step.+ Document e = makeDoc(makeIcosphere(2));+ CHECK(registry().execute(e, "mask_clear").ok);+ CHECK(!e.undo.canUndo());++ // Invert of a plain mesh masks everything (Ctrl+click on the background).+ CHECK(registry().execute(e, "mask_invert").ok);+ CHECK(countMasked(e.mesh) == e.mesh.vertexCount());++ // Hidden vertices keep their mask through invert / all.+ Document h = makeDoc(makeIcosphere(3));+ h.mesh.ensureHidden();+ for (uint32_t t = 0; t < h.mesh.triangleCount(); ++t) h.mesh.hidden[t] = uint8_t(h.mesh.positions[h.mesh.triangles[t].x].y > 0.5f);+ CHECK(registry().execute(h, "mask_invert").ok);+ bool ok = true;+ for (uint32_t v = 0; v < h.mesh.vertexCount(); ++v) ok &= h.mesh.mask[v] == (h.mesh.vertexHidden(v) ? 0.0f : 1.0f);+ CHECK(ok);+}++TEST(mask_blur_sharpen_grow_shrink) {+ Document d = makeDoc(makeIcosphere(4));+ maskHalf(d.mesh);+ const size_t masked = countMasked(d.mesh);+ const std::vector<float> original = d.mesh.mask;++ // Blur creates intermediate values along the edge but keeps the overall balance.+ CHECK(registry().execute(d, "mask_blur", {{"iterations", 3.0}}).ok);+ const size_t soft = size_t(std::count_if(d.mesh.mask.begin(), d.mesh.mask.end(), [](float m) { return m > 0.05f && m < 0.95f; }));+ CHECK(soft > 0);+ CHECK(std::all_of(d.mesh.mask.begin(), d.mesh.mask.end(), [](float m) { return m >= 0.0f && m <= 1.0f; }));+ // Sharpen pushes them back towards 0/1.+ CHECK(registry().execute(d, "mask_sharpen", {{"iterations", 6.0}}).ok);+ const size_t softAfter = size_t(std::count_if(d.mesh.mask.begin(), d.mesh.mask.end(), [](float m) { return m > 0.05f && m < 0.95f; }));+ CHECK(softAfter < soft);+ CHECK(registry().execute(d, "undo").ok);+ CHECK(registry().execute(d, "undo").ok);+ CHECK(d.mesh.mask == original);++ CHECK(registry().execute(d, "mask_grow", {{"iterations", 2.0}}).ok);+ const size_t grown = countMasked(d.mesh);+ CHECK(grown > masked);+ CHECK(registry().execute(d, "mask_shrink", {{"iterations", 4.0}}).ok);+ CHECK(countMasked(d.mesh) < masked);+ CHECK(registry().execute(d, "undo").ok);+ CHECK(countMasked(d.mesh) == grown);++ // Shrink of a single masked vertex removes it; grow of an empty mask does nothing.+ Document e = makeDoc(makeIcosphere(2));+ e.mesh.ensureMask();+ e.mesh.mask[0] = 1.0f;+ CHECK(maskShrink(e.mesh, 1));+ CHECK(countMasked(e.mesh, 0.0f) == 0);+ CHECK(!maskGrow(e.mesh, 3));+}++TEST(mask_by_cavity_finds_creases) {+ // A sphere with a band pushed inwards: the rim of the band is concave.+ Mesh m = makeIcosphere(5);+ for (glm::vec3& p : m.positions)+ if (std::abs(p.y) < 0.3f) p *= 0.85f;+ m.recomputeAllNormals();+ Document d = makeDoc(std::move(m));+ CHECK(registry().execute(d, "mask_by_cavity", {{"strength", 1.0}, {"threshold", 0.02}}).ok);+ bool convexFree = true, rimMasked = false;+ for (uint32_t v = 0; v < d.mesh.vertexCount(); ++v) {+ const float y = std::abs(d.mesh.positions[v].y);+ const float r = glm::length(d.mesh.positions[v]);+ if (y > 0.6f) convexFree &= d.mesh.mask[v] == 0.0f; // smooth convex caps+ if (r < 0.9f && y > 0.12f) rimMasked |= d.mesh.mask[v] > 0.5f; // bottom of the step at the band's edge+ }+ CHECK(convexFree && rimMasked);++ // Strength scales the result; a huge threshold masks nothing.+ CHECK(registry().execute(d, "mask_by_cavity", {{"strength", 0.4}}).ok);+ CHECK(*std::max_element(d.mesh.mask.begin(), d.mesh.mask.end()) <= 0.4f + 1e-6f);+ CHECK(registry().execute(d, "mask_by_cavity", {{"threshold", 1.0}}).ok);+ CHECK(countMasked(d.mesh, 0.0f) == 0);+ CHECK(registry().execute(d, "undo").ok);+ CHECK(countMasked(d.mesh, 0.0f) > 0);+}++TEST(mask_by_polygroup) {+ Document d = makeDoc(makeIcosphere(3));+ Mesh& m = d.mesh;+ m.ensurePolygroups();+ for (uint32_t t = 0; t < m.triangleCount(); ++t) {+ const auto& tri = m.triangles[t];+ m.polygroups[t] = (m.positions[tri.x].z + m.positions[tri.y].z + m.positions[tri.z].z) > 0.0f ? 2u : 0u;+ }+ CHECK(registry().execute(d, "mask_by_polygroup", {{"index", 2.0}}).ok);+ bool ok = true;+ for (uint32_t v = 0; v < m.vertexCount(); ++v) {+ if (m.positions[v].z > 0.2f) ok &= m.mask[v] == 1.0f;+ if (m.positions[v].z < -0.2f) ok &= m.mask[v] == 0.0f;+ }+ CHECK(ok);+ // Replace vs add.+ CHECK(registry().execute(d, "mask_by_polygroup", {{"index", 0.0}}).ok);+ bool replaced = true;+ for (uint32_t v = 0; v < m.vertexCount(); ++v)+ if (m.positions[v].z > 0.2f) replaced &= m.mask[v] == 0.0f;+ CHECK(replaced);+ CHECK(registry().execute(d, "mask_by_polygroup", {{"index", 2.0}, {"add", true}}).ok);+ CHECK(countMasked(m) == m.vertexCount());+ CHECK(!registry().execute(d, "mask_by_polygroup", {}).ok); // index is required+ CHECK(registry().execute(d, "undo").ok);+ CHECK(registry().execute(d, "undo").ok);+ CHECK(registry().execute(d, "undo").ok);+ CHECK(countMasked(m, 0.0f) == 0);+}