> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/workflows/ja/burokku/blocks/video-processing/byte-tracker.md).
# Byteトラッカー
{% hint style="warning" %}
**非推奨**
このブロックは非推奨です。代わりに [ByteTrackトラッカー](/workflows/ja/burokku/blocks/video-processing/byte-track-tracker.md) ブロックを使用してください。
{% endhint %}
## v3
ByteTrackアルゴリズムを使用して動画フレーム間でオブジェクトを追跡し、一貫したオブジェクトIDを維持し、遮蔽や一時的な消失を処理し、検出結果を既存のトラックに関連付け、一意のtrack IDを割り当て、インスタンスを新規または既出として分類し、オブジェクトの挙動分析、移動追跡、初回出現検出、動画分析ワークフローを可能にします。
## このブロックの仕組み
このブロックは、各フレームの検出結果を既存のトラックに関連付け、新しいオブジェクトには新規トラックを作成することで、連続する動画フレーム間でオブジェクト追跡を維持し、さらにインスタンスを過去に見たことがあるかどうかに基づいて分類します。このブロックは:
1. 現在のフレームの検出予測と、埋め込み動画メタデータを含む画像を受け取ります
2. 画像から動画メタデータ（フレームレートと動画識別子を含む）を抽出します:
* WorkflowImageDataオブジェクトからvideo\_metadataにアクセスします
* トラッカー設定用に fps（1秒あたりのフレーム数）を抽出します
* 異なる動画ごとに追跡状態を分けて保持するためにvideo\_identifierを抽出します
* fps が欠落していても適切に処理します（失敗せずに 0 を既定値とし、警告を記録します）
3. 動画用の ByteTrack トラッカーを初期化または取得します:
* 各一意の動画（video\_identifier で識別）ごとに新しいトラッカーインスタンスを作成します
* フレーム間で追跡状態を維持するため、トラッカーをメモリに保存します
* メタデータのフレームレートとユーザー指定パラメータでトラッカーを設定します
* 同じ動画の後続フレームでは既存のトラッカーを再利用します
4. 動画用のインスタンスキャッシュを初期化または取得します:
* これまでに見た track ID を追跡するためのキャッシュを作成します
* video\_identifier を使用して、動画ごとに個別のキャッシュを維持します
* instances\_cache\_size パラメータでキャッシュサイズを設定します
* キャッシュ容量の管理に FIFO（先入れ先出し）戦略を使用します
5. 複数の検出バッチが提供されている場合は統合します:
* 複数のソースからの検出結果を 1 つの検出セットにまとめます
* 一貫した追跡のため、すべての検出結果をまとめて処理します
6. ByteTrack アルゴリズムを使用してトラックを更新します:
* **トラックの関連付け**: IoU（Intersection over Union）マッチングを使用して、現在フレームの検出結果を既存のトラックに対応付けます
* **トラックの有効化**: 既存のトラックに一致せず、confidence が track\_activation\_threshold を上回る検出結果から新しいトラックを作成します
* **トラックのマッチング**: IoU が minimum\_matching\_threshold を超えると、検出結果をトラックに関連付けます
* **トラックの保持**: 一致しないトラックを lost\_track\_buffer を使って保持し、一時的な遮蔽に対応します
* **トラックの検証**: minimum\_consecutive\_frames 以上連続して存在したトラックのみを出力します
7. 追跡中のインスタンスを新規または既出として分類します:
* track\_id を持つ各追跡済み検出について、インスタンスキャッシュを確認します
* **新規インスタンス**: キャッシュに見つからない track ID は新規（初回出現）としてマークされます
* **既出インスタンス**: キャッシュに見つかった track ID は既出（再出現）としてマークされます
* 新しい track ID でキャッシュを更新し、FIFO 方式でキャッシュサイズを管理します
8. 追跡の課題に対応します:
* **遮蔽**: オブジェクトが一時的に見えなくなっても、lost\_track\_buffer フレームを使ってトラックを維持します
* **検出漏れ**: 検出が欠けているフレームでもトラックを維持します
* **偽陽性**: 十分長く継続しないトラックを除外します（minimum\_consecutive\_frames）
* **トラックの分断**: 失われたオブジェクト用のバッファを維持することで、トラックの分割を抑えます
9. 各オブジェクトに一意の track ID を割り当てます:
* 各追跡オブジェクトには、フレームをまたいで保持される一貫した track\_id が付与されます
* track ID はトラックが有効化されたときに割り当てられ、動画全体を通して維持されます
* 動画シーケンス全体で個々のオブジェクトを追跡できるようにします
10. 追跡済み検出結果の 3 つのセットを返します:
* **tracked\_detections**: track ID 付きのすべての追跡済み検出結果（v2 と同じ）
* **new\_instances**: 初めて出現する track ID を持つ検出結果（各 track ID は初回生成時に 1 回だけ出現します）
* **already\_seen\_instances**: 既に見たことのある track ID を持つ検出結果（track ID は、トラッカーが検出結果に関連付けるたびに出現します）
ByteTrack は、外観特徴を必要とせずにフレーム間の検出結果を関連付ける、検出ベース追跡（tracking-by-detection）を行う効率的なマルチオブジェクト追跡アルゴリズムです。2 段階の関連付け戦略を使用し、まず高信頼度の検出結果をトラックにマッチングし、次に低信頼度の検出結果を残りのトラックと失われたトラックにマッチングします。このアルゴリズムは失われたトラック用のバッファを維持しており、遮蔽や検出失敗によってオブジェクトが一時的に消えてもトラックを復元できます。インスタンス分類機能により、初回出現（シーンに入ってきた新しいオブジェクト）と再出現（遮蔽後またはフレーム外へ出た後に戻ってきたオブジェクト）を区別でき、カウント、挙動分析、イベント検出に役立ちます。設定可能なパラメータで追跡動作を微調整できます。track\_activation\_threshold は新規トラックを作成するタイミングを制御し（高いほど保守的）、lost\_track\_buffer は遮蔽処理を制御し（高いほど遮蔽からの復帰性能が向上）、minimum\_matching\_threshold は関連付け品質を制御し（高いほど厳密なマッチング）、minimum\_consecutive\_frames は短命な偽トラックを除外します（高いほど偽トラックが少ない）、instances\_cache\_size は新規/既出の分類のために記憶する track ID の数を制御します（高いほど記憶期間が長い）。
## 一般的な使用例
* **ビデオ解析**：行動分析や移動パターンのために動画フレーム間でオブジェクトを追跡します（例: 動画内の人の動きを追跡する、車両の経路を監視する、オブジェクトの軌跡を分析する）ことで、動画分析ワークフローを可能にします
* **初回出現検出**：カウントやイベント検出のために、シーンに入ってくる新しいオブジェクトを識別します（例: エリアに入る新しい人物を検出する、新しく現れる車両を特定する、初回出現を追跡する）ことで、新規インスタンス検出ワークフローを可能にします
* **交通監視**：外観追跡を用いて交通シーン内の車両やオブジェクトを追跡します（例: フレーム間で車両を追跡する、車両の経路を監視する、一貫した ID で一意の車両数を数える、シーンに入る新しい車両を検出する）ことで、交通監視ワークフローを可能にします
* **監視システム**：セキュリティ監視のためにオブジェクトの同一性を維持し、新規侵入を検出します（例: 監視映像内の人物を追跡する、エリアに入る新しい人物を検出する、オブジェクトの移動を監視する、オブジェクトの同一性を維持する）ことで、監視追跡ワークフローを可能にします
* **小売分析**：小売インサイトのために、入店検出を伴って顧客と商品を追跡します（例: 顧客の経路を追跡する、店に入る新規顧客を検出する、買い物行動を監視する、来店者数のパターンを分析する）ことで、小売分析ワークフローを可能にします
* **物体数のカウント**：初回出現を追跡することで一意のオブジェクトを正確にカウントします（例: 新規インスタンスを追跡して一意の来訪者を数える、交差点に入る車両を数える、一意のオブジェクト出現を追跡する）ことで、正確なカウントワークフローを可能にします
## 他のブロックへの接続
このブロックは、動画メタデータと検出予測を含む画像を受け取り、tracked\_detections、new\_instances、already\_seen\_instances を生成します:
* **オブジェクト検出、インスタンスセグメンテーション、またはキーポイント検出ブロックの後** 検出されたオブジェクトを動画フレーム間で追跡します（例: 動画内の検出オブジェクトを追跡する、検出結果に track ID を追加する、フレーム間でオブジェクトの同一性を維持する）ことで、検出から追跡へのワークフローを可能にします
* **new\_instances 出力を使用して** 初回出現を検出して処理します（例: 新しいオブジェクトを数える、初回出現時にアクションをトリガーする、新規侵入を検出する、新しいオブジェクトの追跡を初期化する）ことで、新規インスタンス検出ワークフローを可能にします
* **already\_seen\_instances 出力を使用して** 再出現や戻ってきたオブジェクトを処理します（例: 戻ってくるオブジェクトを扱う、再出現を処理する、既存オブジェクトに絞り込む）ことで、再出現処理ワークフローを可能にします
* **動画分析ブロックの前** 一貫したオブジェクトの同一性を必要とする場合に使用します（例: 追跡されたオブジェクトの挙動を分析する、オブジェクトの軌跡を処理する、追跡済みオブジェクトデータを扱う）ことで、追跡から分析へのワークフローを可能にします
* **可視化ブロックの前** 一貫した色やラベルで追跡オブジェクトを表示します（例: 追跡オブジェクトを可視化する、track ID を表示する、オブジェクトの経路を示す、新規インスタンスを強調表示する）ことで、追跡の可視化ワークフローを可能にします
* **ロジックブロックの前** Continue If のように、トラック情報やインスタンスの状態に基づいて判断します（例: オブジェクトが新規なら継続する、track ID で絞り込む、追跡データを使って判断する、新規か戻りオブジェクトかを扱う）ことで、追跡ベースの判断ワークフローを可能にします
## バージョン差分
**v2からの強化点:**
* **インスタンス分類**: 2 つの新しい出力（`new_instances` と `already_seen_instances`）track ID が以前に見られたことがあるかどうかに基づいて追跡オブジェクトを分類します。これにより、初回出現検出と再出現追跡が可能になります
* **インスタンスキャッシュ**: フレーム間で以前に見た track ID を記憶するインスタンスキャッシュシステムを導入し、シーンに入ってきた新しいオブジェクトと、遮蔽後またはフレーム外へ出た後に再出現したオブジェクトを区別できるようにします
* **キーポイント検出のサポート**: オブジェクト検出とインスタンスセグメンテーションに加えて、キーポイント検出の予測もサポートし、キーポイントベースの検出モデルまで追跡機能を拡張します
* **設定可能なキャッシュサイズ**: 追加します `instances_cache_size` キャッシュ内で記憶する track ID の数を制御するパラメータで、メモリ使用量と追跡履歴の長さのバランスを取ります
* **拡張された出力**: 1 つではなく 3 つの出力を返します - `tracked_detections` （すべての追跡オブジェクト）、 `new_instances` （初回出現）、および `already_seen_instances` （再出現）
## 要件
このブロックでは、frame rate（fps）と video identifier 情報を含む、埋め込み動画メタデータ付きの画像と検出予測が必要です。最適な追跡性能のため、画像の video\_metadata には有効な fps 値を含める必要がありますが、欠落していてもブロックは fps=0 で継続します。このブロックは各動画のフレーム間で追跡状態とインスタンスキャッシュを維持するため、フレームが順次処理される動画ワークフローで使用してください。最適な追跡性能のため、検出結果はフレーム間で一貫して提供する必要があります。このアルゴリズムは安定した検出性能で最もよく機能し、lost\_track\_buffer メカニズムを通じて一時的な検出ギャップに対応します。インスタンスキャッシュは、キャッシュサイズ上限に達すると FIFO 方式で古い track ID を削除しながら、見た track ID の履歴を保持します。
### 型識別子
ステップで次の識別子を使用してください `"type"` フィールド： `roboflow_core/byte_tracker@v3` ワークフローにこのブロックをステップとして追加するには。
### プロパティ
| **名前** | **型** | **説明** | 参照 |
| ---------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| `name` | `str` | このステップの一意の識別子を入力してください。 | ❌ |
| `track_activation_threshold` | `float` | 検出結果から新しいトラックを有効化するための confidence 閾値です。0.0 から 1.0 の間でなければなりません。既定値は 0.25 です。この閾値を上回る confidence を持つ検出結果だけが新しいトラックを作成できます。この閾値を上げる（例: 0.3〜0.5）と、高信頼度の検出結果だけからトラックを作成するため、追跡精度と安定性が向上しますが、confidence が低い正しい検出を見逃す可能性があります。この閾値を下げる（例: 0.15〜0.2）と、低信頼度の検出結果も受け入れるため追跡の完全性は高まりますが、偽陽性によるノイズや不安定性が増すリスクがあります。検出モデルの性能に応じて調整してください。検出が信頼できる場合は低い値を、偽陽性が多い場合は高い値を使用します。 | ✅ |
| `lost_track_buffer` | `整数` | トラックが失われた（一致する検出結果がない）ときに、そのトラックを維持するフレーム数です。正の整数でなければなりません。既定値は 30 フレームです。オブジェクトが一時的に消えた場合（遮蔽、検出漏れ、フレーム外への退出など）、そのトラックは失われたと見なされる前にこのフレーム数だけ維持されます。この値を大きくすると（例: 50〜100）、遮蔽処理が改善され、短い検出ギャップによるトラックの分断や消失が大幅に減りますが、メモリ使用量は増えます。この値を小さくすると（例: 10〜20）、メモリ使用量は減りますが、短い遮蔽中にトラックが消える可能性があります。遮蔽の頻度に応じて調整してください。頻繁に遮蔽が起きる場合は高い値を、安定した追跡シナリオでは低い値を使用します。 | ✅ |
| `minimum_matching_threshold` | `float` | 既存トラックに検出結果をマッチングするための IoU（Intersection over Union）閾値です。0.0 から 1.0 の間でなければなりません。既定値は 0.8 です。検出結果は、バウンディングボックスの IoU がこの閾値を超えたときにトラックへ関連付けられます。この閾値を上げる（例: 0.85〜0.95）と、より強い空間的重なりを要求するため追跡精度は向上しますが、オブジェクトが速く動く場合や検出ボックスが変動する場合にトラックの分断が起こりやすくなります。この閾値を下げる（例: 0.6〜0.75）と、より緩い一致を受け入れるため追跡の完全性は向上しますが、偽陽性の関連付けやトラックのドリフトが発生しやすくなります。オブジェクトの移動速度と検出の安定性に応じて調整してください。安定したオブジェクトには高い値を、速く動くオブジェクトには低い値を使用します。 | ✅ |
| `minimum_consecutive_frames` | `整数` | オブジェクトがトラックとして有効と見なされて出力される前に、連続して追跡される必要がある最小フレーム数です。正の整数でなければなりません。既定値は 1 です（すべてのトラックは即座に有効です）。少なくともこの連続フレーム数だけ継続したトラックのみが出力に含まれます。この値を大きくすると（例: 3〜5）、偽検出や二重検出から偶発的に作成されたトラックを防ぎ、短命な不要トラックを除外できますが、短い正当なトラックを見逃すリスクがあります。この値を小さくすると（例: 1）、すべてのトラックが即座に含まれ、完全性は最大になりますが、偽トラックが含まれる可能性があります。偽陽性率に応じて調整してください。偽検出が多い場合は高い値を、検出が信頼できる場合は低い値を使用します。 | ✅ |
| `instances_cache_size` | `整数` | インスタンスキャッシュ内で、新規か既出かを判定するために記憶する track ID の最大数です。正の整数でなければなりません。既定値は 16384 です。キャッシュは FIFO（先入れ先出し）方式で削除を行い、キャッシュがいっぱいになると最も古い track ID が削除され、新しいもののための空きが作られます。この値を大きくすると（例: 32768〜65536）、より長い期間の track ID 履歴を保持でき、より長い間隔の後の再出現を検出できますが、メモリをより多く使用します。この値を小さくすると（例: 8192）、メモリ使用量は減りますが、以前に出現した track ID の履歴を失い、再出現したオブジェクトが新規として分類される可能性があります。動画の長さやオブジェクトの再出現パターンに応じて調整してください。長い動画や再出現が多い場合は高い値を、短い動画や再出現がまれな場合は低い値を使用します。 | ❌ |
この **参照** 列は、で利用可能な動的値を使ってプロパティをパラメータ化できる可能性を示します `ワークフロー` 実行時。参照 *バインディング* 詳細は。
### ランタイム互換性
`soft` - ランタイム `hosted_serverless`, `dedicated_deployment`；実行 `リモート`; 入力 `動画` このブロックは、プロセスメモリ内に動画ごとの状態を保持します（video\_metadata.video\_identifier をキーとする）。ステートレスまたは複数レプリカのHTTPランタイムでリモートステップ実行を行うと、連続するリクエストが別々のワーカープロセスによって処理される可能性があるため、呼び出し間で状態がリセットされ、追跡／カウント／集計には意味のない出力になります。安定したフレーム間結果を得るには、永続的な WebRTC セッションでローカルステップ実行を使用してください。
`soft` - 入力 `image` このブロックは、動画または繰り返しフレームのワークフローからの時間的コンテキストに依存します。静止画像／写真では、追跡、比較、集計、可視化に使える意味のある履歴がないため、このブロックの利点はほとんど、またはまったくありません。
### 入力と出力のバインディング
利用可能な接続は、そのバインディング種別によって異なります。どのバインディング種別が `Byte Tracker` のバージョン `v3` あるか確認してください。
入力と出力のバインディング
* 入力
* `image` ([*`image`*](/workflows/ja/gaido/developer-guide/kinds/image.md)): ByteTrack の初期化と追跡状態管理に必要な、埋め込み動画メタデータ（fps と video\_identifier）を含む入力画像です。ブロックは WorkflowImageData オブジェクトから video\_metadata を抽出します。fps 値はトラッカーの設定に使用され、video\_identifier は異なる動画ごとに個別の追跡状態とインスタンスキャッシュを維持するために使用されます。fps が欠落しているか無効な場合、ブロックは 0 を既定値とし、警告を記録しますが、処理は継続します。複数の動画を処理する場合は、各動画のメタデータに一意の video\_identifier を含めて、追跡状態とキャッシュを分離してください。ブロックは video\_identifier を使用して、各動画のフレーム間で永続的なトラッカーとインスタンスキャッシュを維持します。
* `検出` (*Union\[*[*`object_detection_prediction`*](/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)*,* [*`instance_segmentation_prediction`*](/workflows/ja/gaido/developer-guide/kinds/instance-segmentation-prediction.md)*,* [*`keypoint_detection_prediction`*](/workflows/ja/gaido/developer-guide/kinds/keypoint-detection-prediction.md)*]*): 現在の動画フレームで追跡するための検出予測（オブジェクト検出、インスタンスセグメンテーション、またはキーポイント検出）です。ブロックはこれらの検出結果を既存のトラックに関連付けるか、新しいトラックを作成します。オブジェクト検出、インスタンスセグメンテーション、キーポイント検出の予測に対応しています。一貫した追跡を維持するため、各フレームに順番に検出結果を提供してください。複数の検出バッチが提供された場合、追跡前に統合されます。検出結果にはバウンディングボックスとクラス名（キーポイント検出の場合はキーポイントも）が含まれている必要があります。追跡後、出力には track\_id 情報が付加された同じ検出結果が含まれ、フレーム間で同じオブジェクトを識別できます。
* `track_activation_threshold` ([*`float_zero_to_one`*](/workflows/ja/gaido/developer-guide/kinds/float-zero-to-one.md)): 検出結果から新しいトラックを有効化するための confidence 閾値です。0.0 から 1.0 の間でなければなりません。既定値は 0.25 です。この閾値を上回る confidence を持つ検出結果だけが新しいトラックを作成できます。この閾値を上げる（例: 0.3〜0.5）と、高信頼度の検出結果だけからトラックを作成するため、追跡精度と安定性が向上しますが、confidence が低い正しい検出を見逃す可能性があります。この閾値を下げる（例: 0.15〜0.2）と、低信頼度の検出結果も受け入れるため追跡の完全性は高まりますが、偽陽性によるノイズや不安定性が増すリスクがあります。検出モデルの性能に応じて調整してください。検出が信頼できる場合は低い値を、偽陽性が多い場合は高い値を使用します。
* `lost_track_buffer` ([*`整数`*](/workflows/ja/gaido/developer-guide/kinds/integer.md)): トラックが失われた（一致する検出結果がない）ときに、そのトラックを維持するフレーム数です。正の整数でなければなりません。既定値は 30 フレームです。オブジェクトが一時的に消えた場合（遮蔽、検出漏れ、フレーム外への退出など）、そのトラックは失われたと見なされる前にこのフレーム数だけ維持されます。この値を大きくすると（例: 50〜100）、遮蔽処理が改善され、短い検出ギャップによるトラックの分断や消失が大幅に減りますが、メモリ使用量は増えます。この値を小さくすると（例: 10〜20）、メモリ使用量は減りますが、短い遮蔽中にトラックが消える可能性があります。遮蔽の頻度に応じて調整してください。頻繁に遮蔽が起きる場合は高い値を、安定した追跡シナリオでは低い値を使用します。
* `minimum_matching_threshold` ([*`float_zero_to_one`*](/workflows/ja/gaido/developer-guide/kinds/float-zero-to-one.md)): 既存トラックに検出結果をマッチングするための IoU（Intersection over Union）閾値です。0.0 から 1.0 の間でなければなりません。既定値は 0.8 です。検出結果は、バウンディングボックスの IoU がこの閾値を超えたときにトラックへ関連付けられます。この閾値を上げる（例: 0.85〜0.95）と、より強い空間的重なりを要求するため追跡精度は向上しますが、オブジェクトが速く動く場合や検出ボックスが変動する場合にトラックの分断が起こりやすくなります。この閾値を下げる（例: 0.6〜0.75）と、より緩い一致を受け入れるため追跡の完全性は向上しますが、偽陽性の関連付けやトラックのドリフトが発生しやすくなります。オブジェクトの移動速度と検出の安定性に応じて調整してください。安定したオブジェクトには高い値を、速く動くオブジェクトには低い値を使用します。
* `minimum_consecutive_frames` ([*`整数`*](/workflows/ja/gaido/developer-guide/kinds/integer.md)): オブジェクトがトラックとして有効と見なされて出力される前に、連続して追跡される必要がある最小フレーム数です。正の整数でなければなりません。既定値は 1 です（すべてのトラックは即座に有効です）。少なくともこの連続フレーム数だけ継続したトラックのみが出力に含まれます。この値を大きくすると（例: 3〜5）、偽検出や二重検出から偶発的に作成されたトラックを防ぎ、短命な不要トラックを除外できますが、短い正当なトラックを見逃すリスクがあります。この値を小さくすると（例: 1）、すべてのトラックが即座に含まれ、完全性は最大になりますが、偽トラックが含まれる可能性があります。偽陽性率に応じて調整してください。偽検出が多い場合は高い値を、検出が信頼できる場合は低い値を使用します。
* 出力
* `tracked_detections` ([`object_detection_prediction`](/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)): 検出されたバウンディングボックスを sv.Detections(...) オブジェクト形式で含む予測。
* `new_instances` ([`object_detection_prediction`](/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)): 検出されたバウンディングボックスを sv.Detections(...) オブジェクト形式で含む予測。
* `already_seen_instances` ([`object_detection_prediction`](/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)): 検出されたバウンディングボックスを sv.Detections(...) オブジェクト形式で含む予測。
JSON 定義の例
```json
{
"name": "",
"type": "roboflow_core/byte_tracker@v3",
"image": "",
"detections": "$steps.object_detection_model.predictions",
"track_activation_threshold": 0.25,
"lost_track_buffer": 30,
"minimum_matching_threshold": 0.8,
"minimum_consecutive_frames": 1,
"instances_cache_size": ""
}
```
## v2
ByteTrackアルゴリズムを使用して動画フレーム間でオブジェクトを追跡し、一貫したオブジェクトIDを維持し、遮蔽や一時的な消失を処理し、検出結果を既存のトラックに関連付け、一意のtrack IDを割り当て、オブジェクトの挙動分析、移動追跡、動画分析ワークフローを可能にします。
## このブロックの仕組み
このブロックは、各フレームの検出結果を既存のトラックに関連付け、新しいオブジェクトには新規トラックを作成することで、連続する動画フレーム間でオブジェクト追跡を維持します。このブロックは:
1. 現在のフレームの検出予測と、埋め込み動画メタデータを含む画像を受け取ります
2. 画像から動画メタデータ（フレームレートと動画識別子を含む）を抽出します:
* WorkflowImageDataオブジェクトからvideo\_metadataにアクセスします
* トラッカー設定用に fps（1秒あたりのフレーム数）を抽出します
* 異なる動画ごとに追跡状態を分けて保持するためにvideo\_identifierを抽出します
* fps が欠落していても適切に処理します（失敗せずに 0 を既定値とし、警告を記録します）
3. 動画用の ByteTrack トラッカーを初期化または取得します:
* 各一意の動画（video\_identifier で識別）ごとに新しいトラッカーインスタンスを作成します
* フレーム間で追跡状態を維持するため、トラッカーをメモリに保存します
* メタデータのフレームレートとユーザー指定パラメータでトラッカーを設定します
* 同じ動画の後続フレームでは既存のトラッカーを再利用します
4. 複数の検出バッチが提供されている場合は統合します:
* 複数のソースからの検出結果を 1 つの検出セットにまとめます
* 一貫した追跡のため、すべての検出結果をまとめて処理します
5. ByteTrack アルゴリズムを使用してトラックを更新します:
* **トラックの関連付け**: IoU（Intersection over Union）マッチングを使用して、現在フレームの検出結果を既存のトラックに対応付けます
* **トラックの有効化**: 既存のトラックに一致せず、confidence が track\_activation\_threshold を上回る検出結果から新しいトラックを作成します
* **トラックのマッチング**: IoU が minimum\_matching\_threshold を超えると、検出結果をトラックに関連付けます
* **トラックの保持**: 一致しないトラックを lost\_track\_buffer を使って保持し、一時的な遮蔽に対応します
* **トラックの検証**: minimum\_consecutive\_frames 以上連続して存在したトラックのみを出力します
6. 追跡の課題に対応します:
* **遮蔽**: オブジェクトが一時的に見えなくなっても、lost\_track\_buffer フレームを使ってトラックを維持します
* **検出漏れ**: 検出が欠けているフレームでもトラックを維持します
* **偽陽性**: 十分長く継続しないトラックを除外します（minimum\_consecutive\_frames）
* **トラックの分断**: 失われたオブジェクト用のバッファを維持することで、トラックの分割を抑えます
7. 各オブジェクトに一意の track ID を割り当てます:
* 各追跡オブジェクトには、フレームをまたいで保持される一貫した track\_id が付与されます
* track ID はトラックが有効化されたときに割り当てられ、動画全体を通して維持されます
* 動画シーケンス全体で個々のオブジェクトを追跡できるようにします
8. track ID 付きの追跡済み検出結果を返します:
* track\_id 情報で強化された検出予測を出力します
* 各検出結果には、フレーム間で同じオブジェクトを識別するための割り当て済み track\_id が含まれます
* すべての元の検出プロパティ（バウンディングボックス、confidence、クラス名）に追跡情報を加えて保持します
ByteTrack は、外観特徴を必要とせずにフレーム間の検出結果を関連付ける、検出ベース追跡（tracking-by-detection）を行う効率的なマルチオブジェクト追跡アルゴリズムです。2 段階の関連付け戦略を使用し、まず高信頼度の検出結果をトラックにマッチングし、次に低信頼度の検出結果を残りのトラックと失われたトラックにマッチングします。このアルゴリズムは失われたトラック用のバッファを維持しており、遮蔽や検出失敗によってオブジェクトが一時的に消えてもトラックを復元できます。設定可能なパラメータで追跡動作を微調整できます。track\_activation\_threshold は新規トラックを作成するタイミングを制御し（高いほど保守的）、lost\_track\_buffer は遮蔽処理を制御し（高いほど遮蔽からの復帰性能が向上）、minimum\_matching\_threshold は関連付け品質を制御し（高いほど厳密なマッチング）、minimum\_consecutive\_frames は短命な偽トラックを除外します（高いほど偽トラックが少ない）。
## 一般的な使用例
* **ビデオ解析**：行動分析や移動パターンのために動画フレーム間でオブジェクトを追跡します（例: 動画内の人の動きを追跡する、車両の経路を監視する、オブジェクトの軌跡を分析する）ことで、動画分析ワークフローを可能にします
* **交通監視**：交通分析のために交通シーン内の車両やオブジェクトを追跡します（例: フレーム間で車両を追跡する、車両の経路を監視する、一貫した ID で車両数を数える）ことで、交通監視ワークフローを可能にします
* **監視システム**：セキュリティ監視のために動画フレーム間でオブジェクトの同一性を維持します（例: 監視映像内の人物を追跡する、オブジェクトの移動を監視する、オブジェクトの同一性を維持する）ことで、監視追跡ワークフローを可能にします
* **スポーツ分析**：スポーツ動画内の選手やオブジェクトを追跡してパフォーマンスを分析します（例: 選手の動きを追跡する、選手の軌跡を分析する、ボールの位置を監視する）ことで、スポーツ分析ワークフローを可能にします
* **小売分析**：小売インサイトのために動画フレーム間で顧客と商品を追跡します（例: 顧客の経路を追跡する、買い物行動を監視する、来店者数のパターンを分析する）ことで、小売分析ワークフローを可能にします
* **オブジェクトの挙動分析**：時間の経過に伴うオブジェクトの挙動や相互作用を分析するためにオブジェクトを追跡します（例: オブジェクト間の相互作用を分析する、移動パターンを調べる、オブジェクト間の関係を追跡する）ことで、挙動分析ワークフローを可能にします
## 他のブロックへの接続
このブロックは、動画メタデータと検出予測を含む画像を受け取り、track ID 付きの tracked\_detections を生成します:
* **物体検出またはインスタンスセグメンテーションブロックの後** 検出されたオブジェクトを動画フレーム間で追跡します（例: 動画内の検出オブジェクトを追跡する、検出結果に track ID を追加する、フレーム間でオブジェクトの同一性を維持する）ことで、検出から追跡へのワークフローを可能にします
* **動画分析ブロックの前** 一貫したオブジェクトの同一性を必要とする場合に使用します（例: 追跡されたオブジェクトの挙動を分析する、オブジェクトの軌跡を処理する、追跡済みオブジェクトデータを扱う）ことで、追跡から分析へのワークフローを可能にします
* **可視化ブロックの前** 一貫した色やラベルで追跡オブジェクトを表示します（例: 追跡オブジェクトを可視化する、track ID を表示する、オブジェクトの経路を示す）ことで、追跡の可視化ワークフローを可能にします
* **ロジックブロックの前** Continue If のように、トラック情報に基づいて判断します（例: オブジェクトが追跡されている場合に継続する、track ID で絞り込む、追跡データを使って判断する）ことで、追跡ベースの判断ワークフローを可能にします
* **カウントまたは集計ブロックの前** 追跡オブジェクトを正確にカウントします（例: 一意の追跡オブジェクトを数える、トラック統計を集計する、トラックデータを処理する）ことで、追跡からカウントへのワークフローを可能にします
* **ビデオ処理パイプラインでは** オブジェクト追跡がより大きな動画分析ワークフローの一部である場合に使用します（例: 動画パイプラインでオブジェクトを追跡する、処理チェーンで同一性を維持する、動画分析を可能にする）ことで、動画追跡パイプラインワークフローを可能にします
## バージョン差分
**v1からの強化点:**
* **入力の簡素化**: `image` を使用し、別個の `metadata` フィールドを要求する代わりに埋め込み動画メタデータを含む入力を使用することで、ワークフロー接続を簡素化し、入力の複雑さを削減します
* **fps の適切な処理**: fps が欠落しているか無効な場合でも、エラーを発生させずに 0 を既定値とし、警告を記録して適切に処理します。これにより、ブロックは不完全なメタデータに対してより堅牢になります
* **統合の改善**: 動画メタデータを別のメタデータ入力ではなく画像オブジェクトから直接アクセスするため、画像ベースのワークフローとの統合が向上します
## 要件
このブロックでは、frame rate（fps）と video identifier 情報を含む、埋め込み動画メタデータ付きの画像と検出予測が必要です。最適な追跡性能のため、画像の video\_metadata には有効な fps 値を含める必要がありますが、欠落していてもブロックは fps=0 で継続します。このブロックは各動画のフレーム間で追跡状態を維持するため、フレームが順次処理される動画ワークフローで使用してください。最適な追跡性能のため、検出結果はフレーム間で一貫して提供する必要があります。このアルゴリズムは安定した検出性能で最もよく機能し、lost\_track\_buffer メカニズムを通じて一時的な検出ギャップに対応します。
### 型識別子
ステップで次の識別子を使用してください `"type"` フィールド： `roboflow_core/byte_tracker@v2` ワークフローにこのブロックをステップとして追加するには。
### プロパティ
| **名前** | **型** | **説明** | 参照 |
| ---------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| `name` | `str` | このステップの一意の識別子を入力してください。 | ❌ |
| `track_activation_threshold` | `float` | 検出結果から新しいトラックを有効化するための confidence 閾値です。0.0 から 1.0 の間でなければなりません。既定値は 0.25 です。この閾値を上回る confidence を持つ検出結果だけが新しいトラックを作成できます。この閾値を上げる（例: 0.3〜0.5）と、高信頼度の検出結果だけからトラックを作成するため、追跡精度と安定性が向上しますが、confidence が低い正しい検出を見逃す可能性があります。この閾値を下げる（例: 0.15〜0.2）と、低信頼度の検出結果も受け入れるため追跡の完全性は高まりますが、偽陽性によるノイズや不安定性が増すリスクがあります。検出モデルの性能に応じて調整してください。検出が信頼できる場合は低い値を、偽陽性が多い場合は高い値を使用します。 | ✅ |
| `lost_track_buffer` | `整数` | トラックが失われた（一致する検出結果がない）ときに、そのトラックを維持するフレーム数です。正の整数でなければなりません。既定値は 30 フレームです。オブジェクトが一時的に消えた場合（遮蔽、検出漏れ、フレーム外への退出など）、そのトラックは失われたと見なされる前にこのフレーム数だけ維持されます。この値を大きくすると（例: 50〜100）、遮蔽処理が改善され、短い検出ギャップによるトラックの分断や消失が大幅に減りますが、メモリ使用量は増えます。この値を小さくすると（例: 10〜20）、メモリ使用量は減りますが、短い遮蔽中にトラックが消える可能性があります。遮蔽の頻度に応じて調整してください。頻繁に遮蔽が起きる場合は高い値を、安定した追跡シナリオでは低い値を使用します。 | ✅ |
| `minimum_matching_threshold` | `float` | 既存トラックに検出結果をマッチングするための IoU（Intersection over Union）閾値です。0.0 から 1.0 の間でなければなりません。既定値は 0.8 です。検出結果は、バウンディングボックスの IoU がこの閾値を超えたときにトラックへ関連付けられます。この閾値を上げる（例: 0.85〜0.95）と、より強い空間的重なりを要求するため追跡精度は向上しますが、オブジェクトが速く動く場合や検出ボックスが変動する場合にトラックの分断が起こりやすくなります。この閾値を下げる（例: 0.6〜0.75）と、より緩い一致を受け入れるため追跡の完全性は向上しますが、偽陽性の関連付けやトラックのドリフトが発生しやすくなります。オブジェクトの移動速度と検出の安定性に応じて調整してください。安定したオブジェクトには高い値を、速く動くオブジェクトには低い値を使用します。 | ✅ |
| `minimum_consecutive_frames` | `整数` | オブジェクトがトラックとして有効と見なされて出力される前に、連続して追跡される必要がある最小フレーム数です。正の整数でなければなりません。既定値は 1 です（すべてのトラックは即座に有効です）。少なくともこの連続フレーム数だけ継続したトラックのみが出力に含まれます。この値を大きくすると（例: 3〜5）、偽検出や二重検出から偶発的に作成されたトラックを防ぎ、短命な不要トラックを除外できますが、短い正当なトラックを見逃すリスクがあります。この値を小さくすると（例: 1）、すべてのトラックが即座に含まれ、完全性は最大になりますが、偽トラックが含まれる可能性があります。偽陽性率に応じて調整してください。偽検出が多い場合は高い値を、検出が信頼できる場合は低い値を使用します。 | ✅ |
この **参照** 列は、で利用可能な動的値を使ってプロパティをパラメータ化できる可能性を示します `ワークフロー` 実行時。参照 *バインディング* 詳細は。
### ランタイム互換性
`soft` - ランタイム `hosted_serverless`, `dedicated_deployment`；実行 `リモート`; 入力 `動画` このブロックは、プロセスメモリ内に動画ごとの状態を保持します（video\_metadata.video\_identifier をキーとする）。ステートレスまたは複数レプリカのHTTPランタイムでリモートステップ実行を行うと、連続するリクエストが別々のワーカープロセスによって処理される可能性があるため、呼び出し間で状態がリセットされ、追跡／カウント／集計には意味のない出力になります。安定したフレーム間結果を得るには、永続的な WebRTC セッションでローカルステップ実行を使用してください。
`soft` - 入力 `image` このブロックは、動画または繰り返しフレームのワークフローからの時間的コンテキストに依存します。静止画像／写真では、追跡、比較、集計、可視化に使える意味のある履歴がないため、このブロックの利点はほとんど、またはまったくありません。
### 入力と出力のバインディング
利用可能な接続は、そのバインディング種別によって異なります。どのバインディング種別が `Byte Tracker` のバージョン `v2` あるか確認してください。
入力と出力のバインディング
* 入力
* `image` ([*`image`*](/workflows/ja/gaido/developer-guide/kinds/image.md)): ByteTrack の初期化と追跡状態管理に必要な、埋め込み動画メタデータ（fps と video\_identifier）を含む入力画像です。ブロックは WorkflowImageData オブジェクトから video\_metadata を抽出します。fps 値はトラッカーの設定に使用され、video\_identifier は異なる動画ごとに個別の追跡状態を維持するために使用されます。fps が欠落しているか無効な場合、ブロックは 0 を既定値とし、警告を記録しますが、処理は継続します。複数の動画を処理する場合は、各動画のメタデータに一意の video\_identifier を含めて、追跡状態を分離してください。ブロックは video\_identifier を使用して、各動画のフレーム間で永続的なトラッカーを維持します。このバージョンでは、別個のメタデータフィールドを必要とせず、メタデータを画像オブジェクトに埋め込むことで入力が簡素化されています。
* `検出` (*Union\[*[*`object_detection_prediction`*](/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)*,* [*`instance_segmentation_prediction`*](/workflows/ja/gaido/developer-guide/kinds/instance-segmentation-prediction.md)*]*): 現在の動画フレームで追跡するための検出予測（オブジェクト検出またはインスタンスセグメンテーション）です。ブロックはこれらの検出結果を既存のトラックに関連付けるか、新しいトラックを作成します。一貫した追跡を維持するため、各フレームに順番に検出結果を提供してください。複数の検出バッチが提供された場合、追跡前に統合されます。検出結果にはバウンディングボックスとクラス名が含まれている必要があります。追跡後、出力には track\_id 情報が付加された同じ検出結果が含まれ、フレーム間で同じオブジェクトを識別できます。
* `track_activation_threshold` ([*`float_zero_to_one`*](/workflows/ja/gaido/developer-guide/kinds/float-zero-to-one.md)): 検出結果から新しいトラックを有効化するための confidence 閾値です。0.0 から 1.0 の間でなければなりません。既定値は 0.25 です。この閾値を上回る confidence を持つ検出結果だけが新しいトラックを作成できます。この閾値を上げる（例: 0.3〜0.5）と、高信頼度の検出結果だけからトラックを作成するため、追跡精度と安定性が向上しますが、confidence が低い正しい検出を見逃す可能性があります。この閾値を下げる（例: 0.15〜0.2）と、低信頼度の検出結果も受け入れるため追跡の完全性は高まりますが、偽陽性によるノイズや不安定性が増すリスクがあります。検出モデルの性能に応じて調整してください。検出が信頼できる場合は低い値を、偽陽性が多い場合は高い値を使用します。
* `lost_track_buffer` ([*`整数`*](/workflows/ja/gaido/developer-guide/kinds/integer.md)): トラックが失われた（一致する検出結果がない）ときに、そのトラックを維持するフレーム数です。正の整数でなければなりません。既定値は 30 フレームです。オブジェクトが一時的に消えた場合（遮蔽、検出漏れ、フレーム外への退出など）、そのトラックは失われたと見なされる前にこのフレーム数だけ維持されます。この値を大きくすると（例: 50〜100）、遮蔽処理が改善され、短い検出ギャップによるトラックの分断や消失が大幅に減りますが、メモリ使用量は増えます。この値を小さくすると（例: 10〜20）、メモリ使用量は減りますが、短い遮蔽中にトラックが消える可能性があります。遮蔽の頻度に応じて調整してください。頻繁に遮蔽が起きる場合は高い値を、安定した追跡シナリオでは低い値を使用します。
* `minimum_matching_threshold` ([*`float_zero_to_one`*](/workflows/ja/gaido/developer-guide/kinds/float-zero-to-one.md)): 既存トラックに検出結果をマッチングするための IoU（Intersection over Union）閾値です。0.0 から 1.0 の間でなければなりません。既定値は 0.8 です。検出結果は、バウンディングボックスの IoU がこの閾値を超えたときにトラックへ関連付けられます。この閾値を上げる（例: 0.85〜0.95）と、より強い空間的重なりを要求するため追跡精度は向上しますが、オブジェクトが速く動く場合や検出ボックスが変動する場合にトラックの分断が起こりやすくなります。この閾値を下げる（例: 0.6〜0.75）と、より緩い一致を受け入れるため追跡の完全性は向上しますが、偽陽性の関連付けやトラックのドリフトが発生しやすくなります。オブジェクトの移動速度と検出の安定性に応じて調整してください。安定したオブジェクトには高い値を、速く動くオブジェクトには低い値を使用します。
* `minimum_consecutive_frames` ([*`整数`*](/workflows/ja/gaido/developer-guide/kinds/integer.md)): オブジェクトがトラックとして有効と見なされて出力される前に、連続して追跡される必要がある最小フレーム数です。正の整数でなければなりません。既定値は 1 です（すべてのトラックは即座に有効です）。少なくともこの連続フレーム数だけ継続したトラックのみが出力に含まれます。この値を大きくすると（例: 3〜5）、偽検出や二重検出から偶発的に作成されたトラックを防ぎ、短命な不要トラックを除外できますが、短い正当なトラックを見逃すリスクがあります。この値を小さくすると（例: 1）、すべてのトラックが即座に含まれ、完全性は最大になりますが、偽トラックが含まれる可能性があります。偽陽性率に応じて調整してください。偽検出が多い場合は高い値を、検出が信頼できる場合は低い値を使用します。
* 出力
* `tracked_detections` ([`object_detection_prediction`](/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)): 検出されたバウンディングボックスを sv.Detections(...) オブジェクト形式で含む予測。
JSON 定義の例
```json
{
"name": "",
"type": "roboflow_core/byte_tracker@v2",
"image": "",
"detections": "$steps.object_detection_model.predictions",
"track_activation_threshold": 0.25,
"lost_track_buffer": 30,
"minimum_matching_threshold": 0.8,
"minimum_consecutive_frames": 1
}
```
## v1
ByteTrackアルゴリズムを使用して動画フレーム間でオブジェクトを追跡し、一貫したオブジェクトIDを維持し、遮蔽や一時的な消失を処理し、検出結果を既存のトラックに関連付け、一意のtrack IDを割り当て、オブジェクトの挙動分析、移動追跡、動画分析ワークフローを可能にします。
## このブロックの仕組み
このブロックは、各フレームの検出結果を既存のトラックに関連付け、新しいオブジェクトには新規トラックを作成することで、連続する動画フレーム間でオブジェクト追跡を維持します。このブロックは:
1. 現在のフレームの検出予測と、フレームレートおよび動画識別子を含む動画メタデータを受け取ります
2. 動画用の ByteTrack トラッカーを初期化または取得します:
* 各一意の動画（video\_identifier で識別）ごとに新しいトラッカーインスタンスを作成します
* フレーム間で追跡状態を維持するため、トラッカーをメモリに保存します
* メタデータのフレームレートとユーザー指定パラメータでトラッカーを設定します
* 同じ動画の後続フレームでは既存のトラッカーを再利用します
3. 複数の検出バッチが提供されている場合は統合します:
* 複数のソースからの検出結果を 1 つの検出セットにまとめます
* 一貫した追跡のため、すべての検出結果をまとめて処理します
4. ByteTrack アルゴリズムを使用してトラックを更新します:
* **トラックの関連付け**: IoU（Intersection over Union）マッチングを使用して、現在フレームの検出結果を既存のトラックに対応付けます
* **トラックの有効化**: 既存のトラックに一致せず、confidence が track\_activation\_threshold を上回る検出結果から新しいトラックを作成します
* **トラックのマッチング**: IoU が minimum\_matching\_threshold を超えると、検出結果をトラックに関連付けます
* **トラックの保持**: 一致しないトラックを lost\_track\_buffer を使って保持し、一時的な遮蔽に対応します
* **トラックの検証**: minimum\_consecutive\_frames 以上連続して存在したトラックのみを出力します
5. 追跡の課題に対応します:
* **遮蔽**: オブジェクトが一時的に見えなくなっても、lost\_track\_buffer フレームを使ってトラックを維持します
* **検出漏れ**: 検出が欠けているフレームでもトラックを維持します
* **偽陽性**: 十分長く継続しないトラックを除外します（minimum\_consecutive\_frames）
* **トラックの分断**: 失われたオブジェクト用のバッファを維持することで、トラックの分割を抑えます
6. 各オブジェクトに一意の track ID を割り当てます:
* 各追跡オブジェクトには、フレームをまたいで保持される一貫した track\_id が付与されます
* track ID はトラックが有効化されたときに割り当てられ、動画全体を通して維持されます
* 動画シーケンス全体で個々のオブジェクトを追跡できるようにします
7. track ID 付きの追跡済み検出結果を返します:
* track\_id 情報で強化された検出予測を出力します
* 各検出結果には、フレーム間で同じオブジェクトを識別するための割り当て済み track\_id が含まれます
* すべての元の検出プロパティ（バウンディングボックス、confidence、クラス名）に追跡情報を加えて保持します
ByteTrack は、外観特徴を必要とせずにフレーム間の検出結果を関連付ける、検出ベース追跡（tracking-by-detection）を行う効率的なマルチオブジェクト追跡アルゴリズムです。2 段階の関連付け戦略を使用し、まず高信頼度の検出結果をトラックにマッチングし、次に低信頼度の検出結果を残りのトラックと失われたトラックにマッチングします。このアルゴリズムは失われたトラック用のバッファを維持しており、遮蔽や検出失敗によってオブジェクトが一時的に消えてもトラックを復元できます。設定可能なパラメータで追跡動作を微調整できます。track\_activation\_threshold は新規トラックを作成するタイミングを制御し（高いほど保守的）、lost\_track\_buffer は遮蔽処理を制御し（高いほど遮蔽からの復帰性能が向上）、minimum\_matching\_threshold は関連付け品質を制御し（高いほど厳密なマッチング）、minimum\_consecutive\_frames は短命な偽トラックを除外します（高いほど偽トラックが少ない）。
## 一般的な使用例
* **ビデオ解析**：行動分析や移動パターンのために動画フレーム間でオブジェクトを追跡します（例: 動画内の人の動きを追跡する、車両の経路を監視する、オブジェクトの軌跡を分析する）ことで、動画分析ワークフローを可能にします
* **交通監視**：交通分析のために交通シーン内の車両やオブジェクトを追跡します（例: フレーム間で車両を追跡する、車両の経路を監視する、一貫した ID で車両数を数える）ことで、交通監視ワークフローを可能にします
* **監視システム**：セキュリティ監視のために動画フレーム間でオブジェクトの同一性を維持します（例: 監視映像内の人物を追跡する、オブジェクトの移動を監視する、オブジェクトの同一性を維持する）ことで、監視追跡ワークフローを可能にします
* **スポーツ分析**：スポーツ動画内の選手やオブジェクトを追跡してパフォーマンスを分析します（例: 選手の動きを追跡する、選手の軌跡を分析する、ボールの位置を監視する）ことで、スポーツ分析ワークフローを可能にします
* **小売分析**：小売インサイトのために動画フレーム間で顧客と商品を追跡します（例: 顧客の経路を追跡する、買い物行動を監視する、来店者数のパターンを分析する）ことで、小売分析ワークフローを可能にします
* **オブジェクトの挙動分析**：時間の経過に伴うオブジェクトの挙動や相互作用を分析するためにオブジェクトを追跡します（例: オブジェクト間の相互作用を分析する、移動パターンを調べる、オブジェクト間の関係を追跡する）ことで、挙動分析ワークフローを可能にします
## 他のブロックへの接続
このブロックは検出予測と動画メタデータを受け取り、track ID 付きの tracked\_detections を生成します:
* **物体検出またはインスタンスセグメンテーションブロックの後** 検出されたオブジェクトを動画フレーム間で追跡します（例: 動画内の検出オブジェクトを追跡する、検出結果に track ID を追加する、フレーム間でオブジェクトの同一性を維持する）ことで、検出から追跡へのワークフローを可能にします
* **動画分析ブロックの前** 一貫したオブジェクトの同一性を必要とする場合に使用します（例: 追跡されたオブジェクトの挙動を分析する、オブジェクトの軌跡を処理する、追跡済みオブジェクトデータを扱う）ことで、追跡から分析へのワークフローを可能にします
* **可視化ブロックの前** 一貫した色やラベルで追跡オブジェクトを表示します（例: 追跡オブジェクトを可視化する、track ID を表示する、オブジェクトの経路を示す）ことで、追跡の可視化ワークフローを可能にします
* **ロジックブロックの前** Continue If のように、トラック情報に基づいて判断します（例: オブジェクトが追跡されている場合に継続する、track ID で絞り込む、追跡データを使って判断する）ことで、追跡ベースの判断ワークフローを可能にします
* **カウントまたは集計ブロックの前** 追跡オブジェクトを正確にカウントします（例: 一意の追跡オブジェクトを数える、トラック統計を集計する、トラックデータを処理する）ことで、追跡からカウントへのワークフローを可能にします
* **ビデオ処理パイプラインでは** オブジェクト追跡がより大きな動画分析ワークフローの一部である場合に使用します（例: 動画パイプラインでオブジェクトを追跡する、処理チェーンで同一性を維持する、動画分析を可能にする）ことで、動画追跡パイプラインワークフローを可能にします
## 要件
このブロックでは、frame rate（fps）情報を含む検出予測（オブジェクト検出またはインスタンスセグメンテーション）と動画メタデータが必要です。動画メタデータには、ByteTrack の初期化に有効な fps 値が含まれている必要があります。このブロックは各動画のフレーム間で追跡状態を維持するため、フレームが順次処理される動画ワークフローで使用してください。最適な追跡性能のため、検出結果はフレーム間で一貫して提供する必要があります。このアルゴリズムは安定した検出性能で最もよく機能し、lost\_track\_buffer メカニズムを通じて一時的な検出ギャップに対応します。
### 型識別子
ステップで次の識別子を使用してください `"type"` フィールド： `roboflow_core/byte_tracker@v1` ワークフローにこのブロックをステップとして追加するには。
### プロパティ
| **名前** | **型** | **説明** | 参照 |
| ---------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| `name` | `str` | このステップの一意の識別子を入力してください。 | ❌ |
| `track_activation_threshold` | `float` | 検出結果から新しいトラックを有効化するための confidence 閾値です。0.0 から 1.0 の間でなければなりません。既定値は 0.25 です。この閾値を上回る confidence を持つ検出結果だけが新しいトラックを作成できます。この閾値を上げる（例: 0.3〜0.5）と、高信頼度の検出結果だけからトラックを作成するため、追跡精度と安定性が向上しますが、confidence が低い正しい検出を見逃す可能性があります。この閾値を下げる（例: 0.15〜0.2）と、低信頼度の検出結果も受け入れるため追跡の完全性は高まりますが、偽陽性によるノイズや不安定性が増すリスクがあります。検出モデルの性能に応じて調整してください。検出が信頼できる場合は低い値を、偽陽性が多い場合は高い値を使用します。 | ✅ |
| `lost_track_buffer` | `整数` | トラックが失われた（一致する検出結果がない）ときに、そのトラックを維持するフレーム数です。正の整数でなければなりません。既定値は 30 フレームです。オブジェクトが一時的に消えた場合（遮蔽、検出漏れ、フレーム外への退出など）、そのトラックは失われたと見なされる前にこのフレーム数だけ維持されます。この値を大きくすると（例: 50〜100）、遮蔽処理が改善され、短い検出ギャップによるトラックの分断や消失が大幅に減りますが、メモリ使用量は増えます。この値を小さくすると（例: 10〜20）、メモリ使用量は減りますが、短い遮蔽中にトラックが消える可能性があります。遮蔽の頻度に応じて調整してください。頻繁に遮蔽が起きる場合は高い値を、安定した追跡シナリオでは低い値を使用します。 | ✅ |
| `minimum_matching_threshold` | `float` | 既存トラックに検出結果をマッチングするための IoU（Intersection over Union）閾値です。0.0 から 1.0 の間でなければなりません。既定値は 0.8 です。検出結果は、バウンディングボックスの IoU がこの閾値を超えたときにトラックへ関連付けられます。この閾値を上げる（例: 0.85〜0.95）と、より強い空間的重なりを要求するため追跡精度は向上しますが、オブジェクトが速く動く場合や検出ボックスが変動する場合にトラックの分断が起こりやすくなります。この閾値を下げる（例: 0.6〜0.75）と、より緩い一致を受け入れるため追跡の完全性は向上しますが、偽陽性の関連付けやトラックのドリフトが発生しやすくなります。オブジェクトの移動速度と検出の安定性に応じて調整してください。安定したオブジェクトには高い値を、速く動くオブジェクトには低い値を使用します。 | ✅ |
| `minimum_consecutive_frames` | `整数` | オブジェクトがトラックとして有効と見なされて出力される前に、連続して追跡される必要がある最小フレーム数です。正の整数でなければなりません。既定値は 1 です（すべてのトラックは即座に有効です）。少なくともこの連続フレーム数だけ継続したトラックのみが出力に含まれます。この値を大きくすると（例: 3〜5）、偽検出や二重検出から偶発的に作成されたトラックを防ぎ、短命な不要トラックを除外できますが、短い正当なトラックを見逃すリスクがあります。この値を小さくすると（例: 1）、すべてのトラックが即座に含まれ、完全性は最大になりますが、偽トラックが含まれる可能性があります。偽陽性率に応じて調整してください。偽検出が多い場合は高い値を、検出が信頼できる場合は低い値を使用します。 | ✅ |
この **参照** 列は、で利用可能な動的値を使ってプロパティをパラメータ化できる可能性を示します `ワークフロー` 実行時。参照 *バインディング* 詳細は。
### ランタイム互換性
`soft` - ランタイム `hosted_serverless`, `dedicated_deployment`；実行 `リモート`; 入力 `動画` このブロックは、プロセスメモリ内に動画ごとの状態を保持します（video\_metadata.video\_identifier をキーとする）。ステートレスまたは複数レプリカのHTTPランタイムでリモートステップ実行を行うと、連続するリクエストが別々のワーカープロセスによって処理される可能性があるため、呼び出し間で状態がリセットされ、追跡／カウント／集計には意味のない出力になります。安定したフレーム間結果を得るには、永続的な WebRTC セッションでローカルステップ実行を使用してください。
`soft` - 入力 `image` このブロックは、動画または繰り返しフレームのワークフローからの時間的コンテキストに依存します。静止画像／写真では、追跡、比較、集計、可視化に使える意味のある履歴がないため、このブロックの利点はほとんど、またはまったくありません。
### 入力と出力のバインディング
利用可能な接続は、そのバインディング種別によって異なります。どのバインディング種別が `Byte Tracker` のバージョン `v1` あるか確認してください。
入力と出力のバインディング
* 入力
* `metadata` ([*`video_metadata`*](/workflows/ja/gaido/developer-guide/kinds/video-metadata.md)): ByteTrack の初期化と追跡状態管理に必要な、frame rate（fps）と video identifier 情報を含む動画メタデータです。fps 値はトラッカーの設定に使用され、video\_identifier は異なる動画ごとに個別の追跡状態を維持するために使用されます。メタデータには有効な fps 情報が含まれている必要があります。ByteTrack の初期化にはフレームレートが必要です。複数の動画を処理する場合は、各動画のメタデータに一意の video\_identifier を含めて、追跡状態を分離してください。ブロックは video\_identifier を使用して、各動画のフレーム間で永続的なトラッカーを維持します。。
* `検出` (*Union\[*[*`object_detection_prediction`*](/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)*,* [*`instance_segmentation_prediction`*](/workflows/ja/gaido/developer-guide/kinds/instance-segmentation-prediction.md)*]*): 現在の動画フレームで追跡するための検出予測（オブジェクト検出またはインスタンスセグメンテーション）です。ブロックはこれらの検出結果を既存のトラックに関連付けるか、新しいトラックを作成します。一貫した追跡を維持するため、各フレームに順番に検出結果を提供してください。複数の検出バッチが提供された場合、追跡前に統合されます。検出結果にはバウンディングボックスとクラス名が含まれている必要があります。追跡後、出力には track\_id 情報が付加された同じ検出結果が含まれ、フレーム間で同じオブジェクトを識別できます。
* `track_activation_threshold` ([*`float_zero_to_one`*](/workflows/ja/gaido/developer-guide/kinds/float-zero-to-one.md)): 検出結果から新しいトラックを有効化するための confidence 閾値です。0.0 から 1.0 の間でなければなりません。既定値は 0.25 です。この閾値を上回る confidence を持つ検出結果だけが新しいトラックを作成できます。この閾値を上げる（例: 0.3〜0.5）と、高信頼度の検出結果だけからトラックを作成するため、追跡精度と安定性が向上しますが、confidence が低い正しい検出を見逃す可能性があります。この閾値を下げる（例: 0.15〜0.2）と、低信頼度の検出結果も受け入れるため追跡の完全性は高まりますが、偽陽性によるノイズや不安定性が増すリスクがあります。検出モデルの性能に応じて調整してください。検出が信頼できる場合は低い値を、偽陽性が多い場合は高い値を使用します。
* `lost_track_buffer` ([*`整数`*](/workflows/ja/gaido/developer-guide/kinds/integer.md)): トラックが失われた（一致する検出結果がない）ときに、そのトラックを維持するフレーム数です。正の整数でなければなりません。既定値は 30 フレームです。オブジェクトが一時的に消えた場合（遮蔽、検出漏れ、フレーム外への退出など）、そのトラックは失われたと見なされる前にこのフレーム数だけ維持されます。この値を大きくすると（例: 50〜100）、遮蔽処理が改善され、短い検出ギャップによるトラックの分断や消失が大幅に減りますが、メモリ使用量は増えます。この値を小さくすると（例: 10〜20）、メモリ使用量は減りますが、短い遮蔽中にトラックが消える可能性があります。遮蔽の頻度に応じて調整してください。頻繁に遮蔽が起きる場合は高い値を、安定した追跡シナリオでは低い値を使用します。
* `minimum_matching_threshold` ([*`float_zero_to_one`*](/workflows/ja/gaido/developer-guide/kinds/float-zero-to-one.md)): 既存トラックに検出結果をマッチングするための IoU（Intersection over Union）閾値です。0.0 から 1.0 の間でなければなりません。既定値は 0.8 です。検出結果は、バウンディングボックスの IoU がこの閾値を超えたときにトラックへ関連付けられます。この閾値を上げる（例: 0.85〜0.95）と、より強い空間的重なりを要求するため追跡精度は向上しますが、オブジェクトが速く動く場合や検出ボックスが変動する場合にトラックの分断が起こりやすくなります。この閾値を下げる（例: 0.6〜0.75）と、より緩い一致を受け入れるため追跡の完全性は向上しますが、偽陽性の関連付けやトラックのドリフトが発生しやすくなります。オブジェクトの移動速度と検出の安定性に応じて調整してください。安定したオブジェクトには高い値を、速く動くオブジェクトには低い値を使用します。
* `minimum_consecutive_frames` ([*`整数`*](/workflows/ja/gaido/developer-guide/kinds/integer.md)): オブジェクトがトラックとして有効と見なされて出力される前に、連続して追跡される必要がある最小フレーム数です。正の整数でなければなりません。既定値は 1 です（すべてのトラックは即座に有効です）。少なくともこの連続フレーム数だけ継続したトラックのみが出力に含まれます。この値を大きくすると（例: 3〜5）、偽検出や二重検出から偶発的に作成されたトラックを防ぎ、短命な不要トラックを除外できますが、短い正当なトラックを見逃すリスクがあります。この値を小さくすると（例: 1）、すべてのトラックが即座に含まれ、完全性は最大になりますが、偽トラックが含まれる可能性があります。偽陽性率に応じて調整してください。偽検出が多い場合は高い値を、検出が信頼できる場合は低い値を使用します。
* 出力
* `tracked_detections` ([`object_detection_prediction`](/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)): 検出されたバウンディングボックスを sv.Detections(...) オブジェクト形式で含む予測。
JSON 定義の例
```json
{
"name": "",
"type": "roboflow_core/byte_tracker@v1",
"metadata": "",
"detections": "$steps.object_detection_model.predictions",
"track_activation_threshold": 0.25,
"lost_track_buffer": 30,
"minimum_matching_threshold": 0.8,
"minimum_consecutive_frames": 1
}
```