MotionFrame is a Rust tool for generating motion-vector textures for flipbook animation. It analyzes an image sequence, computes optical flow, accumulates sub-frame motion, and writes color and motion atlases that a runtime shader can sample for smoother playback with fewer texture frames.
The project includes a desktop application, a command-line converter, and a web version.
Try it in your browser: motionframe.aki-null.net
| Fade Blend | Motion Blend |
|---|---|
 |
 |
 |
 |
- GUI Frontend
- Batch Conversion CLI
- Cross-Platform
- Supports macOS, Windows, and Linux.
- Skipped Frame Analysis
- Enhances motion analysis precision with high frame rate input.
- Analyzes every input frame and accumulates skipped frames into each motion vector frame.
- Useful for fast movement that is difficult for image-based motion analysis.
- Motion Vector Stagger Packing
- Motion vector textures use 2 channels, but this may not be optimal for some platforms.
- Packing them into 4 channels reduces texture size by half and compresses well with formats like ASTC.
- Color Atlas Packing
- Motion Visualization
- Free and Open Source
See the reference shader implementation (MIT) for shaders to render this.
Install the pinned Rust toolchain, then build:
git clone https://github.com/aki-null/MotionFrame.git
cd MotionFrame
cargo build --release --bin motionframeThe desktop binary is written to:
target/release/motionframe
Launch the desktop application:
cargo run --release --bin motionframeIn the desktop app:
- Load frames: drag and drop an image sequence onto the window, or click Browse. A folder works (the tool infers the frame-number naming), as does a single atlas image (tile count is auto-detected).
- Configure options. Output frames sets the target output count, and Analyze skipped frames improves quality when the input has more frames than the output.
- Click Generate. The result appears across the tabs: Color, Motion, Visualization (motion as arrows), and Preview (animated GPU playback warped by the motion vectors).
- Click Save to export a color atlas and a motion vector atlas (TGA), plus JSON metadata.
Convert one image sequence or atlas from the command line:
cargo run --release --bin motionframe -- convert \
--input frames/explosion \
--output out/explosion \
--output-count 64 \
--layout autoThe CLI writes:
<prefix>_color_atlas.tga<prefix>_motion_atlas.tga<prefix>_meta.json
Use motionframe convert --help for all conversion options.
MotionFrame 2.0 is a Rust rewrite of the original Python application. The
previous Python implementation is archived on the legacy-python branch and
the python-final tag.
- Desktop application and CLI are built from Rust.
- Optical flow and atlas generation are implemented in the Rust engine.
- Runtime dependencies are no longer installed through Python.
Existing image-sequence workflows should map to the Rust CLI and desktop app.
Output quality and performance are expected to improve. If a script depended
on Python internals, migrate it to the motionframe CLI.
Use these refs for the old Python implementation:
legacy-pythonpython-finalv1.0.0-python-final
./scripts/verify.sh # fmt + clippy + test + release build + web build + license check
./scripts/verify-quick.sh # fmt + clippy + tests
./scripts/verify-parity.sh # flow + atlas pipeline parity testsMotionFrame is licensed under GPL v3.0. Third-party notices and license texts
are listed in THIRD-PARTY-LICENSES.md.
- Import the motion vector texture as linear (non-sRGB) in your game engine.
- In Unity, uncheck "sRGB (Color Texture)" in the texture settings.
- The exported JSON holds metadata useful for shader parameters, such as motion strength and total frame count.
Downloading this tool and using generated textures for your game does not contaminate your software with GPL v3.0.
Generated atlases:
| Color Atlas | Motion Atlas |
|---|---|
 |
 |
 |
 |