6.1 KiB
Phase 3 顔向き推定仕様
推奨依存環境
MediaPipeとNumPy/OpenCVの要件衝突を避けるため、Phase 3の推奨・固定環境は mediapipe==0.10.21、numpy==1.26.4、opencv-contrib-python==4.11.0.86 の組み合わせとする。opencv-contrib-python が通常の cv2 APIも提供するため、opencv-python は同じ仮想環境へ導入しない。既存環境に両方が存在する場合は、関連する4パッケージをアンインストールしてから requirements.txt を再インストールする。
1. 目的と構成
Phase 2の TrackedPerson ごとに顔ランドマークと近似Head Poseを取得し、track ID、frame、時刻に対応付ける。Phase 4の基準Yaw・振り向き判定の入力基盤であり、本Phaseでは判定・音声・反応時間を扱わない。
TrackedPerson -> FaceROI -> FaceProcessor(MediaPipe) -> FaceLandmark
|
v
HeadPoseEstimator(solvePnP)
|
v
HeadPoseResult -> FaceTrackManager -> CSV / display
2. FaceROI
人物Box上端から roi_height_ratio（既定0.45）までを候補とし、候補の幅・高さを roi_expand_ratio だけ拡張して画像内へクリップする。最小寸法、確定track、評価領域条件で除外する。面積の大きい領域内人物を優先し、1フレームの最大処理人数を制限する。
3. MediaPipe Face Mesh
各ROIをBGRからRGBへ変換してFace Meshへ渡す。複数顔の場合はROI中心に最も近い顔を採用する。正規化されたROI座標をフレーム全体のpixel座標へ変換し、MediaPipe型を外へ漏らさない。例外や未検出はtrack単位のfailure resultに変換する。
4. 使用ランドマークとHead Pose
MediaPipe index 1（nose tip）、152（chin）、33/263（左右目尻）、61/291（左右口角）を使う。顔の上下・左右へ広く分布し、一般的な6点solvePnP近似と対応しやすいためである。簡易3Dモデルの単位は任意で、相対形状が重要である。モデルのY軸はOpenCV画像座標と同じ下向きを正とし、正面顔が約180°回転として解かれる座標系不一致を避ける。
OpenCV solvePnP と Rodrigues で回転行列を求め、X/Y/Z回転をPitch/Yaw/Rollとしてdegreeで返す。本実装上、正のPitchはX軸正回転、正のYawはY軸正回転、正のRollはZ軸正回転である。ただし画像座標、カメラ設置、鏡像反転によって直感的な左右・上下と符号が一致しない場合がある。
顔平面の軸反転によるsolvePnPの等価解では、直立した正面顔でもRollが±180°付近になることがある。本研究では通常の直立した通行人を対象とするため、Rollを軸方向として [-90°, 90°) の等価表現へ正規化する。例えば -170°は10°、170°は-10°として扱う。上下逆さの顔を区別する用途にはこの正規化を使用できない。
5. カメラ行列の近似と制約
焦点距離をframe width、主点を画像中心、歪み係数をゼロとする。カメラキャリブレーションを行わないため絶対角度には系統誤差があり、同一条件下の変化量を優先する。Phase 4前に実機で符号と基準値を確認する。
6. 平滑化と頻度制御
推定成功値をtrack ID別EMA（既定alpha 0.4）で平滑化し、失敗時は更新しない。process_every_n_frames=N はNフレームごとに処理し、間引きフレームはface CSVへ書かず画面では直近値を使う。max_persons_per_frame でCPU負荷を制御する。
7. 状態とログ
FaceTrackManager は処理対象フレーム、顔検出・pose成功数、成功率、最新角度、Yaw最小・最大・平均、上限付き時系列を保持する。
face_frames.csv: frame、track ID、成否、角度、landmark数、ROI、失敗理由face_summary.csv: track別成功率、Yaw統計、最終角度、有効性
UTF-8 BOM付きで、summaryはtrack IDごとに一度だけ出力する。
8. 表示
track付近へYaw/Pitch/RollまたはFace NG、FaceROIを表示する。全ランドマーク表示は負荷を考慮して既定false。左上にface enabled、Face OK、Pose OKを表示する。無効時もPhase 1・2描画を維持する。
9. 例外・無効状態
roi_too_small、face_not_detected、insufficient_landmarks、solvepnp_failed、angle_out_of_range、mediapipe_error を結果で区別する。真横付近の近似誤差を許容する既定上限は120°とする。範囲外でも計算済みraw角度はCSVと画面へ残し、符号・閾値調整に利用する。face無効・処理間引きは結果とCSV行を生成しない。tracker無効時はtrack IDを安定管理できないためfaceを自動無効化し、実行ログに警告する。フレーム単位の失敗は検出・追跡を停止させない。
10. テスト
実モデルなしでROI比率・拡張・クリップ・除外、モデル型、成功率とYaw統計、カメラ行列、点不足、Euler変換、角度範囲、EMA用状態、CSV/BOM/失敗行/summary重複を検証する。MediaPipeは遅延importし、標準pytestは未導入環境でも実推論を要求しない。
11. 実機確認
正面、右、左、上、下、首傾斜について角度と符号を記録する。通行中track IDとの対応、顔なし人物、複数人、最大処理人数、face CSV、CPU平均・最低FPSを確認する。右・左Yawが逆方向へ変化すること、上下Pitch、傾斜Roll、正面安定性を重点評価する。
12. Phase 4への引き継ぎ
安定提供する値はtrack ID、frame、timestamp、face/pose成否、Pitch/Yaw/Roll、failure reason、顔検出率、pose推定率である。Phase 4はrecent historyから基準Yaw、変化量、振り向きレベル、開始・最大・継続時間、品質除外を算出する。