ImageMotionGuider

The name oversells it a little. ImageMotionGuider doesn't "guide" motion the way a ControlNet or a motion LoRA does - no model gets loaded, nothing gets trained, nothing even gets downloaded. It's a pure image-processing trick: it turns one still image into a batch of frames that slide across a mirrored, seamlessly-tiling version of it, and the intended workflow is to VAE-encode that batch and hand it to Hunyuan Video as your starting latent. The video model sees a smooth lateral pan and keeps moving in that direction. Think of it as the image-to-video equivalent of the old Ken Burns effect, minus the empty borders.

Why you'd reach for it

If you run Hunyuan Video image-to-video, you know the drill: you give it a first frame and hope it invents a camera move. ImageMotionGuider is the "don't hope" button. Because the pan is computed deterministically from your inputs, the same settings give the same motion every time - which makes it genuinely nice for loops, for matching the direction of motion to your prompt, and for when you want a subtle push-in you can tune instead of re-rolling. It's a hack, but a cheap and repeatable one: a small PyTorch op that costs nothing on your VRAM budget relative to the 13B video model it feeds.

One honest caveat before you build your workflow around it: this pack exists for Hunyuan, and Hunyuan's own standing in 2026 is shaky - Wan took the image-to-video crown in early 2025 and the community mostly moved on. If you're here because the name sounds useful but you don't actually run Hunyuan, there are better first-frame paths. If you do run it and want deterministic camera motion, this is about the lowest-cost way to get it.

How it works

The source is one small Python file with a single loop. For each of frame_num frames it calculates an x-offset that slides from 0 up to move_range_x in even steps, then tiles a horizontally mirrored copy of your image into a canvas so the panning window is always fully covered - mirroring is the trick that kills the black bars, and when the pan wraps around, the seam is invisible because the next tile is just the image flipped.

The optional zoom ramps in linearly across the frames: each frame center-crops the image by a little more and bilinearly upscales it back to full size. The output is a batch of frame_num full-resolution images, all in one tensor.

The inputs that matter

Only four inputs, all required, and only three you'll actually touch:

• image - the IMAGE input. Feed it from any LoadImage (the repo's bundled workflow runs an Image Resize first, which is a good idea).
• move_range_x (INT, -150 to 150, default 0) - the total pan in pixels. Positive pans right, negative pans left. Start around ±50; bigger values get dramatic fast.
• frame_num (INT, 2 to 150, default 10) - how many frames to produce. 10–20 is plenty for testing.
• zoom (FLOAT, 0 to 0.5, step 0.05, default 0) - push-in strength over the sequence. Use it sparingly; it center-crops, so combined with a pan it crops deeper into the mirrored tiles.

The single output is IMAGE: a batch of frame_num frames. Wire it into a VAEEncode, and that encoded latent feeds the sampler (the shipped workflow pairs it with EmptyHunyuanLatentVideo → SamplerCustomAdvanced → VAEDecodeTiled → VHS_VideoCombine).

Install

Two real options, no dependencies either way:

# via ComfyUI Manager: search "ComfyUI-ImageMotionGuider" and install
# or manually:
cd ComfyUI/custom_nodes
git clone https://github.com/ShmuelRonen/ComfyUI-ImageMotionGuider.git

Then restart ComfyUI. That's it - there's no requirements.txt, no model download, no extra weights. The whole thing is built on ComfyUI's bundled torch, so it works the day you install it.

Where people get burned

• "Seamless" means no empty borders, not a true loop. At the mirror seam the image flips horizontally, so you get a ping-pong pan, not a seamless cycle of the same orientation. If you genuinely need a loop, that's a different tool.
• frame_num is a batch size, and it's a VRAM cliff. 150 frames of full-res images, VAE-encoded and pushed through a 13B video model, will eat your card. Test at 10–20 frames before dreaming of 150.
• It's Hunyuan-specific in intent. The frames are just images - feed them to Wan or LTX and you get a panning batch with no motion guidance attached. The magic only happens through the latent-first-frame workflow the author ships in the repo.