# Phase 4 振り向き判定仕様

## 1. Phase 4の目的

track ID付きHead PoseのYaw時系列から、サイネージ方向への顔向き変化、継続時間、強度、評価可否を算出する。音声提示や声掛け後反応はPhase 5の対象である。

## 2. システム構成

```text
HeadPoseResult -> TurnDetector -> TurnFrameResult / TurnEvent / TurnTrackState
TrackManager finalize ---------> TurnTrackManager -> summary
```

## 3. HeadPoseResultからTurnFrameResultへの変換

有効な `HeadPoseResult` をtrack ID別の状態へ入力し、baseline、現在Yaw、raw delta、サイネージ方向delta、candidate、confirmed、levelを持つ `TurnFrameResult` へ変換する。顔処理を間引いたフレームではTurn更新もframeログも行わない。

## 4. サイネージ方向Yawの定義

`positive` は `current - baseline`、`negative` は `baseline - current` をサイネージ方向deltaとし、サイネージへ向く変化を正に統一する。カメラ・鏡像設定ごとに実機で符号を確認する。

## 5. 基準Yaw取得

既定 `first_valid` はwindow内の最初の有効Yawを最低3点集め中央値とする。`before_trigger` はトリガー通過前だけ、`region_entry_window` は領域進入後の指定windowだけ収集する。中央値で瞬間ノイズを抑える。Phase 5で声掛け前windowを追加可能な状態構造とする。

## 6. 振り向きレベル分類

10/20/35/50°をsubtle/weak/medium/strong境界とする。weak以上を主判定とし、subtleは補助反応として保持する。最大delta、発生frame/time、最強levelをtrack単位で保持する。

## 7. 継続時間条件

weak以上は0.30秒、subtleは0.20秒の継続を要求する。elapsed timeで測り、0.30秒以内のpose gapは継続、超過時はcandidateを終了する。

## 8. 顔検出不能ケースの扱い

顔未検出は「振り向きなし」ではない。no face、no pose、baselineなし、sample不足、顔・pose成功率不足をsummaryの除外理由として区別し、`not_evaluable` とする。評価可能で未確定の場合のみ `evaluable_no_turn` とする。

## 9. face_appeared補助イベント

一定時間顔／poseが得られなかった後の有効poseは `face_appeared` 補助イベントとするが、単独ではconfirmedにしない。

## 10. TurnDetector状態管理

TurnDetectorは上限付きYaw/baseline履歴、candidate開始、最終確認、最大delta、最強level、成功率を管理する。イベントはbaseline acquired、face appeared、candidate started、confirmed、level changed、lost、track finalized。confirmedイベントとsummaryはtrack ID単位で重複防止する。

## 11. TurnLogger CSV仕様

- `turn_frames.csv`: frameごとのbaseline、Yaw、delta、candidate、confirmed、level、失敗理由
- `turn_events.csv`: 状態遷移とUTF-8 JSON metadata
- `turn_summary.csv`: 人物単位の成功率、baseline、最大delta、時刻、level、評価可否

すべてUTF-8 BOM付きで、summaryはtrack ID単位に重複を防ぐ。event metadataは `ensure_ascii=False` のJSONで保存する。

## 12. 画面表示

人物付近にTurn levelとdelta、左上に評価可能数、confirmed、subtle、weak+を表示する。評価不能は `Turn:N/A`。一時停止中は状態・時刻・CSVを更新しない。

## 13. 例外処理

tracker、face、head poseのいずれかが無効ならTurnを自動無効化してPhase 1〜3を継続する。顔・pose失敗は評価不能結果として扱い、追跡処理を停止しない。ログI/Oエラーは `TurnLogError` として既存例外体系へ統合する。

## 14. テスト

純粋な合成HeadPoseResultで符号、全境界、中央値baseline、継続、短／長gap、最大delta、イベント一回性、face appeared、評価不能、全CSV/BOM/JSON/summary重複を検証する。実モデル例外は既存FaceProcessorで結果化され、Turnは評価不能として扱う。

## 15. 実機確認手順

静止状態で正面・サイネージ・反対方向を向き、符号を確定する。通過では非注視、軽い／明確／瞬間反応、最初から注視、左右両方向、複数人、face appearedを試す。signage方向、baseline、current、delta、level、confirmed、顔・pose率、除外理由を記録する。

## 16. Phase 5への引き継ぎ

安定インターフェースはtrack ID、baseline/current/delta、level、confirmed、turn start/confirmed time、最大delta、face appeared、分析可否、除外理由である。Phase 5は音声提示時刻を追加し、提示前baselineと提示後response latencyを計算する。