---
document_type: "spec"
service: "MOMENTRY_CORE"
title: "Pose Processor V1.0.0"
date: "2026-05-02"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
parent: "PROCESSOR_SELECTION_V1.0.0.md"
tags:
  - "momentry"
  - "core"
  - "processor"
  - "pose"
  - "mediapipe"
  - "pose-estimation"
  - "v1.0.0"
ai_query_hints:
  - "Pose 使用 MediaPipe Pose (pose_landmarker_heavy, 33 keypoints)"
  - "Pose 處理 159.6s 影片全幀約 65.87s，即時倍率 2.4x"
  - "Pose 輸出 1853 frames, 2341 persons, 603KB"
  - "Pose 支援 GPU 加速（uses_gpu = true）"
  - "Pose 與 YOLO 同為處理瓶頸之一"
related_documents:
  - "PROCESSOR_SELECTION_V1.0.0.md"
  - "../YOLO_V1.0.0.md"
  - "../FACE_V1.0.0.md"
  - "../CUT_V1.0.0.md"
  - "../CHUNK_DEFINITION_V1.0.0.md"
---

# Pose Processor V1.0.0

| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-05-02 |
| 文件版本 | V1.0 |

**狀態**: ✅ 100% | **模型**: MediaPipe Pose | **GPU**: 是

## 關鍵術語定義

| 術語 | 定義 |
|------|------|
| Pose Estimation | 姿態估計，偵測人體關鍵點位置 |
| MediaPipe | Google 開發的跨平台 ML 解決方案 |
| keypoint | 關鍵點，pose_landmarker_heavy 輸出 33 個關鍵點 |
| landmarker_heavy | MediaPipe 的精確模式，準確度最高但速度較慢 |
| bottleneck | 處理瓶頸，Pose 與 YOLO 同為最耗時的 processor |

---

## 選型過程

使用 MediaPipe Pose（pose_landmarker_heavy, 33 keypoints）。

---

## 效能實測（ExaSAN 159.6s 影片, 全幀處理）

| 指標 | 值 |
|------|-----|
| 處理時間 | 65.87s |
| 即時倍率 | 2.4x（瓶頸之一，與 YOLO 相當） |
| 輸出 | 1853 frames, 2341 persons, 603KB |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-05-02 | 初始版本 | OpenCode | deepseek-chat |

## 資源預估

| 資源 | 值 |
|------|-----|
| CPU | 0.4 |
| 記憶體 | 1024 MB |
| GPU | 支援（`uses_gpu = true`） |
| 依賴 | 無 |

---

## Apple Vision Framework 替代實作

### POC 結果

使用 `VNDetectHumanBodyPoseRequest`（ANE 加速）取代 MediaPipe/YOLOv8 Pose。

測試影片：Thunderbolt ExaSAN at CCBN (24fps, sample_interval=90)

| 指標 | YOLOv8 Pose (CPU) | Vision Framework (ANE) |
|------|-------------------|----------------------|
| **Per frame** | **45ms** | **9ms** ⚡ |
| **加速比** | 1x | **5x** |
| **Joints** | 17 keypoints (COCO) | **19 joints** |
| **ANE 加速** | ❌ CPU only | ✅ **是** |
| **記憶體** | ~1GB (PyTorch) | 極低（系統框架） |
| **Joint 品質** | ✅ 標準 COCO | neck/shoulders 高 conf |

### 選型結論

Vision Framework body pose 在速度（5x）和資源使用上均優於 YOLOv8 Pose，且 ANE 加速不佔 CPU。

**決定**: 以 Apple Vision Framework `VNDetectHumanBodyPoseRequest` 取代 YOLOv8 Pose。

### 實作

`scripts/swift_processors/swift_pose.swift` 為完整 Pose processor，支援：
- 影片逐幀 / 取樣處理
- 輸出格式相容於 Rust `PoseResult` struct
- 可透過 `pose_processor.py` wrapper 被 PythonExecutor 呼叫
- ANE 加速，19 joints（neck, shoulders, elbows, wrists, hips, knees, ankles, root, nose, eyes, ears）

### 相關檔案

```
scripts/swift_processors/swift_pose.swift        # Vision Framework pose processor
scripts/swift_processors/pose_benchmark.swift     # Benchmark test
```

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-05-02 | 初始版本 | OpenCode | deepseek-chat |
| V1.1 | 2026-05-04 | 以 Apple Vision Framework 取代 YOLOv8 Pose | OpenCode | deepseek-chat |
