From 77598a4713281aad0e924dc45ce1e572ed431bdb Mon Sep 17 00:00:00 2001
From: Warren <warren@momentry.ddns.net>
Date: Fri, 8 May 2026 13:45:35 +0800
Subject: [PATCH] docs: add XY trajectory visual encoding guide with
 color/size/fade

---
 .../TRACE/TRACE_HEATMAP_SPEC_V1.0.0.md        | 90 ++++++++++++++++---
 1 file changed, 78 insertions(+), 12 deletions(-)

diff --git a/docs_v1.0/API_V1.0.0/TRACE/TRACE_HEATMAP_SPEC_V1.0.0.md b/docs_v1.0/API_V1.0.0/TRACE/TRACE_HEATMAP_SPEC_V1.0.0.md
index 243ae4b..65d6210 100644
--- a/docs_v1.0/API_V1.0.0/TRACE/TRACE_HEATMAP_SPEC_V1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/TRACE/TRACE_HEATMAP_SPEC_V1.0.0.md
@@ -125,23 +125,89 @@ face_density
 
 #### 雙軸軌跡圖 (xy)
 
-同時顯示 X 和 Y：
+同時顯示 X 和 Y，時間用視覺編碼隱含在圖中。
+
+##### 視覺編碼方式
+
+| 方法 | 做法 | 適用場景 |
+|------|------|---------|
+| **顏色漸層** | 點/線從冷色到暖色 (🔵→🟢→🟡→🔴) | 單一 entity 的時間流向 |
+| **點大小漸變** | 點從大到小（或反比） | 多 entity 疊加時 |
+| **殘影軌跡** | 舊位置淡出 (██→░░) | 短片段的細微移動 |
+| **箭頭標記** | 起點標 S，終點標 E | 展示片段或 demo |
+
+##### 顏色漸層法
 
 ```
 Y%
-100% ┤
-     │     ╔══ Audrey
- 75% ┤    ║
-     │    ║     ╔══ Cary
- 50% ┤    ║    ║
-     │    ║    ║
- 25% ┤    ║    ║
-     │   ╔╝    ║
-  0% ┤──╚──────╚────────→ X%
-     0%   25%   50%   75% 100%
+  │  🔵──🔵                    🔵 = t=0s (冷色)
+  │       ──🔵──🔵             🟢 = t=1000s
+  │              ──🟢──🟢      🟡 = t=2000s
+  │                     ──🟠──🔴  🔴 = t=3000s (暖色)
+  └─────────────────────────→ X%
+
+閱讀方向：🔵 → 🔴，冷到暖 = 時間前進
 ```
 
-點的大小隨時間變化（大到小 = 時間前進），顏色代表不同 identity。
+##### 點大小法
+
+```
+Y%
+  │  ○──○                    ○ = t=0s (小)
+  │       ──○──○             
+  │              ──◉──◉      ◉ = t=2000s (中)
+  │                     ──●──●  ● = t=3000s (大)
+  └─────────────────────────→ X%
+
+閱讀方向：小○ → 大●，自然形成時間箭頭
+```
+
+##### 實際範例：Cary Grant 走過房間
+
+```
+Y% (畫面高度)
+ 100% ┤
+      │
+  75% ┤
+      │           ●Cary(t=2730s)
+      │        ◉──┘
+  50% ┤     ◉
+      │  ◉──┘
+  25% ┤●Cary(t=2707s)
+      │
+   0% ┤
+      └─────────────────────────→ X% (畫面寬度)
+       0%   25%   50%   75%  100%
+
+顏色：🔵→🟢→🟡→🔴  (2707s → 2770s，共 44 秒)
+判讀：Cary 從畫面左下走進，往右上方移動到中央
+```
+
+##### 多 Identity 疊加
+
+不同顏色代表不同人，直接看 XY 路徑交會：
+
+```
+Y%
+  │  🔵════🔵               🔵 Cary Grant
+  │         ║
+  │         ║    🔴══🔴     🔴 Audrey Hepburn
+  │         ║   ║
+  │         ╚═══╝
+  │        交會處 ═ 兩人同時出現在同一區域
+  └────────────────────────→ X%
+```
+
+##### 判讀方式
+
+| 圖形 | 意義 |
+|------|------|
+| 斜線 ↗↘ | 人物在畫面中移動 |
+| 水平線 → | 人物左右移動（高度不變） |
+| 垂直線 ↑↓ | 人物上下移動（左右不變） |
+| 聚集點 ●●● | 人物長時間停留（坐著、站定位） |
+| 兩條線交叉 ✕ | 兩人同時出現在同一區域 |
+| 平行線 ═══ | 兩人同方向移動（一起走） |
 
 #### 縱向軌跡範例 (axis=y)