Object Load Background Image

Object_LoadBackgroundImage wraps Blender's bpy.ops.object.load_background_image - it loads an image into the 3D viewport as a background reference, not as an object in the scene. Think tracing paper. You see the character behind your mesh layers, which makes manual rigging and alignment in the graph's preview much less guesswork.

This is one of those nodes where the name misleads you. "Load Background Image" sounds like it should take a ComfyUI IMAGE tensor. It doesn't - the primary input is a filepath string pointing at an image on disk, because that's what the underlying Blender operator expects. If you're coming from the image side of ComfyUI you'll want to save your image with a Save Image node first, then feed the path here.

The inputs that matter

• BPY_OBJ (optional) - the object to attach the background image to. Unwired, it uses the active object.
• filepath - the path to the reference image. The one you actually set.
• filter_image / filter_folder - file-browser filters from Blender's interactive file dialog. In the node they mostly do nothing useful since there's no dialog; leave them on.
• view_align - align the 3D view to the image after loading. Keep it on if you want the reference facing the camera.

The output is the same BPY_OBJ, so the node slots in as a side step: run it once, then carry on with the objects it doesn't touch.

Where it fits

Honestly, in a fully automated avatar pipeline you rarely need a background reference - the pack's whole pitch is that segmentation and mesh creation happen from the image automatically. This node earns its keep during debugging and manual alignment: seeing the original character behind your mesh layers is what tells you a jaw mesh is drifting. Treat it as a debugging convenience, not a pipeline stage.

Installation

Avatar Graph needs Python 3.10.x (the bpy==3.6.0 wheel is 3.10-only). Install via ComfyUI Manager searching "Avatar Graph", or:

cd ComfyUI/custom_nodes
git clone https://github.com/avatechai/avatar-graph-comfyui
cd avatar-graph-comfyui
pip install -r requirements.txt

Restart with --enable-cors-header for the live preview; first launch downloads the SAM model (~2.4 GB) and mediapipe landmarkers. And if you load a path and the viewport shows nothing, check the path actually resolves - a nonexistent file is the classic silent failure with this one.