Goal: every moment you shot survives; when one moment has several near-identical frames (bursts, re-shoots) only the best one is auto-picked; you then review the doubtful ones.
cullkit analyze SHOOT_DIR WORK_DIR # scan → scenes → pick best frame per scene
cullkit review WORK_DIR # second pass in the browser (localhost only)
cullkit export WORK_DIR OUT_DIR # selects/ + rejects/ + report.csv (+ optional XMP labels)
Setup (Python ≥ 3.10):
python3 -m venv .venv && . .venv/bin/activate
pip install -e '.[faces,dev]'
cullkit fetch-models # ~4 MB MediaPipe face model (Apache-2.0); optional, enables blink/smile checks
cullkit demo /tmp/demo_event && cullkit analyze /tmp/demo_event /tmp/demo_work && cullkit review /tmp/demo_work
- Scenes (the "keep every moment" part). Frames are walked in capture order (EXIF
DateTimeOriginal+sub-seconds; file mtime as fallback). A frame joins an open scene only if it is withinwindow_s(12 s) of it and visually similar. The similarity bar rises with the time gap (0.55 for a true burst → 0.80 at the window edge), and the frame must also resemble the scene as a whole, which stops slow drift from chaining two moments together. Similarity = shift-tolerant correlation (phase-correlation aligned) + colour layout + dHash, minus a penalty when a localised region changed (a subject that moved elsewhere against an unchanged backdrop). Landscape and portrait never merge; different cameras interleave correctly. Anything uncertain stays split — an extra keeper costs a click, a lost moment costs the shot. - Best frame. Within a scene: sharpness of the in-focus region (gradient energy of the sharpest
tiles, so bokeh backgrounds don't hurt; noise-robust) and of the faces, eyes open (MediaPipe blink
blendshapes, area-weighted so the main subject counts most), face-count coverage (a frame where
someone turned away or left loses), smile, exposure/clipping. Sharpness is judged relative to the scene.
Hard defects (blurry vs. the scene's best, blink on a main face) demote a frame whenever a clean
alternative exists.
--keep Nauto-keeps the top N per scene. - Nothing is deleted. Decisions live in
WORK_DIR/state.json; export copies/links files. RAW+JPEG pairs are one shot and travel together with sidecars.
After pass 1 every scene keeps one photo. cullkit pass2 WORK [--window 60] [--strictness -1..1] [--apply] (or
Check similar photos… in the UI) compares the currently selected photos across scenes.
Two selects only count as near-identical if they are both visually near-identical (stricter than pass 1:
similarity ≥ 0.80–0.88) and within window seconds of each other (default 60 s; pass 1 uses 12 s), so it
catches a pose re-shot a minute later or a burst pass 1 split at its size cap. Their scenes are merged, the best
frame stays selected, and the merged scene is flagged second pass for your review (Split takes it apart again;
the whole step is one undo). Photos you decided by hand are never touched. It works from saved state, so it also
works after the selects were moved into a folder. On the 334-photo choir shoot it found nothing: the closest
cross-scene pairs were visibly different poses.
The browser check is guided: How it works → See the results → Confirm. Open More tools → Check similar photos…; the default search needs no settings. Checking is read-only. Similar picks appear together with an explanation of what grouping changes; a separate confirmation applies it and opens the review queue. If there are no matches, choose Done, back to photos. Optional time/similarity settings are tucked under Adjust the search.
On first open the review UI shows a Quick start dialog (also the ⚡ button, key Q, or
cullkit accept WORK --level … / cullkit analyze … --level … from the shell). It works like the
approval levels in agent tools:
| Level | What it does |
|---|---|
| Manual approval | Nothing is accepted for you; you confirm every scene (flagged ones first). |
| Auto-accept (recommended) | Accepts every scene without warnings; close calls, uncertain groupings and missing faces stay in your queue. |
| Full access | Accepts every scene exactly as auto-picked, warnings included. Fastest; any scene can be reopened. |
Accepting only marks scenes as confirmed — picks and your manual overrides stand, nothing is deleted, and it is a single undo step. A banner under the top bar always says what to do next (choose a level → review the flagged scenes → export), and the export dialog warns about scenes still unconfirmed.
Scenes are flagged when the choice is risky: close call (top two within 0.04), no clean frame
(every frame blinks/blurs), faces missing in the winner, uncertain grouping (merged by a thin
margin — could be two moments), oversize/long-span scenes, and soft single (an unpaired frame that is
unusually soft; kept anyway). The queue starts with those.
Keys: ↑↓ scene · ←→ frame · Space toggle keep · K/X/A keep/reject/auto · Enter reviewed+next ·
C compare with the auto-pick · Z 100 % zoom (synced when comparing) · F face/blink overlay ·
M merge with next scene · S split here · U undo · 1/2/3 filters.
The UI refuses to reject the last kept frame of a scene.
The review UI ships in English, 简体中文, 繁體中文, Español, हिन्दी, العربية (right-to-left), Français, Português,
Русский, 日本語, Deutsch and 한국어. It follows the browser language and can be switched from the dropdown in the
top bar (remembered per browser). To add a language, add one object to cullkit/review/static/i18n.js;
missing keys fall back to English. The command-line output and this README are English only.
- Junk (accidental triggers).
J(or Mark as junk…) excludes a frame or a whole scene. It is the one case allowed to leave a scene with no kept photo, so it is manual-only (no automation level ever marks junk) and needs a confirmation dialog; the server refuses it without that confirmation. A junk frame is never auto-picked, so a scene whose winner is junked falls back to its next-best frame. Restore any time. - Move is the default, copy is opt-in. Cull… in the UI, or
cullkit cull WORK [--types jpg|raw|both] [--buckets selects,rejects,junk] [--into DIR] [--dry-run], creates a new_cullkit_<date-time>/folder inside the analysed directory and MOVES the photos you tick intoselects/,rejects/andjunk/. Moves are renames on the same volume: no extra storage, nothing deleted, nothing overwritten, and a cross-volume move (which would be copy-then-delete) is refused. A second confirmation is required (tick "I understand" in the UI, typeMOVEin the CLI).MANIFEST.jsonletscullkit restore <folder> --work WORK(or the UI's Restore button) put everything back, even after a crash. Deleting the folders is left to you. cullkit export WORK [DEST]sorts intoselects/ rejects/ junk/, also moving by default. With noDEST(or a blank destination in the UI) it creates a fresh_cullkit_<date-time>/folder inside the analysed directory (--mode copy|hardlink|symlinkare opt-in; copy uses extra storage). It writes aMANIFEST-*.jsonfor restore.- File types:
--types jpg(JPG/HEIC/other pictures only),--types raw(RAW plus their .xmp sidecars) orboth(default); in the UI it is the Files to process dropdown in both Cull and Export (remembered). Files of the other type are left exactly where they are. A shot with no file of the chosen type is skipped.
-
Undo / Redo buttons (keys
U/Y) in the top bar show how many steps are available and what the next one is. History is saved toWORK/history/(last 100 steps), so it survives restarting the review server; a freshanalyzeclears it. Every kind of change is covered: keep/reject, junk, review marks, merge/split, batch accept, second pass. -
Return to unclassified… (per photo or whole scene) puts photos that were already selected/classified back to square one: your manual decision is dropped (back to the automatic pick), the scene is reopened for review and, if the files had been moved into a
_cullkit_*folder, they are moved back to their original place — one photo at a time, never overwriting anything (a file blocking the original path stays put and is reported). The decision part is undoable; the file part is reversible by culling again. The side panel shows where a moved photo is now. -
Restore (UI Cull… → Previous culls → Restore, or
cullkit restore FOLDER --work WORK) is idempotent (a second click or run is harmless), shows progress while a big card is working, disarms the "I understand" box afterwards, and removes the emptyselects/ rejects/ junk/folders it leaves behind (rmdironly: it cannot remove a folder that still holds a photo). The_cullkit_*folder itself, with itsMANIFEST*.jsonandreport.csv, is left for you to delete. -
Reset all… (UI top bar, or
cullkit reset WORK [--keep-scenes] [--keep-files]) returns everything to the unclassified state in one step: manual keep/reject/junk, review marks and the batch-accept level are cleared; optionally the original scenes are rebuilt from the cached analysis (undoing merges, splits and the second pass) and every moved file goes back to its original place. Nothing is deleted. Decisions and scenes are one Undo step; moving files back is not part of Undo.
--window, --strictness -1..1 (positive = split more), --keep, or --config file.json with any field
of cullkit/config.py. Re-running analyze on the same work dir is incremental (cached per file) and
carries manual decisions over.
Commercial: Aftershoot, Narrative Select, FilterPixel (scene grouping, per-face close-ups, human override). Open: the browser-based "Cull" write-up (perceptual hash + Laplacian variance), PixCull (multi-axis scoring, XMP round-trip). Face state: Google MediaPipe FaceLandmarker blendshapes (OpenCV 5's wheels no longer ship Haar cascades, so classic eye detectors were not an option).
- Tested on synthetic bursts and one real shoot (334 Sony A7 V RAW+JPEG frames of a choir contest):
scenes and picks were checked by eye on contact sheets, but thresholds are tuned on that single shoot.
Expect to adjust
window_s/--strictnessfor other event types. - Faces are detected on overlapping tiles of a 4000 px decode (frontal faces only; turned/profile faces are missed). In crowds somebody is always blinking or looking down, so hard blink/missing-face defects apply only to groups of ≤ 6 faces; bigger groups are ranked on the relative eye score. Intentional closed-eye moments (kisses, laughing) look like blinks — that is what the review pass is for.
- RAW capture times come from EXIF when readable (TIFF-based RAWs, embedded JPEG); otherwise mtime.
pytestruns the pipeline on generated photos (grouping vs ground truth, ranking, invariants, export).
This public repository contains source code, documentation and tests only. No real
shoot photographs, RAW files, thumbnails, screenshots, face-analysis records,
selection manifests, logs or local model binaries are distributed. The repository
uses a source-file allowlist in .gitignore to keep generated and private data out
of future commits. Do not force-add private media or analysis output.
The test suite and cullkit demo generate synthetic images locally at runtime;
those generated images are not committed or uploaded. Optional face models are
fetched separately from the upstream provider.
MIT — see LICENSE. Third-party dependencies and separately downloaded models remain under their respective licenses.