Object Volume Import

If you've ever imported an OpenVDB simulation - smoke, fire, clouds, an explosion you bought or baked - into Blender, you know the exact dialog this node wraps. Object Volume Import is bpy.ops.object.volume_import wearing a ComfyUI mask. It loads a .vdb (or .nvdb) volume file into the pack's shared headless Blender scene and hands you back the result as a BPY_OBJ.

It's niche, same as its sibling Object_VolumeAdd. In the straight avatar pipeline - character image in, segmented mesh layers out, shape keys, then the live editor - volumes are rarely the point. Where this earns its keep is the moment you want a real-world sim asset sitting in the same scene as your rig: a smoke plume behind the avatar, an ember cloud, anything a game/VFX person would hand you as a baked volume. Since Avatar Graph gives you the whole Blender operator library anyway, importing is the natural complement to adding primitives.

How it works

The node calls Blender's volume import operator with the properties you set, creates the volume object from the grid file, and returns it as BPY_OBJ. Same chain rule as every node in this pack: in goes a BPY_OBJ (optional - it just sets the active object first), out comes a BPY_OBJ you feed to the next Avatar Graph node. And that object only speaks the pack's type language; don't try to wire it into a normal image node.

The catch with import-style nodes in a headless graph: there's no file browser. The filepath and directory fields are plain strings, so you type or paste an absolute path. The heap of filter_* booleans (blender, image, movie, python, font, sound, text, archive, collada, alembic, usd, obj, volume, folder…) are leftovers from Blender's actual file-picker dialog - the generator auto-exported the whole operator signature, and they mostly don't do anything when you're passing a path directly. The two that matter are filter_volume and filter_folder, which default to true.

Inputs that matter

• BPY_OBJ - optional active-object reference.
• filepath - the real input. Absolute path to your .vdb file.
• directory - used with filepath for relative resolution; you can usually leave it blank.
• location, rotation, scale - B_VECTOR3 triples for placing the imported volume.
• align - WORLD / VIEW / CURSOR, same as the add-volume node.

Output: BPY_OBJ - the imported volume object.

Installing it

Part of the Avatar Graph pack (Avatech AI). ComfyUI Manager → search "Avatar Graph", or:

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

Restart after. The usual pack gotchas apply: it pins bpy==3.6.0, which only builds against Python 3.10.x, so a Python 3.11+ ComfyUI env will fail to import the whole pack. First launch also auto-downloads the SAM ViT-H model (~2.5 GB) into ComfyUI/models/sams plus two MediaPipe landmarkers - expect a slow first boot.

Common issues

• "No module named bpy" → Python version mismatch; get on 3.10.x.
• File not found / nothing imports → you gave it a relative path or a typo. Use an absolute path; there's no picker to rescue you.
• Volume doesn't render → volumes need raymarching; a mesh-first output path can silently drop them. Plan the export side before you wire this in.
• Scene resets each run - the shared Blender scene is cleared per execution, so import, transform, and output must live in one graph pass.

Verdict: a faithful little import bridge for people who already have volume data. Most avatar users will never touch it - and that's fine, it's here when you need it.