@melite/models-trellis2-native 0.1.4-alpha → 0.1.5-pre-alpha

package/README.md

@@ -0,0 +1,36 @@
+---
+description: TRELLIS.2 Native family — background-removed image to textured GLB through voxel structure, shape, and texture stages, with the mesh action on the ComfyUI engine.
+kind: package-library
+---
+
+# @melite/models-trellis2-native
+
+`@melite/models-trellis2-native` is the model family package for TRELLIS.2 on native ComfyUI (`form_img_to_mesh`, genre 3d): background-removed conditioning flows to a voxel structure, a shape latent, and a texture atlas, saved as a `.glb`. The DECL declares the `mesh` action, a three-resolution variant rail, and the five-file lift-chain provisioning. The estate boot mounts it as a Cordis plugin through `ctx.models.registerFamily` inside `ctx.effect`; the img-to-mesh card binds the action. The lane is this package's own `actions.ts`, pinned to committed goldens.
+
+## Declaration
+
+Variants: `1024` (default; BF16 at ~12 GB VRAM peak or INT8 ConvRot at ~8 GB), `1536` (hero quality; 16/10 GB), and a hidden fast `512`. Family defaults fix the sampler table (euler/normal structure and shape, euler/simple then euler/normal texture), `steps` 12 / `shape_steps` 20, `cfg` 7.5, remesh at 768 faces decimated to 700k, atlas 4096, AO 1024, normal 2048, `sd3_shift` 5, and `seed` 42. The `mesh` action requires `input_image` — the 3D lift is image-conditioned and takes no text prompt — and its facts door refuses any of the five load keys missing: `unet`, `vae`, `texture_vae`, `clip_vision`, `background_removal`. Provisions pin the weights, including `birefnet.safetensors` from Comfy-Org's BiRefNet repo for background removal. The build runs structure, shape, upsample, remesh, texture, and the atlas/AO/normal bakes, then saves through `MeshToFile3D` + `Save3DAdvanced`.
+
+## Model Experience
+
+### Request context and condition
+
+#### What the model sees
+
+- **input_image** — required; the source image the lift conditions on.
+- **resolution / bg_removal** — the closed variant table and the birefnet on/off/auto pick.
+- **sampler rows and seed** — the per-stage sampler/scheduler/steps/cfg table and the sentinel-minted seed.
+
+#### Token effect
+
+Zero-direct token effect — the fields ride the composed ComfyUI graph; no harness context is spent.
+
+#### KV Cache effect
+
+Independent — each mesh run is its own engine request; no shared prefix.
+
+## Known Limitations and Deferred Work
+
+- **No text conditioning** — the lane accepts no prompt; shape intent must come from the image alone.
+- **VRAM peaks are cell-declared** — the 8–16 GB figures are the DECL's measured rows, not runtime guarantees on every GPU.
+- **Image quality ceiling** — background removal and texture fidelity are not verified against the running engine.

package/lib/actions.d.ts

@@ -7,7 +7,6 @@ export type MeshFacts = {
     readonly vae: string;
     readonly texture_vae: string;
     readonly clip_vision: string;
-    readonly background_removal: string;
 };
 /** The gated params doc the mesh segment reads (the card's schema
  * walk validated types and bounds — a same-process typed boundary;
@@ -21,6 +20,6 @@ export type MeshParams = Record<string, unknown>;
  *  @returns the typed facts the segment factory reads */
 export declare function parseMeshFacts(raw: LaneInputsFacts): MeshFacts;
 /** The mesh action: trellis_t1 — DINOv3 conditioning (the image IS
- * the prompt; negative = ConditioningZeroOut). */
+ * the prompt; the negative is the conditioning's own output 1). */
 export declare const mesh: ComfyActionSpec<MeshParams, MeshFacts>;
 //# sourceMappingURL=actions.d.ts.map

package/lib/actions.js

@@ -1,5 +1,5 @@
 import { requireText } from "@melite/comfyui-card-kit/facts";
-import { MESH_RESOLUTIONS, MESH_BG_MODES, MESH_ATLAS_SIZES, MESH_AO_SIZES, MESH_NORMAL_SIZES } from "@melite/comfyui-card-kit";
+import { MESH_RESOLUTIONS, MESH_ATLAS_SIZES, MESH_AO_SIZES, MESH_NORMAL_SIZES, admitMeshLiftShared, isSpell } from "@melite/comfyui-card-kit";
 import { SAMPLER_OPTIONS, SCHEDULER_OPTIONS } from "@melite/comfyui-card-kit/vocab";
 /** The mesh facts door: the resolved lane_inputs parsed into the
  * closed shape — a missing load key refuses field-named here,
@@ -12,39 +12,19 @@ export function parseMeshFacts(raw) {
         vae: requireText(raw, 'vae', 'trellis2-native mesh'),
         texture_vae: requireText(raw, 'texture_vae', 'trellis2-native mesh'),
         clip_vision: requireText(raw, 'clip_vision', 'trellis2-native mesh'),
-        background_removal: requireText(raw, 'background_removal', 'trellis2-native mesh'),
     };
 }
-const isSpell = (s) => s.startsWith('$');
-/** The lift arms' admission slice for THIS family (moved verbatim
- * from the kit's admitMeshLift — the required image and closed
- * sets refuse HERE, never in the schema): the source image,
- * resolution, bg mode, the bake-size table
- * (the pixal-only camera_fov row is pixal's, not ours). */
-function admitMeshLift(p) {
-    if (!String(p.input_image || '').trim()) {
-        throw new Error(`required param 'input_image' (Source image) missing on the img-to-mesh card — the 3D lift is image-conditioned (no text prompt rides this lane)`);
-    }
-    const MESH_RESOLUTIONS = ['1024', '1536'];
-    const MESH_BG_MODES = ['auto', 'on', 'off'];
-    const MESH_BAKE_SIZES = [
-        ['atlas_size', ['2048', '4096']],
-        ['ao_size', ['512', '1024']],
-        ['normal_size', ['1024', '2048']],
-    ];
-    if (!MESH_RESOLUTIONS.includes(String(p.resolution))) {
-        throw new Error(`resolution ${JSON.stringify(p.resolution)} is not one of ${MESH_RESOLUTIONS.join('|')} — the variant table is closed`);
-    }
-    const bg = String(p.bg_removal || 'auto');
-    if (!MESH_BG_MODES.includes(bg)) {
-        throw new Error(`bg_removal ${JSON.stringify(bg)} is not one of auto|on|off — birefnet either cuts or it doesn't`);
-    }
-    for (const [k, opts] of MESH_BAKE_SIZES) {
-        if (!opts.includes(String(p[k]))) {
-            throw new Error(`${k} ${JSON.stringify(p[k])} is not one of ${opts.join('|')} — the bake-size table is closed`);
-        }
-    }
-}
+/** The wired-tensor law (the lanes-image precedent, ported 1:1):
+ *  a '$name' value names an upstream stage's wired output — the
+ *  spell IS the tensor and rides node inputs verbatim. ROW-4
+ *  refuses producer links in Load* file slots, so a spelled image
+ *  NEVER builds a loader; file paths keep the disk handoff. */
+/** The lift arms' admission slice for THIS family: the SHARED kit
+ *  seat (the dry-sweep's J4 re-hoist — two families carried this
+ *  verbatim; the required image and closed sets refuse in the
+ *  slice, never in the schema). This family adds no private arm
+ *  (the pixal-only camera_fov row is pixal's, not ours). */
+const admitMeshLift = admitMeshLiftShared;
 /** The dual guided unet + the two VAEs — the lift chain's shared
  * head. Creation order lands the reference renderers' numbering: the SHAPE
  * pair first (CFGOverride.0/RescaleCFG.0), then the STRUCT pair
@@ -74,15 +54,6 @@ function loadLiftHeads(g, li, p) {
     const texVae = g.node('VAELoader', { vae_name: li.texture_vae }).out();
     return { unet, rescaleShape, shifted, shapeVae, texVae };
 }
-/** The birefnet cut (bg_removal auto/on): the cutout MASK from
- * RemoveBackground bridged to IMAGE via MaskToImage (the GPU
- * canary verdict — RemoveBackground outputs MASK, not IMAGE). */
-function cutBackground(g, li, img) {
-    const bgm = g.node('LoadBackgroundRemovalModel', { bg_removal_name: li.background_removal }).out();
-    const mask = g.node('RemoveBackground', { bg_removal_model: bgm, image: img }).out();
-    const src = g.node('MaskToImage', { mask }).out();
-    return { src, mask };
-}
 /** The shared structure→shape→upsample→texture→bake→glb chain
  * (_shared_lift_chain verbatim — the model delta lives
  * ENTIRELY in the conditioning pair passed in). */
@@ -203,7 +174,7 @@ function sharedLiftChain(g, p, heads, pos, neg, prefix) {
     }).out();
 }
 /** The mesh action: trellis_t1 — DINOv3 conditioning (the image IS
- * the prompt; negative = ConditioningZeroOut). */
+ * the prompt; the negative is the conditioning's own output 1). */
 export const mesh = {
     id: "mesh",
     inputs: [],
@@ -220,7 +191,6 @@ export const mesh = {
         { name: "resolution", type: "enum", options: MESH_RESOLUTIONS },
         { name: "steps", type: "number", bounds: [4, 60] },
         { name: "cfg", type: "number", bounds: [1, 15] },
-        { name: "bg_removal", type: "enum", options: MESH_BG_MODES },
         { name: "shape_steps", type: "number", bounds: [4, 60] },
         { name: "shape_cfg", type: "number", bounds: [1, 15] },
         { name: "shape_sampler", type: "enum", options: SAMPLER_OPTIONS },
@@ -262,13 +232,24 @@ export const mesh = {
             ? p.input_image
             : g.node('LoadImage', { image: p.input_image }).out();
         const heads = loadLiftHeads(g, li, p);
-        let condImage = img;
-        if (p.bg_removal !== 'off') {
-            condImage = cutBackground(g, li, img).src;
-        }
+        // THE TEMPLATE HAS NO MASK BRIDGE: the crop eats the photo
+        // (LoadImage) verbatim — a MaskToImage-sourced crop feeds the
+        // silhouette, and the silhouette starves every appearance
+        
+        // IMAGE for its masks leg.
+        const cropped = g.node('ImageCropToMask', {
+            images: img, masks: img,
+            pad_factor: 1.1, width: 1024, height: 1024,
+            // pin autofills leaves in place (core defaults)
+            background: '#000000', grow_mask: 0,
+        }).out();
         const clip = g.node('CLIPVisionLoader', { clip_name: li.clip_vision }).out();
-        const pos = g.node('Trellis2Conditioning', { clip_vision_model: clip, image: condImage }).out(0);
-        const neg = g.node('ConditioningZeroOut', { conditioning: pos }).out();
+        const cond = g.node('Trellis2Conditioning', { clip_vision_model: clip, image: cropped });
+        const pos = cond.out(0);
+        // the negative IS the conditioning's second output — never a
+        // fabricated zero (the zero drops the shared proj pack the
+        // template routes as every pass's negative)
+        const neg = cond.out(1);
         // Family constant, never a knob (compose stamps the prefix
         // internally; stable).
         return sharedLiftChain(g, p, heads, pos, neg, 'trellis2_native');

package/lib/index.d.ts

@@ -1,6 +1,7 @@
 import type { Plugin } from "@deepseek-ai/cordis";
-import type { ModelDecl } from "@melite/comfyui-cordis/model-contract";
+import type { ModelDecl } from '@melite/comfyui-card-kit/model-contract';
 export declare const DECL: ModelDecl;
 export declare const family: Plugin;
 export { mesh } from "./actions.js";
+export { family as default };
 //# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -6,8 +6,13 @@ export const DECL = {
     "description": "Image to textured 3D mesh (native ComfyUI TRELLIS.2): background-removed conditioning → voxel structure → shape latent → texture atlas, saved as a .glb.",
     "engine": "comfyui",
     "defaults": {
+        
+        // standard / quality, defaulting to standard): the floors ARE the
+        // standard tier — 1024 + the template's 768/700k tail (the card
+        // schema carries no remesh default, so this row is the raw-compose
+        // floor; the surviving 1024 lane stamps none, and the quality
+        // recipe's 1536/2048/2M picks override these as patch-only rows).
         "resolution": "1024",
-        "bg_removal": "auto",
         "steps": 12,
         "cfg": 7.5,
         "shape_steps": 20,
@@ -35,7 +40,7 @@ export const DECL = {
         "rescale_shape": 0.5,
         "override_struct": 0.667,
         "override_shape": 0.769,
-        "seed": 42
+        "seed": -1
     },
     "studio": {
         "tenant": "3d/img-to-mesh",
@@ -54,9 +59,11 @@ export const DECL = {
         {
             "id": "1024",
             "label": "1024",
-            "hint": "Standard resolution — DEFAULT",
+            "hint": "Standard resolution — the fast tier",
             "group": "Variant",
             "route": "trellis2-native",
+            // no resolver_defaults — the family defaults row owns
+            // resolution (one value, one owner); this row IS the lane
             "order": 0,
             "cells": [
                 {
@@ -74,77 +81,41 @@ export const DECL = {
                 }
             ]
         },
+        
+        // standard, quality on the img to mesh node, defaulting to
+        // standard"). Resolution rides ONE seat — the family defaults
+        // row's 1024 — so fast and standard leave it unstated and only
+        // quality restates the 1536 pick (the card's closed enum owns
+        // the vocabulary: 1024 | 1536; the hidden 512 lane was
+        // off-envelope and died with its variant row). The remesh tail
+        // rides the family defaults row (the floors ARE the standard —
+        // the h3 precedent: a recipe stamps only what DIFFERS from the
+        // floor). STANDARD is the stamp-less first row: the birth stamp
+        // takes the FIRST Recipe row, so every fresh card lands here
+        // named Standard with the calibration riding as floors.
         {
-            "id": "1536",
-            "label": "1536",
-            "hint": "Quality resolution — hero assets, final production",
-            "group": "Variant",
-            "route": "trellis2-native-1536",
-            "order": 2,
-            "resolver_defaults": { "resolution": "1536" },
-            "cells": [
-                {
-                    "quant": "bf16",
-                    "label": "BF16",
-                    "hide_from_dropdown": true,
-                    "route": "trellis2-native-1536-bf16",
-                    "vram_peak_gb": 16,
-                },
-                {
-                    "quant": "int8",
-                    "label": "INT8 ConvRot",
-                    "route": "trellis2-native-1536-int8",
-                    "vram_peak_gb": 10,
-                }
-            ]
-        },
-        {
-            "id": "512",
-            "label": "512",
-            "hint": "Fast resolution — props, thumbnails, iteration",
-            "group": "Variant",
-            "route": "trellis2-native-512",
-            "order": 1,
-            "hide_from_dropdown": true,
-            "cells": [
-                {
-                    "quant": "bf16",
-                    "label": "BF16",
-                    "hide_from_dropdown": true,
-                    "route": "trellis2-native-512-bf16",
-                    "vram_peak_gb": 8,
-                },
-                {
-                    "quant": "int8",
-                    "label": "INT8 ConvRot",
-                    "route": "trellis2-native-512-int8",
-                    "vram_peak_gb": 5,
-                }
-            ]
-        },
-        {
-            "id": "fast_mesh",
-            "label": "Fast Mesh",
-            "hint": "Remesh 128 + 10k faces — the card schema's own floors (lightest preview mesh).",
+            "id": "standard",
+            "label": "Standard",
+            "hint": "The default — the official template's calibration as the floor: 1024 + remesh 768 + 700k faces; fits a 24GB card.",
             "group": "Recipe",
-            "wire_defaults": { "remesh_resolution": 128, "decimate_faces": 10000 },
             "cells": [],
         },
         {
-            "id": "hero_mesh",
-            "label": "Hero Mesh",
-            "hint": "Remesh 2048 + 2M faces — the card schema's own ceilings (densest hero mesh).",
+            "id": "fast",
+            "label": "Fast",
+            "hint": "Preview tier — remesh 128 + 10k faces at the same 1024 floor; the lightest mesh that still unwraps.",
             "group": "Recipe",
-            "wire_defaults": { "remesh_resolution": 2048, "decimate_faces": 2000000 },
+            "wire_defaults": { "remesh_resolution": 128, "decimate_faces": 10000 },
             "cells": [],
         },
         {
-            "id": "default",
-            "label": "Default",
-            "hint": "The family default — no extra stamps; a fresh card lands here.",
+            "id": "quality",
+            "label": "Quality",
+            "hint": "Hero assets — resolution 1536 + remesh 2048 + 2M faces; RemeshMesh wants ~3.6 GiB over a ~19 GiB resident chain (32GB+ VRAM only).",
             "group": "Recipe",
+            "wire_defaults": { "resolution": "1536", "remesh_resolution": 2048, "decimate_faces": 2000000 },
             "cells": [],
-        }
+        },
     ],
     "variant_groups": [
         {
@@ -158,8 +129,8 @@ export const DECL = {
         {
             "id": "Recipe",
             "label": "Recipe",
-            "tooltip": "One-click recipes — patch-only rows that stamp picks onto the draft; Default stamps nothing.",
-            "default": "default"
+            "tooltip": "One-click mesh tiers — patch-only rows: Fast (preview tail), Standard (the calibrated default), Quality (1536 hero pass).",
+            "default": "standard"
         }
     ],
     "provisions": [
@@ -190,22 +161,39 @@ export const DECL = {
             "folder": "clip_vision",
             "sha256": "5cb785e458de7c460579082418af81f5c62380c181599344bdc60898c63468ee",
             "size_bytes": 1212559776
-        },
-        {
-            "name": "birefnet.safetensors",
-            "url": "https://huggingface.co/Comfy-Org/BiRefNet/resolve/main/background_removal/birefnet.safetensors",
-            "folder": "background_removal",
-            "sha256": "9ab37426bf4de0567af6b5d21b16151357149139362e6e8992021b8ce356a154",
-            "size_bytes": 444473596
         }
     ],
     "lane_inputs": {
-        "background_removal": "birefnet.safetensors",
         "clip_vision": "dino_v3_vit_l.safetensors",
         "texture_vae": "trellis_2_texture_vae_bf16.safetensors",
         "unet": "trellis_2_int8_convrot.safetensors",
         "vae": "trellis_2_shape_vae_bf16.safetensors"
     },
+    // THE DECLARED HOME (the lane-presence cure): the store folder this
+    // pack-specific lane file lives in — the run gate probes it at press
+    // instead of dying untyped at the engine.
+    "lane_homes": { "texture_vae": "vae" },
+    // THE LANE SURFACE (the z-image precedent): exactly the knobs the
+    // img-to-mesh card serves — the mesh lift, its shape/texture
+    // passes, the remesh/decimate tail, and the per-pass sampler pairs.
+    "params": [
+        "input_image", "rigged_glb", "target_glb",
+        "seed", "resolution", "steps", "cfg",
+        "camera_fov",
+        "shape_steps", "shape_cfg", "tex1_steps", "tex1_cfg",
+        "tex2_steps", "tex2_cfg",
+        "remesh_resolution", "remesh_qef", "remesh_drop_inverted",
+        "remesh_drop_enclosed", "remesh_fix_poles",
+        "decimate_faces", "smooth_angle",
+        "atlas_size", "ao_size", "normal_size",
+        "struct_sampler", "struct_scheduler",
+        "shape_sampler", "shape_scheduler",
+        "tex1_sampler", "tex1_scheduler",
+        "tex2_sampler", "tex2_scheduler",
+        "sd3_shift",
+        "rescale_struct", "rescale_shape",
+        "override_struct", "override_shape",
+    ],
     // the mesh action the img-to-mesh card binds (the trellis_t1
     // lane tree).
     "actions": [mesh],
@@ -218,4 +206,9 @@ export const family = {
     },
 };
 export { mesh } from "./actions.js";
+// The Loader-row face: DSH loads plugin rows by bare specifier and
+// unwraps `exports.default ?? exports` (vendor/cordis_plugins/loader
+// unwrapExports) — the default export IS the row-loadable plugin. The
+// named `family` stays the library face (engine loadFamilies).
+export { family as default };
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@melite/models-trellis2-native",
-  "version": "0.1.4-alpha",
+  "version": "0.1.5-pre-alpha",
   "license": "SSPL-1.0",
   "type": "module",
   "exports": {
@@ -11,8 +11,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@melite/comfyui-card-kit": "0.1.4-alpha",
-    "@melite/comfyui-cordis": "0.1.4-alpha"
+    "@melite/comfyui-card-kit": "0.1.5-pre-alpha"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",