Skip to content
MoYu2008FishPublic

About

Local-first event photo culling with scene grouping, quality ranking and a guided browser review workspace. No photo data included.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

cullkit — event-photo culling with a manual second pass

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

How it decides

  1. 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 within window_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.
  2. 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 N auto-keeps the top N per scene.
  3. 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.

Second pass: near-identical selects

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.

Quick actions: how much to trust the automation

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.

Second pass (review UI)

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.

Languages

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 shots, moving and file types (no copies, no deletion)

  • 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 into selects/, rejects/ and junk/. 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, type MOVE in the CLI). MANIFEST.json lets cullkit 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 into selects/ rejects/ junk/, also moving by default. With no DEST (or a blank destination in the UI) it creates a fresh _cullkit_<date-time>/ folder inside the analysed directory (--mode copy|hardlink|symlink are opt-in; copy uses extra storage). It writes a MANIFEST-*.json for restore.
  • File types: --types jpg (JPG/HEIC/other pictures only), --types raw (RAW plus their .xmp sidecars) or both (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 and returning photos

  • 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 to WORK/history/ (last 100 steps), so it survives restarting the review server; a fresh analyze clears 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 empty selects/ rejects/ junk/ folders it leaves behind (rmdir only: it cannot remove a folder that still holds a photo). The _cullkit_* folder itself, with its MANIFEST*.json and report.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.

Tuning

--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.

Prior art consulted

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).

Status / known limits

  • 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 / --strictness for 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.
  • pytest runs the pipeline on generated photos (grouping vs ground truth, ranking, invariants, export).

Privacy and repository contents

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.

License

MIT — see LICENSE. Third-party dependencies and separately downloaded models remain under their respective licenses.

About

Local-first event photo culling with scene grouping, quality ranking and a guided browser review workspace. No photo data included.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages