> 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/visualize-predictions/trace-visualization.md).

# トレース可視化

検出の追跡結果に基づいてトレースを描画します。

追跡されたオブジェクトの軌跡パスを描画し、最近の位置を色付きの線で結んで移動履歴を可視化し、オブジェクトの移動パターン、経路、追跡挙動を時間の経過とともに示します。

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

このブロックは画像と追跡済み予測（トラッカーID付き）を受け取り、各追跡オブジェクトの最近の移動履歴を示す軌跡パスを描画します。このブロックは、

1. 画像と追跡済み予測を入力として受け取ります（予測には追跡ブロックからの tracker\_id データが含まれている必要があります）
2. 各追跡オブジェクトの追跡IDと位置履歴を抽出します
3. 選択した位置アンカー（中心、角、辺、または重心）に基づいて、トレースを描画する基準点を決定します
4. 選択したカラーパレットに基づいて色を適用し、クラス、インデックス、またはトラックIDごとに色を割り当てます
5. Supervision の TraceAnnotator を使用して、各追跡オブジェクトについて最近の位置（最大 trace\_length 個の位置）を結ぶ軌跡線を描画します
6. 履歴位置を順番に結び、オブジェクトの移動方向とパターンを示す経路トレースを作成します
7. 元の画像に軌跡パスを重ねた注釈付き画像を返します

このブロックは、各追跡オブジェクトが最近のフレームでたどった経路を描画することで、オブジェクト追跡を可視化します。各追跡オブジェクトには固有のトレース線（トラックID、クラス、またはインデックスで色分け）が割り当てられ、最近の位置を結んで、移動方向、速度、軌跡パターンを示す視覚的な軌跡を作成します。trace\_length パラメータは、各トレースに含める履歴位置の数を制御します（値が大きいほどより多くの移動履歴を表示し、値が小さいほど最近の移動のみを表示します）。この可視化には、フレーム間で位置を結ぶために追跡情報が必要なため、Byte Tracker などの追跡ブロックからの tracker ID を含む予測が必要です。これらのトレースは、オブジェクトの移動を可視化し、追跡パターンを特定し、時間の経過に伴うオブジェクトの挙動を理解するのに役立ちます。

## 一般的な使用例

* **オブジェクト軌跡の可視化**: 物体の挙動、移動パターン、または車両追跡、歩行者流量分析、物体移動監視などの用途で、追跡されたオブジェクトの移動経路と軌跡を可視化して理解します
* **追跡性能の検証**: オブジェクトの経路を可視化して追跡の一貫性を確認し、追跡エラーやID切り替わりを特定し、オブジェクトが一貫した軌跡を維持しているかを検証します
* **移動パターン分析**: 軌跡トレースを可視化して移動パターン、速度、方向変化を分析し、監視、セキュリティ、交通監視ワークフローにおけるオブジェクトの挙動を理解したり、異常を検出したり、移動傾向を特定したりします
* **経路逸脱の検出**: オブジェクトの経路を可視化して、想定ルートからの逸脱を検出し、異常な移動パターンを特定し、安全、セキュリティ、またはコンプライアンスのワークフローでオブジェクトの軌跡を監視します
* **リアルタイム追跡監視**: リアルタイム監視インターフェース、ダッシュボード、またはライブ映像フィードに軌跡トレースを表示し、オブジェクトの移動と追跡挙動をその場で可視化します
* **動画解析と後処理**: 動画解析、後処理ワークフロー、または法科学分析のために軌跡可視化を作成し、オブジェクトの移動経路とパターンの理解が重要な場面で活用します

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

このブロックの注釈付き画像は次に接続できます：

* **追跡ブロック** (例: Byte Tracker) は、トレース可視化に必要なトラッカーID付きの追跡済み予測を受け取るためのものです
* **他の可視化ブロック** (例: Bounding Box Visualization、Label Visualization、Dot Visualization) は、軌跡トレースと追加の注釈を組み合わせて包括的な追跡可視化を行うためのものです
* **データ保存ブロック** (例: Local File Sink、CSV Formatter、Roboflow Dataset Upload) は、記録、レポート、または分析のために軌跡トレース付きの画像を保存するためのものです
* **Webhook ブロック** 軌跡トレースを含む可視化結果を外部システム、API、または Web アプリケーションへ送信し、ダッシュボードや監視ツールに表示するためのものです
* **通知ブロック** (例: Email Notification、Slack Notification) は、警告やレポートの視覚的証拠として、軌跡トレース付きの注釈画像を送信するためのものです
* **動画出力ブロック** ライブ監視、追跡可視化、または後処理分析のために、軌跡トレース付きの注釈付き動画ストリームや録画を作成するためのものです

### タイプ識別子

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

### プロパティ

| **名前**          | **型**       | **説明**                                                                                                                                                                                                                                                  | 参照 |
| --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| `name`          | `str`       | このステップの一意の識別子を入力してください。                                                                                                                                                                                                                                 | ❌  |
| `copy_image`    | `bool`      | このオプションを有効にすると、可視化用に入力画像のコピーを作成し、元画像を保持します。複数の可視化を重ねる場合に使用してください..                                                                                                                                                                                      | ✅  |
| `color_palette` | `str`       | 可視化要素のカラーパレットを選択します..                                                                                                                                                                                                                                   | ✅  |
| `palette_size`  | `int`       | パレット内の色数を指定します。カスタムまたは Matplotlib のパレットを使用する場合に適用されます..                                                                                                                                                                                                 | ✅  |
| `custom_colors` | `List[str]` | HEX形式でバウンディングボックス用のカスタムカラーのリストを定義します..                                                                                                                                                                                                                  | ✅  |
| `color_axis`    | `str`       | バウンディングボックスの色をどのように割り当てるかを選択します。負のクラスまたはトラッカーIDを持つ検出結果（たとえば、class\_id = -1 の未一致 VLM ラベル）は、中立的なグレーで描画されます..                                                                                                                                              | ✅  |
| `位置`            | `str`       | 各検出のバウンディングボックスに対する軌跡トレースの描画基準となるアンカー位置。CENTER（ボックスの中心）、角（TOP\_LEFT、TOP\_RIGHT、BOTTOM\_LEFT、BOTTOM\_RIGHT）、辺の中点（TOP\_CENTER、CENTER\_LEFT、CENTER\_RIGHT、BOTTOM\_CENTER）、または CENTER\_OF\_MASS（物体の重心）を選択できます。トレースパスは、最近のフレームにわたってこのアンカーポイントでの位置を結んで描画されます。 | ✅  |
| `trace_length`  | `int`       | 各軌跡トレースに含める、履歴のある追跡オブジェクト位置の最大数。移動の軌跡がどれだけ長く表示されるかを制御します。値が大きいほど、より長いトレースになり、より多くの移動履歴を表示します。値が小さいほど、短いトレースになり、最近の移動のみを表示します。1以上である必要があります。典型的な値は、希望する軌跡の長さとフレームレートに応じて 10〜50 フレームの範囲です。                                                                | ✅  |
| `thickness`     | `int`       | ピクセル単位の軌跡トレース線の太さ。経路線がどれだけ太く表示されるかを制御します。値が大きいほど太く、より目立つトレースになり、値が小さいほど細く、控えめなトレースになります。1以上である必要があります。典型的な値は 1〜5 ピクセルです。                                                                                                                                | ✅  |

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

### 実行時互換性

`ソフト` - ランタイム `hosted_serverless`, `dedicated_deployment`; 実行 `リモート`; 入力 `動画` : 軌跡履歴は、プロセスメモリ内のキャッシュされた TraceAnnotator に保存されます。ステートレスまたはマルチレプリカの HTTP ランタイムでリモートステップ実行を行うと、連続するフレームが別のワーカープロセスによって処理される可能性があるため、トレースがリセットされたり、ワーカー間で分断されたりします。安定したフレーム間可視化には、InferencePipeline でローカルステップ実行を使用してください。

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

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

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

<details>

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

* input
  * `image` ([*`image`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/image.md)）：可視化する画像..
  * `copy_image` ([*`boolean`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/boolean.md)）：このオプションを有効にすると、可視化用に入力画像のコピーを作成し、元画像を保持します。複数の可視化を重ねる場合に使用してください..
  * `predictions` (*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)*,* [*`rle_instance_segmentation_prediction`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/rle-instance-segmentation-prediction.md)*]*): 可視化するモデル予測..
  * `color_palette` ([*`string`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/string.md)）：可視化要素のカラーパレットを選択します..
  * `palette_size` ([*`integer`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/integer.md)）：パレット内の色数を指定します。カスタムまたは Matplotlib のパレットを使用する場合に適用されます..
  * `custom_colors` ([*`list_of_values`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/list-of-values.md)）：HEX形式でバウンディングボックス用のカスタムカラーのリストを定義します..
  * `color_axis` ([*`string`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/string.md)）：バウンディングボックスの色をどのように割り当てるかを選択します。負のクラスまたはトラッカーIDを持つ検出結果（たとえば、class\_id = -1 の未一致 VLM ラベル）は、中立的なグレーで描画されます..
  * `位置` ([*`string`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/string.md)): 各検出のバウンディングボックスに対する軌跡トレースの描画基準となるアンカー位置。CENTER（ボックスの中心）、角（TOP\_LEFT、TOP\_RIGHT、BOTTOM\_LEFT、BOTTOM\_RIGHT）、辺の中点（TOP\_CENTER、CENTER\_LEFT、CENTER\_RIGHT、BOTTOM\_CENTER）、または CENTER\_OF\_MASS（物体の重心）を選択できます。トレースパスは、最近のフレームにわたってこのアンカーポイントでの位置を結んで描画されます。
  * `trace_length` ([*`integer`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/integer.md)): 各軌跡トレースに含める、履歴のある追跡オブジェクト位置の最大数。移動の軌跡がどれだけ長く表示されるかを制御します。値が大きいほど、より長いトレースになり、より多くの移動履歴を表示します。値が小さいほど、短いトレースになり、最近の移動のみを表示します。1以上である必要があります。典型的な値は、希望する軌跡の長さとフレームレートに応じて 10〜50 フレームの範囲です。
  * `thickness` ([*`integer`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/integer.md)): ピクセル単位の軌跡トレース線の太さ。経路線がどれだけ太く表示されるかを制御します。値が大きいほど太く、より目立つトレースになり、値が小さいほど細く、控えめなトレースになります。1以上である必要があります。典型的な値は 1〜5 ピクセルです。
* output
  * `image` ([`image`](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/image.md)）：ワークフロー内の画像。

</details>

<details>

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

```json
{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/trace_visualization@v1",
	    "image": "$inputs.image",
	    "copy_image": true,
	    "predictions": "$steps.object_detection_model.predictions",
	    "color_palette": "DEFAULT",
	    "palette_size": 10,
	    "custom_colors": [
	        "#FF0000",
	        "#00FF00",
	        "#0000FF"
	    ],
	    "color_axis": "CLASS",
	    "position": "CENTER",
	    "trace_length": 30,
	    "thickness": 1
	}
```

</details>
