RT-DETRv2 + BoT-SORT による人物追跡・再識別（ソースコードと実行結果）

【概要】RT-DETRv2で人物を検出し、BoT-SORTで外観特徴（ReID）と動きを組み合わせて追跡・再識別するプログラムである。

【目次】

• 第１章　プログラム利用ガイド
• 第２章　Python開発環境，ライブラリ類
• 第３章　Python 3.12 のインストール
• 第４章　Python の開発環境 Visual Studio Code のインストールと Python 用の設定
• 第５章　RT-DETRv2 + BoT-SORT 人物追跡プログラム

第１章　プログラム利用ガイド

1. このプログラムの利用シーン

動画映像内の複数人物を自動検出し、各人物の外観特徴に基づいて継続的に追跡・再識別するシステムである。監視カメラシステムでの人物追跡、小売店舗での顧客行動分析、空港や駅での人流監視、スポーツ映像での選手追跡などの用途に適用できる。人物の外観情報を特徴ベクトルとして数値化し、動き情報と組み合わせてフレーム間での同一人物判定を実行する。

2. 主な機能

• リアルタイム人物検出: RT-DETRv2により動画フレーム内の人物を自動検出し、信頼度0.5以上の人物領域を特定する。
• 動き予測と外観特徴照合: BoT-SORTがカルマンフィルタによる動き予測と、ReIDモデルによる外観特徴照合を組み合わせ、フレーム間での人物ID割り当てを実行する。
• カメラ動き補償: カメラが動く場合でも、ECC（Enhanced Correlation Coefficient）法による動き補償で追跡精度を維持する。
• 視覚的表示: 各人物に固有の色でバウンディングボックスを描画し、Person ID、検出信頼度を画面表示する。
• 結果ログ保存: フレームごとの検出人数、Person ID、検出信頼度をテキストファイルに保存する。

3. 基本的な使い方

プログラム起動後、入力選択画面で以下のいずれかを選択する。

• 0を入力: 動画ファイルを選択し、ファイルダイアログから処理対象の動画を指定する。
• 1を入力: ウェブカメラを使用し、リアルタイム映像処理を開始する。
• 2を入力: サンプル動画を自動ダウンロードして処理を実行する。

処理開始後は自動的に人物検出と追跡が実行され、画面に検出結果が表示される。各人物には固有のPerson IDが割り当てられ、バウンディングボックスの色で区別される。コンソールには詳細な処理結果がフレーム単位で出力される。ESCキーまたはqキーで終了する。

4. 便利な機能

• ReIDモデルの自動ダウンロード: 初回実行時にReIDモデルの重みファイルが自動的にダウンロードされる。
• 結果ログ出力: 処理完了時に、処理フレーム数や使用デバイスを含む結果がresult.txtに保存される。
• 閾値設定: 検出信頼度の閾値がプログラム上部で定義されており、用途に応じた調整が可能である。

第２章　Python開発環境，ライブラリ類

ここでは、最低限の事前準備について説明する。機械学習や深層学習を行う場合は、NVIDIA CUDA、Visual Studio、Cursorなどを追加でインストールすると便利である。これらについては別ページ https://www.kkaneko.jp/cc/dev/aiassist.htmlで詳しく解説しているので、必要に応じて参照してください。

第３章　Python 3.12 のインストール

Pythonのインストールを行い、Pythonのプログラムを実行する環境を整える。扱う環境は、Windows搭載パソコンである。金子研究室では、Python 3.12.10を推奨する。

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\""

REM Python と Scripts を PATH 先頭に追加
powershell -NoProfile -Command "$p='C:\Program Files\Python312'; $s=\"$p\Scripts\"; $c=[Environment]::GetEnvironmentVariable('Path','Machine'); if((Test-Path $p) -and (';'+$c+';' -notlike \"*;$p;*\") -and (';'+$c+';' -notlike \"*;$s;*\")){[Environment]::SetEnvironmentVariable('Path',\"$p;$s;$c\",'Machine')}"

python --version

第４章　Python の開発環境 Visual Studio Code のインストールと Python 用の設定

Python の開発環境Visual Studio Code（プログラムを編集するソフトウェア。以下、VS Code）を整える。

REM ============================================================
REM Microsoft Visual Studio Code
REM ============================================================
winget uninstall -e --id Microsoft.VisualStudioCode --silent --disable-interactivity --accept-source-agreements
rmdir /s /q C:\ProgramData\vscode-extensions 2>nul
rmdir /s /q "%APPDATA%\Code" 2>nul
rmdir /s /q "%USERPROFILE%\.vscode" 2>nul
rmdir /s /q "%LOCALAPPDATA%\Microsoft\vscode-update" 2>nul

REM VS Code をシステム領域に新規インストール
winget install --scope machine --id Microsoft.VisualStudioCode -e --silent --accept-source-agreements --accept-package-agreements

REM 全ユーザー共有の拡張機能フォルダ
mkdir C:\ProgramData\vscode-extensions 2>nul
icacls "C:\ProgramData\vscode-extensions" /grant "Everyone:(OI)(CI)M" /T

REM スタートメニューのショートカットを --extensions-dir 付きで再作成
rmdir /s /q "C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio Code" 2>nul
del "C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio Code.lnk" 2>nul
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
echo === セットアップ完了 ===

必要なライブラリをシステム領域にインストール

管理者権限でコマンドプロンプトを起動する （手順：Windowsキーまたはスタートメニュー → cmd と入力 → 右クリック → 「管理者として実行」）。

次のコマンドを実行する。

REM PyTorch をインストール（GPU対応版）
set "CUDA_TAG=cu128"
set "PYTHON_PATH=C:\Program Files\Python312"
"%PYTHON_PATH%\Scripts\pip" install --no-user -U numpy torch torchvision torchaudio --index-url https://download.pytorch.org/whl/%CUDA_TAG%
pip install --no-user -U transformers opencv-python pillow boxmot

第５章　RT-DETRv2 + BoT-SORT 人物追跡プログラム

概要

このプログラムは、RT-DETRv2による人物検出とBoT-SORTによる追跡・再識別を組み合わせた人物追跡システムである。動画フレームから複数の人物を自動検出し、動きの予測と外観特徴の照合を組み合わせて、フレームをまたいだ人物の同一性を判定する。

主要技術

RT-DETRv2 (Real-Time Detection Transformer v2)

RT-DETRv2は2024年に発表されたリアルタイム物体検出用Transformerアーキテクチャである[1]。従来のYOLOシリーズを凌駕する検出精度を維持しながら、リアルタイム処理を実現する。変形可能な注意機構による多スケール特徴抽出と、クエリ選択により高精度な人物検出を行う。COCO 2017データセットで事前学習されている。このプログラムでは、人物クラス（PERSON_CLASS_ID = 0）の検出に特化した処理を実行する。

BoT-SORT

BoT-SORTは2022年に発表された、動き情報と外観情報を組み合わせたマルチオブジェクト追跡アルゴリズムである[2]。カルマンフィルタによる動き予測、カメラの動きを補償するカメラモーション補償（CMC）、そして改良されたバウンディングボックス表現を統合する。ReIDモデルによる外観特徴を併用するBoT-SORT-ReIDは、MOT17およびMOT20の両ベンチマークにおいて、MOTA、IDF1、HOTAのすべての主要指標で最高水準の性能を達成している[2]。従来のDeepSORTと比較して、より高精度な関連付けと、遮蔽からの復帰性能に優れる。

OSNet (Omni-Scale Network)

OSNetは2019年に発表された、人物再識別のための軽量な畳み込みニューラルネットワークである[3]。複数の畳み込みストリームを持つ残差ブロックにより、異なる空間スケールの特徴を検出し、統一集約ゲートによってスケールに応じた重み付けで特徴を融合する。少ないパラメータ数ながら高い識別性能を達成する。このプログラムでは、BoT-SORTの外観特徴抽出モデルとして使用する。

技術的特徴

このプログラムは段階的処理を行う。第1段階でRT-DETRv2が人物検出を行い、信頼度閾値（CONF_THRESH = 0.5）以上の人物領域を特定する。第2段階でBoT-SORTが、カルマンフィルタによる動き予測とOSNetによる外観特徴抽出を組み合わせた統合追跡により、各人物にIDを割り当てる。高信頼度の検出には外観特徴とIoU（バウンディングボックスの重なり率）の両方を用いた対応付けを行い、低信頼度の検出にはIoUのみによる対応付けを行う二段階の関連付けを実行する。

実装の特色

プログラムはGPU/CPU自動選択機能を備え、CUDA対応環境では高速処理を実現する。人物ID、検出信頼度を日本語で画面表示する。入力ソースとして動画ファイル、ウェブカメラ、サンプル動画に対応する。リアルタイム処理中は各人物に固有の色でバウンディングボックスを描画し、視覚的な区別を可能にする。処理結果は詳細なログとして保存され、フレーム番号、検出人数、Person IDを含む分析データを提供する。

参考文献

[1] Lv, W., Zhao, Y., Chang, Q., Huang, K., Wang, G., & Liu, Y. (2024). RT-DETRv2: Improved Baseline with Bag-of-Freebies for Real-Time Detection Transformer. https://arxiv.org/abs/2407.17140

[2] Aharon, N., Orfaig, R., & Bobrovsky, B. Z. (2022). BoT-SORT: Robust Associations Multi-Pedestrian Tracking. https://arxiv.org/abs/2206.14651

[3] Zhou, K., Yang, Y., Cavallaro, A., & Xiang, T. (2019). Omni-Scale Feature Learning for Person Re-Identification. In Proceedings of the IEEE/CVF International Conference on Computer Vision (ICCV), 3701-3711. https://arxiv.org/abs/1905.00953

ソースコード

# RT-DETRv2 + BoT-SORT による人物追跡・再識別プログラム
# 前準備:
# pip install --no-user -U numpy torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128
# pip install --no-user -U transformers opencv-python pillow boxmot
# 特徴技術および学習済モデルの利用制限: RT-DETRv2はApache 2.0ライセンス。BoT-SORT（boxmot）はAGPL-3.0ライセンス。必ず利用者自身で利用制限を確認すること。

import cv2
import torch
import numpy as np
from pathlib import Path
from transformers import RTDetrV2ForObjectDetection, RTDetrImageProcessor
from PIL import Image, ImageDraw, ImageFont
import time
import urllib.request
from datetime import datetime
from boxmot import BotSort
import tkinter as tk
from tkinter import filedialog

# GPU/CPU自動選択
device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
print(f'デバイス: {str(device)}')
# GPU使用時の最適化
if device.type == 'cuda':
    torch.backends.cudnn.benchmark = True

# -----------------------------
# RT-DETRv2モデル設定
# -----------------------------
MODEL_NAME = 'PekingU/rtdetr_v2_r50vd'
CONF_THRESH = 0.5
PERSON_CLASS_ID = 0
PERSON_COLOR = (0, 255, 0)
FONT_PATH = 'C:/Windows/Fonts/meiryo.ttc'
FONT_SIZE = 20

model = RTDetrV2ForObjectDetection.from_pretrained(MODEL_NAME).to(device)
processor = RTDetrImageProcessor.from_pretrained(MODEL_NAME)
model.eval()
print("RT-DETRv2モデル初期化完了")

# -----------------------------
# BoT-SORT設定（ReID有効）
# -----------------------------
tracker = BotSort(
    reid_weights=Path('osnet_x0_25_msmt17.pt'),  # 外観特徴抽出に使うReIDモデル（自動ダウンロード）
    device=device,
    half=False,
)

# -----------------------------
# IDに基づく色生成関数
# -----------------------------
def get_color_by_id(track_id):
    """IDに基づいて一意の色を生成"""
    if isinstance(track_id, str):
        track_id = hash(track_id) % 2147483647
    elif not isinstance(track_id, int):
        track_id = int(track_id)

    np.random.seed(abs(track_id))
    color = np.random.randint(0, 255, 3)
    return (int(color[0]), int(color[1]), int(color[2]))

# -----------------------------
# ヘルパー関数
# -----------------------------
frame_count = 0
results_log = []

def video_frame_processing(frame):
    global frame_count
    current_time = time.time()
    frame_count += 1

    # RT-DETRv2による人物検出
    frame_pil = Image.fromarray(cv2.cvtColor(frame, cv2.COLOR_BGR2RGB))
    inputs = processor(images=frame_pil, return_tensors='pt')
    inputs = {k: v.to(device) for k, v in inputs.items()}

    with torch.no_grad():
        outputs = model(**inputs)

    target_sizes = torch.tensor([frame.shape[:2]]).to(device)
    results = processor.post_process_object_detection(
        outputs, target_sizes=target_sizes, threshold=CONF_THRESH
    )[0]

    if len(results['labels']) > 0:
        boxes_all = results['boxes'].cpu().numpy()
        scores_all = results['scores'].cpu().numpy()
        labels_all = results['labels'].cpu().numpy()
        person_idx = labels_all == PERSON_CLASS_ID
        boxes = boxes_all[person_idx]
        scores = scores_all[person_idx]
        labels = labels_all[person_idx]
    else:
        boxes = np.empty((0, 4))
        scores = np.empty((0,))
        labels = np.empty((0,))

    # -----------------------------
    # BoT-SORTで追跡・ReIDによるID付与
    # -----------------------------
    if len(boxes) > 0:
        dets = np.concatenate(
            [boxes, scores.reshape(-1, 1), labels.reshape(-1, 1)], axis=1
        ).astype(np.float32)
    else:
        dets = np.empty((0, 6), dtype=np.float32)

    # tracks: [x1, y1, x2, y2, id, conf, cls, ind] の並びで返る
    tracks_arr = tracker.update(dets, frame)

    tracks = []
    for t in tracks_arr:
        x1, y1, x2, y2, tid, conf = t[0], t[1], t[2], t[3], t[4], t[5]
        tracks.append({'id': int(tid), 'box': (x1, y1, x2, y2), 'conf': float(conf)})

    # -----------------------------
    # フォント設定と描画
    # -----------------------------
    font = ImageFont.truetype(FONT_PATH, FONT_SIZE)
    img_pil = Image.fromarray(cv2.cvtColor(frame, cv2.COLOR_BGR2RGB))
    draw = ImageDraw.Draw(img_pil)

    # フレーム情報をPillowで描画
    draw.text((10, 30), f'Frame: {frame_count}', font=font, fill=(255, 255, 0))
    draw.text((10, 70), f'検出人数: {len(tracks)}', font=font, fill=(0, 255, 0))

    # ID情報とバウンディングボックスの描画
    for trk in tracks:
        x1, y1, x2, y2 = map(int, trk['box'])
        tid = trk['id']
        conf = trk['conf']

        # IDに応じた色を取得
        id_color = get_color_by_id(tid)

        # ID情報をテキストで表示（背景付き）
        label_text = f'ID:{tid} Conf:{conf:.2f}'
        bbox = draw.textbbox((x1+5, max(30, y1-10)), label_text, font=font)
        draw.rectangle([bbox[0]-5, bbox[1]-5, bbox[2]+5, bbox[3]+5], fill=id_color)
        draw.text((x1+5, max(30, y1-10)), label_text, font=font, fill=(255, 255, 255))

    frame = cv2.cvtColor(np.array(img_pil), cv2.COLOR_RGB2BGR)

    # MBR（人物の範囲）をIDに応じた色で描画
    for trk in tracks:
        x1, y1, x2, y2 = map(int, trk['box'])
        id_color = get_color_by_id(trk['id'])
        cv2.rectangle(frame, (x1, y1), (x2, y2), id_color, 3)

    # -----------------------------
    # ログ出力
    # -----------------------------
    result = f'Frame {frame_count}: {len(tracks)}人検出'
    for trk in tracks:
        result += f' | ID:{trk["id"]} Conf:{trk["conf"]:.2f}'

    return frame, result, current_time

print("0: 動画ファイル")
print("1: カメラ")
print("2: サンプル動画")

choice = input("選択: ")

if choice == '0':
    root = tk.Tk()
    root.withdraw()
    path = filedialog.askopenfilename()
    if not path:
        exit()
    cap = cv2.VideoCapture(path)
elif choice == '1':
    cap = cv2.VideoCapture(0, cv2.CAP_DSHOW)
    if not cap.isOpened():
        cap = cv2.VideoCapture(0)
    cap.set(cv2.CAP_PROP_BUFFERSIZE, 1)
else:
    # サンプル動画ダウンロード・処理
    SAMPLE_URL = 'https://raw.githubusercontent.com/opencv/opencv/master/samples/data/vtest.avi'
    SAMPLE_FILE = 'vtest.avi'
    urllib.request.urlretrieve(SAMPLE_URL, SAMPLE_FILE)
    cap = cv2.VideoCapture(SAMPLE_FILE)

if not cap.isOpened():
    print('動画ファイル・カメラを開けませんでした')
    exit()

# メイン処理
print('\n=== 動画処理開始 ===')
print('操作方法:')
print('  ESC キーまたは q キー: プログラム終了')
try:
    while True:
        ret, frame = cap.read()
        if not ret:
            break

        MAIN_FUNC_DESC = "RT-DETRv2 + BoT-SORT"
        processed_frame, result, current_time = video_frame_processing(frame)
        cv2.imshow(MAIN_FUNC_DESC, processed_frame)
        if choice == '1':  # カメラの場合
            print(datetime.fromtimestamp(current_time).strftime("%Y-%m-%d %H:%M:%S.%f")[:-3], result)
        else:  # 動画ファイルの場合
            print(frame_count, result)
        results_log.append(result)
        key = cv2.waitKey(1) & 0xFF
        if key == 27 or key == ord('q'):
            break
finally:
    print('\n=== プログラム終了 ===')
    cap.release()
    cv2.destroyAllWindows()
    if results_log:
        with open('result.txt', 'w', encoding='utf-8') as f:
            f.write('=== 結果 ===\n')
            f.write(f'処理フレーム数: {frame_count}\n')
            f.write(f'使用デバイス: {str(device).upper()}\n')
            if device.type == 'cuda':
                f.write(f'GPU: {torch.cuda.get_device_name(0)}\n')
            f.write('\n')
            f.write('\n'.join(results_log))
        print(f'\n処理結果をresult.txtに保存しました')