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/Project.h"
#include "core/LegacyNames.h"
#include "core/Micro.h"
#include "core/Timeline.h"
#include "core/Multires.h"
#include "core/LayerStack.h"
#include "core/LayerStackIO.h"
#include "core/SelectionSets.h"
#include "core/Texture.h"
#include "core/ThreadPool.h"
#include "core/ForgeSpheres.h"
#include "core/Tube.h"
#include "io/Zip.h"
#include <algorithm>
#include <atomic>
#include <bit>
#include <cctype>
#include <cmath>
#include <cstring>
#include <deque>
#include <filesystem>
#include <fstream>
#include <map>
#include <system_error>
#include <thread>
#if defined(__unix__) || defined(__APPLE__)
#include <fcntl.h>
#include <unistd.h>
#define SF_PREAD 1
#else
#define SF_PREAD 0
#endif
#ifndef SCULPTFORGE_VERSION
#define SCULPTFORGE_VERSION "unknown"
#endif
namespace sf {
namespace {
constexpr const char* kFormatName = "SculptForge project";
constexpr const char* kManifestName = "manifest.json";
constexpr const char* kThumbnailName = "thumbnail.png";
ProjectThumbnailProvider& thumbnailProvider() {
static ProjectThumbnailProvider provider;
return provider;
}
// Top-level manifest keys owned by the core (mesh, layers and active_layer are
// version 1); every other key belongs to
// Document::projectSettings (camera, render, brush, symmetry, ...).
const char* const kCoreKeys[] = {"format", "version", "app_version", "mesh", "layers", "active_layer",
"parts", "active_part", "part_folders", "brushes", "active_brush", "splats", "attachments",
"unitless_scale", "unitless_format"};
std::filesystem::path fsPath(const std::string& p) { return std::filesystem::path(std::u8string(p.begin(), p.end())); }
constexpr size_t kMaxAttachmentSize = size_t(64) << 20;
// Document::projectFiles names: "lit spheres/Gold.png" - letters, digits, space . _ - and '/' between parts.
bool validAttachmentName(const std::string& name) {
if (name.empty() || name.size() > 200 || name.front() == '/' || name.back() == '/' || name.find("..") != std::string::npos)
return false;
return std::all_of(name.begin(), name.end(), [](unsigned char c) {
return std::isalnum(c) || c == ' ' || c == '.' || c == '_' || c == '-' || c == '/' || c >= 0x80;
});
}
bool isCoreKey(const std::string& key) {
return std::any_of(std::begin(kCoreKeys), std::end(kCoreKeys), [&](const char* k) { return key == k; });
}
// --- Blobs: little-endian arrays of f32 / u32 / u8 with N components per element ---
enum class Scalar { F32, U32, U8 };
const char* scalarName(Scalar s) { return s == Scalar::F32 ? "f32" : s == Scalar::U32 ? "u32" : "u8"; }
size_t scalarSize(Scalar s) { return s == Scalar::U8 ? 1 : 4; }
[[maybe_unused]] void put32(std::vector<uint8_t>& out, uint32_t v) {
for (int i = 0; i < 4; ++i) out.push_back(uint8_t(v >> (8 * i)));
}
uint32_t get32(const uint8_t* p) { return uint32_t(p[0]) | uint32_t(p[1]) << 8 | uint32_t(p[2]) << 16 | uint32_t(p[3]) << 24; }
// `n` 32-bit values as little-endian bytes (a plain copy on little-endian machines).
template <class T>
std::vector<uint8_t> littleEndian(const T* v, size_t n) {
static_assert(sizeof(T) == 4);
std::vector<uint8_t> data;
if constexpr (std::endian::native == std::endian::little) {
data.resize(n * 4);
if (n) std::memcpy(data.data(), v, n * 4);
} else {
data.reserve(n * 4);
for (size_t i = 0; i < n; ++i) put32(data, std::bit_cast<uint32_t>(v[i]));
}
return data;
}
// Reads `n` little-endian 32-bit values (a plain copy on little-endian machines).
template <class T>
void fromLittleEndian(const uint8_t* p, size_t n, T* out) {
static_assert(sizeof(T) == 4);
if constexpr (std::endian::native == std::endian::little) {
if (n) std::memcpy(out, p, n * 4);
} else {
for (size_t i = 0; i < n; ++i) out[i] = std::bit_cast<T>(get32(p + 4 * i));
}
}
class Writer {
public:
// Adds a blob and returns its manifest descriptor.
Json add(const std::string& file, Scalar type, int components, size_t count, std::vector<uint8_t> data) {
entries.push_back({file, std::move(data)});
return descriptor(file, type, components, count);
}
// Adds `count` elements of `components` 32-bit values at `v` (which must outlive the save): written straight
// from memory on little-endian machines, without a copy of the scene.
Json add32(const std::string& file, Scalar type, int components, size_t count, const void* v) {
const size_t n = count * size_t(components);
if constexpr (std::endian::native == std::endian::little) {
ZipEntry e{file, {}};
e.external = n ? static_cast<const uint8_t*>(v) : nullptr;
e.externalSize = n * 4;
entries.push_back(std::move(e));
return descriptor(file, type, components, count);
} else {
return add(file, type, components, count, littleEndian(static_cast<const uint32_t*>(v), n));
}
}
Json floats(const std::string& file, const float* v, size_t count, int components) {
return add32(file, Scalar::F32, components, count, v);
}
Json vec3s(const std::string& file, const std::vector<glm::vec3>& v) {
return floats(file, v.empty() ? nullptr : &v[0].x, v.size(), 3);
}
Json uints(const std::string& file, const uint32_t* v, size_t count, int components) {
return add32(file, Scalar::U32, components, count, v);
}
// Copied: for arrays that don't outlive the save.
Json ownedUints(const std::string& file, const std::vector<uint32_t>& v) {
return add(file, Scalar::U32, 1, v.size(), littleEndian(v.data(), v.size()));
}
Json bytes(const std::string& file, const std::vector<uint8_t>& v) { return add(file, Scalar::U8, 1, v.size(), v); }
// `count` 16-bit integers at `v` (which must outlive the save), as u8 x 2, written straight from memory on
// little-endian machines.
Json int16s(const std::string& file, const int16_t* v, size_t count) {
if constexpr (std::endian::native == std::endian::little) {
ZipEntry e{file, {}};
e.external = count ? reinterpret_cast<const uint8_t*>(v) : nullptr;
e.externalSize = count * 2;
entries.push_back(std::move(e));
return descriptor(file, Scalar::U8, 2, count);
} else {
std::vector<uint8_t> data(count * 2);
for (size_t i = 0; i < count; ++i) data[2 * i] = uint8_t(uint16_t(v[i])), data[2 * i + 1] = uint8_t(uint16_t(v[i]) >> 8);
return add(file, Scalar::U8, 2, count, std::move(data));
}
}
// Copied external-free: a byte array that must outlive the save.
Json externalBytes(const std::string& file, const std::vector<uint8_t>& v) {
ZipEntry e{file, {}};
e.external = v.empty() ? nullptr : v.data();
e.externalSize = v.size();
entries.push_back(std::move(e));
return descriptor(file, Scalar::U8, 1, v.size());
}
std::vector<ZipEntry> entries;
private:
static Json descriptor(const std::string& file, Scalar type, int components, size_t count) {
Json d = Json::object();
d.set("file", file);
d.set("type", scalarName(type));
d.set("components", components);
d.set("count", double(count));
return d;
}
};
// Reads blobs straight from the archive into the arrays they belong in (no copy of the file in memory).
class Reader {
public:
std::map<std::string, ZipFileEntry> files;
std::string error;
// Big blobs are read on the shared thread pool, except while a BVH builds on another thread (it gets the pool).
bool parallelReads = true;
bool open(const std::string& path, std::string& err) {
std::vector<ZipFileEntry> index;
if (!readStoredZipIndex(path, index, err)) return false;
for (auto& e : index) files[e.name] = std::move(e);
file_.open(fsPath(path), std::ios::binary);
if (!file_) {
err = "Cannot open " + path;
return false;
}
#if SF_PREAD
fd_ = ::open(path.c_str(), O_RDONLY | O_CLOEXEC);
#endif
return true;
}
~Reader() {
#if SF_PREAD
if (fd_ >= 0) ::close(fd_);
#endif
}
// The whole entry `name` (false if missing or unreadable).
bool entry(const std::string& name, std::vector<uint8_t>& out) {
auto it = files.find(name);
if (it == files.end() || it->second.size > (uint64_t(1) << 32)) return false;
out.resize(size_t(it->second.size));
return readAt(it->second.offset, out.size(), out.data());
}
// Validates `desc` against the expected layout and reads its bytes into `out` (false + error on mismatch).
bool read(const Json& desc, const char* what, Scalar type, int components, size_t count, void* out) {
if (!desc.isObject()) return fail(what, "is missing");
if (desc["type"].asString() != scalarName(type) || int(desc["components"].asNumber()) != components)
return fail(what, "has an unexpected layout");
if (desc["count"].asNumber(-1) != double(count)) return fail(what, "has the wrong size");
auto it = files.find(desc["file"].asString());
if (it == files.end()) return fail(what, "data is missing from the archive");
const size_t bytes = count * size_t(components) * scalarSize(type);
if (it->second.size != bytes) return fail(what, "data is truncated");
if (!readAt(it->second.offset, bytes, out)) return fail(what, "data is truncated");
return true;
}
bool floats(const Json& desc, const char* what, size_t count, int components, float* out) {
if (!read(desc, what, Scalar::F32, components, count, out)) return false;
toNative(out, count * size_t(components));
return true;
}
bool vec3s(const Json& desc, const char* what, size_t count, std::vector<glm::vec3>& out) {
out.resize(count);
return floats(desc, what, count, 3, count ? &out[0].x : nullptr);
}
bool uints(const Json& desc, const char* what, size_t count, int components, uint32_t* out) {
if (!read(desc, what, Scalar::U32, components, count, out)) return false;
toNative(out, count * size_t(components));
return true;
}
bool bytes(const Json& desc, const char* what, size_t count, std::vector<uint8_t>& out) {
out.resize(count);
return read(desc, what, Scalar::U8, 1, count, out.data());
}
bool int16s(const Json& desc, const char* what, size_t count, std::vector<int16_t>& out) {
out.resize(count);
if (!read(desc, what, Scalar::U8, 2, count, out.data())) return false;
if constexpr (std::endian::native != std::endian::little)
for (int16_t& v : out) {
const uint8_t* p = reinterpret_cast<const uint8_t*>(&v);
v = int16_t(uint16_t(p[0]) | uint16_t(p[1]) << 8);
}
return true;
}
private:
std::ifstream file_;
#if SF_PREAD
int fd_ = -1;
#endif
bool readAt(uint64_t offset, size_t n, void* out) {
if (n == 0) return true;
#if SF_PREAD
// Big arrays in 8 MB pieces on every core (the copies and the page faults of the fresh array are the cost).
constexpr size_t kPiece = size_t(8) << 20;
if (fd_ >= 0 && n >= 2 * kPiece && parallelReads) {
std::atomic<bool> ok = true;
poolFor((n + kPiece - 1) / kPiece, [&](size_t b, size_t e) {
for (size_t i = b; i < e; ++i) {
size_t done = i * kPiece;
const size_t end = std::min(n, done + kPiece);
while (done < end) {
const ssize_t got = ::pread(fd_, static_cast<char*>(out) + done, end - done, off_t(offset + done));
if (got <= 0) {
ok = false;
break;
}
done += size_t(got);
}
}
}, 1, 1);
return ok;
}
#endif
file_.clear();
file_.seekg(std::streamoff(offset));
return bool(file_.read(static_cast<char*>(out), std::streamsize(n)));
}
// Little-endian values read in place become native ones (nothing to do on little-endian machines).
template <class T>
static void toNative(T* v, size_t n) {
static_assert(sizeof(T) == 4);
if constexpr (std::endian::native != std::endian::little) {
for (size_t i = 0; i < n; ++i) {
const uint8_t* p = reinterpret_cast<const uint8_t*>(&v[i]);
v[i] = std::bit_cast<T>(get32(p));
}
}
}
bool fail(const char* what, const char* problem) {
if (error.empty()) error = std::string("Project ") + what + " " + problem;
return false;
}
};
Json matrixJson(const glm::mat4& m) {
Json a = Json::array();
for (int c = 0; c < 4; ++c)
for (int r = 0; r < 4; ++r) a.push(double(m[c][r]));
return a;
}
glm::mat4 matrixFromJson(const Json& a) {
glm::mat4 m(1.0f);
if (a.size() != 16) return m;
for (int c = 0; c < 4; ++c)
for (int r = 0; r < 4; ++r) m[c][r] = float(a[size_t(c * 4 + r)].asNumber(c == r ? 1.0 : 0.0));
return m;
}
size_t countOf(const Json& j) {
const double n = j.asNumber(-1);
return n >= 0 && n < 4.0e9 ? size_t(n) : size_t(-1);
}
// Writes a mesh's blobs under `prefix` ("parts/0/") and sets `mesh` and `layers` in `out`. `generatedTriangles`:
// a generated subdivision level's triangle count; its triangles aren't written (format 6).
void writeMesh(Writer& w, const std::string& prefix, const Mesh& m, Json& out, size_t generatedTriangles = 0) {
Json mesh = Json::object();
mesh.set("vertex_count", double(m.vertexCount()));
mesh.set("positions", w.vec3s(prefix + "mesh/positions.bin", m.positions));
if (generatedTriangles) {
mesh.set("triangle_count", double(generatedTriangles));
} else {
mesh.set("triangle_count", double(m.triangleCount()));
mesh.set("triangles", w.uints(prefix + "mesh/triangles.bin", m.triangles.empty() ? nullptr : &m.triangles[0].x,
m.triangleCount(), 3));
}
if (!m.layers.empty()) mesh.set("base", w.vec3s(prefix + "mesh/base.bin", m.base));
if (m.hasMask()) mesh.set("mask", w.floats(prefix + "mesh/mask.bin", m.mask.data(), m.mask.size(), 1));
if (m.hasColors()) mesh.set("colors", w.vec3s(prefix + "mesh/colors.bin", m.colors));
if (m.hasFaceGroups())
mesh.set("facegroups", w.uints(prefix + "mesh/facegroups.bin", m.facegroups.data(), m.facegroups.size(), 1));
if (m.hasHidden()) mesh.set("hidden", w.bytes(prefix + "mesh/hidden.bin", m.hidden));
if (m.hasUvs()) mesh.set("uvs", w.floats(prefix + "mesh/uvs.bin", &m.uvs[0].x, m.uvs.size(), 2));
if (m.hasUvFlags()) mesh.set("uv_flags", w.bytes(prefix + "mesh/uv_flags.bin", m.uvFlags)); // seams, pins (core/Uv.h)
// Optional and ignored by older readers, so no format version bump.
if (m.hasQuads())
mesh.set("quad_partners", w.uints(prefix + "mesh/quad_partners.bin", m.quadPartners.data(), m.quadPartners.size(), 1));
out.set("mesh", std::move(mesh));
Json layers = Json::array();
for (size_t i = 0; i < m.layers.size(); ++i) {
Json l = Json::object();
l.set("name", m.layers[i].name);
l.set("weight", double(m.layers[i].weight));
l.set("delta", w.vec3s(prefix + "layers/" + std::to_string(i) + ".bin", m.layers[i].delta));
layers.push(std::move(l));
}
out.set("layers", std::move(layers));
}
// Reads a mesh from its `mesh` and `layers` manifest entries (size-checked against the blobs). `levelData`: a
// subdivision level's arrays, kept without topology or normals; a generated level's have no triangles.
// `topology` false: the caller calls finishMesh once the mesh has its subdivision levels (so it gets the
// adjacency they give).
bool readMesh(Reader& r, const Json& mj, const Json& lj, Mesh& m, std::string& error, bool levelData = false,
bool topology = true) {
const size_t nv = countOf(mj["vertex_count"]), nt = countOf(mj["triangle_count"]);
if (nv == size_t(-1) || nt == size_t(-1)) {
error = "Project mesh has no valid vertex/triangle count";
return false;
}
const bool withTriangles = !levelData || mj.has("triangles");
if (withTriangles) m.triangles.resize(nt);
if (!r.vec3s(mj["positions"], "positions", nv, m.positions) ||
(withTriangles && !r.uints(mj["triangles"], "triangles", nt, 3, nt ? &m.triangles[0].x : nullptr))) {
error = r.error;
return false;
}
for (const auto& t : m.triangles)
if (t.x >= nv || t.y >= nv || t.z >= nv) {
error = "Project triangles reference missing vertices";
return false;
}
if (mj.has("mask")) {
m.mask.resize(nv);
r.floats(mj["mask"], "mask", nv, 1, m.mask.data());
}
if (mj.has("colors")) r.vec3s(mj["colors"], "colors", nv, m.colors);
if (mj.has("facegroups")) {
m.facegroups.resize(nt);
r.uints(mj["facegroups"], "facegroups", nt, 1, m.facegroups.data());
}
if (mj.has("hidden")) {
if (!r.bytes(mj["hidden"], "hidden flags", nt, m.hidden)) m.hidden.clear();
}
if (mj.has("uvs")) {
m.uvs.resize(nt * 3);
r.floats(mj["uvs"], "uvs", nt * 3, 2, nt ? &m.uvs[0].x : nullptr);
}
if (mj.has("uv_flags")) {
if (!r.bytes(mj["uv_flags"], "UV seams", nt * 3, m.uvFlags)) m.uvFlags.clear();
}
if (mj.has("quad_partners")) { // rebuildTopology() unpairs anything that isn't a valid pair
m.quadPartners.resize(nt);
r.uints(mj["quad_partners"], "quad partners", nt, 1, m.quadPartners.data());
}
if (lj.size()) {
r.vec3s(mj["base"], "base positions", nv, m.base);
for (size_t i = 0; i < lj.size() && r.error.empty(); ++i) {
SculptLayer layer;
layer.name = lj[i]["name"].asString();
layer.weight = float(lj[i]["weight"].asNumber(1.0));
r.vec3s(lj[i]["delta"], "layer offsets", nv, layer.delta);
m.layers.push_back(std::move(layer));
}
}
if (!r.error.empty()) {
error = r.error;
return false;
}
if (levelData || !topology) {
if (!m.layers.empty()) m.evaluateAll();
if (!topology) m.sanitizeAttributes();
return true;
}
m.rebuildTopology();
if (!m.layers.empty()) m.evaluateAll();
m.recomputeAllNormals();
return true;
}
void finishMesh(Mesh& m) {
m.rebuildTopology();
m.recomputeAllNormals();
}
// Paint layers (core/PaintLayer.h) are their own Part key, "paint_layers", next to "mesh":
// readers that don't know it load `mesh.colors`, the composited (flattened) paint.
Json writePaintLayers(Writer& w, const std::string& prefix, const Mesh& m) {
Json out = Json::object();
out.set("active", m.activePaintLayer);
out.set("base", w.vec3s(prefix + "paint/base.bin", m.paintBase));
Json layers = Json::array();
for (size_t i = 0; i < m.paintLayers.size(); ++i) {
const PaintLayer& pl = m.paintLayers[i];
Json l = Json::object();
l.set("name", pl.name);
l.set("opacity", double(pl.opacity));
l.set("blend", blendModeId(pl.blend));
l.set("visible", pl.visible);
l.set("locked", pl.locked);
l.set("color", w.vec3s(prefix + "paint/" + std::to_string(i) + "_color.bin", pl.color));
l.set("alpha", w.floats(prefix + "paint/" + std::to_string(i) + "_alpha.bin", pl.alpha.data(), pl.alpha.size(), 1));
layers.push(std::move(l));
}
out.set("layers", std::move(layers));
return out;
}
bool readPaintLayers(Reader& r, const Json& pj, Mesh& m, std::string& error) {
if (!pj.isObject() || pj["layers"].size() == 0) return true;
const size_t nv = m.vertexCount();
r.vec3s(pj["base"], "paint base layer", nv, m.paintBase);
for (size_t i = 0; i < pj["layers"].size() && r.error.empty(); ++i) {
const Json& lj = pj["layers"][i];
PaintLayer l;
l.name = lj["name"].asString();
if (l.name.empty()) l.name = "Layer " + std::to_string(i + 1);
l.opacity = std::clamp(float(lj["opacity"].asNumber(1.0)), 0.0f, 1.0f);
if (!parseBlendMode(lj["blend"].asString(), l.blend)) l.blend = BlendMode::Normal; // a newer mode
l.visible = lj["visible"].asBool(true);
l.locked = lj["locked"].asBool(false);
r.vec3s(lj["color"], "paint layer colours", nv, l.color);
l.alpha.resize(nv);
r.floats(lj["alpha"], "paint layer coverage", nv, 1, l.alpha.data());
m.paintLayers.push_back(std::move(l));
}
if (!r.error.empty()) {
error = r.error;
return false;
}
const double active = pj["active"].asNumber(-1);
m.activePaintLayer = active >= 0 && active < double(m.paintLayers.size()) ? int(active) : -1;
sanitizePaintLayers(m); // recomposites if `colors` was missing
return true;
}
// Texture painting (core/Texture.h) is the Part key "texture" (format 3): the size, where paint goes,
// and every layer as a PNG blob (top row = v 1, as image files are). Without layers "base" is the texture.
Json pngBlob(Writer& w, const std::string& file, int width, int height, const std::vector<uint8_t>& rgba) {
Image img;
img.width = width;
img.height = height;
img.rgba.resize(rgba.size());
const size_t row = size_t(width) * 4;
for (int y = 0; y < height; ++y) std::memcpy(&img.rgba[size_t(height - 1 - y) * row], &rgba[size_t(y) * row], row);
std::vector<uint8_t> png;
img.encodePng(png);
Json d = w.bytes(file, png);
d.set("encoding", "png");
return d;
}
bool readPngBlob(Reader& r, const Json& desc, const char* what, int width, int height, std::vector<uint8_t>& rgba,
std::string& error) {
const size_t n = countOf(desc["count"]);
std::vector<uint8_t> png;
const bool ok = n != size_t(-1) && n < (size_t(1) << 31) && r.bytes(desc, what, n, png);
Image img;
std::string why;
if (!ok || !Image::decode(png.data(), n, img, why) || img.width != width || img.height != height) {
error = r.error.empty() ? std::string("Project ") + what + " is not a " + std::to_string(width) + "x" +
std::to_string(height) + " image" + (why.empty() ? "" : " (" + why + ")")
: r.error;
return false;
}
rgba.resize(img.rgba.size());
const size_t row = size_t(width) * 4;
for (int y = 0; y < height; ++y) std::memcpy(&rgba[size_t(y) * row], &img.rgba[size_t(height - 1 - y) * row], row);
return true;
}
Json writeTexture(Writer& w, const std::string& prefix, const Mesh& m) {
const PaintTexture& t = *m.texture;
Json out = Json::object();
out.set("width", t.width);
out.set("height", t.height);
out.set("paint_to_texture", m.paintToTexture);
out.set("active", t.activeLayer);
out.set("base", pngBlob(w, prefix + "texture/base.png", t.width, t.height, t.layers.empty() ? t.pixels : t.base));
Json layers = Json::array();
for (size_t i = 0; i < t.layers.size(); ++i) {
const TextureLayer& tl = t.layers[i];
Json l = Json::object();
l.set("name", tl.name);
l.set("opacity", double(tl.opacity));
l.set("blend", blendModeId(tl.blend));
l.set("visible", tl.visible);
l.set("locked", tl.locked);
l.set("rgba", pngBlob(w, prefix + "texture/" + std::to_string(i) + ".png", t.width, t.height, tl.rgba));
// A Fill layer (format 7, core/LayerStack.h): its settings and painted mask; `rgba` is its last evaluation,
// so readers that don't know Fill layers show it as a paint layer.
if (tl.fill) {
l.set("fill", fillLayerJson(*tl.fill));
if (tl.mask.size() == t.texelCount() * 4)
l.set("mask", pngBlob(w, prefix + "texture/" + std::to_string(i) + "_mask.png", t.width, t.height, tl.mask));
}
layers.push(std::move(l));
}
out.set("layers", std::move(layers));
// Material channels (format 7, core/LayerStackIO.h); absent for a base-colour-only texture.
if (Json pbr = writeTextureChannels(t, prefix, [&](const std::string& file, const std::vector<uint8_t>& bytes) {
return w.bytes(file, bytes);
});
pbr.isObject())
out.set("pbr", std::move(pbr));
return out;
}
bool readTexture(Reader& r, const Json& tj, Mesh& m, std::string& error) {
if (!tj.isObject()) return true;
const double w = tj["width"].asNumber(0), h = tj["height"].asNumber(0);
if (!(w >= 1 && h >= 1 && w <= 16384 && h <= 16384)) {
error = "Project texture has an invalid size";
return false;
}
auto tex = makeTexture(int(w), int(h));
std::vector<uint8_t> base;
if (!readPngBlob(r, tj["base"], "texture", tex->width, tex->height, base, error)) return false;
for (size_t i = 0; i < tj["layers"].size(); ++i) {
const Json& lj = tj["layers"][i];
TextureLayer l;
l.name = lj["name"].asString();
if (l.name.empty()) l.name = "Layer " + std::to_string(i + 1);
l.opacity = std::clamp(float(lj["opacity"].asNumber(1.0)), 0.0f, 1.0f);
if (!parseBlendMode(lj["blend"].asString(), l.blend)) l.blend = BlendMode::Normal;
l.visible = lj["visible"].asBool(true);
l.locked = lj["locked"].asBool(false);
if (!readPngBlob(r, lj["rgba"], "texture layer", tex->width, tex->height, l.rgba, error)) return false;
if (lj["fill"].isObject()) {
auto fill = std::make_shared<FillLayer>();
if (!fillLayerFromJson(lj["fill"], *fill, error)) return false;
l.fill = std::move(fill);
if (lj["mask"].isObject() && !readPngBlob(r, lj["mask"], "fill layer mask", tex->width, tex->height, l.mask, error))
return false;
}
tex->layers.push_back(std::move(l));
}
if (tex->layers.empty()) {
tex->pixels = std::move(base);
} else {
tex->base = std::move(base);
const double active = tj["active"].asNumber(-1);
tex->activeLayer = active >= 0 && active < double(tex->layers.size()) ? int(active) : -1;
compositeTextureAll(*tex);
}
for (size_t i = 3; i < (tex->layers.empty() ? tex->pixels : tex->base).size(); i += 4)
(tex->layers.empty() ? tex->pixels : tex->base)[i] = 255; // Base is opaque
if (!readTextureChannels(tj["pbr"], *tex,
[&](const Json& desc, const char* what, size_t maxBytes, std::vector<uint8_t>& out) {
const size_t n = countOf(desc["count"]);
return n != size_t(-1) && n <= maxBytes && r.bytes(desc, what, n, out);
},
error)) {
if (!r.error.empty()) error = r.error;
return false;
}
tex->markAllDirty();
m.texture = std::move(tex);
m.paintToTexture = tj["paint_to_texture"].asBool(true);
return true;
}
// Subdivision levels (core/Multires.h) are the Part key "subdiv" (format 4; sculpt-layer details in local
// frames from format 5): the current level and every level's mesh (as "mesh" / "layers" / "paint_layers"),
// details and topology (scheme, Smooth, quad pairing and child maps). The Part's own "mesh" is the current level,
// so readers that don't know levels load what was shown. A current level identical to that mesh is not written
// twice ("same_as_mesh"). Format 6: a generated level (made by Divide, SubdivTopology::generated) has no
// triangles and no child maps ("generated"), and a level without "detail" that isn't stale takes the detail that
// fits its positions (SubdivLevel::detail).
Json writeSubdiv(Writer& w, const std::string& prefix, const Mesh& m) {
Json out = Json::object();
out.set("current", subdivCurrentLevel(m));
Json levels = Json::array();
const bool inSync = subdivInSync(m);
for (int i = 0; i < subdivLevelCount(m); ++i) {
const std::string p = prefix + "subdiv/" + std::to_string(i) + "/";
const SubdivLevel& l = subdivLevel(m, i);
const Mesh& data = *l.data;
const bool generated = l.topo && l.topo->generated;
Json lj = Json::object();
if (i == subdivCurrentLevel(m) && inSync) {
lj.set("same_as_mesh", true);
} else {
writeMesh(w, p, data, lj, generated ? l.triangleCount() : 0);
if (hasPaintLayers(data)) lj.set("paint_layers", writePaintLayers(w, p, data));
}
if (l.stale) lj.set("stale", true);
if (l.topo) {
const SubdivTopology& tp = *l.topo;
Json t = Json::object();
t.set("catmull_clark", tp.catmullClark);
t.set("smooth", tp.smooth);
if (const std::vector<uint32_t> pairing = tp.pairing(); !pairing.empty())
t.set("pairing", w.ownedUints(p + "pairing.bin", pairing));
if (generated) {
t.set("generated", true);
} else {
t.set("vertex_child", w.uints(p + "vertex_child.bin", tp.vertexChild.data(), tp.vertexChild.size(), 1));
t.set("edge_child", w.uints(p + "edge_child.bin", tp.edgeChild.data(), tp.edgeChild.size(), 1));
if (!tp.faceChild.empty()) t.set("face_child", w.uints(p + "face_child.bin", tp.faceChild.data(), tp.faceChild.size(), 1));
}
lj.set("topology", std::move(t));
}
if (l.detail) lj.set("detail", w.vec3s(p + "detail.bin", *l.detail));
Json ld = Json::array();
for (size_t k = 0; k < l.layerDetail.size(); ++k)
ld.push(l.layerDetail[k] ? w.vec3s(p + "layer_detail_" + std::to_string(k) + ".bin", *l.layerDetail[k]) : Json());
if (!l.layerDetail.empty()) lj.set("layer_detail", std::move(ld));
levels.push(std::move(lj));
}
out.set("levels", std::move(levels));
return out;
}
bool readUintList(Reader& r, const Json& desc, const char* what, std::vector<uint32_t>& out) {
const size_t n = countOf(desc["count"]);
if (n == size_t(-1) || n > (size_t(1) << 31)) {
r.error = std::string("Project ") + what + " has an invalid size";
return false;
}
out.resize(n);
return r.uints(desc, what, n, 1, out.data());
}
// Reads "subdiv" into `m` (the Part's current level). Levels that don't fit are an error. Format 4 kept the
// sculpt-layer details in world space (`worldLayerDetail`): they're converted to local frames.
bool readSubdiv(Reader& r, const Json& sj, Mesh& m, std::string& error, bool worldLayerDetail) {
if (!sj.isObject()) return true;
const Json& list = sj["levels"];
if (!list.isArray() || list.size() < 2 || list.size() > 32) {
error = "Project has invalid subdivision levels";
return false;
}
MultiresStack stack;
const double current = sj["current"].asNumber(-1);
if (current < 0 || current >= double(list.size())) {
error = "Project has an invalid current subdivision level";
return false;
}
stack.current = int(current);
// The triangles of the level below (its own, or generated into one of the two buffers), to build each level's
// topology from.
const std::vector<glm::uvec3>* below = nullptr;
std::vector<glm::uvec3> generatedBelow[2];
for (size_t i = 0; i < list.size(); ++i) {
const Json& lj = list[i];
const bool generated = i > 0 && lj["topology"]["generated"].asBool(false);
SubdivLevel level;
auto data = std::make_shared<Mesh>();
if (lj["same_as_mesh"].asBool(false) && i == size_t(stack.current)) {
// Just the level's arrays (no topology, normals or texture), as the stack stores levels.
if (!generated) data->triangles = m.triangles;
data->positions = m.positions;
data->mask = m.mask;
data->colors = m.colors;
data->facegroups = m.facegroups;
data->hidden = m.hidden;
data->uvs = m.uvs;
data->quadPartners = m.quadPartners;
data->base = m.base;
data->layers = m.layers;
data->paintBase = m.paintBase;
data->paintLayers = m.paintLayers;
data->activePaintLayer = m.activePaintLayer;
} else {
if (!readMesh(r, lj["mesh"], lj["layers"], *data, error, true)) return false;
if (!readPaintLayers(r, lj["paint_layers"], *data, error)) return false;
if (data->triangles.empty() && !generated && countOf(lj["mesh"]["triangle_count"]) != 0) {
error = "Project subdivision level " + std::to_string(i + 1) + " has no triangles";
return false;
}
}
level.data = std::move(data);
level.stale = lj["stale"].asBool(false);
const size_t nv = level.data->vertexCount();
if (lj.has("detail")) {
level.detail = std::make_shared<std::vector<glm::vec3>>();
if (!r.vec3s(lj["detail"], "subdivision detail", nv, *level.detail)) {
error = r.error;
return false;
}
}
for (const Json& d : lj["layer_detail"].items()) {
if (!d.isObject()) {
level.layerDetail.push_back(nullptr);
continue;
}
auto v = std::make_shared<std::vector<glm::vec3>>();
if (!r.vec3s(d, "subdivision layer detail", nv, *v)) {
error = r.error;
return false;
}
level.layerDetail.push_back(std::move(v));
}
if (i > 0) {
const Json& t = lj["topology"];
std::vector<uint32_t> pairing, vc, ec, fc;
if ((t.has("pairing") && !readUintList(r, t["pairing"], "subdivision quad pairing", pairing)) ||
(!generated && (!readUintList(r, t["vertex_child"], "subdivision vertex map", vc) ||
!readUintList(r, t["edge_child"], "subdivision edge map", ec) ||
(t.has("face_child") && !readUintList(r, t["face_child"], "subdivision face map", fc))))) {
error = r.error;
return false;
}
level.topo = rebuildSubdivTopology(*below, uint32_t(stack.levels[i - 1].data->vertexCount()), uint32_t(nv),
generated ? nullptr : &level.data->triangles, std::move(pairing),
t["catmull_clark"].asBool(false), t["smooth"].asBool(true),
std::move(vc), std::move(ec), std::move(fc), error);
if (!level.topo) {
error = "Project " + error;
return false;
}
if (generated && level.topo->fineTriangles != countOf(lj["mesh"]["triangle_count"]) && !lj["same_as_mesh"].asBool(false)) {
error = "Project subdivision level " + std::to_string(i + 1) + " doesn't fit the level below";
return false;
}
}
if (i + 1 < list.size()) { // the next level is built on this one's triangles
if (level.topo && level.topo->generated && level.data->triangles.empty()) {
generateFaces(*level.topo, generatedBelow[i % 2], nullptr);
below = &generatedBelow[i % 2];
} else {
below = &level.data->triangles;
}
}
stack.levels.push_back(std::move(level));
}
if (worldLayerDetail) convertWorldLayerDetail(stack);
if (!attachSubdivStack(m, std::move(stack), error)) {
error = "Project " + error;
return false;
}
return true;
}
// Selection Sets (core/SelectionSets.h): `selection_sets` = {"version", "morph_target", "sets": [summary + "data"]},
// each set one packed u8 blob under parts/i/sets/. Optional, so no format version bump: older readers ignore it.
constexpr int kSelectionSetsVersion = 1;
Json writeSelectionSets(Writer& w, const std::string& prefix, const SelectionSetList& list) {
Json j = Json::object();
j.set("version", kSelectionSetsVersion);
if (!list.morphTarget.empty()) j.set("morph_target", list.morphTarget);
Json sets = Json::array();
for (size_t k = 0; k < list.sets.size(); ++k) {
Json one = selectionSetSummary(*list.sets[k]);
std::vector<uint8_t> packed = packSelectionSet(*list.sets[k]);
const size_t n = packed.size();
one.set("data", w.add(prefix + "sets/" + std::to_string(k) + ".bin", Scalar::U8, 1, n, std::move(packed)));
sets.push(std::move(one));
}
j.set("sets", std::move(sets));
return j;
}
// Sets that can't be read (damaged, or from a newer set format) are left out and named in `skipped`; the rest of
// the project still loads.
void readSelectionSets(Reader& r, const Json& j, Mesh& m, std::string& skipped) {
if (!j.isObject() || !j["sets"].isArray()) return;
auto list = std::make_shared<SelectionSetList>();
for (const Json& one : j["sets"].items()) {
const Json& desc = one["data"];
auto it = r.files.find(desc["file"].asString());
const double count = desc["count"].asNumber(-1);
std::vector<uint8_t> bytes;
SelectionSet set;
std::string why;
const std::string saved = r.error;
const bool ok = it != r.files.end() && count >= 0 && double(it->second.size) == count &&
r.bytes(desc, "selection set", size_t(count), bytes) &&
unpackSelectionSet(bytes.data(), bytes.size(), set, why) && list->find(set.name) < 0;
r.error = saved;
if (!ok) {
skipped += (skipped.empty() ? "" : ", ") + ("'" + one["name"].asString() + "'");
continue;
}
list->sets.push_back(std::make_shared<const SelectionSet>(std::move(set)));
}
list->morphTarget = j["morph_target"].asString();
if (list->find(list->morphTarget) < 0) list->morphTarget.clear();
if (!list->sets.empty()) m.selectionSets = std::move(list);
}
// A Part read from a project, before it joins the document.
struct LoadedPart {
std::string name, bridgeName;
std::vector<QRemeshGuide> qremeshGuides;
bool visible = true;
Shading shading = Shading::Default;
int folder = -1; // index into the manifest's part_folders (#96)
int activeLayer = -1;
int link = -1; // a linked copy of this earlier Part (#94): no mesh of its own
glm::mat4 transform{1.0f}; // Part::transform
Mesh mesh;
// A big mesh's BVH is built on its own thread once the positions and triangles are read (they don't change
// after that), while the subdivision levels, topology and normals load.
BVH bvh;
std::thread bvhBuilder;
LoadedPart() = default;
LoadedPart(const LoadedPart&) = delete;
~LoadedPart() { finishBvh(); }
void startBvh() {
if (mesh.triangleCount() >= 1'000'000) bvhBuilder = std::thread([this] { bvh.build(mesh); });
}
// The BVH to hand over (null: build it on the spot).
BVH* finishBvh() {
if (bvhBuilder.joinable()) {
bvhBuilder.join();
built = true;
}
return built ? &bvh : nullptr;
}
bool built = false;
};
constexpr size_t kMaxProjectParts = 100000;
} // namespace
bool isProjectPath(const std::string& path) {
std::string ext = fsPath(path).extension().string();
std::transform(ext.begin(), ext.end(), ext.begin(), [](unsigned char c) { return char(std::tolower(c)); });
return ext == kProjectExtension;
}
bool saveProject(const std::string& path, const Document& doc, std::string& error) {
Writer w;
Json manifest = Json::object();
manifest.set("format", kFormatName);
ProjectVersionNeed version; // the lowest format the content needs (set again once the Parts are written)
manifest.set("version", version.version);
manifest.set("app_version", SCULPTFORGE_VERSION);
// Every Part with its mesh, layers and state; blobs live under parts/<i>/.
Json parts = Json::array();
for (int i = 0; i < doc.partCount(); ++i) {
const Part& s = doc.parts[size_t(i)];
const bool active = doc.checkedOut(i);
Json st = Json::object();
st.set("name", s.name);
st.set("visible", s.visible);
if (s.shading != Shading::Default) st.set("shading", shadingName(s.shading)); // (no format change: optional)
if (const int f = doc.partFolderIndex(s.folder); f >= 0) st.set("folder", f); // (#96: optional, as shading)
if (s.moved()) {
st.set("transform", matrixJson(s.transform));
version.need(8);
}
int link = -1; // a linked copy (#94): the first Part with its mesh holds it
for (int k = 0; k < i && link < 0; ++k)
if (doc.parts[size_t(k)].data == s.data) link = k;
if (link >= 0) {
st.set("link", link);
version.need(8);
parts.push(std::move(st));
continue;
}
writeMesh(w, "parts/" + std::to_string(i) + "/", doc.partMesh(i), st);
st.set("active_layer", active ? doc.activeLayer : s.data->activeLayer);
if (hasPaintLayers(doc.partMesh(i)))
st.set("paint_layers", writePaintLayers(w, "parts/" + std::to_string(i) + "/", doc.partMesh(i)));
if (doc.partMesh(i).texture && doc.partMesh(i).texture->width > 0) {
st.set("texture", writeTexture(w, "parts/" + std::to_string(i) + "/", doc.partMesh(i)));
version.need(textureFormatVersion(*doc.partMesh(i).texture));
}
if (subdivLevelCount(doc.partMesh(i)))
st.set("subdiv", writeSubdiv(w, "parts/" + std::to_string(i) + "/", doc.partMesh(i)));
if (const Mesh& m = doc.partMesh(i); m.micro && microMatches(m)) { // format 7: the micro level (core/Micro.h)
const MicroMesh& mm = *m.micro;
const std::string p = "parts/" + std::to_string(i) + "/micro/";
Json mj = Json::object();
mj.set("level", mm.level);
mj.set("step", double(mm.step));
// Tiles packed (delta + per-tile range, core/MicroStore.h): untouched tiles are 3 bytes.
std::vector<uint8_t> packed;
microPackTiles(mm.disp.data(), mm.baseTriangles, mm.samples, packed);
const size_t packedBytes = packed.size();
mj.set("displacement_packed", w.add(p + "displacement.pack", Scalar::U8, 1, packedBytes, std::move(packed)));
if (mm.hasMask()) mj.set("mask", w.externalBytes(p + "mask.bin", mm.mask));
st.set("micro", std::move(mj));
version.need(7);
}
const std::string& bridgeName = active ? doc.bridgeName : s.data->bridgeName;
if (!bridgeName.empty()) st.set("bridge_name", bridgeName);
const std::vector<QRemeshGuide>& guides = active ? doc.qremeshGuides : s.data->qremeshGuides;
if (!guides.empty()) st.set("qremesh_guides", qremeshGuidesToJson(guides)); // (no format change: optional)
if (const Mesh& m = doc.partMesh(i); m.selectionSets && !m.selectionSets->sets.empty())
st.set("selection_sets", writeSelectionSets(w, "parts/" + std::to_string(i) + "/", *m.selectionSets));
if (const Mesh& m = doc.partMesh(i); !m.forgespheres.empty()) { // a Forge Sphere Part (core/Forge Spheres.h); optional
st.set("forgespheres", forgespheresToJson(m.forgespheres));
if (m.forgespherePreview) st.set("forgesphere_preview", true);
}
if (const Mesh& m = doc.partMesh(i); !m.tube.empty()) st.set("tube", tubeToJson(m.tube)); // a Tube Part (core/Tube.h); optional
parts.push(std::move(st));
}
manifest.set("parts", std::move(parts));
manifest.set("active_part", doc.activePart);
if (!doc.partFolders.empty()) { // Parts list folders (#96); no format change: older readers ignore them
Json folders = Json::array();
for (const PartFolder& f : doc.partFolders) {
Json fj = Json::object();
fj.set("name", f.name);
if (f.collapsed) fj.set("collapsed", true);
folders.push(std::move(fj));
}
manifest.set("part_folders", std::move(folders));
}
Json brushes = Json::array();
for (const auto& b : doc.brushes) brushes.push(b.toJson());
manifest.set("brushes", std::move(brushes));
if (doc.activeBrush >= 0 && doc.activeBrush < int(doc.brushes.size()))
manifest.set("active_brush", doc.brushes[size_t(doc.activeBrush)].name);
if (!doc.splats.empty()) {
const SplatCloud& s = doc.splats;
if (std::string v = s.validate(); !v.empty()) {
error = "Cannot save splats: " + v;
return false;
}
Json splats = Json::object();
splats.set("count", double(s.size()));
splats.set("sh_degree", s.shDegree);
splats.set("name", s.name);
splats.set("transform", matrixJson(s.transform));
splats.set("positions", w.vec3s("splats/positions.bin", s.positions));
std::vector<float> rot;
rot.reserve(s.size() * 4);
for (const auto& q : s.rotations) rot.insert(rot.end(), {q.x, q.y, q.z, q.w});
splats.set("rotations", w.add("splats/rotations.bin", Scalar::F32, 4, s.size(), littleEndian(rot.data(), rot.size())));
splats.set("scales", w.vec3s("splats/scales.bin", s.scales));
splats.set("opacities", w.floats("splats/opacities.bin", s.opacities.data(), s.size(), 1));
splats.set("sh", w.vec3s("splats/sh.bin", s.sh));
manifest.set("splats", std::move(splats));
}
if (!doc.projectFiles.empty()) { // (no format change: optional, older readers ignore it)
Json files = Json::array();
for (const auto& [name, bytes] : doc.projectFiles) {
if (!validAttachmentName(name)) continue;
Json f = Json::object();
f.set("name", name);
f.set("data", w.bytes("attachments/" + name, bytes));
files.push(std::move(f));
}
manifest.set("attachments", std::move(files));
}
if (doc.projectSettings.isObject())
for (const auto& [key, value] : doc.projectSettings.members())
if (!isCoreKey(key)) manifest.set(key, value);
// The unit-less file the scene came from (Document::unitlessScale). Optional: older readers ignore it.
if (doc.unitlessScale > 0.0) {
manifest.set("unitless_scale", doc.unitlessScale);
manifest.set("unitless_format", doc.unitlessFormat);
}
manifest.set("version", version.version);
const std::string text = manifest.dump(true);
w.entries.insert(w.entries.begin(), ZipEntry{kManifestName, std::vector<uint8_t>(text.begin(), text.end())});
// The preview goes second, so loadProjectThumbnail finds it after reading two local headers.
if (const ProjectThumbnailProvider& provider = thumbnailProvider()) {
Image thumb;
std::vector<uint8_t> png;
if (provider(doc, thumb) && !thumb.empty() && thumb.encodePng(png))
w.entries.insert(w.entries.begin() + 1, ZipEntry{kThumbnailName, std::move(png)});
}
// Write next to the target and rename, so a failed save never destroys the previous file.
const std::string tmp = path + ".tmp";
if (!writeStoredZip(tmp, w.entries, 64, error)) return false;
std::error_code ec;
std::filesystem::rename(fsPath(tmp), fsPath(path), ec);
if (ec) {
std::filesystem::remove(fsPath(tmp), ec);
error = "Cannot write " + path;
return false;
}
return true;
}
bool loadProject(const std::string& path, Document& doc, std::string& error) {
Reader r;
if (!r.open(path, error)) return false;
std::vector<uint8_t> manifestText;
if (!r.entry(kManifestName, manifestText)) {
error = path + " is not a SculptForge project (no manifest)";
return false;
}
Json manifest;
if (!Json::parse(std::string(manifestText.begin(), manifestText.end()), manifest, error) || !manifest.isObject() ||
manifest["format"].asString() != kFormatName) {
error = path + " is not a SculptForge project" + (error.empty() ? "" : " (" + error + ")");
return false;
}
manifest = legacy::modernizeKeys(manifest); // keys an older version wrote
const double version = manifest["version"].asNumber(0);
if (version > kProjectVersion) {
error = path + " was saved by a newer SculptForge (" + manifest["app_version"].asString() +
", project format " + std::to_string(int(version)) + "); this version reads format " +
std::to_string(kProjectVersion) + ". Please update SculptForge to open it.";
return false;
}
if (version < 1) {
error = path + " has an invalid project version";
return false;
}
// Parts: version 1 has one mesh at the top level, version 2 a "parts" list.
std::deque<LoadedPart> parts; // (stable addresses: BVH threads use them)
std::string skippedSets; // selection sets that couldn't be read
int activePart = 0;
if (version < 2) {
LoadedPart& s = parts.emplace_back();
s.name = "Sculpt";
if (!readMesh(r, manifest["mesh"], manifest["layers"], s.mesh, error)) return false;
s.activeLayer = int(manifest["active_layer"].asNumber(-1));
} else {
const Json& list = manifest["parts"];
if (!list.isArray() || list.size() == 0 || list.size() > kMaxProjectParts) {
error = "Project has no valid Part list";
return false;
}
for (const Json& sj : list.items()) {
LoadedPart& s = parts.emplace_back();
s.name = sj["name"].asString();
if (s.name.empty()) s.name = "Part";
s.visible = sj["visible"].asBool(true);
if (sj["shading"].isString()) parseShading(sj["shading"].asString(), s.shading); // unknown: Default
s.folder = int(sj["folder"].asNumber(-1));
s.bridgeName = sj["bridge_name"].asString();
s.qremeshGuides = qremeshGuidesFromJson(sj["qremesh_guides"]);
if (sj["transform"].isArray()) s.transform = matrixFromJson(sj["transform"]);
if (const Json& lj = sj["link"]; lj.isNumber()) {
const double l = lj.asNumber(-1);
if (!(l >= 0 && l < double(parts.size() - 1)) || parts[size_t(l)].link >= 0) {
error = "Project Part link is invalid";
return false;
}
s.link = int(l);
continue;
}
if (!readMesh(r, sj["mesh"], sj["layers"], s.mesh, error, false, false)) return false;
s.mesh.forgespheres = forgespheresFromJson(sj["forgespheres"]);
s.mesh.forgespherePreview = !s.mesh.forgespheres.empty() && sj["forgesphere_preview"].asBool(false);
s.mesh.tube = tubeFromJson(sj["tube"]);
readSelectionSets(r, sj["selection_sets"], s.mesh, skippedSets);
// The BVH builds (on the pool) while the levels and topology load (off it), then the normals.
s.startBvh();
r.parallelReads = !s.bvhBuilder.joinable();
if (!readPaintLayers(r, sj["paint_layers"], s.mesh, error)) return false;
if (!readTexture(r, sj["texture"], s.mesh, error)) return false;
if (!readSubdiv(r, sj["subdiv"], s.mesh, error, version < 5)) return false;
s.mesh.rebuildTopology();
s.finishBvh();
r.parallelReads = true;
s.mesh.recomputeAllNormals();
if (const Json& mj = sj["micro"]; mj.isObject() && version >= 7) {
const int level = int(mj["level"].asNumber(0));
if (level < 1 || level > MicroMesh::kMaxLevel) {
error = "Project micro level is invalid";
return false;
}
const uint32_t n = 1u << level;
const size_t count = s.mesh.triangleCount() * size_t((n + 1) * (n + 2) / 2);
const uint32_t samples = (n + 1) * (n + 2) / 2;
MicroStore disp;
std::vector<uint8_t> mask;
if (const Json& pj = mj["displacement_packed"]; pj.isObject()) { // tiles packed (MicroStore.h)
std::vector<uint8_t> packed;
const size_t bytes = countOf(pj["count"]);
if (bytes == size_t(-1) || !r.bytes(pj, "micro displacement", bytes, packed)) {
error = r.error.empty() ? "Project micro displacement is invalid" : r.error;
return false;
}
std::string why;
if (microWantsOutOfCore(count)) disp.assignMapped(count, why);
else disp.assign(count, 0);
if (!microUnpackTiles(packed.data(), packed.size(), s.mesh.triangleCount(), samples, disp.data())) {
error = "Project micro displacement is damaged";
return false;
}
} else {
std::vector<int16_t> plain;
if (!r.int16s(mj["displacement"], "micro displacement", count, plain)) {
error = r.error;
return false;
}
disp = std::move(plain);
}
if (mj["mask"].isObject() && !r.bytes(mj["mask"], "micro mask", count, mask)) {
error = r.error;
return false;
}
if (!microAttach(s.mesh, level, float(mj["step"].asNumber(0)), std::move(disp), std::move(mask), error)) return false;
}
s.activeLayer = int(sj["active_layer"].asNumber(-1));
}
const double active = manifest["active_part"].asNumber(0);
activePart = active >= 0 && active < double(parts.size()) ? int(active) : 0;
}
// Splats
SplatCloud splats;
if (const Json& sj = manifest["splats"]; sj.isObject()) {
const size_t n = countOf(sj["count"]);
const int degree = int(sj["sh_degree"].asNumber(0));
if (n == size_t(-1) || degree < 0 || degree > 3) {
error = "Project splats have an invalid size";
return false;
}
splats.resize(n, degree);
splats.name = sj["name"].isString() ? sj["name"].asString() : splats.name;
splats.transform = matrixFromJson(sj["transform"]);
std::vector<float> rot(n * 4);
r.vec3s(sj["positions"], "splat positions", n, splats.positions);
r.floats(sj["rotations"], "splat rotations", n, 4, rot.data());
r.vec3s(sj["scales"], "splat scales", n, splats.scales);
r.floats(sj["opacities"], "splat opacities", n, 1, splats.opacities.data());
r.vec3s(sj["sh"], "splat colours", n * size_t(splats.shCount()), splats.sh);
if (!r.error.empty()) {
error = r.error;
return false;
}
for (size_t i = 0; i < n; ++i) splats.rotations[i] = glm::quat(rot[i * 4 + 3], rot[i * 4], rot[i * 4 + 1], rot[i * 4 + 2]);
}
// Everything parsed: replace the scene. Part 0 is checked out first; the others are added
// behind it, given their layer and Bridge name, and the saved active Part is selected last.
auto validLayer = [](int layer, const Mesh& m) { return layer >= 0 && layer < int(m.layers.size()) ? layer : -1; };
BVH* built = parts[0].finishBvh();
doc.setMesh(std::move(parts[0].mesh), parts[0].name, built);
doc.activeLayer = validLayer(parts[0].activeLayer, doc.mesh);
doc.bridgeName = parts[0].bridgeName;
doc.qremeshGuides = std::move(parts[0].qremeshGuides);
doc.parts[0].visible = parts[0].visible;
doc.parts[0].shading = parts[0].shading;
doc.parts[0].transform = parts[0].transform;
for (size_t i = 1; i < parts.size(); ++i) {
if (parts[i].link >= 0) { // shares an earlier Part's mesh (Parts load in order: index i is i here too)
const int at = doc.addLink(parts[i].link, parts[i].name, parts[i].transform);
doc.parts[size_t(at)].visible = parts[i].visible;
doc.parts[size_t(at)].shading = parts[i].shading;
continue;
}
BVH* builtI = parts[i].finishBvh();
const int at = doc.addPart(std::move(parts[i].mesh), parts[i].name, false, -1, builtI);
Part& s = doc.parts[size_t(at)];
s.visible = parts[i].visible;
s.shading = parts[i].shading;
s.transform = parts[i].transform;
s.data->activeLayer = validLayer(parts[i].activeLayer, s.data->mesh);
s.data->bridgeName = parts[i].bridgeName;
s.data->qremeshGuides = std::move(parts[i].qremeshGuides);
}
// Folders (#96): a Part pointing at a folder that isn't there is simply outside any folder.
if (const Json& folders = manifest["part_folders"]; folders.isArray() && folders.size() <= kMaxProjectParts) {
std::vector<uint32_t> ids;
for (const Json& fj : folders.items()) {
ids.push_back(doc.addPartFolder(fj["name"].isString() ? fj["name"].asString() : std::string("Folder")));
doc.partFolders.back().collapsed = fj["collapsed"].asBool(false);
}
for (size_t i = 0; i < parts.size(); ++i)
if (parts[i].folder >= 0 && parts[i].folder < int(ids.size())) doc.parts[i].folder = ids[size_t(parts[i].folder)];
}
doc.selectPart(activePart);
if (const double scale = manifest["unitless_scale"].asNumber(0.0); scale > 0.0 && std::isfinite(scale)) {
doc.unitlessScale = scale;
const std::string& format = manifest["unitless_format"].asString();
doc.unitlessFormat = format == "stl" || format == "obj" || format == "ply" ? format : "";
}
doc.splats = std::move(splats);
doc.splatsChanged();
if (!skippedSets.empty())
doc.notice += (doc.notice.empty() ? "" : "; ") + std::string("Selection sets left out (unreadable): ") + skippedSets;
for (const auto& b : manifest["brushes"].items()) {
if (!b.isObject()) continue;
// Brushes the library already has, unchanged, stay library brushes; the rest are the project's own.
BrushRecipe recipe = BrushRecipe::fromJson(b);
const std::string json = recipe.toJson().dump();
const bool known = std::any_of(doc.brushes.begin(), doc.brushes.end(), [&](const BrushRecipe& have) {
return have.name == recipe.name && have.toJson().dump() == json;
});
if (known) continue;
recipe.origin.source = BrushSource::Project;
doc.addBrush(std::move(recipe));
}
doc.activeBrush = -1;
const std::string& activeBrush = manifest["active_brush"].asString();
for (size_t i = 0; i < doc.brushes.size() && !activeBrush.empty(); ++i)
if (doc.brushes[i].name == activeBrush) doc.activeBrush = int(i);
doc.projectSettings = Json::object();
for (const auto& [key, value] : manifest.members())
if (!isCoreKey(key)) doc.projectSettings.set(key, value);
// Attachments are extras (an embedded Lit Sphere): one that can't be read is left out rather than failing the file.
doc.projectFiles.clear();
for (const Json& f : manifest["attachments"].items()) {
const std::string name = legacy::modernize(f["name"].asString()); // our own folder names, e.g. Lit Spheres
const size_t n = countOf(f["data"]["count"]);
if (!validAttachmentName(name) || n == size_t(-1) || n > kMaxAttachmentSize || doc.projectFiles.size() >= 64) continue;
std::vector<uint8_t> bytes;
r.error.clear();
if (r.bytes(f["data"], "attachment", n, bytes)) doc.projectFiles[name] = std::move(bytes);
}
r.error.clear();
doc.path = path;
doc.markClean();
return true;
}
void setProjectThumbnailProvider(ProjectThumbnailProvider provider) { thumbnailProvider() = std::move(provider); }
bool loadProjectThumbnail(const std::string& path, Image& out, std::string& error) {
std::ifstream f(fsPath(path), std::ios::binary);
if (!f) {
error = "Cannot open " + path;
return false;
}
// Walk the local file headers from the start: the thumbnail is the second entry when present,
// so this reads a few hundred bytes plus the PNG instead of the whole project.
for (int entry = 0; entry < 4; ++entry) {
uint8_t h[30];
if (!f.read(reinterpret_cast<char*>(h), sizeof h) || get32(h) != 0x04034B50) break;
const uint32_t method = uint32_t(h[8]) | uint32_t(h[9]) << 8;
const uint32_t size = get32(h + 18);
const size_t nameLen = size_t(h[26]) | size_t(h[27]) << 8, extraLen = size_t(h[28]) | size_t(h[29]) << 8;
std::string name(nameLen, '\0');
if (!f.read(name.data(), std::streamsize(nameLen))) break;
f.seekg(std::streamoff(extraLen), std::ios::cur);
if (name == kThumbnailName && method == 0) {
std::vector<uint8_t> png(size);
if (!f.read(reinterpret_cast<char*>(png.data()), std::streamsize(size))) break;
return Image::decode(png.data(), png.size(), out, error);
}
f.seekg(std::streamoff(size), std::ios::cur);
}
error = path + " has no thumbnail";
return false;
}
CommandResult openProjectCommand(Document& doc, const std::string& path) {
std::string err;
if (!loadProject(path, doc, err)) return {false, err};
std::string msg = "Opened project " + std::filesystem::path(path).filename().string() + " (";
// The Sculpt Timeline saved beside it, if it matches (only into the app's own scene: not thumbnails, scratch opens).
const int histories = &doc == Timeline::historyDocument ? loadHistorySidecar(doc, path) : 0;
if (doc.partCount() > 1) msg += std::to_string(doc.partCount()) + " Parts, ";
size_t tris = 0, layers = 0;
for (int i = 0; i < doc.partCount(); ++i) {
tris += doc.partMesh(i).triangleCount();
layers += doc.partMesh(i).layers.size();
}
msg += std::to_string(tris) + " triangles";
if (layers) msg += ", " + std::to_string(layers) + " layers";
if (!doc.splats.empty()) msg += ", " + std::to_string(doc.splats.size()) + " splats";
if (histories > 0) msg += ", with its history";
return {true, msg + ")"};
}
void registerProjectCommands(CommandRegistry& registry) {
using T = ParamSpec::Type;
registry.add({"save_project",
"Save everything (mesh, mask, vertex paint, face groups, visibility, UVs, sculpt layers, splats, brushes "
"and view settings) as a SculptForge project (.sfproj).",
{{"path", T::String, "Output .sfproj path (UTF-8). Defaults to the current project path.", false}},
[](Document& doc, const Args& a) -> CommandResult {
std::string path = argString(a, "path", isProjectPath(doc.path) ? doc.path : std::string());
if (path.empty()) return {false, "No path given"};
// Any other extension too: "head.obj" must not overwrite an OBJ with a ZIP
// that open, isProjectPath and Ctrl+S would not recognise.
if (!isProjectPath(path)) path += kProjectExtension;
std::string err;
subdivCommit(doc.mesh); // fold pending edits into the levels, so they're written once
if (!saveProject(path, doc, err)) return {false, err};
doc.path = path;
doc.markClean();
// The Sculpt Timeline's history beside it (<name>.sfhist), when the app asks for it.
if (Timeline::saveWithProject && &doc == Timeline::historyDocument && !saveHistorySidecar(doc, path, &err))
return {true, "Saved project " + path + " (the history wasn't saved: " + err + ")"};
return {true, "Saved project " + path};
}});
registry.add({"open_project", "Open a SculptForge project (.sfproj), replacing the current scene.",
{{"path", T::String, ".sfproj path (UTF-8).", true}},
[](Document& doc, const Args& a) -> CommandResult {
return openProjectCommand(doc, argString(a, "path"));
}});
}
// ---------------------------------------------------------------------------
// Recent files
// ---------------------------------------------------------------------------
std::vector<std::string> addRecentFile(std::vector<std::string> list, const std::string& path, size_t limit) {
if (path.empty()) return list;
list.erase(std::remove(list.begin(), list.end(), path), list.end());
list.insert(list.begin(), path);
if (list.size() > limit) list.resize(limit);
return list;
}
std::vector<std::string> pruneRecentFiles(std::vector<std::string> list,
const std::function<bool(const std::string&)>& exists) {
std::vector<std::string> out;
for (auto& p : list)
if (!p.empty() && std::find(out.begin(), out.end(), p) == out.end() && exists(p)) out.push_back(std::move(p));
return out;
}
} // namespace sf