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.
Mesh attributes (v0.2 foundation)
sf::Mesh (src/core/Mesh.h) carries optional attributes, empty until a feature needs them
(no memory cost). When present, the size always matches the mesh.
| Attribute | Type | Size | Empty means |
|---|---|---|---|
mask |
std::vector<float> |
vertices | nothing masked |
colors |
std::vector<glm::vec3> |
vertices | no vertex paint |
facegroups |
std::vector<uint32_t> |
triangles | every triangle in group 0 |
hidden |
std::vector<uint8_t> |
triangles | all visible |
uvs |
std::vector<glm::vec2> |
3 x triangles | no UVs (corner order = triangle order) |
quadPartners |
std::vector<uint32_t> |
triangles | no quads (Mesh::kNoQuad = a plain triangle) |
- Mask: 0 = free, 1 = fully masked. Colors: linear RGB 0..1 (OBJ/PLY convert from sRGB via
srgbToLinear/linearToSrgb; glTF COLOR_0 is already linear). - Read with
maskAt(v),colorAt(v, fallback),facegroupAt(t),triangleHidden(t),vertexHidden(v)(all adjacent triangles hidden); safe on empty attributes. Write afterensureMask()/ensureColors()/ensureFaceGroups()/ensureHidden();clearMask()etc. free them again. rebuildTopology()drops wrongly sized attributes (sanitizeAttributes()): fill them first.
Quads
Meshes are triangles, but quadPartners[t] names the triangle t forms a quad with (an imported quad split in
two, a Plane/Cube cell, a voxel-remesh cell). Pairs are mutual, share one edge wound oppositely, and
sanitizeAttributes() unpairs anything else, so a topology change can never leave a stale pair (at worst it
loses some). Record pairs with pairQuad(t, u) after pushing both triangles (it grows the array; resize it to the
triangle count before rebuildTopology() if triangles follow). Read with quadPartnerAt(t), which also
requires both halves to share a face group: what Wire shows as a quad and what exporters write as one.
- Display:
Renderer::uploadFacesbuilds GL_LINES edges without the diagonals for meshes with quads. - Export:
exportFace(t, face)gives 4 corners (in winding order; an(a,b,c)+(a,c,d)split gives(a,b,c,d)), 3, or 0 for the second half of a quad. OBJ, FBX, PLY, USD and Bridge files use it; glTF and STL stay triangles. - Building a mesh from some triangles of another:
remapQuads(src, newIndex, dst); appending:appendQuads(dst, firstTriangle, src).
Telling the renderer
- Vertex attributes (mask, colors):
mesh.markDirty(v)per vertex ormarkAllDirty(). - Triangle attributes (hidden, face groups): set
mesh.facesDirty = true. RenderSettings(src/render/Renderer.h):showVertexPaint(colors replace the base colour),showMask(masked areas darken),showFaceGroups(facegroupColor(id), same hash as the shader). Hidden triangles are left out of the index buffer. Toggles live in the View menu.
Preservation through topology changes
| Operation | mask / colors | face groups / hidden | uvs | quadPartners |
|---|---|---|---|---|
loopSubdivide (Primitives.cpp) |
linear interpolation | children inherit | corner midpoints | each quad -> 4 quads |
decimate / generateLods (Decimate.cpp) |
exact (vertices are a subset) | surviving faces keep theirs | follow kept vertex (approximate at seams) | dropped |
voxelRemesh (Voxel.cpp) |
nearest original vertex (transferVertexAttributes) |
reset (visible, group 0) | dropped | new: every surface-nets quad |
weldImported (Mesh.cpp) |
first vertex of each welded group | per kept triangle | per kept triangle | pairs of kept triangles |
extractTriangles / split / remove hidden (Face Groups.cpp) |
per kept vertex | per kept triangle | per kept triangle | pairs with both halves kept |
mergeMeshes (Parts.cpp) |
concatenated | concatenated | concatenated | concatenated (ids shifted) |
| plane / cube primitives | empty | cube: one group per side | empty | every grid cell |
| icosphere, image relief/inflate | empty | empty | empty | empty |
New topology operations must do the same (transferVertexAttributes(src, dst) for rebuilt surfaces).
Paint layers (src/core/PaintLayer.h)
With paint layers, colors is a cache: the composited stack of paintBase (the Base layer) and
paintLayers (per-vertex colour + alpha, opacity, blend mode, visible, locked); activePaintLayer is where
painting goes. Paint through paintVertex() (it writes the active layer and recomposites that vertex) and
record undo with Sculptor::recordColor / UndoRecord::captureColors, which capture the active layer.
Subset operations call copyPaintLayers(src, dst, kept), loopSubdivide calls subdividePaintLayers;
anything else that changes the vertex count flattens the stack (sanitizePaintLayers, run by
rebuildTopology), keeping the look in colors.
Undo (src/core/Undo.h)
UndoRecord holds sparse UndoChannels: positions (layer target), mask, colors
(per vertex), hidden, facegroups (per triangle), or a full mesh snapshot. Snapshots
(Document::replaceMeshUndoable) copy every attribute. Undo allocates a missing attribute
before restoring, so recording values of an empty attribute is fine.
- Strokes: inside
Sculptor::beginStroke/endStroke, callsculptor.recordMask(mesh, v)/recordColor(mesh, v)before writingmesh.mask[v]/mesh.colors[v]. - Whole-attribute operations:
doc.undo.push(UndoRecord::captureMask(mesh, "Invert Mask"))(alsocaptureColors,captureHidden,captureFaceGroups, optionally for a subset) before changing.
Brush hooks (src/core/Sculpt.h/.cpp)
vertexInfluence(mesh, v)= 0 for fully hidden vertices, else1 - mask.Sculptor::displaceapplies it, so every displacement brush respects mask and hidden (built-in, recipe and Move). Paint brushes should multiply by it; mask brushes must not.brushVertices(mesh, bvh, center, radius, out)= sphere query minus fully hidden vertices; use it instead ofBVH::queryVerticesin new brushes.Sculptor::mirrors(sym)gives symmetry.- Picking:
BVH::raycastskips hidden triangles, soApp::picknever lands on them.
Python and tests
doc.mask (N,) float32, doc.colors (N,3) float32, doc.facegroups (M,) uint32, doc.hidden (M,)
uint8: copies, None when absent, assignable (None clears). New tests: add tests/test_<feature>.cpp
including TestHarness.h (TEST/CHECK); CMake globs it. See tests/test_attributes.cpp.