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.
Stencil (#155)
Ask (@kenttumanda123-netizen): a reference image over the viewport that you move, turn, scale and fade, then sculpt or paint through it: its detail goes onto the model as displacement (sculpt brushes) or colour (Vertex Paint); move it and repeat. Roadmap item "stencils" (welcome.md). Our name: Stencil.
Model
- Screen space. The stencil is an image placed on the canvas, not on the model: the model turns under it. Its
placement is kept in canvas fractions (centre 0..1 across and down, size = its height / the canvas height, angle
counter-clockwise as seen), so it stays put when the window changes size.
core/Stencil.h, state onDocument(doc.stencil), not saved with the project (a session tool, like the brush cursor). - Sampling. Each dab carries a
StencilView(the stencil, the dab's view-projection and canvas aspect). A vertex is projected to the canvas, turned back by the stencil's placement into image coordinates and sampled bilinearly. Sculpt brushes multiply their falloff (or alpha) by the image's brightness x its alpha; outside the image (unless Tile) the weight is 0, so nothing moves. Behind the camera: 0. - Vertex Paint lays the image's own colours (alpha = coverage), or with Paint its colours off its brightness
masks the paint colour. Texture painting doesn't take it yet (follow-up: the same weight in
Texture.cpp). - Invert uses the negative; Opacity only changes how strongly the overlay shows (the brushes always take the whole image: a faint stencil shouldn't sculpt faintly without saying so; Intensity does that).
- Symmetry: yes, mirrored. A symmetry copy's vertex takes the stencil at its mirror image's place on screen
(
SymCopy::inversePointbefore projecting), so the pattern mirrors across: a face stencilled on the right shows on the left mirrored, as the stroke itself is. (Sampling the mirror's own screen position would put a different part of the image there, or nothing.) - Which brushes. Every brush that takes an alpha: the built-in sculpt brushes (
Sculptor::dabSingle), custom brushes (dabRecipeSingle), Vertex Paint (paintDab). Not Move, the Kelvinlet brushes, Vector Displacement or the mask brush (they don't take alphas either). A stencilled dab takes the exact path (no scale-adaptive dabs, no fused batches, no micro base dabs), as an alpha does. - Micro levels: through the grid kernel's per-point pattern hook (
MicroStroke::dab'stexture), as recipe patterns are; big brushes evaluate it on the coarse points the way they do an alpha.
Image
The same loader as alphas (Image::load; no new parser or dependency), kept up to 2048 px on its longer side (a
stencil spans the view; an alpha's 512 is too coarse). Use alpha makes the brush's current alpha the stencil: a
Library or image alpha is read again from its file at full size, a built-in pattern as generated.
UI
Alpha palette > Stencil: Load image..., Use alpha, Remove; Show, Adjust, Invert, Tile, Paint its colours, Hide
while navigating; Opacity, Size, Angle; Reset placement. Commands stencil_load, stencil_set, stencil_clear
(scripts, tests, the AI). Actions in the command palette: Load Stencil..., Show Stencil, Adjust Stencil (no default
keys: every input style keeps its own).
- Overlay on the background draw list (under the panels, over the model), outline always, image at Opacity.
- Adjust puts handles on it: drag inside = move, a corner = scale about the centre, the round knob above the top
edge = turn (Shift: 15 degree steps). Keys while adjusting: arrows move (Shift: 1 px),
-/=scale,,/.turn 15 degrees (Shift: 1). Enter or Esc goes back to sculpting. While adjusting the brush ring hides and clicks off the stencil do nothing. - Navigating (orbit, pan, zoom, roll) fades it to 15% (Hide while navigating, on by default): it stays locked to the view, which is what "reposition and repeat" needs: turn the model under it, stroke again.
Cost
No stencil: one null check per dab. With one: a matrix multiply and four texel reads per vertex in the brush. The stroke lag bench (25/120/240 px) runs without a stencil and is unchanged.