Object Load Reference Image

Avatar Graph builds interactive 2D avatars by treating your character portrait as raw material for a little Blender scene running inside ComfyUI - segment it, turn pieces into mesh planes, rig them, animate them. Object Load Reference Image is where that image actually enters Blender's world. Everything downstream - mesh layers, UV unwraps, shape keys - is built on top of whatever this node loads.

How it works

This wraps Blender's own "load reference image" operation: it creates an Empty object in the scene with your image displayed on it, the way riggers and modelers have always used flat reference photos as a tracing plane before building geometry over them. It's not a diffusion-side image loader like ComfyUI's stock LoadImage - it's a Blender object, which is why the output type is BPY_OBJ rather than IMAGE. Every other Blender node in this pack (the primitive generators, the remesh operators, the bake node) consumes and produces that same BPY_OBJ type, chaining Blender operators together the way you'd click through Blender's own menus, just as ComfyUI nodes instead.

The README is specific about what makes a good source image here: an open-mouth, front-facing character shot at a minimum of 768×768, because the rigging pipeline needs to reliably locate facial features. If you're generating the character with Stable Diffusion first, they suggest appending looking at viewer, detailed face, open mouth, [smile], solo, eye-level angle to your prompt for exactly that reason.

The inputs and outputs that matter

Everything here is optional at the schema level, but two are the ones you'll actually touch:

• filepath - the string path to your image file. This is the one setting that matters for a beginner: point it at your character PNG.
• view_align - boolean, defaults on. Keeps the reference plane facing the viewport camera rather than sitting at a fixed world rotation, which is what you want for a flat character portrait.

There's also a BPY_OBJ input (for chaining onto an existing object/scene context) and filter_image / filter_folder booleans that control file-browser filtering if you're wiring this interactively rather than hardcoding a path. Output is a single BPY_OBJ - feed that into whatever mesh-layer or transform node comes next.

How to install it

Through ComfyUI Manager (search "Avatar Graph"), or manually:

cd ComfyUI/custom_nodes
git clone https://github.com/avatechai/avatar-graph-comfyui

then pip install -r requirements.txt and restart. This is one of the nodes where the pack's core dependency actually bites: it needs Blender's bpy package, which is hard-pinned to Python 3.10.x. On macOS/Linux, run it in its own conda environment (conda create --name comfyui python=3.10) rather than an existing 3.11/3.12 ComfyUI install - mixing bpy into an environment built for a newer Python is the single most common way people break this pack before they've even loaded their first character image. Windows users can skip the headache with Avatech's prebuilt Python-3.10 ComfyUI zip, then add this pack via Manager.

Common issues & troubleshooting

"No module named bpy" or an isolated-environment error on load - this is a real, recurring complaint with any ComfyUI pack that embeds Blender's Python module, not unique to this one: bpy needs an exact Python version and its own dependency chain, and if it's installed into the wrong environment (or a different node touched the same environment afterward) it silently stops working. Reinstall inside a clean Python 3.10 environment rather than debugging package-by-package.

Reference image loads but facial features aren't detected downstream - check resolution and framing first. Below 768×768, or a closed mouth / three-quarter angle, is a known failure mode per the README's own guidance, not a bug in this node.

No live preview - this node itself doesn't need it, but if you're chasing the interactive avatar view later and it's blank, confirm you restarted ComfyUI with --enable-cors-header; without it the Blender-side data never reaches Avatech's web editor.