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
// SculptForge - open source digital sculpting
// SPDX-License-Identifier: GPL-3.0-or-later
//
// #155: the Stencil (core/Stencil.h): an image over the view the brushes work through. Its placement maps the right
// texel when turned and scaled, nothing happens off it (unless tiled), and the sculpt brushes, Vertex Paint and the
// symmetry copies take it at the place each vertex shows on screen.
#include "TestHarness.h"
#include "core/Commands.h"
#include "core/Primitives.h"
#include "core/Stencil.h"
#include "core/VertexPaint.h"
#include <glm/gtc/matrix_transform.hpp>
#include <cmath>
#include <tuple>
using namespace sf;
namespace {
bool near(float a, float b, float eps = 1e-4f) { return std::abs(a - b) <= eps; }
// w x h pixels, all black and opaque, with `white` (x, y) pixels white.
Image blackImage(int w, int h, std::initializer_list<glm::ivec2> white = {}) {
Image img;
img.width = w;
img.height = h;
img.rgba.assign(size_t(w) * size_t(h) * 4, 0);
for (size_t i = 3; i < img.rgba.size(); i += 4) img.rgba[i] = 255;
for (glm::ivec2 p : white)
for (int k = 0; k < 3; ++k) img.rgba[(size_t(p.y) * size_t(w) + size_t(p.x)) * 4 + size_t(k)] = 255;
return img;
}
// Looking straight down at makePlane (the XZ plane), orthographic: x runs across the canvas, z down it.
glm::mat4 topView() {
return glm::ortho(-1.0f, 1.0f, -1.0f, 1.0f, 0.1f, 10.0f) * glm::lookAt(glm::vec3(0, 5, 0), glm::vec3(0.0f), glm::vec3(0, 0, -1));
}
DabParams topDab(const glm::vec3& center, float radius) {
DabParams p;
p.center = center;
p.viewDir = glm::vec3(0, -1, 0);
p.radius = radius;
p.strength = 1.0f;
return p;
}
float maxRise(const Mesh& m, bool left) {
float best = 0.0f;
for (const glm::vec3& v : m.positions)
if ((v.x < -0.02f) == left && (v.x > 0.02f) == !left) best = std::max(best, std::abs(v.y));
return best;
}
} // namespace
TEST(stencil_turned_scaled_maps_the_right_texel) {
Stencil st;
st.set(blackImage(2, 2, {{0, 0}}), "corner", ""); // the top-left pixel white
st.center = {0.5f, 0.5f};
st.size = 0.5f;
st.angle = glm::radians(90.0f); // counter-clockwise: the image's top goes to the left
const float aspect = 2.0f; // a canvas twice as wide as it is tall
// Round trip at a few points, turned and not.
for (float a : {0.0f, 30.0f, 90.0f, -135.0f}) {
st.angle = glm::radians(a);
for (glm::vec2 uv : {glm::vec2(0.1f, 0.2f), glm::vec2(0.5f), glm::vec2(0.9f, 0.7f)}) {
glm::vec2 back;
CHECK(st.imageCoord(st.canvasPoint(uv, aspect), aspect, back));
CHECK(near(back.x, uv.x) && near(back.y, uv.y));
}
}
st.angle = glm::radians(90.0f);
const glm::vec2 top = st.canvasPoint({0.5f, 0.0f}, aspect);
CHECK(near(top.x, 0.5f - 0.25f / aspect) && near(top.y, 0.5f)); // the top edge's middle: left of the centre
// The white top-left pixel lands below-left of the centre (top -> left, left -> bottom), the rest is black.
const glm::vec2 white = st.canvasPoint({0.25f, 0.25f}, aspect);
CHECK(white.x < 0.5f && white.y > 0.5f);
glm::vec2 uv;
CHECK(st.imageCoord(white, aspect, uv) && near(st.value(uv), 1.0f));
CHECK(st.imageCoord(glm::vec2(0.5f + (0.5f - white.x), white.y), aspect, uv) && near(st.value(uv), 0.0f));
// Twice the size: the same canvas point is nearer the centre of the image.
st.size = 1.0f;
CHECK(st.imageCoord(white, aspect, uv) && near(uv.x, 0.375f) && near(uv.y, 0.375f));
// Invert: the negative.
st.size = 0.5f;
st.invert = true;
CHECK(st.imageCoord(white, aspect, uv) && near(st.value(uv), 0.0f));
}
TEST(stencil_outside_is_no_effect_unless_tiled) {
Stencil st;
st.set(blackImage(4, 4, {{0, 0}, {1, 0}, {2, 0}, {3, 0}, {0, 1}, {1, 1}, {2, 1}, {3, 1}}), "top", ""); // top half white
st.size = 0.2f;
glm::vec2 uv;
CHECK(!st.imageCoord({0.9f, 0.9f}, 1.0f, uv));
StencilView view{&st, topView(), 1.0f};
CHECK(view.weight(glm::vec3(0.0f, 0.0f, -0.05f)) > 0.99f); // on the image's top half
CHECK(view.weight(glm::vec3(0.0f, 0.0f, 0.05f)) < 0.01f); // its bottom half
CHECK(view.weight(glm::vec3(0.8f, 0.0f, 0.8f)) == 0.0f); // off the image
st.tile = true; // repeats: one image height (0.2 of the canvas = 0.4 world) further down is the top half again
CHECK(st.imageCoord({0.9f, 0.9f}, 1.0f, uv));
CHECK(view.weight(glm::vec3(0.0f, 0.0f, -0.05f + 0.4f)) > 0.99f);
st.visible = false;
CHECK(!view.active());
// Behind a perspective camera: nothing (in front, the same line of sight takes it).
st.visible = true;
st.tile = false;
const StencilView persp{&st, glm::perspective(glm::radians(50.0f), 1.0f, 0.1f, 100.0f) *
glm::lookAt(glm::vec3(0, 5, 0), glm::vec3(0.0f), glm::vec3(0, 0, -1)), 1.0f};
CHECK(persp.weight(glm::vec3(0.0f, 0.0f, -0.2f)) > 0.99f);
CHECK(persp.weight(glm::vec3(0.0f, 20.0f, -0.2f)) == 0.0f);
}
TEST(stencil_sculpts_only_under_the_image) {
Document doc = makeDoc(makePlane(80));
Mesh& m = doc.mesh;
// A white image whose right edge sits on the canvas centre: the brush's left half is under it.
Stencil st;
st.set(blackImage(1, 1, {{0, 0}}), "white", "");
st.size = 0.6f;
st.center = {0.5f - 0.3f, 0.5f};
DabParams p = topDab(glm::vec3(0.0f), 0.4f);
p.stencil = {&st, topView(), 1.0f};
CHECK(doc.sculptor.beginStroke(m, "Standard"));
for (int i = 0; i < 4; ++i) doc.sculptor.dab(m, doc.bvh, BrushType::Standard, p, Symmetry{false, false, false});
doc.sculptor.endStroke();
CHECK(maxRise(m, true) > 0.01f);
CHECK(maxRise(m, false) == 0.0f);
// Without the stencil the same dab raises both sides.
Document plain = makeDoc(makePlane(80));
DabParams q = topDab(glm::vec3(0.0f), 0.4f);
CHECK(plain.sculptor.beginStroke(plain.mesh, "Standard"));
plain.sculptor.dab(plain.mesh, plain.bvh, BrushType::Standard, q, Symmetry{false, false, false});
plain.sculptor.endStroke();
CHECK(maxRise(plain.mesh, true) > 0.0f && maxRise(plain.mesh, false) > 0.0f);
}
TEST(stencil_symmetry_mirrors_the_pattern) {
// The image covers only the right of the canvas; a dab there with X symmetry also raises its mirror on the left,
// which takes the stencil at its mirror image's place (the right), so the pattern mirrors across.
Document doc = makeDoc(makePlane(80));
Mesh& m = doc.mesh;
Stencil st;
st.set(blackImage(1, 1, {{0, 0}}), "white", "");
st.size = 0.4f;
st.center = {0.75f, 0.5f};
DabParams p = topDab(glm::vec3(0.5f, 0.0f, 0.0f), 0.25f);
p.stencil = {&st, topView(), 1.0f};
CHECK(doc.sculptor.beginStroke(m, "Standard"));
doc.sculptor.dab(m, doc.bvh, BrushType::Standard, p, Symmetry{true, false, false});
doc.sculptor.endStroke();
CHECK(maxRise(m, false) > 0.0f);
CHECK(near(maxRise(m, true), maxRise(m, false), 1e-5f));
}
TEST(stencil_vertex_paint_lays_its_colours) {
Document doc = makeDoc(makePlane(40));
Mesh& m = doc.mesh;
Image red = blackImage(1, 1);
red.rgba[0] = 255;
Stencil st;
st.set(red, "red", "");
st.size = 2.0f; // covers the whole view
DabParams p = topDab(glm::vec3(0.0f), 0.5f);
p.stencil = {&st, topView(), 1.0f};
CHECK(doc.sculptor.beginStroke(m, "Paint"));
CHECK(paintDab(doc.sculptor, m, doc.bvh, p, glm::vec3(0, 0, 1), Symmetry{false, false, false}) > 0);
const uint32_t centre = uint32_t(m.vertexCount() / 2);
CHECK(m.colors[centre].x > 0.99f && m.colors[centre].z < 0.01f); // red, not the blue paint colour
doc.sculptor.endStroke();
// Colours off: its brightness masks the paint colour; a black stencil (red's luminance is low) paints little.
st.set(blackImage(1, 1), "black", "");
st.colors = false;
Document doc2 = makeDoc(makePlane(40));
CHECK(doc2.sculptor.beginStroke(doc2.mesh, "Paint"));
CHECK(paintDab(doc2.sculptor, doc2.mesh, doc2.bvh, p, glm::vec3(0, 0, 1), Symmetry{false, false, false}) == 0);
doc2.sculptor.endStroke();
}
TEST(stencil_commands) {
Document doc = makeDoc(makePlane(4));
CommandRegistry reg;
CHECK(!reg.execute(doc, "stencil_load", {}).ok);
CHECK(!reg.execute(doc, "stencil_load", {{"alpha", true}}).ok); // Round: no alpha
CHECK(reg.execute(doc, "brush_set_alpha", {{"name", "cracks"}}).ok);
CHECK(reg.execute(doc, "stencil_load", {{"alpha", true}, {"reset", true}}).ok);
CHECK(doc.stencil.active() && doc.stencil.name == "Cracks");
CHECK(doc.stencil.image->width == 1024); // a built-in pattern made again at the Stencil's size (the alpha's is 128)
CHECK(doc.brushAlpha.width == 128);
CHECK(reg.execute(doc, "stencil_set", {{"x", 0.25}, {"angle", 450.0}, {"size", 100.0}, {"opacity", 2.0}, {"tile", true}}).ok);
CHECK(near(doc.stencil.center.x, 0.25f) && near(glm::degrees(doc.stencil.angle), 90.0f, 1e-3f));
CHECK(doc.stencil.size == 20.0f && doc.stencil.opacity == 1.0f && doc.stencil.tile);
CHECK(reg.execute(doc, "stencil_set", {{"visible", false}}).ok && !doc.stencil.active());
CHECK(reg.execute(doc, "stencil_clear", {}).ok && !doc.stencil.image);
CHECK(!reg.execute(doc, "stencil_load", {{"path", "/nonexistent/stencil.png"}}).ok);
}
namespace {
// A straight groove across the view at `angleDeg`, its profile as the Cobblestone pattern's (sqrt of a smoothstep:
// steep at the floor), `halfWidth` canvas heights; w x w pixels.
Image grooveImage(int w, float angleDeg, float halfWidth) {
Image img = blackImage(w, w);
const glm::vec2 dir(std::cos(glm::radians(angleDeg)), std::sin(glm::radians(angleDeg)));
for (int y = 0; y < w; ++y)
for (int x = 0; x < w; ++x) {
const glm::vec2 p((x + 0.5f) / w - 0.5f, (y + 0.5f) / w - 0.5f);
const float d = std::abs(p.x * dir.y - p.y * dir.x); // distance from the line through the centre
float t = std::clamp(d / halfWidth, 0.0f, 1.0f);
t = t * t * (3.0f - 2.0f * t);
const uint8_t g = uint8_t(std::lround(std::sqrt(t) * 255.0f));
for (int k = 0; k < 3; ++k) img.rgba[(size_t(y) * size_t(w) + size_t(x)) * 4 + size_t(k)] = g;
}
return img;
}
// Sculpts Standard dabs along the groove of `st` (laid over topView, the plane 2 x 2 world = the canvas), and returns
// the roughness along it: vertices binned by their distance from the groove line, the p99 of how far each is from its
// bin's mean height, over the groove's depth. A clean groove's height depends on the distance alone (0); beads along
// it don't.
float grooveRoughness(const Stencil& st, float angleDeg, int resolution) {
Document doc = makeDoc(makePlane(resolution));
Mesh& m = doc.mesh;
// The groove on the plane: canvas y runs along +z (topView), so the image's (x, y) is the world's (x, z).
const glm::vec3 along(std::cos(glm::radians(angleDeg)), 0.0f, std::sin(glm::radians(angleDeg)));
CHECK(doc.sculptor.beginStroke(m, "Standard"));
for (float s = -0.6f; s <= 0.6f; s += 0.01f) {
DabParams p = topDab(along * s, 0.25f);
p.strength = 0.3f;
p.stencil = {&st, topView(), 1.0f};
doc.sculptor.dab(m, doc.bvh, BrushType::Standard, p, Symmetry{false, false, false});
}
doc.sculptor.endStroke();
const glm::vec3 across = glm::cross(along, glm::vec3(0, 1, 0));
// Each bin's heights against a straight line through them (height by distance), so a steep wall inside one bin
// isn't counted as roughness; what is left is how the height wanders along the groove.
constexpr int kBins = 60;
constexpr float kReach = 0.15f; // world units each side of the groove line
struct Fit { double n = 0, x = 0, y = 0, xx = 0, xy = 0; };
std::vector<Fit> fit(kBins);
std::vector<std::tuple<int, float, float>> samples; // bin, distance, height
float lo = 1e9f, hi = -1e9f;
for (const glm::vec3& v : m.positions) {
if (std::abs(glm::dot(v, along)) > 0.3f) continue; // the stroke's even middle
const float d = std::abs(glm::dot(v, across));
if (d >= kReach) continue;
const int b = std::min(int(d / kReach * kBins), kBins - 1);
Fit& f = fit[size_t(b)];
f.n += 1; f.x += d; f.y += v.y; f.xx += double(d) * d; f.xy += double(d) * v.y;
samples.emplace_back(b, d, v.y);
lo = std::min(lo, v.y);
hi = std::max(hi, v.y);
}
std::vector<float> dev;
for (auto [b, d, y] : samples) {
const Fit& f = fit[size_t(b)];
const double den = f.n * f.xx - f.x * f.x;
const double k = std::abs(den) > 1e-18 ? (f.n * f.xy - f.x * f.y) / den : 0.0;
const double c = (f.y - k * f.x) / f.n;
dev.push_back(float(std::abs(y - (c + k * d))));
}
std::sort(dev.begin(), dev.end());
const float depth = std::max(hi - lo, 1e-9f);
return dev.empty() ? 1.0f : dev[size_t(double(dev.size() - 1) * 0.99)] / depth;
}
} // namespace
TEST(stencil_groove_walls_are_smooth_along_the_groove) {
// A Cobblestone-like groove, 30 degrees across the plane's grid, about three vertices wide each side: its walls
// and floor must follow the groove, not bead along the triangles (#155, the 0.11.11 What's New shots).
const float angle = 30.0f;
Stencil st;
st.set(grooveImage(1024, angle, 0.02f), "groove", "");
st.size = 1.0f;
const float r = grooveRoughness(st, angle, 160);
CHECK(r < 0.01f);
// The cause in 0.11.11: the pattern at the alpha's 128 px, its pixels stair-stepping along the groove.
Stencil coarse;
coarse.set(grooveImage(128, angle, 0.02f), "groove", "");
coarse.size = 1.0f;
CHECK(grooveRoughness(coarse, angle, 160) > 2.0f * r);
}
TEST(stencil_fine_image_on_a_light_mesh_sculpts_evenly) {
// A 2048 px one-pixel checker over the view: each vertex of a light mesh is many pixels from the next, so read
// point by point it got whatever pixel it landed on (noise that shimmers as the stencil moves); averaged over the
// vertices' spacing it is an even grey, so the stroke raises an even plateau.
Image checker = blackImage(2048, 2048);
for (int y = 0; y < 2048; ++y)
for (int x = 0; x < 2048; ++x)
if ((x + y) % 2 == 0)
for (int k = 0; k < 3; ++k) checker.rgba[(size_t(y) * 2048 + size_t(x)) * 4 + size_t(k)] = 255;
Stencil st;
st.set(checker, "checker", "");
CHECK(st.mips && st.mips->size() == 2); // 1024, 512 (no coarser: their square pixels would stair-step edges)
st.size = 1.0f;
// The plateau's unevenness (sd / mean of the heights along the stroke's middle), with and without the stencil:
// the stencil may add next to nothing to what the stroke itself leaves on the grid.
auto unevenness = [&](int res, const Stencil* with) {
Document doc = makeDoc(makePlane(res));
Mesh& m = doc.mesh;
CHECK(doc.sculptor.beginStroke(m, "Standard"));
for (float s = -0.5f; s <= 0.5f; s += 0.02f) {
DabParams p = topDab(glm::vec3(s, 0, 0), 0.3f);
p.strength = 0.3f;
if (with) p.stencil = {with, topView(), 1.0f};
doc.sculptor.dab(m, doc.bvh, BrushType::Standard, p, Symmetry{false, false, false});
}
doc.sculptor.endStroke();
double sum = 0, sq = 0, n = 0;
for (const glm::vec3& v : m.positions)
if (std::abs(v.x) < 0.3f && std::abs(v.z) < 0.05f) {
sum += v.y;
sq += double(v.y) * v.y;
n += 1;
}
const double mean = sum / n;
return mean > 0.0 ? std::sqrt(std::max(0.0, sq / n - mean * mean)) / mean : 1.0;
};
for (int res : {40, 160}) {
const double plain = unevenness(res, nullptr), stencilled = unevenness(res, &st);
std::printf(" %d cells: plateau sd / mean %.4f (no stencil %.4f)\n", res, stencilled, plain);
CHECK(stencilled < plain + 0.01); // (point by point: 0.065 at 40 cells, 0.17 at 160)
}
}