4.6 KiB
Phase 4 振り向き判定仕様
1. Phase 4の目的
track ID付きHead PoseのYaw時系列から、サイネージ方向への顔向き変化、継続時間、強度、評価可否を算出する。音声提示や声掛け後反応はPhase 5の対象である。
2. システム構成
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 metadataturn_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を計算する。