Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

forge(pbr): run material completion on every delivered mesh, opt out with derive_pbr

nirholas48cf04323877
diff --git a/api/_lib/forge-options.js b/api/_lib/forge-options.js
index ab5c85824..b46b16f0c 100644
--- a/api/_lib/forge-options.js
+++ b/api/_lib/forge-options.js
@@ -8,6 +8,10 @@
// • output_format — glb (default) or a compressed variant (draco / meshopt)
// • texture_size — bake textures at a specific resolution
// • target_polycount — explicit geometry budget on poly-aware backends
+// • derive_pbr — the ONE exception to "off by default": the material
+// completion pass (glb-pbr-derive.js) runs on every delivered mesh, because
+// an albedo-only material is a defect rather than a preference. Send
+// `derive_pbr: false` to receive the lane's own materials untouched.
//
// normalizeForgeOptions() validates and clamps; an explicitly-present but invalid
// value is reported in `errors` so the endpoint can answer 400 with an actionable
@@ -41,6 +45,7 @@ function compressionFor(format) {
* compression: 'none' | 'draco' | 'meshopt',
* textureSize: number | null,
* targetPolycount: number | null,
+ * derivePbr: boolean, // material completion pass — true unless opted out
* hasOptions: boolean, // true iff any non-default option was supplied
* errors: Array<{ field: string, message: string }>,
* }}
@@ -108,8 +113,20 @@ export function normalizeForgeOptions(body) {
}
}
+ // derive_pbr — opt-OUT. Anything other than an explicit boolean false leaves
+ // the completion pass on; a non-boolean value is reported rather than
+ // silently coerced, so `derive_pbr: "no"` never reads as true.
+ let derivePbr = true;
+ if (b.derive_pbr !== undefined && b.derive_pbr !== null) {
+ if (typeof b.derive_pbr !== 'boolean') {
+ errors.push({ field: 'derive_pbr', message: 'derive_pbr must be true or false.' });
+ } else {
+ derivePbr = b.derive_pbr;
+ }
+ }
+
const hasOptions =
- seed !== null || outputFormat !== 'glb' || textureSize !== null || targetPolycount !== null;
+ seed !== null || outputFormat !== 'glb' || textureSize !== null || targetPolycount !== null || !derivePbr;
return {
seed,
@@ -117,6 +134,7 @@ export function normalizeForgeOptions(body) {
compression: compressionFor(outputFormat),
textureSize,
targetPolycount,
+ derivePbr,
hasOptions,
errors,
};
@@ -148,5 +166,6 @@ export function summarizeForgeOptions(opts) {
output_format: opts.outputFormat,
texture_size: opts.textureSize,
target_polycount: opts.targetPolycount,
+ derive_pbr: opts.derivePbr !== false,
};
}
diff --git a/api/_lib/forge-store.js b/api/_lib/forge-store.js
index 06c672448..aaf3995b2 100644
--- a/api/_lib/forge-store.js
+++ b/api/_lib/forge-store.js
@@ -394,18 +394,20 @@ async function copyToBucket({ sourceUrl, key, fallbackContentType, maxBytes, com
let quality = null;
let compression = null;
let cleaned = null;
- if (computeQuality || compress || cleanup) {
- const scored = await scoreAndCompress(buf, { computeQuality, compress, cleanup });
+ let pbr = null;
+ if (computeQuality || compress || cleanup || derivePbr) {
+ const scored = await scoreAndCompress(buf, { computeQuality, compress, cleanup, derivePbr, prompt, tier, materialClass });
buf = scored.buf;
quality = scored.quality;
compression = scored.compression;
cleaned = scored.cleaned;
+ pbr = scored.pbr;
}
await putObject({ key, body: buf, contentType, metadata: { source: 'forge' } });
// `buffer` is the bytes actually stored, post-cleanup and post-compression, so
// a caller that hashes or grades them is describing the asset users receive
// rather than the provider's original, and does it without a second fetch.
- return { bytes: buf.length, publicUrl: publicUrl(key), quality, compression, cleaned, buffer: buf };
+ return { bytes: buf.length, publicUrl: publicUrl(key), quality, compression, cleaned, pbr, buffer: buf };
}
function imageExtFor(url) {
@@ -464,7 +466,15 @@ function gradeDeliveredMesh({ buffer, creationId, sourceUrl }) {
// every forge mesh is raw marching-cubes output that benefits, and
// it's best-effort (any failure ships the original bytes). Pass
// false to deliver the provider geometry untouched.
-export async function materializeCreation({ replicateJobId, clientKey, glbUrl, quality = false, compress = null, cleanup = true }) {
+// derivePbr - complete the material set (glb-pbr-derive.js): a derived normal
+// map, a packed occlusion/roughness/metallic map, the material
+// class's measured factors and its real-world extension layer. On
+// by default, because every reconstruction lane bakes an albedo
+// and stops (the free TRELLIS lanes ship no materials at all, so
+// glTF's default fully-metallic material renders them as rough
+// metal). Best-effort like the rest of the chain; pass false to
+// deliver the lane's own materials untouched.
+export async function materializeCreation({ replicateJobId, clientKey, glbUrl, quality = false, compress = null, cleanup = true, derivePbr = true }) {
if (!forgeStoreEnabled() || !replicateJobId || !glbUrl) return null;
const existing = await findByJob({ replicateJobId, clientKey });
if (!existing) return null;
@@ -477,6 +487,7 @@ export async function materializeCreation({ replicateJobId, clientKey, glbUrl, q
quality: null,
compression: null,
cleaned: null,
+ pbr: null,
};
}
@@ -490,6 +501,12 @@ export async function materializeCreation({ replicateJobId, clientKey, glbUrl, q
computeQuality: quality,
compress,
cleanup,
+ derivePbr,
+ // The row carries the words the material classifier reads and the tier
+ // that sets the derived maps' resolution, so no caller has to thread
+ // either through the poll path.
+ prompt: existing.prompt || '',
+ tier: existing.tier || '',
});
// Reference image is part of the training pair but never blocks the mesh.
@@ -551,6 +568,7 @@ export async function materializeCreation({ replicateJobId, clientKey, glbUrl, q
quality: glb.quality ?? null,
compression: glb.compression ?? null,
cleaned: glb.cleaned ?? null,
+ pbr: glb.pbr ?? null,
};
} catch (err) {
// A 404/410 means the provider's ephemeral asset (e.g. a HuggingFace Space's
diff --git a/api/gpt-forge.js b/api/gpt-forge.js
index e80566504..ae9f5ef1e 100644
--- a/api/gpt-forge.js
+++ b/api/gpt-forge.js
@@ -645,6 +645,7 @@ async function runNvidiaTextLane({ req, res, ip, prompt, aspect, tier, path, opt
glbUrl: submitted.resultGlbUrl,
quality: true,
compress: opts?.compression && opts.compression !== 'none' ? opts.compression : null,
+ derivePbr: opts?.derivePbr !== false,
});
// One auto-retry on a flagged low-quality/degenerate output (CLAUDE.md: no
@@ -682,6 +683,7 @@ async function runNvidiaTextLane({ req, res, ip, prompt, aspect, tier, path, opt
glbUrl: retry.resultGlbUrl,
quality: true,
compress: opts?.compression && opts.compression !== 'none' ? opts.compression : null,
+ derivePbr: opts?.derivePbr !== false,
});
if (retryDurable) {
durable = retryDurable;
@@ -721,6 +723,7 @@ async function runNvidiaTextLane({ req, res, ip, prompt, aspect, tier, path, opt
replicateJobId: rj, clientKey, userId: await sessionUserIdFromReq(req),
glbUrl: r.resultGlbUrl, quality: true,
compress: opts?.compression && opts.compression !== 'none' ? opts.compression : null,
+ derivePbr: opts?.derivePbr !== false,
});
return rd ? { glbUrl: rd.glbUrl, durable: rd } : null;
},
@@ -912,6 +915,7 @@ async function runHfImageLane({
glbUrl: resultGlbUrl,
quality: true,
compress: wantCompress,
+ derivePbr: opts?.derivePbr !== false,
});
// One auto-retry on a flagged low-quality/degenerate output. Only attempted
@@ -955,6 +959,7 @@ async function runHfImageLane({
glbUrl: retryFinished.resultGlbUrl,
quality: true,
compress: wantCompress,
+ derivePbr: opts?.derivePbr !== false,
});
if (retryDurable) {
durable = retryDurable;
@@ -1004,6 +1009,7 @@ async function runHfImageLane({
const rd = await materializeCreation({
replicateJobId: rj, clientKey, userId: await sessionUserIdFromReq(req),
glbUrl: rf.resultGlbUrl, quality: true, compress: wantCompress,
+ derivePbr: opts?.derivePbr !== false,
});
return rd ? { glbUrl: rd.glbUrl, durable: rd } : null;
} finally {
@@ -1676,6 +1682,7 @@ async function startJob(req, res) {
glbUrl: submitted.resultGlbUrl,
quality: true,
compress: opts.compression !== 'none' ? opts.compression : null,
+ derivePbr: opts.derivePbr !== false,
});
return json(res, 200, {
job_id: null,
@@ -2880,6 +2887,7 @@ async function pollJob(req, res, jobId) {
glbUrl: result.resultGlbUrl,
quality: true,
compress: boundOpts?.compression || null,
+ derivePbr: boundOpts?.derivePbr !== false,
});
// Populate the result cache this job was bound to at submit time (text→3D,
// non-high-tier, platform-keyed lanes only: see forgeResultCacheKey). A