IAMCCS H3 Reference Image · R42

On paper this is the dullest node in the set: it saves a PNG. In practice it's the piece that lets your H3 video graph and your H3 still-image graph be the same graph - no rewiring, no second queue, no duplicating the prompt. It does that by being deliberately lazy: the image socket only gets evaluated when Settings PRO says the current task is a reference image.

What it's for

The R42 still branch exists so your reference plates - character sheets, production stills, the images your ref2va shots get conditioned on - come out of the same project state as the video. So the graph holds both jobs at once, sharing a prompt and a canvas through the CineLinX bus.

Which creates a problem: if a save node always grabbed its input, every video render would also fire the whole still pass, and you'd pay for an H3 generation you didn't want. So this node asks permission first.

How it works

It implements ComfyUI's lazy-input contract as a mode gate. check_lazy_status reads the settings off the cine_linx payload, and only requests the images socket when task_mode is reference_image and no image has arrived yet. Until it asks, the entire still branch upstream of it is never executed - that's how you get a mode switch instead of two graphs.

Then save does the boring part competently:

• Mode isn't reference_image → returns a None image and a report like R42 image branch idle · Settings PRO mode=fl2va. Nothing is written.
• Mode is reference_image → validates that it got a real tensor, trims the batch to the first frame, and hands that to ComfyUI's own SaveImage with your filename_prefix and the workflow metadata.

Note the trim. It saves images[:1]. If you were hoping this would drop a four-up sheet of your batch in the output folder, it won't - one file, one frame.

The inputs and outputs that matter

• cine_linx (IAMCCS_SUPERNODE_LINX) - required, and it's the only thing that decides whether this node is awake. Wire it from the same Settings PRO that feeds the rest of the branch.
• filename_prefix (STRING) - defaults to IAMCCS/H3_REFERENCES/reference, so your stills land in ComfyUI/output/IAMCCS/H3_REFERENCES/. Change it per project unless you enjoy sorting a single folder forever.
• images (optional IMAGE) - from the H3 still generator, or from IAMCCS_H3OptionalSameSizeDetail if you're running the detail pass.

It's registered as an output node, so it drives the queue rather than merely passing data. The useful bit is that it doesn't only save: reference_image goes back out as a plain IMAGE, so you can feed that still straight back into the video side as a reference or guide. That's the loop: generate the plate, keep it, then shoot the shot that needs it.

report is your status line - read it before debugging anything else.

Installing it

Same pack as the rest of the R42 branch, via IAMCCS Nodes in ComfyUI Manager, or:

cd ComfyUI/custom_nodes
git clone https://github.com/IAMCCS/IAMCCS-nodes

Restart and hard-refresh the browser - this package ships frontend code, and a duplicated copy inside custom_nodes is the classic source of stale node definitions and phantom UI. Nothing extra to pip install: this node uses ComfyUI's built-in SaveImage. No weights ship with the pack, and H3's own weights are a separate download under a licence that carves out the US, EU, UK and South Korea.

Installing the pack isn't the same as having the branch: Settings PRO only treats reference_image as available when the graph contains both the IAMCCS_R42ReferenceImagePromptBridge and an H3 image-generator node (SatoDiveH3Image).

Where people get burned

"Nothing was saved." Look at the report. If it says the branch is idle, your task_mode is still a video mode - that is the node working correctly, not failing. This is by far the most common confusion, because a node that silently declines to run looks identical to a broken one.

"R42 H3 Image Generator produced no image tensor." Different error, different cause: the mode was right, but nothing arrived on the wire. Usually the image socket is pointed at a node that returned None or that never ran in this pass.

Only one image, ever. That's the images[:1] trim, and it's intentional.

Filenames piling up. SaveImage appends counters, so you get incrementing files rather than overwrites. Set a per-project prefix and you'll have a sane folder.

And the one that catches people who are certain everything is configured: if the cine_linx payload came from a region of the graph built before you changed the mode, you're reading stale settings and the gate stays shut. Re-run cleanly, and hard-refresh after a pack update.