Reference Image Load - Star7

MiniMax H3 is a 33B video model where sequence length is everything. Every reference image or video you feed it gets packed into the token sequence the transformer churns through, and that packed length is what decides whether a run fits on your card and how long each step takes. A reference image is the cheap end of that trade - way cheaper than a reference video - but drop in an unconstrained 4K still and you've still handed H3 thousands of conditioning tokens you didn't need.

Reference Image Load - Star7 exists to stop that. It's a one-stop loader: it grabs a still from your ComfyUI input folder, and in the same node limits its longest edge to an H3-aligned size, keeping the aspect ratio and the orientation intact. The default cap is 1024, and the output dimensions snap to the 32-pixel grid H3 expects.

The inputs that matter

• image - a dropdown of images in ComfyUI/input/, with an upload button. Same as any standard Load Image.
• 最长边 / max_long_edge - longest-edge limit, default 1024, step 32. Set it to 0 to keep the source size untouched.
• 允许小图放大 / allow_upscale - off by default, and the README wants it that way. Resampling a small image up adds interpolated detail that just spends H3 tokens on pixels that aren't real. Flip it on only for structure/motion A/B tests.

Note the two names: this pack localizes its UI. On a Chinese-locale ComfyUI the parameters read 最长边 and 允许小图放大; on an English UI they're max_long_edge and allow_upscale. Same fields either way, and your workflow saves the English keys regardless of language.

Outputs and where they go

• image (IMAGE) - the loaded, rescaled tensor.
• mask (MASK) - built from the image's alpha channel if it has one (transparency becomes 1 - alpha); otherwise a zero mask.

In the pack's example workflow the image output feeds a T8 conditioning node's ref_image_0 interface, which is the standard H3 single-reference path. The mask is there for the cases where your reference has transparency and you want the conditioning to respect it.

How it works under the hood

Load via PIL, EXIF-transpose so phone photos aren't sideways, convert to RGB, fit the long edge to the limit with area resampling (the quality-safe downscaler), and scale the mask to match. Small. Predictable. No FFmpeg, no video pipeline, no model downloads - this is the lightweight member of the pack.

Installing it

It ships in the same package as the main MiniMax H3 Activation Chunk - Star7 node. If you installed that via ComfyUI Manager (search MiniMax H3 Activation Chunk - Star7) or cloned the repo, this one is already in your node list - zero extra dependencies. You'll find it under Star7/image in the node menu.

The one trap

People see "1024" and assume it's a quality knob, then wonder why their 4K reference looks soft. It's not a quality knob - it's a VRAM and speed lever. H3 re-renders the reference at conditioning resolution anyway; an over-big canvas is pure waste. If you genuinely need more reference detail for a specific shot, raise max_long_edge (or set 0 for the original), but expect the packed sequence - and your step time - to climb with it. Keep it at 1024 until a run actually demands more.