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/MapExport.h"
#include "core/BakeImage.h"
#include "core/Commands.h"
#include "core/Document.h"
#include "core/Json.h"
#include "core/Texture.h"
#include "core/TextureChannels.h"
#include "core/ThreadPool.h"
#include <algorithm>
#include <cctype>
#include <cmath>
#include <cstdio>
#include <cstdlib>
#include <filesystem>
#include <fstream>
#include <sstream>
#include <thread>
namespace sf {
namespace {
// The built-in presets, in the same JSON a user preset file holds (so the parser is what defines them).
const char* const kBuiltinPresets[] = {
R"PRESET({"id": "unreal", "label": "Unreal Engine",
"description": "Base colour (opacity in alpha when painted), DirectX normal, packed occlusion / roughness / metallic. The Unreal bridge imports these and builds a material.",
"file": "T_{name}_{map}", "normal": "directx",
"maps": [{"map": "BC", "channels": ["base_color.r", "base_color.g", "base_color.b", "opacity?"]},
{"map": "N", "channels": ["normal.r", "normal.g", "normal.b"]},
{"map": "ORM", "channels": ["ao", "roughness", "metallic"]},
{"map": "E", "channels": ["emissive.r", "emissive.g", "emissive.b"], "optional": true},
{"map": "H", "channels": ["height"], "bits": 16, "optional": true}]})PRESET",
R"PRESET({"id": "unity_urp", "label": "Unity (URP Lit)",
"description": "Base map, OpenGL normal, metallic in red with smoothness in alpha, occlusion, emission and height.",
"file": "{name}_{map}", "normal": "opengl",
"maps": [{"map": "BaseMap", "channels": ["base_color.r", "base_color.g", "base_color.b", "opacity?"]},
{"map": "Normal", "channels": ["normal.r", "normal.g", "normal.b"]},
{"map": "MetallicSmoothness", "channels": ["metallic", "0", "0", "smoothness"]},
{"map": "Occlusion", "channels": ["ao"], "optional": true},
{"map": "Emission", "channels": ["emissive.r", "emissive.g", "emissive.b"], "optional": true},
{"map": "Height", "channels": ["height"], "bits": 16, "optional": true}]})PRESET",
R"PRESET({"id": "unity_hdrp", "label": "Unity (HDRP Lit)",
"description": "Base map, OpenGL normal and the mask map: metallic, occlusion, detail mask (white), smoothness.",
"file": "{name}_{map}", "normal": "opengl",
"maps": [{"map": "BaseMap", "channels": ["base_color.r", "base_color.g", "base_color.b", "opacity?"]},
{"map": "Normal", "channels": ["normal.r", "normal.g", "normal.b"]},
{"map": "MaskMap", "channels": ["metallic", "ao", "1", "smoothness"]},
{"map": "Emission", "channels": ["emissive.r", "emissive.g", "emissive.b"], "optional": true},
{"map": "Height", "channels": ["height"], "bits": 16, "optional": true}]})PRESET",
R"PRESET({"id": "gltf", "label": "glTF",
"description": "glTF 2.0 metal-rough: base colour, OpenGL normal, occlusion / roughness / metallic packed in R / G / B.",
"file": "{name}_{map}", "normal": "opengl",
"maps": [{"map": "baseColor", "channels": ["base_color.r", "base_color.g", "base_color.b", "opacity?"]},
{"map": "normal", "channels": ["normal.r", "normal.g", "normal.b"]},
{"map": "occlusionRoughnessMetallic", "channels": ["ao", "roughness", "metallic"]},
{"map": "emissive", "channels": ["emissive.r", "emissive.g", "emissive.b"], "optional": true}]})PRESET",
R"PRESET({"id": "godot", "label": "Godot",
"description": "Godot StandardMaterial3D: albedo, OpenGL normal, ORM (occlusion / roughness / metallic), emission, height.",
"file": "{name}_{map}", "normal": "opengl",
"maps": [{"map": "albedo", "channels": ["base_color.r", "base_color.g", "base_color.b", "opacity?"]},
{"map": "normal", "channels": ["normal.r", "normal.g", "normal.b"]},
{"map": "orm", "channels": ["ao", "roughness", "metallic"]},
{"map": "emission", "channels": ["emissive.r", "emissive.g", "emissive.b"], "optional": true},
{"map": "height", "channels": ["height"], "bits": 16, "optional": true}]})PRESET",
R"PRESET({"id": "blender", "label": "Blender",
"description": "One file per channel for the Principled BSDF: base colour, roughness, metallic, OpenGL normal, height (16-bit), AO, emission, alpha.",
"file": "{name}_{map}", "normal": "opengl",
"maps": [{"map": "BaseColor", "channels": ["base_color.r", "base_color.g", "base_color.b"]},
{"map": "Roughness", "channels": ["roughness"]},
{"map": "Metallic", "channels": ["metallic"]},
{"map": "Normal", "channels": ["normal.r", "normal.g", "normal.b"]},
{"map": "Height", "channels": ["height"], "bits": 16, "optional": true},
{"map": "AO", "channels": ["ao"], "optional": true},
{"map": "Emission", "channels": ["emissive.r", "emissive.g", "emissive.b"], "optional": true},
{"map": "Alpha", "channels": ["opacity"], "optional": true}]})PRESET",
R"PRESET({"id": "usd", "label": "USD (UsdPreviewSurface)",
"description": "One file per UsdPreviewSurface input: diffuseColor, roughness, metallic, normal, occlusion, emissiveColor, opacity, displacement.",
"file": "{name}_{map}", "normal": "opengl",
"maps": [{"map": "diffuseColor", "channels": ["base_color.r", "base_color.g", "base_color.b"]},
{"map": "roughness", "channels": ["roughness"]},
{"map": "metallic", "channels": ["metallic"]},
{"map": "normal", "channels": ["normal.r", "normal.g", "normal.b"]},
{"map": "occlusion", "channels": ["ao"], "optional": true},
{"map": "emissiveColor", "channels": ["emissive.r", "emissive.g", "emissive.b"], "optional": true},
{"map": "opacity", "channels": ["opacity"], "optional": true},
{"map": "displacement", "channels": ["height"], "bits": 16, "optional": true}]})PRESET",
};
std::string lower(std::string s) {
for (char& c : s) c = char(std::tolower(static_cast<unsigned char>(c)));
return s;
}
std::filesystem::path fsPath(const std::string& s) { return std::filesystem::path(std::u8string(s.begin(), s.end())); }
std::string utf8(const std::filesystem::path& p) {
const auto u = p.u8string();
return std::string(u.begin(), u.end());
}
// Safe in file names: letters, digits, '-', '_' and '.'.
std::string safeName(const std::string& s) {
std::string out;
for (unsigned char c : s) out += std::isalnum(c) || c == '-' || c == '_' || c == '.' ? char(c) : '_';
return out.empty() ? std::string("Object") : out;
}
// The sources a map keeps for this texture ('?' components dropped when their channel is off).
std::vector<MapSource> keptSources(const PaintTexture& t, const MapSpec& map) {
std::vector<MapSource> out;
for (const MapSource& s : map.sources)
if (!(s.dropIfMissing && s.kind == MapSource::Kind::Channel && !channelEnabled(t, Channel(s.channel)))) out.push_back(s);
if (out.size() == 2) out.resize(1); // grey + alpha isn't offered: keep grey
return out;
}
// Evaluates the map's sources over the texture: fn(x, y, values) with values in 0..1, rows bottom-up.
template <class Fn>
void evaluate(const PaintTexture& t, const std::vector<MapSource>& srcs, bool directX, Fn&& fn) {
bool needNormal = false;
uint32_t needed = 0;
for (const MapSource& s : srcs)
if (s.kind == MapSource::Kind::Channel) {
if (s.channel == int(Channel::Normal)) needNormal = true;
else needed |= 1u << s.channel;
}
const TileImage* imgs[kChannelCount] = {};
for (int c = 1; c < kChannelCount; ++c)
if ((needed & (1u << c)) && channelEnabled(t, Channel(c))) imgs[c] = &channelImage(t, Channel(c));
poolFor(size_t(t.height), [&](size_t b, size_t e) {
float vals[4];
for (int y = int(b); y < int(e); ++y)
for (int x = 0; x < t.width; ++x) {
float chan[kChannelCount][3];
glm::vec3 n(0, 0, 1);
if (needNormal) n = effectiveNormalAt(t, x, y);
const uint8_t* px = &t.pixels[(size_t(y) * size_t(t.width) + size_t(x)) * 4];
for (size_t k = 0; k < srcs.size(); ++k) {
const MapSource& s = srcs[k];
float v = s.constant;
if (s.kind == MapSource::Kind::Channel) {
if (s.channel == int(Channel::BaseColor)) {
v = float(px[std::clamp(s.component, 0, 2)]) / 255.0f;
} else if (s.channel == int(Channel::Normal)) {
float c = n[std::clamp(s.component, 0, 2)];
if (s.component == 1 && directX) c = -c;
v = c * 0.5f + 0.5f;
} else if (const TileImage* img = imgs[s.channel]) {
img->values(x, y, chan[s.channel]);
v = chan[s.channel][std::clamp(s.component, 0, img->components() - 1)];
} else {
v = channelFormat(s.channel).defaultValue[size_t(std::clamp(s.component, 0, 2))];
}
}
vals[k] = std::clamp(s.invert ? 1.0f - v : v, 0.0f, 1.0f);
}
fn(x, y, vals);
}
}, 8, 2);
}
} // namespace
bool parseMapSource(const std::string& textIn, MapSource& out, std::string& error) {
out = MapSource();
std::string text;
for (char c : textIn)
if (!std::isspace(static_cast<unsigned char>(c))) text += char(std::tolower(static_cast<unsigned char>(c)));
if (!text.empty() && text.back() == '?') {
out.dropIfMissing = true;
text.pop_back();
}
if (text.rfind("1-", 0) == 0) {
out.invert = true;
text = text.substr(2);
}
if (text.empty()) {
error = "Empty map source";
return false;
}
if (std::isdigit(static_cast<unsigned char>(text[0])) || text[0] == '.') {
char* end = nullptr;
const float v = std::strtof(text.c_str(), &end);
if (end && *end == '\0' && std::isfinite(v)) {
out.kind = MapSource::Kind::Constant;
out.constant = std::clamp(v, 0.0f, 1.0f);
if (out.invert) out.constant = 1.0f - out.constant, out.invert = false;
return true;
}
}
if (text == "smoothness" || text == "gloss" || text == "glossiness") {
out.kind = MapSource::Kind::Channel;
out.channel = int(Channel::Roughness);
out.invert = !out.invert;
return true;
}
std::string name = text, comp;
if (const size_t dot = text.find('.'); dot != std::string::npos) {
name = text.substr(0, dot);
comp = text.substr(dot + 1);
}
Channel c;
if (!parseChannel(name, c)) {
error = "Unknown map source '" + textIn + "'";
return false;
}
out.kind = MapSource::Kind::Channel;
out.channel = int(c);
if (!comp.empty()) {
static const char* names[] = {"r", "g", "b"};
int found = -1;
for (int i = 0; i < 3; ++i)
if (comp == names[i] || comp == std::string(1, "xyz"[i])) found = i;
if (comp == "a" && c == Channel::BaseColor) { // base colour's alpha is the opacity channel
out.channel = int(Channel::Opacity);
found = 0;
}
if (found < 0 || (found > 0 && channelFormat(out.channel).components < 3 && out.channel != int(Channel::BaseColor))) {
error = "Unknown component in map source '" + textIn + "'";
return false;
}
out.component = found;
}
return true;
}
bool parseExportPreset(const std::string& json, ExportPreset& out, std::string& error) {
Json j;
if (!Json::parse(json, j, error) || !j.isObject()) {
error = "Export preset is not a JSON object" + (error.empty() ? "" : " (" + error + ")");
return false;
}
out = ExportPreset();
out.id = j["id"].asString();
out.label = j["label"].isString() ? j["label"].asString() : out.id;
out.description = j["description"].asString();
out.file = j["file"].isString() ? j["file"].asString() : std::string("{name}_{map}");
if (out.file.find("{map}") == std::string::npos) {
error = "Export preset 'file' must contain {map}";
return false;
}
const std::string normal = lower(j["normal"].isString() ? j["normal"].asString() : std::string("opengl"));
if (normal != "opengl" && normal != "directx") {
error = "Export preset 'normal' must be opengl or directx";
return false;
}
out.normalDirectX = normal == "directx";
if (!j["maps"].isArray() || j["maps"].size() == 0 || j["maps"].size() > 32) {
error = "Export preset needs a list of 1-32 maps";
return false;
}
for (size_t i = 0; i < j["maps"].size(); ++i) {
const Json& mj = j["maps"][i];
MapSpec m;
m.map = mj["map"].asString();
if (m.map.empty() || safeName(m.map) != m.map) {
error = "Export preset map " + std::to_string(i + 1) + " needs a 'map' name of letters, digits, - and _";
return false;
}
const size_t n = mj["channels"].size();
if (!mj["channels"].isArray() || (n != 1 && n != 3 && n != 4)) {
error = "Map '" + m.map + "' needs 1, 3 or 4 channels";
return false;
}
for (size_t k = 0; k < n; ++k) {
MapSource s;
if (!parseMapSource(mj["channels"][k].asString(), s, error)) return false;
m.sources.push_back(s);
}
m.bits = int(mj["bits"].asNumber(8));
if (m.bits != 8 && m.bits != 16) {
error = "Map '" + m.map + "': bits must be 8 or 16";
return false;
}
m.optional = mj["optional"].asBool(false);
out.maps.push_back(std::move(m));
}
return true;
}
const std::vector<ExportPreset>& builtinExportPresets() {
static const std::vector<ExportPreset> presets = [] {
std::vector<ExportPreset> v;
for (const char* text : kBuiltinPresets) {
ExportPreset p;
std::string err;
if (parseExportPreset(text, p, err)) v.push_back(std::move(p));
}
return v;
}();
return presets;
}
bool findExportPreset(const std::string& idOrPath, ExportPreset& out, std::string& error) {
std::string id = lower(idOrPath);
if (id == "ue" || id == "unreal_engine") id = "unreal";
if (id == "unity") id = "unity_urp";
if (id == "urp") id = "unity_urp";
if (id == "hdrp") id = "unity_hdrp";
if (id == "gltf2" || id == "glb") id = "gltf";
for (const ExportPreset& p : builtinExportPresets())
if (p.id == id) {
out = p;
return true;
}
std::ifstream f(fsPath(idOrPath), std::ios::binary);
if (!f) {
std::string ids;
for (const ExportPreset& p : builtinExportPresets()) ids += (ids.empty() ? "" : ", ") + p.id;
error = "No export preset '" + idOrPath + "' (built-in: " + ids + ", or a preset .json file)";
return false;
}
std::stringstream ss;
ss << f.rdbuf();
if (!parseExportPreset(ss.str(), out, error)) return false;
if (out.id.empty()) out.id = utf8(fsPath(idOrPath).stem());
return true;
}
bool mapWanted(const PaintTexture& t, const MapSpec& map) {
if (!map.optional) return true;
for (const MapSource& s : map.sources)
if (s.kind == MapSource::Kind::Channel && s.channel != int(Channel::BaseColor) && channelEnabled(t, Channel(s.channel)))
return true;
return false;
}
bool renderMap(const PaintTexture& t, const MapSpec& map, bool directX, Image& out, int& channels) {
if (t.width <= 0 || t.pixels.size() != t.texelCount() * 4) return false;
const std::vector<MapSource> srcs = keptSources(t, map);
channels = int(srcs.size());
out.width = t.width;
out.height = t.height;
out.rgba.assign(t.texelCount() * 4, 255);
evaluate(t, srcs, directX, [&](int x, int y, const float* v) {
uint8_t* o = &out.rgba[(size_t(t.height - 1 - y) * size_t(t.width) + size_t(x)) * 4];
auto b = [](float f) { return uint8_t(std::lround(f * 255.0f)); };
if (channels == 1) {
o[0] = o[1] = o[2] = b(v[0]);
} else {
o[0] = b(v[0]), o[1] = b(v[1]), o[2] = b(v[2]);
if (channels == 4) o[3] = b(v[3]);
}
});
return true;
}
bool renderMap16(const PaintTexture& t, const MapSpec& map, bool directX, std::vector<uint16_t>& out, int& channels) {
if (t.width <= 0 || t.pixels.size() != t.texelCount() * 4) return false;
const std::vector<MapSource> srcs = keptSources(t, map);
channels = int(srcs.size());
out.assign(t.texelCount() * size_t(channels), 0);
evaluate(t, srcs, directX, [&](int x, int y, const float* v) {
uint16_t* o = &out[(size_t(t.height - 1 - y) * size_t(t.width) + size_t(x)) * size_t(channels)];
for (int k = 0; k < channels; ++k) o[k] = uint16_t(std::lround(v[k] * 65535.0f));
});
return true;
}
std::string mapFileName(const ExportPreset& preset, const MapSpec& map, const std::string& name) {
std::string f = preset.file;
auto put = [&](const std::string& key, const std::string& value) {
for (size_t at = f.find(key); at != std::string::npos; at = f.find(key, at + value.size())) f.replace(at, key.size(), value);
};
put("{name}", safeName(name));
put("{map}", map.map);
return safeName(f) + ".png";
}
bool exportMaps(const PaintTexture& t, const ExportPreset& preset, const std::string& folder, const std::string& name,
std::vector<ExportedMap>& written, std::string& error) {
written.clear();
std::error_code ec;
std::filesystem::create_directories(fsPath(folder), ec);
if (!std::filesystem::is_directory(fsPath(folder))) {
error = "Cannot create the folder " + folder;
return false;
}
// PNG compression is single-threaded and dominates at 4K / 8K: maps are written on up to four threads at once.
std::vector<const MapSpec*> maps;
for (const MapSpec& map : preset.maps)
if (mapWanted(t, map)) maps.push_back(&map);
std::vector<std::string> paths(maps.size()), errors(maps.size());
std::vector<char> ok(maps.size(), 0);
auto writeOne = [&](size_t i) {
const MapSpec& map = *maps[i];
paths[i] = utf8(fsPath(folder) / fsPath(mapFileName(preset, map, name)));
int channels = 0;
if (map.bits == 16) {
std::vector<uint16_t> px;
ok[i] = renderMap16(t, map, preset.normalDirectX, px, channels) && savePng16(paths[i], t.width, t.height, channels, px, errors[i]);
} else {
Image img;
ok[i] = renderMap(t, map, preset.normalDirectX, img, channels) && img.savePng(paths[i], errors[i]);
}
};
constexpr size_t kAtOnce = 4;
for (size_t first = 0; first < maps.size(); first += kAtOnce) {
std::vector<std::thread> threads;
for (size_t i = first + 1; i < std::min(maps.size(), first + kAtOnce); ++i) threads.emplace_back(writeOne, i);
writeOne(first);
for (auto& th : threads) th.join();
}
for (size_t i = 0; i < maps.size(); ++i) {
if (!ok[i]) {
error = errors[i].empty() ? "Cannot write " + paths[i] : errors[i];
return false;
}
written.push_back({maps[i]->map, paths[i]});
}
return true;
}
bool encodeMapPng(const PaintTexture& t, const std::vector<std::string>& sources, bool directX, std::vector<uint8_t>& png) {
MapSpec spec;
spec.map = "map";
for (const std::string& s : sources) {
MapSource src;
std::string err;
if (!parseMapSource(s, src, err)) return false;
spec.sources.push_back(src);
}
Image img;
int channels = 0;
return renderMap(t, spec, directX, img, channels) && img.encodePng(png);
}
std::vector<std::string> pbrSlots(const PaintTexture& t, bool packedOrm) {
std::vector<std::string> out;
if (!hasMaterialChannels(t)) return out;
out.push_back("base_color");
if (channelEnabled(t, Channel::Normal) || channelEnabled(t, Channel::Height)) out.push_back("normal");
if (packedOrm) {
out.push_back("orm");
} else {
out.push_back("roughness");
out.push_back("metallic");
if (channelEnabled(t, Channel::AO)) out.push_back("occlusion");
}
if (channelEnabled(t, Channel::Emissive)) out.push_back("emissive");
if (!packedOrm && channelEnabled(t, Channel::Opacity)) out.push_back("opacity");
return out;
}
std::vector<std::string> pbrSlotSources(const std::string& slot) {
if (slot == "base_color") return {"base_color.r", "base_color.g", "base_color.b", "opacity?"};
if (slot == "normal") return {"normal.r", "normal.g", "normal.b"};
if (slot == "orm") return {"ao", "roughness", "metallic"};
if (slot == "roughness") return {"roughness"};
if (slot == "metallic") return {"metallic"};
if (slot == "occlusion") return {"ao"};
if (slot == "emissive") return {"emissive.r", "emissive.g", "emissive.b"};
if (slot == "opacity") return {"opacity"};
return {};
}
void registerMapExportCommands(CommandRegistry& reg) {
using T = ParamSpec::Type;
reg.add({"export_maps",
"Export the active Part's texture channels as image files for an engine or DCC, using an export "
"preset: unreal (T_<name>_BC / _N in DirectX / _ORM), unity_urp, unity_hdrp (mask map), gltf, godot, "
"blender (one file per channel), usd, or your own preset .json file (docs/guide/export-presets.md). "
"list=true lists the presets.",
{{"preset", T::String, "Preset id or a preset .json path. Default gltf.", false},
{"folder", T::String, "Output folder (created if missing).", false},
{"name", T::String, "Object name in the file names. Default: the Part's name.", false},
{"list", T::Bool, "List the built-in presets instead.", false}},
[](Document& doc, const Args& a) -> CommandResult {
if (argBool(a, "list", false)) {
std::string s = "Export presets:";
for (const ExportPreset& p : builtinExportPresets()) {
s += "\n " + p.id + " (" + p.label + "):";
for (const MapSpec& m : p.maps) s += " " + m.map + (m.optional ? "?" : "");
}
return {true, s};
}
if (!hasTexture(doc.mesh))
return {false, "The Part has no texture: create one first (Tool > Texture Map > New, or texture_create)"};
const std::string folder = argString(a, "folder");
if (folder.empty()) return {false, "Give a folder"};
ExportPreset preset;
std::string err;
if (!findExportPreset(argString(a, "preset", "gltf"), preset, err)) return {false, err};
std::string name = argString(a, "name");
if (name.empty() && doc.activePart >= 0 && doc.activePart < doc.partCount())
name = doc.parts[size_t(doc.activePart)].name;
if (name.empty()) name = "Sculpt";
std::vector<ExportedMap> written;
if (!exportMaps(*doc.mesh.texture, preset, folder, name, written, err)) return {false, err};
std::string files;
for (const ExportedMap& m : written) files += "\n " + m.path;
return {true, "Exported " + std::to_string(written.size()) + " " + preset.label + " maps (" +
std::to_string(doc.mesh.texture->width) + "x" + std::to_string(doc.mesh.texture->height) + "):" + files};
}});
}
} // namespace sf