ComfyUI-BrainDead

---

🎯 About BrainDead Nodes

AN internally-used node pack for Biloxi Studios designed to help with character, story, 3D, and audio generation for next-generation UGC game and TV pipelines. All nodes use the ComfyUI V3 API and appear under the 🧠BrainDead category in the node browser.

---

Workflow Templates

Eighteen ready-to-use workflows ship in example_workflows/ and appear in ComfyUI under Workflow → Browse Templates → ComfyUI-BrainDead, each with a thumbnail and an in-canvas note.

Templates appear in Workflow → Browse Templates → ComfyUI-BrainDead and are prefixed BD- so they're easy to find and identify as BrainDead workflow templates.

---

Installation

ComfyUI Manager

Search for "BrainDead" in ComfyUI Manager and install. Dependencies in requirements.txt are installed automatically.

Manual Installation

cd ComfyUI/custom_nodes
git clone https://github.com/BizaNator/ComfyUI-BrainDead
cd ComfyUI-BrainDead
pip install -r requirements.txt

Dependencies

requirements.txt is installed automatically by ComfyUI Manager. It covers:

Pixal3D model weights (~10 GB) are downloaded automatically on first run. cube_part is vendored under nodes/cubepart/vendor/ — no separate install needed.

---

Features

Cache Nodes (🧠BrainDead/Cache)

Smart caching with lazy evaluation — upstream nodes are completely SKIPPED when cache is valid.

How Caching Works:

1. Place a cache node after an expensive operation
2. First run: generates data, saves to output/BrainDead_Cache/
3. Subsequent runs: loads from cache, skips upstream generation entirely
4. Change the seed to force regeneration

Save Context System — replace ad-hoc concat-string filename chains:

1. Add ONE BD Save Context node with a template like %project%/%character%/%character%_%name%_v%version%%suffix% and set vars (character, name, version, project, etc.)
2. Downstream BD Save File / BD Bulk Save nodes auto-pick the context (or specify context_id if multiple are registered)
3. Each save just sets its suffix (e.g. _albedo, _skin_mask, _head) — context resolves the rest
4. Per-save custom_vars (multiline key=value) layer on top of the context for one-off variations like subfolder=PBR or materials=metal
5. BD Get Context Path outputs a STRING path for ANY save node — works with ComfyUI's built-in SaveImage and third-party packs

Character Nodes (🧠BrainDead/Character)

Advanced tools for maintaining character consistency with Qwen-Image models.

Features:

• Customizable system prompts for character consistency
• Multi-image support (up to 3 reference images)
• Per-image weight and role control
• Identity-focused templates that prioritize facial features

Mesh Nodes (🧠BrainDead/Mesh)

3D mesh processing, color sampling, simplification, and PBR texture baking tools.

Mesh types — TRIMESH vs native MESH: BD nodes pass meshes as TRIMESH (a full trimesh.Trimesh carrying vertex colors, UVs, materials, and processing/export) — the same type TRELLIS2 / Hunyuan3d-2-1 / GeometryPack use. ComfyUI's built-in 3D nodes use the native MESH type, a thin batched (vertices, faces) tensor container with no colors/UVs. They're different data models, not interchangeable. Use BD Trimesh → MESH / BD MESH → Trimesh to bridge when you need a built-in 3D node — but keep work inside TRIMESH (and BD Export Mesh With Colors) whenever colors/UVs must survive, since native MESH can't represent them.

OVoxel Baking Pipeline:

[TRELLIS2 Texture] → voxelgrid → [BD OVoxel Bake] → mesh + PBR textures
                                       OR
[TRELLIS2 Texture] → voxelgrid → [BD OVoxel Texture Bake]
                          ↑ mesh → [BD Blender Decimate] → [BD UV Unwrap] ↗

VXZ Caching Pipeline:

[TRELLIS2 Texture] → voxelgrid → [BD Export OVoxel] → saved .vxz + .mesh.npz
                                                            ↓
[BD Load OVoxel] → voxelgrid → [BD OVoxel Bake] → re-bake without regenerating

Blender Nodes (🧠BrainDead/Blender)

Advanced mesh processing using Blender's geometry tools (requires Blender 5.0+, bundled in lib/).

Hard Edge Preservation Pipeline:

[Input Mesh]
    ↓
[BD Planar Grouping] (straighten_boundaries=True)
    ↓ Clean geometric boundaries
[BD Blender Edge Marking] (FROM_COLORS_AND_ANGLE)
    ↓ Mark SHARP/SEAM edges
[BD Blender Merge Planes] (delimit_sharp=True)
    ↓ Dissolve while respecting marks
[Low-poly mesh with hard edges intact]

BD Blender Edge Marking Operations:

• FROM_COLORS: Mark edges where vertex colors differ
• FROM_ANGLE: Mark edges by dihedral angle threshold
• FROM_COLORS_AND_ANGLE: Combine both methods
• CLEAR: Remove existing edge marks

BD Blender Merge Planes Features:

• Delimit options: Respect SHARP, SEAM, MATERIAL, NORMAL edges
• Dissolve angle: Control coplanar face merging threshold
• Region subdivision: Proportional face density based on area
• Output topology: TRI, QUAD, or NGON output

Prompt Nodes (🧠BrainDead/Prompt)

Iterate through multiple prompts with automatic filename generation, plus per-Run iteration over typed inputs.

Iterator vs Bulk Save: BD Bulk Save (in Cache) saves N files in ONE Run — use when downstream IS just save. BD For Each Run (here) emits one (data, label) per Run — use when downstream is more complex (e.g. per-iteration upscale before save).

Modes:

• sequential: Cycle through prompts in order
• manual: Select specific prompt by index
• random: Shuffle prompts randomly
• single: Always use first prompt

Filename Modes:

• auto_index: base_000, base_001, etc.
• suffix_list: base_front, base_left, etc.
• template: {base}_{index:03d}_{suffix}

Segmentation Nodes (🧠BrainDead/Segmentation)

Character segmentation, parts pipeline, PBR map derivation, asset prep.

Parts pipeline — single-execution character processing using the PARTS_BUNDLE type:

SAM3 multi-prompt + mask cleanup:

Human parser backends (deferred for stylized art — trained on photos):

MediaPipe face masks & guided SAM3:

Face socket / animation textures:

Luma / lighting tools:

Drawing tools:

Mask manipulation:

Asset prep / game textures:

Recommended PBR pipeline using existing depth/normal estimators (DepthAnythingV2 / Lotus / MiDaS / Metric3D — all installed via comfyui_controlnet_aux):

Source character image
  ├─→ ImageToMask (alpha) → silhouette_mask
  ├─→ DepthAnythingV2Preprocessor → depth (IMAGE)
  ├─→ Metric3D-NormalMapPreprocessor → normal_map (optional)
  ├─→ Skin shader alpha → ImageToMask → aux_shading_alpha
  └─→ Manga lineart ControlNet → aux_detail_texture

ALL into BD Derive PBR Maps with metallic_zone_mask=accessories_mask
  → albedo, normal, roughness, metallic, ao, packed_orm, packed_arm

→ BD Bulk Save with labels=albedo,normal,roughness,metallic,ao,orm,arm
   → context auto-pick → 7 files saved in one Run

Recommended character parts pipeline (rebuild + composite via SAM3 + Qwen Image Edit):

[Source IMAGE]
   ├─→ [external VLM, e.g. ComfyUI-QwenVL] → newline-separated part list
   │
   ├─→ BD_Lotus2ModelLoader (depth) → BD_Lotus2Predict → depth_image
   │
   └─→ BD_SAM3MultiPrompt
         ↓ combined_mask, per_prompt_masks
       BD_PartsRefine (iou_threshold=0.7)
         ↓ refined_masks, refined_labels
       BD_PartsBuilder
         masks=refined_masks, labels=refined_labels,
         combined_mask=combined_mask, depth_image=depth
         ↓ parts (PARTS_BUNDLE)
       BD_PartsBatchEdit (Qwen)
         model + clip + vae from your Qwen Image Edit 2509 + Lightning subgraph
         inpaint_mode=flatten_redraw, alpha_after_edit=auto_from_white_bg
         tonemap=2.0, shift=3.0, cfg_norm=0.85 (matches manual recipe)
         ↓ parts (rebuilt) + image_batch
       BD_PartsExport
         composite_size=4096 (or whatever), save_psd=true, save_masks=true
         → per-tag PNGs + composite PNG + layered PSD with optional mask layers

Pixal3D Nodes (🧠BrainDead/Pixal3D)

Image-to-3D generation using Pixal3D (TencentARC/Pixal3D, Trellis2-based). Downloads ~10GB model weights on first run to /srv/AI_Stuff/models/huggingface/.

Pixal3D pipeline:

[Source image + mask]
  ↓
BD Pixal3D Preprocess  (fov_mode=auto_moge)
  ↓ pixal3d_input
BD Pixal3D Image to 3D  (pipeline_type=1024_cascade)
  ↓ mesh              ↓ voxelgrid
BD CuMesh Simplify    BD OVoxelBake → albedo, normal, roughness, metallic

CubePart Nodes (🧠BrainDead/CubePart)

Open-vocabulary, part-controllable 3D decomposition with Roblox CubePart. Give it a mesh and up to 8 free-text part names; it generates one clean mesh per part, canonically aligned for rigging / game engines. The cube_part library is vendored under nodes/cubepart/vendor/ (self-contained — no separate pip package).

Models — paths auto-resolve via ComfyUI folder_paths (respecting extra_model_paths.yaml) and auto-download from HuggingFace on first run if missing (auto_download toggle, default on). Leave model_dir/text_encoder_path empty to auto-resolve, or set an explicit override.

• Roblox/cubepart → cubepart model folder (extra_model_paths.yaml: cubepart: → /srv/AI_Stuff/models/cubepart/; else models/cubepart). multi_part_dit.safetensors ~8.6GB + vae.safetensors ~1.3GB.
• Qwen/Qwen3-VL-4B-Instruct → under the LLM model folder (/srv/AI_Stuff/models/LLM/Qwen3-VL-4B-Instruct/), text encoder loaded offline.

To pre-download instead of relying on first-run auto-download:

huggingface-cli download Roblox/cubepart --local-dir /srv/AI_Stuff/models/cubepart
huggingface-cli download Qwen/Qwen3-VL-4B-Instruct --local-dir /srv/AI_Stuff/models/LLM/Qwen3-VL-4B-Instruct

License: CubePart code is MIT, but the model weights / parent repo are under the CUBE3D RESEARCH-ONLY RAIL-MS license — fine for internal/research use; review before shipping outputs commercially.

CubePart pipeline:

[mesh from Pixal3D / Trellis2 / .glb]
  ↓ mesh
BD CubePart Segment  (parts="body, left wheel, right wheel, ...")
  ↓ parts (TRIMESH_LIST)        ↓ combined (colored preview)
BD CubePart Get Part (index=N)
  ↓ mesh
BD CuMesh Simplify → BD Blender Decimate → export

# Preview all segments at once:
parts ─→ BD Mesh Preview (Thumbnails)   # labeled contact-sheet IMAGE of every part
parts ─→ BD Preview 3D                  # interactive three.js viewer, color-coded

Depth Nodes (🧠BrainDead/Depth)

SOTA monocular geometry prediction.

---

Usage Examples

Cache Expensive Generation

[Expensive Node] → [BD Cache Image] → [Next Node]
                     seed: 42

First run generates and caches. Subsequent runs skip generation.

Character Sheet Workflow

[BD Prompt Iterator (Advanced)]
  prompts: "front view\nleft profile\nright profile\nback view"
  suffixes: "_front\n_left\n_right\n_back"
  base_filename: "character"
  ↓
[BD Qwen Character Edit]
  ↓
[BD Save File]
  name_prefix: "MyCharacter"

Save Context Workflow (PBR Maps Example)

Replace concat-string chains with one context + N save nodes:

BD Save Context
  template: "%project%/%character%/%character%_%name%_v%version%%suffix%"
  character: "letti"  name: "topwear"  version: "03"  project: "biloxi"
                                ↓
                          context_id (auto-picks if only one registered)
                                ↓
BD Derive PBR Maps             BD Bulk Save
  ├─ albedo ────→ input_1        labels = "albedo
  ├─ normal ────→ input_2                  normal
  ├─ roughness ─→ input_3                  roughness
  ├─ metallic ──→ input_4                  metallic
  └─ ao ────────→ input_5                  ao"
                                custom_vars = "subfolder=PBR"
                                ↓
                          Saves all 5 in ONE Run:
                          biloxi/letti/PBR/letti_topwear_v03_albedo_001.png
                          biloxi/letti/PBR/letti_topwear_v03_normal_001.png
                          biloxi/letti/PBR/letti_topwear_v03_roughness_001.png
                          ...

Per-save custom_vars layer on top of the context's vars. Empty %var% segments collapse cleanly (a/%b%/c with b="" → a/c). Undefined vars stay as %var% literals to surface typos.

Multi-Reference Character Edit

[Load Image 1 (identity)] ─┐
[Load Image 2 (style)]    ─┼→ [BD Qwen Identity Lock] → [Generate]
[Load Image 3 (pose)]     ─┘     image1_strength: 1.5
                                  image1_role: character

---

Directory Structure

ComfyUI-BrainDead/
├── nodes/
│   ├── mesh/          # 3D mesh processing
│   ├── blender/       # Blender-based operations
│   ├── cache/         # Caching and save nodes
│   ├── character/     # Qwen character consistency
│   ├── pixal3d/       # Pixal3D image-to-3D
│   ├── cubepart/      # Roblox CubePart (vendored)
│   ├── trellis2/      # TRELLIS2 shape/texture
│   └── segmentation/  # SAM3, Parts, Face, Luma, PBR
├── example_workflows/ # 9 ready-to-use workflow templates
├── docs/images/       # Banner + workflow thumbnails
├── tools/             # audit_workflows.py, etc.
├── lib/               # Bundled Blender 5.0
└── requirements.txt   # Auto-installed by ComfyUI Manager

output/
├── BrainDead_Cache/     # Cache nodes save here (clearable)
│   ├── cached_image_abc123.png
│   ├── cached_mesh_def456.ply
│   └── MyProject/       # Subdirectories supported via name_prefix
│       └── step1_xyz789.png
└── saved_file.png       # BD Save File saves to main output/

---

Node Counts at a Glance

~113 nodes across 10 categories:

• Cache — caching, save/load, save-context system (~16)
• Mesh — 3D processing, color sampling, simplification, OVoxel PBR baking, orient, vertex-color/detail-normal baking (~29)
• Blender — Blender-based geometry tools (~12)
• TRELLIS2 — TRELLIS2-specific shape/texture nodes (~9)
• Pixal3D — image-to-3D generation (Pixal3D + MoGe FOV estimation) (~2)
• CubePart — open-vocabulary part decomposition (Roblox CubePart) (~2)
• Character — Qwen-Image character consistency (~4)
• Prompt — prompt iteration, filename templates, ForEach iteration (~5)
• Segmentation — SAM3 multi-prompt + Parts pipeline + FaceSocketInfill + LumaStats + NormalizeLuma + CenterMedianLuma + DepthToShadowMap + DrawRect + DrawEllipse + MaskResolver + MaskCorrelate + Human parsers (~25)
• Depth — Lotus-2 (FLUX-based diffusion depth/normal) (~2)
• PBR / asset prep — MaskFlatten, PackChannels, DerivePBR (in Segmentation)

Node Categories

🧠BrainDead/
├── Cache/         # Caching and file I/O nodes
├── Mesh/          # 3D mesh processing and color tools
├── Blender/       # Blender-based mesh operations
├── TRELLIS2/      # TRELLIS2-specific caching
├── Pixal3D/       # Pixal3D image-to-3D generation
├── CubePart/      # Roblox CubePart part decomposition
├── Character/     # Qwen-Image character consistency
├── Prompt/        # Prompt iteration tools
├── Segmentation/  # SAM3 + Parts pipeline + asset prep
└── Depth/         # Lotus-2 depth/normal

---

Tips

Caching Best Practices

• Use descriptive cache_name values: "trellis_base_mesh", "character_face_gen"
• Use name_prefix for project organization: "Project1/Step1"
• Connect workflow seed to cache seed for automatic invalidation
• Use force_refresh to regenerate without changing seed

Character Consistency

• Always use the highest quality reference image for image1
• Set image1_role to "character" and highest strength
• Use secondary images only for style/pose reference
• The Identity Lock node is optimized for face preservation

Prompt Iteration

• Use suffix_list mode for clean filenames: char_front, char_left
• Connect seed output to sampler for different seeds per prompt
• Use workflow_id to maintain separate iteration states

---

Support

• GitHub Issues: Report bugs
• Discord: BrainDeadGuild