No description
  • Python 93.2%
  • Shell 6.8%
Find a file
2026-10-28 06:44:56 +00:00
test dedup: dHash-based 'too similar' filter with greedy time-ordered backfill; cap sample reads (ffmpeg -t spills on concat files with mid-stream pixel format changes) 2026-10-28 06:44:56 +00:00
.gitignore perfect-frames: N evenly-spaced, focus-filtered frame extraction for huge 360 videos 2026-10-22 09:43:14 +00:00
perfect_frames.py dedup: dHash-based 'too similar' filter with greedy time-ordered backfill; cap sample reads (ffmpeg -t spills on concat files with mid-stream pixel format changes) 2026-10-28 06:44:56 +00:00
README.md dedup: dHash-based 'too similar' filter with greedy time-ordered backfill; cap sample reads (ffmpeg -t spills on concat files with mid-stream pixel format changes) 2026-10-28 06:44:56 +00:00

perfect-frames

Extract N evenly-spaced, well-focused frames from huge videos — designed for 8K equirectangular 360 footage (GBs per minute) where decoding the whole file to pick sharp frames is not an option.

How it works

  1. Probe — ffprobe for duration/fps/resolution (no decoding).
  2. Candidates — N timestamps evenly spaced across the duration.
  3. Score locally — around each candidate, ffmpeg decodes a small window (default ±1.5 s) at low resolution through a rawvideo pipe; each sampled frame is scored with a focus metric (variance of Laplacian or Tenengrad).
  4. Pick the sharpest per window, then reject frames that are blurry:
    • --min-score — absolute floor (calibrate per footage via a dry run)
    • --min-relative — reject if below a fraction of the median winner score
  5. Export — precise re-seek, single frame at full resolution (lossless PNG by default, or --jpeg-quality).

Total work ≈ N × window_seconds of low-res decode + one seek per survivor. Windows are scored in parallel (-j).

Setup

python3 -m venv .venv && .venv/bin/pip install numpy opencv-python-headless
# ffmpeg / ffprobe must be on PATH

Usage

# 12 sharp PNG frames from an 8K 360 video
.venv/bin/python perfect_frames.py video.mp4 -n 12 -o out/

# Calibrate first: score only, look at report.json scores, then set --min-score
.venv/bin/python perfect_frames.py big.mp4 -n 12 --dry-run

# Wider search, stricter relative sharpness, JPEG, 8 workers
.venv/bin/python perfect_frames.py big.mp4 -n 20 -w 6.0 --min-relative 0.7 \
    --jpeg-quality 92 -j 8 -o out/

Key options

Flag Default Meaning
-n 10 Number of target frames
-w/--window 3.0 Search window (s) centered on each candidate
-f/--sample-fps 5.0 Scoring sample rate inside the window
-s/--scale 1280 Scoring downscale width
-m/--metric laplacian laplacian (var) or tenengrad (grad energy)
--pole-mask 0.0 Ignore fraction of top/bottom (360 pole distortion, e.g. 0.1)
--min-score off Absolute focus floor
--min-relative 0.5 Floor vs. median winner score (0 = off)
-j/--jobs 4 Parallel ffmpeg workers (scan and export)
--snap-keyframes off Move picks to the nearest keyframe so export decodes 1 frame (see below)
--snap-tolerance 0.2 Max distance (s) to snap a pick to a keyframe
--dedup-threshold 8 dHash Hamming distance under which a pick is "too similar" (0 = off)
--no-backfill — Drop duplicate windows instead of trying the window's next-best candidate
--jpeg-quality PNG 1–100 to export JPEG instead of PNG
--dry-run — Report only

Every run writes report.json with per-window scores, winners, and reject reasons — useful for tuning thresholds against your footage.

Removing "too similar" frames

Duplicates arise when the camera lingers on one view: neighboring windows score near-identical content and their winners are the same picture. The metric is a 64-bit difference hash (dHash) — each frame is downscaled to 8×9 grayscale and each adjacent pixel pair contributes one bit ("which is brighter"). dHash is invariant to brightness, gamma, and compression; comparing two frames is one xor + popcount. It's computed on the low-res scoring frames already in memory, so it costs microseconds per sample.

How to read dHash Hamming distances (measured on fixtures, see test/metric_experiment.py):

distance meaning
0–2 identical or same view a few seconds apart in a static scene
3–7 same scene, slightly different
8+ clearly different content

--dedup-threshold (default 8) works as a greedy filter in time order: each window's pick survives only if it is ≥ threshold bits from every already-kept frame. With backfill (default on), a window whose top pick duplicates an earlier frame swaps to its own next-best-scoring candidate (already decoded — free) as long as it clears the blur floor, so you still get N distinct frames where the footage allows. --no-backfill just drops. Every decision lands in report.json (best_dhash, dropped_similar_to, similar_dist, backfilled).

Calibration tips:

  • Static-camera walkthrough (photogrammetry): default 8 is right.
  • Slow continuous camera motion where you want "early/mid/late stages" of a similar scene: raise to 12–14 or disable with 0.
  • Two picks snapped to the same keyframe export byte-identical images and are always dropped (exact-timestamp collision), independent of hashes.
  • Histogram metrics separate scenes just as well but ignore geometry — a different viewing angle of the same room looks like a duplicate, which is exactly the information you want in a 360 walkthrough. Pixel-distance metrics are too fragile (exposure drift). Feature/SSIM methods are heavier for no added benefit at this decision granularity.

Speeding up the export phase

An exact-timestamp export at 8K must fast-seek to the previous keyframe and decode forward to the target — with a 2 s GOP that's ~60 full 8K frames decoded per pick just to discard them. Two mitigations, combinable:

  1. Parallel exports — the export loop uses the same -j thread pool as the scan, so N frames export concurrently.
  2. --snap-keyframes — after scoring, each pick is moved (in parallel, via ffprobe's packet index — no decode) to the nearest keyframe within --snap-tolerance seconds. Snapped exports use -noaccurate_seek, landing directly on the keyframe and decoding exactly one frame. Picks outside the tolerance fall back to exact export automatically, and every snap is recorded in the report (snapped_to_keyframe, snap_delta).

Trade-off: a snapped frame is up to snap_tolerance away from the frame that was scored, and two picks near the same keyframe can snap to the same image (they export as separate files). For long-GOP camera footage (GOP ≥ 1 s) this turns the export phase from "decode dozens of 8K frames per pick" into "one seek per pick".

Tuning notes for 360 footage

  • Use --pole-mask 0.1 (or so) — equirectangular poles are stretched and can skew gradient scores.
  • tenengrad is slightly more robust to sensor noise; laplacian reacts harder to motion blur. Try both in a dry run.
  • Motion blur is a within-window problem: bigger -w gives the picker more room to dodge a shaky moment; higher --sample-fps catches short sharp instants at more decode cost.
  • The relative threshold assumes roughly comparable scenes; for footage with wildly different content density (dark vs. detailed scenes), calibrate --min-score per shoot instead.

Tests

test/ contains a synthetic clip (sharp → tmix-blurred → sharp) used to verify the pipeline rejects blur via --min-score. Regenerate with the commands in test/make_fixtures.sh.