docs: add X-axis + xy trajectory modes, API request format

docs_v1.0/API_V1.0.0/TRACE/TRACE_HEATMAP_SPEC_V1.0.0.md

@@ -28,6 +28,26 @@ Search Query
 
 核心：一個標準模組，**設定條件 → 熱力圖 + timeline + 位置參考**，適用於任何可追蹤實體。
 
+## API
+
+### POST /api/v1/file/:file_uuid/heatmap
+
+#### Request
+
+```json
+{
+  "type": "face | object | pose | identity",
+  "trajectory_axis": "y | x | xy",
+  "filter": {
+    "identity_ids": [2102, 187],
+    "trace_ids": [3128, 3126],
+    "object_class": "person",
+    "min_confidence": 0.5,
+    "time_range": [0, 5954]
+  }
+}
+```
+
 ```
 輸入條件                    輸出
 ┌─────────────┐          ┌──────────────────────┐
@@ -81,17 +101,49 @@ face_density
 | `min_confidence` | float | 0.5 | Minimum detection confidence |
 | `trace_ids` | string | — | Comma-separated trace_id filter (optional) |
 
-##### Type: `trajectory` — 2D 軌跡圖 (縱向位置 × 時間)
+##### Type: `trajectory` — 2D 軌跡圖 (位置 × 時間)
 
-將畫面 Y 軸位置對應時間，把 3D 時空 (x, y, t) 投影到 2D (y, t) 平面上。
+將 3D 時空 (x, y, t) 投影到 2D 平面上，可選三種投影方式。
 
-#### 為什麼只看縱向 (y)？
+| 模式 | 參數 `axis` | 投影 | 用途 |
+|------|:-----------:|------|------|
+| 縱向軌跡 | `y` | (y, t) | 站/坐/蹲/離開畫面 — 人物本身的動作 |
+| 橫向軌跡 | `x` | (x, t) | 人物在畫面中左右移動、穿越 |
+| 雙軸軌跡 | `xy` | (y, x + t) | 同時顯示左右移動 + 上下動作 |
 
-- 鏡頭多為水平固定，橫向移動（x 軸）通常反映的是鏡頭 pan，不是人物的真實移動
-- 縱向（y 軸）才是人物本身的動作：**站 → 蹲 → 坐下 → 離開畫面**
-- 時間軸（t 軸）則顯示這些動作發生的**節奏**
+#### 為什麼需要 X 軸？
 
-#### 視覺化範例
+| 動作 | X 軸變化 | Y 軸變化 | 判讀 |
+|------|:--------:|:--------:|------|
+| 人物走過畫面（左→右） | ⬆️ | — | X 上升，Y 不變 |
+| 鏡頭 pan（跟拍） | ➡️ 整條線平移 | — | 所有 entity X 同時變化 |
+| 人物站起來 | — | ⬆️ | Y 上升，X 不變 |
+| 人物走近鏡頭 | — | ⬇️ (臉變大) | bbox height 增加，Y 可能下降 |
+| 人物穿越 + 站起 | ⬆️ | ⬆️ | X + Y 同時上升 |
+
+加上 X 軸後可以區分「人物自己移動」vs「鏡頭在動」。鏡頭 pan 時所有 entity 的 X 會同時平移；人物自己走則只有單一 entity 的 X 變化。
+
+#### 雙軸軌跡圖 (xy)
+
+同時顯示 X 和 Y：
+
+```
+Y%
+100% ┤
+     │     ╔══ Audrey
+ 75% ┤    ║
+     │    ║     ╔══ Cary
+ 50% ┤    ║    ║
+     │    ║    ║
+ 25% ┤    ║    ║
+     │   ╔╝    ║
+  0% ┤──╚──────╚────────→ X%
+     0%   25%   50%   75% 100%
+```
+
+點的大小隨時間變化（大到小 = 時間前進），顏色代表不同 identity。
+
+#### 縱向軌跡範例 (axis=y)
 
 一個人從上往下走，在畫面上的軌跡就是一條斜線：
 
@@ -117,11 +169,13 @@ face_density
 
 | 圖形 | 意義 |
 |------|------|
-| 水平線 `══` | 人物停留在同一高度（坐著、站著不動） |
-| 斜線 `/` `\` | 人物在畫面中移動（站起來 / 蹲下 / 走遠） |
+| 水平線 `══` | 人物停留在同一位置（坐著、站著不動） |
+| 斜線 `/` `\` | 人物在畫面中移動 |
 | 垂直跳躍 `║` | 鏡頭切換（cut），人物出現在不同位置 |
+| X + Y 同時斜線 | 人物在畫面中穿越（walk across） |
+| X 平移 + Y 不變 | 鏡頭 pan 跟拍 |
 | 密集區 `██` | 同一人物長時間出現在該區域 |
-| 空白區 | 人物不在畫面中（或未被偵測到） |
+| 空白區 | 人物不在畫面中 |
 
 #### 多 Identity 疊加
 
@@ -131,6 +185,7 @@ face_density
 - **誰一直在移動？** → 斜線最多的那條
 - **誰和誰同時出現在畫面？** → 時間軸上重疊的段落
 - **誰的位置最高/最低？** → Y 軸位置對比
+- **誰從左邊入鏡？誰從右邊？** → X 軸位置對比
 
 #### 資料格式