ailia Tracker

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

はじめに

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

1

サンプルをクローン

C++ サンプルリポジトリをクローンしてサブモジュールを初期化します。ailia-tracker-cpp バインディングはサブモジュールとして含まれています。

git clone https://github.com/ailia-ai/ailia-models-cpp.git
cd ailia-models-cpp
git submodule init
git submodule update

macOS の場合のみ、dylib の quarantine 属性を解除します。

./xattr.sh
サンプルリポジトリ bytetrack サンプル
2

ビルドして実行

1 か月の評価ライセンスを取得し、CMake と OpenCV をインストールしてビルド、ByteTrack サンプルを実行します。bytetrack.sh が YOLOX-S 検出モデルを自動でダウンロードしてから動画を解析します。

# 評価ライセンスを取得
cd ailia
python3 download_license.py
cd ..

# macOS
brew install cmake opencv
# Linux: apt install cmake libopencv-dev
# Windows: install CMake and Visual Studio,
#   then set OpenCV_DIR to your OpenCV build path

cmake .
cmake --build .
cd object_tracking/bytetrack
./bytetrack.sh    # use bytetrack.bat on Windows
C++ セットアップガイド

動作環境

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

対応 OS

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

言語とコンパイラ

  • 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)

機能

C / C# / 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 の追跡処理を組み合わせる最小サンプル。

#include "ailia_tracker.h"
#include "ailia_detector.h"

struct AILIATracker *tracker = nullptr;
AILIATrackerSettings settings = {0.1f, 0.7f, 0.5f, 30, 0.8f};
ailiaTrackerCreate(&tracker, AILIA_TRACKER_ALGORITHM_BYTE_TRACK, &settings,
                   AILIA_TRACKER_SETTINGS_VERSION, AILIA_TRACKER_FLAG_NONE);

// Per frame: feed detector outputs, compute, read tracked objects
for (auto &d : detectorObjects) {  // d is AILIADetectorObject
    ailiaTrackerAddTarget(tracker, &d, AILIA_DETECTOR_OBJECT_VERSION);
}
ailiaTrackerCompute(tracker);

unsigned int n;
ailiaTrackerGetObjectCount(tracker, &n);
for (unsigned int i = 0; i < n; i++) {
    AILIATrackerObject obj;
    ailiaTrackerGetObject(tracker, &obj, i, AILIA_TRACKER_OBJECT_VERSION);
    printf("ID %u  bbox %.2f %.2f %.2f %.2f\n", obj.id, obj.x, obj.y, obj.w, obj.h);
}

ailiaTrackerDestroy(tracker);

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

C++

Unity

JNI

よくある質問

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 カメラでも使えますか?

はい。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