特定人物追跡ツール― BoostTrack++・TrackTrack・SAM 2.1 の比較表示
プログラムの動作の様子の動画:[動画]
実行ファイル:[exe]
実行ファイル(exe)は、Chrome または Firefox を用いてダウンロードすることを推奨。初回実行時に、SmartScreenの「WindowsによってPCが保護されました」の警告画面が出ます。警告画面で「詳細情報」をクリック、「実行」をクリックで続行できます。
説明資料: [PDF], [PPTX] , [動画](クリックして再生開始), クレジット:動画は「VOICEVOX:青山龍星」、「Vrew」、「Gemini」を用いて作成
本資料とコードの作成にAIを使用。参考プロンプト: prompt.md (実際にはこのプロンプトを変更したり、追加のプロンプトを与えている場合がある)
このプログラムの理念と目的
本プログラムは、固定監視カメラの映像の中で、利用者が指定した1人の人物を追跡し続けるツールである。入力には、カメラ映像、動画ファイル、付属のデモ動画を使える。人混み、他人や物に隠れること(遮蔽)、横向きや後ろ向きへの姿勢の変化といった、監視映像で追跡が途切れやすい状況を想定している。
本プログラムの目的は、仕組みの異なる3つの追跡手法を、同じ映像の同じ人物に対して同時に動かすことである。これにより、どの手法がその人物を追い続けられるかを利用者が直接比較できる。手法A(BoostTrack++)と手法B(TrackTrack)には、まったく同じ人物検出結果と人物再同定(ReID)特徴を与え、そのうえで共通の「対象人物管理」を動かす。手法C(SAM 2.1)には、対象を指定したときの矩形だけを手掛かりとして与える。入力条件をそろえているため、観察される違いは手法そのものの違いである。
想定される利用者は、監視映像での特定人物追跡の手法を評価・選定する技術者や研究者であると考えられる(推測)。実行条件、使用したモデルのハッシュ値、パラメータの変更履歴、フレームごとの追跡状態を保存できるため、結果を後から検証し、同じ条件で再実行できる。画面に表示される数値は本ツール内部の状態を集計したものであり、正解データと比べた追跡精度ではない。
特徴
同じ条件での手法比較
手法Aと手法Bには、各フレームについて同じ人物検出結果、同じReID特徴、同じ対象人物管理を与える。手法Cは、過去のフレームの観測をメモリに保持して1つの物体のマスク(物体が写っている画素の領域)を推定する動画セグメンテーションモデルであり、人物検出、ReID、トラックIDを使わない。結果は、複数の手法を並べて表示するほか、1画面に重ねたり、1つの手法だけを拡大したりして表示できる。
多物体追跡の結果から1人を保持し続ける「対象人物管理」
多物体追跡手法は映像中の全員にトラックID(人物ごとの追跡番号)を付ける。しかし、遮蔽などでIDが途切れたり、別人のIDと入れ替わったりすることがある。本ツールは、手法A・Bの出力に次の処理を加えて、指定された人物を保持し続ける。
- 対象の外観特徴を最大60件まで「ギャラリー」として蓄積する。利用者が指定したときの外観は固定の基準として扱い、置き換えない。
- 対象を見失った後は、外観の類似度、見失った位置からの距離、複数フレームでの投票をもとに、別のトラックを対象として付け替える(再捕捉)。
- 付け替えた後は照合検証を行う。対象が見えている時間の累計が2秒になるまで外観を照合し、一致しなければ付け替えを取り消す。
- 追跡中に外観の類似度が判定閾値を下回り続けた場合は、IDがすり替わったと判断し、外観がより一致する人物へ付け替える。
- 対象と同時に別の場所に写っている人物は「対象ではない人物」として記憶し、似た服装の他人へ誤って付け替えることを抑える。
- 外観の判定閾値は、実行中に自動で調整される。基準は、対象自身との類似度の分布(下位25%の点)と、他人との類似度の分布(上位1%の点)である。調整の範囲は、初期値の−0.12〜+0.18に制限される。
実行中のパラメータ調整と記録
主要な閾値は、実行中にスライダーで変更でき、次の処理フレームから反映される。変更の履歴は実行条件ファイルに記録される。
公式実装の移植
BoostTrack++とTrackTrackは、各手法の公式実装(MIT License)のアルゴリズムを移植したものである。ヘルプには、同じ入力に対して公式実装と同じ出力になることを確認したと記載されている。SAM 2.1は、Meta公式の学習済みモデルを、Ultralyticsの実装を使って推論する。
機能概要
1フレームごとの処理は、次の順序で行われる。
- 映像の取得:カメラはDirectShowで開き、MJPG形式で6通りの設定(1920×1080、1280×720、640×480のそれぞれで60 fpsと30 fps)を試す。実測したフレームレートを1 fps単位に丸めて比べ、最も高い設定を選ぶ。同じ値の場合は、解像度が高いほうを選ぶ。処理が追いつかないときは最新のフレームだけを処理し、使わなかったフレームの数を記録する。動画ファイルは全フレームを順に処理し、時刻には動画ファイルに記録されたタイムスタンプを使う。
- 人物検出:YOLO11で人物(personクラス)だけを検出する。信頼度0.10以上、面積100画素以上の検出を残す。重複除去(NMS:大きく重なる検出のうち、信頼度の低いほうを除く処理)は、IoUが0.95を超える場合だけ除く緩い設定にしている。IoUは、2つの矩形の共通部分の面積を合併部分の面積で割った値(0〜1)である。この設定により、重なり合った人物の検出も残る。
- 検出の振り分け:手法Aには、IoU 0.70でNMSを行った後の検出を与える。手法Bには、IoU 0.80でNMSを行った後の検出を与える。さらに、このNMSで除かれた検出のうち、信頼度が手法Bの検出閾値を超えるものも与える。
- ReID特徴の計算(手法A・Bを実行する場合のみ):人物の矩形を切り出し、外観を表す特徴ベクトルに変換する。幅6画素未満または高さ12画素未満の矩形については計算しない。
- 追跡:選んだ手法A・B・Cをそれぞれ実行する。
- 対象人物管理(手法A・Bのみ):指定された人物に対応するトラックを判定し、再捕捉、照合検証、すり替わりの修正を行う。
- 描画と保存:結果を画面に表示し、設定に応じてファイルに保存する。
追跡する対象は、映像中の人物をクリックするか、写真ファイルで指定する(写真は手法A・Bのみ)。デモ動画では、対象が自動で選ばれる。動画ファイルは最後まで処理すると自動で停止する。
「結果を保存」にチェックを入れて開始すると、プログラムと同じ場所にある results フォルダの中に、開始日時を名前にしたフォルダが作られ、次のファイルが保存される。
- compare.mp4:実行した全手法の映像を、元の大きさのまま横1列に並べた比較動画である。画面の表示モードには影響されない。処理中に1フレームずつ書き足す。カメラ入力の場合は、再生時間が実際の経過時間と一致するように、最大30 fpsで書き込む。
- target_log.csv:処理フレームごと・手法ごとの記録である。対象の状態、トラックID、矩形、外観の類似度、判定閾値、照合検証中かどうか、物体存在ロジット、マスクの面積、その時点のパラメータ値などを記録する。処理中に書き足す。
- conditions.json:使用したモデル、各ファイルのSHA-256、パラメータ、ライブラリのバージョンを記録する。開始時に書き出し、停止時に、実行中のパラメータ変更履歴を加えて書き直す。
- summary.json:指標の最終値とその定義を記録する。停止時に出力する。
画面操作およびキー操作
画面構成
画面には「追跡」タブと「ヘルプ」タブがある。起動時のウィンドウは、縦768画素の画面に収まる大きさで表示される。幅は画面の幅と1366画素のうち小さいほう、高さは688画素である。追跡タブは、上部4行の操作欄、中央の映像表示部、右側の情報欄、下部のステータス表示で構成される。
1行目:入力とモデル(開始前だけ変更できる)
- 入力:次の3つから選ぶ。
- 「カメラ」:カメラ番号0〜9を指定する。
- 「動画ファイル」:「参照…」を押し、mp4、avi、mov、mkv、wmv、m4vのいずれかを選ぶ。
- 「デモ動画」:屋外の歩道、店舗の通路、屋内の出入り、廊下の歩行の4本から選ぶ。
- 人物検出:YOLO11n/s/m/l/xから選ぶ。後ろのモデルほど検出性能が高いが、処理が重くなる。
- 解像度:人物検出の入力解像度を640、960、1280から選ぶ。大きくするほど小さく写った人物を検出しやすくなるが、処理が重くなる。
- ReID:手法A・Bが使う人物再同定モデルを、YOLO26n-ReID、YOLO26s-ReID、LightMBNから選ぶ。
- SAM:手法Cが使うモデルを、SAM 2.1-T/S/B+から選ぶ。後ろのモデルほど大きく、処理が重くなる。
既定値は、CUDA対応GPUのある環境ではYOLO11m・1280・LightMBN・SAM 2.1-B+、CPUだけの環境ではYOLO11s・640・YOLO26n-ReID・SAM 2.1-Tである。
2行目:手法の選択と実行操作
- 実行する手法:「A: BoostTrack++」「B: TrackTrack」「C: SAM 2.1(メモリ型)」から1つ以上を選ぶ。手法Cは処理が重いため、CPUだけの環境では既定でチェックが外れている。
- 結果を保存:チェックを入れると、
resultsフォルダの中に開始日時を名前にしたフォルダを作り、比較動画、記録、実行条件、集計を保存する。 - 一時停止/再開 (Space):処理を一時停止し、もう一度押すと再開する。
- 1 フレーム進む (→):1フレームだけ処理して一時停止する。対象が入れ替わる瞬間などを細かく確認するときに使う。
- 写真で指定…:写真ファイルに写った人物を追跡の対象にする(手法A・Bのみ)。
3行目:表示の設定
- 表示:表示モードを選ぶ。
- 「並列表示」:実行中の全手法を、表示倍率が最大になる行数・列数で並べる。
- 「重ね合わせ」:全手法を1画面に重ねる。枠線の種類で手法を区別する(A=実線、B=破線、C=点線)。複数の手法を実行しているときだけ選べる。
- 「A のみ(拡大)」など:その手法だけを大きく表示する。
- 全トラック表示:手法A・Bでは、対象以外のトラックのうち確定済みのもの(一定回数以上、検出と対応付いたもの)も、細い枠とID番号で表示する。手法Cだけを表示しているときは、クリックで対象に指定できる人物検出(信頼度0.25以上)を灰色の枠で示す。
- 画面を保存:現在の表示画面を、
resultsフォルダの直下に画面_年月日_時分秒.pngという名前のPNG画像で保存する。 - 全画面表示/ノートPC表示 (F11):全画面表示と、縦768画素向けの表示を切り替える。
- 通常/混雑:手法A・Bの閾値をまとめて設定する。設定される値は次の表のとおりである。手法AのIoU閾値と手法Cには作用しない。
| ボタン | Aの検出閾値 | Bの検出閾値 | Bの新規トラック閾値 | Bの関連付け閾値 |
|---|---|---|---|---|
| 通常 | 0.50 | 0.55 | 0.65 | 0.70 |
| 混雑 | 0.40 | 0.40 | 0.45 | 0.55 |
人物どうしが重なり合う映像では「混雑」を選ぶ。閾値が下がるため、隠れて信頼度が低くなった検出も追跡に使われる。これらの値は、各手法の公式設定をもとに、COCOデータセットで学習したYOLO11に合わせて本ツールで調整したものであり、公式の値とは異なる。
4行目:パラメータのスライダー(実行中も変更できる)
値は、マウスの左ボタンを離した時点で送られ、次の処理フレームから反映される。
- A:検出閾値(0.05〜0.95):信頼度を補正した後の値がこの閾値未満の検出は、追跡に使わない。手法Aは、既存トラックの近くにある検出の信頼度を引き上げる補正を行う。値を下げると、隠れかけた人物も追跡に使われるが、誤検出から新しいトラックが作られやすくなる。
- A:IoU 閾値(0.05〜0.90):予測位置と検出のIoU(2つの矩形の重なりの割合)がこの値以上のときに、両者を対応付ける。ReIDの類似度が0.75以上の場合は、この値の半分以上の重なりでも対応付ける。値を上げると誤った対応付けは減るが、速く動く人物の追跡が途切れやすくなる。
- B:検出閾値(0.05〜0.95):信頼度がこの値を超える検出を、高信頼度の検出として扱う。この値以下の検出は、コストに0.20を加えたうえで使う。
- B:関連付け閾値(0.30〜0.95):コストがこの値未満で、かつ互いに最も近いトラックと検出の組を対応付ける。コストは、位置の重なり、外観、信頼度、動きの向きから計算する0〜1の不一致度で、小さいほど一致していることを表す。対応付けは、閾値を0.05ずつ下げながら繰り返し行う。値を上げるほど、対応付けの条件は緩くなる。
- C:マスク閾値(−8.0〜8.0):各画素のロジット(対象に属する度合いを表すスコア。0が確率50%に相当する)がこの値を超える画素を、対象の領域とする。値を上げるとマスクは小さくなる。変わるのは出力されるマスクだけで、モデルのメモリは影響を受けない。一時停止中に変更すると、表示中のフレームにもすぐ反映される。ただし、記録済みの集計は変わらない。
映像の見方
- 対象の人物は太い枠で示される。枠の色は、手法Aがマゼンタ、手法Bがシアン、手法Cが黄である。
- 手法A・Bの枠に付く番号は、各トラッカー内部のトラックIDである。
- 「対象候補(照合検証中)」は、見失った後に別のトラックへ付け替え、照合を続けている状態を表す。対象が見えている時間の累計が2秒になるまで照合し、外観が一致しなければ付け替えを取り消す。
- 手法Cでは、半透明の黄色の領域と輪郭線が、SAM 2.1が出力したマスクを表す。
- 橙色の破線は、遮蔽中の予測位置を表す。1.5秒を超えると表示されなくなる。
- 薄い赤の細い破線は、最後に対象を確認した位置を表す。
- 対象の足元の軌跡は、直近3秒分が表示される。
- 画面下端の帯は、状態の時系列である。1列が1処理フレームに対応し、右端が最新である。色の意味は次のとおりである。
- 緑:追跡中(検出と対応付いている)。手法Cではマスクがある状態。
- 橙:遮蔽中(検出と対応付かず、予測位置だけがある)。
- 赤:探索中(対象のトラックがない)。手法Cではマスクがない状態。
- 灰:対象が未設定。
- 右側の情報欄には、指定したときの対象の外観(サムネイル)と、手法ごとに次の値が表示される。
- 手法A・B:状態、外観の類似度と判定閾値、時間割合(追跡中・予測のみ・探索中)、トラックIDの変更回数、再捕捉の回数、照合検証で取り消した回数、すり替わりを修正した回数、最長の見失い時間、処理時間。外観の類似度は、ギャラリーの特徴とのコサイン類似度のうち上位3件の平均で、−1〜1の値をとる。
- 手法C:物体存在ロジット、マスクの出現率、マスクの消失・再出現の回数、最長の非出現時間、処理時間。物体存在ロジットは、対象が写っているかを表す値で、正なら出現、0以下なら非出現と判定される。確率ではない。
- 手法間の対象矩形のIoU(位置の一致度)と、処理速度。
マウス操作と対象の指定
左クリック
映像中の人物をクリックすると、その人物が追跡の対象になる。どの表示モードでも操作でき、別の人物をクリックすれば対象を指定し直せる。
対象になるのは、クリックした位置を含み、信頼度が0.25以上の人物検出である。複数の検出が重なっている場合は、矩形の中心に近く、画面の手前にいる(足元が下側にある)人物が選ばれる。
- 手法A・B:IoU 0.5以上で重なるトラックがあれば、すぐにそのトラックに結び付ける。指定直後は、対象が見えている時間で1秒、処理フレームで5フレームに達するまで、他人に覆われている面積が30%未満であれば、外観の類似度に関係なく外観をギャラリーに追加する。
- 手法C:クリックした人物の検出矩形を手掛かりとして与え、そのフレームから追跡を始める。
写真で指定
「写真で指定…」で画像ファイルを選ぶと、写真の中で「面積×信頼度」が最大の人物が対象になり、手法A・Bがその人物を映像の中から探す。人物が1人だけ大きく写った写真を使うと、意図した人物が選ばれやすい。
手法Cは写真による指定に対応していない。手法A・Bと同時に実行しているときに写真で指定すると、手法Cの対象は解除される。手法Cだけを実行しているときは、写真による指定は受け付けられない。
デモ動画での自動選択
デモ動画では、10処理フレーム目以降に、次の条件をすべて満たす人物のうち、「信頼度×√面積×画像中心への近さ」が最大の人物が自動で対象になる。
- 信頼度が0.6以上である。
- 他の検出と重なっていない。
- 画像の端に接していない。
自動で選ばれた後でも、クリックすれば対象を変更できる。
キー操作
- Space:実行中に、一時停止と再開を切り替える。
- →:1フレームだけ処理して一時停止する。再生中に押しても一時停止に切り替わる。カメラ入力では、押した時点で最新のフレームを処理するため、それまでに取り込まれたフレームは処理されない。
- F1:ヘルプタブを開く。ヘルプには、手順、手法の詳細、全パラメータ、今回の実行条件が表示される。
- Esc:ヘルプタブを表示しているときは、追跡タブに戻る。全画面表示のときは、縦768画素向けの表示に戻す。
- F11:全画面表示と、縦768画素向けの表示を切り替える。
使用技術
YOLO11(Ultralytics)
COCOデータセット(80クラス)で学習された物体検出モデルで、本ツールでは人物クラスだけを使う。n/s/m/l/xの5つのサイズがある。Ultralyticsは2026年1月に後継のYOLO26を公開したが、本ツールでは選択できない(出典)。
人物再同定(ReID)モデル
人物の画像を特徴ベクトルに変換し、ベクトルどうしのコサイン類似度で同一人物かどうかを判定するためのモデルである。手法A・Bで使う。
- YOLO26n-ReID/YOLO26s-ReID:MSMT17で学習されたモデルである。入力は448×448画素で、ONNX Runtimeで推論する。
- LightMBN:Market-1501で学習されたモデルである。OSNetを骨格とし、入力は384×128画素、特徴は3584次元で、PyTorchで推論する。
判定閾値の初期値は、YOLO26n-ReIDが0.50、YOLO26s-ReIDが0.52、LightMBNが0.66である。これらは、デモ動画「屋外の歩道」で、別人どうしの組が閾値を超える割合が1〜2%程度になるように定めた経験値である。
BoostTrack++(手法A、Stanojević & Todorović, 2024)
カルマンフィルタで各人物の次の位置を予測し、予測位置と検出を1回の最適割当(Jonker–Volgenant法)で対応付ける多物体追跡手法である。
- 既存トラックの近くにある低信頼度の検出は、信頼度を引き上げてから使う。これにより、隠れかけた人物も追跡に使われる。
- 対応付けには、IoU(2つの矩形の重なりの割合)、マハラノビス距離(予測の不確かさを考慮した距離)、矩形の形の類似度、ReIDの類似度を組み合わせて使う。
- 検出と対応付かない状態がmax(30, 2×fps)フレームを超えたトラックは削除される。
TrackTrack(手法B、Shim ら, CVPR 2025)
互いに最も近いトラックと検出の組だけを対応付ける処理を、閾値を段階的に厳しくしながら繰り返す多物体追跡手法である。
- 低信頼度の検出や、重複除去(NMS)で除かれた検出も、不一致度に加算をしたうえで利用する。
- 既存トラックと大きく重なる(IoU 0.55超)検出からは新しいトラックを作らず、同じ人物にトラックが重複して作られることを抑える。
- カルマンフィルタの観測ノイズを、検出の信頼度に応じて調整する。
- 検出と対応付かない状態が2×fpsフレームを超えたトラックは削除される。
SAM 2.1(手法C、Meta)
指定された物体のマスクを、動画の各フレームで推定する動画セグメンテーションモデルである。
- メモリとして、対象を指定したフレームと直近6フレームのマスクの情報、および直近の最大15フレームの物体ポインタ(物体を要約した特徴)を保持する。
- 各フレームについて、マスクと物体存在ロジット(対象が写っているかを表す値で、正なら出現と判定)を出力する。
- 入力は1024×1024画素で、画像エンコーダにはHieraを使う。
- Meta公式の学習済みモデルをHugging Faceから取得し、SHA-256で照合したうえで、UltralyticsのSAM 2実装で推論する。
後継のSAM 3は、Ultralyticsで動画追跡にも対応している(出典)。本ツールのヘルプによれば、SAM 3の重みの取得にはHugging Faceでの利用申請と承認が必要で、プログラムから自動では取得できないため、本ツールでは採用していない。
その他のライブラリ
PyTorch(YOLO11、LightMBN、SAM 2.1の推論)、ONNX Runtime(YOLO26-ReIDの推論)、OpenCV(映像の入出力)、lap(割当問題の求解)、Pillow・Tkinter(画面表示)、NumPyを使う。
実行上の注意点
- GPUで推論するには、CUDA対応版のPyTorchが必要である。
onnxruntimeとonnxruntime-gpuは同時にインストールすると競合するため、どちらか一方だけをインストールする。 - 手法Cは、Ultralyticsのバージョンに依存する。手法CはUltralyticsの内部構造を直接使っている。Ultralyticsを更新した後に手法Cがエラーになる場合は、以前に正常に動作したときのconditions.jsonに記録されているバージョンを入れ直す。
- 初回の起動にはネットワーク接続が必要である。学習済みモデルはプログラムと同じ場所の
modelsフォルダに、デモ動画はdemoフォルダに、自動でダウンロードされる。2回目以降はダウンロード済みのファイルを使う。ネットワークに接続できない環境では、別の環境でダウンロードしたこれらのフォルダを、プログラムと同じ場所にコピーする。「ハッシュ値が一致しません」と表示された場合は、該当するファイルを削除してから再実行する。 - Windowsで使う。
- パスは英数字だけにする。OpenCVは、日本語などを含むパスの動画を読み書きできない。本ツールは短いパス名への変換を試みるが、それでもエラーになる場合は、動画ファイルを英数字だけのパスに移動する。比較動画はプログラムと同じ場所の
resultsフォルダに書き込まれるため、プログラムを置くフォルダも英数字だけのパスにする。 - タイムスタンプが単調に増加しない動画は処理できない。「動画のタイムスタンプが単調増加していません」と表示された場合は、ffmpegなどで動画を再エンコードしてから使う。
- 手法Cは処理が重い。SAM 2.1は毎フレーム1024×1024画素で画像エンコーダを動かすため、手法A・Bより処理時間が大幅に長い。処理を軽くするには、手法Cのチェックを外す、小さいモデル(YOLO11n/s、SAM 2.1-T)を選ぶ、検出の解像度を640にする、といった方法がある。カメラ入力で処理が追いつかないと、処理されないフレームが増え、追跡の手掛かりが減る。
- 表示・保存される数値は、追跡の精度ではない。これらの数値は、本ツール内部の状態を集計したものである。例えば手法Cでは、マスクが別の人物に移っても「マスクあり」として数えられる。追跡が正しいかどうかは、映像や比較動画を見て確認する。
- 人物再同定(手法A・B)の結果は、服装・照明・解像度に強く左右される。似た服装の人物、小さく写った人物、写り始めで体の一部しか見えていない人物では、誤った付け替えや見逃しが起こりうる。判定閾値の初期値はデモ動画で定めた経験値であり、実行中に自動で調整されるが、最適な値は撮影現場によって異なる。誤った付け替えが起きた場合は、正しい人物をクリックし直すと、対象を指定し直せる。
- 時間割合の集計には誤差が入る場合がある。時刻は、カメラの露光時刻ではなく、PCがフレームを取得した時刻である。時間割合は、直前の処理フレームからの経過時間を、そのフレームの状態に割り当てて集計する。そのため、処理が遅いときや、カメラ入力で一時停止したときは、観測していない時間も次の処理フレームの状態に含まれる。正確な時間割合が必要な場合は、動画ファイルで処理するか、カメラ入力では一時停止しない。
- 終了するときは「停止」を押す。比較動画と記録ファイルは処理中に書き足され、停止時に閉じられる。MP4形式の動画は閉じる処理で再生に必要な情報が書き込まれるため、プロセスを強制終了すると、比較動画が再生できなくなる場合がある。動画ファイルを最後まで処理した場合は、自動で停止・保存される。
- ライセンスを確認する。UltralyticsのライブラリとYOLO11の重みはAGPL-3.0である。ReIDモデルの重みの配布元(Ultralytics、BoxMOT)もAGPL-3.0である。PyInstallerで作成したexeを配布する場合や、ネットワーク経由のサービスとして提供する場合は、AGPL-3.0に従ってソースコードを利用者に提供するか、Ultralyticsの商用ライセンスを取得する。Intelのデモ動画はCC BY 4.0であるため、利用するときは出典として「Intel IoT DevKit sample-videos」を表示する。
- 人物の追跡では、法令に配慮する(一般的な注意)。特定の人物を映像で追跡し、記録を保存することは、個人情報の取り扱いにあたる。運用前に、個人情報保護法などの関係法令や社内規程(撮影や利用目的の掲示、同意の取得など)に沿っていることを確認する。
- exe化した場合の保存先:PyInstallerでexe化した場合、
models、demo、resultsの各フォルダは、exeと同じ場所に作られる。
exeファイルの作成手順
cd /d c:\users\user\proj\person_tracking
python -m venv venv
venv\Scripts\activate.bat
python -m pip install --upgrade pip
pip install -U --no-user pyinstaller pytest ultralytics onnxruntime lap pillow opencv-python numpy torch torchvision
pyinstaller --onefile --clean --noconfirm --collect-all ultralytics --collect-all onnxruntime --collect-all lap --collect-all PIL --collect-all opencv_python --collect-all numpy --collect-all torch --collect-all torchvision person_tracking.py
実行ファイル:[exe]
実行ファイル(exe)は、Chrome または Firefox を用いてダウンロードすることを推奨。初回実行時に、SmartScreenの「WindowsによってPCが保護されました」の警告画面が出ます。警告画面で「詳細情報」をクリック、「実行」をクリックで続行できます。
ソースコード実行のための前準備
Python 3.12 のインストール
Pythonのインストールを行い、Pythonのプログラムを実行する環境を整える。扱う環境は、Windows搭載パソコンである。金子研究室では、Python 3.12.10を推奨する。
[Windows での Python 3.12 のインストール手順を見るには、ここをクリック]
Windows での Python 3.12 のインストール
以下のいずれかの方法でPython 3.12をインストールする。Pythonがインストール済みの場合、この手順は不要である。
方法 1:winget によるインストール
【インストールコマンドの実行方法】
管理者権限でコマンドプロンプトを起動する(手順:Windowsキーまたはスタートメニュー → cmd と入力 → 右クリック → 「管理者として実行」)。そして、コマンド全体をコマンドプロンプトにコピー&ペーストする。
--scope machine を指定することで、システム全体(全ユーザー向け)にインストールされる。このオプションの実行には管理者権限が必要である。インストール完了後、コマンドプロンプトを再起動するとPATHが反映される。
REM Python 3.12 をシステム領域にインストール
winget install --id Python.Python.3.12 -e --scope machine --silent --accept-source-agreements --accept-package-agreements --override "/quiet InstallAllUsers=1 PrependPath=1 Include_test=0 Include_pip=1 Include_launcher=1 InstallLauncherAllUsers=1 TargetDir=\"C:\Program Files\Python312\""
if not "%ERRORLEVEL%"=="0" ( color 0c & echo Python 3.12 のインストールに失敗しました & ping 127.0.0.1 -n 6 >nul & color )
REM Python と Scripts を PATH 先頭に追加
powershell -NoProfile -Command "$p='C:\Program Files\Python312'; $s=\"$p\Scripts\"; if(Test-Path $p){$k=[Microsoft.Win32.Registry]::LocalMachine.OpenSubKey('SYSTEM\CurrentControlSet\Control\Session Manager\Environment',$true); $c=$k.GetValue('Path','',[Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames); $t=$k.GetValueKind('Path'); $new=$c; if((';'+$new+';') -notlike \"*;$p;*\"){$new=$p+';'+$new}; if((';'+$new+';') -notlike \"*;$s;*\"){$new=$s+';'+$new}; if($new -ne $c){$k.SetValue('Path',$new,$t)}; $k.Close()}"
REM 現在のセッションにも反映(システムPATHを再取得して連結)
for /f "usebackq tokens=2,*" %A in (`reg query "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v Path`) do set "PATH=%B"
REM pip / wheel の更新
python -m pip install --no-user -U pip wheel
if not "%ERRORLEVEL%"=="0" ( color 0c & echo pip / wheel の更新に失敗しました & ping 127.0.0.1 -n 6 >nul & color )
方法 2:インストーラーによるインストール
- Python公式サイト(https://www.python.org/downloads/)にアクセスし、「Download Python 3.x.x」ボタンからWindows用インストーラーをダウンロードする。
- ダウンロードしたインストーラーを実行する。
- 初期画面の下部に表示される「Add python.exe to PATH」にチェックを入れてから「Customize installation」を選択する。このチェックを入れ忘れると、コマンドプロンプトから
pythonコマンドを実行できない。 - 「Install Python 3.xx for all users」にチェックを入れ、「Install」をクリックする。
インストールの確認
コマンドプロンプトで以下を実行する。
python --version
バージョン番号(例:Python 3.12.x)が表示されればインストール成功である。「'python' は、内部コマンドまたは外部コマンドとして認識されていません。」と表示される場合は、インストールが正常に完了していない。
Python の開発環境 Visual Studio Code のインストールと Python 用の設定
Python の開発環境Visual Studio Code(プログラムを編集するソフトウェア。以下、VS Code)を整える。
[Windows での Visual Studio Code のインストールと Python 用の設定手順を見るには、ここをクリック]
Windows での Visual Studio Code のインストールと Python 用の設定手順
1. VS Code と拡張機能のインストール
以下のコマンドにより,既存の VS Code を削除し,全ユーザー共有の設定で再インストールしたうえで,拡張機能(VS Code に機能を追加するソフトウェア)をまとめて導入する.
【インストールコマンドの実行方法】
管理者権限でコマンドプロンプトを起動する(手順:Windows キーまたはスタートメニュー → cmd と入力 → 右クリック → 「管理者として実行」)。そして,コマンド全体をコマンドプロンプトにコピー&ペーストする。
インストールコマンド
REM ============================================================
REM Microsoft Visual Studio Code
REM ============================================================
REM Build Tools + Desktop development with C++(VCTools)+ 追加コンポーネント(一括)
REM 未インストール時: winget で新規インストール
REM インストール済み時: setup.exe modify でコンポーネント追加(バージョンは変更しない)
winget list --id Microsoft.VisualStudio.BuildTools 2>nul | findstr /i "BuildTools" >nul 2>&1
if %ERRORLEVEL% EQU 0 (
for /f "usebackq delims=" %P in (`"C:\Program Files (x86)\Microsoft Visual Studio\Installer\vswhere.exe" -products Microsoft.VisualStudio.Product.BuildTools -property installationPath`) do start /wait "" "C:\Program Files (x86)\Microsoft Visual Studio\Installer\setup.exe" modify --installPath "%P" --add Microsoft.VisualStudio.Workload.VCTools --add Microsoft.VisualStudio.Workload.MSBuildTools --add Microsoft.VisualStudio.Component.VC.CMake.Project --add Microsoft.VisualStudio.Component.VC.Llvm.Clang --add Microsoft.VisualStudio.Component.VC.Llvm.ClangToolset --add Microsoft.VisualStudio.Component.Windows11SDK.26100 --add Microsoft.VisualStudio.Component.VC.v143.x86.x64 --includeRecommended --quiet --norestart --nocache
if not "%ERRORLEVEL%"=="0" ( color 0c & echo Build Tools のコンポーネント追加に失敗しました & ping 127.0.0.1 -n 6 >nul & color )
) else (
winget install --scope machine --id Microsoft.VisualStudio.BuildTools -e --silent --disable-interactivity --force --accept-source-agreements --accept-package-agreements --override "--quiet --wait --norestart --nocache --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended --add Microsoft.VisualStudio.Workload.MSBuildTools --add Microsoft.VisualStudio.Component.VC.CMake.Project --add Microsoft.VisualStudio.Component.VC.Llvm.Clang --add Microsoft.VisualStudio.Component.VC.Llvm.ClangToolset --add Microsoft.VisualStudio.Component.Windows11SDK.26100 --add Microsoft.VisualStudio.Component.VC.v143.x86.x64"
if not "%ERRORLEVEL%"=="0" ( color 0c & echo Build Tools のインストールに失敗しました & ping 127.0.0.1 -n 6 >nul & color )
)
REM 全ユーザー共有の拡張機能フォルダ
if not exist "C:\ProgramData\vscode-extensions" mkdir "C:\ProgramData\vscode-extensions"
icacls "C:\ProgramData\vscode-extensions" /grant "Everyone:(OI)(CI)M" /T
REM スタートメニューのショートカットを --extensions-dir 付きで再作成
if exist "C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio Code" rmdir /s /q "C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio Code"
if exist "C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio Code.lnk" del "C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio Code.lnk"
powershell -NoProfile -Command "$s=New-Object -ComObject WScript.Shell; $lnk=$s.CreateShortcut('C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio Code.lnk'); $lnk.TargetPath='C:\Program Files\Microsoft VS Code\Code.exe'; $lnk.Arguments='--extensions-dir \"C:\ProgramData\vscode-extensions\"'; $lnk.Save()"
REM ショートカットの検証
powershell -NoProfile -Command "$s=New-Object -ComObject WScript.Shell; $lnk=$s.CreateShortcut('C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio Code.lnk'); Write-Host 'TargetPath:' $lnk.TargetPath; Write-Host 'Arguments:' $lnk.Arguments"
REM ファイル / フォルダ右クリックの「Code で開く」を登録
reg add "HKLM\SOFTWARE\Classes\*\shell\VSCode\command" /ve /d "\"C:\Program Files\Microsoft VS Code\Code.exe\" --extensions-dir \"C:\ProgramData\vscode-extensions\" \"%1\"" /f
reg add "HKLM\SOFTWARE\Classes\Directory\shell\VSCode\command" /ve /d "\"C:\Program Files\Microsoft VS Code\Code.exe\" --extensions-dir \"C:\ProgramData\vscode-extensions\" \"%1\"" /f
reg add "HKLM\SOFTWARE\Classes\Directory\Background\shell\VSCode\command" /ve /d "\"C:\Program Files\Microsoft VS Code\Code.exe\" --extensions-dir \"C:\ProgramData\vscode-extensions\" \"%V\"" /f
REM --extensions-dir 付きで起動する code.cmd ラッパを作成
REM (%* を echo で書くと対話的 cmd で失われるため、PowerShell で [char]37+'*' を書き出す)
powershell -NoProfile -Command "$pct=[char]37; $q=[char]34; $c='@echo off'+[char]13+[char]10+$q+'C:\Program Files\Microsoft VS Code\bin\code.cmd'+$q+' --extensions-dir '+$q+'C:\ProgramData\vscode-extensions'+$q+' '+$pct+'*'+[char]13+[char]10; [IO.File]::WriteAllText('C:\ProgramData\vscode-extensions\vscode.cmd',$c,[Text.Encoding]::ASCII)"
REM 拡張機能のインストール
set "CODE=C:\Program Files\Microsoft VS Code\bin\code.cmd"
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --uninstall-extension GitHub.copilot
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --uninstall-extension GitHub.copilot-chat
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --install-extension ms-python.python
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --install-extension ms-python.vscode-pylance
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --install-extension ms-python.debugpy
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --install-extension MS-CEINTL.vscode-language-pack-ja
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --install-extension saoudrizwan.claude-dev
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --install-extension rust-lang.rust-analyzer
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --install-extension tamasfe.even-better-toml
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --install-extension anthropic.claude-code
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --install-extension almenon.arepl
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --list-extensions --show-versions
REM settings.json を作成(自動更新オフ、Python、Claude Code 設定)
if not exist "%APPDATA%\Code\User" mkdir "%APPDATA%\Code\User"
python -c "import json,os;data={'update.mode':'none','update.enableWindowsBackgroundUpdates':False,'extensions.autoUpdate':False,'python.defaultInterpreterPath':r'C:\Program Files\Python312\python.exe','claudeCode.environmentVariables':[{'name':'ANTHROPIC_API_KEY','value':'not-needed'},{'name':'ANTHROPIC_AUTH_TOKEN','value':'ollama'},{'name':'ANTHROPIC_BASE_URL','value':'http://localhost:11434'},{'name':'ANTHROPIC_MODEL','value':'glm-4.7-flash'},{'name':'CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC','value':'1'}]};p=os.path.join(os.environ['APPDATA'],'Code','User','settings.json');open(p,'w',encoding='utf-8').write(json.dumps(data,indent=4));print('Done:',p)"
REM 自動更新の抑止ポリシー(settings.json に加えて、レジストリ側でも明示的にオフ)
reg add "HKLM\SOFTWARE\Policies\Microsoft\VSCode" /v "UpdateMode" /t REG_SZ /d "none" /f
echo === セットアップ完了 ===
2. Python インタプリタの選択
同一マシンに複数の Python がインストールされている場合,VS Code で使用する Python 本体(インタプリタ:Python プログラムを解釈・実行するソフトウェア)を選択する必要がある.
- コマンドパレット(コマンド名で機能を呼び出す VS Code の入力欄)を開く(
Ctrl+Shift+P) Python: Select Interpreterと入力する
- 表示される一覧から,使用する Python(例:
C:\Program Files\Python312\python.exe)を選択する.
必要なライブラリをシステム領域にインストール
管理者権限でコマンドプロンプトを起動する
(手順:Windowsキーまたはスタートメニュー → cmd と入力 → 右クリック → 「管理者として実行」)。
以下を実行する。
set "CUDA_TAG=cu128"REM MediaPipe 標準機能のインストール
pip uninstall -y opencv-python-headless opencv-contrib-python-headless opencv-python
pip install --no-user -U numpy torch torchvision --index-url https://download.pytorch.org/whl/%CUDA_TAG%
pip uninstall -y opencv-python-headless opencv-contrib-python-headless opencv-python
pip install -U --no-user ultralytics onnxruntime-gpu lap pillow opencv-contrib-python numpy torch
ソースコード
保存し、Visual Studio Code などで実行する。