v0.1.4 — keep_warm widget + memory hygiene + upstream roadmap

Targeted refactor after auditing the visualbruno/ComfyUI-Trellis2 pixal3d branch recent commits. No node-API breakage — drop-in over v0.1.3.

What's new

keep_warm widget on Pixal3DImageToMesh

New BOOLEAN widget (default True). When False, the ~14 GB Pixal3D pipeline singleton is freed at the end of the run instead of being kept resident. Default preserves prior behavior (warm singleton → next call ~3 min; cold → ~7-10 min).

Use keep_warm=False when you have a single Pixal3D-then-other-stuff workflow and want the VRAM back without queuing a separate Pixal3D: Free Pipeline node.

Tighter memory hygiene in the post-sampling stages

run_pixal3d now drops latent / mesh references in the right order so peak VRAM during mesh extraction has the most possible headroom:

• tex_slat (larger) is freed before shape_slat
• mesh_list is dropped after the single mesh is taken
• raw mesh (vertices, coords, voxel attrs — ~1-2 GB on 1536_cascade) freed after GLB bake
• explicit gc.collect() + torch.cuda.empty_cache() between stages

No behavior change — just earlier release of references we no longer need.

README: upstream roadmap section

Documents the TRELLIS2 pixal3d branch in flight — use_tiled_decoder, expanded pipeline_type, per-stage memory management, standard natten 0.21.6 wheel — so anyone reading the docs knows what's coming and why this plugin stays on 1024_cascade defaults for now.

Memory + performance table refreshed

Bundled-workflow row added; 1536_cascade OOM ceiling explicitly called out (~30 GB Pixal3D models + ~16 GB comfy-aimdo cast buffer = 46 GB > 34 GB on a 5090).

What we deliberately didn't change

TRELLIS2's per-stage memory wins come from calling Pixal3D's pipeline sub-methods directly across separate ComfyUI nodes. Our plugin uses pipeline.run() monolithically — same model, same outputs, different control surface. The use_tiled_decoder knob also lives in TRELLIS2's wrapper layer, not in Tencent's Pixal3D pipeline itself. Both of those become accessible to us only when:

1. Tencent's upstream pixal3d/pipelines/pixal3d_image_to_3d.py exposes the tiled-decoder hook, OR
2. We rewrite our run_pixal3d to call Pixal3D's sub-methods (SS / shape / tex / decoders) directly, like TRELLIS2's wrapper does.

Option 2 is a significant rewrite and would couple us tightly to Pixal3D's internal API. Holding off until upstream lands either.

Full diff: v0.1.3...v0.1.4