Prepare Refs (QQ)

Every serious Wan compositing workflow eventually needs the same thing: a clean background plate and a set of cut-out reference images of the thing you want to move, plus the masks that define them. Preparing those by hand in an external editor is a workflow-killing detour. PrepareRefs is the in-canvas version - you draw lasso shapes directly over the image in ComfyUI, and the node exports the background, the cut-out refs, their masks, and matte-ready mask images. The Power Spline Editor in this same pack is the consumer that makes this all click.

It's part of siraxe/ComfyUI-WanVideoWrapper_QQ, sir_axe's Wan pack - added in v1.1.0 specifically to feed the spline editor's cutout workflows. The README's example workflow (ttm_ref_cutout) is exactly this: lasso the subject, prep the refs, drive it around a scene.

How it works

The node is a canvas surface (default mask_width/mask_height 1280×960) you draw on. Each drawn lasso becomes a reference layer; the node parses that layer data, converts each shape into an image and a mask, and composites the result. A few specifics worth knowing:

• The background gets inpainted behind the lassoed-out subject, so you end up with a clean plate and a separate ref cutout.
• Ref images are auto-cropped to 768×768 bounding boxes and scaled - a deliberate, hardcoded choice (to_bounding_box is always on) so every ref comes out square and uniform for downstream nodes.
• The mat_masks output is white-on-black masks at full resolution, explicitly built for MatAnyone2 / SAM-based matting workflows (the pack ships MatAnyone2 support since v1.2.8).
• A backend Canvas button can trigger ref preparation without starting a full ComfyUI run - handy when you're iterating on the cutout.

Inputs and outputs that matter

• mask_width / mask_height - canvas dimensions (8–8192, stepped by 8).
• bg_image (optional) - the image you're drawing on; if connected, its resolution wins and the canvas conforms.
• extra_refs / extra_masks (optional) - additional refs/masks merged into the batch.
• internal_state, ref_layer_data, export_filename - canvas persistence and export plumbing, mostly managed by the UI rather than hand-edited.

Outputs: bg_image, ref_images (IMAGE), ref_masks (MASK), and mat_masks (IMAGE).

Installation

cd ComfyUI/custom_nodes
git clone https://github.com/siraxe/ComfyUI-WanVideoWrapper_QQ.git

Restart ComfyUI (or ComfyUI Manager → "WanVideoWrapper_QQ"). This node needs OpenCV - the code imports cv2 directly, and the pack's requirements.txt is empty, so nothing auto-installs it. If it fails to import, run:

pip install opencv-python

in your ComfyUI Python environment. And post-v1.3.4, delete any old wanwrapper_qq folder after the pack renamed to ComfyUI-SA-Nodes-QQ.

Common issues

The most confusing behavior is the "empty output" path: if you run it with no valid drawn layers and no extra_refs, it returns zeroed tensors plus a warning - that's the node telling you there's nothing to export, not a crash. Second, the 768×768 crop is non-negotiable; if you expected full-resolution refs, that's the hardcoded behavior, so design around it. And the canvas dimension widgets are a floor, not a final answer - connecting a bg_image overrides them, so a 1920×1080 plate yields 1920×1080 outputs even though the widgets say 1280×960.