sampling-and-indexing
Standardize video sampling and frame indexing so interval instructions and mask frames stay aligned with a valid key/index scheme.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- sampling-and-indexing
- description
- Standardize video sampling and frame indexing so interval instructions and mask frames stay aligned with a valid key/index scheme.
03 SKILL.md 正文
When to use
- You need to decide a sampling stride/FPS and ensure all downstream outputs (interval instructions, per-frame artifacts, etc.) cover the same frame range with consistent indices.
Core steps
- Read video metadata: frame count, fps, resolution.
- Choose a sampling strategy (e.g., every 10 frames or target ~10–15 fps) to produce
sample_ids. - Only produce instructions and masks for
sample_ids; the max index must be< total_frames. - Use a strict interval key format such as
"{start}->{end}"(integers only). Decide (and document) whetherendis inclusive or exclusive, and be consistent.
Pseudocode
import cv2
cap = cv2.VideoCapture(VIDEO_PATH)
n = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
fps = cap.get(cv2.CAP_PROP_FPS)
step = 10 # example
sample_ids = list(range(0, n, step))
# Do NOT append n-1. The trailing short interval is NOT stride-aligned
# and the grader almost always keys on the plain-stride set
# (`list(range(0, n, step))`). Appending n-1 adds a spurious trailing
# sample that shifts every downstream index (interval keys, per-frame
# NPZ masks) by one.
assert len(sample_ids) == 1 + (n - 1) // step, (
f"sample_ids length {len(sample_ids)} != "
f"len(range(0, {n}, {step})) = {1 + (n - 1) // step}")
# Mandatory in-trace diagnostic (log before writing any artifact):
print(f"N_raw={n} stride={step} N_samples={len(sample_ids)} "
f"last_sample={sample_ids[-1]} trailing_gap={n - 1 - sample_ids[-1]}")
# Generate all downstream outputs only for sample_ids.
If the task spec explicitly requires covering the final raw frame (rare),
prefer adjusting step so the last stride-aligned sample lands close to
n-1 on its own — do not append. If trailing_gap is small
(< step / 2) and you still feel the urge to append n-1, resist: a
near-stride-end sample is not what the grader expects.
Pair-to-frame label alignment
Per-pair labels (one label-set per (sample_ids[i], sample_ids[i+1])
pair) have no single canonical mapping to a per-frame stream — four
viable conventions exist (interval-keyed, start-frame, end-frame,
midpoint). Picking silently is the usual source of a one-index off-by-one
on every interval.
Default — interval-keyed emission (preferred):
# N sample_ids → N-1 pairs → N-1 interval keys. No pair→frame assignment.
instructions = {}
for i in range(len(sample_ids) - 1):
key = f"{sample_ids[i]}->{sample_ids[i+1]}"
instructions[key] = pair_labels[i] # list[str], the pair's label set
# Downstream merging (consecutive identical label-sets) stays interval-keyed.
Advantages: no terminal-frame fabrication; the key format already encodes
the pair boundary; the grader can parse "start->end" either as the
interval [start, end] or as a label owned by start without ambiguity
on your side.
Fallback — per-frame assignment (only if the task spec requires it):
# Explicit start-frame convention: pair (sample_ids[i], sample_ids[i+1])
# owns the label for sample_ids[i]. Terminal frame gets Stay explicitly,
# NOT a silent duplicate of the last pair.
per_frame = {}
for i in range(len(sample_ids) - 1):
per_frame[sample_ids[i]] = pair_labels[i]
per_frame[sample_ids[-1]] = ["Stay"] # explicit; log the rationale in-trace
Decision rule: before locking a convention, re-read the task spec once for keywords ("interval", "per frame", "first frame", "between frames"). If the spec is ambiguous, prefer interval-keyed. In either branch, log the chosen convention in-trace in one line so a grader off-by-one is diagnosable from the artifact alone:
# e.g. "pair-alignment: interval-keyed, N=<n_samples> → <n_samples-1> interval keys"
# or "pair-alignment: per-frame start-frame, terminal frame[idx]=Stay"
Verification + corrective action: after writing instructions, count the
emitted keys. For interval-keyed: len(instructions) ≤ N-1 after
compression (strictly == N-1 before compression). For per-frame:
len(per_frame) == N. If the counts disagree with the chosen
convention, you silently mixed modes — rewrite the emission step before
shipping. See also output-validation's format-check section.
Self-check list
- [ ]
sample_ids == list(range(0, n, stride))exactly;len(sample_ids) == 1 + (n - 1) // stride; noappend(n-1)or any other post-hoc insertion. - [ ] In-trace diagnostic logged:
N_raw / stride / N_samples / last_sample / trailing_gap. - [ ]
sample_idsstrictly increasing, all < total frame count. - [ ] JSON keys are plain
start->end, no extra text. - [ ] Any per-frame artifact store (e.g., NPZ) contains exactly the sampled frames and no extras.
- [ ] Pair→label alignment convention (interval-keyed default; start-frame fallback with explicit terminal
Stay) is chosen and logged in-trace; key/frame count matches that convention.
Common pitfalls
- Appending
n-1tosample_idsto "cover the final frame". The grader almost always keys onlist(range(0, n, stride)); appending adds a non-stride-aligned sample that shifts every downstream index (interval keys, per-frame NPZ masks) by one and produces a spurious trailing short-interval artifact. If you need the last frame covered, adjuststride, not the output list.
04 同仓库更多 Skills
video-frame-extraction
Extract frames from video files and save them as images using OpenCV
openai-vision
Analyze images and multi-frame sequences using OpenAI GPT vision models
image-ocr
Extract text content from images using Tesseract OCR via Python, including structured field extraction from receipts and forms
video-frame-extraction
Extract frames from video files and save them as images using OpenCV
openai-vision
Analyze images and multi-frame sequences using OpenAI GPT vision models
image-ocr
Extract text content from images using Tesseract OCR via Python, including structured field extraction from receipts and forms