SignageSystem/docs/head_pose_smoothing.md

頭部角度（Yaw）の平滑化フィルタと静止時ゆらぎ

静止していてもYawが変化する問題に対する調査記録と、選択可能なフィルタの説明。

設定（config/default.yaml の head_pose）

キー	既定値	内容
smoothing_enabled	true	false で平滑化なし（none と同じ）
smoothing_method	ema	none / ema / median_ema / hampel_ema / one_euro / median_one_euro
ema_alpha	0.4	EMA係数。median_ema・hampel_ema でも使用
smoothing_window	5	窓幅（サンプル数）。窓の時間幅は姿勢更新レートに依存する
hampel_threshold	3.0	Hampel判定のしきい値（頑健σの倍数）
one_euro_min_cutoff / one_euro_beta / one_euro_d_cutoff	1.0 / 0.0 / 1.0	One Euro Filter のパラメータ
filter_reset_gap_sec	0.0	姿勢サンプルがこれより離れたらフィルタ状態をリセット（0で無効）
smoothing_window_sec	0.0	0より大きいと、中央値系フィルタの窓を「直近N秒」で指定する（smoothing_window より優先）。更新レートが変わってもフィルタの強さが変わらない
max_reprojection_error_ratio	0.0	再投影誤差が「目尻間距離×この値」を超えた姿勢を棄却（0で無効）。正常フレームの比率は約0.07、破綻フレームは0.4以上

既定値は従来動作（ema, α=0.4）と同じ。新キーはYAMLに書かなくてもよい（既定値が使われる）。 フィルタ本体は src/yaw_filters.py。

計測と比較の手順

1. 正面静止で30〜60秒ログを取る（data/logs/face/*_face_frames.csv。raw_yaw 列が生値）。
2. python -m src.yaw_noise_report <csv> --track-id N --t-start 4 --t-end 44 --csv out.csv
3. 各フィルタのSD・最大変動幅・フレーム間ジッタを比較する。 遅れは静止データからは測れないので、階段・ランプ入力のシミュレーションまたは実際の振り向き試行で確認する。

計測結果（2026-10-01, 研究室, 正面・3m・静止, 4〜44秒, n=714, 約17.8Hz, 1280x720）

フィルタ	SD	最大変動幅	階段90%遅れ	ランプ遅れ
生Yaw	6.27°	49.6°	0	0
ema 0.4（従来）	3.77°	28.1°	0.22秒	0.06秒
median5 + ema 0.4	1.92°	17.1°	0.34秒	0.17秒
median5 + one_euro(1.0, β=0.02)	1.96°	20.0°	0.22秒	0.11秒
hampel w7 k3 + ema 0.4	2.17°	21.9°	0.39秒	-

• 遅れは、サンプル間隔0.056秒で、0→30°のステップ入力が27°に達するまでの時間（ランプは60°/sで増加する入力に対する遅れ）。
• 1か所・1距離・1人の静止データによる比較。実際の振り向き中の挙動は未検証。
• 現行（ema 0.4）の出力は、静止していても3σ=11.3°、最大変動幅28°あり、subtle(10°)・weak(20°)のしきい値に達しうる。

追加計測（2026-10-02, 研究室, 正面・3m・静止＋移動, median5+EMA 0.4設定時のログ, 約23.1Hz）

静止区間（フレーム250〜1390, 49.3秒）：

フィルタ	SD	最大変動幅	平均から8°超の外れ	階段90%遅れ
生Yaw	9.02°	72.6°	-	0
ema 0.4（旧デフォルト）	5.70°	54.3°	11.5%	0.17秒
median5 + ema 0.4	3.50°	38.8°	2.5%	0.26秒
median 0.45秒 + ema 0.5	2.27°	31.0°	0.5%	0.35秒
median 0.55秒 + ema 0.5	1.85°	9.9°	0.0%	0.39秒

• 実機の yaw 列は、生Yawにオフラインで同じフィルタをかけた結果と一致した（最大差 9e-7）。
• 生Yawの+側スパイクは8.7%。連続長は1フレーム46回・2連続17回・3連続3回・4連続1回・6連続1回。 中央値は、窓n個で(n-1)/2連続までのスパイクを除去できる。median5（n=5）は2連続まで。
• 移動しながら向く区間（フレーム218〜240）で、生Yawは-68.7°→-23.1°。90%到達は median5+EMA0.4が0.76秒、旧デフォルトが0.67秒、median 0.55秒+EMA0.5が0.80秒（50%到達は0.31/0.09/0.40秒）。 窓を広げても、実際の振り向きでの追加の遅れは小さい。
• 再投影誤差/目尻間距離の比は、正常フレームで p99 でも0.12〜0.19。0.4以上のフレームはすべて、 目尻間距離が20px以下の小さい顔（入退場の移動中）で、Yawも破綻していた（例: 比104.9でYaw -1.0°、比150でYaw -66.7°）。 比0.3で除外すると、静止区間のフレームは1つも除外されず、破綻フレームだけが落ちる。 静止時のスパイクとは相関しない（スパイク1.58px、その他1.57px）。
• 静止中の中央値からの逸脱が10°を超えた状態の連続時間は、旧デフォルトで最長0.27秒、median5で0.22秒、 median 0.55秒窓ではさらに短い。min_turn_duration_sec(0.3秒)との余裕は、窓を広げるほど大きくなる。

分かったこと

• 生Yawの分散の大部分は、フレームごとの独立なノイズと、単発の+側スパイク（約5%）による。 中央値系フィルタ（median / Hampel）が単発スパイクに有効。
• ROI・bboxのフレーム間ゆらぎは0.3〜0.5px程度で、原因ではない。
• 再投影誤差はスパイクと相関せず（外れ値フレーム1.59px、その他1.58px）、除外基準には使えない。
• 顔が小さい（3mで目尻間距離が約24px）ため、ランドマーク0.5px程度の誤差で、Yawの標準偏差は4〜5°程度になる （シミュレーションで確認。実測の6.3°と同水準）。ROIを拡大しても元画素数は増えない。 → 精度を上げるには、距離を縮める・解像度を上げる・望遠にするなど、顔を大きく映す対策が最も効く。
• useExtrinsicGuess（前フレームの解を初期値にする）はシミュレーション上で効果なし。実装していない。
• 焦点距離の仮定（現行はフレーム幅=1280px、実際は約800px相当と推定）は、Yawへの影響が1°未満。

注意点（要確認）

• Yawの符号が反転している可能性が高い。 src/head_pose.py の MODEL_POINTS はYを下向きに直した一方で zの符号は据え置かれ、目・口が鼻先より手前にある（奥行きが反転した）顔になっている。 シミュレーションでは、実際の頭部回転に対して推定Yawの符号が反転した（真値+15°→推定-15°、大きさは保たれる）。 turn_detection.signage_yaw_direction が実測に合わせて設定されていれば結果は一貫するが、 「正のYaw＝物理的にどちら向きか」を前提にした解釈・報告では注意が必要。 モデルを直す場合は符号が変わるので、signage_yaw_direction と過去ログの扱いも同時に見直すこと。
• 正面を向いた静止時のYaw中央値が、2回の計測（2026-10-01, 10-02）とも約-20°だった（bbox中心はそれぞれ671px, 680px。 画像中心640pxから約30〜40px、約2°しか離れていない）。立ち位置では説明できない。 レンズとプレビュー画面は物理的に離れているため、プレビューを見ていた可能性は除外されている。 原因は未解明（3Dモデル点と実際の顔の不一致、頭部の実際の向きなど）。 距離を変えて（例: 1.5m）測り、オフセットが距離で変わるか（小さい顔による見かけの偏り）、 変わらないか（系統的なずれ）を確認する。振り向き検出は基準Yawとの差を使うので、固定のオフセットは影響しない。
• 一部の設定値（median_one_euro の β など）は、この静止データのノイズ規模に合わせたもの。距離が変わったら再評価する。