ailia Tracker

物体検出結果をもとに物体の移動を追跡するライブラリです。

はじめに

プラットフォームを選び、YOLOX-S 検出と ByteTrack の組合せで動画中の物体を追跡してみましょう。

1

インストール

ailia Tracker と、検出に使う ailia SDK、サンプルで使う opencv-python をインストールします。

pip3 install ailia ailia_tracker opencv-python

Python や git をまだインストールしていない方は、Python 環境のセットアップ(Windows / Mac / Linux) を先にご覧ください。

PyPI で見る
2

サンプルを実行

ailia-models から example_tracker.py をダウンロードして実行します。YOLOX-S で検出した物体を ByteTrack で追跡し、ID 付きのバウンディングボックスを表示します。モデルは自動ダウンロードされます。デフォルトは Web カメラ入力で、-v video.mp4 で動画ファイルも指定できます。

wget https://raw.githubusercontent.com/ailia-ai/ailia-models/master/object_tracking/bytetrack/example_tracker.py
python3 example_tracker.py

Windows の場合は python3 の代わりに python を使用してください。

example_tracker.py

動作環境

ailia Tracker はデスクトップとモバイルで動作します。物体検出部分は Windows / Linux で GPU 推論に対応しています。

対応 OS

  • Windows 10 / 11
  • macOS 11 以降
  • Linux (Ubuntu 20.04 以降)
  • iOS 13 / Android 7 以降

言語とコンパイラ

  • Python 3.8 以降 / Dart・Flutter 3.3 以降
  • C++17 (VS 2019 以降 / Xcode 14.2 以降 / clang) + CMake
  • C# / Unity 2021.3.10f1 以降
  • Kotlin / Java (JNI)

同梱モデル

  • YOLOX-S (物体検出)
  • ByteTrack (物体追跡)
  • 80 COCO カテゴリ

入出力

  • 動画ファイルまたは Web カメラ入力
  • 注釈付き MP4 出力
  • 追跡 ID / カテゴリ / 信頼度
  • バウンディングボックス (x / y / w / h)

機能

Python / C / C# / Flutter / JNI API で利用できる物体追跡機能。

検出と対応付け

  • YOLOX-S 検出器 (80 COCO クラス)
  • ByteTrack による ID 対応付け
  • GPU 推論によるフレームごとの推論

追跡結果

  • フレーム間で一貫した追跡 ID
  • 物体カテゴリ
  • 検出確率
  • 正規化バウンディングボックス (0-1 範囲)

フィルタリング

  • カテゴリでフィルタ可能 (例: category 0 で人物のみ)
  • 信頼度でのフィルタはアプリ側で実装

GPU アクセラレーション

  • Windows / Linux で cuDNN + CUDA (検出処理)
  • macOS / iOS で Metal
  • GPU がない環境では CPU フォールバック

プロジェクトで API を使う

既存の検出器に ByteTrack の追跡処理を組み合わせる最小サンプル。

import ailia_tracker

tracker = ailia_tracker.AiliaTracker()  # ByteTrack with default settings

# Per frame: feed detector outputs, compute, read tracked objects
for obj in detections:  # ailia.Detector results
    tracker.add_target(obj["category"], obj["prob"],
                       obj["box"]["x"], obj["box"]["y"],
                       obj["box"]["w"], obj["box"]["h"])
tracker.compute()

for obj in tracker.get_objects():
    print(f"ID {obj.id}  bbox {obj.x:.2f} {obj.y:.2f} {obj.w:.2f} {obj.h:.2f}")

tracker.release()

プラットフォーム別 API リファレンス

Python

C++

Unity

Flutter

よくある質問

ailia Tracker についてのよくある質問。

ailia Tracker は内部でどんなモデルを使っていますか?

フレームごとの物体検出を 80 の COCO カテゴリで行うのが YOLOX-S、フレーム間で検出結果を安定した追跡 ID に対応付けるのが ByteTrack です。

モデルファイルはどこからダウンロードできますか?

YOLOX-S の重みと prototxt。

yolox_s.opt.onnx
yolox_s.opt.onnx.prototxt

両方のファイルをサンプルバイナリと同じフォルダに配置してください。

人物だけなど特定カテゴリのみ追跡するには?

AILIATrackerObject には COCO ラベルに対応する整数の category 属性があります。アプリ側でフィルタしてください — たとえば人物だけ追跡するなら category == 0 のみ残す、必要なラベルだけのルックアップを作るなど。

Tracker からはどんな情報が得られますか?

各追跡オブジェクトに対して、フレーム間で一貫した idcategory、検出 prob、および正規化バウンディングボックス (x, y, w, h) が得られます。0 が左 / 上端、1 が右 / 下端です。

パラメータ (score_threshold / track_threshold / track_buffer など) はどう調整しますか?

検出スコア閾値、トラッキングバッファ長、IoU マッチング閾値などは AILIATrackerSettings 構造体で設定します。各フィールドの意味と推奨値、ByteTrack の挙動については API ドキュメントの ailia Tracker のパラメータ セクションを参照してください。

Web カメラでも使えますか?

はい。Python サンプルはデフォルトで Web カメラ入力です (-v <index> でカメラ番号を指定)。C++ サンプルでは -w <index> を渡すとファイルの代わりに Web カメラ入力になります。Unity バインディングも ailia-tracker-unity パッケージで同じカメラ入力モードを提供します。

GPU 推論を有効にするには?

macOS / iOS では Metal が自動的に使用されます。Windows / Linux では CUDA Toolkit と cuDNN のインストールが必要です。詳しい手順は CUDA Toolkit / cuDNN インストールガイド を参照してください。GPU アクセラレーションは物体検出処理に適用され、ByteTrack の対応付けは CPU 上で動作します。

ライセンスはどう扱われますか?

C++ バインディングは評価版パッケージの ailia.lic をランタイムライブラリと同じ場所に配置する必要があります。

Windows: ailia.dll と同じフォルダ。
macOS: ~/Library/SHALO/
Linux: ~/.shalo/

Unity と JNI バインディングは初回実行時に評価ライセンスを自動ダウンロードします。商用配布には製品ライセンスを申請してください。詳細は ailia ライセンス規約 を参照してください。

資料

関連記事

ailia Tech Blog のモデル解説・リリースノート・チュートリアルです。

ailia Tracker: 物体追跡ライブラリ
tech.ailia.ai
ByteTrack: 低確度 BBox も考慮するトラッキング
tech.ailia.ai
YOLOX: YOLOv5 を超える物体検出
tech.ailia.ai