🌊 MI2V Flow Predictor

The name is the whole pitch: MI2V Flow Predictor doesn't animate anything. It plans the motion - a dense optical flow field for a 16-frame clip - and hands that plan to the pack's other nodes. You point it at a first frame, optionally draw arrows saying "this thing moves that way," and it tells the next node exactly where every pixel should travel. It's the brain; the MI2V Flow Animator is the muscle.

This is stage one of Motion-I2V, the CUHK/NVIDIA research model ("Consistent and Controllable Image-to-Video Generation with Explicit Motion Modeling," arXiv 2401.15977). IDGallagher wrapped the original PyTorch code into this diffusers-based ComfyUI pack in September 2024. The honest framing: in 2026, Wan 2.2 is the obvious choice for general image-to-video. But nothing in the modern stack lets you hand-draw the motion vectors the way Motion-I2V does. That explicit control is the only reason to come here, and this node is where it lives.

How it works

The predictor runs a text-conditioned flow-generation model (a 3D SD 1.5 UNet with a ControlNet bolted on) over your first frame. Your motion arrows become sparse "drag" points - small patches of displacement around each arrow's start - which the ControlNet reads as conditioning. The output is a dense optical flow: for each of the 15 subsequent frames, a per-pixel movement vector. The preview output shows that flow as a color image, where hue is direction and brightness is speed (the standard optical-flow color wheel the README mentions).

Two mechanism details worth knowing. First, the predictor silently resizes your image to the nearest multiple of 8 before running - so a 1023px-wide frame becomes 1024px, and your drawn arrows get rescaled to match. Second, the flow output carries a prepended zero-flow frame so the animator treats the first frame as a fixed anchor. That's why the whole thing is locked to 16 frames.

The inputs that matter

• first_frame (IMAGE) - the image you're animating. The only truly mandatory one.
• motion_vectors (STRING) - arrows from the MotionPainter node, serialized as x1,y1,x2,y2 per line. Leave empty for pure prompt-driven motion.
• motion_mask (MASK) - a region to hold still; anything under the mask gets its flow zeroed out.
• flow_unit_id (INT, default 5) - the brush radius of each drag point. This is the parameter that's easy to miss and fun to mess with: set it to 0 and the control signal is disabled entirely, leaving you with text-only flow prediction.
• prompt / negative_prompt, seed, num_inference_steps (25), guidance_scale (7) - standard diffusion fare.

Outputs

• flow (FLOW) - the plan. Wire this into the Flow Animator.
• preview (IMAGE) - the color-coded flow visualization. Save or preview it and you'll see the motion before paying the cost of rendering it.

Install

Via ComfyUI Manager (search "IG Motion I2V"), or:

cd ComfyUI/custom_nodes
git clone https://github.com/IDGallagher/ComfyUI-IG-Motion-I2V
# restart ComfyUI

The pack's requirements.txt pulls in diffusers>=0.30.0, cupy-cuda12x>=13.2.0, and omegaconf>=2.3.0. And here's the part people underestimate: the first time you run this node it prints "We need to download 17.3 Gb of files from Hugging Face" and pulls the full wangfuyun/Motion-I2V checkpoint into ComfyUI/models/diffusers/Motion-I2V. Budget the disk and the bandwidth before your first queue.

Gotchas

• VRAM. This is a diffusers wrapper, not a Comfy-native node - the whole pipeline is rebuilt in Python every run, and the README's own TODO list has "Reduce VRAM usage" sitting right there. Plan for a serious GPU (think 16–24GB class) and expect slow, memory-heavy first runs.
• xformers is mandatory. The code hard-asserts it; if it's missing, the node dies. And cupy-cuda12x means CUDA 12 on a Linux-ish setup is the realistic target - this pack's lineage is research code, not Windows-friendly.
• Model re-loads every run. There's no keep-model-loaded toggle exposed, so each queue eats the load time again. It's a wrapper, not polished.
• The multi-of-8 surprise. Because of the silent resize, load your image pre-sized (e.g. 1024×576) - that's exactly why the pack ships the Pause node and why drawing arrows before resizing leads to tears.

One more tip: run the predictor, stare at the preview colors, and then decide whether to commit to the animator. That two-step check is the whole point of the design - it saves you from rendering 16 frames of a plan you'd already rejected.