73 lines
6.1 KiB
Markdown
73 lines
6.1 KiB
Markdown
# 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では判定・音声・反応時間を扱わない。
|
||
|
||
```text
|
||
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、変化量、振り向きレベル、開始・最大・継続時間、品質除外を算出する。
|