特定人物追跡ツール― 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の出力に次の処理を加えて、指定された人物を保持し続ける。

実行中のパラメータ調整と記録

主要な閾値は、実行中にスライダーで変更でき、次の処理フレームから反映される。変更の履歴は実行条件ファイルに記録される。

公式実装の移植

BoostTrack++とTrackTrackは、各手法の公式実装(MIT License)のアルゴリズムを移植したものである。ヘルプには、同じ入力に対して公式実装と同じ出力になることを確認したと記載されている。SAM 2.1は、Meta公式の学習済みモデルを、Ultralyticsの実装を使って推論する。

機能概要

1フレームごとの処理は、次の順序で行われる。

  1. 映像の取得:カメラはDirectShowで開き、MJPG形式で6通りの設定(1920×1080、1280×720、640×480のそれぞれで60 fpsと30 fps)を試す。実測したフレームレートを1 fps単位に丸めて比べ、最も高い設定を選ぶ。同じ値の場合は、解像度が高いほうを選ぶ。処理が追いつかないときは最新のフレームだけを処理し、使わなかったフレームの数を記録する。動画ファイルは全フレームを順に処理し、時刻には動画ファイルに記録されたタイムスタンプを使う。
  2. 人物検出:YOLO11で人物(personクラス)だけを検出する。信頼度0.10以上、面積100画素以上の検出を残す。重複除去(NMS:大きく重なる検出のうち、信頼度の低いほうを除く処理)は、IoUが0.95を超える場合だけ除く緩い設定にしている。IoUは、2つの矩形の共通部分の面積を合併部分の面積で割った値(0〜1)である。この設定により、重なり合った人物の検出も残る。
  3. 検出の振り分け:手法Aには、IoU 0.70でNMSを行った後の検出を与える。手法Bには、IoU 0.80でNMSを行った後の検出を与える。さらに、このNMSで除かれた検出のうち、信頼度が手法Bの検出閾値を超えるものも与える。
  4. ReID特徴の計算(手法A・Bを実行する場合のみ):人物の矩形を切り出し、外観を表す特徴ベクトルに変換する。幅6画素未満または高さ12画素未満の矩形については計算しない。
  5. 追跡:選んだ手法A・B・Cをそれぞれ実行する。
  6. 対象人物管理(手法A・Bのみ):指定された人物に対応するトラックを判定し、再捕捉、照合検証、すり替わりの修正を行う。
  7. 描画と保存:結果を画面に表示し、設定に応じてファイルに保存する。

追跡する対象は、映像中の人物をクリックするか、写真ファイルで指定する(写真は手法A・Bのみ)。デモ動画では、対象が自動で選ばれる。動画ファイルは最後まで処理すると自動で停止する。

「結果を保存」にチェックを入れて開始すると、プログラムと同じ場所にある results フォルダの中に、開始日時を名前にしたフォルダが作られ、次のファイルが保存される。

画面操作およびキー操作

画面構成

画面には「追跡」タブと「ヘルプ」タブがある。起動時のウィンドウは、縦768画素の画面に収まる大きさで表示される。幅は画面の幅と1366画素のうち小さいほう、高さは688画素である。追跡タブは、上部4行の操作欄、中央の映像表示部、右側の情報欄、下部のステータス表示で構成される。

1行目:入力とモデル(開始前だけ変更できる)

既定値は、CUDA対応GPUのある環境ではYOLO11m・1280・LightMBN・SAM 2.1-B+、CPUだけの環境ではYOLO11s・640・YOLO26n-ReID・SAM 2.1-Tである。

2行目:手法の選択と実行操作

3行目:表示の設定

ボタンAの検出閾値Bの検出閾値Bの新規トラック閾値Bの関連付け閾値
通常0.500.550.650.70
混雑0.400.400.450.55

人物どうしが重なり合う映像では「混雑」を選ぶ。閾値が下がるため、隠れて信頼度が低くなった検出も追跡に使われる。これらの値は、各手法の公式設定をもとに、COCOデータセットで学習したYOLO11に合わせて本ツールで調整したものであり、公式の値とは異なる。

4行目:パラメータのスライダー(実行中も変更できる)

値は、マウスの左ボタンを離した時点で送られ、次の処理フレームから反映される。

映像の見方

マウス操作と対象の指定

左クリック

映像中の人物をクリックすると、その人物が追跡の対象になる。どの表示モードでも操作でき、別の人物をクリックすれば対象を指定し直せる。

対象になるのは、クリックした位置を含み、信頼度が0.25以上の人物検出である。複数の検出が重なっている場合は、矩形の中心に近く、画面の手前にいる(足元が下側にある)人物が選ばれる。

写真で指定

「写真で指定…」で画像ファイルを選ぶと、写真の中で「面積×信頼度」が最大の人物が対象になり、手法A・Bがその人物を映像の中から探す。人物が1人だけ大きく写った写真を使うと、意図した人物が選ばれやすい。

手法Cは写真による指定に対応していない。手法A・Bと同時に実行しているときに写真で指定すると、手法Cの対象は解除される。手法Cだけを実行しているときは、写真による指定は受け付けられない。

デモ動画での自動選択

デモ動画では、10処理フレーム目以降に、次の条件をすべて満たす人物のうち、「信頼度×√面積×画像中心への近さ」が最大の人物が自動で対象になる。

自動で選ばれた後でも、クリックすれば対象を変更できる。

キー操作

使用技術

YOLO11(Ultralytics)

COCOデータセット(80クラス)で学習された物体検出モデルで、本ツールでは人物クラスだけを使う。n/s/m/l/xの5つのサイズがある。Ultralyticsは2026年1月に後継のYOLO26を公開したが、本ツールでは選択できない(出典)。

人物再同定(ReID)モデル

人物の画像を特徴ベクトルに変換し、ベクトルどうしのコサイン類似度で同一人物かどうかを判定するためのモデルである。手法A・Bで使う。

判定閾値の初期値は、YOLO26n-ReIDが0.50、YOLO26s-ReIDが0.52、LightMBNが0.66である。これらは、デモ動画「屋外の歩道」で、別人どうしの組が閾値を超える割合が1〜2%程度になるように定めた経験値である。

BoostTrack++(手法A、Stanojević & Todorović, 2024)

カルマンフィルタで各人物の次の位置を予測し、予測位置と検出を1回の最適割当(Jonker–Volgenant法)で対応付ける多物体追跡手法である。

TrackTrack(手法B、Shim ら, CVPR 2025)

互いに最も近いトラックと検出の組だけを対応付ける処理を、閾値を段階的に厳しくしながら繰り返す多物体追跡手法である。

SAM 2.1(手法C、Meta)

指定された物体のマスクを、動画の各フレームで推定する動画セグメンテーションモデルである。

後継のSAM 3は、Ultralyticsで動画追跡にも対応している(出典)。本ツールのヘルプによれば、SAM 3の重みの取得にはHugging Faceでの利用申請と承認が必要で、プログラムから自動では取得できないため、本ツールでは採用していない。

その他のライブラリ

PyTorch(YOLO11、LightMBN、SAM 2.1の推論)、ONNX Runtime(YOLO26-ReIDの推論)、OpenCV(映像の入出力)、lap(割当問題の求解)、Pillow・Tkinter(画面表示)、NumPyを使う。

実行上の注意点

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:インストーラーによるインストール

  1. Python公式サイト(https://www.python.org/downloads/)にアクセスし、「Download Python 3.x.x」ボタンからWindows用インストーラーをダウンロードする。
  2. ダウンロードしたインストーラーを実行する。
  3. 初期画面の下部に表示される「Add python.exe to PATH」にチェックを入れてから「Customize installation」を選択する。このチェックを入れ忘れると、コマンドプロンプトから python コマンドを実行できない。
  4. 「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 プログラムを解釈・実行するソフトウェア)を選択する必要がある.

  1. コマンドパレット(コマンド名で機能を呼び出す VS Code の入力欄)を開く(Ctrl+Shift+P)
  2. Python: Select Interpreter と入力する
  3. 表示される一覧から,使用する 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 などで実行する。