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.

feat(forge): add Pixal3D fidelity lane, 1-4 photo multi-view fusion

nirholas5b4f31d059ac
diff --git a/api/_lib/forge-options.js b/api/_lib/forge-options.js
index f3e8e5ad0..5d9d48846 100644
--- a/api/_lib/forge-options.js
+++ b/api/_lib/forge-options.js
@@ -8,7 +8,12 @@
// • 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
-// • resolution : TRELLIS.2 voxel resolution (512, 1024 or 1536)
+// • resolution : TRELLIS.2 / Pixal3D voxel resolution (512, 1024 or 1536)
+// • view_labels : per-image front/back/left/right tag for a multi-image
+// request (Pixal3D's "Match my photo" lane). Null entries are allowed:
+// the worker infers the front view when every label is omitted.
+// • fill_other_sides : ask Pixal3D to synthesize the other three sides from a
+// single uploaded photo (MV-Adapter) instead of requiring 2-4 views.
// • 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
@@ -19,7 +24,7 @@
// message rather than silently doing something the caller didn't ask for. A value
// that is simply absent is never an error — it just keeps the current default.
-import { TRELLIS2_RESOLUTIONS } from './forge-tiers.js';
+import { TRELLIS2_RESOLUTIONS, PIXAL3D_VIEW_LABELS } from './forge-tiers.js';
// glb is the universal default. The two compressed variants run a post-generation
// pass (see glb-compress.js) that shrinks the delivered file without changing the
@@ -48,7 +53,9 @@ function compressionFor(format) {
* compression: 'none' | 'draco' | 'meshopt',
* textureSize: number | null,
* targetPolycount: number | null,
- * resolution: 512 | 1024 | 1536 | null, // TRELLIS.2 voxel resolution
+ * resolution: 512 | 1024 | 1536 | null, // TRELLIS.2 / Pixal3D voxel resolution
+ * viewLabels: Array<'front'|'back'|'left'|'right'|null> | null, // per-image tag
+ * fillOtherSides: boolean, // synthesize the other sides from one photo
* 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 }>,
@@ -131,6 +138,39 @@ export function normalizeForgeOptions(body) {
});
}
+ // view_labels: per-image front/back/left/right tag for Pixal3D's multi-image
+ // lane. Each entry must be one of PIXAL3D_VIEW_LABELS or null (the worker
+ // infers the front view); the array's length must match the image count,
+ // but imageUrls isn't visible here, so that cross-check happens at the
+ // forge.js boundary where both are in scope.
+ let viewLabels = null;
+ if (b.view_labels !== undefined && b.view_labels !== null) {
+ if (!Array.isArray(b.view_labels)) {
+ errors.push({ field: 'view_labels', message: 'view_labels must be an array.' });
+ } else {
+ const bad = b.view_labels.some((v) => v !== null && !PIXAL3D_VIEW_LABELS.includes(v));
+ if (bad) {
+ errors.push({
+ field: 'view_labels',
+ message: `Each view_labels entry must be null or one of: ${PIXAL3D_VIEW_LABELS.join(', ')}.`,
+ });
+ } else {
+ viewLabels = b.view_labels;
+ }
+ }
+ }
+
+ // fill_other_sides: opt-IN. Asks Pixal3D to synthesize the other three sides
+ // from a single uploaded photo instead of requiring 2-4 views.
+ let fillOtherSides = false;
+ if (b.fill_other_sides !== undefined && b.fill_other_sides !== null) {
+ if (typeof b.fill_other_sides !== 'boolean') {
+ errors.push({ field: 'fill_other_sides', message: 'fill_other_sides must be true or false.' });
+ } else {
+ fillOtherSides = b.fill_other_sides;
+ }
+ }
+
// 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.
@@ -144,7 +184,14 @@ export function normalizeForgeOptions(body) {
}
const hasOptions =
- seed !== null || outputFormat !== 'glb' || textureSize !== null || targetPolycount !== null || resolution !== null || !derivePbr;
+ seed !== null ||
+ outputFormat !== 'glb' ||
+ textureSize !== null ||
+ targetPolycount !== null ||
+ resolution !== null ||
+ viewLabels !== null ||
+ fillOtherSides ||
+ !derivePbr;
return {
seed,
@@ -153,6 +200,8 @@ export function normalizeForgeOptions(body) {
textureSize,
targetPolycount,
resolution,
+ viewLabels,
+ fillOtherSides,
derivePbr,
hasOptions,
errors,
@@ -186,6 +235,8 @@ export function summarizeForgeOptions(opts) {
texture_size: opts.textureSize,
target_polycount: opts.targetPolycount,
resolution: opts.resolution ?? null,
+ view_labels: opts.viewLabels ?? null,
+ fill_other_sides: Boolean(opts.fillOtherSides),
derive_pbr: opts.derivePbr !== false,
};
}
diff --git a/api/_lib/forge-tiers.js b/api/_lib/forge-tiers.js
index 3329f0816..795cfe7f3 100644
--- a/api/_lib/forge-tiers.js
+++ b/api/_lib/forge-tiers.js
@@ -340,6 +340,39 @@ export const BACKENDS = Object.freeze({
free: true,
blurb: 'Free fast image to 3D geometry on our own Modly worker running Hunyuan3D 2 Mini Turbo, decimated to your poly budget, no vendor cost. Untextured; retexture or stylize after.',
}),
+ pixal3d: Object.freeze({
+ id: 'pixal3d',
+ label: 'Pixal3D (self-host)',
+ vendor: 'TencentARC Pixal3D · self-host',
+ paths: Object.freeze(['image']),
+ byok: false,
+ provider: 'gcp',
+ // Our own Pixal3D worker (workers/model-pixal3d on Cloud Run, MIT, TRELLIS.2
+ // backbone). The only image lane that actually fuses every reference photo
+ // it is given (1 to 4, each with an optional front/back/left/right label)
+ // instead of reconstructing from the first view alone: pixel-aligned
+ // fidelity to the caller's own photos rather than a hallucinated match. A
+ // single photo can also ask the worker to synthesize the other three sides
+ // (MV-Adapter) before fusing. Opt-in only: never a named free default or a
+ // failover target for another lane, so a plain request never lands here by
+ // chance, the caller asks for "Match my photo" explicitly.
+ requiresEnv: Object.freeze(['MODEL_PIXAL3D_URL', 'GCP_RECONSTRUCTION_KEY']),
+ polyControl: false,
+ userImages: true,
+ // Discoverable lane capabilities the catalog and UI read directly, rather
+ // than hardcoding "pixal3d" checks outside this registry.
+ maxImages: 4,
+ multiView: true,
+ fillOtherSides: true,
+ baseEta: 100,
+ // Cold-start budget for our own scale-to-zero worker: it streams the
+ // heavier of its two pipelines (single-view or multi-view) plus MoGe on
+ // first use, on top of the TRELLIS.2-backbone compile warm-up.
+ coldStartSeconds: 110,
+ credits: null,
+ free: true,
+ blurb: '"Match my photo": 1 to 4 reference images fused pixel-aligned into one PBR mesh on our own Pixal3D worker, no vendor cost. Label views front/back/left/right, or let the worker fill in the other sides from a single photo.',
+ }),
triposg: Object.freeze({
id: 'triposg',
label: 'TripoSG',
@@ -763,6 +796,17 @@ export const SELFHOST_TRELLIS_QUALITY = Object.freeze({
// draft 512, standard and high 1024, max 1536.
export const TRELLIS2_RESOLUTIONS = Object.freeze([512, 1024, 1536]);
+// Pixal3D voxel resolutions a caller may request (workers/model-pixal3d
+// request_policy.py RESOLUTIONS). Omitted, the worker maps the tier to one:
+// draft and standard 1024, high and max 1536. No 512 option: Pixal3D's
+// pixel-aligned path is the fidelity lane, not the fast-draft one.
+export const PIXAL3D_RESOLUTIONS = Object.freeze([1024, 1536]);
+
+// The four view labels Pixal3D's camera rig understands (workers/model-pixal3d
+// camera_rig.py VIEW_AZIMUTH_DEGREES). A caller tags each uploaded image with
+// one of these, or leaves it null to let the worker infer the front view.
+export const PIXAL3D_VIEW_LABELS = Object.freeze(['front', 'back', 'left', 'right']);
+
export function selfhostQualityForTier(tierId) {
return SELFHOST_TRELLIS_QUALITY[tierId] || SELFHOST_TRELLIS_QUALITY[DEFAULT_TIER];
}
@@ -793,10 +837,15 @@ export function backendIsConfigured(backendId) {
}
// The self-host image lanes the forge handler drives through one async GCP
-// block (api/forge.js, api/gpt-forge.js): the two TRELLIS workers and the two
-// Modly lanes, which share one worker (workers/modly).
+// block (api/forge.js, api/gpt-forge.js): the two TRELLIS workers, Pixal3D,
+// and the two Modly lanes, which share one worker (workers/modly). Pixal3D is
+// never a FAILOVER TARGET for the others (see nextSelfHostImageLane below) and
+// never falls over to them either: a down Pixal3D leaves the multi-image
+// request with no lane that can fuse more than one view, so it falls through
+// to the standing single-view reconstruct chain instead of silently dropping
+// the caller's second and third photos on a lane that only reads the first.
export const MODLY_LANES = Object.freeze(['modly', 'modly_hunyuan']);
-const SELF_HOST_IMAGE_LANES = Object.freeze(['trellis2', 'trellis_selfhost', ...MODLY_LANES]);
+const SELF_HOST_IMAGE_LANES = Object.freeze(['trellis2', 'trellis_selfhost', 'pixal3d', ...MODLY_LANES]);
export function isSelfHostImageLane(backendId) {
return SELF_HOST_IMAGE_LANES.includes(backendId);
@@ -804,7 +853,9 @@ export function isSelfHostImageLane(backendId) {
// Human name for a self-host image lane in a designed "not configured" error.
export function selfHostLaneName(backendId) {
- return MODLY_LANES.includes(backendId) ? BACKENDS[backendId].label : 'Self-hosted TRELLIS';
+ if (MODLY_LANES.includes(backendId)) return BACKENDS[backendId].label;
+ if (backendId === 'pixal3d') return 'Pixal3D';
+ return 'Self-hosted TRELLIS';
}
// Where a self-host image lane retries when its worker is down, before the
@@ -900,7 +951,15 @@ export function buildCatalog() {
configured: backendIsConfigured(b.id),
blurb: b.blurb,
// Voxel resolutions the lane accepts as the `resolution` request option.
- resolutions: b.id === 'trellis2' ? TRELLIS2_RESOLUTIONS : undefined,
+ resolutions: b.id === 'trellis2' ? TRELLIS2_RESOLUTIONS : b.id === 'pixal3d' ? PIXAL3D_RESOLUTIONS : undefined,
+ // Multi-image capability: how many reference photos the lane will
+ // actually fuse (vs. read-the-first-view-only), the labels it
+ // understands per image, and whether it can synthesize the unseen
+ // sides from a single photo. Undefined/false for every other lane.
+ max_images: b.maxImages || 1,
+ multi_view: Boolean(b.multiView),
+ view_labels: b.multiView ? PIXAL3D_VIEW_LABELS : undefined,
+ fill_other_sides: Boolean(b.fillOtherSides),
estimates: b.paths.reduce((acc, p) => {
acc[p] = TIER_IDS.map((tierId) => ({
tier: tierId,
diff --git a/api/_providers/gcp.js b/api/_providers/gcp.js
index ede3ce713..b845ce1e7 100644
--- a/api/_providers/gcp.js
+++ b/api/_providers/gcp.js
@@ -13,6 +13,12 @@
// shape: POST /infer → { task_id } GET /tasks/:id → result_gcs_url.
//
// trellis2 → MODEL_TRELLIS2_URL (workers/model-trellis2)
+// pixal3d → MODEL_PIXAL3D_URL (workers/model-pixal3d)
+// "Match my photo": 1-4 reference views fused pixel-aligned
+// (unlike every other image lane above, it reads every view in
+// the array, not just the first). `view_labels` tags each view
+// front/back/left/right; `fill_other_sides` synthesizes the
+// other three sides from one photo via MV-Adapter.
// modly → MODEL_MODLY_URL (workers/modly, TripoSG)
// modly_hunyuan → MODEL_MODLY_URL (workers/modly, Hunyuan3D 2 Mini Turbo)
// One Modly worker serves both; the request's `model` field
@@ -106,6 +112,12 @@ function serviceUrlForMode(mode) {
// Self-hosted Microsoft TRELLIS.2 image→3D worker (workers/model-trellis2),
// the default image lane. Same /infer + /tasks/:id task shape.
return readEnv('MODEL_TRELLIS2_URL');
+ case 'pixal3d':
+ // Self-hosted TencentARC Pixal3D worker (workers/model-pixal3d): the
+ // "Match my photo" lane. Unlike every other image lane above, it fuses
+ // every one of its 1-4 reference views instead of reading the first.
+ // Same /infer + /tasks/:id task shape.
+ return readEnv('MODEL_PIXAL3D_URL');
case 'modly':
case 'modly_hunyuan':
// Self-hosted Modly worker (workers/modly): one service, two models.
@@ -216,6 +228,30 @@ function buildWorkerRequest(request) {
};
}
+ if (mode === 'pixal3d') {
+ // Self-hosted Pixal3D (workers/model-pixal3d): 1-4 reference views in, a
+ // pixel-aligned PBR GLB out. `view_labels` tags each view front/back/left/
+ // right (omitted entries, or the whole field omitted, let the worker infer
+ // the front view from its camera estimator); `fill_other_sides` asks the
+ // worker to synthesize the other three sides from a single supplied photo.
+ const photos = Array.isArray(params?.images) && params.images.length
+ ? params.images
+ : [sourceUrl].filter(Boolean);
+ const body = { images: photos, body_type: params?.bodyType || 'neutral' };
+ if (Array.isArray(params?.view_labels)) body.view_labels = params.view_labels;
+ if (params?.fill_other_sides === true) body.fill_other_sides = true;
+ if (Number.isFinite(Number(params?.resolution))) body.resolution = Math.round(Number(params.resolution));
+ if (params?.tier) body.tier = params.tier;
+ if (Number.isFinite(Number(params?.seed))) body.seed = Math.floor(Number(params.seed));
+ if (Number.isFinite(Number(params?.texture_size))) body.texture_size = Math.round(Number(params.texture_size));
+ if (Number.isFinite(Number(params?.decimation_target))) body.decimation_target = Math.round(Number(params.decimation_target));
+ return {
+ path: '/infer',
+ resultKey: 'result_gcs_url',
+ body,
+ };
+ }
+
if (mode === 'modly' || mode === 'modly_hunyuan') {
return buildModlyRequest(mode, sourceUrl, params);
}
@@ -497,6 +533,10 @@ const MODE_ETA = {
reconstruct: 120,
trellis: 60,
trellis2: 75,
+ // Pixel-aligned single-view path is close to TRELLIS.2's own cost; the
+ // multi-view fusion path (2-4 images) and the optional MV-Adapter
+ // "fill the other sides" rung both run meaningfully heavier.
+ pixal3d: 100,
// TripoSG's 20 to 50 flow steps plus repair and decimate on the L4.
modly: 60,
// Hunyuan3D 2 Mini Turbo is a few-step distilled sampler.
@@ -602,14 +642,14 @@ export function createRegenProvider({ reconstructUrl } = {}) {
);
}
- // Report how the job was conditioned. For reconstruct the worker fuses
- // every image in the body; the Hunyuan3D worker conditions on the
- // primary view only (report 1 so a multi-view request is never
+ // Report how the job was conditioned. For reconstruct and Pixal3D the
+ // worker fuses every image in the body; the Hunyuan3D worker conditions
+ // on the primary view only (report 1 so a multi-view request is never
// silently claimed as fused); other modes are single-source.
const viewsUsed =
mode === 'hunyuan' || mode === 'trellis2' || mode === 'modly' || mode === 'modly_hunyuan'
? 1
- : (mode === 'reconstruct' || mode === 'trellis') && Array.isArray(workerReq.body.images)
+ : (mode === 'reconstruct' || mode === 'trellis' || mode === 'pixal3d') && Array.isArray(workerReq.body.images)
? workerReq.body.images.length
: 0;
diff --git a/api/forge.js b/api/forge.js
index c009cc549..c7a0ca290 100644
--- a/api/forge.js
+++ b/api/forge.js
@@ -1421,6 +1421,29 @@ async function startJobWithBody(req, res, body) {
message: `Provide between 1 and ${MAX_VIEWS} reference images.`,
});
}
+ // Pixal3D's "Match my photo" lane fuses every view it is given, so its cap
+ // is tighter than the generic MAX_VIEWS turnaround ceiling (4, not 6), and
+ // its optional per-image labels must line up with the images they tag.
+ if (backendId === 'pixal3d') {
+ if (imageUrls.length > 4) {
+ return json(res, 400, {
+ error: 'invalid_image_urls',
+ message: 'Match my photo accepts 1 to 4 reference images.',
+ });
+ }
+ if (opts.viewLabels && opts.viewLabels.length !== imageUrls.length) {
+ return json(res, 400, {
+ error: 'invalid_view_labels',
+ message: `view_labels must have exactly one entry per image (sent ${imageUrls.length} image(s) and ${opts.viewLabels.length} label(s)).`,
+ });
+ }
+ if (opts.fillOtherSides && imageUrls.length !== 1) {
+ return json(res, 400, {
+ error: 'invalid_fill_other_sides',
+ message: 'fill_other_sides needs exactly one reference image; send one photo and let the worker synthesize the other sides.',
+ });
+ }
+ }
// Validate every view at the boundary before any of them reach the model.
for (const u of imageUrls) {
if (!HTTP_URL_RE.test(u) || u.length > 2048) {
@@ -2166,6 +2189,27 @@ async function startJobWithBody(req, res, body) {
texture_size: opts.textureSize ?? undefined,
decimation_target: opts.targetPolycount ?? undefined,
},
+ } : backendId === 'pixal3d' ? {
+ mode: 'pixal3d',
+ sourceUrl: referenceImageUrl,
+ params: {
+ // Unlike every other lane above, Pixal3D actually fuses every view
+ // in this array (up to 4) instead of reading the first one alone,
+ // the whole point of the "Match my photo" lane. view_labels tags
+ // each entry front/back/left/right; omitted, the worker infers the
+ // front view from the camera estimator. fill_other_sides asks it to
+ // synthesize the other three sides from a single photo instead.
+ images: views,
+ view_labels: opts.viewLabels ?? undefined,
+ fill_other_sides: opts.fillOtherSides || undefined,
+ seed: opts.seed ?? undefined,
+ // Voxel resolution: an explicit request value (1024 or 1536), else
+ // the worker maps the tier (draft/standard 1024, high/max 1536).
+ resolution: opts.resolution ?? undefined,
+ tier: tier.id,
+ texture_size: opts.textureSize ?? undefined,
+ decimation_target: opts.targetPolycount ?? undefined,
+ },
} : {
mode: 'trellis',
sourceUrl: referenceImageUrl,
diff --git a/tests/api/forge-pixal3d-request.test.js b/tests/api/forge-pixal3d-request.test.js
new file mode 100644
index 000000000..7edddc720
--- /dev/null
+++ b/tests/api/forge-pixal3d-request.test.js
@@ -0,0 +1,243 @@
+/**
+ * Request-boundary contract for Pixal3D's "Match my photo" lane on api/forge.js:
+ * the 1-4 image cap (tighter than the generic MAX_VIEWS=6), the view_labels
+ * length check, the fill_other_sides single-image check, and the happy path
+ * that must return a GLB job and record every input URL on the creation row.
+ *
+ * Modeled on tests/api/forge-multiview-photo.test.js (same mocking shape).
+ */
+
+import { describe, it, expect, vi, beforeAll, beforeEach } from 'vitest';
+
+beforeAll(() => {
+ Object.assign(process.env, {
+ APP_ORIGIN: 'https://three.ws',
+ MODEL_PIXAL3D_URL: 'https://pixal3d.example.run.app',
+ MODEL_TRELLIS2_URL: 'https://trellis2.example.run.app',
+ GCP_RECONSTRUCTION_KEY: 'test-gcp-key',
+ NVIDIA_API_KEY: 'nvapi-test',
+ JWT_SECRET: 'test-jwt-secret-at-least-32-characters-long',
+ });
+});
+
+const gcpSubmit = vi.fn(async ({ params }) => ({
+ extJobId: 'gcpjob-pixal3d-01',
+ viewsUsed: params.images.length,
+ multiview: params.images.length > 1,
+}));
+vi.mock('../../api/_providers/gcp.js', () => ({
+ createRegenProvider: () => ({ submit: gcpSubmit }),
+}));
+
+vi.mock('../../api/_mcp3d/text-to-image.js', () => ({
+ textToImage: vi.fn(async () => ({ imageUrl: 'https://cdn.example/ref.png', model: 'flux' })),
+ synthesizeTurnaroundViews: vi.fn(async () => []),
+}));
+
+const createCreation = vi.fn(async () => 'creation-pixal3d-1');
+vi.mock('../../api/_lib/forge-store.js', () => ({
+ hashClient: (v) => `client:${v || 'anon'}`,
+ hashIp: (v) => `ip:${v}`,
+ createCreation,
+ materializeCreation: vi.fn(async ({ glbUrl }) => ({ id: 'creation-pixal3d-1', glbUrl })),
+ markFailed: vi.fn(async () => {}),
+ findByJob: vi.fn(async () => null),
+ runWithCreationContext: (_facts, fn) => fn(),
+}));
+
+vi.mock('../../api/_lib/forge-lane-health.js', () => ({
+ laneHealthSnapshot: vi.fn(async () => ({ statusMap: {}, byId: {} })),
+ markLaneUnhealthy: vi.fn(async () => {}),
+ laneCooldownKey: (id) => `forge-lane:${id}`,
+}));
+
+vi.mock('../../api/_lib/forge-image-validate.js', () => ({
+ validateForgeImage: vi.fn(async () => ({ ok: true })),
+}));
+
+vi.mock('../../api/_lib/rate-limit.js', async (importActual) => {
+ const actual = await importActual();
+ return {
+ ...actual,
+ limits: {
+ ...actual.limits,
+ mcp3dGenerate: vi.fn(async () => ({ success: true, reset: Date.now() + 1000 })),
+ mcp3dGenerateFree: vi.fn(async () => ({ success: true, reset: Date.now() + 1000 })),
+ },
+ clientIp: () => '203.0.113.9',
+ };
+});
+
+const { default: handler } = await import('../../api/forge.js');
+
+function makeReq(body) {
+ return {
+ method: 'POST',
+ url: '/api/forge',
+ headers: { 'content-type': 'application/json', 'x-forge-client': 'tester' },
+ on(event, cb) {
+ if (event === 'data') cb(Buffer.from(JSON.stringify(body)));
+ if (event === 'end') cb();
+ },
+ };
+}
+
+function makeRes() {
+ return {
+ statusCode: 200,
+ headers: {},
+ body: null,
+ setHeader(name, value) {
+ this.headers[String(name).toLowerCase()] = value;
+ },
+ end(body) {
+ this.body = body ? JSON.parse(body) : null;
+ },
+ };
+}
+
+const PHOTOS = [
+ 'https://cdn.example/front.png',
+ 'https://cdn.example/back.png',
+ 'https://cdn.example/left.png',
+];
+
+beforeEach(() => {
+ gcpSubmit.mockClear();
+ createCreation.mockClear();
+});
+
+describe('Pixal3D request boundary: image count', () => {
+ it('rejects a 5-image request (lane cap is 4, tighter than the generic 6)', async () => {
+ const req = makeReq({
+ image_urls: [...PHOTOS, 'https://cdn.example/right.png', 'https://cdn.example/extra.png'],
+ tier: 'standard',
+ path: 'image',
+ backend: 'pixal3d',
+ skip_validation: true,
+ });
+ const res = makeRes();
+ await handler(req, res);
+ expect(res.statusCode).toBe(400);
+ expect(res.body.error).toBe('invalid_image_urls');
+ expect(gcpSubmit).not.toHaveBeenCalled();
+ });
+
+ it('a 5-image request on trellis2 (within the generic 6-image cap) is unaffected by the pixal3d-only check', async () => {
+ const req = makeReq({
+ image_urls: [...PHOTOS, 'https://cdn.example/right.png', 'https://cdn.example/extra.png'],
+ tier: 'standard',
+ path: 'image',
+ backend: 'trellis2',
+ skip_validation: true,
+ });
+ const res = makeRes();
+ await handler(req, res);
+ expect(res.statusCode).toBe(200);
+ expect(gcpSubmit).toHaveBeenCalledTimes(1);
+ expect(gcpSubmit.mock.calls[0][0].params.images).toHaveLength(5);
+ });
+});
+
+describe('Pixal3D request boundary: view_labels', () => {
+ it('rejects a view_labels array whose length does not match the image count', async () => {
+ const req = makeReq({
+ image_urls: PHOTOS,
+ view_labels: ['front', 'back'],
+ tier: 'standard',
+ path: 'image',
+ backend: 'pixal3d',
+ skip_validation: true,
+ });
+ const res = makeRes();
+ await handler(req, res);
+ expect(res.statusCode).toBe(400);
+ expect(res.body.error).toBe('invalid_view_labels');
+ expect(gcpSubmit).not.toHaveBeenCalled();
+ });
+});
+
+describe('Pixal3D request boundary: fill_other_sides', () => {
+ it('rejects fill_other_sides when more than one image is supplied', async () => {
+ const req = makeReq({
+ image_urls: PHOTOS,
+ fill_other_sides: true,
+ tier: 'standard',
+ path: 'image',
+ backend: 'pixal3d',
+ skip_validation: true,
+ });
+ const res = makeRes();
+ await handler(req, res);
+ expect(res.statusCode).toBe(400);
+ expect(res.body.error).toBe('invalid_fill_other_sides');
+ expect(gcpSubmit).not.toHaveBeenCalled();
+ });
+
+ it('accepts fill_other_sides with exactly one image', async () => {
+ const req = makeReq({
+ image_urls: [PHOTOS[0]],
+ fill_other_sides: true,
+ tier: 'standard',
+ path: 'image',
+ backend: 'pixal3d',
+ skip_validation: true,
+ });
+ const res = makeRes();
+ await handler(req, res);
+ expect(res.statusCode).toBe(200);
+ expect(gcpSubmit.mock.calls[0][0].params.fill_other_sides).toBe(true);
+ });
+});
+
+describe('Pixal3D happy path: multi-image request', () => {
+ it('a 3-image request queues a job and records every input URL on the creation row', async () => {
+ const req = makeReq({
+ image_urls: PHOTOS,
+ view_labels: ['front', 'back', 'left'],
+ tier: 'standard',
+ path: 'image',
+ backend: 'pixal3d',
+ skip_validation: true,
+ });
+ const res = makeRes();
+ await handler(req, res);
+
+ expect(res.statusCode).toBe(200);
+ expect(res.body.backend).toBe('pixal3d');
+ expect(res.body.status).toBe('queued');
+
+ expect(gcpSubmit).toHaveBeenCalledTimes(1);
+ const submitted = gcpSubmit.mock.calls[0][0];
+ expect(submitted.mode).toBe('pixal3d');
+ expect(submitted.params.images).toEqual(PHOTOS);
+ expect(submitted.params.view_labels).toEqual(['front', 'back', 'left']);
+
+ expect(createCreation).toHaveBeenCalledTimes(1);
+ const creation = createCreation.mock.calls[0][0];
+ expect(creation.sourceImageUrls).toEqual(PHOTOS);
+ expect(creation.viewsRequested).toBe(3);
+ expect(creation.viewsUsed).toBe(3);
+ expect(creation.multiview).toBe(true);
+ expect(creation.backend).toBe('pixal3d');
+ });
+
+ it('a single-image pixal3d request stays a single-view job (byte-for-byte path, no synthesis noise)', async () => {
+ const req = makeReq({
+ image_urls: [PHOTOS[0]],
+ tier: 'standard',
+ path: 'image',
+ backend: 'pixal3d',
+ skip_validation: true,
+ });
+ const res = makeRes();
+ await handler(req, res);
+
+ expect(res.statusCode).toBe(200);
+ expect(gcpSubmit.mock.calls[0][0].params.images).toEqual([PHOTOS[0]]);
+ const creation = createCreation.mock.calls[0][0];
+ expect(creation.viewsRequested).toBe(1);
+ expect(creation.viewsUsed).toBe(1);
+ expect(creation.multiview).toBe(false);
+ });
+});
diff --git a/tests/api/forge-pixal3d.test.js b/tests/api/forge-pixal3d.test.js
new file mode 100644
index 000000000..d264f5072
--- /dev/null
+++ b/tests/api/forge-pixal3d.test.js
@@ -0,0 +1,215 @@
+// Pixal3D "Match my photo" lane: registration, env-gated config, opt-in
+// routing (never a default or a failover target), the forge.js request
+// boundary (1-4 images, view_labels, fill_other_sides), and the gcp
+// provider's `pixal3d` mode wire contract.
+//
+// Unlike every other self-host image lane (trellis2, trellis_selfhost, the
+// Modly pair), Pixal3D actually fuses every reference view it is given
+// instead of reading the first one alone, that is the whole point of this
+// lane, and the one behavior these tests exist to pin down.
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import {
+ BACKENDS,
+ resolveBackendId,
+ backendIsConfigured,
+ buildCatalog,
+ isSelfHostImageLane,
+ nextSelfHostImageLane,
+ selfHostLaneName,
+ FREE_DEFAULT_FOR_TIERS,
+ FREE_FALLBACK_FOR_PATH,
+ PIXAL3D_RESOLUTIONS,
+ PIXAL3D_VIEW_LABELS,
+} from '../../api/_lib/forge-tiers.js';
+import { normalizeForgeOptions } from '../../api/_lib/forge-options.js';
+import { createRegenProvider } from '../../api/_providers/gcp.js';
+
+const VARS = ['MODEL_PIXAL3D_URL', 'MODEL_TRELLIS2_URL', 'MODEL_TRELLIS_URL', 'GCP_RECONSTRUCTION_KEY'];
+const saved = {};
+const ORIGINAL_FETCH = globalThis.fetch;
+
+beforeEach(() => {
+ for (const v of VARS) {
+ saved[v] = process.env[v];
+ delete process.env[v];
+ }
+});
+afterEach(() => {
+ for (const v of VARS) {
+ if (saved[v] === undefined) delete process.env[v];
+ else process.env[v] = saved[v];
+ }
+ globalThis.fetch = ORIGINAL_FETCH;
+ vi.restoreAllMocks();
+});
+
+describe('forge-tiers: Pixal3D backend registration', () => {
+ it('registers a free, platform-keyed, multi-image backend that accepts user photos', () => {
+ const b = BACKENDS.pixal3d;
+ expect(b).toBeTruthy();
+ expect(b.provider).toBe('gcp');
+ expect(b.byok).toBe(false);
+ expect(b.paths).toEqual(['image']);
+ expect(b.requiresEnv).toEqual(['MODEL_PIXAL3D_URL', 'GCP_RECONSTRUCTION_KEY']);
+ expect(b.free).toBe(true);
+ expect(b.userImages).toBe(true);
+ expect(b.maxImages).toBe(4);
+ expect(b.multiView).toBe(true);
+ expect(b.fillOtherSides).toBe(true);
+ expect(b.credits).toBeNull();
+ });
+
+ it('is configured only when BOTH the worker URL and the shared key are present', () => {
+ expect(backendIsConfigured('pixal3d')).toBe(false);
+ process.env.MODEL_PIXAL3D_URL = 'https://pixal3d.example.run.app';
+ expect(backendIsConfigured('pixal3d')).toBe(false); // key still missing
+ process.env.GCP_RECONSTRUCTION_KEY = 'secret';
+ expect(backendIsConfigured('pixal3d')).toBe(true);
+ });
+
+ it('surfaces in the catalog with its resolutions, max image count and view labels', () => {
+ process.env.MODEL_PIXAL3D_URL = 'https://pixal3d.example.run.app';
+ process.env.GCP_RECONSTRUCTION_KEY = 'secret';
+ const b = buildCatalog().backends.find((x) => x.id === 'pixal3d');
+ expect(b).toBeTruthy();
+ expect(b.free).toBe(true);
+ expect(b.user_images).toBe(true);
+ expect(b.configured).toBe(true);
+ expect(b.resolutions).toEqual(PIXAL3D_RESOLUTIONS);
+ expect(b.max_images).toBe(4);
+ expect(b.multi_view).toBe(true);
+ expect(b.view_labels).toEqual(PIXAL3D_VIEW_LABELS);
+ expect(b.fill_other_sides).toBe(true);
+ });
+
+ it('is a self-host image lane, but never a named default or a failover target', () => {
+ process.env.MODEL_PIXAL3D_URL = 'https://pixal3d.example.run.app';
+ process.env.MODEL_TRELLIS2_URL = 'https://trellis2.example.run.app';
+ process.env.GCP_RECONSTRUCTION_KEY = 'secret';
+ expect(isSelfHostImageLane('pixal3d')).toBe(true);
+ // Not named anywhere in the free-default or free-fallback tables.
+ expect(Object.values(FREE_DEFAULT_FOR_TIERS).some((v) => v.image === 'pixal3d')).toBe(false);
+ expect(FREE_FALLBACK_FOR_PATH.image).not.toContain('pixal3d');
+ // A plain (no explicit backend) photo request never lands here.
+ expect(resolveBackendId({ path: 'image', tier: 'standard', userImages: true, country: 'US' })).not.toBe('pixal3d');
+ // Nothing fails over TO pixal3d, and pixal3d fails over to nothing (a
+ // down Pixal3D must never silently drop the caller's 2nd/3rd photo on a
+ // lane that only reads the first view).
+ expect(nextSelfHostImageLane('trellis2')).not.toBe('pixal3d');
+ expect(nextSelfHostImageLane('pixal3d')).toBeNull();
+ expect(selfHostLaneName('pixal3d')).toBe('Pixal3D');
+ });
+
+ it('stays explicitly selectable even when unconfigured (the handler owns rejection)', () => {
+ expect(
+ resolveBackendId({ path: 'image', tier: 'standard', backend: 'pixal3d', userImages: true, country: 'US' }),
+ ).toBe('pixal3d');
+ });
+});
+
+describe('forge-options: Pixal3D view_labels / fill_other_sides', () => {
+ it('accepts the documented resolutions', () => {
+ for (const r of PIXAL3D_RESOLUTIONS) {
+ expect(normalizeForgeOptions({ resolution: r }).errors).toEqual([]);
+ }
+ });
+
+ it('round-trips a per-image view_labels array', () => {
+ const o = normalizeForgeOptions({ view_labels: ['front', 'right', 'back'] });
+ expect(o.viewLabels).toEqual(['front', 'right', 'back']);
+ });
+});
+
+describe('gcp provider: pixal3d mode wire contract', () => {
+ it('forwards every reference image, not just the first, plus view_labels', async () => {
+ process.env.MODEL_PIXAL3D_URL = 'https://pixal3d.example.run.app';
+ process.env.GCP_RECONSTRUCTION_KEY = 'secret';
+ let sent = null;
+ globalThis.fetch = vi.fn(async (url, opts) => {
+ expect(url).toBe('https://pixal3d.example.run.app/infer');
+ sent = JSON.parse(opts.body);
+ expect(opts.headers.authorization).toBe('Bearer secret');
+ return new Response(JSON.stringify({ task_id: 'task-p3d', status: 'queued' }), {
+ status: 202,
+ headers: { 'content-type': 'application/json' },
+ });
+ });
+
+ const provider = createRegenProvider();
+ const images = [
+ 'https://three.ws/cdn/front.png',
+ 'https://three.ws/cdn/back.png',
+ 'https://three.ws/cdn/left.png',
+ ];
+ const submitted = await provider.submit({
+ mode: 'pixal3d',
+ sourceUrl: images[0],
+ params: {
+ images,
+ view_labels: ['front', 'back', 'left'],
+ resolution: 1536,
+ tier: 'high',
+ seed: 42,
+ },
+ });
+
+ expect(sent.images).toEqual(images);
+ expect(sent.view_labels).toEqual(['front', 'back', 'left']);
+ expect(sent.resolution).toBe(1536);
+ expect(sent.tier).toBe('high');
+ expect(sent.seed).toBe(42);
+ // Unlike trellis2/hunyuan/modly (which hardcode viewsUsed:1), Pixal3D
+ // genuinely fuses every view, the DoD line this test pins down.
+ expect(submitted.viewsUsed).toBe(3);
+ expect(submitted.multiview).toBe(true);
+ });
+
+ it('forwards fill_other_sides only when the caller opts in', async () => {
+ process.env.MODEL_PIXAL3D_URL = 'https://pixal3d.example.run.app';
+ process.env.GCP_RECONSTRUCTION_KEY = 'secret';
+ const bodies = [];
+ globalThis.fetch = vi.fn(async (_url, opts) => {
+ bodies.push(JSON.parse(opts.body));
+ return new Response(JSON.stringify({ task_id: 'task-fos', status: 'queued' }), {
+ status: 202,
+ headers: { 'content-type': 'application/json' },
+ });
+ });
+ const provider = createRegenProvider();
+ await provider.submit({
+ mode: 'pixal3d',
+ sourceUrl: 'https://three.ws/cdn/photo.png',
+ params: { images: ['https://three.ws/cdn/photo.png'], fill_other_sides: true },
+ });
+ await provider.submit({
+ mode: 'pixal3d',
+ sourceUrl: 'https://three.ws/cdn/photo.png',
+ params: { images: ['https://three.ws/cdn/photo.png'] },
+ });
+ expect(bodies[0].fill_other_sides).toBe(true);
+ expect(bodies[1]).not.toHaveProperty('fill_other_sides');
+ });
+
+ it('single-image request stays the same minimal shape as trellis2 (no view_labels/fill_other_sides noise)', async () => {
+ process.env.MODEL_PIXAL3D_URL = 'https://pixal3d.example.run.app';
+ process.env.GCP_RECONSTRUCTION_KEY = 'secret';
+ let sent = null;
+ globalThis.fetch = vi.fn(async (_url, opts) => {
+ sent = JSON.parse(opts.body);
+ return new Response(JSON.stringify({ task_id: 'task-single', status: 'queued' }), {
+ status: 202,
+ headers: { 'content-type': 'application/json' },
+ });
+ });
+ const provider = createRegenProvider();
+ const submitted = await provider.submit({
+ mode: 'pixal3d',
+ sourceUrl: 'https://three.ws/cdn/photo.png',
+ params: { images: ['https://three.ws/cdn/photo.png'] },
+ });
+ expect(sent).toEqual({ images: ['https://three.ws/cdn/photo.png'], body_type: 'neutral' });
+ expect(submitted.viewsUsed).toBe(1);
+ expect(submitted.multiview).toBe(false);
+ });
+});
diff --git a/tests/forge-options.test.js b/tests/forge-options.test.js
index ff6aa9b0d..d1f5c6852 100644
--- a/tests/forge-options.test.js
+++ b/tests/forge-options.test.js
@@ -106,6 +106,36 @@ describe('normalizeForgeOptions — texture size & polycount', () => {
});
});
+describe('normalizeForgeOptions: view_labels & fill_other_sides', () => {
+ it('accepts a valid view_labels array, including null entries', () => {
+ const o = normalizeForgeOptions({ view_labels: ['front', null, 'left'] });
+ expect(o.viewLabels).toEqual(['front', null, 'left']);
+ expect(o.errors).toEqual([]);
+ expect(o.hasOptions).toBe(true);
+ });
+
+ it('rejects a non-array view_labels', () => {
+ expect(normalizeForgeOptions({ view_labels: 'front' }).errors[0].field).toBe('view_labels');
+ });
+
+ it('rejects an unknown label inside view_labels', () => {
+ expect(normalizeForgeOptions({ view_labels: ['front', 'sideways'] }).errors[0].field).toBe('view_labels');
+ });
+
+ it('defaults view_labels to null when omitted', () => {
+ expect(normalizeForgeOptions({}).viewLabels).toBeNull();
+ });
+
+ it('accepts fill_other_sides as a boolean and defaults to false', () => {
+ expect(normalizeForgeOptions({ fill_other_sides: true }).fillOtherSides).toBe(true);
+ expect(normalizeForgeOptions({}).fillOtherSides).toBe(false);
+ });
+
+ it('rejects a non-boolean fill_other_sides', () => {
+ expect(normalizeForgeOptions({ fill_other_sides: 'yes' }).errors[0].field).toBe('fill_other_sides');
+ });
+});
+
describe('summarizeForgeOptions', () => {
it('echoes the resolved options for the response', () => {
const o = normalizeForgeOptions({ seed: 9, output_format: 'glb-draco', texture_size: 1024 });
@@ -115,9 +145,18 @@ describe('summarizeForgeOptions', () => {
texture_size: 1024,
target_polycount: null,
resolution: null,
+ view_labels: null,
+ fill_other_sides: false,
// Material completion is on unless the caller opts out, and the echo
// says so, so a client can tell why its delivered file carries maps.
derive_pbr: true,
});
});
+
+ it('echoes view_labels and fill_other_sides when supplied', () => {
+ const o = normalizeForgeOptions({ view_labels: ['front', 'back'], fill_other_sides: true });
+ const s = summarizeForgeOptions(o);
+ expect(s.view_labels).toEqual(['front', 'back']);
+ expect(s.fill_other_sides).toBe(true);
+ });
});
diff --git a/workers/model-pixal3d/Dockerfile b/workers/model-pixal3d/Dockerfile
new file mode 100644
index 000000000..002656288
--- /dev/null
+++ b/workers/model-pixal3d/Dockerfile
@@ -0,0 +1,135 @@
+# Pixal3D (TencentARC, MIT): 1 to 4 photos to a PBR-textured 3D asset on an L4 (24 GB).
+#
+# Built on TRELLIS.2's own backbone, so this image follows workers/model-trellis2's
+# Dockerfile closely (same CUDA/torch matrix, same attention backend, same gltfpack
+# pin) and adds only what Pixal3D's own setup needs on top:
+# * MoGe-2 (microsoft/moge, MIT), the monocular camera estimator Pixal3D's single-
+# view path uses to recover a camera from one photo (inference.py's
+# get_camera_params_wild_moge). Installed from git, not pip, as upstream does.
+# * natten (SHI-Labs, MIT), compiled from source like the v1 CuMesh/FlexGEMM
+# extensions: it has no prebuilt wheel for this torch/CUDA combination.
+# * diffusers/accelerate pinned to the versions Pixal3D's own requirements.txt
+# names, one step ahead of trellis2's because Pixal3D also drives the optional
+# MV-Adapter (huanngzh/MV-Adapter, Apache-2.0) SDXL rung for "fill in the other
+# sides" (mv_adapter_fill.py).
+# * utils3d is the same EasternJournalist pin trellis2 already carries.
+FROM python:3.11-slim AS gltfpack
+ARG GLTFPACK_VERSION=v1.2
+ARG GLTFPACK_SHA256=ebc236f5f6c08c7e5c5750476a187d24805d44d8c680449c4b7369c333f817b1
+RUN apt-get update && apt-get install -y --no-install-recommends curl unzip ca-certificates \
+ && curl -fsSL -o /tmp/gltfpack.zip \
+ https://github.com/zeux/meshoptimizer/releases/download/${GLTFPACK_VERSION}/gltfpack-ubuntu.zip \
+ && echo "${GLTFPACK_SHA256} /tmp/gltfpack.zip" | sha256sum -c - \
+ && unzip -j /tmp/gltfpack.zip gltfpack -d /usr/local/bin \
+ && chmod +x /usr/local/bin/gltfpack \
+ && /usr/local/bin/gltfpack -v
+
+FROM nvidia/cuda:12.4.1-cudnn-devel-ubuntu22.04
+
+ARG TORCH_CUDA_ARCH_LIST="8.9"
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+ PYTHONUNBUFFERED=1 \
+ PIP_NO_CACHE_DIR=1 \
+ DEBIAN_FRONTEND=noninteractive \
+ TORCH_CUDA_ARCH_LIST="${TORCH_CUDA_ARCH_LIST}" \
+ CUDA_HOME=/usr/local/cuda \
+ ATTN_BACKEND=xformers \
+ PIXAL3D_SRC=/opt/pixal3d-src \
+ MVADAPTER_SRC=/opt/mvadapter-src \
+ PYTHONPATH=/opt/pixal3d-src:/opt/pixal3d-src/o-voxel:/opt/mvadapter-src \
+ PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True \
+ # The weights are staged to the bucket, never fetched from the Hub at serve time.
+ HF_HUB_OFFLINE=1 \
+ TRANSFORMERS_OFFLINE=1 \
+ # Cap glibc at two malloc arenas; see workers/model-trellis2's identical comment.
+ MALLOC_ARENA_MAX=2
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+ python3.10 python3.10-dev python3-pip \
+ git curl wget build-essential ninja-build \
+ libgl1 libglib2.0-0 libgomp1 libjpeg-dev \
+ libusb-1.0-0 libegl1 \
+ && rm -rf /var/lib/apt/lists/* \
+ && ln -sf /usr/bin/python3.10 /usr/bin/python3 \
+ && ln -sf /usr/bin/python3.10 /usr/bin/python \
+ && pip install --upgrade pip setuptools wheel
+
+COPY --from=gltfpack /usr/local/bin/gltfpack /usr/local/bin/gltfpack
+
+# 1. Torch first (own layer; every extension below links against it).
+RUN pip install torch==2.6.0 torchvision==0.21.0 --index-url https://download.pytorch.org/whl/cu124
+
+# 2. Shared TRELLIS.2-backbone dependencies, same pins as workers/model-trellis2.
+RUN pip install \
+ imageio imageio-ffmpeg tqdm easydict opencv-python-headless ninja trimesh \
+ "transformers==4.57.1" pandas lpips zstandard kornia timm einops \
+ pillow plyfile scipy "open3d==0.19.0" \
+ && pip install git+https://github.com/EasternJournalist/utils3d.git@9a4eb15e4021b67b12c460c7057d642626897ec8
+
+# 3. xformers matched to torch 2.6.0.
+RUN pip install xformers==0.0.29.post2 --index-url https://download.pytorch.org/whl/cu124
+
+# 4. Compiled CUDA extensions. --no-build-isolation is REQUIRED on every one of
+# these: each setup.py imports torch at build time and PEP517 isolation hides the
+# torch from step 1. TRELLIS.2 is pinned to the same commit workers/model-trellis2
+# carries, for the o-voxel postprocess module Pixal3D's own to_glb call reuses.
+RUN git clone --recursive https://github.com/microsoft/TRELLIS.2.git /tmp/ext/TRELLIS.2 \
+ && git -C /tmp/ext/TRELLIS.2 checkout 75fbf0183001ed9876c8dbb35de6b68552ee08bd \
+ && git -C /tmp/ext/TRELLIS.2 submodule update --init --recursive
+RUN git clone -b v0.4.0 --depth 1 https://github.com/NVlabs/nvdiffrast.git /tmp/ext/nvdiffrast \
+ && pip install --no-build-isolation /tmp/ext/nvdiffrast
+RUN git clone --recursive https://github.com/JeffreyXiang/CuMesh.git /tmp/ext/CuMesh \
+ && pip install --no-build-isolation /tmp/ext/CuMesh
+RUN git clone --recursive https://github.com/JeffreyXiang/FlexGEMM.git /tmp/ext/FlexGEMM \
+ && pip install --no-build-isolation /tmp/ext/FlexGEMM
+RUN pip install --no-build-isolation /tmp/ext/TRELLIS.2/o-voxel
+# natten has no prebuilt wheel for CUDA 12.4 + torch 2.6; Pixal3D's attention
+# blocks need it for neighborhood attention.
+RUN pip install natten==0.21.0 --no-build-isolation
+RUN rm -rf /tmp/ext
+
+# 5. MoGe-2 (microsoft/moge, MIT): the single-view camera estimator.
+RUN pip install git+https://github.com/microsoft/MoGe.git@74fbce054ebed49800de42d0ad0e83495065719a
+
+# 6. Pixal3D itself, pinned to a commit for the same reproducibility reason
+# TRELLIS.2 is pinned above: its own reference scripts (inference.py,
+# inference_mv.py) and pipelines package are imported directly by main.py.
+RUN git clone https://github.com/TencentARC/Pixal3D.git /opt/pixal3d-src \
+ && git -C /opt/pixal3d-src checkout f7cf38429b0bd264f1995f0f8743a88b1c728b94
+
+# 7. MV-Adapter (huanngzh/MV-Adapter, Apache-2.0): the optional "fill in the
+# other sides" rung. diffusers/accelerate match its own requirements.txt.
+RUN pip install "diffusers==0.37.1" "accelerate==1.13.0"
+RUN git clone https://github.com/huanngzh/MV-Adapter.git /opt/mvadapter-src \
+ && git -C /opt/mvadapter-src checkout 4277e0018232bac82bb2c103caf0893cedb711be \
+ && pip install --no-deps -r /opt/mvadapter-src/requirements.txt || true
+
+# 8. Server deps. pytest is here for the build-time gate at the bottom of this
+# file: the pure-logic modules are unit tested during `docker build`, so a broken
+# one can never reach a revision.
+RUN pip install \
+ "fastapi==0.115.0" "uvicorn[standard]==0.32.0" "pydantic>=2.0.0" \
+ "httpx>=0.27.0" "google-cloud-storage==2.18.0" "safetensors>=0.4.0" \
+ "pytest>=8.0.0"
+
+WORKDIR /app
+COPY worker_security.py request_policy.py storage_backend.py instance_health.py \
+ pipeline_config.py glb_pack.py camera_rig.py mv_adapter_fill.py main.py /app/
+COPY test_request_policy.py test_storage_backend.py test_instance_health.py \
+ test_pipeline_config.py test_glb_pack.py test_camera_rig.py test_app_contract.py /app/
+
+# Build-time gate, neither half of which needs a GPU: the pure-logic tests, then
+# the served contract against the exact dependency set that will run.
+RUN python3 -m pytest /app/test_request_policy.py /app/test_storage_backend.py \
+ /app/test_instance_health.py /app/test_pipeline_config.py /app/test_glb_pack.py \
+ /app/test_camera_rig.py -q \
+ && python3 /app/test_app_contract.py
+
+EXPOSE 8080
+
+CMD ["uvicorn", "main:app", \
+ "--host", "0.0.0.0", \
+ "--port", "8080", \
+ "--workers", "1", \
+ "--timeout-keep-alive", "300"]
diff --git a/workers/model-pixal3d/README.md b/workers/model-pixal3d/README.md
new file mode 100644
index 000000000..a66cba240
--- /dev/null
+++ b/workers/model-pixal3d/README.md
@@ -0,0 +1,235 @@
+# model-pixal3d: 1 to 4 photos to PBR 3D asset, pixel-aligned (Pixal3D)
+
+FastAPI inference service that turns **one to four photos of the same subject
+into a PBR-textured GLB** with [TencentARC
+Pixal3D](https://github.com/TencentARC/Pixal3D) (pixel-aligned image-to-3D,
+MIT license, built on [Microsoft
+TRELLIS.2](https://github.com/microsoft/TRELLIS.2)'s backbone). It is the
+Forge's fidelity lane, labeled **"Match my photo"**: where `model-trellis2`
+and `model-hunyuan3d` generate a plausible asset from one view,
+`model-pixal3d` pixel-aligns the result to every photo it is given, and more
+photos narrow the result further.
+
+What a caller gets back:
+
+- A glTF binary with base colour, metallic-roughness and normal maps, same
+ bake pipeline as `model-trellis2`: `o_voxel` postprocess, alpha-aware
+ `BLEND`/`OPAQUE` material choice, meshopt compression through the pinned
+ `gltfpack` binary.
+- Two resolutions: `1024` (default, draft/standard tiers) and `1536`
+ (maximum detail, cascaded, high/max tiers).
+- **1 to 4 input images.** One photo runs the single-view path (Pixal3D's own
+ MoGe-2 camera estimation recovers the shot's camera from the photo itself).
+ Two to four photos run the multi-view path: an optional `view_labels` entry
+ per image (`"front"`, `"back"`, `"left"`, `"right"`) places it at that
+ azimuth around one shared, MoGe-2-estimated camera; an unlabeled slot
+ spreads evenly among the azimuths no label claimed. Exactly one photo with
+ `fill_other_sides: true` first synthesizes the other three azimuths with
+ MV-Adapter (`mv_adapter_fill.py`), then runs the same multi-view path on all
+ four, trading a slower request for a result informed by more than one real
+ view.
+
+Work is asynchronous: `POST /infer` returns `202` with a `task_id`, and the
+caller polls `GET /tasks/{id}` until `status` is `done`. With `GCS_BUCKET` set
+the GLB lands at
+`gs://$GCS_BUCKET/raw-meshes/pixal3d/{task_id}.glb` and is returned as a
+`storage.googleapis.com` URL. Without it the container writes tasks and
+results under `OUTPUT_DIR` and serves the mesh from `GET /results/{id}.glb`.
+
+## Endpoints
+
+`POST /infer`, `GET /tasks/{id}` and `GET /results/{id}.glb` require
+`Authorization: Bearer $API_KEY`. `GET /health` and `GET /` are
+unauthenticated: they carry no secrets, and the platform reads them to decide
+whether the lane can take work.
+
+### `POST /infer`
+
+```json
+{
+ "images": [
+ "https://example.com/front.png",
+ "https://example.com/back.png"
+ ],
+ "view_labels": ["front", "back"],
+ "fill_other_sides": false,
+ "resolution": 1536,
+ "tier": "high",
+ "seed": 42,
+ "texture_size": 4096,
+ "decimation_target": 1000000,
+ "job_id": "optional-caller-id"
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `images` | 1 to 4 `https://` URLs or `data:` URIs, same subject, any order. URLs are SSRF-checked (no private or link-local hosts). |
+| `view_labels` | Optional, one entry per image: `"front"`, `"back"`, `"left"`, `"right"`, or `null`. Omitted or shorter than `images` means every slot spreads evenly. A length mismatch is a `400`. |
+| `fill_other_sides` | Only valid with exactly one image (otherwise `400`): synthesize the other three azimuths with MV-Adapter before reconstructing. |
+| `resolution` | `1024` or `1536`. Anything else is a `422`. Wins over `tier`. |
+| `tier` | `draft`/`standard` (1024), `high`/`max` (1536). Used only when `resolution` is absent. |
+| `seed` | Reproducible sampling. |
+| `texture_size`, `decimation_target` | Bake overrides, clamped to 512-4096 (power of two) and 50k-2M faces. |
+
+### `GET /tasks/{id}`
+
+```json
+{
+ "task_id": "…",
+ "status": "done",
+ "result_gcs_url": "https://storage.googleapis.com/…/raw-meshes/pixal3d/….glb",
+ "resolution": 1536,
+ "resolution_served": 1536,
+ "views_used": 2,
+ "alpha_mode": "OPAQUE",
+ "packed": true
+}
+```
+
+A request the GPU cannot hold is retried one size down (1536 to 1024) and
+`resolution_served` reports the step so the platform never reports a
+stepped-down result as the requested one. `status` is one of `queued`,
+`running`, `done`, `failed`.
+
+## Run it and call it
+
+```bash
+# Build and run on a machine with an NVIDIA GPU (24 GB or more).
+docker build -t model-pixal3d workers/model-pixal3d
+docker run --gpus all -p 8080:8080 \
+ -e API_KEY=dev-secret -e OUTPUT_DIR=/data \
+ -e WEIGHTS_GCS_URI=gs://three-ws-model-weights/pixal3d \
+ -v "$PWD/data:/data" model-pixal3d
+
+# Submit and poll a 2-photo request.
+TASK=$(curl -s -X POST localhost:8080/infer \
+ -H "Authorization: Bearer dev-secret" -H "content-type: application/json" \
+ -d '{"images":["https://example.com/front.png","https://example.com/back.png"],
+ "view_labels":["front","back"],"resolution":1536}' | jq -r .task_id)
+curl -s localhost:8080/tasks/$TASK -H "Authorization: Bearer dev-secret"
+```
+
+Through the platform the same lane is reached with `POST /api/forge` using
+`{"path":"image","backend":"pixal3d","images":[...],"view_labels":[...]}`, or
+from the Forge UI's "Match my photo" drop zone (1 to 4 images, optional view
+labels per slot). The catalog (`GET /api/forge?catalog`) lists the accepted
+`resolutions` on the `pixal3d` backend.
+
+## Environment
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `API_KEY` | none | Shared bearer secret (Secret Manager `avatar-reconstruction-key` on Cloud Run). |
+| `GCS_BUCKET` | unset | Output bucket. Unset uses `OUTPUT_DIR`. |
+| `OUTPUT_DIR` | `/output` | Task and result volume for standalone use. |
+| `WEIGHTS_DIR` | `/weights/pixal3d` | Local weight tree (gcsfuse mount on Cloud Run). |
+| `WEIGHTS_GCS_URI` | unset | `gs://` tree. Each sub-model streams to local disk, loads, then is deleted, so peak disk is one checkpoint. The full set (about 46 GiB across both pipelines) does not fit Cloud Run's in-memory filesystem otherwise. |
+| `WEIGHTS_LOCAL_DIR` | `/tmp/pixal3d-weights` | Scratch for that streaming. |
+| `MVADAPTER_WEIGHTS_DIR` | `/weights/mvadapter` | Local staged copy of the SDXL base, VAE and adapter weights `fill_other_sides` needs. Falls back to the Hub id per model when a sub-directory is missing, which fails under `HF_HUB_OFFLINE=1` until staged (see `stage_weights.sh`). |
+| `PIXAL3D_SRC` | `/opt/pixal3d-src` | Vendored Pixal3D checkout; `main.py` imports its `inference.py`/`inference_mv.py` reference scripts directly rather than reimplementing them. |
+| `MVADAPTER_SRC` | `/opt/mvadapter-src` | Vendored MV-Adapter checkout, same reasoning. |
+| `LOW_VRAM` | `1` | Moves each stage's weights to the GPU only while it runs. A single L4 cannot hold the single-view pipeline, the multi-view pipeline and MV-Adapter resident at once; see "Known limits" below. |
+| `MAX_RESOLUTION` | `1536` | Ceiling on the served resolution. |
+| `MAX_CONCURRENT` | `1` | Parallel inferences per instance. One GPU, so instance count is the concurrent-generation count. |
+| `IMAGE_FETCH_TIMEOUT_S` | `30` | Per-attempt image fetch timeout. |
+| `MODEL_LOAD_ATTEMPTS` | `4` | Weight-staging attempts before the error latches and `/health` returns 503. |
+| `MODEL_LOAD_RETRY_BASE_S`, `MODEL_LOAD_RETRY_CAP_S` | see `main.py` | Load-retry backoff bounds. |
+
+The platform side reads `MODEL_PIXAL3D_URL` (this service's URL) and
+`GCP_RECONSTRUCTION_KEY` (the bearer secret) from the `three-ws-api`
+environment. Until `MODEL_PIXAL3D_URL` is set the lane reports unconfigured
+and Forge's "Match my photo" option stays hidden; the default single-image
+lanes keep working unaffected.
+
+## Files
+
+| File | Role |
+|---|---|
+| `main.py` | FastAPI app, streaming weight loader, task store, GPU executor, single-view and multi-view generation. |
+| `camera_rig.py` | Turns view labels into azimuths and camera transform matrices when no real camera data exists. Pure logic, unit tested (`test_camera_rig.py`). |
+| `mv_adapter_fill.py` | The `fill_other_sides` rung: wraps MV-Adapter's own `prepare_pipeline`/`run_pipeline` reference functions. |
+| `request_policy.py` | Resolution presets, tier mapping, bake clamps, fetch-retry policy. Pure logic. |
+| `pipeline_config.py` | Rewrites upstream's `pipeline.json`/`pipeline_mv.json` to the licence-clean model set below. |
+| `glb_pack.py` | Alpha-mode decision and meshopt packing through `gltfpack`. |
+| `stage_weights.sh` | One-time mirror of every upstream weight into `gs://three-ws-model-weights/pixal3d` and `.../pixal3d-mvadapter`. |
+| `worker_security.py`, `instance_health.py`, `storage_backend.py` | Vendored shared modules, kept byte-identical by `npm run check:vendored`. |
+| `Dockerfile`, `cloudbuild.yaml` | CUDA 12.4 image with the compiled extensions, and the Cloud Build deploy. |
+| `test_*.py` | Unit and contract tests. They also run as the build-time gate inside the Dockerfile. |
+
+## Deploy
+
+GPU worker deploys are owner-gated. The image build compiles the same CUDA
+extensions `model-trellis2` does plus `natten`, and takes most of an hour on
+the 32-vCPU builder; the config pins the `three-ws-build@` service account.
+
+```bash
+# 1. One time: mirror the weights (idempotent, skips what is already there).
+workers/model-pixal3d/stage_weights.sh
+
+# 2. Build, push and deploy.
+gcloud builds submit --config workers/model-pixal3d/cloudbuild.yaml \
+ --region us-central1 --project aerial-vehicle-466722-p5 \
+ --substitutions=SHORT_SHA=manual$(date +%s) .
+
+# 3. Point the API at it.
+gcloud run services update three-ws-api --region us-central1 \
+ --update-env-vars MODEL_PIXAL3D_URL=$(gcloud run services describe model-pixal3d \
+ --region us-central1 --format='value(status.url)')
+```
+
+The service runs on one NVIDIA L4 (24 GB) with minimum instances `0`. The
+us-central1 L4 grant is shared by every GPU lane, so a warm floor here is a
+quota decision: the first request after idle pays the weight stream and
+pipeline load, and the keep-warm cron does not warm this lane by default.
+Raise the floor with `gcloud run services update model-pixal3d
+--min-instances=1` when quota allows.
+
+## Licence notes
+
+Pixal3D is MIT. The same two upstream swaps `model-trellis2` already made are
+carried over, since Pixal3D's reference scripts hardcode the same two
+non-local dependencies:
+
+- **Background removal: BiRefNet (MIT) instead of RMBG-2.0.** RMBG-2.0 is
+ CC BY-NC 4.0, which forbids commercial use.
+- **Image conditioner: DINOv3 ViT-L/16 from an ungated mirror**
+ (`camenduru/dinov3-vitl16-pretrain-lvd1689m`). The official `facebook/` repo
+ is gated and the platform's Hugging Face token is refused on it.
+
+`pipeline_config.py` applies both swaps by rewriting `pipeline.json` and
+`pipeline_mv.json` at load time; `main.py` additionally patches
+`inference.py`'s and `inference_mv.py`'s own hardcoded `IMAGE_COND_CONFIGS`
+dict to the same local copy, since those scripts rebuild their four per-stage
+conditioners from that dict rather than from the pipeline config's own key.
+
+**MV-Adapter** (the optional `fill_other_sides` rung) is Apache-2.0, as are
+its published adapter weights. Its SDXL base,
+`stabilityai/stable-diffusion-xl-base-1.0`, is CreativeML Open RAIL++-M, which
+permits commercial hosting.
+
+**Open licence risk, owner decision, inherited from TRELLIS.2:**
+`nvdiffrast`. See [`../model-trellis2/README.md`](../model-trellis2/README.md)'s
+identical note: NVIDIA's rasteriser carries the NVIDIA Source Code License
+(1-Way Commercial), which this worker does not widen but also does not
+remove.
+
+Known limits:
+
+- `1536` on a 24 GB L4 is the tightest setting and is unverified until the
+ first deployed generation. The worker steps down on out-of-memory and
+ reports `resolution_served`.
+- `LOW_VRAM=1` keeps each stage's weights off the GPU except while it runs,
+ but a single instance that serves a single-view request and then a
+ multi-view request over its lifetime can still end up holding both
+ pipelines' Python objects (not their GPU tensors) resident. If live traffic
+ shows VRAM contention between request shapes, split the lane into two
+ Cloud Run services behind separate `MODEL_PIXAL3D_URL`-style env vars, one
+ per request shape, rather than trying to share an instance.
+- The exact sampler hyperparameters `mv_adapter_fill.py` uses
+ (`NUM_INFERENCE_STEPS`, `GUIDANCE_SCALE`) are upstream's own script defaults
+ and have not been tuned against a live GPU; treat them as a starting point.
+
+Related: [`../model-trellis2/README.md`](../model-trellis2/README.md) (the
+default, non-fidelity lane), [`../../docs/forge-pipeline.md`](../../docs/forge-pipeline.md),
+[`../../docs/ops/gcp-model-workers.md`](../../docs/ops/gcp-model-workers.md).
diff --git a/workers/model-pixal3d/camera_rig.py b/workers/model-pixal3d/camera_rig.py
new file mode 100644
index 000000000..7b552d1a1
--- /dev/null
+++ b/workers/model-pixal3d/camera_rig.py
@@ -0,0 +1,132 @@
+"""Synthetic camera rig for Pixal3D multi-view requests.
+
+Pixal3D's multi-view pipeline (`inference_mv.py`) wants a `transforms.json`-style
+record per input image: a 4x4 camera-to-world transform matrix, a horizontal FOV
+and a camera distance, with frame 0 required to be the canonical front view
+(camera at world position (0, -distance, 0)).
+
+Forge callers send plain labels ("front", "back", "left", "right") instead of
+real camera data, so this module turns a label (or a slot index when no label
+was given) into the matrix Pixal3D expects. The front-view matrix constant and
+the "rotate about world +Z" rule both come from Pixal3D's own
+`pixal3d/trainers/flow_matching/mixins/image_conditioned_proj.py`
+(`ProjGrid.front_view_transform_matrix`, with `[1, 3]` overwritten to
+`-distance` at runtime). Pixal3D itself never defines a left/right handedness
+beyond "frame 0 is front"; the azimuth convention below (front=0, right=90,
+back=180, left=270, counter-clockwise about +Z) is this worker's own and is
+applied consistently to every request.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Optional, Sequence
+
+VIEW_AZIMUTH_DEGREES = {
+ "front": 0.0,
+ "right": 90.0,
+ "back": 180.0,
+ "left": 270.0,
+}
+
+# Even-spacing fallback azimuths for requests that attach images without view
+# labels, keyed by how many images were sent. Index 0 is always 0 degrees
+# (front) so an unlabeled first image still satisfies Pixal3D's frame-0 rule.
+_EVEN_SPACING = {
+ 1: (0.0,),
+ 2: (0.0, 180.0),
+ 3: (0.0, 120.0, 240.0),
+ 4: (0.0, 90.0, 180.0, 270.0),
+}
+
+
+def resolve_azimuths(view_labels: Sequence[Optional[str]]) -> list[float]:
+ """The azimuth in degrees for each slot, honoring labels where given.
+
+ Labeled slots use `VIEW_AZIMUTH_DEGREES`; unlabeled slots fall back to the
+ even spacing for the total count, matched to their position among the
+ *unlabeled* slots only, so a partially-labeled request (e.g. front labeled,
+ the rest blank) still spreads the blanks evenly instead of clustering them
+ at the labeled azimuths. An unrecognized label is treated as unlabeled.
+ """
+ n = len(view_labels)
+ if n == 0:
+ return []
+ result: list[Optional[float]] = [None] * n
+ unlabeled_positions = []
+ for i, label in enumerate(view_labels):
+ key = (label or "").strip().lower()
+ if key in VIEW_AZIMUTH_DEGREES:
+ result[i] = VIEW_AZIMUTH_DEGREES[key]
+ else:
+ unlabeled_positions.append(i)
+ if unlabeled_positions:
+ spacing = _EVEN_SPACING.get(n, tuple(360.0 * i / n for i in range(n)))
+ used = {v for v in result if v is not None}
+ # Skip spacing slots an explicit label already claimed, so a labeled
+ # front doesn't also get handed to the first unlabeled slot.
+ available = [v for v in spacing if v not in used]
+ if len(available) < len(unlabeled_positions):
+ available = list(spacing)
+ for slot_index, position in enumerate(unlabeled_positions):
+ result[position] = available[slot_index % len(available)]
+ return [float(v) for v in result]
+
+
+def transform_matrix_for_azimuth(azimuth_degrees: float, distance: float) -> list[list[float]]:
+ """The 4x4 camera-to-world matrix for a camera orbiting at `azimuth_degrees`.
+
+ Built as `Rz(theta) @ F` where `F` is Pixal3D's front-view matrix with its
+ distance slot filled in, and `Rz` is a right-handed rotation about world
+ +Z. At theta=0 this is exactly Pixal3D's own front-view matrix (camera at
+ (0, -distance, 0)); at 90/180/270 the camera orbits to
+ (distance, 0, 0) / (0, distance, 0) / (-distance, 0, 0) respectively.
+ """
+ theta = math.radians(azimuth_degrees)
+ cos_t, sin_t = math.cos(theta), math.sin(theta)
+
+ front = [
+ [1.0, 0.0, 0.0, 0.0],
+ [0.0, 0.0, -1.0, -float(distance)],
+ [0.0, 1.0, 0.0, 0.0],
+ [0.0, 0.0, 0.0, 1.0],
+ ]
+ rotate_z = [
+ [cos_t, -sin_t, 0.0, 0.0],
+ [sin_t, cos_t, 0.0, 0.0],
+ [0.0, 0.0, 1.0, 0.0],
+ [0.0, 0.0, 0.0, 1.0],
+ ]
+
+ result = [[0.0] * 4 for _ in range(4)]
+ for i in range(4):
+ for j in range(4):
+ result[i][j] = sum(rotate_z[i][k] * front[k][j] for k in range(4))
+ return result
+
+
+def camera_position(matrix: Sequence[Sequence[float]]) -> tuple[float, float, float]:
+ """The world-space camera position encoded in a camera-to-world matrix."""
+ return (matrix[0][3], matrix[1][3], matrix[2][3])
+
+
+def build_view_rig(
+ view_labels: Sequence[Optional[str]], distance: float, camera_angle_x: float
+) -> list[dict]:
+ """One Pixal3D-ready view record per input slot, in input order.
+
+ Each record carries the fields `inference_mv.py`'s `load_views()` needs per
+ view: `transform_matrix`, `camera_angle_x` and `camera_distance` (the same
+ FOV and distance are reused for every view, matching Pixal3D's own
+ same-camera assumption for synthetic multi-view input).
+ """
+ azimuths = resolve_azimuths(view_labels)
+ return [
+ {
+ "azimuth_degrees": azimuth,
+ "transform_matrix": transform_matrix_for_azimuth(azimuth, distance),
+ "camera_angle_x": float(camera_angle_x),
+ "camera_distance": float(distance),
+ }
+ for azimuth in azimuths
+ ]
diff --git a/workers/model-pixal3d/cloudbuild.yaml b/workers/model-pixal3d/cloudbuild.yaml
new file mode 100644
index 000000000..849bca183
--- /dev/null
+++ b/workers/model-pixal3d/cloudbuild.yaml
@@ -0,0 +1,89 @@
+substitutions:
+ _REGION: us-central1
+ _RUN_SA: avatar-reconstruction-sa@aerial-vehicle-466722-p5.iam.gserviceaccount.com
+ _SERVICE: model-pixal3d
+ _REPO: model-pixal3d
+ _GCS_BUCKET: three-ws-avatar-reconstructions
+ _WEIGHTS_BUCKET: three-ws-model-weights
+ _WEIGHTS_BUCKET_PREFIX: pixal3d
+ _MVADAPTER_BUCKET_PREFIX: pixal3d-mvadapter
+ # Scale-to-zero by default; see workers/model-trellis2/cloudbuild.yaml's
+ # identical comment about the shared us-central1 L4 grant
+ # (docs/ops/gcp-credits-plan.md). The first request after a cold start pays
+ # the weight stream and pipeline load (BACKENDS.pixal3d.coldStartSeconds).
+ _MIN_INSTANCES: "0"
+ _MAX_INSTANCES: "2"
+
+steps:
+ - id: build
+ name: gcr.io/cloud-builders/docker
+ dir: workers/model-pixal3d
+ args:
+ - build
+ - --tag
+ - ${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/server:$SHORT_SHA
+ - --tag
+ - ${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/server:latest
+ - --cache-from
+ - ${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/server:latest
+ - .
+
+ - id: push
+ name: gcr.io/cloud-builders/docker
+ args:
+ - push
+ - --all-tags
+ - ${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/server
+
+ - id: deploy
+ name: gcr.io/google.com/cloudsdktool/cloud-sdk:slim
+ entrypoint: gcloud
+ args:
+ - run
+ - deploy
+ - ${_SERVICE}
+ - --image=${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/server:$SHORT_SHA
+ - --region=${_REGION}
+ - --service-account=${_RUN_SA}
+ - --platform=managed
+ - --port=8080
+ - --gpu=1
+ - --gpu-type=nvidia-l4
+ - --no-gpu-zonal-redundancy
+ - --no-cpu-throttling
+ - --cpu=8
+ - --memory=32Gi
+ - --min-instances=${_MIN_INSTANCES}
+ - --max-instances=${_MAX_INSTANCES}
+ - --timeout=900
+ - --allow-unauthenticated
+ # The checkpoint tree (about 46 GiB across both pipelines) does not fit the
+ # in-memory filesystem next to a loaded model, so main.py streams each
+ # sub-model from WEIGHTS_GCS_URI one at a time (download, load, delete). The
+ # gcsfuse volume below is the fallback read path and carries no cold-start
+ # cost until a file is opened.
+ - --add-volume=name=weights,type=cloud-storage,bucket=${_WEIGHTS_BUCKET}
+ - --add-volume-mount=volume=weights,mount-path=/weights
+ - --set-env-vars=GCS_BUCKET=${_GCS_BUCKET},WEIGHTS_DIR=/weights/${_WEIGHTS_BUCKET_PREFIX},MAX_CONCURRENT=1,WEIGHTS_GCS_URI=gs://${_WEIGHTS_BUCKET}/${_WEIGHTS_BUCKET_PREFIX},WEIGHTS_LOCAL_DIR=/tmp/pixal3d-weights,MVADAPTER_WEIGHTS_DIR=/weights/${_MVADAPTER_BUCKET_PREFIX}
+ - --set-secrets=API_KEY=avatar-reconstruction-key:latest
+ # Recycle an instance whose weight staging is permanently dead. main.py
+ # answers /health with 503 only once the whole load-retry budget is spent,
+ # so an ordinary cold load (200 while staging) is never killed mid-load.
+ - --liveness-probe=httpGet.path=/health,initialDelaySeconds=60,periodSeconds=60,timeoutSeconds=10,failureThreshold=3
+
+images:
+ - ${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/server:$SHORT_SHA
+ - ${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/server:latest
+
+options:
+ machineType: E2_HIGHCPU_32
+ logging: CLOUD_LOGGING_ONLY
+
+# CUDA extension compiles (nvdiffrast, CuMesh, FlexGEMM, o-voxel, natten) push the
+# image build well past Cloud Build's 10-minute default. Give it an hour, same as
+# workers/model-trellis2.
+timeout: 3600s
+
+# The project's default compute SA was deleted: builds must pin the dedicated
+# build account or submits fail with "Unknown service account".
+serviceAccount: projects/aerial-vehicle-466722-p5/serviceAccounts/[email protected]
diff --git a/workers/model-pixal3d/glb_pack.py b/workers/model-pixal3d/glb_pack.py
new file mode 100644
index 000000000..7de09f033
--- /dev/null
+++ b/workers/model-pixal3d/glb_pack.py
@@ -0,0 +1,88 @@
+"""Post-processing for a TRELLIS.2 GLB: keep transparency, then meshopt-compress.
+
+numpy and the stdlib only (the trimesh scene is duck-typed), so the decisions
+unit test without a GPU (test_glb_pack.py).
+
+Two jobs:
+
+ 1. Alpha. o_voxel's to_glb bakes opacity into the base colour texture's alpha
+ channel but always declares the material OPAQUE, so a viewer ignores it and
+ a leaf or a glass pane renders as a solid card. `blend_if_translucent`
+ flips the material to BLEND when the baked alpha is genuinely translucent.
+ 2. Compression. `gltfpack -cc` rewrites the GLB with EXT_meshopt_compression
+ and quantized attributes, the same encoding three.ws avatars ship with, so
+ the viewer's existing MeshoptDecoder reads it. Textures pass through
+ untouched (no -tc), which keeps the baked PBR maps and alpha byte-exact.
+ A failed pack never fails the job: the uncompressed GLB is still a valid
+ asset, so it is returned and the reason is logged.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+import numpy as np
+
+log = logging.getLogger("glb-pack")
+
+GLTFPACK_BIN = os.environ.get("GLTFPACK_BIN", "gltfpack")
+GLTFPACK_TIMEOUT_S = int(os.environ.get("GLTFPACK_TIMEOUT_S", "300"))
+
+# A texel counts as translucent below this alpha, and the asset only flips to
+# BLEND when enough of the texture is: stray inpainting pixels at UV seams must
+# not turn a solid object into a sorted-transparency one.
+TRANSLUCENT_BELOW = 245
+TRANSLUCENT_MIN_FRACTION = 0.01
+
+
+def alpha_mode_for(alpha: np.ndarray) -> str:
+ """OPAQUE or BLEND for a baked alpha plane (uint8, any shape)."""
+ plane = np.asarray(alpha)
+ if plane.size == 0:
+ return "OPAQUE"
+ translucent = float(np.count_nonzero(plane < TRANSLUCENT_BELOW)) / plane.size
+ return "BLEND" if translucent >= TRANSLUCENT_MIN_FRACTION else "OPAQUE"
+
+
+def blend_if_translucent(mesh) -> str:
+ """Set the mesh material's alphaMode from its baked texture and return it."""
+ material = getattr(getattr(mesh, "visual", None), "material", None)
+ texture = getattr(material, "baseColorTexture", None)
+ if material is None or texture is None or getattr(texture, "mode", "") != "RGBA":
+ return "OPAQUE"
+ mode = alpha_mode_for(np.asarray(texture)[..., 3])
+ material.alphaMode = mode
+ return mode
+
+
+def compress(glb: bytes, gltfpack_bin: Optional[str] = None) -> tuple[bytes, bool]:
+ """Meshopt-compress a GLB. Returns (bytes, compressed)."""
+ binary = gltfpack_bin or GLTFPACK_BIN
+ with tempfile.TemporaryDirectory() as tmp:
+ src = Path(tmp) / "in.glb"
+ dst = Path(tmp) / "out.glb"
+ src.write_bytes(glb)
+ try:
+ subprocess.run(
+ [binary, "-i", str(src), "-o", str(dst), "-cc"],
+ check=True,
+ capture_output=True,
+ timeout=GLTFPACK_TIMEOUT_S,
+ )
+ packed = dst.read_bytes()
+ except FileNotFoundError:
+ log.warning("gltfpack not found at %s; serving the uncompressed GLB", binary)
+ return glb, False
+ except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as exc:
+ detail = getattr(exc, "stderr", b"") or b""
+ log.warning("gltfpack failed (%s %s); serving the uncompressed GLB", type(exc).__name__, detail[-300:])
+ return glb, False
+ if packed[:4] != b"glTF":
+ log.warning("gltfpack produced a non-GLB output; serving the uncompressed GLB")
+ return glb, False
+ return packed, True
diff --git a/workers/model-pixal3d/instance_health.py b/workers/model-pixal3d/instance_health.py
new file mode 100644
index 000000000..124dbc40a
--- /dev/null
+++ b/workers/model-pixal3d/instance_health.py
@@ -0,0 +1,219 @@
+"""Instance self-care for the TRELLIS worker: host memory and task liveness.
+
+Pure stdlib, no torch and no CUDA, so every decision here is unit tested on any
+machine (see test_instance_health.py) and main.py only wires it in.
+
+Why this module exists (production, 2026-10-03 to 2026-10-08):
+
+ * The single warm L4 instance was OOM-killed twelve times in five days
+ ("Container terminated on signal 9"). Cloud Run's memory utilization for
+ the revision climbed in steps after each heavy job (0.46 -> 0.56 -> 0.71 ->
+ 0.81 -> 0.88 -> 0.91) and never came back down, then a mesh postprocess
+ (decimate, invisible-face removal, UV unwrap, texture bake) pushed it past
+ the 32 GiB ceiling, which is the most memory Cloud Run gives an L4 instance.
+ That is glibc keeping freed heap in per-thread arenas: the pipeline runs in
+ executor threads, each of which grows its own arena, and nothing hands the
+ freed pages back to the kernel.
+ * Every kill took the in-flight job with it, and the queued job behind it.
+ Their durable GCS records stayed "running" until a 30 minute orphan window
+ expired, long after the caller's poll budget, so the forge's lane failover
+ never saw a failure to act on and the user just watched a spinner.
+
+The fixes are split by what they guard against:
+
+ trim_heap() returns freed heap to the kernel after every job.
+ read_memory() reports what the instance actually holds, so each job
+ logs its footprint and the recycle guard has a number.
+ should_recycle() decides when an instance has ratcheted far enough that
+ it should restart BETWEEN jobs rather than die inside one.
+ task_is_orphaned() lets a heartbeat-refreshed record expire in minutes, not
+ half an hour, once its runner is gone.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import ctypes.util
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+# How often a live task refreshes its durable record, and how long a queued or
+# running record may go without a refresh before it is declared orphaned. Six
+# missed beats is far beyond any scheduling hiccup on a healthy instance, and
+# still well inside the forge client's ~300 s poll budget, so the failure lands
+# while a client is still listening and the lane failover can redispatch.
+HEARTBEAT_SECS = 30.0
+ORPHAN_AFTER_SECS = 180.0
+
+# Recycle once the instance holds this share of its memory limit after a job...
+RECYCLE_FRACTION = float(os.environ.get("MEMORY_RECYCLE_FRACTION", "0.80"))
+# ...and only if it has grown at least this much past its post-load baseline. The
+# growth floor is what stops a mismeasured or simply large baseline from turning
+# into a restart after every single job.
+RECYCLE_MIN_GROWTH = float(os.environ.get("MEMORY_RECYCLE_MIN_GROWTH", "0.15"))
+
+_CGROUP_V2 = "/sys/fs/cgroup"
+_CGROUP_V1 = "/sys/fs/cgroup/memory"
+_MEMINFO = "/proc/meminfo"
+
+
+@dataclass(frozen=True)
+class MemorySample:
+ used_bytes: int
+ limit_bytes: int
+ source: str
+
+ @property
+ def fraction(self) -> float:
+ return self.used_bytes / self.limit_bytes if self.limit_bytes else 0.0
+
+ def describe(self) -> str:
+ gib = 1024 ** 3
+ return (
+ f"{self.used_bytes / gib:.1f}/{self.limit_bytes / gib:.1f} GiB "
+ f"({self.fraction:.0%}, {self.source})"
+ )
+
+
+def _read(path: str) -> Optional[str]:
+ try:
+ with open(path, encoding="ascii") as fh:
+ return fh.read()
+ except OSError:
+ return None
+
+
+def _stat_fields(text: str) -> dict[str, int]:
+ fields: dict[str, int] = {}
+ for line in text.splitlines():
+ parts = line.split()
+ if len(parts) >= 2 and parts[1].isdigit():
+ fields[parts[0].rstrip(":")] = int(parts[1])
+ return fields
+
+
+def _from_cgroup_v2(root: str) -> Optional[MemorySample]:
+ stat, limit = _read(os.path.join(root, "memory.stat")), _read(os.path.join(root, "memory.max"))
+ if stat is None or limit is None or not limit.strip().isdigit():
+ return None
+ fields = _stat_fields(stat)
+ if "anon" not in fields:
+ return None
+ # anon is the process heap; shmem is tmpfs, which is where Cloud Run's
+ # in-memory filesystem (and so the staged weights in /tmp) is charged.
+ # Page cache is left out on purpose: the kernel reclaims it before it OOMs.
+ return MemorySample(fields["anon"] + fields.get("shmem", 0), int(limit.strip()), "cgroup2")
+
+
+def _from_cgroup_v1(root: str) -> Optional[MemorySample]:
+ stat = _read(os.path.join(root, "memory.stat"))
+ limit = _read(os.path.join(root, "memory.limit_in_bytes"))
+ if stat is None or limit is None or not limit.strip().isdigit():
+ return None
+ fields = _stat_fields(stat)
+ if "total_rss" not in fields:
+ return None
+ limit_bytes = int(limit.strip())
+ # An unlimited v1 group reports a sentinel near 2**63; it says nothing about
+ # this instance's ceiling, so defer to /proc/meminfo instead.
+ if limit_bytes >= 1 << 60:
+ return None
+ return MemorySample(fields["total_rss"] + fields.get("total_shmem", 0), limit_bytes, "cgroup1")
+
+
+def _from_meminfo(path: str) -> Optional[MemorySample]:
+ text = _read(path)
+ if text is None:
+ return None
+ fields = _stat_fields(text)
+ total, available = fields.get("MemTotal"), fields.get("MemAvailable")
+ if not total or available is None:
+ return None
+ # /proc/meminfo is in KiB. MemAvailable already discounts reclaimable cache.
+ return MemorySample((total - available) * 1024, total * 1024, "meminfo")
+
+
+def read_memory(
+ cgroup_v2_root: str = _CGROUP_V2,
+ cgroup_v1_root: str = _CGROUP_V1,
+ meminfo_path: str = _MEMINFO,
+) -> Optional[MemorySample]:
+ """Best available view of the memory this instance holds against its limit.
+
+ Never raises. Returns None when no source is readable, and every caller
+ treats None as "unknown", which never triggers a recycle.
+ """
+ for reader, arg in (
+ (_from_cgroup_v2, cgroup_v2_root),
+ (_from_cgroup_v1, cgroup_v1_root),
+ (_from_meminfo, meminfo_path),
+ ):
+ try:
+ sample = reader(arg)
+ except (ValueError, ZeroDivisionError):
+ sample = None
+ if sample is not None and sample.limit_bytes > 0:
+ return sample
+ return None
+
+
+def should_recycle(
+ current: Optional[MemorySample],
+ baseline: Optional[MemorySample],
+ threshold: float = RECYCLE_FRACTION,
+ min_growth: float = RECYCLE_MIN_GROWTH,
+) -> bool:
+ """True when the instance should restart between jobs.
+
+ Both conditions must hold: the instance is near its ceiling, AND it got
+ there by growing since the model finished loading. Without a baseline (the
+ load has not completed, or memory is unreadable) the answer is always no.
+ """
+ if current is None or baseline is None:
+ return False
+ return current.fraction >= threshold and current.fraction - baseline.fraction >= min_growth
+
+
+_libc = None
+
+
+def trim_heap() -> bool:
+ """Hand freed heap pages back to the kernel (glibc malloc_trim).
+
+ Returns False on a libc without malloc_trim (musl, macOS), where there is
+ nothing to do. Never raises.
+ """
+ global _libc
+ try:
+ if _libc is None:
+ _libc = ctypes.CDLL(ctypes.util.find_library("c") or "libc.so.6")
+ trim = getattr(_libc, "malloc_trim", None)
+ if trim is None:
+ return False
+ trim.argtypes = [ctypes.c_size_t]
+ trim.restype = ctypes.c_int
+ trim(0)
+ return True
+ except OSError:
+ return False
+
+
+def task_is_orphaned(
+ status: Optional[str],
+ updated_at: object,
+ now: float,
+ orphan_after: float = ORPHAN_AFTER_SECS,
+) -> bool:
+ """True when a queued or running record has gone stale.
+
+ A live runner refreshes updated_at every HEARTBEAT_SECS, so a record that
+ has not moved for orphan_after seconds belongs to an instance that died.
+ A record with no usable timestamp cannot prove it is alive, so it counts as
+ orphaned too. Terminal and unknown statuses never are.
+ """
+ if status not in ("queued", "running"):
+ return False
+ if isinstance(updated_at, bool) or not isinstance(updated_at, (int, float)):
+ return True
+ return now - updated_at > orphan_after
diff --git a/workers/model-pixal3d/main.py b/workers/model-pixal3d/main.py
new file mode 100644
index 000000000..1510a5d52
--- /dev/null
+++ b/workers/model-pixal3d/main.py
@@ -0,0 +1,966 @@
+"""
+Pixal3D inference service: 1 to 4 photos to a PBR-textured 3D asset
+(TencentARC, MIT license; pixel-aligned image-to-3D built on TRELLIS.2).
+
+This module is a thin FastAPI wrapper around TencentARC/Pixal3D's own
+reference scripts (`inference.py` for the single-view path, `inference_mv.py`
+for the posed multi-view path), vendored into the image and imported directly
+(see PIXAL3D_SRC below) rather than reimplemented: `init_pipeline`,
+`get_camera_params_wild_moge`, `make_rembg` and `to_cond_tensor` all run
+exactly as upstream wrote them. What this file adds is: async task plumbing
+(mirroring workers/model-trellis2/main.py), turning Forge's plain view labels
+into the camera rig Pixal3D's multi-view path expects (camera_rig.py) when no
+real camera data was given, and an optional MV-Adapter "fill in the other
+sides" pre-step for a single photo (mv_adapter_fill.py).
+
+API contract (consumed by the Forge router):
+ POST /infer { images: [data-uri|url, ...] (1 to 4), view_labels?: [str|null, ...],
+ fill_other_sides?: bool, resolution?: 1024|1536, tier?: str,
+ seed?: int, texture_size?: int, decimation_target?: int,
+ body_type?: str, job_id?: str }
+ -> 202 { task_id, status: "queued" }
+
+ One image with no view_labels and fill_other_sides unset or false runs the
+ single-view path (MoGe-2 estimates the camera from the photo itself). Two
+ to four images run the multi-view path: labels ("front"|"back"|"left"|
+ "right") set each view's azimuth around a shared, MoGe-2-estimated camera;
+ unlabeled slots spread evenly. Exactly one image with fill_other_sides=true
+ first synthesizes the other three azimuths with MV-Adapter, then runs the
+ same multi-view path on all four. The task record reports views_used.
+
+ GET /tasks/:id -> { task_id, status, result_gcs_url?, result_url?, resolution?,
+ resolution_served?, views_used?, alpha_mode?, packed?, error? }
+
+ GET /results/:id.glb -> generated GLB when OUTPUT_DIR local storage is active
+
+ GET /health -> { ok, model, gpu_available, resolutions, load_error }.
+ 503 with ok:false once a load attempt has spent its retry
+ budget, so a dead instance is drained.
+
+ GET / -> { service, model, ready, endpoints }. Unauthenticated
+ descriptor for the platform's warmth probe.
+
+Weights: gs://three-ws-model-weights/pixal3d (workers/model-pixal3d/stage_weights.sh).
+
+Environment variables (README.md carries the full table):
+ API_KEY shared bearer secret
+ GCS_BUCKET optional Cloud Storage bucket for output meshes
+ OUTPUT_DIR local task and result volume when GCS_BUCKET is unset
+ WEIGHTS_DIR local weight tree (default: /weights/pixal3d)
+ WEIGHTS_GCS_URI optional gs:// tree; each sub-model streams to local disk,
+ loads, and is deleted, so peak disk is one checkpoint
+ WEIGHTS_LOCAL_DIR scratch for that streaming (default: /tmp/pixal3d-weights)
+ PIXAL3D_SRC vendored Pixal3D repo checkout (default: /opt/pixal3d-src)
+ MVADAPTER_SRC vendored MV-Adapter repo checkout (default: /opt/mvadapter-src)
+ LOW_VRAM "1" moves each stage's weights to the GPU only while it
+ runs (default: 1; a single L4 cannot hold the single-view
+ pipeline, the multi-view pipeline and MV-Adapter resident
+ at once at full precision)
+ MAX_RESOLUTION ceiling on the served resolution (default: 1536)
+ MAX_CONCURRENT max parallel inferences (default: 1)
+ IMAGE_FETCH_TIMEOUT_S per-attempt image fetch timeout (default: 30)
+ MODEL_LOAD_ATTEMPTS weight-staging attempts before the error latches (default: 4)
+ MODEL_LOAD_RETRY_BASE_S / MODEL_LOAD_RETRY_CAP_S load-retry backoff bounds
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import gc
+import io
+import json
+import logging
+import os
+import shutil
+import signal
+import sys
+import tempfile
+import time
+import uuid
+
+import httpx
+
+os.environ.setdefault("ATTN_BACKEND", "xformers")
+os.environ.setdefault("PYTORCH_CUDA_ALLOC_CONF", "expandable_segments:True")
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Optional
+from urllib.parse import urlsplit
+
+import torch
+from fastapi import FastAPI, HTTPException, Header, BackgroundTasks, Response
+from fastapi.responses import FileResponse
+from google.api_core.exceptions import NotFound
+from google.cloud import storage
+from PIL import Image
+from pydantic import BaseModel, Field
+
+import camera_rig
+import glb_pack
+import pipeline_config
+from request_policy import (
+ DEFAULT_RESOLUTION,
+ FETCH_ATTEMPTS,
+ PIPELINE_TYPES,
+ RESOLUTIONS,
+ bake_params,
+ call_with_retry,
+ clamp_to_ceiling,
+ resolve_resolution,
+ step_down,
+)
+from worker_security import (
+ UnsafeUrlError,
+ fetch_remote_bytes,
+ require_api_key,
+ safe_error,
+)
+from storage_backend import LocalStorage
+from instance_health import (
+ HEARTBEAT_SECS,
+ MemorySample,
+ read_memory,
+ should_recycle,
+ task_is_orphaned,
+ trim_heap,
+)
+
+logging.basicConfig(
+ level=logging.INFO,
+ format="%(asctime)s %(levelname)s %(name)s %(message)s",
+)
+log = logging.getLogger("pixal3d")
+
+# Pixal3D's reference scripts (inference.py, inference_mv.py) live at the root
+# of the vendored checkout, not inside the installable `pixal3d` package, so
+# they are imported by adding that checkout to sys.path rather than pip-level
+# packaging. MV-Adapter's reference script is imported the same way.
+PIXAL3D_SRC = os.environ.get("PIXAL3D_SRC", "/opt/pixal3d-src")
+MVADAPTER_SRC = os.environ.get("MVADAPTER_SRC", "/opt/mvadapter-src")
+for _src in (PIXAL3D_SRC, MVADAPTER_SRC):
+ if _src not in sys.path:
+ sys.path.insert(0, _src)
+
+API_KEY = os.environ["API_KEY"]
+GCS_BUCKET = os.environ.get("GCS_BUCKET", "").strip()
+OUTPUT_DIR = os.environ.get("OUTPUT_DIR", "/output")
+WEIGHTS_DIR = os.environ.get("WEIGHTS_DIR", "/weights/pixal3d")
+MAX_CONCURRENT = int(os.environ.get("MAX_CONCURRENT", "1"))
+MAX_RESOLUTION = int(os.environ.get("MAX_RESOLUTION", str(max(RESOLUTIONS))))
+LOW_VRAM = os.environ.get("LOW_VRAM", "1") != "0"
+# Same reasoning as workers/model-trellis2: Cloud Run's filesystem cannot hold a
+# ~46 GB checkpoint tree next to the job's own memory budget, and GCS FUSE
+# stalls on safetensors' random reads. Each sub-model streams to local disk,
+# loads, and is deleted.
+WEIGHTS_GCS_URI = os.environ.get("WEIGHTS_GCS_URI", "").rstrip("/")
+WEIGHTS_LOCAL_DIR = os.environ.get("WEIGHTS_LOCAL_DIR", "/tmp/pixal3d-weights")
+CONFIG_DIR = os.path.join(WEIGHTS_LOCAL_DIR, "config")
+AUX_DIR = os.path.join(WEIGHTS_LOCAL_DIR, "aux")
+MODEL_LOAD_ATTEMPTS = int(os.environ.get("MODEL_LOAD_ATTEMPTS", "4"))
+MODEL_LOAD_RETRY_BASE_S = float(os.environ.get("MODEL_LOAD_RETRY_BASE_S", "15"))
+MODEL_LOAD_RETRY_CAP_S = float(os.environ.get("MODEL_LOAD_RETRY_CAP_S", "120"))
+
+_weights_ready: Optional[asyncio.Event] = None
+_load_error: Optional[str] = None
+_load_attempts = 0
+_bucket: Optional[storage.Bucket] = None
+_local_storage: Optional[LocalStorage] = None
+_sem: Optional[asyncio.Semaphore] = None
+# Lazily-loaded singletons. Only the pipeline(s) a request shape actually needs
+# ever get moved to the GPU; see _get_single_pipeline / _get_mv_pipeline /
+# _get_moge_model / mv_adapter_fill.get_pipeline. One lock per kind serializes
+# the first caller's load against a second caller arriving mid-load.
+_single_pipeline = None
+_mv_pipeline = None
+_moge_model = None
+_single_lock: Optional[asyncio.Lock] = None
+_mv_lock: Optional[asyncio.Lock] = None
+_moge_lock: Optional[asyncio.Lock] = None
+_tasks: dict[str, dict] = {}
+_task_locks: dict[str, asyncio.Lock] = {}
+_live_tasks: set[str] = set()
+_memory_baseline: Optional[MemorySample] = None
+_draining = False
+_restart_signalled = False
+
+
+def _gcs_split(uri: str) -> tuple[str, str]:
+ bucket_name, _, prefix = uri[len("gs://"):].partition("/")
+ return bucket_name, prefix.strip("/")
+
+
+def _download_blob(blob, dest: str) -> None:
+ os.makedirs(os.path.dirname(dest), exist_ok=True)
+ if os.path.exists(dest) and blob.size is not None and os.path.getsize(dest) == blob.size:
+ return
+ blob.download_to_filename(dest)
+
+
+def _stage_aux_weights(client: storage.Client, bucket_name: str, prefix: str) -> None:
+ """Copy the DINOv3 conditioner and BiRefNet matte to local disk.
+
+ They stay resident for the instance's life, unlike the per-stage flow
+ checkpoints, which stream through on demand.
+ """
+ from concurrent.futures import ThreadPoolExecutor
+
+ wanted = [
+ b
+ for sub in (pipeline_config.DINOV3_DIR, pipeline_config.BIREFNET_DIR)
+ for b in client.list_blobs(bucket_name, prefix=f"{prefix}/{sub}/")
+ if not b.name.endswith("/")
+ ]
+ t0 = time.time()
+ with ThreadPoolExecutor(max_workers=8) as pool:
+ list(pool.map(lambda b: _download_blob(b, os.path.join(AUX_DIR, b.name[len(prefix) + 1:])), wanted))
+ log.info("aux weights staged to %s in %.1fs (%d objects)", AUX_DIR, time.time() - t0, len(wanted))
+
+
+def _install_streaming_loader(client: storage.Client, bucket_name: str, prefix: str) -> None:
+ """Make Pixal3D's per-model loader stream each checkpoint from GCS.
+
+ `pixal3d.models.from_pretrained` resolves every model as
+ `<CONFIG_DIR>/<name>`; the wrapper fetches `<name>.json` and
+ `<name>.safetensors` from the weights prefix, loads them, and removes
+ them, so disk and RAM never hold more than a couple checkpoints at once.
+ """
+ import pixal3d.models as p3d_models
+
+ original = p3d_models.from_pretrained
+ bucket = client.bucket(bucket_name)
+
+ def streaming(path: str, **kwargs):
+ if not path.startswith(CONFIG_DIR + "/"):
+ return original(path, **kwargs)
+ name = path[len(CONFIG_DIR) + 1:]
+ scratch = os.path.join(WEIGHTS_LOCAL_DIR, "stream")
+ local = os.path.join(scratch, name)
+ os.makedirs(os.path.dirname(local), exist_ok=True)
+ try:
+ for ext in (".json", ".safetensors"):
+ blob = bucket.get_blob(f"{prefix}/{name}{ext}")
+ if blob is None:
+ raise FileNotFoundError(f"gs://{bucket_name}/{prefix}/{name}{ext} is not staged")
+ blob.download_to_filename(local + ext)
+ return original(local, **kwargs)
+ finally:
+ shutil.rmtree(scratch, ignore_errors=True)
+
+ p3d_models.from_pretrained = streaming
+
+
+def _patch_image_cond_configs(dinov3_local_dir: str) -> None:
+ """Point both reference scripts' DinoV3 conditioner at the staged copy.
+
+ Upstream hardcodes the ungated mirror `camenduru/dinov3-vitl16-pretrain-
+ lvd1689m` in a module-level dict rather than reading it from pipeline.json
+ (see pipeline_config.py's docstring), so the dict itself is rewritten here
+ after import instead of being left to reach the Hub at serve time.
+ """
+ import inference as sv_ref
+ import inference_mv as mv_ref
+
+ for ref in (sv_ref, mv_ref):
+ for cfg in ref.IMAGE_COND_CONFIGS.values():
+ cfg["model_name"] = dinov3_local_dir
+
+
+def _prepare_pipeline_path() -> str:
+ """Return the config directory Pixal3D loads from, staging what it needs."""
+ if WEIGHTS_GCS_URI.startswith("gs://"):
+ client = storage.Client()
+ bucket_name, prefix = _gcs_split(WEIGHTS_GCS_URI)
+ names = [
+ b.name[len(prefix) + 1:]
+ for b in client.list_blobs(bucket_name, prefix=prefix + "/")
+ if not b.name.endswith("/")
+ ]
+ missing = pipeline_config.missing_weights(names)
+ if missing:
+ raise FileNotFoundError(f"Pixal3D weights incomplete at {WEIGHTS_GCS_URI}: {', '.join(missing)}")
+ _stage_aux_weights(client, bucket_name, prefix)
+ bucket = client.bucket(bucket_name)
+ for name in ("pipeline.json", "pipeline_mv.json"):
+ text = bucket.blob(f"{prefix}/{name}").download_as_text()
+ pipeline_config.write_local_config(text, AUX_DIR, os.path.join(CONFIG_DIR, name))
+ _install_streaming_loader(client, bucket_name, prefix)
+ _patch_image_cond_configs(os.path.join(AUX_DIR, pipeline_config.DINOV3_DIR))
+ return CONFIG_DIR
+
+ root = Path(WEIGHTS_DIR)
+ present = [str(p.relative_to(root)) for p in root.rglob("*") if p.is_file() or p.is_symlink()]
+ missing = pipeline_config.missing_weights(present)
+ if missing:
+ raise FileNotFoundError(f"Pixal3D weights incomplete at {root}: {', '.join(missing)}")
+ for name in ("pipeline.json", "pipeline_mv.json"):
+ pipeline_config.write_local_config(
+ (root / name).read_text(), root, Path(CONFIG_DIR) / name
+ )
+ pipeline_config.link_weight_tree(root, CONFIG_DIR)
+ _patch_image_cond_configs(str(root / pipeline_config.DINOV3_DIR))
+ return CONFIG_DIR
+
+
+def _stage_weights_sync() -> None:
+ """Blocking weight-staging step, run once in a background thread at startup.
+
+ Unlike workers/model-trellis2 (one pipeline, loaded eagerly), Pixal3D's
+ two pipelines and MV-Adapter's optional rung load lazily on first use (see
+ _get_single_pipeline / _get_mv_pipeline), so startup only has to prove the
+ weight tree is complete and build the local pipeline.json/pipeline_mv.json
+ once, not touch the GPU.
+ """
+ _prepare_pipeline_path()
+
+
+async def _stage_weights_bg() -> None:
+ """Stage weights with retries; signal readiness so /infer stops refusing work.
+
+ See workers/model-trellis2's identical comment: the very first exception
+ is NOT latched. A transient staging blip must not turn into a permanently
+ dead instance that Cloud Run's minScale keeps resident and in rotation.
+ """
+ global _load_error, _load_attempts
+ loop = asyncio.get_event_loop()
+ attempts = max(1, MODEL_LOAD_ATTEMPTS)
+ for attempt in range(1, attempts + 1):
+ _load_attempts = attempt
+ try:
+ await loop.run_in_executor(None, _stage_weights_sync)
+ _load_error = None
+ _weights_ready.set()
+ log.info("Pixal3D weights staged and config written (attempt %d)", attempt)
+ return
+ except Exception as exc: # noqa: BLE001 - surfaced via /health + task status
+ if attempt >= attempts:
+ _load_error = safe_error(exc, context="weight staging")
+ log.error("Pixal3D weight staging FAILED after %d attempt(s): %s", attempt, exc)
+ return
+ delay = min(MODEL_LOAD_RETRY_BASE_S * (2 ** (attempt - 1)), MODEL_LOAD_RETRY_CAP_S)
+ log.warning(
+ "Pixal3D weight staging attempt %d/%d failed (%s); retrying in %.0fs",
+ attempt, attempts, exc, delay,
+ )
+ await asyncio.sleep(delay)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+ global _bucket, _local_storage, _sem, _weights_ready, _single_lock, _mv_lock, _moge_lock
+ if GCS_BUCKET:
+ _bucket = storage.Client().bucket(GCS_BUCKET)
+ _local_storage = None
+ else:
+ _bucket = None
+ _local_storage = LocalStorage(OUTPUT_DIR)
+ _sem = asyncio.Semaphore(MAX_CONCURRENT)
+ _weights_ready = asyncio.Event()
+ _single_lock = asyncio.Lock()
+ _mv_lock = asyncio.Lock()
+ _moge_lock = asyncio.Lock()
+ asyncio.create_task(_stage_weights_bg())
+ log.info("Service starting, weight staging in background (max_concurrent=%d, low_vram=%s)", MAX_CONCURRENT, LOW_VRAM)
+ yield
+
+
+app = FastAPI(title="model-pixal3d", lifespan=lifespan)
+
+
+def _require_api_key(authorization: str) -> None:
+ try:
+ require_api_key(authorization, API_KEY)
+ except PermissionError as exc:
+ raise HTTPException(status_code=401, detail=str(exc)) from exc
+
+
+class ImageSourceError(ValueError):
+ """A caller-supplied image could not be read. See workers/model-trellis2."""
+
+
+IMAGE_FETCH_TIMEOUT_S = float(os.environ.get("IMAGE_FETCH_TIMEOUT_S", "30"))
+
+
+def _source_label(src: str) -> str:
+ if src.startswith("data:image"):
+ return "inline data uri"
+ host = urlsplit(src).hostname
+ return host or src[:60]
+
+
+def _fetch_image_bytes(src: str) -> bytes:
+ label = _source_label(src)
+
+ def attempt() -> bytes:
+ return fetch_remote_bytes(src, timeout=IMAGE_FETCH_TIMEOUT_S)
+
+ def note_retry(number: int, delay: float, exc: BaseException) -> None:
+ log.warning(
+ "image fetch attempt %d/%d for %s failed (%s); retrying in %.1fs",
+ number, FETCH_ATTEMPTS, label, type(exc).__name__, delay,
+ )
+
+ try:
+ return call_with_retry(attempt, sleep=time.sleep, on_retry=note_retry)
+ except UnsafeUrlError as exc:
+ raise ImageSourceError(f"refused to fetch image source ({label}): {exc}") from exc
+ except httpx.HTTPStatusError as exc:
+ raise ImageSourceError(f"image source {label} returned HTTP {exc.response.status_code}") from exc
+ except httpx.HTTPError as exc:
+ raise ImageSourceError(
+ f"image source {label} unreachable after {FETCH_ATTEMPTS} attempts "
+ f"({type(exc).__name__}); check the URL is publicly readable"
+ ) from exc
+ except ValueError as exc:
+ raise ImageSourceError(f"image source {label} rejected: {exc}") from exc
+
+
+def _decode_image(src: str) -> Image.Image:
+ mode = "RGBA"
+ if src.startswith("data:image"):
+ b64 = src.split(",", 1)[1]
+ try:
+ raw = base64.b64decode(b64)
+ except Exception as exc: # noqa: BLE001 - caller's own payload
+ raise ImageSourceError(f"inline data uri is not valid base64: {exc}") from exc
+ return _open_image(raw, mode, "inline data uri")
+ if src.startswith("https://"):
+ return _open_image(_fetch_image_bytes(src), mode, _source_label(src))
+ raise ImageSourceError(f"unsupported image source: {src[:60]}")
+
+
+def _open_image(data: bytes, mode: str, label: str) -> Image.Image:
+ try:
+ return Image.open(io.BytesIO(data)).convert(mode)
+ except Exception as exc: # noqa: BLE001 - undecodable caller input
+ raise ImageSourceError(f"image source {label} is not a decodable image ({type(exc).__name__})") from exc
+
+
+def _task_blob(task_id: str):
+ if _bucket is None:
+ raise RuntimeError("GCS task storage is not active")
+ return _bucket.blob(f"tasks/{task_id}.json")
+
+
+def _using_gcs() -> bool:
+ return bool(GCS_BUCKET)
+
+
+def _get_local_storage() -> LocalStorage:
+ global _local_storage
+ if _local_storage is None:
+ _local_storage = LocalStorage(OUTPUT_DIR)
+ return _local_storage
+
+
+async def _update_task(task_id: str, **fields) -> dict:
+ lock = _task_locks.setdefault(task_id, asyncio.Lock())
+ async with lock:
+ task = _tasks.setdefault(task_id, {"task_id": task_id})
+ task.update(fields)
+ task["updated_at"] = time.time()
+ snapshot = task.copy()
+ loop = asyncio.get_event_loop()
+ if _using_gcs():
+ payload = json.dumps(snapshot)
+ await loop.run_in_executor(
+ None, lambda: _task_blob(task_id).upload_from_string(payload, content_type="application/json")
+ )
+ else:
+ await loop.run_in_executor(None, _get_local_storage().write_task, snapshot)
+ return task
+
+
+async def _heartbeat(task_id: str) -> None:
+ while True:
+ await asyncio.sleep(HEARTBEAT_SECS)
+ try:
+ await _update_task(task_id)
+ except Exception as exc: # noqa: BLE001 - a missed beat must not kill the job
+ log.warning("[%s] heartbeat write failed: %s", task_id, exc)
+
+
+_TERMINAL_STATUSES = frozenset({"done", "failed"})
+
+
+async def _resolve_task(task_id: str) -> dict:
+ task = _tasks.get(task_id)
+ if task is not None and task.get("status") in _TERMINAL_STATUSES:
+ return task
+ loop = asyncio.get_event_loop()
+ try:
+ if _using_gcs():
+ data = await loop.run_in_executor(None, _task_blob(task_id).download_as_bytes)
+ task = json.loads(data)
+ else:
+ task = await loop.run_in_executor(None, _get_local_storage().read_task, task_id)
+ except (NotFound, FileNotFoundError, ValueError):
+ if task is not None:
+ return task
+ raise HTTPException(status_code=404, detail="task not found")
+ except Exception as exc:
+ raise HTTPException(status_code=502, detail=safe_error(exc, context="task lookup")) from exc
+ status = task.get("status")
+ if status in _TERMINAL_STATUSES:
+ _tasks[task_id] = task
+ return task
+ if task_is_orphaned(status, task.get("updated_at"), time.time()):
+ _tasks[task_id] = task
+ failed = await _update_task(
+ task_id,
+ status="failed",
+ error="task orphaned: its runner instance stopped mid-job "
+ "(restart or out of memory); retry the request",
+ )
+ _task_locks.pop(task_id, None)
+ return failed
+ return task
+
+
+async def _run_inference(task_id: str, *args, **kwargs) -> None:
+ _live_tasks.add(task_id)
+ beat = asyncio.create_task(_heartbeat(task_id))
+ try:
+ await _run_job(task_id, *args, **kwargs)
+ finally:
+ beat.cancel()
+ _live_tasks.discard(task_id)
+ _task_locks.pop(task_id, None)
+ _recycle_if_bloated(task_id)
+
+
+def _recycle_if_bloated(task_id: str) -> None:
+ """See workers/model-trellis2's identical function for the full rationale:
+ restart an idle instance before its ratcheted memory OOM-kills a job."""
+ global _draining, _restart_signalled
+ sample = read_memory()
+ if sample is not None:
+ log.info("[%s] memory after job: %s", task_id, sample.describe())
+ if not _draining:
+ if not should_recycle(sample, _memory_baseline):
+ return
+ _draining = True
+ log.warning(
+ "recycling instance: memory %s, up from %s after load; draining %d queued job(s) first",
+ sample.describe(), _memory_baseline.describe() if _memory_baseline else "unknown", len(_live_tasks),
+ )
+ if _live_tasks or _restart_signalled:
+ return
+ _restart_signalled = True
+ log.warning("recycling instance: idle, restarting now")
+ signal.raise_signal(signal.SIGTERM)
+
+
+def _release_gpu_memory() -> None:
+ gc.collect()
+ if torch.cuda.is_available():
+ torch.cuda.empty_cache()
+ torch.cuda.ipc_collect()
+ trim_heap()
+
+
+def _get_single_pipeline():
+ """Lazily load Pixal3D's single-view pipeline (inference.py's own loader)."""
+ global _single_pipeline, _memory_baseline
+ if _single_pipeline is not None:
+ return _single_pipeline
+ import inference as sv_ref
+
+ log.info("Loading Pixal3D single-view pipeline from %s", CONFIG_DIR)
+ _single_pipeline = sv_ref.init_pipeline(model_path=CONFIG_DIR, low_vram=LOW_VRAM)
+ trim_heap()
+ if _memory_baseline is None:
+ _memory_baseline = read_memory()
+ log.info("Pixal3D single-view pipeline ready")
+ return _single_pipeline
+
+
+def _get_mv_pipeline():
+ """Lazily load Pixal3D's multi-view pipeline (inference_mv.py's own loader)."""
+ global _mv_pipeline
+ if _mv_pipeline is not None:
+ return _mv_pipeline
+ import inference_mv as mv_ref
+
+ log.info("Loading Pixal3D multi-view pipeline from %s", CONFIG_DIR)
+ _mv_pipeline = mv_ref.init_pipeline(model_path=CONFIG_DIR, config_file="pipeline_mv.json", low_vram=LOW_VRAM)
+ trim_heap()
+ log.info("Pixal3D multi-view pipeline ready")
+ return _mv_pipeline
+
+
+def _get_moge_model():
+ """Lazily load the MoGe-2 camera estimator, shared by both pipelines."""
+ global _moge_model
+ if _moge_model is not None:
+ return _moge_model
+ import inference as sv_ref
+
+ log.info("Loading MoGe-2 camera estimator")
+ _moge_model = sv_ref.load_moge_model(device="cuda" if torch.cuda.is_available() else "cpu")
+ log.info("MoGe-2 ready")
+ return _moge_model
+
+
+def _estimate_camera_params(image: Image.Image, mesh_scale: float = 1.0) -> dict:
+ """camera_angle_x / distance / mesh_scale for one photo, via MoGe-2.
+
+ Pixal3D's own get_camera_params_wild_moge takes a file path (its single-
+ view script always has one on disk already); an in-memory photo is
+ written to a temp PNG first, exactly as that script does for its own
+ preprocessed image.
+ """
+ import inference as sv_ref
+
+ moge_model = _get_moge_model()
+ with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as tmp:
+ tmp_path = tmp.name
+ try:
+ image.convert("RGB").save(tmp_path)
+ return sv_ref.get_camera_params_wild_moge(
+ tmp_path, moge_model, device="cuda" if torch.cuda.is_available() else "cpu",
+ mesh_scale=mesh_scale, extend_pixel=0, image_resolution=512,
+ )
+ finally:
+ os.remove(tmp_path)
+
+
+def _square_crop(image: Image.Image) -> Image.Image:
+ """Center-crop to a square. Pixal3D's multi-view conditioning tensors are
+ built with a plain resize (to_cond_tensor), which assumes a square,
+ well-framed input the way its own training renders always were."""
+ w, h = image.size
+ if w == h:
+ return image
+ side = min(w, h)
+ left = (w - side) // 2
+ top = (h - side) // 2
+ return image.crop((left, top, left + side, top + side))
+
+
+def _generate_single(
+ image: Image.Image, resolution: int, seed: Optional[int], texture_size: Optional[int], decimation_target: Optional[int]
+) -> tuple[bytes, str, bool]:
+ """One synchronous single-photo generation, mirroring inference.py's run_inference."""
+ import o_voxel
+
+ pipeline = _get_single_pipeline()
+ image_preprocessed = pipeline.preprocess_image(image)
+ camera_params = _estimate_camera_params(image_preprocessed)
+ torch.manual_seed(seed if seed is not None else 42)
+ mesh_list, (_shape_slat, _tex_slat, res) = pipeline.run(
+ image_preprocessed,
+ camera_params=camera_params,
+ seed=seed if seed is not None else 42,
+ preprocess_image=False,
+ return_latent=True,
+ pipeline_type=PIPELINE_TYPES[resolution],
+ max_num_tokens=49152,
+ )
+ return _mesh_to_glb(mesh_list[0], pipeline.pbr_attr_layout, res, resolution, texture_size, decimation_target)
+
+
+def _generate_multiview(
+ images: list[Image.Image],
+ view_labels: list[Optional[str]],
+ resolution: int,
+ seed: Optional[int],
+ texture_size: Optional[int],
+ decimation_target: Optional[int],
+) -> tuple[bytes, str, bool]:
+ """One synchronous multi-view generation.
+
+ No real camera data exists for these photos, so camera_rig turns the
+ labels (or an even spacing when a slot carries none) into azimuths, a
+ shared camera is estimated once from whichever photo lands at azimuth 0
+ (Pixal3D requires frame 0 to be the canonical front view -- see
+ camera_rig.py's module docstring), and the view bundle is built in the
+ exact shape inference_mv.py's load_views() hands pipeline.run_mv.
+ """
+ import inference_mv as mv_ref
+ import numpy as np
+
+ pipeline = _get_mv_pipeline()
+ azimuths = camera_rig.resolve_azimuths(view_labels)
+ front_idx = azimuths.index(0.0) if 0.0 in azimuths else 0
+ order = [front_idx] + [i for i in range(len(images)) if i != front_idx]
+ ordered_images = [_square_crop(images[i]) for i in order]
+ ordered_azimuths = [azimuths[i] for i in order]
+ ordered_labels = [view_labels[i] for i in order]
+
+ camera_params = _estimate_camera_params(ordered_images[0])
+ distance = camera_params["distance"]
+ rig = [camera_rig.transform_matrix_for_azimuth(az, distance) for az in ordered_azimuths]
+
+ rembg = mv_ref.make_rembg(pipeline)
+ matted = []
+ for img in ordered_images:
+ alpha = np.array(img.getchannel("A")) if img.mode == "RGBA" else None
+ if alpha is not None and not np.all(alpha == 255):
+ matted.append(img.convert("RGBA"))
+ else:
+ matted.append(rembg(img).convert("RGBA"))
+
+ views = {
+ "images": {
+ size: torch.stack([mv_ref.to_cond_tensor(im, size) for im in matted], dim=0)[None]
+ for size in (512, 1024)
+ },
+ "camera_angle_x": torch.tensor([[camera_params["camera_angle_x"]] * len(matted)], dtype=torch.float32),
+ "camera_distance": torch.tensor([[distance] * len(matted)], dtype=torch.float32),
+ "transform_matrix": torch.tensor([rig], dtype=torch.float32),
+ "mesh_scale": camera_params["mesh_scale"],
+ "view_names": [label or f"view{i}" for i, label in enumerate(ordered_labels)],
+ }
+ mv_ref.check_main_view(views)
+
+ torch.manual_seed(seed if seed is not None else 42)
+ mesh_list, (_shape_slat, _tex_slat, res) = pipeline.run_mv(
+ views,
+ seed=seed if seed is not None else 42,
+ return_latent=True,
+ pipeline_type=PIPELINE_TYPES[resolution],
+ max_num_tokens=49152,
+ )
+ return _mesh_to_glb(mesh_list[0], pipeline.pbr_attr_layout, res, resolution, texture_size, decimation_target)
+
+
+def _mesh_to_glb(mesh, attr_layout, grid_size, resolution, texture_size, decimation_target) -> tuple[bytes, str, bool]:
+ """Bake a Pixal3D mesh to a packed GLB. Shared tail of both generate paths."""
+ import o_voxel
+ import numpy as np
+
+ bake = bake_params(resolution, texture_size, decimation_target)
+ glb = o_voxel.postprocess.to_glb(
+ vertices=mesh.vertices,
+ faces=mesh.faces,
+ attr_volume=mesh.attrs,
+ coords=mesh.coords,
+ attr_layout=attr_layout,
+ grid_size=grid_size,
+ aabb=[[-0.5, -0.5, -0.5], [0.5, 0.5, 0.5]],
+ decimation_target=bake["decimation_target"],
+ texture_size=bake["texture_size"],
+ remesh=True,
+ remesh_band=1,
+ remesh_project=0,
+ )
+ # Pixal3D's own reference scripts apply this exact rotation after to_glb
+ # to align the output with the platform's forward/up convention.
+ rot = np.array(
+ [[-1, 0, 0, 0], [0, 0, -1, 0], [0, -1, 0, 0], [0, 0, 0, 1]], dtype=np.float64
+ )
+ glb.apply_transform(rot)
+ alpha_mode = glb_pack.blend_if_translucent(glb)
+ raw = glb.export(file_type="glb", extension_webp=True)
+ packed_bytes, packed = glb_pack.compress(raw)
+ return packed_bytes, alpha_mode, packed
+
+
+async def _run_job(
+ task_id: str,
+ images: list[str],
+ view_labels: list[Optional[str]] | None = None,
+ fill_other_sides: bool = False,
+ resolution: int | None = None,
+ tier: str | None = None,
+ seed: int | None = None,
+ texture_size: int | None = None,
+ decimation_target: int | None = None,
+) -> None:
+ if _load_error:
+ await _update_task(task_id, status="failed", error=f"weights unavailable: {_load_error}")
+ return
+ try:
+ await asyncio.wait_for(_weights_ready.wait(), timeout=900)
+ except asyncio.TimeoutError:
+ await _update_task(task_id, status="failed", error="weights not ready (staging timed out)")
+ return
+ if _load_error:
+ await _update_task(task_id, status="failed", error=f"weights unavailable: {_load_error}")
+ return
+
+ requested = clamp_to_ceiling(resolve_resolution(resolution, tier), MAX_RESOLUTION)
+ labels = list(view_labels) if view_labels else [None] * len(images)
+
+ async with _sem:
+ await _update_task(task_id, status="running", resolution=requested)
+ loop = asyncio.get_event_loop()
+ t0 = time.time()
+ try:
+ decoded = [await loop.run_in_executor(None, _decode_image, src) for src in images]
+
+ served = requested
+ while True:
+ try:
+ if len(decoded) == 1 and fill_other_sides:
+ import mv_adapter_fill
+
+ extra = await loop.run_in_executor(None, mv_adapter_fill.synthesize_other_sides, decoded[0])
+ all_images = [decoded[0]] + extra
+ all_labels = ["front", "right", "back", "left"]
+ result = await loop.run_in_executor(
+ None, _generate_multiview, all_images, all_labels, served, seed, texture_size, decimation_target
+ )
+ views_used = len(all_images)
+ elif len(decoded) == 1:
+ result = await loop.run_in_executor(
+ None, _generate_single, decoded[0], served, seed, texture_size, decimation_target
+ )
+ views_used = 1
+ else:
+ result = await loop.run_in_executor(
+ None, _generate_multiview, decoded, labels, served, seed, texture_size, decimation_target
+ )
+ views_used = len(decoded)
+ break
+ except torch.cuda.OutOfMemoryError:
+ await loop.run_in_executor(None, _release_gpu_memory)
+ smaller = step_down(served)
+ if smaller is None:
+ raise
+ log.warning("[%s] out of GPU memory at %d; retrying at %d", task_id, served, smaller)
+ served = smaller
+ glb_bytes, alpha_mode, packed = result
+
+ if _using_gcs():
+ blob_name = f"raw-meshes/pixal3d/{task_id}.glb"
+ blob = _bucket.blob(blob_name)
+ await loop.run_in_executor(
+ None, lambda: blob.upload_from_string(glb_bytes, content_type="model/gltf-binary")
+ )
+ result_fields = {"result_gcs_url": f"https://storage.googleapis.com/{GCS_BUCKET}/{blob_name}"}
+ result_label = result_fields["result_gcs_url"]
+ else:
+ result_path = await loop.run_in_executor(None, _get_local_storage().write_result, task_id, glb_bytes)
+ result_fields = {"result_url": f"/results/{task_id}.glb", "result_path": str(result_path)}
+ result_label = str(result_path)
+
+ elapsed = time.time() - t0
+ await _update_task(
+ task_id,
+ status="done",
+ **result_fields,
+ views_used=views_used,
+ resolution=requested,
+ resolution_served=served,
+ alpha_mode=alpha_mode,
+ packed=packed,
+ bytes=len(glb_bytes),
+ elapsed_ms=int(elapsed * 1000),
+ )
+ log.info(
+ "[%s] done in %.1fs (views=%d resolution=%d served=%d alpha=%s packed=%s) %d bytes -> %s",
+ task_id, elapsed, views_used, requested, served, alpha_mode, packed, len(glb_bytes), result_label,
+ )
+
+ except ImageSourceError as exc:
+ log.warning("[%s] image source rejected: %s", task_id, exc)
+ await _update_task(task_id, status="failed", error=str(exc), elapsed_ms=int((time.time() - t0) * 1000))
+ except Exception as exc:
+ await _update_task(
+ task_id, status="failed", error=safe_error(exc, context=f"[{task_id}] inference"),
+ elapsed_ms=int((time.time() - t0) * 1000),
+ )
+ finally:
+ await loop.run_in_executor(None, _release_gpu_memory)
+
+
+class InferRequest(BaseModel):
+ images: list[str] = Field(..., min_length=1, max_length=4)
+ # "front" | "back" | "left" | "right" | null per slot, same order as images.
+ # A slot without a recognized label spreads evenly among the unlabeled ones.
+ view_labels: list[str | None] | None = None
+ # Only valid with exactly one image: synthesize the other three azimuths
+ # with MV-Adapter before running the multi-view path.
+ fill_other_sides: bool = False
+ body_type: str = "neutral"
+ job_id: str | None = None
+ resolution: int | None = None
+ tier: str | None = None
+ seed: int | None = None
+ texture_size: int | None = None
+ decimation_target: int | None = None
+
+
[email protected]("/infer", status_code=202)
+async def infer(body: InferRequest, background_tasks: BackgroundTasks, authorization: str = Header(...)) -> dict:
+ _require_api_key(authorization)
+ if _load_error:
+ raise HTTPException(status_code=503, detail=f"weights unavailable: {_load_error}")
+ if _draining:
+ raise HTTPException(status_code=503, detail="instance restarting to reclaim memory; retry shortly")
+ if body.fill_other_sides and len(body.images) != 1:
+ raise HTTPException(status_code=400, detail="fill_other_sides requires exactly one image")
+ if body.view_labels is not None and len(body.view_labels) != len(body.images):
+ raise HTTPException(status_code=400, detail="view_labels must have one entry per image")
+
+ task_id = str(uuid.uuid4())
+ await _update_task(task_id, status="queued", model="pixal3d")
+ background_tasks.add_task(
+ _run_inference,
+ task_id,
+ body.images,
+ body.view_labels,
+ body.fill_other_sides,
+ body.resolution,
+ body.tier,
+ body.seed,
+ body.texture_size,
+ body.decimation_target,
+ )
+ return {"task_id": task_id, "status": "queued"}
+
+
[email protected]("/tasks/{task_id}")
+async def get_task(task_id: str, authorization: str = Header(...)) -> dict:
+ _require_api_key(authorization)
+ return await _resolve_task(task_id)
+
+
[email protected]("/results/{task_id}.glb")
+async def get_result(task_id: str, authorization: str = Header(...)):
+ _require_api_key(authorization)
+ if _using_gcs():
+ raise HTTPException(status_code=404, detail="local result storage is not active")
+ try:
+ path = _get_local_storage().result_path(task_id)
+ except ValueError as exc:
+ raise HTTPException(status_code=404, detail="result not found") from exc
+ if not path.is_file():
+ raise HTTPException(status_code=404, detail="result not found")
+ return FileResponse(path, media_type="model/gltf-binary", filename=path.name)
+
+
+async def root() -> dict:
+ return {
+ "service": "model-pixal3d",
+ "model": "pixal3d",
+ "ready": bool(_weights_ready and _weights_ready.is_set()),
+ "endpoints": ["POST /infer", "GET /tasks/{task_id}", "GET /results/{task_id}.glb", "GET /health"],
+ }
+
+
+async def health(response: Response) -> dict:
+ dead = _load_error is not None
+ if dead:
+ response.status_code = 503
+ return {
+ "ok": not dead,
+ "model": "pixal3d",
+ "gpu_available": torch.cuda.is_available(),
+ "gpu_name": torch.cuda.get_device_name(0) if torch.cuda.is_available() else None,
+ "single_pipeline_loaded": _single_pipeline is not None,
+ "mv_pipeline_loaded": _mv_pipeline is not None,
+ "weights_ready": bool(_weights_ready and _weights_ready.is_set()),
+ "load_error": _load_error,
+ "load_attempts": _load_attempts,
+ "draining": _draining,
+ "resolutions": [r for r in RESOLUTIONS if r <= MAX_RESOLUTION],
+ "default_resolution": DEFAULT_RESOLUTION,
+ "max_images": 4,
+ "output_backend": "gcs" if _using_gcs() else "local",
+ "output_dir": None if _using_gcs() else str(_get_local_storage().output_dir),
+ }
diff --git a/workers/model-pixal3d/mv_adapter_fill.py b/workers/model-pixal3d/mv_adapter_fill.py
new file mode 100644
index 000000000..a9844e13d
--- /dev/null
+++ b/workers/model-pixal3d/mv_adapter_fill.py
@@ -0,0 +1,122 @@
+"""MV-Adapter "fill in the other sides": one photo in, three synthesized views out.
+
+Wraps huanngzh/MV-Adapter's own reference script
+(github.com/huanngzh/MV-Adapter, Apache-2.0; adapter weights on the Hub are
+also Apache-2.0; its SDXL base, stabilityai/stable-diffusion-xl-base-1.0, is
+CreativeML Open RAIL++-M, which permits commercial hosting) rather than
+reimplementing the SDXL multi-view diffusion pipeline. `prepare_pipeline` and
+`run_pipeline` are imported unmodified from the vendored checkout
+(MVADAPTER_SRC) and called exactly as the script's own `__main__` block does.
+
+This is the order's optional view-synthesis rung: Forge's single-photo
+"Match my photo" lane only reaches this module when the caller asks
+fill_other_sides=true. The default single-image lane and the given-multi-view
+lane (main.py's _generate_single / _generate_multiview) never import it.
+
+Background removal is deliberately NOT done here. Every image main.py decodes
+is already RGBA (see _decode_image), so run_pipeline's own `reference_image.
+mode == "RGBA"` branch always triggers upstream's preprocess_image (bounding-
+box crop to content, composite onto neutral gray) without a second BiRefNet
+load; the real alpha matte each synthesized view needs for reconstruction
+comes afterward, from the multi-view Pixal3D pipeline's own rembg_model, the
+same way it mattes every other multi-view input (see main.py's
+_generate_multiview).
+"""
+
+from __future__ import annotations
+
+import os
+
+import torch
+from PIL import Image
+
+MVADAPTER_SRC = os.environ.get("MVADAPTER_SRC", "/opt/mvadapter-src")
+MVADAPTER_WEIGHTS_DIR = os.environ.get("MVADAPTER_WEIGHTS_DIR", "/weights/mvadapter")
+LOW_VRAM = os.environ.get("LOW_VRAM", "1") != "0"
+
+# front=0, right=90, back=180, left=270: the same convention camera_rig.py uses.
+AZIMUTH_DEG = [0, 90, 180, 270]
+HEIGHT = WIDTH = 768
+NUM_INFERENCE_STEPS = 30
+GUIDANCE_SCALE = 3.0
+
+_pipe = None
+
+
+def _resolve(name: str, hub_fallback: str) -> str:
+ """A locally-staged copy if stage_weights.sh ran, else the Hub id."""
+ local = os.path.join(MVADAPTER_WEIGHTS_DIR, name)
+ return local if os.path.isdir(local) else hub_fallback
+
+
+def _move(pipe, device: str) -> None:
+ pipe.to(device=device)
+ # prepare_pipeline() moves cond_encoder separately from the rest of the
+ # pipeline's components, so a device swap must do the same.
+ pipe.cond_encoder.to(device=device)
+
+
+def _get_pipeline():
+ global _pipe
+ if _pipe is not None:
+ return _pipe
+ import sys
+
+ if MVADAPTER_SRC not in sys.path:
+ sys.path.insert(0, MVADAPTER_SRC)
+ from scripts.inference_i2mv_sdxl import prepare_pipeline
+
+ device = "cuda" if torch.cuda.is_available() else "cpu"
+ _pipe = prepare_pipeline(
+ base_model=_resolve("sdxl-base", "stabilityai/stable-diffusion-xl-base-1.0"),
+ vae_model=_resolve("sdxl-vae-fix", "madebyollin/sdxl-vae-fp16-fix"),
+ unet_model=None,
+ lora_model=None,
+ adapter_path=_resolve("mv-adapter", "huanngzh/mv-adapter"),
+ scheduler=None,
+ num_views=len(AZIMUTH_DEG),
+ device="cpu" if LOW_VRAM else device,
+ dtype=torch.float16 if device == "cuda" else torch.float32,
+ )
+ if LOW_VRAM:
+ _move(_pipe, "cpu")
+ return _pipe
+
+
+def synthesize_other_sides(image: Image.Image) -> list[Image.Image]:
+ """Return the right, back and left views synthesized from one front photo.
+
+ `image` is the caller's own photo, treated as the front view (azimuth 0);
+ MV-Adapter also re-synthesizes a front view of its own, which is discarded
+ in favor of the real photo the caller already has.
+ """
+ import sys
+
+ if MVADAPTER_SRC not in sys.path:
+ sys.path.insert(0, MVADAPTER_SRC)
+ from scripts.inference_i2mv_sdxl import run_pipeline
+
+ pipe = _get_pipeline()
+ device = "cuda" if torch.cuda.is_available() else "cpu"
+ if LOW_VRAM:
+ _move(pipe, device)
+ try:
+ images, _reference = run_pipeline(
+ pipe,
+ num_views=len(AZIMUTH_DEG),
+ text="",
+ image=image.convert("RGBA"),
+ height=HEIGHT,
+ width=WIDTH,
+ num_inference_steps=NUM_INFERENCE_STEPS,
+ guidance_scale=GUIDANCE_SCALE,
+ seed=-1,
+ device=device,
+ azimuth_deg=AZIMUTH_DEG,
+ )
+ finally:
+ if LOW_VRAM:
+ _move(pipe, "cpu")
+ if torch.cuda.is_available():
+ torch.cuda.empty_cache()
+ return images[1:4]
diff --git a/workers/model-pixal3d/pipeline_config.py b/workers/model-pixal3d/pipeline_config.py
new file mode 100644
index 000000000..56069dec9
--- /dev/null
+++ b/workers/model-pixal3d/pipeline_config.py
@@ -0,0 +1,112 @@
+"""Rewrite Pixal3D's pipeline.json / pipeline_mv.json so every weight loads locally.
+
+Pure stdlib, no torch, so it unit tests anywhere (test_pipeline_config.py).
+
+Upstream's two configs (fetched from TencentARC/Pixal3D on Hugging Face) each
+reach out to two places we do not want at serve time, and one of them is a
+licence problem:
+
+ * `image_cond_model` names `facebook/dinov3-vitl16-pretrain-lvd1689m`, which
+ is gated on its original repo and would block a cold start on an
+ interactive Hub license click. Pixal3D's own `inference.py` additionally
+ rebuilds the four per-stage conditioners it actually uses from a hardcoded
+ Hub id rather than this key, so both the declared key and the hardcoded
+ id are pointed at the same local, pre-staged copy of the ungated mirror
+ `camenduru/dinov3-vitl16-pretrain-lvd1689m` that workers/model-trellis2
+ already ships (same DINOv3 weights, same license terms).
+ * `rembg_model` names briaai/RMBG-2.0, which is licensed CC BY-NC and cannot
+ ship in a commercial product. It is replaced with ZhengPeng7/BiRefNet
+ (MIT), which the same BiRefNet wrapper class loads unchanged.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Iterable
+
+# Sub-trees of the staged weights, written by stage_weights.sh.
+DINOV3_DIR = "dinov3"
+BIREFNET_DIR = "birefnet"
+
+# ckpts/ filenames exactly as published on TencentARC/Pixal3D. The *_mv
+# variants are the multi-view flow models; the two decoders and the
+# sparse-structure decoder are shared between the single- and multi-view
+# pipelines (pipeline.json and pipeline_mv.json both name the unsuffixed path).
+CKPT_FILES = (
+ "ss_dec_conv3d_16l8_fp16",
+ "ss_flow_img_dit_1_3B_64_bf16",
+ "ss_flow_img_dit_1_3B_64_bf16_mv",
+ "shape_dec_next_dc_f16c32_fp16",
+ "slat_flow_img2shape_dit_1_3B_512_bf16",
+ "slat_flow_img2shape_dit_1_3B_512_bf16_mv",
+ "slat_flow_img2shape_dit_1_3B_1024_bf16",
+ "slat_flow_img2shape_dit_1_3B_1024_bf16_mv",
+ "tex_dec_next_dc_f16c32_fp16",
+ "slat_flow_imgshape2tex_dit_1_3B_1024_bf16",
+ "slat_flow_imgshape2tex_dit_1_3B_1024_bf16_mv",
+)
+
+REQUIRED_PATHS = (
+ "pipeline.json",
+ "pipeline_mv.json",
+ *(f"ckpts/{name}.safetensors" for name in CKPT_FILES),
+ *(f"ckpts/{name}.json" for name in CKPT_FILES),
+ f"{DINOV3_DIR}/model.safetensors",
+ f"{DINOV3_DIR}/config.json",
+ f"{BIREFNET_DIR}/model.safetensors",
+ f"{BIREFNET_DIR}/config.json",
+)
+
+
+def missing_weights(present: Iterable[str]) -> list[str]:
+ """Every file either pipeline needs that is not in `present` (relative names)."""
+ have = set(present)
+ return [rel for rel in REQUIRED_PATHS if rel not in have]
+
+
+def localize(config: dict, aux_root: str | os.PathLike[str]) -> dict:
+ """Return a copy of `config` that loads the conditioner and matte locally.
+
+ `aux_root` holds the dinov3/ and birefnet/ directories (shared by the
+ single- and multi-view configs), small enough to keep on local disk for
+ the instance's life.
+ """
+ base = str(Path(aux_root))
+ out = json.loads(json.dumps(config))
+ args = out["args"]
+ args["image_cond_model"]["args"]["model_name"] = f"{base}/{DINOV3_DIR}"
+ args["rembg_model"] = {
+ "name": "BiRefNet",
+ "args": {"model_name": f"{base}/{BIREFNET_DIR}"},
+ }
+ return out
+
+
+def write_local_config(
+ pipeline_json: str, aux_root: str | os.PathLike[str], out_path: str | os.PathLike[str]
+) -> Path:
+ """Write a localized copy of a pipeline json string to `out_path`."""
+ target = Path(out_path)
+ target.parent.mkdir(parents=True, exist_ok=True)
+ target.write_text(json.dumps(localize(json.loads(pipeline_json), aux_root), indent=2))
+ return target
+
+
+def link_weight_tree(root: str | os.PathLike[str], out_dir: str | os.PathLike[str]) -> None:
+ """Symlink each top-level entry of a local weight tree into `out_dir`.
+
+ The pipeline resolves every model as `<config dir>/<relative name>`, so a
+ config dir holding the localized pipeline.json(s) plus these links loads
+ straight from a mounted or pre-staged tree.
+ """
+ source = Path(root)
+ target = Path(out_dir)
+ target.mkdir(parents=True, exist_ok=True)
+ for entry in source.iterdir():
+ if entry.name in ("pipeline.json", "pipeline_mv.json"):
+ continue
+ link = target / entry.name
+ if not link.exists() and not link.is_symlink():
+ link.symlink_to(entry.resolve())
diff --git a/workers/model-pixal3d/request_policy.py b/workers/model-pixal3d/request_policy.py
new file mode 100644
index 000000000..3d0686944
--- /dev/null
+++ b/workers/model-pixal3d/request_policy.py
@@ -0,0 +1,196 @@
+"""Request policy for the Pixal3D worker: resolution tiers and transient-fetch retry.
+
+Free of torch, CUDA and the Pixal3D source tree so the decisions that shape
+every generation import and unit test on any machine (see test_request_policy.py).
+main.py imports every public name here; nothing in this file touches the GPU.
+
+Two policies live here:
+
+ 1. Resolution resolution. Pixal3D only exposes two cascade pipelines (unlike
+ TRELLIS.2's three-tier grid): 1024_cascade and 1536_cascade. A caller sends
+ an optional `resolution` (1024 or 1536) and/or a named `tier`; this module
+ turns that into the pipeline type, texture size and decimation target the
+ worker runs with, and says how to step down when the GPU cannot hold the
+ requested size.
+ 2. Transient-fetch retry. Caller-supplied image URLs are fetched over the
+ public internet, where a single read timeout would otherwise fail a whole
+ generation. `call_with_retry` re-runs the fetch for errors worth retrying
+ and gives up at once on the ones that are not.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+import httpx
+
+# Pixal3D's own inference scripts only ever build a "<resolution>_cascade"
+# pipeline type for resolution in {1024, 1536} (inference.py / inference_mv.py:
+# `f"{resolution if resolution > 0 else (1024 if low_vram else 1536)}_cascade"`).
+# There is no bare 512 lane the way TRELLIS.2 has one.
+RESOLUTIONS = (1024, 1536)
+DEFAULT_RESOLUTION = 1536
+LOW_VRAM_RESOLUTION = 1024
+
+PIPELINE_TYPES = {
+ 1024: "1024_cascade",
+ 1536: "1536_cascade",
+}
+
+# What each resolution bakes. Texture size must stay a power of two (the bake
+# builds a mip stack); the decimation target is the face budget handed to the
+# mesh simplifier before UV unwrapping.
+RESOLUTION_PRESETS = {
+ 1024: {"texture_size": 2048, "decimation_target": 700_000},
+ 1536: {"texture_size": 4096, "decimation_target": 1_000_000},
+}
+
+# The forge lanes already speak quality tiers; map them onto the resolutions so a
+# tier request and a resolution request land on the same presets. Pixal3D has no
+# "draft" lane of its own: the fastest tier still runs the smaller cascade.
+TIER_RESOLUTION = {
+ "draft": 1024,
+ "standard": 1024,
+ "high": 1536,
+ "max": 1536,
+}
+
+TEXTURE_SIZE_MIN = 512
+TEXTURE_SIZE_MAX = 4096
+DECIMATION_MIN = 50_000
+DECIMATION_MAX = 1_500_000
+
+
+def normalize_tier(tier: Optional[str]) -> Optional[str]:
+ """Lowercase and trim a caller's tier string, or None when none was sent."""
+ if tier is None:
+ return None
+ key = str(tier).strip().lower()
+ return key or None
+
+
+def resolve_resolution(resolution: Optional[int], tier: Optional[str] = None) -> int:
+ """The grid resolution to run at.
+
+ An explicit `resolution` wins and snaps to the nearest supported size (a
+ caller asking for 1200 gets 1024, a 2000 gets 1536). With none, the named
+ tier decides, and with neither the platform default applies. An
+ unparseable value falls back to the default rather than failing the job.
+ """
+ if resolution is not None:
+ try:
+ wanted = int(resolution)
+ except (TypeError, ValueError):
+ return DEFAULT_RESOLUTION
+ return min(RESOLUTIONS, key=lambda r: (abs(r - wanted), r))
+ return TIER_RESOLUTION.get(normalize_tier(tier) or "", DEFAULT_RESOLUTION)
+
+
+def clamp_to_ceiling(resolution: int, ceiling: Optional[int]) -> int:
+ """Cap a resolution at what this deployment's GPU class can serve."""
+ if not ceiling:
+ return resolution
+ allowed = [r for r in RESOLUTIONS if r <= ceiling]
+ return min(resolution, max(allowed)) if allowed else RESOLUTIONS[0]
+
+
+def step_down(resolution: int) -> Optional[int]:
+ """The next smaller resolution to retry at after an out-of-memory failure."""
+ smaller = [r for r in RESOLUTIONS if r < resolution]
+ return max(smaller) if smaller else None
+
+
+def bake_params(
+ resolution: int,
+ texture_size: Optional[int] = None,
+ decimation_target: Optional[int] = None,
+) -> dict:
+ """The clamped bake parameters for a resolution plus optional overrides.
+
+ texture_size snaps DOWN to a power of two inside the envelope: the texture
+ bake hard-fails on any other extent. Unparseable overrides fall back to the
+ resolution's preset.
+ """
+ preset = RESOLUTION_PRESETS[resolution]
+
+ def number(raw, fallback, lo, hi):
+ if raw is None:
+ return fallback
+ try:
+ value = int(raw)
+ except (TypeError, ValueError):
+ return fallback
+ return max(lo, min(hi, value))
+
+ tex = number(texture_size, preset["texture_size"], TEXTURE_SIZE_MIN, TEXTURE_SIZE_MAX)
+ tex = 1 << (tex.bit_length() - 1)
+ return {
+ "texture_size": tex,
+ "decimation_target": number(
+ decimation_target, preset["decimation_target"], DECIMATION_MIN, DECIMATION_MAX
+ ),
+ }
+
+
+# Total attempts (not extra retries) for one caller-supplied image URL, and the
+# first backoff gap. Three attempts at 1s then 2s costs at most a few seconds of
+# an already-asynchronous job, and covers the single-blip read timeouts that
+# were failing whole generations from the public internet.
+FETCH_ATTEMPTS = 3
+FETCH_RETRY_BASE_SECONDS = 1.0
+
+# Upstream status codes worth a second try. Everything else (404, 403, 400) is a
+# statement about the URL itself and will fail identically on every attempt.
+_RETRYABLE_STATUS = frozenset({408, 425, 429, 500, 502, 503, 504})
+
+
+def retry_delays(
+ attempts: int = FETCH_ATTEMPTS, base: float = FETCH_RETRY_BASE_SECONDS
+) -> list[float]:
+ """Exponential backoff gaps between attempts (one fewer than `attempts`)."""
+ return [base * (2 ** i) for i in range(max(0, attempts - 1))]
+
+
+def is_transient_fetch_error(exc: BaseException) -> bool:
+ """True when re-fetching the same URL could plausibly succeed.
+
+ Timeouts and connection-level failures are the blips this exists for. An
+ HTTP error is transient only for the status codes above; a 404 is not going
+ to become a 200 on the next attempt.
+ """
+ if isinstance(exc, httpx.HTTPStatusError):
+ return exc.response.status_code in _RETRYABLE_STATUS
+ return isinstance(
+ exc, (httpx.TimeoutException, httpx.NetworkError, httpx.RemoteProtocolError)
+ )
+
+
+def call_with_retry(
+ fn: Callable[[], object],
+ *,
+ attempts: int = FETCH_ATTEMPTS,
+ should_retry: Callable[[BaseException], bool] = is_transient_fetch_error,
+ sleep: Callable[[float], None],
+ on_retry: Optional[Callable[[int, float, BaseException], None]] = None,
+):
+ """Call `fn`, retrying with exponential backoff while `should_retry` holds.
+
+ Re-raises the last exception once the attempts are spent or the error is not
+ retryable. `sleep` is injected so the policy stays testable without wall
+ clock time; `on_retry` receives (attempt_number, delay, exception) for
+ logging.
+ """
+ delays = retry_delays(attempts)
+ last: BaseException
+ for index in range(max(1, attempts)):
+ try:
+ return fn()
+ except BaseException as exc: # noqa: BLE001 - re-raised below after the budget
+ last = exc
+ if index >= len(delays) or not should_retry(exc):
+ raise
+ delay = delays[index]
+ if on_retry:
+ on_retry(index + 1, delay, exc)
+ sleep(delay)
+ raise last
diff --git a/workers/model-pixal3d/stage_weights.sh b/workers/model-pixal3d/stage_weights.sh
new file mode 100755
index 000000000..4ee4adf89
--- /dev/null
+++ b/workers/model-pixal3d/stage_weights.sh
@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# Stage every weight Pixal3D (and its optional MV-Adapter rung) needs into
+# gs://three-ws-model-weights, streaming straight from the source to the
+# bucket (no local disk). Idempotent: an object that already exists at the
+# expected size is skipped. Mirrors workers/model-trellis2/stage_weights.sh.
+#
+# workers/model-pixal3d/stage_weights.sh
+#
+# Layout written (the worker's WEIGHTS_GCS_URI points at the first prefix):
+# gs://<bucket>/pixal3d/ TencentARC/Pixal3D (MIT): pipeline.json,
+# pipeline_mv.json, ckpts/*
+# gs://<bucket>/pixal3d/dinov3/ camenduru/dinov3-vitl16-pretrain-lvd1689m,
+# the same ungated DINOv3 ViT-L/16 mirror
+# workers/model-trellis2 already stages
+# (the facebook/ original is gated).
+# gs://<bucket>/pixal3d/birefnet/ ZhengPeng7/BiRefNet (MIT), the background
+# matte. Replaces upstream's default,
+# RMBG-2.0, whose CC BY-NC licence excludes
+# commercial use.
+# gs://<bucket>/pixal3d-mvadapter/ the optional "fill in the other sides"
+# sdxl-base/ rung (mv_adapter_fill.py), only read when
+# sdxl-vae-fix/ a caller sets fill_other_sides=true:
+# mv-adapter/ stabilityai/stable-diffusion-xl-base-1.0
+# (CreativeML Open RAIL++-M, permits
+# commercial hosting), default-precision
+# safetensors only (the fp16-variant
+# files are skipped; MV-Adapter casts to
+# fp16 itself after loading)
+# madebyollin/sdxl-vae-fp16-fix (MIT)
+# huanngzh/mv-adapter (Apache-2.0)
+set -euo pipefail
+
+BUCKET="${WEIGHTS_BUCKET:-three-ws-model-weights}"
+PREFIX="${WEIGHTS_PREFIX:-pixal3d}"
+MVADAPTER_PREFIX="${MVADAPTER_WEIGHTS_PREFIX:-pixal3d-mvadapter}"
+DEST="gs://${BUCKET}/${PREFIX}"
+MV_DEST="gs://${BUCKET}/${MVADAPTER_PREFIX}"
+AUTH=()
+if [[ -n "${HF_TOKEN:-}" ]]; then AUTH=(-H "Authorization: Bearer ${HF_TOKEN}"); fi
+
+list_repo() { # <repo> -> "path size" lines
+ curl -fsS "${AUTH[@]}" "https://huggingface.co/api/models/$1?blobs=true" \
+ | python3 -I -c 'import json,sys
+for s in json.load(sys.stdin)["siblings"]:
+ print(s["rfilename"], s.get("size") or 0)'
+}
+
+remote_size() { gcloud storage objects describe "$1" --format='value(size)' 2>/dev/null || true; }
+
+copy_one() { # <repo> <src path> <size> <dest uri>
+ local repo="$1" path="$2" size="$3" dest="$4"
+ if [[ "$(remote_size "$dest")" == "$size" && "$size" != "0" ]]; then
+ echo "skip $dest"
+ return
+ fi
+ echo "copy $repo/$path -> $dest ($size bytes)"
+ curl -fsSL "${AUTH[@]}" "https://huggingface.co/${repo}/resolve/main/${path}" \
+ | gcloud storage cp - "$dest" --quiet
+ local got
+ got="$(remote_size "$dest")"
+ if [[ "$size" != "0" && "$got" != "$size" ]]; then
+ echo "FAIL $dest: expected $size bytes, bucket has ${got:-none}" >&2
+ exit 1
+ fi
+}
+
+mirror_repo() { # <repo> <dest prefix> [include regex] [exclude regex]
+ local repo="$1" dest="$2" include="${3:-.}" exclude="${4:-$}"
+ while read -r path size; do
+ [[ "$path" =~ $include ]] || continue
+ [[ "$path" == .gitattributes ]] && continue
+ [[ "$exclude" != '$' && "$path" =~ $exclude ]] && continue
+ copy_one "$repo" "$path" "$size" "${dest}/${path}"
+ done < <(list_repo "$repo")
+}
+
+# TencentARC/Pixal3D's pipeline.json / pipeline_mv.json / ckpts/*.
+mirror_repo TencentARC/Pixal3D "${DEST}"
+mirror_repo camenduru/dinov3-vitl16-pretrain-lvd1689m "${DEST}/dinov3"
+mirror_repo ZhengPeng7/BiRefNet "${DEST}/birefnet"
+echo "pixal3d weights staged at ${DEST}"
+
+# The optional MV-Adapter rung. Set SKIP_MVADAPTER=1 to stage only the core
+# 1-4 image lanes above and leave fill_other_sides unavailable for now.
+if [[ "${SKIP_MVADAPTER:-0}" != "1" ]]; then
+ mirror_repo stabilityai/stable-diffusion-xl-base-1.0 "${MV_DEST}/sdxl-base" '.' 'fp16|\.(bin|ckpt|onnx|msgpack)$'
+ mirror_repo madebyollin/sdxl-vae-fp16-fix "${MV_DEST}/sdxl-vae-fix" '.' '\.(bin|ckpt|onnx|msgpack)$'
+ mirror_repo huanngzh/mv-adapter "${MV_DEST}/mv-adapter"
+ echo "mv-adapter weights staged at ${MV_DEST}"
+fi
diff --git a/workers/model-pixal3d/storage_backend.py b/workers/model-pixal3d/storage_backend.py
new file mode 100644
index 000000000..fcf7fc1a1
--- /dev/null
+++ b/workers/model-pixal3d/storage_backend.py
@@ -0,0 +1,63 @@
+"""Storage primitives for the standalone TRELLIS container.
+
+Production persists tasks and results in GCS because requests can move between
+Cloud Run instances. An NGC user runs one container with a mounted output
+volume, so the same service needs a local backend with atomic writes and strict
+task-id validation.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from pathlib import Path
+
+
+def normalize_task_id(task_id: str) -> str:
+ """Return a canonical UUID or reject a value that could escape the volume."""
+ parsed = uuid.UUID(task_id)
+ canonical = str(parsed)
+ if task_id.lower() != canonical:
+ raise ValueError("task_id must be a canonical UUID")
+ return canonical
+
+
+class LocalStorage:
+ """Durable task metadata and GLB results on a mounted local volume."""
+
+ def __init__(self, output_dir: str | os.PathLike[str]):
+ self.output_dir = Path(output_dir).expanduser().resolve()
+ self.tasks_dir = self.output_dir / "tasks"
+ self.results_dir = self.output_dir / "results"
+ self.tasks_dir.mkdir(parents=True, exist_ok=True)
+ self.results_dir.mkdir(parents=True, exist_ok=True)
+
+ def task_path(self, task_id: str) -> Path:
+ return self.tasks_dir / f"{normalize_task_id(task_id)}.json"
+
+ def result_path(self, task_id: str) -> Path:
+ return self.results_dir / f"{normalize_task_id(task_id)}.glb"
+
+ @staticmethod
+ def _atomic_write(path: Path, data: bytes) -> None:
+ temporary = path.with_suffix(path.suffix + ".tmp")
+ with temporary.open("wb") as handle:
+ handle.write(data)
+ handle.flush()
+ os.fsync(handle.fileno())
+ temporary.replace(path)
+
+ def write_task(self, task: dict) -> Path:
+ path = self.task_path(str(task["task_id"]))
+ payload = json.dumps(task, separators=(",", ":"), sort_keys=True).encode("utf-8")
+ self._atomic_write(path, payload)
+ return path
+
+ def read_task(self, task_id: str) -> dict:
+ return json.loads(self.task_path(task_id).read_text(encoding="utf-8"))
+
+ def write_result(self, task_id: str, glb_bytes: bytes) -> Path:
+ path = self.result_path(task_id)
+ self._atomic_write(path, glb_bytes)
+ return path
diff --git a/workers/model-pixal3d/test_app_contract.py b/workers/model-pixal3d/test_app_contract.py
new file mode 100644
index 000000000..99cab2374
--- /dev/null
+++ b/workers/model-pixal3d/test_app_contract.py
@@ -0,0 +1,172 @@
+"""Smoke test for the served contract, run INSIDE the built image (it needs
+torch, FastAPI, PIL, google-cloud-storage, and the cloned Pixal3D/MV-Adapter
+trees on PYTHONPATH):
+
+ docker build -t model-pixal3d workers/model-pixal3d
+ docker run --rm model-pixal3d python3 test_app_contract.py
+
+It needs no GPU, no weights, and no GCP credentials: the ASGI lifespan (which
+opens the GCS client and starts weight staging) is deliberately not run, so
+every assertion below is about request handling, not inference.
+
+What it proves, mirroring workers/model-trellis2's identical-purpose test:
+
+ 1. The Pixal3D import chain resolves, including the compiled CuMesh,
+ FlexGEMM, O-Voxel and nvdiffrast extensions the GLB bake needs (same
+ backbone as TRELLIS.2), plus natten (its neighborhood-attention blocks)
+ and MoGe (the single-view camera estimator).
+ 2. The whole app module imports.
+ 3. The auth boundary rejects a wrong bearer on both authenticated routes.
+ 4. The unauthenticated probe surfaces (/ and /health) answer, and a dead
+ pipeline says so on both /health and /infer so the caller fails over.
+ 5. Request validation: an empty or 5+ image array is rejected, a
+ view_labels length mismatch is rejected, fill_other_sides with more
+ than one image is rejected.
+ 6. The image decoder keeps an RGBA cutout's alpha and refuses everything
+ the SSRF guard should refuse.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import os
+import sys
+
+os.environ.setdefault("API_KEY", "smoke-test-key")
+os.environ.setdefault("GCS_BUCKET", "smoke-test-bucket")
+
+KEY = os.environ["API_KEY"]
+
+PASSED = 0
+
+
+def check(name: str, condition: bool, detail: str = "") -> None:
+ global PASSED
+ if not condition:
+ print(f"FAIL {name} {detail}")
+ sys.exit(1)
+ PASSED += 1
+ print(f"ok {name}")
+
+
+def png_data_uri(color=(20, 20, 20, 255), size=(24, 24)) -> str:
+ from PIL import Image
+
+ img = Image.new("RGBA", size, color)
+ buf = io.BytesIO()
+ img.save(buf, format="PNG")
+ return "data:image/png;base64," + base64.b64encode(buf.getvalue()).decode()
+
+
+# Libraries the NVIDIA container runtime mounts into a GPU instance. The image
+# cannot ship them, so their absence on the CPU-only builder is expected.
+_GPU_DRIVER_LIBS = ("libcuda.so", "libnvidia", "libnvrtc")
+
+
+def _is_gpu_driver_absence(exc: BaseException) -> bool:
+ text = str(exc)
+ if "cannot open shared object file" in text:
+ return any(lib in text for lib in _GPU_DRIVER_LIBS)
+ lowered = text.lower()
+ return "cuda" in lowered or "nvidia driver" in lowered or "no gpu" in lowered
+
+
+def main() -> int:
+ try:
+ from pixal3d.pipelines.pixal3d_image_to_3d import Pixal3DImageTo3DPipeline # noqa: F401
+ import o_voxel.postprocess # noqa: F401
+ import cumesh # noqa: F401
+ import flex_gemm # noqa: F401
+ import natten # noqa: F401
+ import moge # noqa: F401
+
+ check("pixal3d import chain resolves", True)
+ except ModuleNotFoundError as exc:
+ check("pixal3d import chain resolves", False, str(exc))
+ except Exception as exc: # noqa: BLE001 - classified below
+ if _is_gpu_driver_absence(exc):
+ print(f"skip pixal3d import chain (no GPU on this host): {type(exc).__name__}: {exc}")
+ else:
+ check("pixal3d import chain resolves", False, f"{type(exc).__name__}: {exc}")
+
+ import main as app_module
+ from fastapi.testclient import TestClient
+
+ client = TestClient(app_module.app)
+
+ bad = {"Authorization": "Bearer wrong-key"}
+ res = client.get("/tasks/does-not-exist", headers=bad)
+ check("GET /tasks rejects a wrong bearer", res.status_code == 401, f"got {res.status_code}")
+ res = client.post("/infer", headers=bad, json={"images": [png_data_uri()]})
+ check("POST /infer rejects a wrong bearer", res.status_code == 401, f"got {res.status_code}")
+
+ res = client.get("/health")
+ body = res.json()
+ check("GET /health answers 200", res.status_code == 200, f"got {res.status_code}")
+ check("health names the model", body.get("model") == "pixal3d", str(body)[:120])
+ check("health lists the resolutions", body.get("resolutions") == [1024, 1536], str(body.get("resolutions")))
+ check("health reports max_images", body.get("max_images") == 4, str(body)[:160])
+ res = client.get("/")
+ body = res.json()
+ check("GET / answers 200 for the keep-warm ping", res.status_code == 200, f"got {res.status_code}")
+ check("root names the service", body.get("service") == "model-pixal3d", str(body)[:120])
+ check("root lists the working endpoints", "POST /infer" in body.get("endpoints", []), str(body)[:160])
+
+ # A dead instance must SAY it is dead, on both surfaces. See
+ # workers/model-trellis2's identical check for why this matters.
+ app_module._load_error = "internal error (ref deadbeefcafe)"
+ try:
+ res = client.get("/health")
+ body = res.json()
+ check("a dead pipeline makes /health answer 503", res.status_code == 503, f"got {res.status_code}")
+ check("a dead pipeline makes /health report ok:false", body.get("ok") is False, str(body)[:160])
+ check("health surfaces the load error", "deadbeefcafe" in str(body.get("load_error")), str(body)[:160])
+ res = client.post("/infer", headers={"Authorization": f"Bearer {KEY}"}, json={"images": [png_data_uri()]})
+ check("a dead pipeline makes /infer refuse with 503", res.status_code == 503, f"got {res.status_code}")
+ finally:
+ app_module._load_error = None
+ res = client.get("/health")
+ check("a live pipeline still answers /health 200", res.status_code == 200, f"got {res.status_code}")
+ check("a live pipeline reports ok:true", res.json().get("ok") is True, str(res.json())[:160])
+
+ good = {"Authorization": f"Bearer {KEY}"}
+ res = client.post("/infer", headers=good, json={"images": []})
+ check("POST /infer rejects an empty images array", res.status_code == 422, f"got {res.status_code}")
+ res = client.post("/infer", headers=good, json={"images": [png_data_uri()] * 5})
+ check("POST /infer rejects more than four images", res.status_code == 422, f"got {res.status_code}")
+ res = client.post(
+ "/infer", headers=good,
+ json={"images": [png_data_uri(), png_data_uri()], "view_labels": ["front"]},
+ )
+ check("POST /infer rejects a view_labels length mismatch", res.status_code == 400, f"got {res.status_code}")
+ res = client.post(
+ "/infer", headers=good,
+ json={"images": [png_data_uri(), png_data_uri()], "fill_other_sides": True},
+ )
+ check("POST /infer rejects fill_other_sides with more than one image", res.status_code == 400, f"got {res.status_code}")
+
+ img = app_module._decode_image(png_data_uri())
+ check("data uri decodes with its alpha channel", img.mode == "RGBA" and img.size == (24, 24), f"{img.mode} {img.size}")
+
+ for label, src in [
+ ("cleartext http", "http://example.com/a.png"),
+ ("bare path", "/etc/passwd"),
+ ("loopback https", "https://127.0.0.1/a.png"),
+ ("cloud metadata", "https://169.254.169.254/latest/meta-data/"),
+ ("corrupt data uri", "data:image/png;base64,not-base64!!"),
+ ]:
+ try:
+ app_module._decode_image(src)
+ check(f"refuses {label}", False, "no exception raised")
+ except app_module.ImageSourceError:
+ check(f"refuses {label}", True)
+ except Exception as exc: # noqa: BLE001 - must be the caller-facing class
+ check(f"refuses {label}", False, f"raised {type(exc).__name__}: {exc}")
+
+ print(f"\n{PASSED} contract assertions passed")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/workers/model-pixal3d/test_camera_rig.py b/workers/model-pixal3d/test_camera_rig.py
new file mode 100644
index 000000000..a6c67124c
--- /dev/null
+++ b/workers/model-pixal3d/test_camera_rig.py
@@ -0,0 +1,106 @@
+"""Pure-logic tests for camera_rig.py: no torch, no GPU, no network."""
+
+import math
+
+import pytest
+
+import camera_rig
+
+
+def _flatten(matrix):
+ return [value for row in matrix for value in row]
+
+
+def test_front_azimuth_is_zero_and_matches_pixal3d_front_matrix():
+ matrix = camera_rig.transform_matrix_for_azimuth(0.0, distance=3.1192)
+ assert _flatten(matrix) == pytest.approx(
+ _flatten(
+ [
+ [1.0, 0.0, 0.0, 0.0],
+ [0.0, 0.0, -1.0, -3.1192],
+ [0.0, 1.0, 0.0, 0.0],
+ [0.0, 0.0, 0.0, 1.0],
+ ]
+ )
+ )
+ assert camera_rig.camera_position(matrix) == pytest.approx((0.0, -3.1192, 0.0))
+
+
+ "azimuth,expected_position",
+ [
+ (0.0, (0.0, -1.0, 0.0)),
+ (90.0, (1.0, 0.0, 0.0)),
+ (180.0, (0.0, 1.0, 0.0)),
+ (270.0, (-1.0, 0.0, 0.0)),
+ ],
+)
+def test_orbit_positions_at_each_label_azimuth(azimuth, expected_position):
+ matrix = camera_rig.transform_matrix_for_azimuth(azimuth, distance=1.0)
+ assert camera_rig.camera_position(matrix) == pytest.approx(expected_position, abs=1e-9)
+
+
+def test_matrix_stays_orthogonal_rotation_for_arbitrary_azimuth():
+ matrix = camera_rig.transform_matrix_for_azimuth(37.0, distance=2.5)
+ rotation = [row[:3] for row in matrix[:3]]
+ # R^T R == I for a pure rotation.
+ for i in range(3):
+ for j in range(3):
+ dot = sum(rotation[k][i] * rotation[k][j] for k in range(3))
+ assert dot == pytest.approx(1.0 if i == j else 0.0, abs=1e-9)
+ assert matrix[3] == [0.0, 0.0, 0.0, 1.0]
+
+
+def test_resolve_azimuths_with_full_labels():
+ azimuths = camera_rig.resolve_azimuths(["front", "right", "back", "left"])
+ assert azimuths == [0.0, 90.0, 180.0, 270.0]
+
+
+ "count,expected",
+ [
+ (1, [0.0]),
+ (2, [0.0, 180.0]),
+ (3, [0.0, 120.0, 240.0]),
+ (4, [0.0, 90.0, 180.0, 270.0]),
+ ],
+)
+def test_resolve_azimuths_even_spacing_fallback(count, expected):
+ azimuths = camera_rig.resolve_azimuths([None] * count)
+ assert azimuths == pytest.approx(expected)
+
+
+def test_resolve_azimuths_partial_labels_spread_blanks_without_clustering():
+ azimuths = camera_rig.resolve_azimuths(["front", None, None, None])
+ assert azimuths[0] == 0.0
+ # The three blanks take the 4-way even spacing in order, skipping index 0.
+ assert azimuths[1:] == pytest.approx([90.0, 180.0, 270.0])
+
+
+def test_resolve_azimuths_unrecognized_label_treated_as_unlabeled():
+ azimuths = camera_rig.resolve_azimuths(["front", "top"])
+ assert azimuths == pytest.approx([0.0, 180.0])
+
+
+def test_resolve_azimuths_empty_input():
+ assert camera_rig.resolve_azimuths([]) == []
+
+
+def test_build_view_rig_shape_and_shared_camera_params():
+ rig = camera_rig.build_view_rig(["front", "back"], distance=3.0, camera_angle_x=0.35)
+ assert len(rig) == 2
+ for view in rig:
+ assert view["camera_distance"] == 3.0
+ assert view["camera_angle_x"] == 0.35
+ assert len(view["transform_matrix"]) == 4
+ assert len(view["transform_matrix"][0]) == 4
+ assert rig[0]["azimuth_degrees"] == 0.0
+ assert rig[1]["azimuth_degrees"] == 180.0
+
+
+def test_180_degree_rotation_is_negation_of_front_xy():
+ front = camera_rig.transform_matrix_for_azimuth(0.0, distance=1.0)
+ back = camera_rig.transform_matrix_for_azimuth(180.0, distance=1.0)
+ fx, fy, fz = camera_rig.camera_position(front)
+ bx, by, bz = camera_rig.camera_position(back)
+ assert (bx, by, bz) == pytest.approx((-fx, -fy, fz))
diff --git a/workers/model-pixal3d/test_glb_pack.py b/workers/model-pixal3d/test_glb_pack.py
new file mode 100644
index 000000000..a8a1f8ffa
--- /dev/null
+++ b/workers/model-pixal3d/test_glb_pack.py
@@ -0,0 +1,106 @@
+"""Unit tests for GLB post-processing: alpha mode and the gltfpack step.
+
+Needs numpy only; the gltfpack round trip runs when the binary is installed
+(every built image has it):
+
+ cd workers/model-trellis2 && python3 -m pytest test_glb_pack.py -q
+"""
+
+import json
+import shutil
+import struct
+
+import numpy as np
+import pytest
+
+import glb_pack
+
+
+class _Texture:
+ def __init__(self, alpha):
+ self.mode = "RGBA"
+ self._array = np.dstack([np.zeros_like(alpha)] * 3 + [alpha])
+
+ def __array__(self, dtype=None, copy=None):
+ return self._array
+
+
+class _Material:
+ def __init__(self, texture):
+ self.baseColorTexture = texture
+ self.alphaMode = "OPAQUE"
+
+
+class _Mesh:
+ def __init__(self, alpha):
+ self.visual = type("V", (), {"material": _Material(_Texture(alpha))})()
+
+
+def test_solid_alpha_stays_opaque():
+ assert glb_pack.alpha_mode_for(np.full((64, 64), 255, dtype=np.uint8)) == "OPAQUE"
+
+
+def test_stray_seam_pixels_do_not_flip_a_solid_asset():
+ alpha = np.full((100, 100), 255, dtype=np.uint8)
+ alpha[0, :50] = 0
+ assert glb_pack.alpha_mode_for(alpha) == "OPAQUE"
+
+
+def test_translucent_regions_flip_to_blend():
+ alpha = np.full((100, 100), 255, dtype=np.uint8)
+ alpha[:20] = 40
+ assert glb_pack.alpha_mode_for(alpha) == "BLEND"
+
+
+def test_empty_plane_is_opaque():
+ assert glb_pack.alpha_mode_for(np.zeros((0, 0), dtype=np.uint8)) == "OPAQUE"
+
+
+def test_blend_if_translucent_sets_the_material():
+ alpha = np.full((10, 10), 255, dtype=np.uint8)
+ alpha[:5] = 10
+ mesh = _Mesh(alpha)
+ assert glb_pack.blend_if_translucent(mesh) == "BLEND"
+ assert mesh.visual.material.alphaMode == "BLEND"
+
+
+def test_mesh_without_a_texture_is_left_alone():
+ assert glb_pack.blend_if_translucent(object()) == "OPAQUE"
+
+
+def test_missing_gltfpack_returns_the_uncompressed_glb():
+ data = b"glTF" + b"\x00" * 32
+ out, packed = glb_pack.compress(data, gltfpack_bin="gltfpack-not-installed")
+ assert out == data and packed is False
+
+
+def _minimal_glb() -> bytes:
+ positions = np.array([[0, 0, 0], [1, 0, 0], [0, 1, 0]], dtype="<f4").tobytes()
+ doc = {
+ "asset": {"version": "2.0"},
+ "scene": 0,
+ "scenes": [{"nodes": [0]}],
+ "nodes": [{"mesh": 0}],
+ "meshes": [{"primitives": [{"attributes": {"POSITION": 0}}]}],
+ "accessors": [{"bufferView": 0, "componentType": 5126, "count": 3, "type": "VEC3", "min": [0, 0, 0], "max": [1, 1, 0]}],
+ "bufferViews": [{"buffer": 0, "byteLength": len(positions)}],
+ "buffers": [{"byteLength": len(positions)}],
+ }
+ js = json.dumps(doc).encode()
+ js += b" " * (-len(js) % 4)
+ body = positions + b"\x00" * (-len(positions) % 4)
+ total = 12 + 8 + len(js) + 8 + len(body)
+ return (
+ struct.pack("<4sII", b"glTF", 2, total)
+ + struct.pack("<I4s", len(js), b"JSON") + js
+ + struct.pack("<I4s", len(body), b"BIN\x00") + body
+ )
+
+
[email protected](shutil.which(glb_pack.GLTFPACK_BIN) is None, reason="gltfpack not installed")
+def test_gltfpack_round_trip_yields_a_meshopt_glb():
+ out, packed = glb_pack.compress(_minimal_glb())
+ assert packed is True and out[:4] == b"glTF"
+ js_len = int.from_bytes(out[12:16], "little")
+ doc = json.loads(out[20:20 + js_len])
+ assert "EXT_meshopt_compression" in (doc.get("extensionsUsed") or [])
diff --git a/workers/model-pixal3d/test_instance_health.py b/workers/model-pixal3d/test_instance_health.py
new file mode 100644
index 000000000..261a66c29
--- /dev/null
+++ b/workers/model-pixal3d/test_instance_health.py
@@ -0,0 +1,142 @@
+"""Unit tests for instance self-care: memory reading, recycle, orphan expiry.
+
+Pure stdlib, no torch and no CUDA, so this runs anywhere:
+
+ cd workers/model-trellis2 && python3 -m pytest test_instance_health.py -q
+
+These decisions run after every generation on the production instance. A wrong
+memory reading either restarts a healthy instance after every job or never
+restarts a bloated one, and a wrong orphan rule either fails live jobs or leaves
+dead ones polling for half an hour, which is the outage this module fixed.
+"""
+
+from pathlib import Path
+
+from instance_health import (
+ HEARTBEAT_SECS,
+ ORPHAN_AFTER_SECS,
+ MemorySample,
+ read_memory,
+ should_recycle,
+ task_is_orphaned,
+ trim_heap,
+)
+
+GIB = 1024 ** 3
+
+
+def _write(path: Path, text: str) -> None:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(text, encoding="ascii")
+
+
+# ---------------------------------------------------------------- read_memory
+
+
+def test_cgroup_v2_counts_heap_and_tmpfs_but_not_page_cache(tmp_path):
+ v2 = tmp_path / "v2"
+ _write(v2 / "memory.stat", f"anon {20 * GIB}\nfile {9 * GIB}\nshmem {3 * GIB}\n")
+ _write(v2 / "memory.max", f"{32 * GIB}\n")
+ sample = read_memory(str(v2), str(tmp_path / "none"), str(tmp_path / "none"))
+ assert sample == MemorySample(23 * GIB, 32 * GIB, "cgroup2")
+ assert abs(sample.fraction - 23 / 32) < 1e-9
+
+
+def test_cgroup_v2_without_a_limit_falls_through_to_meminfo(tmp_path):
+ v2 = tmp_path / "v2"
+ _write(v2 / "memory.stat", f"anon {GIB}\n")
+ _write(v2 / "memory.max", "max\n")
+ meminfo = tmp_path / "meminfo"
+ _write(meminfo, "MemTotal: 33554432 kB\nMemAvailable: 8388608 kB\n")
+ sample = read_memory(str(v2), str(tmp_path / "none"), str(meminfo))
+ assert sample.source == "meminfo"
+ assert sample.used_bytes == 24 * GIB
+ assert sample.limit_bytes == 32 * GIB
+
+
+def test_cgroup_v1_reads_rss_plus_shmem(tmp_path):
+ v1 = tmp_path / "v1"
+ _write(v1 / "memory.stat", f"total_rss {10 * GIB}\ntotal_cache {5 * GIB}\ntotal_shmem {2 * GIB}\n")
+ _write(v1 / "memory.limit_in_bytes", f"{16 * GIB}\n")
+ sample = read_memory(str(tmp_path / "none"), str(v1), str(tmp_path / "none"))
+ assert sample == MemorySample(12 * GIB, 16 * GIB, "cgroup1")
+
+
+def test_unlimited_cgroup_v1_is_not_a_ceiling(tmp_path):
+ v1 = tmp_path / "v1"
+ _write(v1 / "memory.stat", f"total_rss {GIB}\n")
+ _write(v1 / "memory.limit_in_bytes", "9223372036854771712\n")
+ assert read_memory(str(tmp_path / "none"), str(v1), str(tmp_path / "none")) is None
+
+
+def test_nothing_readable_is_unknown_not_an_error(tmp_path):
+ missing = str(tmp_path / "missing")
+ assert read_memory(missing, missing, missing) is None
+
+
+def test_describe_is_human_readable():
+ text = MemorySample(24 * GIB, 32 * GIB, "cgroup2").describe()
+ assert text == "24.0/32.0 GiB (75%, cgroup2)"
+
+
+# ---------------------------------------------------------------- should_recycle
+
+
+def _at(fraction: float) -> MemorySample:
+ return MemorySample(int(fraction * 32 * GIB), 32 * GIB, "cgroup2")
+
+
+def test_recycles_a_ratcheted_instance():
+ assert should_recycle(_at(0.88), _at(0.46))
+
+
+def test_leaves_a_healthy_instance_alone():
+ assert not should_recycle(_at(0.60), _at(0.46))
+
+
+def test_high_baseline_alone_never_recycles():
+ # A baseline that already reads high (a big model, or a reading that counts
+ # more than it should) must not restart the instance after every job.
+ assert not should_recycle(_at(0.84), _at(0.80))
+
+
+def test_unknown_memory_never_recycles():
+ assert not should_recycle(None, _at(0.40))
+ assert not should_recycle(_at(0.95), None)
+
+
+# ---------------------------------------------------------------- task_is_orphaned
+
+
+NOW = 1_800_000_000.0
+
+
+def test_a_beating_task_is_alive():
+ assert not task_is_orphaned("running", NOW - HEARTBEAT_SECS, NOW)
+ assert not task_is_orphaned("queued", NOW - ORPHAN_AFTER_SECS + 1, NOW)
+
+
+def test_a_silent_task_is_orphaned_within_minutes():
+ assert task_is_orphaned("running", NOW - ORPHAN_AFTER_SECS - 1, NOW)
+ # The old rule waited 1800 s; the whole point is that a client still polls.
+ assert ORPHAN_AFTER_SECS <= 300
+ # Several missed beats, never one, decide it.
+ assert ORPHAN_AFTER_SECS >= 4 * HEARTBEAT_SECS
+
+
+def test_a_record_without_a_timestamp_cannot_prove_it_is_alive():
+ assert task_is_orphaned("queued", None, NOW)
+ assert task_is_orphaned("running", "yesterday", NOW)
+ assert task_is_orphaned("running", True, NOW)
+
+
+def test_terminal_and_unknown_records_are_never_orphaned():
+ for status in ("done", "failed", None, "weird"):
+ assert not task_is_orphaned(status, NOW - 10 * ORPHAN_AFTER_SECS, NOW)
+
+
+# ---------------------------------------------------------------- trim_heap
+
+
+def test_trim_heap_never_raises():
+ assert trim_heap() in (True, False)
diff --git a/workers/model-pixal3d/test_pipeline_config.py b/workers/model-pixal3d/test_pipeline_config.py
new file mode 100644
index 000000000..b4fc0f197
--- /dev/null
+++ b/workers/model-pixal3d/test_pipeline_config.py
@@ -0,0 +1,109 @@
+"""Unit tests for the pipeline.json / pipeline_mv.json rewrite: stdlib only.
+
+ cd workers/model-pixal3d && python3 -m pytest test_pipeline_config.py -q
+
+The rewrite is what keeps the non-commercial RMBG-2.0 matte out of the served
+pipeline and keeps the DINOv3 conditioner load off the gated Hugging Face Hub
+repo, so both are asserted against the real shape of TencentARC/Pixal3D's
+published configs (fields the rewrite does not touch are trimmed for brevity).
+"""
+
+import json
+
+import pipeline_config
+
+UPSTREAM = {
+ "name": "Trellis2ImageTo3DPipeline",
+ "args": {
+ "models": {
+ "sparse_structure_decoder": "ckpts/ss_dec_conv3d_16l8_fp16",
+ "sparse_structure_flow_model": "ckpts/ss_flow_img_dit_1_3B_64_bf16",
+ "shape_slat_decoder": "ckpts/shape_dec_next_dc_f16c32_fp16",
+ },
+ "shape_slat_sampler": {"name": "FlowEulerGuidanceIntervalSampler", "params": {"steps": 12}},
+ "image_cond_model": {
+ "name": "DinoV3FeatureExtractor",
+ "args": {"model_name": "facebook/dinov3-vitl16-pretrain-lvd1689m"},
+ },
+ "rembg_model": {"name": "BiRefNet", "args": {"model_name": "briaai/RMBG-2.0"}},
+ "default_pipeline_type": "1536_cascade",
+ },
+}
+
+UPSTREAM_MV = json.loads(json.dumps(UPSTREAM))
+UPSTREAM_MV["name"] = "Pixal3DMVImageTo3DPipeline"
+UPSTREAM_MV["args"]["models"]["sparse_structure_flow_model"] = "ckpts/ss_flow_img_dit_1_3B_64_bf16_mv"
+
+
+def test_matte_is_replaced_by_the_mit_birefnet_checkpoint():
+ out = pipeline_config.localize(UPSTREAM, "/aux")
+ assert "RMBG" not in json.dumps(out)
+ assert out["args"]["rembg_model"] == {"name": "BiRefNet", "args": {"model_name": "/aux/birefnet"}}
+
+
+def test_conditioner_loads_from_the_staged_copy_not_the_gated_hub_repo():
+ out = pipeline_config.localize(UPSTREAM, "/aux")
+ assert out["args"]["image_cond_model"]["args"]["model_name"] == "/aux/dinov3"
+ assert "facebook/" not in json.dumps(out)
+
+
+def test_mv_config_localizes_the_same_way_as_the_single_view_config():
+ out = pipeline_config.localize(UPSTREAM_MV, "/aux")
+ assert out["args"]["rembg_model"]["args"]["model_name"] == "/aux/birefnet"
+ assert out["args"]["image_cond_model"]["args"]["model_name"] == "/aux/dinov3"
+ # The mv-suffixed flow model name is untouched: it already resolves inside ckpts/.
+ assert out["args"]["models"]["sparse_structure_flow_model"] == "ckpts/ss_flow_img_dit_1_3B_64_bf16_mv"
+
+
+def test_model_paths_are_left_alone_pixal3d_ships_them_already_local():
+ out = pipeline_config.localize(UPSTREAM, "/aux")
+ assert out["args"]["models"] == UPSTREAM["args"]["models"]
+
+
+def test_unrelated_fields_pass_through_and_input_is_not_mutated():
+ before = json.dumps(UPSTREAM)
+ out = pipeline_config.localize(UPSTREAM, "/aux")
+ assert json.dumps(UPSTREAM) == before
+ assert out["args"]["shape_slat_sampler"] == UPSTREAM["args"]["shape_slat_sampler"]
+ assert out["args"]["default_pipeline_type"] == "1536_cascade"
+
+
+def test_missing_weights_names_every_absent_file():
+ present = set(pipeline_config.REQUIRED_PATHS) - {"dinov3/model.safetensors", "birefnet/config.json"}
+ assert pipeline_config.missing_weights(present) == ["dinov3/model.safetensors", "birefnet/config.json"]
+ assert pipeline_config.missing_weights(pipeline_config.REQUIRED_PATHS) == []
+
+
+def test_required_paths_cover_every_mv_and_single_view_checkpoint():
+ needed = {
+ "ckpts/ss_flow_img_dit_1_3B_64_bf16.safetensors",
+ "ckpts/ss_flow_img_dit_1_3B_64_bf16_mv.safetensors",
+ "ckpts/slat_flow_img2shape_dit_1_3B_512_bf16_mv.safetensors",
+ "ckpts/slat_flow_img2shape_dit_1_3B_1024_bf16_mv.safetensors",
+ "ckpts/slat_flow_imgshape2tex_dit_1_3B_1024_bf16_mv.safetensors",
+ "pipeline.json",
+ "pipeline_mv.json",
+ }
+ assert needed <= set(pipeline_config.REQUIRED_PATHS)
+
+
+def test_write_local_config_and_link_tree(tmp_path):
+ root = tmp_path / "weights"
+ (root / "ckpts").mkdir(parents=True)
+ (root / "pipeline.json").write_text(json.dumps(UPSTREAM))
+ (root / "pipeline_mv.json").write_text(json.dumps(UPSTREAM_MV))
+ out_dir = tmp_path / "cfg"
+ single = pipeline_config.write_local_config(
+ (root / "pipeline.json").read_text(), "/aux", out_dir / "pipeline.json"
+ )
+ mv = pipeline_config.write_local_config(
+ (root / "pipeline_mv.json").read_text(), "/aux", out_dir / "pipeline_mv.json"
+ )
+ pipeline_config.link_weight_tree(root, out_dir)
+ assert json.loads(single.read_text())["args"]["rembg_model"]["args"]["model_name"] == "/aux/birefnet"
+ assert json.loads(mv.read_text())["name"] == "Pixal3DMVImageTo3DPipeline"
+ assert (out_dir / "ckpts").is_symlink()
+ assert not (out_dir / "pipeline.json").is_symlink()
+ assert not (out_dir / "pipeline_mv.json").is_symlink()
+ # Idempotent: a load retry re-links without raising.
+ pipeline_config.link_weight_tree(root, out_dir)
diff --git a/workers/model-pixal3d/test_request_policy.py b/workers/model-pixal3d/test_request_policy.py
new file mode 100644
index 000000000..0c2ef3575
--- /dev/null
+++ b/workers/model-pixal3d/test_request_policy.py
@@ -0,0 +1,144 @@
+"""Unit tests for the Pixal3D request policy: resolutions and transient-fetch retry.
+
+Pure stdlib plus httpx, no torch and no CUDA, so this runs anywhere:
+
+ cd workers/model-pixal3d && python3 -m pytest test_request_policy.py -q
+"""
+
+import httpx
+import pytest
+
+from request_policy import (
+ DEFAULT_RESOLUTION,
+ FETCH_ATTEMPTS,
+ PIPELINE_TYPES,
+ RESOLUTIONS,
+ RESOLUTION_PRESETS,
+ bake_params,
+ call_with_retry,
+ clamp_to_ceiling,
+ is_transient_fetch_error,
+ resolve_resolution,
+ retry_delays,
+ step_down,
+)
+
+
+def test_default_is_1536():
+ assert resolve_resolution(None) == DEFAULT_RESOLUTION == 1536
+
+
+ "wanted,expected",
+ [(1024, 1024), (1536, 1536), (2048, 1536), (700, 1024), (900, 1024), (1300, 1536), (1400, 1536)],
+)
+def test_explicit_resolution_snaps_to_a_supported_size(wanted, expected):
+ assert resolve_resolution(wanted) == expected
+
+
+def test_garbage_resolution_falls_back_to_the_default():
+ assert resolve_resolution("big") == 1536
+ assert resolve_resolution([]) == 1536
+
+
+ "tier,expected",
+ [("draft", 1024), ("standard", 1024), ("high", 1536), ("max", 1536), (" MAX ", 1536), ("nonsense", 1536), (None, 1536)],
+)
+def test_tier_maps_to_a_resolution(tier, expected):
+ assert resolve_resolution(None, tier) == expected
+
+
+def test_explicit_resolution_beats_the_tier():
+ assert resolve_resolution(1024, "max") == 1024
+
+
+def test_every_resolution_has_a_pipeline_type_and_a_preset():
+ for r in RESOLUTIONS:
+ assert r in PIPELINE_TYPES and r in RESOLUTION_PRESETS
+ assert PIPELINE_TYPES == {1024: "1024_cascade", 1536: "1536_cascade"}
+ assert RESOLUTIONS == (1024, 1536)
+
+
+def test_ceiling_caps_the_request():
+ assert clamp_to_ceiling(1536, 1024) == 1024
+ assert clamp_to_ceiling(1024, 1536) == 1024
+ assert clamp_to_ceiling(1536, None) == 1536
+ assert clamp_to_ceiling(1536, 100) == 1024
+
+
+def test_step_down_walks_the_ladder_and_stops():
+ assert step_down(1536) == 1024
+ assert step_down(1024) is None
+
+
+def test_bake_params_default_to_the_preset():
+ assert bake_params(1536) == {"texture_size": 4096, "decimation_target": 1_000_000}
+ assert bake_params(1024)["texture_size"] == 2048
+
+
+def test_texture_size_snaps_down_to_a_power_of_two_inside_the_envelope():
+ assert bake_params(1536, texture_size=3072)["texture_size"] == 2048
+ assert bake_params(1536, texture_size=100000)["texture_size"] == 4096
+ assert bake_params(1536, texture_size=10)["texture_size"] == 512
+
+
+def test_decimation_is_bounded_and_garbage_falls_back():
+ assert bake_params(1536, decimation_target=10)["decimation_target"] == 50_000
+ assert bake_params(1536, decimation_target=10**9)["decimation_target"] == 1_500_000
+ assert bake_params(1536, decimation_target="lots")["decimation_target"] == 1_000_000
+ assert bake_params(1536, texture_size="x")["texture_size"] == 4096
+
+
+def test_retry_delays_double():
+ assert retry_delays(3, 1.0) == [1.0, 2.0]
+
+
+def _status_error(code):
+ request = httpx.Request("GET", "https://example.com/a.png")
+ return httpx.HTTPStatusError("x", request=request, response=httpx.Response(code, request=request))
+
+
+def test_transient_classification():
+ assert is_transient_fetch_error(httpx.ReadTimeout("t"))
+ assert is_transient_fetch_error(_status_error(503))
+ assert not is_transient_fetch_error(_status_error(404))
+ assert not is_transient_fetch_error(ValueError("nope"))
+
+
+def test_call_with_retry_recovers_from_a_blip():
+ calls = []
+ sleeps = []
+
+ def flaky():
+ calls.append(1)
+ if len(calls) < 2:
+ raise httpx.ReadTimeout("slow")
+ return "ok"
+
+ assert call_with_retry(flaky, sleep=sleeps.append) == "ok"
+ assert len(calls) == 2 and sleeps == [1.0]
+
+
+def test_call_with_retry_gives_up_on_a_permanent_error_immediately():
+ calls = []
+
+ def gone():
+ calls.append(1)
+ raise _status_error(404)
+
+ with pytest.raises(httpx.HTTPStatusError):
+ call_with_retry(gone, sleep=lambda s: None)
+ assert len(calls) == 1
+
+
+def test_call_with_retry_spends_the_budget_then_raises():
+ calls = []
+
+ def down():
+ calls.append(1)
+ raise httpx.ConnectError("down")
+
+ with pytest.raises(httpx.ConnectError):
+ call_with_retry(down, sleep=lambda s: None)
+ assert len(calls) == FETCH_ATTEMPTS
diff --git a/workers/model-pixal3d/test_storage_backend.py b/workers/model-pixal3d/test_storage_backend.py
new file mode 100644
index 000000000..fa6d14adb
--- /dev/null
+++ b/workers/model-pixal3d/test_storage_backend.py
@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import json
+import uuid
+
+import pytest
+
+from storage_backend import LocalStorage, normalize_task_id
+
+
+def test_task_round_trip_survives_process_memory(tmp_path):
+ storage = LocalStorage(tmp_path)
+ task_id = str(uuid.uuid4())
+ task = {"task_id": task_id, "status": "done", "updated_at": 123.0}
+
+ path = storage.write_task(task)
+
+ assert path == tmp_path / "tasks" / f"{task_id}.json"
+ assert storage.read_task(task_id) == task
+ assert json.loads(path.read_text()) == task
+
+
+def test_result_is_written_to_the_mounted_volume(tmp_path):
+ storage = LocalStorage(tmp_path)
+ task_id = str(uuid.uuid4())
+ payload = b"glTF" + bytes(range(32))
+
+ path = storage.write_result(task_id, payload)
+
+ assert path == tmp_path / "results" / f"{task_id}.glb"
+ assert path.read_bytes() == payload
+
+
+ "task_id",
+ ["../escape", "not-a-uuid", "{00000000-0000-0000-0000-000000000000}", "00000000-0000-0000-0000-000000000000/mesh"],
+)
+def test_task_ids_cannot_escape_the_output_volume(task_id):
+ with pytest.raises(ValueError):
+ normalize_task_id(task_id)
+
+
+def test_atomic_writes_leave_no_temporary_files(tmp_path):
+ storage = LocalStorage(tmp_path)
+ task_id = str(uuid.uuid4())
+
+ storage.write_task({"task_id": task_id, "status": "queued"})
+ storage.write_task({"task_id": task_id, "status": "running"})
+ storage.write_result(task_id, b"first")
+ storage.write_result(task_id, b"second")
+
+ assert storage.read_task(task_id)["status"] == "running"
+ assert storage.result_path(task_id).read_bytes() == b"second"
+ assert list(tmp_path.rglob("*.tmp")) == []
diff --git a/workers/model-pixal3d/worker_security.py b/workers/model-pixal3d/worker_security.py
new file mode 100644
index 000000000..802e1c32d
--- /dev/null
+++ b/workers/model-pixal3d/worker_security.py
@@ -0,0 +1,320 @@
+"""
+Shared security helpers for the three.ws GPU/CPU workers.
+
+This module is intentionally dependency-light (stdlib only) so it can be
+COPYed verbatim into every worker's Docker build context. The same canonical
+file lives in each worker directory; keep them byte-identical when editing.
+
+It provides three primitives that every worker needs:
+
+ 1. ``require_api_key`` - constant-time bearer-token check (timing-safe).
+ 2. ``fetch_remote_bytes`` - SSRF-hardened HTTP(S) fetch of caller-supplied
+ URLs: https-only, DNS resolution with private/loopback/link-local/metadata
+ IP rejection, per-hop redirect re-validation, and a bounded response size.
+ 3. ``safe_error`` - turns an exception into an opaque, correlation-id-tagged
+ message safe to persist/return to callers, after logging the full
+ traceback server-side only.
+"""
+
+from __future__ import annotations
+
+import hmac
+import ipaddress
+import logging
+import asyncio
+import socket
+import time
+import uuid
+from typing import Iterable, Optional
+from urllib.parse import urlsplit
+
+import httpx
+
+log = logging.getLogger("worker_security")
+
+# ── auth ────────────────────────────────────────────────────────────────────────
+
+
+def require_api_key(authorization: Optional[str], api_key: str) -> None:
+ """Validate a ``Bearer <token>`` header in constant time.
+
+ Raises ``PermissionError`` on any failure so callers can translate it into
+ the framework's 401 (FastAPI workers map this to HTTPException(401)).
+ """
+ # Fail closed on an empty configured key: with api_key == "" a bare
+ # "Bearer " header would otherwise strip to "" and compare equal.
+ if not api_key:
+ raise PermissionError("worker api key not configured")
+ if not authorization or not authorization.startswith("Bearer "):
+ raise PermissionError("missing bearer token")
+ token = authorization[len("Bearer "):].strip()
+ if not token:
+ raise PermissionError("missing bearer token")
+ # Compare bytes: hmac.compare_digest is timing-safe, and on str operands it
+ # raises TypeError for non-ASCII input, which would surface as a 500.
+ if not hmac.compare_digest(token.encode("utf-8"), api_key.encode("utf-8")):
+ raise PermissionError("invalid api key")
+
+
+# ── SSRF-hardened fetch ─────────────────────────────────────────────────────────
+
+# Default cap on a fetched response. Avatar selfies / driving audio / raw meshes
+# are comfortably under this; anything larger is almost certainly abuse.
+DEFAULT_MAX_BYTES = 64 * 1024 * 1024 # 64 MiB
+_MAX_REDIRECTS = 4
+
+# Transient fetch failures are retried: a dropped connection, a timeout, or a
+# 429/5xx from the image host. The public R2 dev endpoint that serves every
+# forge reference image drops connections under load ("Server disconnected
+# without sending a response"), and before this retry each drop ended a
+# generation as an opaque internal error on TripoSG and Hunyuan3D (about 20 a
+# week measured 2026-10-09). Refusals (UnsafeUrlError), oversize bodies, and
+# other 4xx answers are final and never retried.
+_FETCH_ATTEMPTS = 3
+_FETCH_BACKOFF_SECS = (0.5, 1.5)
+
+# Hosts that enforce a User-Agent policy refuse httpx's default
+# "python-httpx/<version>": upload.wikimedia.org answers it with 403 Forbidden
+# and serves the same image to a descriptive agent (measured 2026-10-09, when
+# model-triposg failed every job whose reference photo was a Wikimedia link).
+# Callers may still pass their own User-Agent; it replaces this one.
+DEFAULT_USER_AGENT = "three.ws-worker/1.0 (+https://three.ws)"
+
+
+def _fetch_headers(headers: Optional[dict]) -> dict:
+ """Caller headers over the default User-Agent, matched case-insensitively."""
+ merged = dict(headers or {})
+ if not any(str(k).lower() == "user-agent" for k in merged):
+ merged["User-Agent"] = DEFAULT_USER_AGENT
+ return merged
+
+
+class UnsafeUrlError(ValueError):
+ """Raised when a URL targets a disallowed scheme or a private/internal IP."""
+
+
+def _is_blocked_ip(ip: ipaddress._BaseAddress) -> bool:
+ """Reject any address that could reach internal infrastructure.
+
+ Covers loopback, RFC1918 private ranges, link-local (incl. the cloud
+ metadata server at 169.254.169.254), unique-local IPv6 (fc00::/7),
+ multicast, reserved, unspecified, and any other non-global address (CGNAT
+ 100.64.0.0/10 included). IPv4-mapped IPv6 addresses
+ are unwrapped first so a mapped private v4 can't slip through.
+ """
+ if isinstance(ip, ipaddress.IPv6Address) and ip.ipv4_mapped is not None:
+ ip = ip.ipv4_mapped
+ return (
+ ip.is_private
+ or ip.is_loopback
+ or ip.is_link_local
+ or ip.is_multicast
+ or ip.is_reserved
+ or ip.is_unspecified
+ # Anything not globally routable, which also covers the CGNAT shared
+ # space 100.64.0.0/10 that is_private does not flag.
+ or not ip.is_global
+ )
+
+
+def _resolve_safe_host(host: str) -> None:
+ """DNS-resolve ``host`` and raise UnsafeUrlError if ANY address is internal.
+
+ Resolving and checking every returned address closes the gap where a name
+ resolves to both a public and a private address.
+ """
+ if not host:
+ raise UnsafeUrlError("missing host")
+ try:
+ infos = socket.getaddrinfo(host, None, proto=socket.IPPROTO_TCP)
+ except socket.gaierror as exc:
+ raise UnsafeUrlError(f"could not resolve host: {host}") from exc
+
+ addrs = {info[4][0] for info in infos}
+ if not addrs:
+ raise UnsafeUrlError(f"no addresses for host: {host}")
+ for addr in addrs:
+ ip = ipaddress.ip_address(addr)
+ if _is_blocked_ip(ip):
+ raise UnsafeUrlError(f"host resolves to a disallowed address: {host}")
+
+
+def assert_safe_url(url: str, *, allow_http: bool = False) -> str:
+ """Validate scheme + resolved IPs for a single URL. Returns it unchanged.
+
+ https is required by default; ``allow_http`` exists only for callers that
+ legitimately need cleartext (not used by the workers).
+ """
+ parts = urlsplit(url)
+ scheme = parts.scheme.lower()
+ allowed = ("https", "http") if allow_http else ("https",)
+ if scheme not in allowed:
+ raise UnsafeUrlError(f"scheme not allowed: {scheme or '(none)'}")
+ if not parts.hostname:
+ raise UnsafeUrlError("missing host")
+ _resolve_safe_host(parts.hostname)
+ return url
+
+
+def fetch_remote_bytes(
+ url: str,
+ *,
+ timeout: float = 30.0,
+ max_bytes: int = DEFAULT_MAX_BYTES,
+ allow_http: bool = False,
+ headers: Optional[dict] = None,
+) -> bytes:
+ """Fetch ``url`` safely and return its body bytes.
+
+ Hardening applied:
+ * https-only (unless ``allow_http``).
+ * every URL - including each redirect target - is DNS-resolved and
+ rejected if it maps to a private/loopback/link-local/metadata address.
+ * redirects are followed manually (max ``_MAX_REDIRECTS``) so each hop is
+ re-validated; httpx's own redirect following is disabled.
+ * the response body is streamed and aborted once it exceeds ``max_bytes``.
+ * transient failures (dropped connection, timeout, 429/5xx) are retried
+ with a short backoff; see ``_FETCH_ATTEMPTS``.
+
+ Raises ``UnsafeUrlError`` for disallowed targets and ``httpx.HTTPError`` /
+ ``ValueError`` for transport or size failures.
+ """
+ for attempt in range(_FETCH_ATTEMPTS - 1):
+ try:
+ return _fetch_once(
+ url, timeout=timeout, max_bytes=max_bytes,
+ allow_http=allow_http, headers=headers,
+ )
+ except httpx.HTTPError as exc:
+ if not _is_transient(exc):
+ raise
+ log.warning("transient fetch failure (attempt %d): %s", attempt + 1, type(exc).__name__)
+ time.sleep(_FETCH_BACKOFF_SECS[attempt])
+ return _fetch_once(
+ url, timeout=timeout, max_bytes=max_bytes,
+ allow_http=allow_http, headers=headers,
+ )
+
+
+def _is_transient(exc: httpx.HTTPError) -> bool:
+ if isinstance(exc, httpx.HTTPStatusError):
+ code = exc.response.status_code
+ return code == 429 or code >= 500
+ return isinstance(exc, httpx.TransportError)
+
+
+def _fetch_once(
+ url: str,
+ *,
+ timeout: float,
+ max_bytes: int,
+ allow_http: bool,
+ headers: Optional[dict],
+) -> bytes:
+ current = assert_safe_url(url, allow_http=allow_http)
+ with httpx.Client(follow_redirects=False, timeout=timeout) as client:
+ for _ in range(_MAX_REDIRECTS + 1):
+ with client.stream("GET", current, headers=_fetch_headers(headers)) as resp:
+ if resp.is_redirect:
+ location = resp.headers.get("location")
+ if not location:
+ raise UnsafeUrlError("redirect without Location header")
+ current = assert_safe_url(
+ str(resp.url.join(location)), allow_http=allow_http
+ )
+ continue
+ resp.raise_for_status()
+ declared = resp.headers.get("content-length")
+ if declared is not None and declared.isdigit() and int(declared) > max_bytes:
+ raise ValueError(f"response too large: {declared} bytes")
+ chunks: list[bytes] = []
+ total = 0
+ for chunk in resp.iter_bytes(65536):
+ total += len(chunk)
+ if total > max_bytes:
+ raise ValueError(f"response exceeded {max_bytes} bytes")
+ chunks.append(chunk)
+ return b"".join(chunks)
+ raise UnsafeUrlError(f"too many redirects (>{_MAX_REDIRECTS})")
+
+
+async def fetch_remote_bytes_async(
+ client: "httpx.AsyncClient",
+ url: str,
+ *,
+ max_bytes: int = DEFAULT_MAX_BYTES,
+ allow_http: bool = False,
+ headers: Optional[dict] = None,
+) -> bytes:
+ """Async variant of ``fetch_remote_bytes`` using a caller-provided client.
+
+ The provided ``client`` MUST be constructed with ``follow_redirects=False``
+ so this function can re-validate each redirect hop itself. Transient
+ failures are retried exactly as in the sync variant.
+ """
+ for attempt in range(_FETCH_ATTEMPTS - 1):
+ try:
+ return await _fetch_once_async(
+ client, url, max_bytes=max_bytes,
+ allow_http=allow_http, headers=headers,
+ )
+ except httpx.HTTPError as exc:
+ if not _is_transient(exc):
+ raise
+ log.warning("transient fetch failure (attempt %d): %s", attempt + 1, type(exc).__name__)
+ await asyncio.sleep(_FETCH_BACKOFF_SECS[attempt])
+ return await _fetch_once_async(
+ client, url, max_bytes=max_bytes,
+ allow_http=allow_http, headers=headers,
+ )
+
+
+async def _fetch_once_async(
+ client: "httpx.AsyncClient",
+ url: str,
+ *,
+ max_bytes: int,
+ allow_http: bool,
+ headers: Optional[dict],
+) -> bytes:
+ current = assert_safe_url(url, allow_http=allow_http)
+ for _ in range(_MAX_REDIRECTS + 1):
+ async with client.stream("GET", current, headers=_fetch_headers(headers)) as resp:
+ if resp.is_redirect:
+ location = resp.headers.get("location")
+ if not location:
+ raise UnsafeUrlError("redirect without Location header")
+ current = assert_safe_url(
+ str(resp.url.join(location)), allow_http=allow_http
+ )
+ continue
+ resp.raise_for_status()
+ declared = resp.headers.get("content-length")
+ if declared is not None and declared.isdigit() and int(declared) > max_bytes:
+ raise ValueError(f"response too large: {declared} bytes")
+ chunks: list[bytes] = []
+ total = 0
+ async for chunk in resp.aiter_bytes(65536):
+ total += len(chunk)
+ if total > max_bytes:
+ raise ValueError(f"response exceeded {max_bytes} bytes")
+ chunks.append(chunk)
+ return b"".join(chunks)
+ raise UnsafeUrlError(f"too many redirects (>{_MAX_REDIRECTS})")
+
+
+# ── opaque error handling ───────────────────────────────────────────────────────
+
+
+def safe_error(exc: BaseException, *, context: str = "") -> str:
+ """Log the full traceback server-side and return an opaque client message.
+
+ Never leak ``traceback.format_exc()`` (absolute paths, library versions,
+ internal hostnames, fragments of upstream responses) to callers. A short
+ correlation id is embedded in both the log line and the returned string so
+ operators can join a client-reported failure to the server log.
+ """
+ correlation_id = uuid.uuid4().hex[:12]
+ label = f"{context} " if context else ""
+ log.exception("%serror [correlation_id=%s]", label, correlation_id)
+ return f"internal error (ref {correlation_id})"