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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
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.jsindex 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.jsindex 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.jsindex 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.jsindex 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsindex 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/Dockerfilenew file mode 100644index 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.mdnew file mode 100644index 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.pynew file mode 100644index 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.yamlnew file mode 100644index 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.pynew file mode 100644index 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, Truediff --git a/workers/model-pixal3d/instance_health.py b/workers/model-pixal3d/instance_health.pynew file mode 100644index 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_afterdiff --git a/workers/model-pixal3d/main.py b/workers/model-pixal3d/main.pynew file mode 100644index 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)++[email protected]("/")+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"],+ }++[email protected]("/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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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 lastdiff --git a/workers/model-pixal3d/stage_weights.sh b/workers/model-pixal3d/stage_weights.shnew file mode 100755index 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}"+fidiff --git a/workers/model-pixal3d/storage_backend.py b/workers/model-pixal3d/storage_backend.pynew file mode 100644index 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 pathdiff --git a/workers/model-pixal3d/test_app_contract.py b/workers/model-pixal3d/test_app_contract.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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_ATTEMPTSdiff --git a/workers/model-pixal3d/test_storage_backend.py b/workers/model-pixal3d/test_storage_backend.pynew file mode 100644index 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.pynew file mode 100644index 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})"