Video Snapshot Generator

A lightweight Python utility for extracting snapshots from a video and optionally merging them into a single horizontal contact-sheet image.

The tool supports two modes:

1. Interval Mode – capture snapshots every N seconds.
2. Timestamp Mode – capture snapshots at explicitly specified timestamps.

Each generated image is annotated with its corresponding video timestamp.

---

Features

• Extract snapshots from any video supported by OpenCV.
• Capture frames at fixed intervals.
• Capture frames at arbitrary timestamps.
• Overlay timestamps on generated images.
• Save individual snapshots.
• Merge snapshots into a single horizontal strip.
• Adjustable spacing between merged images.
• Simple command-line interface.

---

Installation

Requirements

• Python 3.8+
• OpenCV
• NumPy

Install dependencies:

pip install opencv-python numpy

---

Usage

python snap_gen.py --video <video_file>

---

Command Line Arguments

Argument	Type	Default	Description
--video	str	Required	Input video file
--snapshot-seconds	float	5.0	Interval between snapshots in interval mode
--timestamps	float list	None	Explicit timestamps (seconds) to capture
--num-snapshots	int	None	Maximum number of snapshots to generate
--merge	flag	False	Merge snapshots into a single horizontal image
--gap	int	10	Gap between merged images (pixels)
--merged-image	str	contact_sheet.jpg	Output merged image filename
--output-dir	str	snapshots	Directory for individual snapshots

---

Interval Mode

Capture frames every 2.5 seconds:

python snap_gen.py \
    --video demo.mp4 \
    --snapshot-seconds 2.5

This captures frames at approximately:

0.0s
2.5s
5.0s
7.5s
10.0s
...

---

Timestamp Mode

Capture frames at specific timestamps:

python snap_gen.py \
    --video demo.mp4 \
    --timestamps 0.0 3.0 7.0 10.0 13.0

This captures frames exactly at:

0.0s
3.0s
7.0s
10.0s
13.0s

When --timestamps is provided, it takes precedence over --snapshot-seconds.

---

Merge Snapshots

Generate a single-row contact sheet:

python snap_gen.py \
    --video demo.mp4 \
    --timestamps 0.0 3.0 7.0 10.0 13.0 \
    --merge \
    --gap 20 \
    --merged-image result.jpg

Result:

[img1]----20px----[img2]----20px----[img3]----20px----...

---

Limit Number of Snapshots

Generate at most 10 snapshots:

python snap_gen.py \
    --video demo.mp4 \
    --snapshot-seconds 2 \
    --num-snapshots 10

---

Output Structure

Example:

project/
│
├── snap_gen.py
├── result.jpg
│
└── snapshots/
    ├── snapshot_000_0.0s.jpg
    ├── snapshot_001_3.0s.jpg
    ├── snapshot_002_7.0s.jpg
    └── ...

---

Example for Robotics Papers

Extract representative frames from a manipulation episode:

python snap_gen.py \
    --video ep_0001_seed0000_success_ars.mp4 \
    --timestamps 0.0 3.0 7.0 10.0 13.0 \
    --merge \
    --gap 20 \
    --merged-image tray_push_merged.jpg

This generates:

• Individual timestamped snapshots
• A merged horizontal figure suitable for papers, presentations, and project pages

---

License

MIT License