momentry_core/docs_v1.0/REFERENCE/Cut_Structure.md

Cut 結構說明

Date: 2026-05-16

---

定義

Cut = 視覺 chunk。
同鏡頭連續拍攝的一組 frame（one continuous camera take）。
由 cut_processor.py（PySceneDetect）偵測場景轉換點自動切割。

與 聽覺 chunk（sentence） 的對照：

chunk 類型      | 模態  | 產出者              | 內容
----------------|-------|---------------------|----------------------
cut (視覺)      | video | cut_processor.py    | scene boundary
sentence (聽覺) | audio | asr_processor.py    | speech text

兩者各自獨立：cut 不含聽覺資訊，sentence 不含視覺資訊。
但在時間軸上可以對齊：某個 cut 時間區間內包含哪些 sentence。

特性：

• 同一個 cut 內：光線、構圖、背景一致
• 換鏡頭 → 新 cut → 物體動態軌跡中斷
• trace 必定落在一個 cut 內（不跨 cut）

儲存在 chunk 表中，chunk_type = 'cut'。

儲存方式

獨立的 cuts 表：

cuts 表
├── id            SERIAL PK
├── file_uuid     VARCHAR(32)  所屬檔案
├── cut_number    INTEGER      同一檔案內序號 (1, 2, 3...)
├── start_frame   BIGINT       開始影格
├── end_frame     BIGINT       結束影格
├── start_time    FLOAT8       開始時間（秒）
├── end_time      FLOAT8       結束時間（秒）
├── fps           FLOAT8       影格率
├── metadata      JSONB       附加資訊
├── created_at    TIMESTAMPTZ  建立時間
└── UNIQUE(file_uuid, cut_number)

資料範例

{
  "id": 989849,
  "chunk_id": "989849",
  "chunk_type": "cut",
  "start_frame": 0,
  "end_frame": 867,
  "fps": 25.0,
  "content": {"type": "scene", "scene_number": 1}
}

與 Trace 的關係

每個 cut 涵蓋一定範圍的影格，trace 則落在 cut 的影格範圍內：

cut 1:  frame 0-867      → trace_id 0-31    (32 traces)
cut 2:  frame 868-973    → trace_id 35-45   (11 traces)
cut 3:  frame 974-1073   → trace_id 46      (1 trace)

trace_id 是 per-file global sequential，不因 cut 重設。
同一個人的不同 cut 會得到不同的 trace_id（因為物體軌跡不連續），但 trace_id 是持續給號的。

cut 1 (camera A): frame 0-867     → trace_1 0~31
cut 2 (camera B): frame 868-973   → trace_1 32~45  ← 繼續給號，不歸零
cut 3 (camera C): frame 974-1073  → trace_1 46     ← 繼續給號

唯一約束仍然是 (file_uuid, trace_id)，cut_id 只是輔助查詢用的 scope 欄位。

查詢

-- 列出所有 cuts
SELECT id, cut_number, start_frame, end_frame, 
       (end_frame - start_frame) as frames
FROM cuts
WHERE file_uuid = ?
ORDER BY cut_number;

-- 某個 cut 內的 traces
SELECT DISTINCT fd.trace_id, count(*) as faces
FROM face_detections fd
WHERE fd.file_uuid = ? AND fd.cut_id = ?
GROUP BY fd.trace_id
ORDER BY fd.trace_id;

數量

File	Cuts	Faces per Cut (avg)
3abeee81...	70	~1,546