FLOWCOUNTPeople-Flow / Crowd Counting & Tracking
FlowCount は、動画から人物を検出・追跡し、人数と動線を計測するモジュールです。
エンジンは RF-DETR ベースの人物検出と、運動モデル・外観 ReID を備えた box-IoU トラッカー
(rf-detr リポジトリの rfdetr_demo)。
俯瞰（高所設置）カメラを主対象に、群衆の人数カウント・ID 付き追跡・前景の姿勢推定までを 1 パイプラインで行います。
人流・群衆計数・追跡
全員を数えて追い、前景は姿勢まで。オンプレで完結する 2 段階パイプライン。
フレーム独立の検出に、アプリ層で時間一貫性（NMS・トラック hold・外観 ReID）を付与し、 検出人数の点滅を抑えて安定した人数と ID を出力します。遠く小さい人物はタイル推論で拾い、 前景の重要人物だけ高精度な姿勢推定を重ねます。
- 検出 + タイルRF-DETR large。重なりタイルで遠方の人物まで捕捉。
- 追跡 + ReID等速+スケール運動モデル、モーションゲート、外観 ReID で ID を維持。
- 前景 pose上位 N 人を crop→keypoint。全員カウント + 前景の高精度姿勢。
01パイプライン（2 段階）
全員は軽量に数え（①→②）、前景の重要人物だけ③で高精度姿勢を追加する 2 段階構成。詳細は下の手順を参照。
- 検出：RF-DETR large（COCO person）。
--resolutionで小さい人物の recall を調整。任意でタイル推論（重なり分割 → NMS 統合）により遠方の人物を回収。 - 追跡・計数：検出 box を box-IoU トラッカーへ。等速+スケールの運動予測、実装不能な対応を弾くモーションゲート、外観 ReID（色ヒストグラム / ONNX 埋め込み）で遮蔽をまたいで ID を維持。NMS + hold + hysteresis + 期待人数 cap/fill で人数を安定化。
- 前景の姿勢：面積上位 N 人だけを（余白付きで）crop し keypoint モデルで COCO-17 骨格を推定、フレーム座標へ写像して描画。全員は軽量に数え、重要人物のみ高精度。
出力は ID 色分けの注釈動画に加え、平均人数（avg_detections_per_frame）と累計ユニーク ID（Unique track ids over clip）。人数の代表値はオーバーレイ左上の live カウント。
02活用シーン
防災・安全
駅前広場・イベント会場・避難導線の混雑監視。俯瞰カメラでの人数計測が、一定人数超過時のアラート判定の基礎データになる。
商業・店舗
店舗前・売場の通行量や滞在動線の把握。人数カウントと ID 付き追跡による通行量計測。
時間軸との掛け合わせ
時間帯・曜日別の人流変化の把握。定点観測を時系列で蓄積すれば時間帯別レポートの基礎データになる。
そのほか
人流の学術研究、都市計画・施設計画のための基礎調査など。
FlowCount 自体は検出・追跡エンジン（左）までを提供。右の 4 つの応用先はいずれも現時点で未実装（要実装）。
検討中：年齢・性別などの属性分析
人数・動線に加えて年齢層・性別などの属性を推定するニーズも想定されるが、本モジュールでは現時点で実装していない。実装を検討する場合、以下を前提とする。
- 位置づけ：歩行者属性認識（Pedestrian Attribute Recognition, PAR）という既存の研究分野の応用にあたる。確立された手法・データセットの知見を活用する方向で検討する。
- 技術的制約：FlowCount が主対象とする俯瞰・高所カメラでは被写体が遠方かつ見下ろし角度になるため、顔ベースの年齢・性別推定は精度が低下しやすい。歩容（gait）や服装・体型など顔以外の手がかりが中心になると見込まれる。
- 精度の偏りへの留意：年齢・性別推定モデルは学習データセットの構成に起因して人種・年代によって精度に偏りが生じることが既存研究で報告されている。導入時は対象環境・対象属性でのバイアス検証を必須とする。
プライバシー設計方針（実装前に確定させる前提事項）：個人を識別する情報（顔画像・生体特徴量）は保持せず集計値のみを保持する／属性推定結果は追跡 ID・動線データと分離し個人の行動追跡には紐付けない／導入は対象国・地域の個人情報保護法制を踏まえた法務協議を前提とする。現時点は設計方針の明文化段階であり、実装可否・時期は未定。
03適合するカメラ視点
見下ろし角度が急なほど人物が分離し、高品質になります。
俯瞰は真上からの視野角のため人物どうしが分離しやすく（左）、アイレベルは奥行きで重なり、同一人物が複数枠にまたがって過剰カウントされやすい（右、破線＝重なった枠）。
| 視点 | 例 | 結果 |
|---|---|---|
| 俯瞰・高所 | 広場を見下ろす / スクランブル交差点 | ◎ ~120 人規模でも実数に近い計数・正確な pose |
| 中程度の見下ろし | 天井カメラ | ◎〜○ |
| アイレベル密集 | 市街の人混み | △ 奥で箱が重なり過剰カウント、密集 crop で pose が乱れる |
アイレベルの密集群衆で正確な絶対数が要る場合は、群衆／頭部カウント特化モデルの領域（将来検討）。
04プリセット
用途に応じて 3 つのプリセットから選びます。品質を取るか速度を取るかのトレードオフです。--preset フラグ 1 つで一括適用でき、--preset auto はクリップを軽くサンプリングして俯瞰/アイレベルを判定し、自動で選びます。
| プリセット | 用途 | タイル推論 | 前景 pose | 検出閾値 |
|---|---|---|---|---|
| overhead | 俯瞰・高精度・オフライン（全部入り） | ○（640 / 256） | ○（Top-8） | 0.25 |
| eye-level | アイレベル・過剰カウント抑制 | ✕ | ○（Top-3） | 0.4 |
| fast | 速度優先（カウント＋追跡のみ） | ✕ | ✕ | 0.3 |
いずれも外観 ReID（--reid-model）は共通で有効化を推奨。コマンド例・全フラグは
FlowCount/README.md（開発リポジトリ内）を参照してください。
05主要ノブ
| フラグ | 意味 | 目安 |
|---|---|---|
--preset | 上表のプリセットを一括適用（個別指定があればそちらが優先） | overhead / eye-level / fast / auto |
--resolution | 検出入力解像度（小さい人物の recall） | 576→960→1152 |
--threshold | 検出信頼度（低いほど recall↑／誤検出↑） | 0.25〜0.4 |
--tile / --tile-overlap | タイル推論（遠方の人物） | 640 / 256、0=off |
--reid-model / --reid-similarity | 外観 ReID（ID 安定） | reid.onnx / 0.6 |
--reid-stride | 埋め込みを N フレームに 1 回（速度回復） | 1〜3 |
--pose-topk | 前景 N 人に姿勢推定 | 0（off）〜8 |
環境変数（RFDETR_TRACK_REID / RFDETR_MAX_MISSED / RFDETR_EXPECTED_PERSON_COUNT ほか）でも設定可能。
06検証で得た定量所見
| 施策 | 効果 |
|---|---|
| 検出モデル + 高解像度 + タイル | 検出人数 14 →〜50（俯瞰広場、背景の群衆を捕捉） |
| 外観 ReID（埋め込み） | 累計ユニーク ID 75 → 37（断片化 ≈半減、平均人数は維持） |
--reid-stride 3 | 速度 4.85 → 7.73 FPS（ID 品質は多少低下：37 → 59） |
| 前景 pose（crop + 余白） | 前景 8 人に正確な骨格（手足の切れは余白で軽減） |
速度目安（フル・タイル + pose）は ~1 FPS のオフライン解析ツール。用途に応じてステージを削り高速化できます。
視点自動判別（--preset auto）の実データ較正：異なる設置高さの実クリップ 6 本（手持ち〜地上・中〜やや高い俯瞰 3 本・真俯瞰の交差点 1 本）で検証し、真俯瞰クリップの誤判定（確信度1.0で「eye-level」と誤検出）を発見・修正。原因はアスペクト比が単独では信頼できないこと（相関係数を主指標に変更）と、判定に本番と異なる軽量モデルを使っていたこと（本番と同じ検出モデルに統一）。修正後は 6 本全てで正しく判定。
eye-level プリセットの実クリップ計数精度：実クリップ（市場・徒歩）を --preset eye-level で検出・追跡し検証。1 フレームあたり平均 14〜17 人の検出は目視カウントと一致。一方、5 秒間の累計ユニーク ID が 57（常時 14〜17 人しかいないのに ID が頻繁に切り替わる断片化）を検出し、--reid（色ヒストグラム版）で 57→30（-47%）に削減、人数精度（avg_live_detections_per_frame）は変化なし。あわせて「--preset が ReID を有効化しない」というドキュメントとの不一致も発見・修正（--preset 使用時は自動で ReID 有効化）。
07オンプレ運用・ライセンス
推論はローカル完結（クローズドネットワーク保持）を前提とします。検出は RF-DETR（Apache-2.0 系）。外観 ReID は torchvision 由来の汎用埋め込み、または人物 ReID 専用（OSNet 等）の ONNX を同一インターフェースで差し替え可能。COCO person クラスに限定した人物検出であり、独自物体への適用には別途 fine-tune / few-shot が必要です。
使用する検出／ReID の重み・出典・ライセンスは データ・モデルについて を参照してください。
08ステータス / ロードマップ
エンジン（rf-detr）は実装・テスト済み。
| 項目 | 内容 | 状態 |
|---|---|---|
| スイート統合 | ランチャー・portal タブ | 完了 |
| 視点の自動判別 | --preset auto で俯瞰/アイレベルを推定しプリセット自動選択 | 完了 |
| 二重カウント低減 | タイル境界の統合強化（内包統合 NMS） | 完了 |
| カウント指標の正規化 | ゴースト除外の live 平均で人数レポート | 完了 |
| 実データでの定量ベンチマーク | 公開クリップ以外での精度検証 | 未着手 |
| 群衆特化モデル | アイレベル密集向けの評価 | 未着手 |
| 属性分析（検討中） | 年齢・性別など。PAR 分野の技術調査・バイアス検証・プライバシー設計（法務協議含む）が前提。実装可否・時期は未定 | 検討中 |