Video Frame Stitcher

Extract frames from video and stitch them into adaptive grid images. Packs more frames per sheet when the scene is calm, fewer when the action heats up — so you can scan hours of footage in seconds.

Features

• Fixed-rate extraction — Extract exactly N frames per second (default 8 fps), independent of source frame rate
• Adaptive grid stitching — Base 4×6 grid (24 frames/image), automatically scales up to 6×8 (48 frames/image) when consecutive frames are similar
• Zero-config thresholds — Uses percentile-based adaptive thresholds derived from the video's own frame-to-frame MSE distribution — no manual tuning needed

How It Works

Video → Extract frames (8 fps) → Compute pairwise MSE → Adaptive grouping → Grid stitch → Output JPGs

Grouping strategy:

Window Avg Diff	Scene Type	Frames per Sheet
< P25	Low motion	Expand to 48 (6×8)
P25 ~ P75	Medium motion	Linear interpolation
> P75	High motion	Keep at 24 (4×6)

The intuition: if nothing much is changing between frames, you might as well pack more of them into one image. If the scene is changing rapidly, fewer frames per sheet keeps each one readable.

Installation

pip install opencv-python numpy

Usage

# Basic
python video_stitcher.py video.mp4

# Custom output directory
python video_stitcher.py video.mp4 -o ./output

# Custom grid range (e.g. 4×6 to 8×10)
python video_stitcher.py video.mp4 --min-rows 4 --min-cols 6 --max-rows 8 --max-cols 10

# Adjust extraction rate
python video_stitcher.py video.mp4 --fps 10

Options

Argument	Default	Description
video	(required)	Path to the video file
-o, --output	output_stitched	Output directory
--fps	8.0	Frames to extract per second
--min-rows	4	Minimum grid rows
--min-cols	6	Minimum grid columns
--max-rows	6	Maximum grid rows
--max-cols	8	Maximum grid columns

Example

A 93-second action scene video:

• 698 frames extracted at 7.5 fps
• 22 stitched images generated
• Low-motion segments → 6×8 grids, 45–46 frames/sheet
• High-motion segments → 4×6 grids, 24 frames/sheet

Requirements

• Python 3.8+
• OpenCV (opencv-python)
• NumPy

License

MIT