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
#include "core/Commands.h"
#include "core/AgentTools.h"
#include "core/ViewCapture.h"
#include "core/Bake.h"
#include "core/Benchmark.h"
#include "core/BrushAlpha.h"
#include "core/BrushLibrary.h"
#include "core/Decimate.h"
#include "core/KeepMasked.h"
#include "core/Macro.h"
#include "core/Pack.h"
#include "core/Dyntopo.h"
#include "core/EnginePresets.h"
#include "core/ExtractMirror.h"
#include "core/Face.h"
#include "core/HardwareProfile.h"
#include "core/ImageTo3D.h"
#include "core/Masking.h"
#include "core/Backdrop.h"
#include "core/CloseHoles.h"
#include "core/Cut.h"
#include "core/Multires.h"
#include "core/Micro.h"
#include "core/MeshTransform.h"
#include "core/MeshCheck.h"
#include "core/PathStroke.h"
#include "core/FaceGroups.h"
#include "core/SelectionSets.h"
#include "core/Parts.h"
#include "core/Units.h"
#include "core/VertexPaint.h"
#include "core/Primitives.h"
#include "core/Project.h"
#include "core/QRemesh.h"
#include "core/ForgeSpheres.h"
#include "core/Tube.h"
#include "core/Garment.h"
#include "core/Deform.h"
#include "core/Sculptable.h"
#include "core/Splats.h"
#include "core/StarterMeshes.h"
#include "core/TextureTransfer.h"
#include "core/Timeline.h"
#include "core/Voxel.h"
#include "core/LegacyNames.h"
#include "io/BridgeProtocol.h"
#include "io/FbxIO.h"
#include "io/GltfIO.h"
#include "io/BlenderCommands.h"
#include "io/BridgeCommands.h"
#include "io/BridgeIO.h"
#include "io/MayaCommands.h"
#include "io/ObjIO.h"
#include "io/PlyIO.h"
#include "io/StlIO.h"
#include "io/UsdIO.h"
#include <algorithm>
#include <cctype>
#include <filesystem>
#include <glm/gtc/matrix_transform.hpp>
#include <sstream>
namespace sf {
double argNumber(const Args& args, const std::string& key, double fallback) {
auto it = args.find(key);
if (it == args.end()) return fallback;
if (auto* d = std::get_if<double>(&it->second)) return *d;
if (auto* b = std::get_if<bool>(&it->second)) return *b ? 1.0 : 0.0;
return fallback;
}
bool argBool(const Args& args, const std::string& key, bool fallback) {
auto it = args.find(key);
if (it == args.end()) return fallback;
if (auto* b = std::get_if<bool>(&it->second)) return *b;
if (auto* d = std::get_if<double>(&it->second)) return *d != 0.0;
return fallback;
}
std::string argString(const Args& args, const std::string& key, const std::string& fallback) {
auto it = args.find(key);
if (it == args.end()) return fallback;
if (auto* s = std::get_if<std::string>(&it->second)) return *s;
return fallback;
}
namespace {
constexpr size_t kMaxSubdivideTriangles = 50'000'000;
std::string lowerExtension(const std::string& path) {
std::string ext = std::filesystem::path(std::u8string(path.begin(), path.end())).extension().string();
std::transform(ext.begin(), ext.end(), ext.begin(), [](unsigned char c) { return char(std::tolower(c)); });
return ext;
}
std::string fileStem(const std::string& path) {
const auto stem = std::filesystem::path(std::u8string(path.begin(), path.end())).stem().u8string();
return std::string(stem.begin(), stem.end());
}
// " (3 Parts)" for a multi-object export, else nothing.
std::string objectCountText(const std::vector<MeshObjectRef>& objects) {
return objects.size() > 1 ? " (" + std::to_string(objects.size()) + " Parts)" : std::string();
}
std::string jsonEscape(const std::string& s) {
std::string out;
for (char c : s) {
switch (c) {
case '"': out += "\\\""; break;
case '\\': out += "\\\\"; break;
case '\n': out += "\\n"; break;
default: out += c;
}
}
return out;
}
// The `unit` argument of open / open_obj (core/Units.h): numbers per metre in an STL, OBJ or PLY. Empty: the
// format's convention (STL millimetres, OBJ and PLY metres). Null with `err` set for an unknown unit.
const LengthUnit* fileUnitArg(const Args& a, const std::string& ext, std::string& err) {
const std::string id = argString(a, "unit");
if (id.empty()) return ext == ".stl" ? &millimetres() : &metres();
const LengthUnit* u = findLengthUnit(id);
if (!u) err = "Unknown unit '" + id + "' (mm, cm, m or in)";
return u;
}
// File numbers to metres, rounded once from double (so writing them back at `perMetre` gives the numbers again).
void fileUnitsToMetres(Mesh& m, double perMetre) {
if (perMetre == 1.0) return;
for (glm::vec3& p : m.positions) p = glm::vec3(glm::dvec3(p) / perMetre);
for (auto& layer : m.layers)
for (glm::vec3& d : layer.delta) d = glm::vec3(glm::dvec3(d) / perMetre);
}
constexpr const char* kUnitArgHelp = "Unit of the numbers in a unit-less file (STL, OBJ, PLY): mm, cm, m or in. Default "
"mm for STL, m for OBJ and PLY. Exports to the same kind of file write that unit "
"back, so the part keeps its size.";
} // namespace
CommandRegistry::CommandRegistry() {
using T = ParamSpec::Type;
add({"new_sphere",
"Replace the scene with a new sphere ready for sculpting.",
{{"subdivisions", T::Number, "Icosphere subdivision level (0-8). Default 6.", false},
{"triangles", T::Number,
"About this many triangles instead (a cube's quads pushed onto the sphere, up to 48M; benchmarks: "
"tools/bench_strokes.sh).",
false}},
[](Document& doc, const Args& a) -> CommandResult {
if (const double t = argNumber(a, "triangles", 0.0); t > 0.0) {
const int res = std::clamp(int(std::lround(std::sqrt(t / 12.0))), 1, 2000);
Mesh m = makeCube(res, 2.0f);
for (glm::vec3& p : m.positions) p = glm::normalize(p);
m.recomputeAllNormals();
doc.setMesh(std::move(m), "Sphere");
doc.path.clear();
return {true, "Created sphere with " + std::to_string(doc.mesh.triangleCount()) + " triangles"};
}
int level = std::clamp(int(argNumber(a, "subdivisions", 6)), 0, 8);
doc.setMesh(makeIcosphere(level), "Sphere");
doc.path.clear();
return {true, "Created sphere with " + std::to_string(doc.mesh.triangleCount()) + " triangles"};
}});
add({"new_plane",
"Replace the scene with a flat grid plane.",
{{"resolution", T::Number, "Grid cells per side (1-2000). Default 128.", false}},
[](Document& doc, const Args& a) -> CommandResult {
int res = std::clamp(int(argNumber(a, "resolution", 128)), 1, 2000);
doc.setMesh(makePlane(res), "Plane");
doc.path.clear();
return {true, "Created plane with " + std::to_string(doc.mesh.triangleCount()) + " triangles"};
}});
add({"open_obj",
"Load a Wavefront OBJ file, replacing the current scene.",
{{"path", T::String, "File path (UTF-8).", true}, {"unit", T::String, kUnitArgHelp, false}},
[](Document& doc, const Args& a) -> CommandResult {
std::string path = argString(a, "path");
std::vector<MeshObject> objects;
std::string err;
const LengthUnit* unit = fileUnitArg(a, ".obj", err);
if (!unit) return {false, err};
if (!loadObj(path, objects, err)) return {false, err};
for (auto& o : objects) fileUnitsToMetres(o.mesh, unit->perMetre);
const size_t count = objects.size();
setSceneObjects(doc, std::move(objects), fileStem(path));
doc.path = path;
doc.unitlessScale = unit->perMetre;
doc.unitlessFormat = "obj";
return {true, "Loaded " + path + (count > 1 ? " (" + std::to_string(count) + " Parts)" : "")};
}});
add({"open",
"Open a file: models replace the scene; Gaussian splats "
"(.ply/.splat captures, KHR_gaussian_splatting .glb, USD ParticleField) load as a reference next to the sculpt. "
"glTF morph targets and FBX/USD blend shapes become sculpt layers. Files with several objects (OBJ `o`, "
"glTF nodes, FBX models, USD meshes) open as one Part each. SculptForge projects (.sfproj) "
"restore the whole scene.",
{{"path", T::String, "File path (UTF-8).", true}, {"unit", T::String, kUnitArgHelp, false}},
[](Document& doc, const Args& a) -> CommandResult {
std::string path = argString(a, "path");
if (isProjectPath(path)) return openProjectCommand(doc, path);
const std::string ext = lowerExtension(path);
std::vector<MeshObject> objects; // one per object in the file (OBJ `o`, glTF node, FBX model, USD prim)
Mesh m;
SplatCloud splats;
std::string err;
BridgeInfo bridge;
const LengthUnit* unit = fileUnitArg(a, ext, err);
if (!unit) return {false, err};
const bool unitless = ext == ".stl" || ext == ".ply" || ext == ".obj";
bool ok;
if (ext == ".glb" || ext == ".gltf") ok = loadGltf(path, objects, err, &splats);
else if (ext == ".usda" || ext == ".usd" || ext == ".usdz") ok = loadUsd(path, objects, splats, err);
else if (ext == ".splat") ok = loadDotSplat(path, splats, err);
else if (ext == ".fbx") ok = loadFbx(path, objects, err);
else if (ext == bridgefile::kExtLower) ok = loadBridge(path, m, err, &bridge);
else if (ext == ".stl") ok = loadStl(path, m, err, unit->perMetre);
else if (ext == ".sculptforge") ok = loadBridgeFolder(path, objects, err); // numbered Bridge files
else if (ext == ".ply") {
PlyContent content;
ok = loadPly(path, m, splats, content, err);
} else ok = loadObj(path, objects, err);
if (!ok) return {false, err};
if (ext == ".obj" || ext == ".ply") {
fileUnitsToMetres(m, unit->perMetre);
for (auto& o : objects) fileUnitsToMetres(o.mesh, unit->perMetre);
}
if (m.triangleCount() > 0) objects.push_back({"", std::move(m)});
std::erase_if(objects, [](const MeshObject& o) { return o.mesh.triangleCount() == 0; });
std::string msg = "Opened " + std::filesystem::path(path).filename().string(); // file name only: status shows in screen recordings
const bool hasMesh = !objects.empty();
if (hasMesh) {
size_t tris = 0, quads = 0, layers = 0;
for (const auto& o : objects) {
tris += o.mesh.triangleCount();
quads += o.mesh.quadCount();
layers = std::max(layers, o.mesh.layers.size());
}
const size_t count = objects.size();
setSceneObjects(doc, std::move(objects), ext == bridgefile::kExtLower && !bridge.name.empty() ? bridge.name : fileStem(path));
doc.path = ext == ".obj" ? path : std::string(); // other formats are exported explicitly
if (ext == bridgefile::kExtLower) doc.bridgeName = bridge.name;
if (unitless) { // exports write this unit back (Document::unitlessScale)
doc.unitlessScale = unit->perMetre;
doc.unitlessFormat = ext.substr(1);
}
msg += " (" + (count > 1 ? std::to_string(count) + " Parts, " : std::string()) + std::to_string(tris) +
" triangles" + (quads == 0 ? "" : ", " + std::to_string(quads) + " quads") + (layers == 0 ? "" : ", " + std::to_string(layers) + " layers") + ")";
}
if (!splats.empty()) {
doc.splats = std::move(splats);
doc.splatsChanged();
msg += " (" + std::to_string(doc.splats.size()) + " Gaussian splats, SH degree " +
std::to_string(doc.splats.shDegree) + ")";
if (hasMesh) doc.markClean(); // a model with its own splats is one freshly opened scene
}
return {true, msg};
}});
add({"remesh",
"Voxel remesh (like Voxel Remesh): rebuild the sculpt as an even, watertight surface, merging overlapping "
"parts and fixing broken scans or generated models. Sculpt layers are baked in. A painted texture is "
"kept (new Auto UVs, colour projected from the old surface) unless keep_texture=false.",
{{"resolution", T::Number, "Voxels across the longest side (32-512). Default 200; higher keeps more detail.", false},
{"keep_texture", T::Bool, "Keep a painted texture: Auto UV the result and project the texture onto it. "
"Default true.", false},
{"keep_masked", T::Bool, "Keep masked: masked areas keep their triangles exactly; the rest is remeshed and "
"joined to them watertight. Default false.", false}},
[](Document& doc, const Args& a) -> CommandResult {
std::string err;
const std::vector<uint8_t> keep = argBool(a, "keep_masked", false) ? keepMaskedTriangles(doc.mesh) : std::vector<uint8_t>();
const bool keeping = std::find(keep.begin(), keep.end(), 1) != keep.end();
if (keeping && std::find(keep.begin(), keep.end(), 0) == keep.end())
return {false, "Remesh: everything is masked, so nothing would change"};
Mesh m = voxelRemesh(doc.mesh, std::clamp(int(argNumber(a, "resolution", 200)), 32, 512), &err);
if (m.triangleCount() == 0) return {false, err};
std::string keepNote;
if (keeping) {
Mesh stitched;
if (!stitchKeptTriangles(doc.mesh, keep, m, stitched, err, &keepNote)) return {false, "Remesh (Keep masked): " + err};
m = std::move(stitched);
}
const std::string texture = carryTextureNote(doc.mesh, m, argBool(a, "keep_texture", true));
doc.replaceMeshUndoable(std::move(m), "Remesh");
return {true, "Remeshed to " + std::to_string(doc.mesh.triangleCount()) + " triangles" + texture +
(keepNote.empty() ? "" : "; Keep masked: " + keepNote)};
}});
add({"image_relief",
"Turn an image into a sculpted relief: light areas rise, dark areas stay low (logos, coins, emblems, "
"height maps, texture photos). Replaces the scene.",
{{"path", T::String, "Image file (png, jpg, bmp, tga...).", true},
{"depth", T::Number, "Relief height as a fraction of the width (0.01-1). Default 0.12.", false},
{"resolution", T::Number, "Detail: grid cells along the long side (32-2048). Default 384.", false},
{"invert", T::Bool, "Make dark areas high instead.", false}},
[](Document& doc, const Args& a) -> CommandResult {
Image img;
std::string err;
if (!Image::load(argString(a, "path"), img, err)) return {false, err};
ReliefOptions o;
o.depth = float(std::clamp(argNumber(a, "depth", o.depth), 0.01, 1.0));
o.resolution = int(std::clamp(argNumber(a, "resolution", o.resolution), 32.0, 2048.0));
o.invert = argBool(a, "invert", false);
doc.replaceMeshUndoable(makeImageRelief(img, o), "Image Relief");
doc.path.clear();
return {true, "Relief with " + std::to_string(doc.mesh.triangleCount()) + " triangles"};
}});
add({"image_inflate",
"Inflate a sketch or silhouette (transparent background or plain backdrop) into a rounded, closed 3D base "
"mesh ready for sculpting. Replaces the scene.",
{{"path", T::String, "Image file.", true},
{"thickness", T::Number, "1 = round, lower = flatter (0.1-3). Default 1.", false},
{"resolution", T::Number, "Detail along the long side (32-512). Default 160.", false},
{"subdivisions", T::Number, "Smoothing subdivision passes (0-3). Default 1.", false}},
[](Document& doc, const Args& a) -> CommandResult {
Image img;
std::string err;
if (!Image::load(argString(a, "path"), img, err)) return {false, err};
InflateOptions o;
o.thickness = float(std::clamp(argNumber(a, "thickness", 1.0), 0.1, 3.0));
o.resolution = int(std::clamp(argNumber(a, "resolution", o.resolution), 32.0, 512.0));
o.subdivisions = int(std::clamp(argNumber(a, "subdivisions", 1.0), 0.0, 3.0));
Mesh m = inflateSilhouette(img, o, &err);
if (m.triangleCount() == 0) return {false, err};
doc.replaceMeshUndoable(std::move(m), "Inflate Sketch");
doc.path.clear();
return {true, "Inflated sketch into " + std::to_string(doc.mesh.triangleCount()) + " triangles"};
}});
add({"image_project",
"Stamp an image onto the current model as surface detail, projected from the front (+Z). Light = raised. "
"Goes into the active sculpt layer.",
{{"path", T::String, "Image file.", true},
{"depth", T::Number, "Displacement at full brightness, as a fraction of the model size (0.001-0.5). Default 0.03.", false},
{"invert", T::Bool, "Make dark areas raised instead.", false}},
[](Document& doc, const Args& a) -> CommandResult {
Image img;
std::string err;
if (!Image::load(argString(a, "path"), img, err)) return {false, err};
AABB b = doc.mesh.bounds();
if (!b.valid()) return {false, "Nothing to project onto"};
const float size = glm::length(b.extent());
const glm::vec3 eye = b.center() + glm::vec3(0, 0, size * 2.0f);
const float halfH = std::max(b.extent().x / std::max(img.aspect(), 1e-3f), b.extent().y) * 0.5f;
const float halfW = halfH * img.aspect();
glm::mat4 proj = glm::ortho(-halfW, halfW, -halfH, halfH, 0.01f, size * 4.0f);
glm::mat4 view = glm::lookAt(eye, b.center(), glm::vec3(0, 1, 0));
ProjectOptions o;
o.depth = float(std::clamp(argNumber(a, "depth", 0.03), 0.001, 0.5)) * size;
o.invert = argBool(a, "invert", false);
o.coverage = 1.0f;
Mesh m = doc.mesh;
size_t n = projectImage(m, doc.activeLayer, img, proj * view, img.aspect(), eye, o);
if (n == 0) return {false, "The image did not land on any front-facing surface"};
doc.replaceMeshUndoable(std::move(m), "Project Image");
return {true, "Projected onto " + std::to_string(n) + " vertices"};
}});
add({"save_obj",
"Export the visible Parts as a Wavefront OBJ file (one `o` object each, face groups as `g` groups). OBJ "
"cannot hold the mask, visibility, sculpt layers or splats, so this is an export: the document keeps its "
"path and unsaved-changes state. UVs are kept; a textured Part also writes <name>.mtl and its PNG beside "
"the file. Positions are in metres, or in the units of the STL/OBJ/PLY the scene was opened from (an STL's "
"millimetres stay millimetres).",
{{"path", T::String, "File path (UTF-8). Defaults to the current document path unless that is a project.", false}},
[](Document& doc, const Args& a) -> CommandResult {
std::string path = argString(a, "path", isProjectPath(doc.path) ? std::string() : doc.path);
if (path.empty()) return {false, "No path given"};
if (isProjectPath(path)) return {false, "Use save_project for .sfproj files"};
std::string err;
const auto objects = visiblePartObjects(doc);
if (objects.empty()) return {false, "Nothing visible to export"};
if (!saveObj(path, objects, err, doc.unitlessExportScale("obj"))) return {false, err};
return {true, "Saved " + path + objectCountText(objects)};
}});
add({"subdivide",
"Smoothly subdivide the mesh (Loop subdivision). Each level multiplies the triangle count by 4. Unlike "
"Divide (subdiv_divide), it keeps no lower levels to step back to.",
{{"levels", T::Number, "Number of subdivision levels to apply (1-4). Default 1.", false}},
[](Document& doc, const Args& a) -> CommandResult {
int levels = std::clamp(int(argNumber(a, "levels", 1)), 1, 4);
size_t projected = doc.mesh.triangleCount();
for (int i = 0; i < levels; ++i) projected *= 4;
if (projected > kMaxSubdivideTriangles)
return {false, "Subdividing would exceed " + std::to_string(kMaxSubdivideTriangles) + " triangles"};
Mesh m = loopSubdivide(doc.mesh);
for (int i = 1; i < levels; ++i) m = loopSubdivide(m);
doc.replaceMeshUndoable(std::move(m), "Subdivide");
return {true, "Subdivided to " + std::to_string(doc.mesh.triangleCount()) + " triangles"};
}});
add({"layer_add",
"Add a sculpt layer (blend shape / morph target). New strokes go into it until another layer is made active.",
{{"name", T::String, "Layer name, e.g. 'Smile' or 'BlinkL'.", false}},
[](Document& doc, const Args& a) -> CommandResult {
Mesh m = doc.mesh;
int idx = m.addLayer(argString(a, "name", "Layer " + std::to_string(doc.mesh.layers.size() + 1)));
doc.replaceMeshUndoable(std::move(m), "Add Layer");
doc.activeLayer = idx;
return {true, "Added layer '" + doc.mesh.layers[idx].name + "' (index " + std::to_string(idx) + ")"};
}});
add({"layer_remove",
"Delete a sculpt layer and its offsets.",
{{"index", T::Number, "Layer index (0-based).", true}},
[](Document& doc, const Args& a) -> CommandResult {
int idx = int(argNumber(a, "index", -1));
if (idx < 0 || idx >= int(doc.mesh.layers.size())) return {false, "No layer " + std::to_string(idx)};
Mesh m = doc.mesh;
m.removeLayer(idx);
doc.replaceMeshUndoable(std::move(m), "Remove Layer");
doc.activeLayer = -1;
return {true, "Removed layer " + std::to_string(idx)};
}});
add({"layer_set_weight",
"Set how strongly a sculpt layer is applied (0 = off, 1 = as sculpted; negative or >1 exaggerates).",
{{"index", T::Number, "Layer index (0-based).", true},
{"weight", T::Number, "Blend weight, typically 0-1.", true}},
[](Document& doc, const Args& a) -> CommandResult {
int idx = int(argNumber(a, "index", -1));
if (idx < 0 || idx >= int(doc.mesh.layers.size())) return {false, "No layer " + std::to_string(idx)};
doc.mesh.setLayerWeight(idx, float(argNumber(a, "weight", 1.0)));
doc.bvhDirty = true;
doc.modified = true;
return {true, "Layer " + std::to_string(idx) + " weight set"};
}});
add({"layer_set_active",
"Choose which sculpt layer new strokes go into (-1 = base mesh).",
{{"index", T::Number, "Layer index, or -1 for the base mesh.", true}},
[](Document& doc, const Args& a) -> CommandResult {
int idx = int(argNumber(a, "index", -1));
if (idx < -1 || idx >= int(doc.mesh.layers.size())) return {false, "No layer " + std::to_string(idx)};
doc.activeLayer = idx;
return {true, idx < 0 ? "Sculpting on base mesh" : "Sculpting on layer " + doc.mesh.layers[idx].name};
}});
add({"decimate",
"Reduce triangle count while preserving shape (quadric edge collapse). Sculpt layers are kept.",
{{"ratio", T::Number, "Fraction of triangles to keep (0.01-1). Default 0.5.", false},
{"triangles", T::Number, "Exact target triangle count (overrides ratio).", false},
{"keep_masked", T::Bool, "Keep masked: masked vertices aren't moved or removed, so masked areas keep their "
"triangles exactly. Default false.", false}},
[](Document& doc, const Args& a) -> CommandResult {
size_t target = a.contains("triangles")
? size_t(std::max(4.0, argNumber(a, "triangles", 4)))
: size_t(double(doc.mesh.triangleCount()) *
std::clamp(argNumber(a, "ratio", 0.5), 0.01, 1.0));
doc.replaceMeshUndoable(decimate(doc.mesh, target, argBool(a, "keep_masked", false)), "Decimate");
return {true, "Decimated to " + std::to_string(doc.mesh.triangleCount()) + " triangles"};
}});
add({"export_glb",
"Export a game-ready binary glTF (.glb), one node and mesh per visible Part (linked copies: one mesh, a node "
"each). Sculpt layers become "
"morph targets (blend shapes). UVs are kept and Part textures are embedded. A baked face take "
"(face_take_bake) becomes an animation of the morph target weights.",
{{"path", T::String, "Output .glb path (UTF-8).", true}},
[](Document& doc, const Args& a) -> CommandResult {
std::string path = argString(a, "path");
std::string err;
const auto objects = visiblePartObjects(doc, true); // (linked copies, #94: one mesh, placed each)
if (objects.empty()) return {false, "Nothing visible to export"};
MorphAnimation take;
const bool animated = bakedFaceAnimation(doc, take);
if (!saveGlb(path, objects, doc.assetName(), err, animated ? &take : nullptr)) return {false, err};
return {true, "Exported " + path + objectCountText(objects) + (animated ? " with the take '" + take.name + "'" : "")};
}});
add({"export_usd",
"Export OpenUSD (.usda text, or .usdz package for AR Quick Look / Vision Pro), one Mesh prim per visible "
"Part (linked copies: instanceable prims referencing the first). Sculpt layers become "
"UsdSkel blend shapes with their current weights; loaded Gaussian splats are included as a "
"ParticleField3DGaussianSplat prim. UVs are kept; a Part's texture becomes a UsdPreviewSurface texture "
"(packed into .usdz, else a PNG beside the file). A baked face take (face_take_bake) becomes time samples "
"of the blend shape weights.",
{{"path", T::String, "Output .usda, .usd or .usdz path (UTF-8).", true},
{"splats", T::Bool, "Include the loaded Gaussian splats. Default true.", false}},
[](Document& doc, const Args& a) -> CommandResult {
std::string path = argString(a, "path");
std::string err;
const SplatCloud* splats = argBool(a, "splats", true) && !doc.splats.empty() ? &doc.splats : nullptr;
const auto objects = visiblePartObjects(doc, true); // (linked copies, #94: one mesh, placed each)
MorphAnimation take;
const bool animated = bakedFaceAnimation(doc, take);
if (!saveUsd(path, objects, splats, doc.assetName(), err, animated ? &take : nullptr)) return {false, err};
return {true, "Exported " + path + objectCountText(objects) +
(splats ? " (mesh + " + std::to_string(splats->size()) + " splats)" : "") +
(animated ? " with the take '" + take.name + "'" : "")};
}});
add({"export_fbx",
"Export binary FBX, one model per visible Part: sculpt layers become blend shapes; with lods > 1 each "
"Part's LOD chain is written as an FBX LOD group in the same file. UVs are kept; a Part's texture is "
"written as a PNG beside the file and used by its material.",
{{"path", T::String, "Output .fbx path (UTF-8).", true},
{"lods", T::Number, "LOD levels including LOD0 (1-8). Default 1.", false},
{"ratio", T::Number, "Triangle ratio between LODs (0.1-0.9). Default 0.5.", false},
{"scale", T::Number, "Multiply positions (FBX units are centimetres). Default 100 (1 unit = 1 m).", false}},
[](Document& doc, const Args& a) -> CommandResult {
const int levels = std::clamp(int(argNumber(a, "lods", 1)), 1, 8);
const auto objects = visiblePartObjects(doc);
if (objects.empty()) return {false, "Nothing visible to export"};
// One model per visible Part; with lods > 1 each gets its own LOD group (see FbxIO.h).
std::vector<std::vector<Mesh>> lods(objects.size());
std::vector<FbxObject> fbxObjects;
for (size_t i = 0; i < objects.size(); ++i) {
FbxObject fo{objects[i].name, {objects[i].mesh}};
if (levels > 1) {
lods[i] = generateLods(*objects[i].mesh, levels, float(std::clamp(argNumber(a, "ratio", 0.5), 0.1, 0.9)));
fo.lods.clear();
for (const auto& l : lods[i]) fo.lods.push_back(&l);
}
fbxObjects.push_back(std::move(fo));
}
FbxExportOptions o;
o.scale = float(argNumber(a, "scale", 100.0));
std::string err;
const std::string path = argString(a, "path");
if (!saveFbx(path, fbxObjects, o, err)) return {false, err};
return {true, "Exported " + path + objectCountText(objects)};
}});
add({"export_unreal",
"Export an Unreal Engine-ready FBX: centimetres, SM_/SK_ naming, LOD chain packed for automatic LOD "
"import; a sculpt with layers becomes a skeletal mesh with morph targets. Every visible Part is its own "
"model (Unreal's Combine Meshes makes them one asset).",
{{"folder", T::String, "Output folder (UTF-8). The file is named after the asset.", true},
{"name", T::String, "Asset name (default SM_<document> or SK_<document>).", false},
{"height_cm", T::Number, "Model height in Unreal, in cm. Default: 1 unit = 1 m.", false},
{"lods", T::Number, "LOD levels for static meshes (1-8). Default 4.", false},
{"ratio", T::Number, "Triangle ratio between LODs (0.1-0.9). Default 0.5.", false}},
[](Document& doc, const Args& a) -> CommandResult {
UnrealExportOptions o;
o.folder = argString(a, "folder");
o.assetName = argString(a, "name");
o.heightCm = float(argNumber(a, "height_cm", 0.0));
o.lods = int(argNumber(a, "lods", 4));
o.ratio = float(argNumber(a, "ratio", 0.5));
UnrealExportResult r;
std::string err;
if (!exportForUnreal(doc, o, r, err)) return {false, err};
size_t morphs = 0;
for (const auto& obj : visiblePartObjects(doc)) morphs += obj.mesh->layers.size();
return {true, "Exported " + r.path + " (" + (r.skeletal ? "skeletal mesh, " + std::to_string(morphs) + " morph targets"
: "static mesh, " + std::to_string(r.lodCount) + " LODs") + ")"};
}});
add({"export_lods",
"Generate a LOD chain of every visible Part and export each level as <name>_LOD<n>.glb next to `path`. "
"Blend shapes are kept on every LOD.",
{{"path", T::String, "Base output path, e.g. /assets/rock.glb.", true},
{"levels", T::Number, "Number of LODs including LOD0 (1-8). Default 4.", false},
{"ratio", T::Number, "Triangle ratio between consecutive LODs (0.1-0.9). Default 0.5.", false}},
[](Document& doc, const Args& a) -> CommandResult {
const std::string pathArg = argString(a, "path");
std::filesystem::path base(std::u8string(pathArg.begin(), pathArg.end()));
int levels = std::clamp(int(argNumber(a, "levels", 4)), 1, 8);
float ratio = float(std::clamp(argNumber(a, "ratio", 0.5), 0.1, 0.9));
const auto objects = visiblePartObjects(doc);
if (objects.empty()) return {false, "Nothing visible to export"};
// Every visible Part is decimated on its own; LOD n of each goes into <name>_LOD<n>.glb.
std::vector<std::vector<Mesh>> lods;
for (const auto& o : objects) {
lods.push_back(generateLods(*o.mesh, levels, ratio));
// Decimation keeps the UVs, so every level can carry the Part's texture.
for (auto& l : lods.back()) l.texture = o.mesh->texture;
}
auto stemU8 = base.stem().u8string();
std::string stem(stemU8.begin(), stemU8.end());
std::ostringstream msg;
msg << "Exported";
for (size_t i = 0; i < lods[0].size(); ++i) {
std::string fileName = stem + "_LOD" + std::to_string(i) + ".glb";
auto out = (base.parent_path() / std::u8string(fileName.begin(), fileName.end())).u8string();
std::string outPath(out.begin(), out.end());
std::string err;
std::vector<MeshObjectRef> level;
size_t tris = 0;
for (size_t k = 0; k < objects.size(); ++k) {
const Mesh& l = lods[k][std::min(i, lods[k].size() - 1)];
level.push_back({objects.size() == 1 ? stem + "_LOD" + std::to_string(i) : objects[k].name, &l});
tris += l.triangleCount();
}
if (!saveGlb(outPath, level, stem + "_LOD" + std::to_string(i), err)) return {false, err};
msg << " LOD" << i << " (" << tris << " tris)";
}
return {true, msg.str()};
}});
{
// brush_create takes every recipe parameter, so AI tool calls and scripts can design brushes.
std::vector<ParamSpec> params = {{"name", T::String, "Brush name.", true},
{"description", T::String, "What the brush is for.", false}};
for (const auto& rp : recipeParams()) {
T type = rp.kind == RecipeParam::Kind::Float ? T::Number
: rp.kind == RecipeParam::Kind::Bool ? T::Bool
: T::String;
params.push_back({rp.key, type, rp.help, false});
}
params.push_back({"connectedOnly", T::Bool,
"Only reach the surface joined to the point under the cursor (the other leg, the next finger "
"stay). Default false.",
false});
params.push_back({"viewFalloff", T::Bool,
"Measure the falloff on screen: a cylinder through the model along the view. Default false.",
false});
add({"brush_create",
"Create (or update, by name) a custom sculpting brush from a recipe and make it the active brush. "
"Omitted parameters use neutral defaults.",
params, [](Document& doc, const Args& a) -> CommandResult {
Json j = Json::object();
for (const auto& [key, value] : a) {
if (auto* d = std::get_if<double>(&value)) j.set(key, *d);
else if (auto* b = std::get_if<bool>(&value)) j.set(key, *b);
else j.set(key, std::get<std::string>(value));
}
doc.activeBrush = doc.addBrush(BrushRecipe::fromJson(j));
return {true, "Brush '" + doc.brushes[doc.activeBrush].name + "' ready"};
}});
}
add({"brush_list", "List the custom brushes in the library (brush_library also shows their files).", {},
[](Document& doc, const Args&) -> CommandResult {
std::string out;
for (size_t i = 0; i < doc.brushes.size(); ++i)
out += (i ? "\n" : "") + std::to_string(i) + ": " + doc.brushes[i].name + " [" +
brushSourceName(doc.brushes[i].origin.source) +
(doc.brushes[i].origin.pack.empty() ? "" : ", " + doc.brushes[i].origin.pack) + "] - " +
doc.brushes[i].description;
return {true, out};
}});
add({"brush_use", "Make a custom brush (a built-in pack brush, one from the library or a pack) the active brush.",
{{"name", T::String, "Brush name, as brush_list shows it (case doesn't matter).", true}},
[](Document& doc, const Args& a) -> CommandResult {
auto low = [](std::string t) {
for (char& c : t) c = char(std::tolower(static_cast<unsigned char>(c)));
return t;
};
const std::string want = low(argString(a, "name"));
for (size_t i = 0; i < doc.brushes.size(); ++i)
if (low(doc.brushes[i].name) == want) {
doc.activeBrush = int(i);
return {true, "Brush: " + doc.brushes[i].name};
}
return {false, "No such brush: " + argString(a, "name") + " (brush_list shows them)"};
}});
add({"brush_save", "Save a custom brush as a shareable .sfbrush file.",
{{"path", T::String, "Output .sfbrush path.", true},
{"name", T::String, "Brush name (defaults to the active brush).", false}},
[](Document& doc, const Args& a) -> CommandResult {
std::string name = argString(a, "name");
const BrushRecipe* r = nullptr;
for (const auto& b : doc.brushes)
if (b.name == name) r = &b;
if (!r && name.empty() && doc.activeBrush >= 0) r = &doc.brushes[doc.activeBrush];
if (!r) return {false, "No such brush: " + name};
std::string err;
if (!r->save(argString(a, "path"), err)) return {false, err};
return {true, "Saved brush '" + r->name + "'"};
}});
add({"brush_load", "Load a .sfbrush file for this session and make it active (brush_install keeps it in your library).",
{{"path", T::String, ".sfbrush path.", true}},
[](Document& doc, const Args& a) -> CommandResult {
BrushRecipe r;
std::string err;
if (!BrushRecipe::load(argString(a, "path"), r, err)) return {false, err};
doc.activeBrush = doc.addBrush(std::move(r));
return {true, "Loaded brush '" + doc.brushes[doc.activeBrush].name + "'"};
}});
registerBrushLibraryCommands(*this); // brush_install, brush_code, brush_delete, ... (BrushLibrary.cpp)
registerBrushCommands(*this); // brush_set_alpha (BrushAlpha.cpp)
registerStencilCommands(*this); // stencil_load, stencil_set, stencil_clear (Stencil.cpp)
registerVdmCommands(*this); // vdm_set, vdm_capture, vdm_stamp, ... (Vdm.cpp)
registerKelvinletCommands(*this); // kelvinlet_settings (Kelvinlet.cpp)
registerCaptureCommands(*this); // capture_alpha, capture_vdm: alpha / VDM from the viewport (ViewCapture.cpp)
registerRetopoCommands(*this); // qremesh, project_all (RetopoCommands.cpp)
registerQRemeshGuideCommands(*this); // qremesh_guide, ... (QRemeshGuides.cpp)
registerForgeSphereCommands(*this); // Forge Sphere_new, ... (Forge Spheres.cpp)
registerTubeCommands(*this); // tube_new, ... (Tube.cpp)
registerAgentTools(*this); // blockout, measure, scene_overview (core/AgentTools.cpp)
registerDeformCommands(*this); // deform_polish, deform_relax, deform_smooth, deform_balloon (Deform.cpp)
add({"stroke",
"Apply a brush along a path on the active Part, like dragging the cursor in the viewport (one undo "
"step). Each point is projected onto the surface along the view direction, so points drawn in the "
"camera's plane give a screen-space stroke. Used for scripted detailing and brush preview renders.",
{{"points", T::String,
"World-space path: \"x,y,z x,y,z ...\" (or separated by '|'). One point stamps a single dab.", true},
{"brush", T::String,
"Custom brush (library name) or built-in brush (Standard, Clay, Crease, Inflate, ...). Default: the "
"active brush.",
false},
{"view", T::String, "Direction the path is projected along, \"x,y,z\" (default 0,0,-1: front view).", false},
{"radius", T::Number, "Brush radius in world units (default 4% of the mesh size).", false},
{"strength", T::Number, "Strength 0-1 (default 0.5).", false},
{"pressure", T::Number, "Constant pen pressure 0-1 (default 1).", false},
{"invert", T::Bool, "Invert the brush (carve instead of build, like holding Alt).", false},
{"curve", T::Bool, "Smooth curve through the points (default true); false = straight segments.", false},
{"spacing", T::Number, "Dab spacing as a fraction of the radius (default: the brush's own).", false},
{"symmetry", T::String, "Mirror axes, e.g. \"x\" or \"xz\" (default none).", false},
{"seed", T::Number, "Random seed for brush jitter (default 1).", false}},
[](Document& doc, const Args& a) -> CommandResult {
PathStroke st;
std::string err;
if (!parsePathPoints(argString(a, "points"), st.points, err)) return {false, err};
const std::string view = argString(a, "view");
if (!view.empty() && !parseVec3(view, st.view)) return {false, "Bad view '" + view + "' (expected x,y,z)"};
st.radius = float(argNumber(a, "radius", 0.0));
st.strength = float(argNumber(a, "strength", 0.5));
st.pressure = float(argNumber(a, "pressure", 1.0));
st.invert = argBool(a, "invert", false);
st.curve = argBool(a, "curve", true);
st.spacing = float(argNumber(a, "spacing", -1.0));
st.seed = uint32_t(std::max(argNumber(a, "seed", 1.0), 0.0));
if (!symmetryArg(a, doc.mesh, st.symmetry, err)) return {false, err};
if (const Part& part = doc.activePartInfo(); part.moved()) { // a moved linked copy (#94): into its space
const glm::mat4 inv = glm::inverse(part.transform);
const float scale = glm::length(glm::vec3(part.transform[0]));
for (auto& p : st.points) p = glm::vec3(inv * glm::vec4(p, 1.0f));
const glm::vec3 view = glm::mat3(inv) * st.view;
if (glm::length(view) > 0.0f) st.view = glm::normalize(view);
if (scale > 0.0f) st.radius /= scale;
}
// Resolve the brush: a library recipe (exact name, then any case), then a built-in type.
const std::string name = argString(a, "brush");
auto lower = [](std::string s) {
std::transform(s.begin(), s.end(), s.begin(), [](unsigned char c) { return char(std::tolower(c)); });
return s;
};
const BrushRecipe* recipe = nullptr;
BrushType type = BrushType::Standard;
if (name.empty()) {
if (doc.activeBrush >= 0 && doc.activeBrush < int(doc.brushes.size())) recipe = &doc.brushes[doc.activeBrush];
} else {
for (const auto& b : doc.brushes)
if (b.name == name) recipe = &b;
for (const auto& b : doc.brushes)
if (!recipe && lower(b.name) == lower(name)) recipe = &b;
if (!recipe) {
if (!brushFromName(name, type)) return {false, "No such brush: " + name}; // stored name or label
}
}
const int dabs = strokePath(doc, recipe, type, st, err);
if (dabs < 0) return {false, err};
if (dabs == 0) return {false, "The path never crosses the surface (check the points and view)"};
return {true, "Stroked " + std::to_string(dabs) + " dabs with " + (recipe ? recipe->name : brushLabel(type))};
}});
add({"splat_info", "Report the loaded Gaussian splats.", {},
[](Document& doc, const Args&) -> CommandResult {
if (doc.splats.empty()) return {true, "No splats loaded"};
const AABB b = doc.splats.bounds(0.98f);
std::ostringstream s;
s << doc.splats.size() << " splats, SH degree " << doc.splats.shDegree << ", main body ("
<< b.min.x << ", " << b.min.y << ", " << b.min.z << ") - (" << b.max.x << ", " << b.max.y << ", " << b.max.z << ")";
return {true, s.str()};
}});
add({"splat_save",
"Save the loaded Gaussian splats: .ply (standard 3DGS layout, e.g. for SuperSplat/Postshot), .splat (compact web viewers), .glb "
"(glTF KHR_gaussian_splatting) or .usda/.usdz (OpenUSD ParticleField3DGaussianSplat).",
{{"path", T::String, "Output path (UTF-8).", true}},
[](Document& doc, const Args& a) -> CommandResult {
if (doc.splats.empty()) return {false, "No splats loaded"};
const std::string path = argString(a, "path");
const std::string ext = lowerExtension(path);
std::string err;
bool ok = ext == ".ply" ? saveSplatPly(path, doc.splats, err)
: ext == ".splat" ? saveDotSplat(path, doc.splats, err)
: ext == ".glb" ? saveSplatGlb(path, doc.splats, err)
: (ext == ".usda" || ext == ".usd" || ext == ".usdz")
? saveUsd(path, nullptr, &doc.splats, doc.assetName(), err)
: (err = "Use a .ply, .splat, .glb, .usda or .usdz file name", false);
if (!ok) return {false, err};
return {true, "Saved " + std::to_string(doc.splats.size()) + " splats to " + path};
}});
add({"splat_clean", "Remove faint splats and outlying floaters from a capture.",
{{"min_opacity", T::Number, "Remove splats fainter than this (0-1). Default 0.05.", false},
{"keep", T::Number, "Fraction of the capture to keep per axis, trimming outliers (0.5-1). Default 0.98.", false}},
[](Document& doc, const Args& a) -> CommandResult {
if (doc.splats.empty()) return {false, "No splats loaded"};
const size_t removed = cleanSplats(doc.splats, float(std::clamp(argNumber(a, "min_opacity", 0.05), 0.0, 1.0)),
float(std::clamp(argNumber(a, "keep", 0.98), 0.5, 1.0)));
doc.splatsChanged();
return {true, "Removed " + std::to_string(removed) + " splats, " + std::to_string(doc.splats.size()) + " left"};
}});
add({"splat_transform",
"Turn and place the splats (captures are often upside down or off-centre). Rotations are in degrees "
"about the capture's centre, applied X then Y then Z.",
{{"rotate_x", T::Number, "Degrees about X (180 flips an upside-down capture).", false},
{"rotate_y", T::Number, "Degrees about Y.", false},
{"rotate_z", T::Number, "Degrees about Z.", false},
{"fit", T::Bool, "Centre at the origin and scale to the size of a new sphere.", false},
{"reset", T::Bool, "Undo all placement first.", false}},
[](Document& doc, const Args& a) -> CommandResult {
if (doc.splats.empty()) return {false, "No splats loaded"};
if (argBool(a, "reset", false)) doc.splats.transform = glm::mat4(1.0f);
rotateSplats(doc.splats, glm::vec3(float(argNumber(a, "rotate_x", 0)), float(argNumber(a, "rotate_y", 0)),
float(argNumber(a, "rotate_z", 0))));
if (argBool(a, "fit", false)) fitSplats(doc.splats);
doc.splatsChanged();
return {true, "Splats placed"};
}});
// splat_to_mesh (Make sculptable) and face_guides: core/Sculptable.cpp.
add({"mesh_to_splats",
"Turn the visible Parts into Gaussian splats (flat oriented surfels with baked clay shading), replacing any "
"loaded splats - for splat viewers, web scenes and engines that render 3DGS.",
{{"count", T::Number, "Number of splats (1000-5000000). Default 250000.", false},
{"shading", T::Bool, "Bake soft lighting and cavity darkening into the colour. Default true.", false}},
[](Document& doc, const Args& a) -> CommandResult {
Mesh merged; // no copy for a single Part
const Mesh& visible = doc.partCount() == 1 ? doc.mesh : (merged = mergedVisibleMesh(doc));
if (visible.triangleCount() == 0) return {false, "The mesh is empty"};
MeshToSplatsOptions o;
o.count = size_t(std::clamp(argNumber(a, "count", 250000), 1000.0, 5000000.0));
o.shading = argBool(a, "shading", true);
doc.splats = meshToSplats(visible, o);
doc.splats.name = doc.assetName();
doc.splatsChanged();
return {true, "Made " + std::to_string(doc.splats.size()) + " splats from the sculpt"};
}});
add({"splat_clear", "Remove the loaded Gaussian splats.", {},
[](Document& doc, const Args&) -> CommandResult {
doc.splats.clear();
doc.splatsChanged();
return {true, "Splats cleared"};
}});
add({"undo", "Undo the last action.", {},
[](Document& doc, const Args&) -> CommandResult {
if (!doc.undo.undo(doc.mesh, doc.bvh)) return {false, "Nothing to undo"};
if (UndoRecord* r = doc.undo.lastRedo(); r && r->part) doc.applyPartStep(*r->part);
doc.modified = true;
return {true, "Undone"};
}});
add({"redo", "Redo the last undone action.", {},
[](Document& doc, const Args&) -> CommandResult {
if (!doc.undo.redo(doc.mesh, doc.bvh)) return {false, "Nothing to redo"};
if (UndoRecord* r = doc.undo.lastUndo(); r && r->part) doc.applyPartStep(*r->part);
doc.modified = true;
return {true, "Redone"};
}});
add({"mesh_info", "Report vertex/triangle counts and bounding box of the mesh.", {},
[](Document& doc, const Args&) -> CommandResult {
AABB b = doc.mesh.bounds();
std::ostringstream s;
s << doc.mesh.vertexCount() << " vertices, " << doc.mesh.triangleCount() << " triangles";
if (b.valid())
s << ", bounds (" << b.min.x << ", " << b.min.y << ", " << b.min.z << ") - (" << b.max.x << ", "
<< b.max.y << ", " << b.max.z << ")";
return {true, s.str()};
}});
registerMaskingCommands(*this);
registerCutCommands(*this); // cut (core/Cut.h)
registerCloseHolesCommands(*this); // close_holes (core/CloseHoles.h)
registerBackdropCommands(*this); // remove_flat_background (core/Backdrop.h)
registerFaceGroupCommands(*this);
registerSelectionSetCommands(*this); // selection_set_* (core/SelectionSets.h)
registerPartCommands(*this);
registerSubdivCommands(*this); // subdiv_* (core/MultiresCommands.cpp)
registerMicroCommands(*this); // micro_* (core/MicroCommands.cpp)
registerDyntopoCommands(*this); // dyntopo (core/DyntopoCommands.cpp)
registerSculptableCommands(*this); // splat_to_mesh, face_guides (core/Sculptable.h)
registerTransformCommands(*this); // transform (core/MeshTransform.h)
registerExtractMirrorCommands(*this); // extract, mirror_and_weld, mirror (core/ExtractMirror.h)
registerMeshCheckCommands(*this); // weld_points, mesh_check, mesh_fix (core/MeshCheck.h)
registerPerformanceCommands(*this); // perf_info, set_multithreading (core/Benchmark.cpp)
registerHardwareProfileCommands(*this); // performance_profile, calibrate, set_performance_override (core/HardwareProfile.cpp)
registerTimelineCommands(*this); // timeline_info / seek / select / retune / save / load (core/Timeline.h)
registerPaintCommands(*this); // core/Vertex paint.cpp
registerBridgeCommands(*this); // bridge_import/export/send/receive, export_stl (io/BridgeCommands.cpp)
registerBlenderCommands(*this); // blender_send/receive (io/BlenderCommands.cpp)
registerMayaCommands(*this); // maya_send/receive (io/MayaCommands.cpp)
registerBakeCommands(*this); // bake (core/Bake.cpp)
registerGarmentCommands(*this); // garment_* (core/GarmentCommands.cpp)
registerFaceCommands(*this); // face_shapes_generate, face_weights, ... (core/FaceCommands.cpp)
registerStarterMeshCommands(*this); // new_starter_mesh (core/StarterMeshes.h)
registerPackCommands(*this); // pack_install, pack_list, pack_remove, ... (core/Pack.h)
registerMacroCommands(*this); // macro_run, macro_list, macro_check (core/Macro.h)
registerProjectCommands(*this); // keep last (core/Project.cpp)
}
void CommandRegistry::remove(const std::string& name) {
commands_.erase(std::remove_if(commands_.begin(), commands_.end(), [&](const Command& c) { return c.name == name; }),
commands_.end());
}
void CommandRegistry::add(Command cmd) {
// The commands that follow the brushes' symmetry take radial and local symmetry too (#63).
static const char* const kSymmetric[] = {"stroke", "vdm_stamp", "mask_rect", "mask_lasso", "hide_rect",
"hide_lasso", "insert_primitive", "insert_mesh", "cut"};
for (const char* name : kSymmetric)
if (cmd.name == name)
for (ParamSpec& p : radialSymmetryParams()) cmd.params.push_back(std::move(p));
commands_.push_back(std::move(cmd));
}
const Command* CommandRegistry::find(const std::string& name) const {
for (const auto& c : commands_)
if (c.name == name) return &c;
if (legacy::isOld(name)) return find(legacy::modernize(name)); // a script or macro from an older version
return nullptr;
}
namespace {
// A value an older version's script may have used as a name (layout=..., mode=..., id=...): letters, digits, '_'
// and '-' only, so paths and a user's own text are never rewritten.
bool oldNameValue(const ArgValue& v) {
const std::string* s = std::get_if<std::string>(&v);
if (!s || s->empty() || s->size() > 64) return false;
for (unsigned char c : *s)
if (!std::isalnum(c) && c != '_' && c != '-') return false;
return legacy::isOld(*s);
}
// Args from an older version's script: parameter names, and (values) old name values.
Args modernizedArgs(const Args& args, bool values) {
Args out;
for (const auto& [k, v] : args)
out[legacy::modernize(k)] = values && oldNameValue(v) ? ArgValue(legacy::modernize(std::get<std::string>(v))) : v;
return out;
}
bool anyOldValue(const Args& args) {
for (const auto& [k, v] : args)
if (oldNameValue(v)) return true;
return false;
}
} // namespace
CommandResult CommandRegistry::execute(Document& doc, const std::string& name, const Args& givenArgs) const {
const Command* cmd = find(name);
if (!cmd) return {false, "Unknown command: " + name};
bool oldKeys = false;
for (const auto& [k, v] : givenArgs) oldKeys = oldKeys || legacy::isOld(k);
const Args renamedKeys = oldKeys ? modernizedArgs(givenArgs, false) : Args{};
const Args& args = oldKeys ? renamedKeys : givenArgs;
for (const auto& p : cmd->params)
if (p.required && !args.contains(p.name)) return {false, "Missing required argument: " + p.name};
doc.notice.clear();
// Extract's preview lasts until Accept or until anything else changes the scene; saving or
// exporting never writes it.
if (doc.extractPreview.id && name.rfind("extract", 0) != 0)
doc.dropExtractPreview(!(name.rfind("save", 0) == 0 || name.rfind("export", 0) == 0));
CommandResult r = cmd->run(doc, args);
if (!r.ok && anyOldValue(args)) // a name value an older version used: try today's; keep the first answer if it fails too
if (CommandResult again = cmd->run(doc, modernizedArgs(args, true)); again.ok) r = std::move(again);
if (const std::string notice = doc.takeNotice(); !notice.empty() && r.ok) r.message += ". " + notice;
return r;
}
std::string CommandRegistry::toolSchemaJson() const {
std::ostringstream s;
s << "[";
for (size_t i = 0; i < commands_.size(); ++i) {
const auto& c = commands_[i];
s << (i ? "," : "") << "{\"name\":\"" << jsonEscape(c.name) << "\",\"description\":\""
<< jsonEscape(c.description) << "\",\"input_schema\":{\"type\":\"object\",\"properties\":{";
std::vector<std::string> required;
for (size_t j = 0; j < c.params.size(); ++j) {
const auto& p = c.params[j];
const char* type = p.type == ParamSpec::Type::Bool ? "boolean"
: p.type == ParamSpec::Type::Number ? "number"
: "string";
s << (j ? "," : "") << "\"" << jsonEscape(p.name) << "\":{\"type\":\"" << type
<< "\",\"description\":\"" << jsonEscape(p.description) << "\"}";
if (p.required) required.push_back(p.name);
}
s << "},\"required\":[";
for (size_t j = 0; j < required.size(); ++j) s << (j ? "," : "") << "\"" << jsonEscape(required[j]) << "\"";
s << "]}}";
}
s << "]";
return s.str();
}
} // namespace sf