> 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トラッカー

ByteTrackを使用して動画フレーム間でオブジェクト位置を追跡・更新します。

{% hint style="warning" %}
**非推奨**

このブロックは非推奨です。代わりに [ByteTrackトラッカー](https://docs.roboflow.com/workflows/ja/burokku/blocks/video-processing/byte-track-tracker.md) ブロックを使用してください。
{% endhint %}

## v3

ByteTrackアルゴリズムを使用して動画フレーム間でオブジェクトを追跡し、一貫したオブジェクトIDを維持し、遮蔽や一時的な消失に対応し、検出結果を既存のトラックに関連付け、固有のトラックIDを割り当て、インスタンスを新規または既出として分類し、オブジェクトの行動分析、移動追跡、初回出現検出、動画解析ワークフローを実現します。

## このブロックの仕組み

このブロックは、各フレームの検出結果を既存のトラックに関連付けて新しいオブジェクトには新規トラックを作成し、さらにインスタンスをこれまで見たことがあるかどうかに基づいて分類することで、連続する動画フレーム間でオブジェクト追跡を維持します。このブロックは：

1. 現在のフレームの検出予測と、動画メタデータを埋め込んだ画像を受け取ります
2. 画像から動画メタデータ（フレームレートと動画識別子を含む）を抽出します：
   * WorkflowImageData オブジェクトから video\_metadata にアクセスします
   * トラッカー設定用のfps（1秒あたりのフレーム数）を抽出します
   * video\_identifier を抽出して、異なる動画ごとに個別の追跡状態を維持します
   * fpsがない場合も適切に処理します（失敗する代わりに0を既定値とし、警告を記録します）
3. 動画用のByteTrackトラッカーを初期化または取得します：
   * 各一意の動画（video\_identifierで識別）ごとに新しいトラッカーインスタンスを作成します
   * フレーム間で追跡状態を維持するためにトラッカーをメモリに保存します
   * メタデータのフレームレートとユーザー指定のパラメータでトラッカーを設定します
   * 同じ動画の後続フレームでは既存のトラッカーを再利用します
4. 動画用のインスタンスキャッシュを初期化または取得します：
   * これまで見たトラックIDを追跡するためのキャッシュを作成します
   * video\_identifierを使用して、各動画ごとに別々のキャッシュを保持します
   * instances\_cache\_sizeパラメータを使ってキャッシュサイズを設定します
   * FIFO（先入れ先出し）方式でキャッシュ容量を管理します
5. 複数の検出バッチが提供されている場合、それらを統合します：
   * 複数のソースからの検出結果を1つの検出セットにまとめます
   * 一貫した追跡のため、すべての検出結果がまとめて処理されるようにします
6. ByteTrackアルゴリズムを使用してトラックを更新します：
   * **トラックの関連付け**：IoU（Intersection over Union）マッチングを使用して、現在フレームの検出結果を既存のトラックに対応付けます
   * **トラックの有効化**：既存のトラックに一致しない、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は、外観特徴を必要とせずにフレーム間で検出結果を関連付ける、検出ベース追跡を行う効率的なマルチオブジェクト追跡アルゴリズムです。2段階の関連付け戦略を使用し、まず高信頼度の検出結果をトラックに一致させ、その後低信頼度の検出結果を残りのトラックや失われたトラックに一致させます。このアルゴリズムは失われたトラック用のバッファを保持し、遮蔽や検出失敗によってオブジェクトが一時的に消えてもトラックを復元できるようにします。インスタンス分類機能により、初回出現（シーンに入ってくる新しいオブジェクト）と再出現（遮蔽後またはフレーム外への移動後に戻ってきたオブジェクト）を区別でき、これはカウント、行動分析、イベント検出に役立ちます。設定可能なパラメータにより追跡挙動を調整できます。track\_activation\_thresholdは新しいトラックを作成するタイミングを制御し（高いほど保守的）、lost\_track\_bufferは遮蔽処理を制御し（高いほど遮蔽復元が優れる）、minimum\_matching\_thresholdは関連付け品質を制御し（高いほど厳密なマッチング）、minimum\_consecutive\_framesは短命な誤トラックを除外し（高いほど誤トラックが少ない）、instances\_cache\_sizeは新規／既出分類のために記憶するtrack IDの数を制御します（高いほど記憶が長い）。

## 一般的な使用例

* **動画解析**：行動分析や移動パターンのために動画フレーム間でオブジェクトを追跡します（例：動画内の人物の移動を追跡し、車両の経路を監視し、オブジェクトの軌跡を分析する）ことで、動画解析ワークフローを実現します
* **初回出現検出**：シーンに入ってくる新しいオブジェクトを識別し、カウントやイベント検出に利用します（例：エリアに入る新しい人物を検出し、新しく現れた車両を識別し、初回出現を追跡する）ことで、新規インスタンス検出ワークフローを実現します
* **交通監視**：交通シーンで車両やオブジェクトを外観追跡付きで追跡します（例：フレーム間で車両を追跡し、車両の経路を監視し、一貫したIDでユニークな車両数を数え、シーンに入る新しい車両を検出する）ことで、交通監視ワークフローを実現します
* **監視システム**：セキュリティ監視のためにオブジェクトIDを維持し、新規侵入を検出します（例：監視映像内の人物を追跡し、エリアに入る新しい人物を検出し、オブジェクトの移動を監視し、オブジェクトIDを維持する）ことで、監視追跡ワークフローを実現します
* **小売分析**：小売インサイトのために顧客と商品を追跡し、入店検知を行います（例：顧客の経路を追跡し、店舗に入る新規顧客を検出し、購買行動を監視し、人流パターンを分析する）ことで、小売分析ワークフローを実現します
* **オブジェクト数カウント**：初回出現を追跡することでユニークなオブジェクトを正確に数えます（例：新規インスタンスを追跡してユニークな来訪者数を数え、交差点に入る車両を数え、一意のオブジェクト出現を追跡する）ことで、正確なカウントワークフローを実現します

## 他のブロックへの接続

このブロックは動画メタデータと検出予測を含む画像を受け取り、tracked\_detections、new\_instances、already\_seen\_instancesを出力します：

* **オブジェクト検出、インスタンスセグメンテーション、またはキーポイント検出ブロックの後に** 動画フレーム間で検出されたオブジェクトを追跡するために使用します（例：動画内で検出オブジェクトを追跡し、検出結果にtrack IDを追加し、フレーム間でオブジェクトIDを維持する）ことで、検出から追跡へのワークフローを実現します
* **new\_instances出力を使用して** 初回出現を検出・処理します（例：新しいオブジェクトを数え、初回出現時にアクションを起動し、新規侵入を検出し、新しいオブジェクトの追跡を開始する）ことで、新規インスタンス検出ワークフローを実現します
* **already\_seen\_instances出力を使用して** 再出現や戻ってきたオブジェクトを処理します（例：戻ってきたオブジェクトを扱い、再出現を処理し、既存オブジェクトのみを抽出する）ことで、再出現処理ワークフローを実現します
* **動画分析ブロックの前に** 一貫したオブジェクトIDを必要とする処理を行います（例：追跡済みオブジェクトの行動を分析し、オブジェクトの軌跡を処理し、追跡済みオブジェクトデータを扱う）ことで、追跡から分析へのワークフローを実現します
* **可視化ブロックの前** 一貫した色やラベルで追跡済みオブジェクトを表示します（例：追跡済みオブジェクトを可視化し、track IDを表示し、オブジェクトの経路を示し、新規インスタンスを強調表示する）ことで、追跡可視化ワークフローを実現します
* **ロジックブロックの前** Continue Ifのように、track情報やインスタンス状態に基づいて判断します（例：オブジェクトが新規なら続行し、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` （再出現）

## 要件

このブロックは、フレームレート（fps）と動画識別子情報を含む、埋め込まれた動画メタデータ付きの検出予測（オブジェクト検出、インスタンスセグメンテーション、またはキーポイント検出）と画像を必要とします。画像のvideo\_metadataには、最適な追跡性能のために有効なfps値を含める必要がありますが、欠けていてもブロックはfps=0で継続します。このブロックは各動画ごとにフレーム間で追跡状態とインスタンスキャッシュを維持するため、フレームを順次処理する動画ワークフローで使用してください。最適な追跡性能のため、検出結果はフレーム間で一貫して提供する必要があります。このアルゴリズムは安定した検出性能で最もよく機能し、lost\_track\_bufferメカニズムを通じて一時的な検出ギャップを処理します。インスタンスキャッシュは、キャッシュサイズ上限に達したときにFIFO方式で古いものから順に削除しながら、見たことのあるtrack IDの履歴を保持します。

### タイプ識別子

ステップで次の識別子を使用してください `"type"` フィールド: `roboflow_core/byte_tracker@v3` を、ワークフローにステップとして追加します。

### プロパティ

| **名前**                       | **型**   | **説明**                                                                                                                                                                                                                                                                                                                                                                                                                     | 参照 |
| ---------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| `name`                       | `str`   | このステップの一意の識別子を入力してください。                                                                                                                                                                                                                                                                                                                                                                                                    | ❌  |
| `track_activation_threshold` | `float` | 検出結果から新しいトラックを有効化するための信頼度しきい値です。0.0〜1.0の範囲である必要があります。既定値は0.25です。このしきい値を超える信頼度を持つ検出結果のみが新しいトラックを作成できます。このしきい値を上げる（例：0.3〜0.5）と、高信頼度の検出結果のみからトラックを作成するため、追跡の精度と安定性が向上しますが、信頼度の低い正しい検出を見逃す可能性があります。このしきい値を下げる（例：0.15〜0.2）と、低信頼度の検出結果も受け入れるため追跡の完全性は向上しますが、誤検出によるノイズや不安定さが増すリスクがあります。検出モデルの性能に応じて調整してください。検出結果が信頼できる場合は低め、誤検出が多い場合は高めの値を使用します。                                                                                  | ✅  |
| `lost_track_buffer`          | `int`   | トラックが失われたとき（一致する検出結果がないとき）に、そのトラックを維持するフレーム数です。正の整数である必要があります。既定値は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` | `int`   | オブジェクトがトラックとして有効と判断され、出力される前に必要な連続フレーム数です。正の整数である必要があります。既定値は1です（すべてのトラックは即座に有効になります）。少なくともこの連続フレーム数だけ継続したトラックのみが出力に含まれます。この値を上げる（例：3〜5）と、誤検出や二重検出から偶発的に作成されたトラックを防ぎ、短命な不要トラックを除外できますが、正当な短いトラックを見逃す可能性があります。この値を下げる（例：1）と、すべてのトラックが即座に含まれ、完全性は最大化されますが、誤トラックが含まれる可能性があります。誤検出率に応じて調整してください。誤検出が多い場合は高め、検出が信頼できる場合は低めの値を使用します。                                                                                             | ✅  |
| `instances_cache_size`       | `int`   | インスタンスが新規か既出かを判定するために、インスタンスキャッシュに記憶しておくtrack IDの最大数です。正の整数である必要があります。既定値は16384です。キャッシュはFIFO（先入れ先出し）方式で置換されます。キャッシュがいっぱいになると、最も古いtrack IDが削除され、新しいもののための空きが作られます。この値を増やす（例：32768〜65536）と、見たことのあるtrack IDの履歴をより長く保持でき、長い間隔の後の再出現も検出しやすくなりますが、メモリをより多く使用します。この値を下げる（例：8192）とメモリ使用量は減りますが、以前に出現したtrack IDの履歴を失う可能性があり、再出現したオブジェクトが新規として分類されることがあります。動画の長さとオブジェクトの再出現パターンに応じて調整してください。長い動画や頻繁な再出現には高め、短い動画やまれな再出現には低めの値を使用します。 | ❌  |

この **参照** この列は、 `workflow` の実行時に利用可能な動的値でプロパティをパラメータ化できる可能性を示します。 *バインディング* の詳細を参照してください。

### 実行時互換性

`ソフト` - ランタイム `hosted_serverless`, `dedicated_deployment`; 実行 `リモート`; 入力 `動画` : このブロックは、動画ごとの状態をプロセスメモリ内に保持します（video\_metadata.video\_identifierでキー付け）。ステートレスまたは複数レプリカのHTTPランタイムでリモートステップ実行を行うと、連続したリクエストが異なるワーカープロセスで処理される可能性があるため、呼び出し間で状態がリセットされ、トラッキング／カウント／集計には出力が無意味になります。フレーム間で安定した結果を得るには、InferencePipeline内でローカルステップ実行を使用してください。

`ソフト` - 入力 `image` : このブロックは、動画または繰り返しフレームのワークフローからの時間的コンテキストに依存します。静止画像／写真では、追跡、比較、集計、可視化に意味のある履歴がないため、このブロックの利点はほとんど、またはまったくありません。

### 入力および出力バインディング

利用可能な接続は、そのバインディング種別に依存します。 `Byte Tracker` バージョン `v3` に、どのバインディング種別があるか確認してください。

<details>

<summary>入力と出力のバインディング</summary>

* input
  * `image` ([*`image`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/image.md)）：ByteTrackの初期化と追跡状態管理に必要な、動画メタデータ（fpsとvideo\_identifier）を埋め込んだ入力画像です。ブロックはWorkflowImageDataオブジェクトからvideo\_metadataを抽出します。fps値はトラッカーの設定に使用され、video\_identifierは異なる動画ごとに別々の追跡状態とインスタンスキャッシュを維持するために使用されます。fpsが欠けているか無効な場合、ブロックは0を既定値とし、警告を記録しますが、処理は継続します。複数の動画を処理する場合は、各動画のメタデータに一意のvideo\_identifierを含めて、追跡状態とキャッシュを分離してください。ブロックはvideo\_identifierを使用して、各動画のフレーム間で永続的なトラッカーとインスタンスキャッシュを維持します。
  * `detections` (*Union\[*[*`instance_segmentation_prediction`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/instance-segmentation-prediction.md)*,* [*`keypoint_detection_prediction`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/keypoint-detection-prediction.md)*,* [*`object_detection_prediction`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)*]*）：現在の動画フレームに対する、追跡対象の検出予測（オブジェクト検出、インスタンスセグメンテーション、またはキーポイント検出）です。ブロックはこれらの検出結果を既存トラックに関連付けるか、新しいトラックを作成します。オブジェクト検出、インスタンスセグメンテーション、キーポイント検出の予測をサポートします。一貫した追跡を維持するため、各フレームごとに順番に検出結果を提供してください。複数の検出バッチがある場合は、追跡前に統合されます。検出結果にはバウンディングボックスとクラス名（キーポイント検出の場合はキーポイントも）が含まれている必要があります。追跡後の出力には、track\_id情報が付加された同じ検出結果が含まれ、フレーム間で同じオブジェクトを識別できるようになります。
  * `track_activation_threshold` ([*`0から1の浮動小数`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/float-zero-to-one.md)）：検出結果から新しいトラックを有効化するための信頼度しきい値です。0.0〜1.0の範囲である必要があります。既定値は0.25です。このしきい値を超える信頼度を持つ検出結果のみが新しいトラックを作成できます。このしきい値を上げる（例：0.3〜0.5）と、高信頼度の検出結果のみからトラックを作成するため、追跡の精度と安定性が向上しますが、信頼度の低い正しい検出を見逃す可能性があります。このしきい値を下げる（例：0.15〜0.2）と、低信頼度の検出結果も受け入れるため追跡の完全性は向上しますが、誤検出によるノイズや不安定さが増すリスクがあります。検出モデルの性能に応じて調整してください。検出結果が信頼できる場合は低め、誤検出が多い場合は高めの値を使用します。
  * `lost_track_buffer` ([*`integer`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/integer.md)）：トラックが失われたとき（一致する検出結果がないとき）に、そのトラックを維持するフレーム数です。正の整数である必要があります。既定値は30フレームです。オブジェクトが一時的に消える場合（遮蔽、検出漏れ、またはフレーム外への移動による）、そのトラックは失われたとみなされる前にこのフレーム数だけ維持されます。この値を増やす（例：50〜100）と、遮蔽処理が強化され、短い検出ギャップによるトラックの断片化や消失が大幅に減りますが、メモリ使用量は増加します。この値を減らす（例：10〜20）とメモリ使用量は減りますが、短い遮蔽中にトラックが消える可能性があります。遮蔽の頻度に応じて調整してください。遮蔽が多い場合は高め、安定した追跡シナリオでは低めの値を使用します。
  * `minimum_matching_threshold` ([*`0から1の浮動小数`*](https://docs.roboflow.com/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` ([*`integer`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/integer.md)）：オブジェクトがトラックとして有効と判断され、出力される前に必要な連続フレーム数です。正の整数である必要があります。既定値は1です（すべてのトラックは即座に有効になります）。少なくともこの連続フレーム数だけ継続したトラックのみが出力に含まれます。この値を上げる（例：3〜5）と、誤検出や二重検出から偶発的に作成されたトラックを防ぎ、短命な不要トラックを除外できますが、正当な短いトラックを見逃す可能性があります。この値を下げる（例：1）と、すべてのトラックが即座に含まれ、完全性は最大化されますが、誤トラックが含まれる可能性があります。誤検出率に応じて調整してください。誤検出が多い場合は高め、検出が信頼できる場合は低めの値を使用します。
* output
  * `tracked_detections` ([`object_detection_prediction`](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)）：sv.Detections(...) オブジェクト形式の検出済みバウンディングボックスを含む予測。
  * `new_instances` ([`object_detection_prediction`](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)）：sv.Detections(...) オブジェクト形式の検出済みバウンディングボックスを含む予測。
  * `already_seen_instances` ([`object_detection_prediction`](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)）：sv.Detections(...) オブジェクト形式の検出済みバウンディングボックスを含む予測。

</details>

<details>

<summary>JSON定義の例</summary>

```json
{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/byte_tracker@v3",
	    "image": "<block_does_not_provide_example>",
	    "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": "<block_does_not_provide_example>"
	}
```

</details>

## v2

ByteTrackアルゴリズムを使用して動画フレーム間でオブジェクトを追跡し、一貫したオブジェクトIDを維持し、遮蔽や一時的な消失に対応し、検出結果を既存のトラックに関連付け、固有のトラックIDを割り当て、オブジェクトの行動分析、移動追跡、動画解析ワークフローを実現します。

## このブロックの仕組み

このブロックは、各フレームの検出結果を既存のトラックに関連付けて新しいオブジェクトには新規トラックを作成することで、連続する動画フレーム間でオブジェクト追跡を維持します。このブロックは：

1. 現在のフレームの検出予測と、動画メタデータを埋め込んだ画像を受け取ります
2. 画像から動画メタデータ（フレームレートと動画識別子を含む）を抽出します：
   * WorkflowImageData オブジェクトから video\_metadata にアクセスします
   * トラッカー設定用のfps（1秒あたりのフレーム数）を抽出します
   * video\_identifier を抽出して、異なる動画ごとに個別の追跡状態を維持します
   * fpsがない場合も適切に処理します（失敗する代わりに0を既定値とし、警告を記録します）
3. 動画用のByteTrackトラッカーを初期化または取得します：
   * 各一意の動画（video\_identifierで識別）ごとに新しいトラッカーインスタンスを作成します
   * フレーム間で追跡状態を維持するためにトラッカーをメモリに保存します
   * メタデータのフレームレートとユーザー指定のパラメータでトラッカーを設定します
   * 同じ動画の後続フレームでは既存のトラッカーを再利用します
4. 複数の検出バッチが提供されている場合、それらを統合します：
   * 複数のソースからの検出結果を1つの検出セットにまとめます
   * 一貫した追跡のため、すべての検出結果がまとめて処理されるようにします
5. ByteTrackアルゴリズムを使用してトラックを更新します：
   * **トラックの関連付け**：IoU（Intersection over Union）マッチングを使用して、現在フレームの検出結果を既存のトラックに対応付けます
   * **トラックの有効化**：既存のトラックに一致しない、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が含まれます
   * すべての元の検出プロパティ（バウンディングボックス、信頼度、クラス名）に加えて追跡情報を保持します

ByteTrackは、外観特徴を必要とせずにフレーム間で検出結果を関連付ける、検出ベース追跡を行う効率的なマルチオブジェクト追跡アルゴリズムです。2段階の関連付け戦略を使用し、まず高信頼度の検出結果をトラックに一致させ、その後低信頼度の検出結果を残りのトラックや失われたトラックに一致させます。このアルゴリズムは失われたトラック用のバッファを保持し、遮蔽や検出失敗によってオブジェクトが一時的に消えてもトラックを復元できるようにします。設定可能なパラメータにより追跡挙動を調整できます。track\_activation\_thresholdは新しいトラックを作成するタイミングを制御し（高いほど保守的）、lost\_track\_bufferは遮蔽処理を制御し（高いほど遮蔽復元が優れる）、minimum\_matching\_thresholdは関連付け品質を制御し（高いほど厳密なマッチング）、minimum\_consecutive\_framesは短命な誤トラックを除外します（高いほど誤トラックが少ない）。

## 一般的な使用例

* **動画解析**：行動分析や移動パターンのために動画フレーム間でオブジェクトを追跡します（例：動画内の人物の移動を追跡し、車両の経路を監視し、オブジェクトの軌跡を分析する）ことで、動画解析ワークフローを実現します
* **交通監視**：交通分析のために交通シーンで車両やオブジェクトを追跡します（例：フレーム間で車両を追跡し、車両の経路を監視し、一貫したIDで車両数を数える）ことで、交通監視ワークフローを実現します
* **監視システム**：セキュリティ監視のために動画フレーム間でオブジェクトIDを維持します（例：監視映像内の人物を追跡し、オブジェクトの移動を監視し、オブジェクトIDを維持する）ことで、監視追跡ワークフローを実現します
* **スポーツ分析**：スポーツ動画内の選手やオブジェクトを追跡してパフォーマンスを分析します（例：選手の動きを追跡し、選手の軌跡を分析し、ボールの位置を監視する）ことで、スポーツ分析ワークフローを実現します
* **小売分析**：動画フレーム間で顧客と商品を追跡して小売インサイトを得ます（例：顧客の経路を追跡し、購買行動を監視し、人流パターンを分析する）ことで、小売分析ワークフローを実現します
* **オブジェクト行動分析**：オブジェクトを追跡して、その行動や時間経過に伴う相互作用を分析します（例：オブジェクト間の相互作用を分析し、移動パターンを調べ、オブジェクト間の関係を追跡する）ことで、行動分析ワークフローを実現します

## 他のブロックへの接続

このブロックは動画メタデータと検出予測を含む画像を受け取り、track ID付きのtracked\_detectionsを出力します：

* **オブジェクト検出またはインスタンスセグメンテーションブロックの後** 動画フレーム間で検出されたオブジェクトを追跡するために使用します（例：動画内で検出オブジェクトを追跡し、検出結果にtrack IDを追加し、フレーム間でオブジェクトIDを維持する）ことで、検出から追跡へのワークフローを実現します
* **動画分析ブロックの前に** 一貫したオブジェクトIDを必要とする処理を行います（例：追跡済みオブジェクトの行動を分析し、オブジェクトの軌跡を処理し、追跡済みオブジェクトデータを扱う）ことで、追跡から分析へのワークフローを実現します
* **可視化ブロックの前** 一貫した色やラベルで追跡済みオブジェクトを表示します（例：追跡済みオブジェクトを可視化し、track IDを表示し、オブジェクトの経路を示す）ことで、追跡可視化ワークフローを実現します
* **ロジックブロックの前** Continue Ifのように、track情報に基づいて判断します（例：オブジェクトが追跡済みなら続行し、track IDに基づいてフィルタし、追跡データを使って判断する）ことで、追跡ベースの判断ワークフローを実現します
* **カウントまたは集計ブロックの前に** 追跡済みオブジェクトを正確に数えるために使用します（例：一意の追跡済みオブジェクトを数え、track統計を集計し、trackデータを処理する）ことで、追跡からカウントへのワークフローを実現します
* **ビデオ処理パイプラインで** オブジェクト追跡がより大きな動画解析ワークフローの一部である場合（例：動画パイプラインでオブジェクトを追跡し、処理チェーンでIDを維持し、動画分析を実現する）に使用します

## バージョンの違い

**v1 からの強化点：**

* **簡素化された入力**: `image` 埋め込みビデオメタデータを含む `メタデータ` 入力を使用し、別個の
* **fpsの適切な処理**：エラーを発生させる代わりに0を既定値とし警告を記録することで、欠落または無効なfps値を適切に処理し、不完全なメタデータに対してより堅牢にします
* **統合の改善**: 画像オブジェクトから直接ビデオメタデータにアクセスできるため、画像ベースのワークフローとの統合が向上し、別個のメタデータ入力を必要としません

## 要件

このブロックは、フレームレート（fps）と動画識別子情報を含む、埋め込まれた動画メタデータ付きの検出予測（オブジェクト検出またはインスタンスセグメンテーション）と画像を必要とします。画像のvideo\_metadataには、最適な追跡性能のために有効なfps値を含める必要がありますが、欠けていてもブロックはfps=0で継続します。このブロックは各動画ごとにフレーム間で追跡状態を維持するため、フレームを順次処理する動画ワークフローで使用してください。最適な追跡性能のため、検出結果はフレーム間で一貫して提供する必要があります。このアルゴリズムは安定した検出性能で最もよく機能し、lost\_track\_bufferメカニズムを通じて一時的な検出ギャップを処理します。

### タイプ識別子

ステップで次の識別子を使用してください `"type"` フィールド: `roboflow_core/byte_tracker@v2` を、ワークフローにステップとして追加します。

### プロパティ

| **名前**                       | **型**   | **説明**                                                                                                                                                                                                                                                                                                                                                                                               | 参照 |
| ---------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| `name`                       | `str`   | このステップの一意の識別子を入力してください。                                                                                                                                                                                                                                                                                                                                                                              | ❌  |
| `track_activation_threshold` | `float` | 検出結果から新しいトラックを有効化するための信頼度しきい値です。0.0〜1.0の範囲である必要があります。既定値は0.25です。このしきい値を超える信頼度を持つ検出結果のみが新しいトラックを作成できます。このしきい値を上げる（例：0.3〜0.5）と、高信頼度の検出結果のみからトラックを作成するため、追跡の精度と安定性が向上しますが、信頼度の低い正しい検出を見逃す可能性があります。このしきい値を下げる（例：0.15〜0.2）と、低信頼度の検出結果も受け入れるため追跡の完全性は向上しますが、誤検出によるノイズや不安定さが増すリスクがあります。検出モデルの性能に応じて調整してください。検出結果が信頼できる場合は低め、誤検出が多い場合は高めの値を使用します。                                                            | ✅  |
| `lost_track_buffer`          | `int`   | トラックが失われたとき（一致する検出結果がないとき）に、そのトラックを維持するフレーム数です。正の整数である必要があります。既定値は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` | `int`   | オブジェクトがトラックとして有効と判断され、出力される前に必要な連続フレーム数です。正の整数である必要があります。既定値は1です（すべてのトラックは即座に有効になります）。少なくともこの連続フレーム数だけ継続したトラックのみが出力に含まれます。この値を上げる（例：3〜5）と、誤検出や二重検出から偶発的に作成されたトラックを防ぎ、短命な不要トラックを除外できますが、正当な短いトラックを見逃す可能性があります。この値を下げる（例：1）と、すべてのトラックが即座に含まれ、完全性は最大化されますが、誤トラックが含まれる可能性があります。誤検出率に応じて調整してください。誤検出が多い場合は高め、検出が信頼できる場合は低めの値を使用します。                                                                       | ✅  |

この **参照** この列は、 `workflow` の実行時に利用可能な動的値でプロパティをパラメータ化できる可能性を示します。 *バインディング* の詳細を参照してください。

### 実行時互換性

`ソフト` - ランタイム `hosted_serverless`, `dedicated_deployment`; 実行 `リモート`; 入力 `動画` : このブロックは、動画ごとの状態をプロセスメモリ内に保持します（video\_metadata.video\_identifierでキー付け）。ステートレスまたは複数レプリカのHTTPランタイムでリモートステップ実行を行うと、連続したリクエストが異なるワーカープロセスで処理される可能性があるため、呼び出し間で状態がリセットされ、トラッキング／カウント／集計には出力が無意味になります。フレーム間で安定した結果を得るには、InferencePipeline内でローカルステップ実行を使用してください。

`ソフト` - 入力 `image` : このブロックは、動画または繰り返しフレームのワークフローからの時間的コンテキストに依存します。静止画像／写真では、追跡、比較、集計、可視化に意味のある履歴がないため、このブロックの利点はほとんど、またはまったくありません。

### 入力および出力バインディング

利用可能な接続は、そのバインディング種別に依存します。 `Byte Tracker` バージョン `v2` に、どのバインディング種別があるか確認してください。

<details>

<summary>入力と出力のバインディング</summary>

* input
  * `image` ([*`image`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/image.md)）：ByteTrackの初期化と追跡状態管理に必要な、動画メタデータ（fpsとvideo\_identifier）を埋め込んだ入力画像です。ブロックはWorkflowImageDataオブジェクトからvideo\_metadataを抽出します。fps値はトラッカーの設定に使用され、video\_identifierは異なる動画ごとに別々の追跡状態を維持するために使用されます。fpsが欠けているか無効な場合、ブロックは0を既定値とし、警告を記録しますが、処理は継続します。複数の動画を処理する場合は、各動画のメタデータに一意のvideo\_identifierを含めて、別々の追跡状態を維持してください。ブロックはvideo\_identifierを使用して、各動画のフレーム間で永続的なトラッカーを維持します。このバージョンでは、メタデータを別フィールドとして要求するのではなく、画像オブジェクトに埋め込むことで入力を簡略化しています。
  * `detections` (*Union\[*[*`instance_segmentation_prediction`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/instance-segmentation-prediction.md)*,* [*`object_detection_prediction`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)*]*）：現在の動画フレームに対する、追跡対象の検出予測（オブジェクト検出またはインスタンスセグメンテーション）です。ブロックはこれらの検出結果を既存トラックに関連付けるか、新しいトラックを作成します。フレーム間で一貫した追跡を維持するため、各フレームごとに順番に検出結果を提供してください。複数の検出バッチがある場合は、追跡前に統合されます。検出結果にはバウンディングボックスとクラス名を含める必要があります。追跡後の出力には、track\_id情報が付加された同じ検出結果が含まれ、フレーム間で同じオブジェクトを識別できるようになります。
  * `track_activation_threshold` ([*`0から1の浮動小数`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/float-zero-to-one.md)）：検出結果から新しいトラックを有効化するための信頼度しきい値です。0.0〜1.0の範囲である必要があります。既定値は0.25です。このしきい値を超える信頼度を持つ検出結果のみが新しいトラックを作成できます。このしきい値を上げる（例：0.3〜0.5）と、高信頼度の検出結果のみからトラックを作成するため、追跡の精度と安定性が向上しますが、信頼度の低い正しい検出を見逃す可能性があります。このしきい値を下げる（例：0.15〜0.2）と、低信頼度の検出結果も受け入れるため追跡の完全性は向上しますが、誤検出によるノイズや不安定さが増すリスクがあります。検出モデルの性能に応じて調整してください。検出結果が信頼できる場合は低め、誤検出が多い場合は高めの値を使用します。
  * `lost_track_buffer` ([*`integer`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/integer.md)）：トラックが失われたとき（一致する検出結果がないとき）に、そのトラックを維持するフレーム数です。正の整数である必要があります。既定値は30フレームです。オブジェクトが一時的に消える場合（遮蔽、検出漏れ、またはフレーム外への移動による）、そのトラックは失われたとみなされる前にこのフレーム数だけ維持されます。この値を増やす（例：50〜100）と、遮蔽処理が強化され、短い検出ギャップによるトラックの断片化や消失が大幅に減りますが、メモリ使用量は増加します。この値を減らす（例：10〜20）とメモリ使用量は減りますが、短い遮蔽中にトラックが消える可能性があります。遮蔽の頻度に応じて調整してください。遮蔽が多い場合は高め、安定した追跡シナリオでは低めの値を使用します。
  * `minimum_matching_threshold` ([*`0から1の浮動小数`*](https://docs.roboflow.com/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` ([*`integer`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/integer.md)）：オブジェクトがトラックとして有効と判断され、出力される前に必要な連続フレーム数です。正の整数である必要があります。既定値は1です（すべてのトラックは即座に有効になります）。少なくともこの連続フレーム数だけ継続したトラックのみが出力に含まれます。この値を上げる（例：3〜5）と、誤検出や二重検出から偶発的に作成されたトラックを防ぎ、短命な不要トラックを除外できますが、正当な短いトラックを見逃す可能性があります。この値を下げる（例：1）と、すべてのトラックが即座に含まれ、完全性は最大化されますが、誤トラックが含まれる可能性があります。誤検出率に応じて調整してください。誤検出が多い場合は高め、検出が信頼できる場合は低めの値を使用します。
* output
  * `tracked_detections` ([`object_detection_prediction`](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)）：sv.Detections(...) オブジェクト形式の検出済みバウンディングボックスを含む予測。

</details>

<details>

<summary>JSON定義の例</summary>

```json
{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/byte_tracker@v2",
	    "image": "<block_does_not_provide_example>",
	    "detections": "$steps.object_detection_model.predictions",
	    "track_activation_threshold": 0.25,
	    "lost_track_buffer": 30,
	    "minimum_matching_threshold": 0.8,
	    "minimum_consecutive_frames": 1
	}
```

</details>

## v1

ByteTrackアルゴリズムを使用して動画フレーム間でオブジェクトを追跡し、一貫したオブジェクトIDを維持し、遮蔽や一時的な消失に対応し、検出結果を既存のトラックに関連付け、固有のトラックIDを割り当て、オブジェクトの行動分析、移動追跡、動画解析ワークフローを実現します。

## このブロックの仕組み

このブロックは、各フレームの検出結果を既存のトラックに関連付けて新しいオブジェクトには新規トラックを作成することで、連続する動画フレーム間でオブジェクト追跡を維持します。このブロックは：

1. 現在のフレームの検出予測と動画メタデータ（フレームレートと動画識別子を含む）を受け取ります
2. 動画用のByteTrackトラッカーを初期化または取得します：
   * 各一意の動画（video\_identifierで識別）ごとに新しいトラッカーインスタンスを作成します
   * フレーム間で追跡状態を維持するためにトラッカーをメモリに保存します
   * メタデータのフレームレートとユーザー指定のパラメータでトラッカーを設定します
   * 同じ動画の後続フレームでは既存のトラッカーを再利用します
3. 複数の検出バッチが提供されている場合、それらを統合します：
   * 複数のソースからの検出結果を1つの検出セットにまとめます
   * 一貫した追跡のため、すべての検出結果がまとめて処理されるようにします
4. ByteTrackアルゴリズムを使用してトラックを更新します：
   * **トラックの関連付け**：IoU（Intersection over Union）マッチングを使用して、現在フレームの検出結果を既存のトラックに対応付けます
   * **トラックの有効化**：既存のトラックに一致しない、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が含まれます
   * すべての元の検出プロパティ（バウンディングボックス、信頼度、クラス名）に加えて追跡情報を保持します

ByteTrackは、外観特徴を必要とせずにフレーム間で検出結果を関連付ける、検出ベース追跡を行う効率的なマルチオブジェクト追跡アルゴリズムです。2段階の関連付け戦略を使用し、まず高信頼度の検出結果をトラックに一致させ、その後低信頼度の検出結果を残りのトラックや失われたトラックに一致させます。このアルゴリズムは失われたトラック用のバッファを保持し、遮蔽や検出失敗によってオブジェクトが一時的に消えてもトラックを復元できるようにします。設定可能なパラメータにより追跡挙動を調整できます。track\_activation\_thresholdは新しいトラックを作成するタイミングを制御し（高いほど保守的）、lost\_track\_bufferは遮蔽処理を制御し（高いほど遮蔽復元が優れる）、minimum\_matching\_thresholdは関連付け品質を制御し（高いほど厳密なマッチング）、minimum\_consecutive\_framesは短命な誤トラックを除外します（高いほど誤トラックが少ない）。

## 一般的な使用例

* **動画解析**：行動分析や移動パターンのために動画フレーム間でオブジェクトを追跡します（例：動画内の人物の移動を追跡し、車両の経路を監視し、オブジェクトの軌跡を分析する）ことで、動画解析ワークフローを実現します
* **交通監視**：交通分析のために交通シーンで車両やオブジェクトを追跡します（例：フレーム間で車両を追跡し、車両の経路を監視し、一貫したIDで車両数を数える）ことで、交通監視ワークフローを実現します
* **監視システム**：セキュリティ監視のために動画フレーム間でオブジェクトIDを維持します（例：監視映像内の人物を追跡し、オブジェクトの移動を監視し、オブジェクトIDを維持する）ことで、監視追跡ワークフローを実現します
* **スポーツ分析**：スポーツ動画内の選手やオブジェクトを追跡してパフォーマンスを分析します（例：選手の動きを追跡し、選手の軌跡を分析し、ボールの位置を監視する）ことで、スポーツ分析ワークフローを実現します
* **小売分析**：動画フレーム間で顧客と商品を追跡して小売インサイトを得ます（例：顧客の経路を追跡し、購買行動を監視し、人流パターンを分析する）ことで、小売分析ワークフローを実現します
* **オブジェクト行動分析**：オブジェクトを追跡して、その行動や時間経過に伴う相互作用を分析します（例：オブジェクト間の相互作用を分析し、移動パターンを調べ、オブジェクト間の関係を追跡する）ことで、行動分析ワークフローを実現します

## 他のブロックへの接続

このブロックは検出予測と動画メタデータを受け取り、track ID付きのtracked\_detectionsを出力します：

* **オブジェクト検出またはインスタンスセグメンテーションブロックの後** 動画フレーム間で検出されたオブジェクトを追跡するために使用します（例：動画内で検出オブジェクトを追跡し、検出結果にtrack IDを追加し、フレーム間でオブジェクトIDを維持する）ことで、検出から追跡へのワークフローを実現します
* **動画分析ブロックの前に** 一貫したオブジェクトIDを必要とする処理を行います（例：追跡済みオブジェクトの行動を分析し、オブジェクトの軌跡を処理し、追跡済みオブジェクトデータを扱う）ことで、追跡から分析へのワークフローを実現します
* **可視化ブロックの前** 一貫した色やラベルで追跡済みオブジェクトを表示します（例：追跡済みオブジェクトを可視化し、track IDを表示し、オブジェクトの経路を示す）ことで、追跡可視化ワークフローを実現します
* **ロジックブロックの前** Continue Ifのように、track情報に基づいて判断します（例：オブジェクトが追跡済みなら続行し、track IDに基づいてフィルタし、追跡データを使って判断する）ことで、追跡ベースの判断ワークフローを実現します
* **カウントまたは集計ブロックの前に** 追跡済みオブジェクトを正確に数えるために使用します（例：一意の追跡済みオブジェクトを数え、track統計を集計し、trackデータを処理する）ことで、追跡からカウントへのワークフローを実現します
* **ビデオ処理パイプラインで** オブジェクト追跡がより大きな動画解析ワークフローの一部である場合（例：動画パイプラインでオブジェクトを追跡し、処理チェーンでIDを維持し、動画分析を実現する）に使用します

## 要件

このブロックは、フレームレート（fps）情報を含む動画メタデータと、検出予測（オブジェクト検出またはインスタンスセグメンテーション）を必要とします。動画メタデータには、ByteTrackの初期化に有効なfps値を含める必要があります。このブロックは各動画ごとにフレーム間で追跡状態を維持するため、フレームを順次処理する動画ワークフローで使用してください。最適な追跡性能のため、検出結果はフレーム間で一貫して提供する必要があります。このアルゴリズムは安定した検出性能で最もよく機能し、lost\_track\_bufferメカニズムを通じて一時的な検出ギャップを処理します。

### タイプ識別子

ステップで次の識別子を使用してください `"type"` フィールド: `roboflow_core/byte_tracker@v1` を、ワークフローにステップとして追加します。

### プロパティ

| **名前**                       | **型**   | **説明**                                                                                                                                                                                                                                                                                                                                                                                               | 参照 |
| ---------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| `name`                       | `str`   | このステップの一意の識別子を入力してください。                                                                                                                                                                                                                                                                                                                                                                              | ❌  |
| `track_activation_threshold` | `float` | 検出結果から新しいトラックを有効化するための信頼度しきい値です。0.0〜1.0の範囲である必要があります。既定値は0.25です。このしきい値を超える信頼度を持つ検出結果のみが新しいトラックを作成できます。このしきい値を上げる（例：0.3〜0.5）と、高信頼度の検出結果のみからトラックを作成するため、追跡の精度と安定性が向上しますが、信頼度の低い正しい検出を見逃す可能性があります。このしきい値を下げる（例：0.15〜0.2）と、低信頼度の検出結果も受け入れるため追跡の完全性は向上しますが、誤検出によるノイズや不安定さが増すリスクがあります。検出モデルの性能に応じて調整してください。検出結果が信頼できる場合は低め、誤検出が多い場合は高めの値を使用します。                                                            | ✅  |
| `lost_track_buffer`          | `int`   | トラックが失われたとき（一致する検出結果がないとき）に、そのトラックを維持するフレーム数です。正の整数である必要があります。既定値は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` | `int`   | オブジェクトがトラックとして有効と判断され、出力される前に必要な連続フレーム数です。正の整数である必要があります。既定値は1です（すべてのトラックは即座に有効になります）。少なくともこの連続フレーム数だけ継続したトラックのみが出力に含まれます。この値を上げる（例：3〜5）と、誤検出や二重検出から偶発的に作成されたトラックを防ぎ、短命な不要トラックを除外できますが、正当な短いトラックを見逃す可能性があります。この値を下げる（例：1）と、すべてのトラックが即座に含まれ、完全性は最大化されますが、誤トラックが含まれる可能性があります。誤検出率に応じて調整してください。誤検出が多い場合は高め、検出が信頼できる場合は低めの値を使用します。                                                                       | ✅  |

この **参照** この列は、 `workflow` の実行時に利用可能な動的値でプロパティをパラメータ化できる可能性を示します。 *バインディング* の詳細を参照してください。

### 実行時互換性

`ソフト` - ランタイム `hosted_serverless`, `dedicated_deployment`; 実行 `リモート`; 入力 `動画` : このブロックは、動画ごとの状態をプロセスメモリ内に保持します（video\_metadata.video\_identifierでキー付け）。ステートレスまたは複数レプリカのHTTPランタイムでリモートステップ実行を行うと、連続したリクエストが異なるワーカープロセスで処理される可能性があるため、呼び出し間で状態がリセットされ、トラッキング／カウント／集計には出力が無意味になります。フレーム間で安定した結果を得るには、InferencePipeline内でローカルステップ実行を使用してください。

`ソフト` - 入力 `image` : このブロックは、動画または繰り返しフレームのワークフローからの時間的コンテキストに依存します。静止画像／写真では、追跡、比較、集計、可視化に意味のある履歴がないため、このブロックの利点はほとんど、またはまったくありません。

### 入力および出力バインディング

利用可能な接続は、そのバインディング種別に依存します。 `Byte Tracker` バージョン `v1` に、どのバインディング種別があるか確認してください。

<details>

<summary>入力と出力のバインディング</summary>

* input
  * `メタデータ` ([*`video_metadata`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/video-metadata.md)）：ByteTrackの初期化と追跡状態管理に必要な、フレームレート（fps）と動画識別子情報を含む動画メタデータです。fps値はトラッカーの設定に使用され、video\_identifierは異なる動画ごとに別々の追跡状態を維持するために使用されます。メタデータには有効なfps情報が含まれている必要があります。ByteTrackは初期化にフレームレートを必要とします。複数の動画を処理する場合は、各動画のメタデータに一意のvideo\_identifierを含めて、別々の追跡状態を維持してください。ブロックはvideo\_identifierを使用して、各動画のフレーム間で永続的なトラッカーを維持します。
  * `detections` (*Union\[*[*`instance_segmentation_prediction`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/instance-segmentation-prediction.md)*,* [*`object_detection_prediction`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)*]*）：現在の動画フレームに対する、追跡対象の検出予測（オブジェクト検出またはインスタンスセグメンテーション）です。ブロックはこれらの検出結果を既存トラックに関連付けるか、新しいトラックを作成します。フレーム間で一貫した追跡を維持するため、各フレームごとに順番に検出結果を提供してください。複数の検出バッチがある場合は、追跡前に統合されます。検出結果にはバウンディングボックスとクラス名を含める必要があります。追跡後の出力には、track\_id情報が付加された同じ検出結果が含まれ、フレーム間で同じオブジェクトを識別できるようになります。
  * `track_activation_threshold` ([*`0から1の浮動小数`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/float-zero-to-one.md)）：検出結果から新しいトラックを有効化するための信頼度しきい値です。0.0〜1.0の範囲である必要があります。既定値は0.25です。このしきい値を超える信頼度を持つ検出結果のみが新しいトラックを作成できます。このしきい値を上げる（例：0.3〜0.5）と、高信頼度の検出結果のみからトラックを作成するため、追跡の精度と安定性が向上しますが、信頼度の低い正しい検出を見逃す可能性があります。このしきい値を下げる（例：0.15〜0.2）と、低信頼度の検出結果も受け入れるため追跡の完全性は向上しますが、誤検出によるノイズや不安定さが増すリスクがあります。検出モデルの性能に応じて調整してください。検出結果が信頼できる場合は低め、誤検出が多い場合は高めの値を使用します。
  * `lost_track_buffer` ([*`integer`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/integer.md)）：トラックが失われたとき（一致する検出結果がないとき）に、そのトラックを維持するフレーム数です。正の整数である必要があります。既定値は30フレームです。オブジェクトが一時的に消える場合（遮蔽、検出漏れ、またはフレーム外への移動による）、そのトラックは失われたとみなされる前にこのフレーム数だけ維持されます。この値を増やす（例：50〜100）と、遮蔽処理が強化され、短い検出ギャップによるトラックの断片化や消失が大幅に減りますが、メモリ使用量は増加します。この値を減らす（例：10〜20）とメモリ使用量は減りますが、短い遮蔽中にトラックが消える可能性があります。遮蔽の頻度に応じて調整してください。遮蔽が多い場合は高め、安定した追跡シナリオでは低めの値を使用します。
  * `minimum_matching_threshold` ([*`0から1の浮動小数`*](https://docs.roboflow.com/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` ([*`integer`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/integer.md)）：オブジェクトがトラックとして有効と判断され、出力される前に必要な連続フレーム数です。正の整数である必要があります。既定値は1です（すべてのトラックは即座に有効になります）。少なくともこの連続フレーム数だけ継続したトラックのみが出力に含まれます。この値を上げる（例：3〜5）と、誤検出や二重検出から偶発的に作成されたトラックを防ぎ、短命な不要トラックを除外できますが、正当な短いトラックを見逃す可能性があります。この値を下げる（例：1）と、すべてのトラックが即座に含まれ、完全性は最大化されますが、誤トラックが含まれる可能性があります。誤検出率に応じて調整してください。誤検出が多い場合は高め、検出が信頼できる場合は低めの値を使用します。
* output
  * `tracked_detections` ([`object_detection_prediction`](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)）：sv.Detections(...) オブジェクト形式の検出済みバウンディングボックスを含む予測。

</details>

<details>

<summary>JSON定義の例</summary>

```json
{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/byte_tracker@v1",
	    "metadata": "<block_does_not_provide_example>",
	    "detections": "$steps.object_detection_model.predictions",
	    "track_activation_threshold": 0.25,
	    "lost_track_buffer": 30,
	    "minimum_matching_threshold": 0.8,
	    "minimum_consecutive_frames": 1
	}
```

</details>
