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.

Masking: Ctrl mask strokes and mask_* commands

islandmedbee9890de0ef
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 4e439795..6d3ff221 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -41,6 +41,7 @@ add_library(sculptforge_core STATIC
src/core/Splats.cpp
src/core/Voxel.cpp
src/core/EnginePresets.cpp
+ src/core/Masking.cpp
src/io/ObjIO.cpp
src/io/FbxIO.cpp
third_party/ufbx/ufbx.c
@@ -103,6 +104,7 @@ if(SCULPTFORGE_BUILD_APP)
src/app/main.cpp
src/app/App.cpp
src/app/Demo.cpp
+ src/app/PanelMasking.cpp
src/render/GL.cpp
src/render/Camera.cpp
src/render/Renderer.cpp
diff --git a/src/app/App.cpp b/src/app/App.cpp
index 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.h
index 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 sf
diff --git a/src/app/PanelMasking.cpp b/src/app/PanelMasking.cpp
new file mode 100644
index 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 sf
diff --git a/src/core/Commands.cpp b/src/core/Commands.cpp
index 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.cpp
new file mode 100644
index 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 = [&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_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 sf
diff --git a/src/core/Masking.h b/src/core/Masking.h
new file mode 100644
index 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 sf
diff --git a/src/core/Sculpt.h b/src/core/Sculpt.h
index 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 sf
diff --git a/tests/test_masking.cpp b/tests/test_masking.cpp
new file mode 100644
index 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);
+}