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
//
// Python bindings (`import sculptforge`) for studio pipelines: every editor
// command, the document's mesh data as NumPy arrays, and the tool schema.
//
// import sculptforge as sf
// doc = sf.Document()
// sf.run(doc, "new_sphere", subdivisions=5)
// sf.run(doc, "export_usd", path="/tmp/head.usdz")
// verts, tris = doc.vertices, doc.triangles # (N, 3) float32, (M, 3) uint32
// doc.mask, doc.colors, doc.face groups # optional attributes, None when absent
// doc.set_selection_set("Eyes", mask=m) # push a selection set; doc.selection_set("Eyes") pulls it
#include "ai/AiCommands.h"
#include "ai/AiPolicy.h"
#include "ai/SplatTrainer.h"
#include "core/BrushLibrary.h"
#include "core/Commands.h"
#include "core/Multires.h"
#include "core/AuditLog.h"
#include "core/Script.h"
#include "core/SelectionSets.h"
#include "core/StudioProfile.h"
#include <pybind11/numpy.h>
#include <pybind11/pybind11.h>
#include <pybind11/stl.h>
#include <cstring>
#include <memory>
namespace py = pybind11;
using namespace sf;
namespace {
const CommandRegistry& registry() {
static CommandRegistry r = [] {
CommandRegistry reg;
ai::setAiEnabled(ai::aiFeaturesAllowed(ai::AiSettings::load(ai::defaultAiSettingsPath()).enabled)); // Preferences > AI, SF_AI
ai::registerAiCommands(reg, [] { return ai::AiSettings::load(ai::defaultAiSettingsPath()); });
ai::registerSplatTrainCommands(reg, [] { return ai::SplatTrainSettings::load(ai::defaultSplatTrainSettingsPath()); });
return reg;
}();
return r;
}
struct CommandError : std::runtime_error {
using std::runtime_error::runtime_error;
};
Args toArgs(const py::kwargs& kwargs) {
Args args;
for (auto item : kwargs) {
const std::string key = py::cast<std::string>(item.first);
const py::handle value = item.second;
if (py::isinstance<py::bool_>(value)) args[key] = value.cast<bool>();
else if (py::isinstance<py::int_>(value) || py::isinstance<py::float_>(value)) args[key] = value.cast<double>();
else args[key] = py::cast<std::string>(py::str(value)); // str, pathlib.Path, ...
}
return args;
}
std::string run(Document& doc, const std::string& name, const py::kwargs& kwargs) {
const Args args = toArgs(kwargs); // touches Python objects: needs the GIL
CommandResult r;
{
py::gil_scoped_release release; // long operations (remesh, AI services) don't block other Python threads
r = registry().execute(doc, name, args);
}
if (!r.ok) throw CommandError(name + ": " + r.message);
return r.message;
}
py::array_t<float> vec3Array(const std::vector<glm::vec3>& v) {
py::array_t<float> a({py::ssize_t(v.size()), py::ssize_t(3)});
if (!v.empty()) std::memcpy(a.mutable_data(), v.data(), v.size() * sizeof(glm::vec3));
return a;
}
// Optional mesh attributes: None while absent, otherwise a copy.
template <class T>
py::object attributeArray(const std::vector<T>& v) {
if (v.empty()) return py::none();
py::array_t<T> a(py::ssize_t(v.size()));
std::memcpy(a.mutable_data(), v.data(), v.size() * sizeof(T));
return a;
}
// Replaces an optional attribute from a 1-D array of `count` values (None clears it).
template <class T>
void setAttribute(std::vector<T>& dst, const py::object& value, size_t count, const char* what) {
if (value.is_none()) {
std::vector<T>().swap(dst);
return;
}
auto a = py::array_t<T, py::array::c_style | py::array::forcecast>::ensure(value);
if (!a || a.ndim() != 1 || size_t(a.shape(0)) != count)
throw py::value_error(std::string(what) + ": expected " + std::to_string(count) + " values or None");
dst.assign(a.data(), a.data() + count);
}
// An (n, k) float32 array of `count` rows (k = 1: 1-D), or a ValueError.
template <class T>
std::vector<T> rows(const py::object& value, size_t count, int k, const char* what) {
auto a = py::array_t<float, py::array::c_style | py::array::forcecast>::ensure(value);
const bool shape = a && ((k == 1 && a.ndim() == 1) || (k > 1 && a.ndim() == 2 && a.shape(1) == k));
if (!shape || size_t(a.shape(0)) != count)
throw py::value_error(std::string(what) + ": expected " + std::to_string(count) + (k > 1 ? " rows of " + std::to_string(k) : " values"));
std::vector<T> out(count);
std::memcpy(out.data(), a.data(), count * sizeof(T));
return out;
}
template <class T>
py::array_t<float> floatRows(const std::vector<T>& v, int k) {
py::array_t<float> a = k == 1 ? py::array_t<float>(py::ssize_t(v.size())) : py::array_t<float>({py::ssize_t(v.size()), py::ssize_t(k)});
if (!v.empty()) std::memcpy(a.mutable_data(), v.data(), v.size() * sizeof(T));
return a;
}
} // namespace
PYBIND11_MODULE(sculptforge, m) {
m.doc() = "SculptForge: free, open-source digital sculpting - Python API for pipelines";
m.attr("__version__") = SCULPTFORGE_VERSION;
py::register_exception<CommandError>(m, "CommandError", PyExc_RuntimeError);
// Studio mode (SF_STUDIO_PROFILE, SF_OFFLINE=1 or a studio build; core/StudioProfile.h), as in the app.
sf::ai::setStudioAiAllowed(startStudioMode("", "", false).profile.ai);
sf::audit::setClient("python"); // (the AI audit log, core/AuditLog.h)
py::class_<Document>(m, "Document", "A scene: the sculpt mesh (with layers), Gaussian splats and edit history.")
.def(py::init([] {
// With the user's brush library and SCULPTFORGE_BRUSH_PATH studio brushes, like the app.
auto doc = std::make_unique<Document>();
for (const auto& message : loadBrushLibrary(*doc))
if (PyErr_WarnEx(PyExc_RuntimeWarning, message.c_str(), 1) < 0) throw py::error_already_set();
return doc;
}))
.def_property_readonly("vertices", [](const Document& d) { return vec3Array(d.mesh.positions); },
"Current vertex positions, (N, 3) float32 (a copy).")
.def_property_readonly("base_vertices", [](const Document& d) { return vec3Array(d.mesh.basePositions()); },
"Vertex positions with every layer at zero, (N, 3) float32.")
.def_property_readonly("normals", [](const Document& d) { return vec3Array(d.mesh.normals); })
.def_property(
"mask", [](const Document& d) { return attributeArray(d.mesh.mask); },
[](Document& d, const py::object& v) {
setAttribute(d.mesh.mask, v, d.mesh.vertexCount(), "mask");
d.mesh.markAllDirty();
d.modified = true;
},
"Per-vertex mask, (N,) float32 with 0 = free and 1 = fully masked; None if the mesh has no mask.")
.def_property(
"colors",
[](const Document& d) -> py::object { return d.mesh.colors.empty() ? py::object(py::none()) : vec3Array(d.mesh.colors); },
[](Document& d, const py::object& v) {
if (v.is_none()) {
d.mesh.clearColors();
} else {
auto a = py::array_t<float, py::array::c_style | py::array::forcecast>::ensure(v);
if (!a || a.ndim() != 2 || a.shape(1) != 3 || size_t(a.shape(0)) != d.mesh.vertexCount())
throw py::value_error("colors: expected (N, 3) linear RGB or None");
d.mesh.colors.resize(d.mesh.vertexCount());
std::memcpy(d.mesh.colors.data(), a.data(), d.mesh.colors.size() * sizeof(glm::vec3));
}
d.mesh.markAllDirty();
d.modified = true;
},
"Per-vertex paint colours, (N, 3) float32 linear RGB in 0..1; None if unpainted.")
.def_property(
"facegroups", [](const Document& d) { return attributeArray(d.mesh.facegroups); },
[](Document& d, const py::object& v) {
setAttribute(d.mesh.facegroups, v, d.mesh.triangleCount(), "facegroups");
d.mesh.facesDirty = true;
d.modified = true;
},
"Per-triangle face group ids, (M,) uint32; None means every triangle is in group 0.")
.def_property(
"hidden", [](const Document& d) { return attributeArray(d.mesh.hidden); },
[](Document& d, const py::object& v) {
setAttribute(d.mesh.hidden, v, d.mesh.triangleCount(), "hidden");
d.mesh.facesDirty = true;
d.modified = true;
},
"Per-triangle hidden flags, (M,) uint8 (nonzero = hidden); None means all visible.")
.def_property_readonly(
"triangles",
[](const Document& d) {
py::array_t<uint32_t> a({py::ssize_t(d.mesh.triangleCount()), py::ssize_t(3)});
if (d.mesh.triangleCount())
std::memcpy(a.mutable_data(), d.mesh.triangles.data(), d.mesh.triangleCount() * sizeof(glm::uvec3));
return a;
},
"Triangle vertex indices, (M, 3) uint32 (a copy).")
.def_property_readonly("layers",
[](const Document& d) {
py::list out;
for (const auto& l : d.mesh.layers) out.append(py::make_tuple(l.name, l.weight));
return out;
},
"Sculpt layers (blend shapes) as (name, weight) tuples.")
.def("layer_delta", [](const Document& d, int index) {
if (index < 0 || index >= int(d.mesh.layers.size())) throw py::index_error("no such layer");
return vec3Array(d.mesh.layers[size_t(index)].delta);
}, py::arg("index"), "Per-vertex offsets of a layer, (N, 3) float32.")
.def(
"set_mesh",
[](Document& d, py::array_t<float, py::array::c_style | py::array::forcecast> vertices,
py::array_t<uint32_t, py::array::c_style | py::array::forcecast> triangles) {
if (vertices.ndim() != 2 || vertices.shape(1) != 3 || triangles.ndim() != 2 || triangles.shape(1) != 3)
throw py::value_error("expected vertices (N, 3) and triangles (M, 3)");
Mesh mesh;
mesh.positions.resize(size_t(vertices.shape(0)));
std::memcpy(mesh.positions.data(), vertices.data(), mesh.positions.size() * sizeof(glm::vec3));
mesh.triangles.resize(size_t(triangles.shape(0)));
std::memcpy(mesh.triangles.data(), triangles.data(), mesh.triangles.size() * sizeof(glm::uvec3));
for (const auto& t : mesh.triangles)
if (t.x >= mesh.vertexCount() || t.y >= mesh.vertexCount() || t.z >= mesh.vertexCount())
throw py::value_error("triangle index out of range");
mesh.rebuildTopology();
mesh.recomputeAllNormals();
d.setMesh(std::move(mesh));
},
py::arg("vertices"), py::arg("triangles"), "Replace the sculpt with your own mesh (clears undo).")
.def_property_readonly("splat_count", [](const Document& d) { return d.splats.size(); })
// Parts: the mesh properties above are the active Part's.
.def_property_readonly("parts",
[](const Document& d) {
py::list out;
for (int i = 0; i < d.partCount(); ++i)
out.append(py::dict(py::arg("name") = d.parts[size_t(i)].name,
py::arg("visible") = d.parts[size_t(i)].visible,
py::arg("triangles") = d.partMesh(i).triangleCount()));
return out;
},
"The Parts (separate meshes) in list order, as dicts with name, visible and triangles.")
.def_property(
"active_part", [](const Document& d) { return d.activePart; },
[](Document& d, const py::object& v) {
int index = -1;
if (py::isinstance<py::str>(v)) index = d.findPart(v.cast<std::string>());
else index = v.cast<int>();
if (index < 0 || index >= d.partCount()) throw py::index_error("no such Part");
d.selectPart(index);
},
"Index of the Part that vertices, mask, layers... and editing commands refer to. Set it to an "
"index or a Part name to select another one.")
// Selection Sets (core/SelectionSets.h) of the active Part (Part): push and pull them as arrays.
.def_property_readonly(
"selection_sets",
[](const Document& d) {
py::list out;
const SelectionSetList* list = d.mesh.selectionSets.get();
if (list)
for (const auto& s : list->sets) {
py::list channels;
for (const char* c : {"mask", "facegroups", "paint", "visibility", "uvs", "morph"}) {
uint32_t bit = 0;
std::string err;
if (parseSetChannels(c, bit, err) && s->has(bit)) channels.append(c);
}
out.append(py::dict(py::arg("name") = s->name, py::arg("channels") = channels,
py::arg("level") = s->level, py::arg("vertex_count") = s->vertexCount,
py::arg("triangle_count") = s->triangleCount,
py::arg("fits") = selectionSetFits(d.mesh, *s),
py::arg("morph_target") = s->name == list->morphTarget));
}
return out;
},
"The active Part's selection sets, as dicts with name, channels, level, vertex_count, triangle_count, "
"fits and morph_target.")
.def(
"selection_set",
[](const Document& d, const std::string& name) {
const SelectionSetList* list = d.mesh.selectionSets.get();
const int i = list ? list->find(name) : -1;
if (i < 0) throw py::key_error("no selection set " + name);
SelectionSetData data;
std::string err;
if (!selectionSetAt(d.mesh, *list->sets[size_t(i)], kSetAllChannels, data, err)) throw CommandError(err);
py::dict out;
if (data.channels & kSetMask) out["mask"] = floatRows(data.mask, 1);
if (data.channels & kSetFaceGroups) out["facegroups"] = attributeArray(data.facegroups);
if (data.channels & kSetPaint) out["colors"] = floatRows(data.colors, 3);
if (data.channels & kSetVisibility) out["hidden"] = attributeArray(data.hidden);
if (data.channels & kSetUvs) out["uvs"] = floatRows(data.uvs, 2);
if (data.channels & kSetMorph) out["positions"] = floatRows(data.positions, 3);
return out;
},
py::arg("name"),
"A selection set's channels at the current subdivision level, as a dict of NumPy arrays (mask, facegroups, "
"colors, hidden, uvs (per triangle corner), positions), only those the set holds.")
.def(
"set_selection_set",
[](Document& d, const std::string& name, const py::object& mask, const py::object& facegroups,
const py::object& colors, const py::object& hidden, const py::object& uvs, const py::object& positions) {
const size_t nv = d.mesh.vertexCount(), nt = d.mesh.triangleCount();
SelectionSetData data;
if (!mask.is_none()) data.mask = rows<float>(mask, nv, 1, "mask"), data.channels |= kSetMask;
if (!facegroups.is_none()) {
setAttribute(data.facegroups, facegroups, nt, "facegroups");
data.channels |= kSetFaceGroups;
}
if (!colors.is_none()) data.colors = rows<glm::vec3>(colors, nv, 3, "colors"), data.channels |= kSetPaint;
if (!hidden.is_none()) {
setAttribute(data.hidden, hidden, nt, "hidden");
data.channels |= kSetVisibility;
}
if (!uvs.is_none()) data.uvs = rows<glm::vec2>(uvs, nt * 3, 2, "uvs"), data.channels |= kSetUvs;
if (!positions.is_none()) data.positions = rows<glm::vec3>(positions, nv, 3, "positions"), data.channels |= kSetMorph;
if (!data.channels) throw py::value_error("give at least one of mask, facegroups, colors, hidden, uvs, positions");
SelectionSet set;
std::string msg;
if (!makeSelectionSet(name, data, uint32_t(nv), uint32_t(nt), subdivCurrentLevel(d.mesh), set, msg) ||
!addSelectionSet(d, std::move(set), "Store set " + name, msg))
throw CommandError(msg);
return msg;
},
py::arg("name"), py::kw_only(), py::arg("mask") = py::none(), py::arg("facegroups") = py::none(),
py::arg("colors") = py::none(), py::arg("hidden") = py::none(), py::arg("uvs") = py::none(),
py::arg("positions") = py::none(),
"Store (or replace) a selection set on the active Part from arrays laid out for the current level "
"(one undo step). Restore it with run(doc, 'selection_set_restore', name=...).")
.def("__repr__", [](const Document& d) {
return "<sculptforge.Document " + std::to_string(d.mesh.vertexCount()) + " vertices, " +
std::to_string(d.mesh.triangleCount()) + " triangles, " + std::to_string(d.mesh.layers.size()) +
" layers, " + std::to_string(d.splats.size()) + " splats>";
});
m.def("run", &run, py::arg("document"), py::arg("command"),
"Run a SculptForge command on a document, e.g. run(doc, 'remesh', resolution=256). "
"Returns the command's message; raises sculptforge.CommandError on failure.");
m.def(
"run_script",
[](Document& doc, const std::string& script) {
std::vector<ScriptStatement> statements;
std::string err;
if (!parseScript(script, statements, err)) throw CommandError(err);
py::list messages;
for (const auto& st : statements) {
CommandResult r;
{
py::gil_scoped_release release;
r = registry().execute(doc, st.command, st.args);
}
if (!r.ok) throw CommandError("line " + std::to_string(st.line) + " (" + st.command + "): " + r.message);
messages.append(r.message);
}
return messages;
},
py::arg("document"), py::arg("script"),
"Run a script in sculptforge-cli syntax: 'new_sphere subdivisions=5; export_glb path=out.glb'.");
m.def(
"commands",
[] {
py::list out;
for (const auto& c : registry().all()) {
py::list params;
for (const auto& p : c.params) {
const char* type = p.type == ParamSpec::Type::Bool ? "bool" : p.type == ParamSpec::Type::Number ? "number" : "string";
params.append(py::dict(py::arg("name") = p.name, py::arg("type") = type,
py::arg("description") = p.description, py::arg("required") = p.required));
}
out.append(py::dict(py::arg("name") = c.name, py::arg("description") = c.description,
py::arg("params") = params));
}
return out;
},
"Every available command with its parameters.");
m.def("tool_schema", [] { return registry().toolSchemaJson(); },
"Commands as LLM tool definitions (JSON), for wiring SculptForge into your own agents.");
}