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 "ai/SplatTrainer.h"
#include "ai/Http.h"
#include "ai/Process.h"
#include "core/BrushLibrary.h"
#include "core/Commands.h"
#include "core/Json.h"
#include "core/Sha256.h"
#include "io/PlyIO.h"
#include <algorithm>
#include <chrono>
#include <cstdlib>
#include <filesystem>
#include <fstream>
#include <sstream>
namespace sf::ai {
namespace fs = std::filesystem;
using namespace sf::capture;
namespace {
fs::path u8path(const std::string& s) { return fs::path(std::u8string(s.begin(), s.end())); }
std::string pathString(const fs::path& p) {
const auto s = p.u8string();
return std::string(s.begin(), s.end());
}
double nowSeconds() {
return std::chrono::duration<double>(std::chrono::steady_clock::now().time_since_epoch()).count();
}
void sleepSeconds(double s) { std::this_thread::sleep_for(std::chrono::milliseconds(int(s * 1000.0))); }
std::string envValue(const char* name) {
const char* v = std::getenv(name);
return v ? std::string(v) : std::string();
}
bool readFile(const std::string& path, std::string& out) {
std::ifstream f(u8path(path), std::ios::binary);
if (!f) return false;
std::stringstream ss;
ss << f.rdbuf();
out = ss.str();
return true;
}
// The last `lines` lines of a log, for error messages.
std::string logTail(const std::string& path, int lines) {
std::string text;
if (!readFile(path, text)) return {};
while (!text.empty() && (text.back() == '\n' || text.back() == '\r')) text.pop_back();
size_t pos = text.size();
for (int i = 0; i < lines && pos != std::string::npos && pos > 0; ++i) pos = text.rfind('\n', pos - 1);
return pos == std::string::npos ? text : text.substr(pos + 1);
}
// "[12/80]" style progress anywhere in the text: the last one.
float bracketProgress(const std::string& text) {
for (size_t p = text.rfind('['); p != std::string::npos; p = p ? text.rfind('[', p - 1) : std::string::npos) {
int a = 0, b = 0;
if (std::sscanf(text.c_str() + p, "[%d/%d]", &a, &b) == 2 && b > 0) return std::clamp(float(a) / float(b), 0.0f, 1.0f);
if (p == 0) break;
}
return -1.0f;
}
std::string toolInDir(const fs::path& dir, const std::string& exe) {
std::error_code ec;
if (!fs::is_directory(dir, ec)) return {};
for (fs::recursive_directory_iterator it(dir, ec), end; !ec && it != end; it.increment(ec))
if (it->is_regular_file(ec) && it->path().filename() == u8path(exe)) return pathString(it->path());
return {};
}
std::string firstOnPath(std::initializer_list<const char*> names) {
for (const char* n : names)
if (std::string p = findOnPath(n); !p.empty()) return p;
return {};
}
std::string captureName(const std::string& source) {
fs::path p = u8path(source);
while (!p.empty() && p.filename().empty()) p = p.parent_path(); // trailing separator
std::error_code ec;
const std::string name = pathString(fs::is_directory(p, ec) ? p.filename() : p.stem());
return name.empty() ? std::string("capture") : name;
}
} // namespace
// --- Settings ---
std::string defaultSplatTrainSettingsPath() { return pathString(u8path(appDataDir()) / "splat_train.json"); }
std::string splatToolsDir() { return pathString(u8path(appDataDir()) / "tools"); }
SplatTrainSettings SplatTrainSettings::load(const std::string& path) {
SplatTrainSettings s;
std::string text, error;
Json j;
if (!readFile(path, text) || !Json::parse(text, j, error) || !j.isObject()) return s;
if (j["brush"].isString()) s.brushPath = j["brush"].asString();
if (j["colmap"].isString()) s.colmapPath = j["colmap"].asString();
if (j["ffmpeg"].isString()) s.ffmpegPath = j["ffmpeg"].asString();
if (j["preset"].isString()) s.preset = j["preset"].asString();
s.copyToLibrary = j["copy_to_library"].asBool(true);
return s;
}
bool SplatTrainSettings::save(const std::string& path) const {
Json j = Json::object();
j.set("brush", brushPath);
j.set("colmap", colmapPath);
j.set("ffmpeg", ffmpegPath);
j.set("preset", preset);
j.set("copy_to_library", copyToLibrary);
std::error_code ec;
fs::create_directories(u8path(path).parent_path(), ec);
std::ofstream f(u8path(path), std::ios::binary);
f << j.dump(true);
return bool(f);
}
// --- Tools ---
const ToolDownload* brushDownload() {
// Brush v0.3.0 (2025-09-14); hashes from the release's sha256.sum.
#if defined(_WIN32) && (defined(_M_X64) || defined(__x86_64__))
static const ToolDownload d{"Brush", "0.3.0",
"https://github.com/ArthurBrussee/brush/releases/download/v0.3.0/brush-app-x86_64-pc-windows-msvc.zip",
"b68e3e9cf052d51bf3ee30776fa5a364de7f2ba13b58443128ff797bb7bcfcd6", 158791348, "brush_app.exe",
"brush-0.3.0", "Apache-2.0", "https://github.com/ArthurBrussee/brush"};
return &d;
#elif defined(__APPLE__) && defined(__aarch64__)
static const ToolDownload d{"Brush", "0.3.0",
"https://github.com/ArthurBrussee/brush/releases/download/v0.3.0/brush-app-aarch64-apple-darwin.tar.xz",
"65b2631398c839be3c1d4d7160fe2326389dec87830aac0710985e6690a1048c", 41447012, "brush_app",
"brush-0.3.0", "Apache-2.0", "https://github.com/ArthurBrussee/brush"};
return &d;
#elif defined(__linux__) && defined(__x86_64__)
static const ToolDownload d{"Brush", "0.3.0",
"https://github.com/ArthurBrussee/brush/releases/download/v0.3.0/brush-app-x86_64-unknown-linux-gnu.tar.xz",
"4f0f9a8785d1951c62df26aae247c02c5bba32b00f40b06df4e1c9b867399e20", 44242224, "brush_app",
"brush-0.3.0", "Apache-2.0", "https://github.com/ArthurBrussee/brush"};
return &d;
#else
return nullptr; // no prebuilt release (Linux on ARM, Intel Macs): build it with cargo and set the path
#endif
}
const ToolDownload* colmapDownload() {
#if defined(_WIN32) && (defined(_M_X64) || defined(__x86_64__))
// COLMAP 4.2.1 (2026-09-29) without CUDA (runs everywhere); hash from GitHub's asset digest.
static const ToolDownload d{"COLMAP", "4.2.1",
"https://github.com/colmap/colmap/releases/download/4.2.1/colmap-x64-windows-nocuda.zip",
"c493d88cb4a43f21afba42cb55bf786e5434a0420e73db0ba1454c5d8b3686ae", 127731595, "colmap.exe",
"colmap-4.2.1", "BSD-3-Clause", "https://github.com/colmap/colmap"};
return &d;
#else
return nullptr; // Linux: the distribution's colmap package; macOS: Homebrew (brew install colmap)
#endif
}
std::string findBrush(const SplatTrainSettings& settings) {
if (std::string e = envValue("SCULPTFORGE_BRUSH"); !e.empty()) return findOnPath(e);
if (!settings.brushPath.empty()) return findOnPath(settings.brushPath);
if (const ToolDownload* d = brushDownload())
if (std::string p = toolInDir(u8path(splatToolsDir()) / d->folder, d->exe); !p.empty()) return p;
return firstOnPath({"brush_app", "brush"});
}
std::string findColmap(const SplatTrainSettings& settings) {
if (std::string e = envValue("SCULPTFORGE_COLMAP"); !e.empty()) return findOnPath(e);
if (!settings.colmapPath.empty()) return findOnPath(settings.colmapPath);
if (const ToolDownload* d = colmapDownload())
if (std::string p = toolInDir(u8path(splatToolsDir()) / d->folder, d->exe); !p.empty()) return p;
return firstOnPath({"colmap"});
}
std::string findFfmpeg(const SplatTrainSettings& settings) {
if (std::string e = envValue("SCULPTFORGE_FFMPEG"); !e.empty()) return findOnPath(e);
if (!settings.ffmpegPath.empty()) return findOnPath(settings.ffmpegPath);
return firstOnPath({"ffmpeg"});
}
bool downloadTool(const ToolDownload& tool, std::string& exePath, std::string& error, std::atomic<float>* progress,
std::atomic<bool>* cancel) {
const fs::path dir = u8path(splatToolsDir()) / tool.folder;
std::error_code ec;
fs::create_directories(dir, ec);
if (ec) {
error = "Cannot create " + pathString(dir);
return false;
}
std::string data;
data.reserve(size_t(tool.bytes));
const HttpResponse r = httpRequestStream("GET", tool.url, {}, {}, 1800, [&](const char* p, size_t n) {
data.append(p, n);
if (progress) progress->store(std::min(0.99f, float(double(data.size()) / double(tool.bytes))));
return !(cancel && cancel->load());
});
if (cancel && cancel->load()) {
error = "Download cancelled";
return false;
}
if (r.status != 200) {
error = "Downloading " + std::string(tool.tool) + " failed: " +
(r.error.empty() ? "HTTP " + std::to_string(r.status) : r.error);
return false;
}
if (sha256Hex(data) != tool.sha256) {
error = std::string(tool.tool) + " download did not match its checksum (not installed)";
return false;
}
const std::string name = std::string(tool.url).substr(std::string(tool.url).rfind('/') + 1);
const fs::path archive = dir / u8path(name);
{
std::ofstream f(archive, std::ios::binary);
f.write(data.data(), std::streamsize(data.size()));
if (!f) {
error = "Cannot write " + pathString(archive);
return false;
}
}
data = std::string();
std::string output;
const int code = runProcess("tar", {"-xf", pathString(archive), "-C", pathString(dir)}, output,
pathString(dir / "unpack"));
fs::remove(archive, ec);
fs::remove_all(dir / "unpack", ec);
if (code != 0) {
error = "Unpacking " + std::string(tool.tool) + " failed (tar): " + output;
return false;
}
exePath = toolInDir(dir, tool.exe);
if (exePath.empty()) {
error = std::string(tool.tool) + " unpacked, but " + tool.exe + " is not in it";
return false;
}
#if !defined(_WIN32)
fs::permissions(u8path(exePath), fs::perms::owner_exec | fs::perms::group_exec | fs::perms::others_exec,
fs::perm_options::add, ec);
#endif
if (progress) progress->store(1.0f);
return true;
}
// --- The job ---
const char* trainStageName(TrainStage stage) {
switch (stage) {
case TrainStage::Idle: return "idle";
case TrainStage::Frames: return "frames";
case TrainStage::Poses: return "poses";
case TrainStage::Training: return "training";
case TrainStage::Done: return "done";
case TrainStage::Failed: return "failed";
case TrainStage::Cancelled: return "cancelled";
}
return "?";
}
std::string defaultTrainOutDir(const std::string& source) {
const fs::path p = u8path(source);
std::error_code ec;
if (fs::is_directory(p, ec)) return pathString(p / "splat");
return pathString(p.parent_path() / u8path(captureName(source) + "-splat"));
}
SplatTrainJob::~SplatTrainJob() {
cancel();
wait();
}
void SplatTrainJob::wait() {
if (worker_.joinable()) worker_.join();
}
void SplatTrainJob::cancel() { cancel_ = true; }
void SplatTrainJob::finishNow() { finish_ = true; }
TrainStatus SplatTrainJob::status() const {
std::lock_guard lock(mutex_);
TrainStatus s = status_;
if (running_) s.elapsed = nowSeconds() - startTime_;
return s;
}
std::shared_ptr<SplatCloud> SplatTrainJob::takePreview() {
std::lock_guard lock(mutex_);
return std::move(preview_);
}
void SplatTrainJob::fail(const std::string& error) {
update([&](TrainStatus& s) {
s.stage = TrainStage::Failed;
s.error = error;
s.message = error;
});
}
bool SplatTrainJob::start(const TrainRequest& request, std::string& error) {
if (running_) {
error = "A splat is already training (cancel it first)";
return false;
}
wait(); // the previous worker has ended; join it
TrainStatus s;
s.stage = TrainStage::Failed;
const SourceKind kind = classifySource(request.source);
bool posed = kind == SourceKind::NerfstudioDataset || kind == SourceKind::ColmapDataset;
if (kind == SourceKind::Images) {
CaptureInfo info;
std::string ignored;
const std::string json = pathString(u8path(request.source) / "capture.json");
posed = readCaptureJson(json, info, ignored) && !info.poses.empty();
}
if (kind == SourceKind::Missing) error = "Capture not found: " + request.source;
else if (kind == SourceKind::Unsupported)
error = "Not a capture: give a video, a folder of photos, or a COLMAP / nerfstudio dataset";
else if (request.brush.empty()) {
error = "Brush (the splat trainer) is not installed";
s.missingTrainer = true;
} else if ((kind == SourceKind::Video || kind == SourceKind::VideoFolder) && request.ffmpeg.empty()) {
error = "ffmpeg is needed to read frames from a video: install it, or train from a folder of photos";
s.missingFfmpeg = true;
} else if (!posed && request.colmap.empty()) {
error = "COLMAP is needed to find the camera positions of the photos";
s.missingPoses = true;
}
if (!error.empty()) {
s.error = s.message = error;
std::lock_guard lock(mutex_);
status_ = s;
return false;
}
cancel_ = false;
finish_ = false;
{
std::lock_guard lock(mutex_);
status_ = TrainStatus();
status_.stage = TrainStage::Frames;
status_.message = "Starting";
status_.outDir = request.outDir.empty() ? defaultTrainOutDir(request.source) : request.outDir;
preview_.reset();
}
framing_ = glm::mat4(1.0f);
startTime_ = nowSeconds();
running_ = true;
TrainRequest r = request;
if (r.outDir.empty()) r.outDir = defaultTrainOutDir(request.source);
worker_ = std::thread([this, r] {
run(r);
update([&](TrainStatus& st) { st.elapsed = nowSeconds() - startTime_; });
running_ = false;
});
return true;
}
void SplatTrainJob::run(TrainRequest r) {
std::error_code ec;
const fs::path out = u8path(r.outDir), work = out / "work";
fs::create_directories(work, ec);
if (ec) return fail("Cannot create " + pathString(work));
const SourceKind kind = classifySource(r.source);
std::string dataset;
bool needPoses = false;
if (!prepareFrames(r, kind, dataset, needPoses)) return;
if (needPoses && !findPoses(r, dataset)) return;
if (stopRequested()) {
update([](TrainStatus& s) {
s.stage = TrainStage::Cancelled;
s.message = "Cancelled";
});
return;
}
train(r, dataset);
}
bool SplatTrainJob::prepareFrames(const TrainRequest& r, SourceKind kind, std::string& dataset, bool& needPoses) {
const fs::path work = u8path(r.outDir) / "work";
const TrainPreset& preset = trainPreset(r.preset);
std::error_code ec;
needPoses = false;
if (kind == SourceKind::NerfstudioDataset || kind == SourceKind::ColmapDataset) {
dataset = r.source;
std::vector<CameraView> views;
std::string err;
const bool ok = kind == SourceKind::NerfstudioDataset
? readTransformsJson(pathString(u8path(r.source) / "transforms.json"), views, err)
: readColmapImages(pathString(u8path(r.source) / "sparse" / "0"), views, err);
if (ok) framing_ = orbitFraming(views);
update([&](TrainStatus& s) { s.frames = int(views.size()); });
return true;
}
const fs::path ds = work / "dataset", images = ds / "images";
fs::remove_all(ds, ec);
fs::create_directories(images, ec);
dataset = pathString(ds);
std::vector<std::string> frames; // candidate photos
fs::path framesDir;
CaptureInfo info;
if (kind == SourceKind::Video || kind == SourceKind::VideoFolder) {
const std::string video = kind == SourceKind::Video ? r.source : findVideo(r.source);
framesDir = work / "frames";
fs::remove_all(framesDir, ec);
fs::create_directories(framesDir, ec);
update([&](TrainStatus& s) {
s.stage = TrainStage::Frames;
s.message = "Reading frames from the video";
s.stageProgress = -1.0f;
});
const std::string log = pathString(work / "ffmpeg.log");
fs::remove(u8path(log), ec);
ChildProcess ff;
std::string err;
// 5 frames a second, at most 1600 px (phones film 4K; Brush trains at <= 1920 anyway).
if (!ff.start(r.ffmpeg,
{"-hide_banner", "-loglevel", "error", "-y", "-i", video, "-vf",
"fps=5,scale=1600:1600:force_original_aspect_ratio=decrease", "-q:v", "2",
pathString(framesDir / "%05d.jpg")},
log, {}, err)) {
fail(err);
return false;
}
while (ff.running()) {
if (stopRequested()) {
ff.kill();
break;
}
const size_t n = listImages(pathString(framesDir)).size();
update([&](TrainStatus& s) { s.message = "Reading frames from the video (" + std::to_string(n) + ")"; });
sleepSeconds(pollSeconds);
}
if (stopRequested()) return true; // run() reports the cancel
frames = listImages(pathString(framesDir));
if (ff.exitCode() != 0 || frames.empty()) {
fail("ffmpeg could not read the video: " + logTail(log, 3));
return false;
}
} else { // photos
const fs::path src = u8path(r.source);
frames = listImages(r.source);
if (frames.empty()) frames = listImages(pathString(src / "images"));
std::string ignored;
readCaptureJson(pathString(src / "capture.json"), info, ignored);
}
// The sharpest frame of each stretch (videos), or all photos up to twice the preset's frame count.
const size_t keep = kind == SourceKind::Images ? size_t(preset.maxFrames) * 2 : size_t(preset.maxFrames);
std::vector<size_t> chosen;
const bool posedPhotos = !info.poses.empty();
if (frames.size() > keep && !posedPhotos) {
std::vector<double> scores(frames.size(), 0.0);
for (size_t i = 0; i < frames.size(); ++i) {
if (stopRequested()) return true;
Image img;
std::string err;
if (Image::load(frames[i], img, err)) scores[i] = sharpness(img);
update([&](TrainStatus& s) {
s.message = "Picking the sharpest frames";
s.stageProgress = float(i + 1) / float(frames.size());
});
}
chosen = selectFrames(scores, keep);
} else {
for (size_t i = 0; i < frames.size(); ++i) chosen.push_back(i);
}
std::vector<std::string> names;
for (size_t k = 0; k < chosen.size(); ++k) {
const fs::path from = u8path(frames[chosen[k]]);
// Video frames are renumbered; photos keep their names (AR poses refer to them).
const fs::path name = framesDir.empty() ? from.filename() : u8path(std::to_string(100000 + k).substr(1) + ".jpg");
if (!framesDir.empty()) fs::rename(from, images / name, ec);
if (framesDir.empty() || ec) fs::copy_file(from, images / name, fs::copy_options::overwrite_existing, ec);
if (ec) {
fail("Cannot copy " + pathString(from) + " into the dataset");
return false;
}
names.push_back(pathString(name));
}
if (!framesDir.empty()) fs::remove_all(framesDir, ec);
update([&](TrainStatus& s) { s.frames = int(names.size()); });
if (names.size() < 3) {
fail("Only " + std::to_string(names.size()) + " usable photos: a splat needs many views (walk around the object)");
return false;
}
if (posedPhotos) { // the phone's AR tracking already knows where each photo was taken
std::vector<CameraView> views;
for (CameraView v : info.poses) {
const std::string base = pathString(u8path(v.file).filename());
if (std::find(names.begin(), names.end(), base) == names.end()) continue;
v.file = "images/" + base;
views.push_back(std::move(v));
}
std::string err;
if (views.size() >= 3 && writeTransformsJson(pathString(ds / "transforms.json"), views, err)) {
framing_ = orbitFraming(views);
return true;
}
if (r.colmap.empty()) {
fail("The capture's camera poses don't match its photos, and COLMAP is not installed");
return false;
}
}
needPoses = true;
return true;
}
bool SplatTrainJob::findPoses(const TrainRequest& r, const std::string& dataset) {
const fs::path ds = u8path(dataset), work = u8path(r.outDir) / "work";
const TrainPreset& preset = trainPreset(r.preset);
std::error_code ec;
update([&](TrainStatus& s) {
s.stage = TrainStage::Poses;
s.message = "Finding the camera positions (COLMAP)";
s.stageProgress = -1.0f;
});
const std::string log = pathString(work / "colmap.log");
fs::remove(u8path(log), ec);
const std::vector<std::string> base = {"automatic_reconstructor", "--workspace_path", dataset,
"--image_path", pathString(ds / "images"),
"--data_type", "video", // frames in order: sequential matching
"--quality", std::string(preset.steps > 10000 ? "medium" : "low"),
"--single_camera", "1", "--camera_model", "PINHOLE", "--dense", "0"};
// COLMAP 3.12+ has the global mapper (formerly GLOMAP, much faster); older versions reject the option, and a
// build without a usable GPU may need --use_gpu 0.
const std::vector<std::vector<std::string>> attempts = {{"--mapper", "global"}, {}, {"--use_gpu", "0"}};
bool ok = false;
for (const auto& extra : attempts) {
fs::remove_all(ds / "sparse", ec);
fs::remove(ds / "database.db", ec);
std::vector<std::string> args = base;
args.insert(args.end(), extra.begin(), extra.end());
ChildProcess p;
std::string err;
{
std::ofstream f(u8path(log), std::ios::app);
f << "\n$ colmap";
for (const auto& a : args) f << ' ' << a;
f << '\n';
}
if (!p.start(r.colmap, args, log, {}, err)) {
fail(err);
return false;
}
while (p.running()) {
if (stopRequested()) {
p.kill();
return true;
}
const float f = bracketProgress(logTail(log, 5));
update([&](TrainStatus& s) { s.stageProgress = f; });
sleepSeconds(pollSeconds);
}
// The model with the most photos goes to sparse/0, where Brush looks.
int best = -1;
size_t bestCount = 0;
for (int k = 0; k < 16; ++k) {
std::vector<CameraView> views;
std::string ignored;
if (readColmapImages(pathString(ds / "sparse" / std::to_string(k)), views, ignored) && views.size() > bestCount) {
best = k;
bestCount = views.size();
}
}
if (p.exitCode() == 0 && best >= 0 && bestCount >= 3) {
if (best != 0) {
fs::rename(ds / "sparse" / "0", ds / "sparse" / "unused-0", ec);
fs::rename(ds / "sparse" / std::to_string(best), ds / "sparse" / "0", ec);
}
ok = true;
break;
}
}
if (!ok) {
fail("COLMAP could not place the cameras (too few overlapping views, blur, or a shiny/plain object). "
"Log: " + log + "\n" + logTail(log, 3));
return false;
}
std::vector<CameraView> views;
std::string err;
if (readColmapImages(pathString(ds / "sparse" / "0"), views, err)) framing_ = orbitFraming(views);
update([&](TrainStatus& s) {
s.message = "Placed " + std::to_string(views.size()) + " of " + std::to_string(s.frames) + " photos";
});
return true;
}
bool SplatTrainJob::loadCheckpoint(const std::string& path, int step) {
Mesh mesh;
auto cloud = std::make_shared<SplatCloud>();
PlyContent content;
std::string err;
if (!loadPly(path, mesh, *cloud, content, err) || cloud->empty()) return false;
cloud->transform = framing_;
cloud->name = "Training";
std::lock_guard lock(mutex_);
preview_ = std::move(cloud);
++status_.previewVersion;
status_.previewStep = step;
status_.splats = int(preview_->size());
return true;
}
bool SplatTrainJob::train(const TrainRequest& r, const std::string& dataset) {
const fs::path work = u8path(r.outDir) / "work", checkpoints = work / "checkpoints";
const TrainPreset& preset = trainPreset(r.preset);
std::error_code ec;
fs::remove_all(checkpoints, ec);
fs::create_directories(checkpoints, ec);
const std::string log = pathString(work / "brush.log");
fs::remove(u8path(log), ec);
update([&](TrainStatus& s) {
s.stage = TrainStage::Training;
s.message = "Starting Brush";
s.totalSteps = preset.steps;
s.stageProgress = -1.0f;
s.logPath = log;
});
ChildProcess p;
std::string err;
if (!p.start(r.brush, brushArguments(dataset, pathString(checkpoints), preset, r.evaluate), log,
{{"RUST_LOG", "brush_cli=info,brush_process=info"}, {"NO_COLOR", "1"}}, err)) {
fail(err);
return false;
}
const double trainStart = nowSeconds();
size_t logOffset = 0;
std::string partial;
int loadedStep = -1;
bool sawError = false;
auto readLog = [&] {
std::ifstream f(u8path(log), std::ios::binary);
if (!f) return;
f.seekg(std::streamoff(logOffset));
std::string chunk((std::istreambuf_iterator<char>(f)), std::istreambuf_iterator<char>());
logOffset += chunk.size();
partial += chunk;
size_t nl;
while ((nl = partial.find('\n')) != std::string::npos) {
const std::string line = partial.substr(0, nl);
partial.erase(0, nl + 1);
TrainerLog t;
if (!parseTrainerLog(line, t)) continue;
update([&](TrainStatus& s) {
if (t.refineIter >= 0) s.step = std::max(s.step, t.refineIter);
if (t.splats >= 0) s.splats = t.splats;
if (t.evalIter >= 0) s.step = std::max(s.step, t.evalIter);
if (t.psnr > 0) s.psnr = t.psnr;
});
sawError = sawError || t.error;
}
};
// The newest checkpoint is loaded once its size holds still for a moment (Brush may still be writing it); a
// file that doesn't parse yet is tried again on the next check.
auto pollCheckpoints = [&](bool final) {
int step = -1;
const std::string path = latestCheckpoint(pathString(checkpoints), step);
if (path.empty() || step <= loadedStep) return;
update([&](TrainStatus& s) { s.step = std::max(s.step, step); });
const uintmax_t size = fs::file_size(u8path(path), ec);
if (ec || size == 0) return;
if (!final) {
sleepSeconds(std::min(0.1, pollSeconds));
if (fs::file_size(u8path(path), ec) != size || ec) return;
}
if (!loadCheckpoint(path, step)) return;
loadedStep = step;
// Older checkpoints are no longer needed (a Quality run would otherwise leave gigabytes of them).
for (fs::directory_iterator it(checkpoints, ec), end; !ec && it != end; it.increment(ec)) {
const int s = checkpointStep(pathString(it->path().filename()));
if (s >= 0 && s < step) fs::remove(it->path(), ec);
}
};
while (p.running()) {
if (stopRequested()) {
p.kill();
break;
}
readLog();
pollCheckpoints(false);
const double t = nowSeconds() - trainStart;
update([&](TrainStatus& s) {
s.message = s.step > 0 ? "Training" : "Loading the photos";
if (s.step > 0) s.eta = t / double(s.step) * double(std::max(0, s.totalSteps - s.step));
s.stageProgress = s.totalSteps > 0 ? float(s.step) / float(s.totalSteps) : -1.0f;
});
sleepSeconds(pollSeconds);
}
readLog();
if (cancel_) {
update([](TrainStatus& s) {
s.stage = TrainStage::Cancelled;
s.message = "Cancelled";
});
return false;
}
pollCheckpoints(true);
if (!finish_ && (p.exitCode() != 0 || sawError)) {
fail("Brush stopped with an error (exit " + std::to_string(p.exitCode()) + "). Log: " + log + "\n" +
logTail(log, 4));
return false;
}
int step = -1;
const std::string last = latestCheckpoint(pathString(checkpoints), step);
if (last.empty()) {
if (finish_) {
update([](TrainStatus& s) {
s.stage = TrainStage::Cancelled;
s.message = "Stopped before the first checkpoint";
});
} else {
fail("Brush finished without writing a splat. Log: " + log);
}
return false;
}
const fs::path result = u8path(r.outDir) / u8path(captureName(r.source) + ".ply");
fs::copy_file(u8path(last), result, fs::copy_options::overwrite_existing, ec);
if (ec) {
fail("Cannot write " + pathString(result));
return false;
}
update([&](TrainStatus& s) {
s.stage = TrainStage::Done;
s.result = pathString(result);
s.step = std::max(s.step, step);
s.eta = 0.0;
s.stageProgress = 1.0f;
s.message = "Trained " + std::to_string(s.splats) + " splats in " + std::to_string(step) + " steps";
});
return true;
}
// --- Commands for sculptforge-cli / Python / MCP (blocking) ---
void registerSplatTrainCommands(CommandRegistry& registry, std::function<SplatTrainSettings()> settings) {
using T = ParamSpec::Type;
registry.add({"splat_train",
"Train a Gaussian splat from a capture: a video, a folder of photos, a phone capture folder or a "
"COLMAP / nerfstudio dataset. Uses Brush (and COLMAP for camera positions, ffmpeg for video). Here "
"it waits until training ends and loads the result; the app trains in the background with a live "
"preview.",
{{"source", T::String, "The capture (video file or folder).", true},
{"out", T::String, "Folder for the result and work files. Default: next to the capture.", false},
{"preset", T::String, "fast (a quick preview) or quality. Default: the saved preset.", false}},
[settings](Document& doc, const Args& a) -> CommandResult {
const SplatTrainSettings s = settings();
TrainRequest req;
req.source = argString(a, "source");
req.outDir = argString(a, "out");
req.preset = argString(a, "preset", s.preset);
req.brush = findBrush(s);
req.colmap = findColmap(s);
req.ffmpeg = findFfmpeg(s);
SplatTrainJob job;
std::string err;
if (!job.start(req, err)) return {false, err};
job.wait();
const TrainStatus st = job.status();
if (st.stage != TrainStage::Done) return {false, st.error.empty() ? st.message : st.error};
if (auto cloud = job.takePreview()) {
doc.splats = std::move(*cloud);
doc.splats.name = captureName(req.source);
doc.splatsChanged();
}
return {true, st.message + "; saved " + st.result};
}});
registry.add({"splat_train_cancel", "Stop splat training (in the app; sculptforge-cli trains in the foreground).", {},
[](Document&, const Args&) -> CommandResult { return {true, "No splat is training"}; }});
}
} // namespace sf::ai