docs: trace heatmap spec v1.0.0 — spatial + temporal + combined
This commit is contained in:
Warren
183
docs_v1.0/API_V1.0.0/TRACE/TRACE_HEATMAP_SPEC_V1.0.0.md
Normal file
183
docs_v1.0/API_V1.0.0/TRACE/TRACE_HEATMAP_SPEC_V1.0.0.md
Normal file
@@ -0,0 +1,183 @@
|
||||
# Trace Heatmap Specification v1.0.0
|
||||
|
||||
## Concept
|
||||
|
||||
將臉部追蹤資料標準化為熱力圖格式，包含空間（畫面位置）和時間（影片進度）兩個維度。
|
||||
|
||||
## Data Model
|
||||
|
||||
### 1. Spatial Heatmap — 臉在哪裡？
|
||||
|
||||
將畫面划分為 grid，計算每個 cell 的 face 活動量：
|
||||
|
||||
```
|
||||
frame (1920×1080)
|
||||
┌──────────────────────┐
|
||||
│ ░░ ░░ ░░░░ │ y
|
||||
│ ░░░░░░░░░░░░░░ │
|
||||
│ ░░░░░░░░░░░░ │
|
||||
│ ░░░░░░░░ │ ← 活動集中在畫面中央
|
||||
│ ░░ │
|
||||
└──────────────────────┘
|
||||
x →
|
||||
```
|
||||
|
||||
### 2. Temporal Heatmap — 什麼時候有臉？
|
||||
|
||||
```
|
||||
face_density
|
||||
│ ██ ████ ██
|
||||
│ ██ ██ ████ ██ ██
|
||||
│ ██ ██ ██████ ██ ██
|
||||
└──────────────────────────→ time
|
||||
0s 3000s 6000s
|
||||
```
|
||||
|
||||
## API Design
|
||||
|
||||
### GET /api/v1/file/:file_uuid/face_trace/heatmap
|
||||
|
||||
回傳標準化熱力圖資料。
|
||||
|
||||
#### Query Parameters
|
||||
|
||||
| Param | Type | Default | Description |
|
||||
|-------|------|---------|-------------|
|
||||
| `type` | enum | `spatial` | `spatial` \| `temporal` \| `combined` |
|
||||
| `grid_x` | int | 20 | Spatial: X axis grid cells |
|
||||
| `grid_y` | int | 12 | Spatial: Y axis grid cells |
|
||||
| `bin_sec` | int | 60 | Temporal: time bucket in seconds |
|
||||
| `time_start` | float | 0 | Time range start (seconds) |
|
||||
| `time_end` | float | — | Time range end (default: video duration) |
|
||||
| `min_confidence` | float | 0.5 | Minimum detection confidence |
|
||||
| `trace_ids` | string | — | Comma-separated trace_id filter (optional) |
|
||||
|
||||
#### Response: Spatial
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "spatial",
|
||||
"frame_width": 1920,
|
||||
"frame_height": 1080,
|
||||
"grid_x": 20,
|
||||
"grid_y": 12,
|
||||
"cell_w": 96,
|
||||
"cell_h": 90,
|
||||
"data": [
|
||||
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
|
||||
[0, 0, 0, 0, 0, 1, 2, 3, 3, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0],
|
||||
[0, 0, 0, 1, 3, 5, 8, 12, 14, 10, 6, 3, 1, 0, 0, 0, 0, 0, 0, 0],
|
||||
[0, 0, 1, 4, 8, 15, 25, 35, 40, 32, 20, 10, 4, 1, 0, 0, 0, 0, 0],
|
||||
...
|
||||
],
|
||||
"max_value": 40,
|
||||
"total_detections": 108204,
|
||||
"total_traces": 6892
|
||||
}
|
||||
```
|
||||
|
||||
#### Response: Temporal
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "temporal",
|
||||
"bin_sec": 60,
|
||||
"duration": 5954,
|
||||
"bins": [
|
||||
{"t_start": 0, "t_end": 60, "face_count": 45, "trace_count": 12, "avg_confidence": 0.82},
|
||||
{"t_start": 60, "t_end": 120, "face_count": 120, "trace_count": 28, "avg_confidence": 0.79},
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Response: Combined
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "combined",
|
||||
"bin_sec": 60,
|
||||
"grid_x": 20,
|
||||
"grid_y": 12,
|
||||
"duration": 5954,
|
||||
"data": [
|
||||
{
|
||||
"t_start": 0,
|
||||
"t_end": 60,
|
||||
"heatmap": [[...], [...]],
|
||||
"max_cell": 8,
|
||||
"face_count": 45
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Standardization Rules
|
||||
|
||||
1. **Normalization**: All values normalized to 0.0–1.0 range with `max_value` for rendering
|
||||
2. **Resolution independence**: Grid size configurable, always returns `cell_w`/`cell_h`
|
||||
3. **Temporal bucketing**: Default 60s bins, adjustable
|
||||
4. **Filterable**: By time range, confidence, specific traces
|
||||
5. **Cachable**: Response includes `file_uuid` + query hash for CDN/Redis cache
|
||||
|
||||
## Frontend Rendering
|
||||
|
||||
### Spatial Heatmap (Canvas)
|
||||
|
||||
```javascript
|
||||
function renderHeatmap(canvas, data) {
|
||||
const cellW = canvas.width / data.grid_x;
|
||||
const cellH = canvas.height / data.grid_y;
|
||||
for (let y = 0; y < data.grid_y; y++) {
|
||||
for (let x = 0; x < data.grid_x; x++) {
|
||||
const intensity = data.data[y][x] / data.max_value;
|
||||
ctx.fillStyle = `rgba(255, 0, 0, ${intensity})`;
|
||||
ctx.fillRect(x * cellW, y * cellH, cellW, cellH);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Temporal Heatmap (SVG)
|
||||
|
||||
```svg
|
||||
<rect x="0" y="0" width="10" height="100" fill="rgba(255,0,0,0.1)" />
|
||||
<rect x="10" y="0" width="10" height="100" fill="rgba(255,0,0,0.3)" />
|
||||
```
|
||||
|
||||
## Implementation
|
||||
|
||||
### Backend (src/api/trace_agent_api.rs)
|
||||
|
||||
Add new route:
|
||||
```rust
|
||||
.route("/api/v1/file/:file_uuid/face_trace/heatmap", get(list_trace_heatmap))
|
||||
```
|
||||
|
||||
### SQL (spatial)
|
||||
|
||||
```sql
|
||||
SELECT
|
||||
FLOOR(x / $grid_w) AS cell_x,
|
||||
FLOOR(y / $grid_h) AS cell_y,
|
||||
COUNT(*) AS intensity
|
||||
FROM dev.face_detections
|
||||
WHERE file_uuid = $1 AND confidence >= $2
|
||||
GROUP BY cell_x, cell_y
|
||||
ORDER BY cell_x, cell_y;
|
||||
```
|
||||
|
||||
### SQL (temporal)
|
||||
|
||||
```sql
|
||||
SELECT
|
||||
FLOOR(frame_number / ($fps * $bin_sec)) AS bin,
|
||||
COUNT(*) AS face_count,
|
||||
COUNT(DISTINCT trace_id) AS trace_count,
|
||||
AVG(confidence) AS avg_confidence
|
||||
FROM dev.face_detections
|
||||
WHERE file_uuid = $1 AND confidence >= $2
|
||||
GROUP BY bin
|
||||
ORDER BY bin;
|
||||
```
|
||||
Reference in New Issue
Block a user