4.9 KiB
Phase 2 人物追跡仕様
1. 目的
フレーム単位のYOLO人物検出を追跡し、1実行内の一時ID、軌跡、領域イベント、トリガー通過、方向、人物単位summaryを生成する。顔推定・振り向き判定・音声制御は対象外である。
2. 構成と追跡方式
PersonDetector -> list[Detection] -> PersonTracker -> list[TrackedPerson]
|
v
TrackManager
events / states / counters
Ultralytics同梱の BYTETracker を使用する。既存依存とバージョンを揃えられ、高信頼検出と低信頼検出の二段階関連付けが遮蔽に有効なためである。内部のResults・トラック型は tracker.py の入力アダプタと出力正規化から外へ出さない。
3. DetectionからTrackedPersonへの変換
Detectionのxyxy、信頼度、class IDをByteTrack入力へ変換する。出力BBoxを画像内へクリップし、不正Boxとperson以外を除外する。公開IDは整数で、外部tracker IDを実行内で単調増加するIDへ写像する。確定状態、age、missedを独自dataclassへ格納する。
4. ByteTrack設定
高・低信頼閾値、新規track閾値、match閾値、buffer、最低確定フレーム、最大miss、score融合をYAMLで設定する。追跡有効時は skip_frames=0 を要求し、推論を飛ばした検出を再利用しない。
5. TrackManager
人物ごとに初回・最終時刻、表示・missフレーム、上限付き軌跡、確定状態、領域・交差イベントを保持する。最大missを超えるとlostとfinalizedを生成し、動画終端、Ctrl+C、通常終了時は全active trackを同じ経路で最終化する。
6. 評価領域
足元点を使用する。初回が領域内なら即時進入とする。それ以外の進入と退出は設定数の連続フレームで確定し、同一種類のイベントを重複生成しない。
7. トリガーライン
縦線はleft/right、横線はtop/bottomの反対側への移動を検出する。確定track、最低点数、デッドバンド、最小変位を要求し、既定ではIDごとに1回だけ記録する。
8. 移動方向
トリガーラインを通過済みで通過方向がある場合、観測済みの trigger_crossing_direction を最終的な movement_direction として最優先する。これにより、通過後に停止した人物がsummaryでstationaryへ上書きされることを防ぐ。通過方向がない場合のみ、直近 direction_window_points の最初と最後の足元点を比較する。支配的な軸と符号から4方向を決め、十分な変位がない場合だけstationary、点不足はunknownとする。
9. 人数定義
- Active Tracks: activeかつ確定
- Total Unique Tracks: 実行中に一度でも確定したID
- Region Visitors: 領域進入済み確定ID
- Trigger Crossings: ライン通過済み確定ID
- Completed Passers: 最終化済みで最低表示時間・領域・交差条件を満たすID
10. CSV
Phase 1検出CSVに加え、tracking_frames（人物・フレーム単位）、events（イベント単位、metadata JSON）、track_summary（最終人物単位）を data/logs/tracking へUTF-8 BOM付きで保存する。summaryはtrack IDごとに重複防止する。
11. 例外と停止
初期化失敗はTrackerError、状態管理はTrackManagementError、CSVはTrackingLogErrorの体系を用意する。単一フレームのtracker更新失敗は記録して空出力とし、次フレームを継続する。停止時は最終化、ログ、tracker、camera、writer、windowの順で確実に解放する。一時停止中は取得・追跡・miss・ログ・時刻を進めない。
12. テスト
外部モデル不要でdataclass、縦横交差、デッドバンド、重複防止、進入退出ヒステリシス、stale/finalize、方向、集計妥当性、3種CSV、BOM、JSONを検証する。ByteTrack実映像性能は手動評価対象とする。
13. 受入・手動評価
同一人物IDの維持、複数ID、遮蔽、進入・退出・交差の一回性、方向、終了summary、カウンタ分離を確認する。シナリオは左右通過、2人並行・交差、遮蔽、ライン停止・往復、浅い領域進入、画面端、再入場、30分運転、CSV整合である。ID switch、fragmentation、誤track、見逃し、実数対システム数、交差誤り、平均・最低FPSを記録する。
14. Phase 3への引き継ぎ
list[TrackedPerson] のtrack ID、BBox、confidence、領域状態と TrackState.trajectory をFaceProcessorへ渡し、HeadPoseResult(track_id, pitch, yaw, roll) と対応付ける。追跡IDは顔認証ではなく、再起動・再入場・遮蔽で変わり得る一時IDである。