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
Rodin 2.5 (Hyper3D) via fal.ai in Generate 3D, image_to_3d and text_to_3d (#123, credit ElgoogUdiab)
islandmedf15833da137c
diff --git a/changes/feat-rodin-fal.md b/changes/feat-rodin-fal.mdnew file mode 100644index 00000000..ef5b3867--- /dev/null+++ b/changes/feat-rodin-fal.md@@ -0,0 +1,15 @@+---+whats_new: **Rodin 2.5 in Generate 3D**: **Generate 3D > fal.ai > Model** now offers Hyper3D **Rodin 2.5** and+ **Rodin 2.5 Fast**, from an image or a description, with your fal.ai key.+added: **Rodin 2.5 (Hyper3D) via fal.ai** (#123, thanks ElgoogUdiab): **Generate 3D > fal.ai > Model** lists+ **Rodin 2.5** and **Rodin 2.5 Fast**. Image and text both work; the untextured GLB goes through the usual import+ and remesh. Uses your fal.ai key (`FAL_KEY`), nothing else is contacted. Commands:+ `image_to_3d service=fal model=fal-ai/hyper3d/rodin/v2.5`, `text_to_3d service=fal model=fal-ai/hyper3d/rodin/v2.5`+ (other fal models keep Hunyuan3D 3.1 Rapid for text).+testers:+ - Any OS with a fal.ai key: Generate 3D > fal.ai > Model > Rodin 2.5, drop teddy-sketch.png, Generate: a sculptable+ teddy arrives (quad remeshed). From text tab, "a cartoon fox sitting": a fox.+ - Rodin 2.5 Fast: same, faster and coarser.+---+In-house re-implementation from the description of outside PR #123 (network code from outside PRs is rebuilt, not+merged). fal.ai only; no direct Hyper3D API, no new hosts, no built-in keys.diff --git a/docs/ai-services.md b/docs/ai-services.mdindex 98d4b0ab..92bcecba 100644--- a/docs/ai-services.md+++ b/docs/ai-services.md@@ -68,4 +68,5 @@ See [Generate 3D with your own ComfyUI](comfyui.md).## Paid servicesfal.ai and Meshy are paid services with their own terms of service and pricing; generations are-billed to your account with them. Model availability and names can change on their side.+billed to your account with them. Hyper3D Rodin 2.5 runs through fal.ai with your fal.ai key: the+image or description goes to fal.ai, which runs Rodin; SculptForge never contacts Hyper3D directly. Model availability and names can change on their side.diff --git a/docs/generators.md b/docs/generators.mdindex 968afca0..8952fe20 100644--- a/docs/generators.md+++ b/docs/generators.md@@ -5,7 +5,7 @@| Service | What it is | Setup ||---|---|---|| **Hugging Face** (default, free) | The official public demos of Hunyuan3D 2.1 / 2 / 2 mini Turbo (Tencent), TRELLIS.2 (Microsoft) and Stable Fast 3D (Stability AI), on Hugging Face's shared ZeroGPU hardware | Nothing. A free token from huggingface.co/settings/tokens (read access), or `HF_TOKEN`, raises the daily GPU allowance; TRELLIS.2 needs one |-| **fal.ai** | Hosted reconstruction models, billed per generation: TRELLIS.2 (Microsoft), Hunyuan3D 3.1 Pro/Rapid (Tencent), Meshy 6 - or any other fal model id | Key from fal.ai/dashboard/keys, or `FAL_KEY` |+| **fal.ai** | Hosted reconstruction models, billed per generation: TRELLIS.2 (Microsoft), Hunyuan3D 3.1 Pro/Rapid (Tencent), Meshy 6, Hyper3D Rodin 2.5 (image or text) - or any other fal model id | Key from fal.ai/dashboard/keys, or `FAL_KEY` || **Meshy** | Meshy's own API (`meshy-7.1` by default) | Key from meshy.ai, or `MESHY_API_KEY` || **ComfyUI** | Any workflow on your own ComfyUI, on this computer or a studio GPU server: Hunyuan3D, TRELLIS, your own graph. See [comfyui.md](comfyui.md) | The server address and an API-format workflow (bundled ones included) || **My generator command** | Anything you run locally (see below) | A command line |@@ -37,6 +37,7 @@ From the command line or an MCP agent:sculptforge-cli -c 'image_to_3d path=hero.png; export_glb path=hero.glb' # free (Hunyuan3D 2.1)HF_TOKEN=... sculptforge-cli -c 'image_to_3d path=hero.png model=trellis-2; export_glb path=hero.glb'FAL_KEY=... sculptforge-cli -c 'image_to_3d path=hero.png service=fal model=fal-ai/trellis-2; export_glb path=hero.glb'+FAL_KEY=... sculptforge-cli -c 'text_to_3d prompt="a dragon head" service=fal model=fal-ai/hyper3d/rodin/v2.5; export_glb path=dragon.glb'MESHY_API_KEY=... sculptforge-cli -c 'image_to_3d path=hero.png service=meshy remesh=false; export_usd path=hero.usdz'```diff --git a/docs/guide/generate-3d.md b/docs/guide/generate-3d.mdindex 686e92ed..f8ca308a 100644--- a/docs/guide/generate-3d.md+++ b/docs/guide/generate-3d.md@@ -74,7 +74,7 @@ Which model runs depends on the service:| Service | Text-to-3D model ||---|---|| Hugging Face | Hunyuan3D 2 mini Turbo (Tencent), or Hunyuan3D 2 if you chose it in **Model**. Any other choice uses Turbo |-| fal.ai | Hunyuan3D 3.1 Rapid (Tencent) |+| fal.ai | Rodin 2.5 (Hyper3D) when it is the chosen **Model** (Rodin 2.5 or Rodin 2.5 Fast), otherwise Hunyuan3D 3.1 Rapid (Tencent) || Meshy | Meshy's own text-to-3D model || ComfyUI | The text workflow you choose (the bundled `text-to-3d` uses FLUX.1 schnell and Hunyuan3D 2.1) |@@ -122,8 +122,10 @@ it to refill, or pick another model.### fal.ai and Meshy (paid)-- **fal.ai**: choose a **Model** (TRELLIS.2, Hunyuan3D 3.1 Pro, Hunyuan3D 3.1 Rapid or Meshy 6) or type any- fal model id into **Model id**. Paste your key from fal.ai/dashboard/keys into **API key**, or set+- **fal.ai**: choose a **Model** (TRELLIS.2, Hunyuan3D 3.1 Pro, Hunyuan3D 3.1 Rapid, Meshy 6, Rodin 2.5 or+ Rodin 2.5 Fast) or type any fal model id into **Model id**. Rodin 2.5 (Hyper3D) works from an image or a+ description; SculptForge asks it for the shape only (GLB, no materials). Rodin 2.5 Fast is cheaper and+ low poly (up to about 20K triangles), fine as a blockout before remeshing. Paste your key from fal.ai/dashboard/keys into **API key**, or set`FAL_KEY`.- **Meshy**: paste your key from meshy.ai (API settings) into **API key**, or set `MESHY_API_KEY`.diff --git a/src/ai/AiCommands.cpp b/src/ai/AiCommands.cppindex e212ed9f..6a50cacf 100644--- a/src/ai/AiCommands.cpp+++ b/src/ai/AiCommands.cpp@@ -98,7 +98,7 @@ void addAiFeatureCommands(CommandRegistry& registry, std::function<AiSettings()>"ComfyUI (service=comfyui workflow=FILE). Replaces the scene. A transparent background works best.",{{"path", T::String, "Image file (png, jpg...).", true},{"service", T::String, "'huggingface' (free, default), 'fal', 'meshy', 'comfyui' (your ComfyUI server), 'command' (your generator) or 'inflate' (offline blockout).", false},- {"model", T::String, "huggingface: hunyuan3d-2.1 (default, no token), trellis-2 (needs HF_TOKEN, else hunyuan3d-2.1 runs), hunyuan3d-2-turbo, hunyuan3d-2, stable-fast-3d; fal: a model id such as fal-ai/trellis-2.", false},+ {"model", T::String, "huggingface: hunyuan3d-2.1 (default, no token), trellis-2 (needs HF_TOKEN, else hunyuan3d-2.1 runs), hunyuan3d-2-turbo, hunyuan3d-2, stable-fast-3d; fal: a model id such as fal-ai/trellis-2 or fal-ai/hyper3d/rodin/v2.5.", false},{"workflow", T::String, "comfyui: API-format workflow file (default: your saved one, else the bundled one).", false},{"url", T::String, "comfyui: server address. Default http://127.0.0.1:8188 or your saved one.", false},{"seed", T::Number, "comfyui: seed for the workflow's sf_seed / seed inputs (default: random).", false},@@ -139,7 +139,8 @@ void addAiFeatureCommands(CommandRegistry& registry, std::function<AiSettings()>"Meshy (MESHY_API_KEY), or a workflow on your own ComfyUI (service=comfyui workflow=FILE). Replaces the scene.",{{"prompt", T::String, "One object, e.g. 'a stylised dragon head with curled horns'.", true},{"service", T::String, "'huggingface' (free, default), 'fal', 'meshy' or 'comfyui' (your ComfyUI server).", false},- {"model", T::String, "huggingface: hunyuan3d-2-turbo or hunyuan3d-2.", false},+ {"model", T::String, "huggingface: hunyuan3d-2-turbo or hunyuan3d-2; fal: fal-ai/hyper3d/rodin/v2.5 (or /fast), "+ "else Hunyuan3D 3.1 Rapid.", false},{"workflow", T::String, "comfyui: API-format workflow file (default: your saved one, else the bundled one).", false},{"url", T::String, "comfyui: server address. Default http://127.0.0.1:8188 or your saved one.", false},{"seed", T::Number, "comfyui: seed for the workflow's sf_seed / seed inputs (default: random).", false},@@ -159,7 +160,8 @@ void addAiFeatureCommands(CommandRegistry& registry, std::function<AiSettings()>"service=huggingface, fal, meshy or comfyui"};if (a.contains("model")) {if (s.generatorService == "meshy") s.meshyModel = argString(a, "model");- else if (s.generatorService != "fal") s.hfModel = argString(a, "model");+ else if (s.generatorService == "fal") s.falModel = argString(a, "model");+ else s.hfModel = argString(a, "model");}const auto stem = std::filesystem::temp_directory_path() /("sculptforge_text_" +diff --git a/src/ai/ImageTo3DService.cpp b/src/ai/ImageTo3DService.cppindex 5803c83b..f20fbad2 100644--- a/src/ai/ImageTo3DService.cpp+++ b/src/ai/ImageTo3DService.cpp@@ -357,6 +357,8 @@ const std::vector<ServiceModel>& falModels() {{"fal-ai/hunyuan-3d/v3.1/pro/image-to-3d", "Hunyuan3D 3.1 Pro (Tencent)"},{"fal-ai/hunyuan-3d/v3.1/rapid/image-to-3d", "Hunyuan3D 3.1 Rapid (Tencent) - fast"},{"fal-ai/meshy/v6/image-to-3d", "Meshy 6"},+ {"fal-ai/hyper3d/rodin/v2.5", "Rodin 2.5 (Hyper3D) - image or text"},+ {"fal-ai/hyper3d/rodin/v2.5/fast", "Rodin 2.5 Fast (Hyper3D) - low poly, cheaper"},};return models;}@@ -461,7 +463,30 @@ const std::vector<HfPreset>& hfPresets() {return presets;}+bool rodinModel(std::string_view id) { return id.find("hyper3d/rodin") != std::string_view::npos; }++std::string falTextModel(const std::string& falModel) {+ return rodinModel(falModel) ? falModel : std::string("fal-ai/hunyuan-3d/v3.1/rapid/text-to-3d");+}++namespace {+// Rodin's fields: a list of images, the mesh as GLB, no material (we sculpt the shape; skips texturing).+Json rodinBody() {+ Json body = Json::object();+ body.set("geometry_file_format", "glb");+ body.set("material", "None");+ return body;+}+} // namespace+std::string falSubmitBody(const std::string& model, const std::string& dataUri) {+ if (rodinModel(model)) {+ Json body = rodinBody();+ Json images = Json::array();+ images.push(dataUri);+ body.set("image_urls", images);+ return body.dump();+ }Json body = Json::object();const bool hunyuan = model.find("hunyuan") != std::string::npos;body.set(hunyuan ? "input_image_url" : "image_url", dataUri);@@ -546,7 +571,12 @@ std::string meshyTextBody(const std::string& model, const std::string& prompt) {return body.dump();}-std::string falTextBody(const std::string& prompt) {+std::string falTextBody(const std::string& prompt, const std::string& model) {+ if (rodinModel(model)) {+ Json body = rodinBody();+ body.set("prompt", prompt.substr(0, 800));+ return body.dump();+ }Json body = Json::object();body.set("prompt", prompt.substr(0, 200));body.set("enable_geometry", true); // shape only@@ -563,7 +593,7 @@ GeneratorResult generate3DFromText(const AiSettings& s, const std::string& promp}if (s.generatorService == "meshy") return runMeshyRequest(s, "/openapi/v2/text-to-3d", meshyTextBody(s.meshyModel, prompt), outputStem, progress);if (s.generatorService == "fal")- return runFalRequest(s, "fal-ai/hunyuan-3d/v3.1/rapid/text-to-3d", falTextBody(prompt), outputStem, progress);+ return runFalRequest(s, falTextModel(s.falModel), falTextBody(prompt, s.falModel), outputStem, progress);if (s.generatorService == "comfyui") return comfy::run(s, {}, {}, prompt, outputStem, progress);if (s.generatorService == "command" || s.generatorService == "inflate") {result.error = "Text to 3D needs Hugging Face (free), fal.ai, Meshy or ComfyUI - pick one of those services";diff --git a/src/ai/ImageTo3DService.h b/src/ai/ImageTo3DService.hindex f1d6b6a1..efac60e9 100644--- a/src/ai/ImageTo3DService.h+++ b/src/ai/ImageTo3DService.h@@ -3,7 +3,7 @@//// Real image-to-3D reconstruction through hosted models, with your own key:// - fal.ai: one key for TRELLIS.2 (Microsoft), Hunyuan3D 3.1 (Tencent),-// Meshy 6 and other models, billed per generation+// Meshy 6, Hyper3D Rodin 2.5 and other models, billed per generation// - Hugging Face Spaces: free public demos of TRELLIS.2, Hunyuan3D 2 / 2.1 and// Stable Fast 3D on shared GPUs (daily quota; a free HF token raises it)// - Meshy: direct API@@ -85,9 +85,14 @@ GeneratorResult generate3D(const AiSettings& settings, const std::string& imagePGeneratorResult generate3DFromText(const AiSettings& settings, const std::string& prompt, const std::string& outputStem,GenerationProgress* progress = nullptr);+// Hyper3D Rodin on fal.ai: image or text to 3D on one endpoint.+bool rodinModel(std::string_view id);+// The fal.ai model text to 3D runs: the chosen one when it takes text (Rodin), else Hunyuan3D 3.1 Rapid.+std::string falTextModel(const std::string& falModel);+// Pieces exposed for tests.std::string meshyTextBody(const std::string& model, const std::string& prompt);-std::string falTextBody(const std::string& prompt);+std::string falTextBody(const std::string& prompt, const std::string& model = {});// The image as sent to services: subject framed on a square, <= 1024 px, PNG.bool prepareImagePng(const std::string& imagePath, std::string& png, std::string& error);bool prepareImageDataUri(const std::string& imagePath, std::string& dataUri, std::string& error);diff --git a/src/app/App.cpp b/src/app/App.cppindex bdb2a10b..073957fc 100644--- a/src/app/App.cpp+++ b/src/app/App.cpp@@ -3263,7 +3263,8 @@ void App::startGenerator() {ai::AiSettings settings = aiSettings_;const bool hunyuan = settings.generatorService == "huggingface"? ai::hunyuanModel(ai::resolveHfPreset(settings, textMode_).id)- : settings.generatorService == "fal" && ai::hunyuanModel(settings.falModel);+ : settings.generatorService == "fal" &&+ ai::hunyuanModel(textMode_ ? ai::falTextModel(settings.falModel) : settings.falModel);if (hunyuan) showHunyuanNoticeOnce();if (settings.comfyImageWorkflow.empty()) settings.comfyImageWorkflow = comfyDefaultWorkflow(false);if (settings.comfyTextWorkflow.empty()) settings.comfyTextWorkflow = comfyDefaultWorkflow(true);@@ -3547,7 +3548,9 @@ void App::drawImageTo3D() {}if (ImGui::IsItemHovered(ImGuiHoveredFlags_DelayNormal)) ImGui::SetTooltip("%s", ai::kHunyuanLicenceNote);ImGui::InputText("Model id", falModel_, sizeof falModel_);- if (ai::hunyuanModel(falModel_)) hint(ai::kHunyuanLicenceNote);+ if (textMode_ && !ai::rodinModel(falModel_)) hint("From text: Hunyuan3D 3.1 Rapid runs (Rodin 2.5 takes text too).");+ if (ai::hunyuanModel(textMode_ ? ai::falTextModel(falModel_) : std::string(falModel_)))+ hint(ai::kHunyuanLicenceNote);ImGui::InputText("API key", falKey_, sizeof falKey_, ImGuiInputTextFlags_Password);if (!falKey_[0]) hint(std::getenv("FAL_KEY") ? "Using FAL_KEY from the environment." : "Get a key at fal.ai/dashboard/keys");} else if (serviceId == "meshy") {diff --git a/tests/test_rodin_fal.cpp b/tests/test_rodin_fal.cppnew file mode 100644index 00000000..27e3f963--- /dev/null+++ b/tests/test_rodin_fal.cpp@@ -0,0 +1,123 @@+// SculptForge - open source digital sculpting+// SPDX-License-Identifier: GPL-3.0-or-later+//+// Hyper3D Rodin 2.5 through fal.ai (#123): request bodies, the fal queue flow against a local fake fal.ai with+// Rodin's documented replies, and nothing sent while AI is off. No real service is contacted.+#include "TestHarness.h"++#include "ai/AiPolicy.h"+#include "ai/Http.h"+#include "ai/ImageTo3DService.h"+#include "link/HttpServer.h"++#include <filesystem>+#include <fstream>+#include <mutex>++using namespace sf;++namespace {++Json parsed(const std::string& text) {+ Json j;+ std::string err;+ CHECK(Json::parse(text, j, err));+ return j;+}++} // namespace++TEST(rodin_fal_request_bodies) {+ CHECK(ai::rodinModel("fal-ai/hyper3d/rodin/v2.5") && ai::rodinModel("fal-ai/hyper3d/rodin/v2.5/fast"));+ CHECK(!ai::rodinModel("fal-ai/trellis-2") && !ai::hunyuanModel("fal-ai/hyper3d/rodin/v2.5"));+ bool listed = false;+ for (const auto& m : ai::falModels()) listed = listed || std::string(m.id) == "fal-ai/hyper3d/rodin/v2.5";+ CHECK(listed);++ // Image: a list of images (the prepared data URI), GLB, no material: the shape is what we sculpt.+ Json body = parsed(ai::falSubmitBody("fal-ai/hyper3d/rodin/v2.5", "data:image/png;base64,AAAA"));+ CHECK(body["image_urls"].isArray() && body["image_urls"][0].asString() == "data:image/png;base64,AAAA");+ CHECK(!body["image_url"].isString());+ CHECK(body["geometry_file_format"].asString() == "glb");+ CHECK(body["material"].asString() == "None");++ // Text: Rodin takes the prompt on the same endpoint; other fal models keep Hunyuan3D 3.1 Rapid's text endpoint.+ CHECK(ai::falTextModel("fal-ai/hyper3d/rodin/v2.5/fast") == "fal-ai/hyper3d/rodin/v2.5/fast");+ CHECK(ai::falTextModel("fal-ai/trellis-2") == "fal-ai/hunyuan-3d/v3.1/rapid/text-to-3d");+ body = parsed(ai::falTextBody(std::string(300, 'x'), "fal-ai/hyper3d/rodin/v2.5"));+ CHECK(body["prompt"].asString().size() == 300 && !body["image_urls"].isArray());+ CHECK(body["geometry_file_format"].asString() == "glb" && body["material"].asString() == "None");+ CHECK(!body["enable_geometry"].isBool()); // Hunyuan's field, not Rodin's++ // Rodin's reply: model_mesh is the GLB; the textures (PNG) are not the model.+ std::string ext;+ Json reply = parsed(R"({"model_mesh":{"url":"https://v3.fal.media/files/x/base_basic_shaded.glb",+ "content_type":"model/gltf-binary","file_name":"base_basic_shaded.glb","file_size":1234},+ "seed":42,"textures":[{"url":"https://v3.fal.media/files/x/texture.png","content_type":"image/png"}]})");+ CHECK(ai::findModelUrl(reply, &ext) == "https://v3.fal.media/files/x/base_basic_shaded.glb" && ext == ".glb");+}++TEST(rodin_fal_text_to_3d_mocked) {+ // A fake fal.ai queue: submit, one status poll, the result, then the file download, all on 127.0.0.1.+ link::HttpServer server;+ link::HttpServer::Options o;+ o.bindAddress = "127.0.0.1";+ std::mutex mutex;+ std::string submittedPath, submittedBody, authorization;+ std::string base;+ const std::string glb = "glTF fake mesh bytes";+ std::string err;+ CHECK(server.start(o, [&](const link::HttpRequest& r) {+ std::lock_guard lock(mutex);+ if (r.method == "POST") {+ submittedPath = r.path;+ submittedBody = r.body;+ authorization = r.header("authorization");+ return link::HttpResponse::json(200, R"({"request_id":"req1","status_url":")" + base ++ R"(/fal-ai/hyper3d/requests/req1/status","response_url":")" + base ++ R"(/fal-ai/hyper3d/requests/req1"})");+ }+ if (r.path.ends_with("/status")) return link::HttpResponse::json(200, R"({"status":"COMPLETED"})");+ if (r.path == "/fal-ai/hyper3d/requests/req1")+ return link::HttpResponse::json(200, R"({"model_mesh":{"url":")" + base + R"(/files/mesh.glb"},"seed":7,)"+ R"("textures":[{"url":")" + base + R"(/files/texture.png"}]})");+ if (r.path == "/files/mesh.glb") return link::HttpResponse::bytes("model/gltf-binary", glb);+ return link::HttpResponse::text(404, "not found");+ }, err));+ base = "http://127.0.0.1:" + std::to_string(server.port());++ ai::AiSettings s = ai::AiSettings::defaults(ai::AiSettings::Provider::Free);+ s.generatorService = "fal";+ s.falModel = "fal-ai/hyper3d/rodin/v2.5";+ s.falKey = "test-key";+ s.falEndpoint = base + "/";+ const std::string stem = tempPath("sf_rodin_text");+ ai::GeneratorResult r = ai::generate3DFromText(s, "a stylised dragon head", stem);+ server.stop();+ CHECK(r.ok);+ CHECK(r.outputPath == stem + ".glb");+ std::ifstream f(r.outputPath, std::ios::binary);+ CHECK(std::string(std::istreambuf_iterator<char>(f), {}) == glb);+ f.close();+ std::filesystem::remove(r.outputPath);+ CHECK(submittedPath == "/fal-ai/hyper3d/rodin/v2.5");+ CHECK(authorization == "Key test-key");+ Json body = parsed(submittedBody);+ CHECK(body["prompt"].asString() == "a stylised dragon head" && body["material"].asString() == "None");+}++TEST(rodin_fal_ai_off_sends_nothing) {+ const bool was = ai::aiEnabled();+ ai::setAiEnabled(false);+ const uint64_t before = ai::httpRequestCount();+ ai::AiSettings s = ai::AiSettings::defaults(ai::AiSettings::Provider::Free);+ s.generatorService = "fal";+ s.falKey = "test-key";+ for (const char* model : {"fal-ai/hyper3d/rodin/v2.5", "fal-ai/hyper3d/rodin/v2.5/fast"}) {+ s.falModel = model;+ CHECK(ai::generate3D(s, "missing.png", tempPath("sf_rodin_off")).error.find("AI features") != std::string::npos);+ CHECK(ai::generate3DFromText(s, "a fox", tempPath("sf_rodin_off")).error.find("AI features") != std::string::npos);+ }+ CHECK(ai::httpRequestCount() == before);+ ai::setAiEnabled(was);+}