chore(docs): document ScoreExtractor tiling and refactor debug scripts (#563)

scripts/debug/dump_frames.py

@@ -0,0 +1,33 @@
+"""원본 프레임 덤프 — 각 영상에서 5개 프레임을 랜덤 추출"""
+import sys
+if sys.platform == "win32":
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+import cv2
+import numpy as np
+from pathlib import Path
+
+output = Path("output")
+dump_dir = output / "raw_dump"
+dump_dir.mkdir(exist_ok=True)
+
+mp4s = sorted(output.glob("*.mp4"))
+for vi, mp4 in enumerate(mp4s):
+    cap = cv2.VideoCapture(str(mp4))
+    total = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+    fps = cap.get(cv2.CAP_PROP_FPS)
+    w = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+    h = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+    print(f"Video {vi+1}: {mp4.name[:30]}... ({w}x{h}, {fps:.0f}fps, {total} frames)")
+
+    # 균등 간격으로 5개 프레임
+    indices = np.linspace(total * 0.1, total * 0.9, 5, dtype=int)
+    for i, idx in enumerate(indices):
+        cap.set(cv2.CAP_PROP_POS_FRAMES, idx)
+        ret, frame = cap.read()
+        if ret:
+            path = dump_dir / f"v{vi+1}_raw_{i}.png"
+            cv2.imwrite(str(path), frame)
+            print(f"  frame {idx} → {path.name} ({frame.shape})")
+    cap.release()
+
+print(f"\n덤프 완료: {dump_dir}")