momentry_core/docs_v1.0/REFERENCE/Trace_Structure.md

Trace 結構說明

Date: 2026-05-16

---

定義

Trace 是 Face Tracker 輸出的一組連續人臉偵測結果，代表同一個人在畫面中的連續出現。每一條 trace 包含多個 face_detections 記錄，共享同一個 trace_id。

結構

資料庫

-- face_detections 表
trace_id    INTEGER       -- 同檔案內順序編號 (0, 1, 2, ...)
file_uuid   VARCHAR(32)   -- 所屬檔案
face_id     VARCHAR       -- 單一偵測 ID (未使用)
identity_id INTEGER       -- 綁定的身份 ID (FK → identities.id)
frame_number INTEGER       -- 所在影格
x, y, w, h  INTEGER       -- Bounding box
confidence  FLOAT4         -- 信心度

scope

範圍	說明
Per-file	trace_id 在同一個 file_uuid 內唯一，從 0 開始遞增
Global	不同檔案的相同 trace_id 沒有關聯，需搭配 file_uuid 使用

API 端點

# Trace 列表（含 face_count、時間範圍、信心度）
POST /api/v1/file/:file_uuid/face_trace/sortby
Body: {"sort_by": "face_count", "limit": 100}

# Trace 內的人臉偵測（含 interpolation）
GET  /api/v1/file/:file_uuid/trace/:trace_id/faces?page=1&page_size=200

# Trace 綁定身份 (trace→identity)
POST /api/v1/identity/:identity_uuid/bind
Body: {"file_uuid": "...", "trace_id": 5}

Trace 與 Identity 的關係

trace_id (per-file seq)
     │
     ├── identity_id (FK → identities.id)
     │       │
     │       └── identity_uuid (global UUID, 32碼無-)
     │
     └── face_detections (N rows per trace)
             │
             ├── frame_number (哪一幀)
             ├── bbox (位置)
             └── confidence (信心度)

Trace 資料範例

{
  "trace_id": 2,
  "face_count": 46,
  "start_frame": 4587,
  "end_frame": 4722,
  "start_time": 191.38,
  "end_time": 196.95,
  "duration_sec": 5.57,
  "avg_confidence": 0.85,
  "sample_face_id": null
}

生命週期

Face Tracker (Python script)
    → 分析人臉 embedding + IoU + 距離
    → 產生 trace_id (同檔案內獨立 numbering)
    → 寫入 face_detections 表
    → Identity Agent 比對 embedding
    → 設定 identity_id (綁定身份)

特點

特性	說明
順序編號	無 UUID，簡單整數，每個檔案從 0 開始
唯一性	(file_uuid, trace_id) 唯一，trace_id 單獨不唯一
補幀	API 支援 interpolate=true 參數補齊中間幀
綁定	透過 Agent API 綁定到 identity_uuid