> 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/ptz-tracking-onvif.md).

# PTZトラッキング（ONVIF）

ONVIF互換のPTZカメラを制御して、物体を追従させます

ONVIF対応のPTZ（パン・チルト・ズーム）カメラを制御し、検出された物体を自動で追従し、プリセット位置へ移動し、PID制御を使用して監視、セキュリティ監視、自動カメラ制御ワークフロー向けに滑らかなトラッキングを維持します。

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

このブロックはONVIFプロトコルを通じてPTZカメラを制御し、リアルタイムで物体を自動的に追跡・追従します。このブロックは次のとおりです：

1. 上流のブロックから物体検出またはインスタンスセグメンテーションの予測を受け取ります
2. IPアドレス、ポート、ユーザー名、パスワードの認証情報を使用して、ONVIF対応のPTZカメラに接続します
3. 移動モード（追従またはプリセットへ移動）を決定します：

   **追従モードの場合：**

   * 追跡する対象オブジェクトを選択します。最も信頼度の高い検出結果、または（トラッカーIDがある場合は）特定の追跡中オブジェクトのいずれかです
   * オブジェクトのバウンディングボックス中心とフレーム中心を比較して位置誤差を計算します
   * PID（比例・積分・微分）制御を使用して、滑らかな移動コマンドを計算します：
     * 比例（Kp）：現在の位置誤差に応答します
     * 積分（Ki）：時間の経過とともに定常偏差を補正します
     * 微分（Kd）：将来の誤差を予測し、振動を抑えます
   * 移動コマンドをカメラの速度制限に合わせて正規化し、コマンドの過剰送信を防ぐためにレート制限を適用します
   * ONVIFのContinuousMoveサービス経由でカメラに連続移動コマンドを送信します
   * ハンチング動作を防ぐため、デッドゾーン（カメラが停止する中心周辺の領域）を監視します
   * 必要に応じて、オブジェクトが中央に来たときにズームインし、フレームを埋めるようズーム速度を調整します
   * トラッカーIDを使用して特定のオブジェクトの追跡を維持し、消えるか追跡がリセットされるまで続けます
   * オブジェクトが検出されない場合、設定可能なアイドル時間の後に自動でプリセット位置へ移動します

   **プリセットへ移動モードの場合：**

   * ONVIFのGotoPresetサービスを使用して、カメラを事前定義されたプリセット位置へ移動します
   * カメラがプリセット機能をサポートし、プリセットが設定されている必要があります
   * 設定で指定されたプリセット名を使用します
4. ワークフロー実行をブロックしないよう、別のイベントループを使用してカメラ通信を非同期に処理します
5. 探索状態、追跡中オブジェクトID、ズーム状態、移動履歴を含むカメラの状態を管理します
6. 2つの出力を返します：
   * **predictions**：追跡中の検出結果（追従しているオブジェクトがない場合は空）
   * **探索中**：カメラが現在移動中／オブジェクトを探索中かどうかを示すブール値

このブロックはPID制御を使用して、オブジェクト中心とフレーム中心の距離に基づく滑らかで比例的な移動コマンドを計算します。移動はカメラの最大速度に対する割合として正規化され、コマンドはレート制限されてカメラへの更新過多を防ぎます。デッドゾーンは、オブジェクトが中心付近にあるときの小さな移動を防ぎ、ハンチング動作を軽減します。ズームが有効な場合、カメラはまずパン／チルトでオブジェクトを中央に合わせ、その後、オブジェクトを視野に収めたままフレームを埋めるようズームインします。

## 一般的な使用例

* **監視とセキュリティ**：監視シナリオで人物や車両を自動追跡します（例：不審な活動を追跡、侵入者を追跡、セキュリティ境界を監視）。これにより自動監視ワークフローを実現します
* **スポーツとイベントの中継**：スポーツイベントや公演中に選手や対象物を追跡します（例：フィールド上の選手を追従、ボールの動きを追跡、イベントのアクションを撮影）。これにより自動スポーツ中継ワークフローを実現します
* **野生動物のモニタリング**：自然環境で動物や野生生物を追従します（例：鳥の動きを追跡、保護区の動物を追従、野生生物の行動を監視）。これにより野生生物観察ワークフローを実現します
* **産業監視**：工業環境でオブジェクトや要員を自動追跡します（例：設備の動きを追跡、作業者の活動を監視、施設内の車両を追従）。これにより産業自動化ワークフローを実現します
* **交通監視**：交通シナリオで車両や対象物を追跡します（例：交差点を通過する車両を追従、交通違反を追跡、道路の活動を監視）。これにより自動交通監視ワークフローを実現します
* **小売分析**：小売環境で顧客や商品を追跡します（例：顧客の動線を追従、商品のやり取りを追跡、購買行動を監視）。これにより小売分析ワークフローを実現します

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

このブロックは予測を受け取り、カメラ制御コマンドと追跡状態を出力します：

* **オブジェクト検出またはインスタンスセグメンテーションブロックの後** カメラで検出されたオブジェクトを追跡します（例：検出された人物を追従、検出された車両を追跡、検出されたオブジェクトを監視）。これにより検出からカメラ追跡へのワークフローを実現します
* **Byte Tracker ブロックの後** 一貫したIDを持つ特定の追跡対象を追従します（例：フレームをまたいで追跡中の人物を追従、特定の車両の追跡を維持、追跡対象オブジェクトを継続的に監視）。これにより追跡からカメラへのワークフローを実現します
* **検出フィルターブロックの後に** 特定のオブジェクトクラスまたはフィルタリングされた検出結果を追跡します（例：特定クラスのみを追跡、フィルタ済み検出を追従、選択したオブジェクトを監視）。これによりフィルタ済み追跡ワークフローを実現します
* **可視化ブロックの前** カメラの移動状態と追跡対象オブジェクトを表示します（例：追跡状態の可視化、探索インジケーターの表示、カメラ制御フィードバックの表示）。これによりカメラ制御可視化ワークフローを実現します
* **通知ブロックの前に** カメラが追跡を開始または停止したときに通知します（例：追跡開始時の通知、追跡喪失時の警告、カメラ状態の報告）。これによりカメラ状態通知ワークフローを実現します
* **監視およびモニタリングのパイプラインでは** 自動カメラ制御が、より大きなセキュリティまたは監視システムの一部となっている場合（例：自動セキュリティシステム、監視パイプライン、カメラ制御チェーン）。これにより包括的な監視ワークフローを実現します

## 要件

このブロックには、ネットワークアクセス可能なONVIF対応PTZカメラが必要です。カメラは、追従モード用のONVIF ContinuousMoveサービスと、プリセット移動用のGotoPresetサービスをサポートしている必要があります。最適な性能のためには、可変速度移動機能を持つカメラを使用してください。可変速度に対応していないカメラは simulate\_variable\_speed オプションを使用できますが、ぎこちない動きになる場合があります。このブロックは、ネットワーク経由でカメラに到達できるプロセスで実行する必要があるため、Roboflowホストのランタイムからは使用できません。オーバーシュートやハンチングを避けて滑らかな追跡を実現するために、PID調整を推奨します。カメラの応答性と動画遅延に応じて pid\_kp、pid\_ki、pid\_kd パラメータを調整してください。正確な追跡のために、カメラの動きと映像フィードバックの間の遅延を最小化する eager buffer consumption 戦略を使用してください。プリセット移動または自動リセット機能を使用する場合、カメラにはプリセットが設定されている必要があります。

### タイプ識別子

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

### プロパティ

| **名前**                                | **型**   | **説明**                                                                                                                                                                              | 参照 |
| ------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| `name`                                | `str`   | このステップの一意の識別子を入力してください。                                                                                                                                                             | ❌  |
| `camera_ip`                           | `str`   | ONVIF接続用のカメラのIPアドレスまたはホスト名。ワークフロー実行環境から到達可能である必要があります..                                                                                                                             | ✅  |
| `camera_port`                         | `int`   | カメラのONVIFサービスのポート（通常は80、8080、またはカメラ固有のポート）。カメラのONVIF設定と一致している必要があります..                                                                                                              | ✅  |
| `camera_username`                     | `str`   | ONVIF認証用のカメラユーザー名。カメラのPTZ制御権限を持っている必要があります..                                                                                                                                        | ✅  |
| `camera_password`                     | `str`   | ONVIF認証用のカメラパスワード。セキュリティのため、シークレットとして保存する必要があります..                                                                                                                                  | ✅  |
| `movement_type`                       | `str`   | カメラの移動モードです。'Follow' モードはPID制御を使用して検出されたオブジェクトを追跡します。'Go To Preset' モードはカメラを事前定義されたプリセット位置へ移動します（default\_position\_preset の設定が必要です）..                                              | ❌  |
| `simulate_variable_speed`             | `bool`  | ネイティブの可変速度サポートがないカメラ向けに、可変速度のシミュレーションを有効にします。有効にすると、100%速度のコマンドを送信し、その後停止コマンドを送って、パーセント速度を近似します。動きがぎこちなくなる場合があります - カメラに可変速度機能がない場合のみ使用してください..                                     | ✅  |
| `zoom_if_able`                        | `bool`  | 追跡中オブジェクトでフレームを埋めるための自動ズームを有効にします。有効にすると、カメラはまずパン／チルトでオブジェクトを中央に合わせ、その後、オブジェクトがフレームいっぱいになるまでズームインします。カメラがズーム機能をサポートしている必要があります..                                                    | ✅  |
| `follow_tracker`                      | `bool`  | トラッカーIDを使用した継続的な追跡を有効にします。有効にすると、カメラは最も信頼度の高い検出結果のトラッカーIDにロックし、その特定のオブジェクトが消えるか追跡がリセットされるまで追従し続けます。トラッカーIDを割り当てるには、ワークフロー内にByte Trackerブロックが必要です..                                  | ✅  |
| `dead_zone`                           | `int`   | フレーム中心の周囲でカメラの動きが停止するデッドゾーンのピクセルサイズ。オブジェクトが中心付近にあるときのハンチング動作を防ぎます。値を大きくするとパン／チルトのハンチングは減りますが、ズームのハンチングが発生する場合があります。値を小さくするとズームの安定性は向上しますが、パン／チルトの振動が発生する場合があります。一般的な範囲：30〜100ピクセル.. | ✅  |
| `default_position_preset`             | `str`   | デフォルト／ホーム位置のプリセット名です。カメラは、アイドル時間後（move\_to\_position\_after\_idle\_seconds が設定されている場合）または Go To Preset モード使用時にこのプリセットへ戻ります。カメラ上で設定されたプリセット名と正確に一致している必要があります。プリセット移動機能に必須です..       | ✅  |
| `move_to_position_after_idle_seconds` | `int`   | 自動リセットまでの秒数です。カメラがこの時間だけ探索／移動を停止した後、自動的に default\_position\_preset に移動します。自動リセットを無効にするには 0 に設定します。default\_position\_preset の設定が必要です..                                              | ✅  |
| `camera_update_rate_limit`            | `int`   | カメラの移動コマンド間の最小時間をミリ秒で指定します。ONVIF更新のレートを制限して、カメラへの負荷を抑えます。値を小さくすると追跡の応答性は向上しますが、低速なカメラでは過負荷になる場合があります。値を大きくするとカメラ負荷は減りますが、動きが滑らかでなくなる場合があります。一般的な範囲：100〜500ms..                      | ✅  |
| `flip_x_movement`                     | `bool`  | 水平（パン）移動方向を反転します。カメラ映像が水平方向にミラー表示され、動きが逆に見える場合に有効にします。画像が反転しているときのカメラ移動を補正するために使用します..                                                                                              | ✅  |
| `flip_y_movement`                     | `bool`  | 垂直（チルト）移動方向を反転します。多くのカメラではY軸が反転しているため、既定で有効になっています。垂直移動が逆に見える場合は無効にしてください..                                                                                                         | ✅  |
| `minimum_camera_speed`                | `float` | 最小移動速度を割合（0.0〜1.0）で指定します。このしきい値を下回る移動コマンドは、この最小値まで引き上げられます。一部のカメラは非常に低い速度を無視します。カメラが小さな動きに反応しない場合は値を上げてください。一般的な範囲：0.02〜0.1（2%〜10%）..                                               | ✅  |
| `pid_kp`                              | `float` | PID比例ゲイン（Kp）。位置誤差への応答を制御します。値を大きくするとカメラの反応は速くなりますが、オーバーシュートやハンチングの原因になる場合があります。値を小さくするとハンチングは減りますが、追跡は遅くなります。既定値から始め、カメラの応答性に応じて調整してください。一般的な範囲：0.1〜0.5..                           | ✅  |
| `pid_ki`                              | `float` | PID積分ゲイン（Ki）。時間の経過とともに誤差を蓄積することで定常偏差を解消します。通常は振動の原因になるため0に保ちます。小さな誤差があるにもかかわらずカメラが常に少し中心から外れて停止する場合は、少しだけ（0.01〜0.1）上げてください..                                                        | ✅  |
| `pid_kd`                              | `float` | PID微分ゲイン（Kd）。将来の誤差を予測し、振動を抑えます。値を大きくすると映像遅延がある場合の安定性が向上しますが、過度に大きいとハンチングの原因になる場合があります。カメラの動きと映像フィードバックの間に大きな遅延がある場合は、値を上げてください（1〜5）。追跡がぎこちなく見える場合は下げてください..                         | ✅  |

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

### 実行時互換性

`ハード` - ランタイム `hosted_serverless`, `dedicated_deployment` ：このブロックにはPTZカメラへのLANアクセスが必要です。ホスト型ServerlessおよびRoboflow Dedicated Deploymentはお客様のLANに到達できません。

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

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

<details>

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

* input
  * `predictions` (*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)*]*）：追跡する物体検出またはインスタンスセグメンテーションの予測。Follow モードでは、ブロックは最も信頼度の高い予測、またはトラッカーIDがある場合は追跡中のオブジェクトを追従します。予測にはバウンディングボックス座標を含める必要があり、永続的な追跡のためにトラッカーIDを含めることもできます..
  * `camera_ip` ([*`string`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/string.md)）：ONVIF接続用のカメラのIPアドレスまたはホスト名。ワークフロー実行環境から到達可能である必要があります..
  * `camera_port` ([*`integer`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/integer.md)）：カメラのONVIFサービスのポート（通常は80、8080、またはカメラ固有のポート）。カメラのONVIF設定と一致している必要があります..
  * `camera_username` ([*`string`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/string.md)）：ONVIF認証用のカメラユーザー名。カメラのPTZ制御権限を持っている必要があります..
  * `camera_password` ([*`secret`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/secret.md)）：ONVIF認証用のカメラパスワード。セキュリティのため、シークレットとして保存する必要があります..
  * `simulate_variable_speed` ([*`boolean`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/boolean.md)）：ネイティブの可変速度サポートがないカメラ向けに、可変速度のシミュレーションを有効にします。有効にすると、100%速度のコマンドを送信し、その後停止コマンドを送って、パーセント速度を近似します。動きがぎこちなくなる場合があります - カメラに可変速度機能がない場合のみ使用してください..
  * `zoom_if_able` ([*`boolean`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/boolean.md)）：追跡中オブジェクトでフレームを埋めるための自動ズームを有効にします。有効にすると、カメラはまずパン／チルトでオブジェクトを中央に合わせ、その後、オブジェクトがフレームいっぱいになるまでズームインします。カメラがズーム機能をサポートしている必要があります..
  * `follow_tracker` ([*`boolean`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/boolean.md)）：トラッカーIDを使用した継続的な追跡を有効にします。有効にすると、カメラは最も信頼度の高い検出結果のトラッカーIDにロックし、その特定のオブジェクトが消えるか追跡がリセットされるまで追従し続けます。トラッカーIDを割り当てるには、ワークフロー内にByte Trackerブロックが必要です..
  * `dead_zone` ([*`integer`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/integer.md)）：フレーム中心の周囲でカメラの動きが停止するデッドゾーンのピクセルサイズ。オブジェクトが中心付近にあるときのハンチング動作を防ぎます。値を大きくするとパン／チルトのハンチングは減りますが、ズームのハンチングが発生する場合があります。値を小さくするとズームの安定性は向上しますが、パン／チルトの振動が発生する場合があります。一般的な範囲：30〜100ピクセル..
  * `default_position_preset` ([*`string`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/string.md)）：デフォルト／ホーム位置のプリセット名です。カメラは、アイドル時間後（move\_to\_position\_after\_idle\_seconds が設定されている場合）または Go To Preset モード使用時にこのプリセットへ戻ります。カメラ上で設定されたプリセット名と正確に一致している必要があります。プリセット移動機能に必須です..
  * `move_to_position_after_idle_seconds` ([*`integer`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/integer.md)）：自動リセットまでの秒数です。カメラがこの時間だけ探索／移動を停止した後、自動的に default\_position\_preset に移動します。自動リセットを無効にするには 0 に設定します。default\_position\_preset の設定が必要です..
  * `camera_update_rate_limit` ([*`integer`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/integer.md)）：カメラの移動コマンド間の最小時間をミリ秒で指定します。ONVIF更新のレートを制限して、カメラへの負荷を抑えます。値を小さくすると追跡の応答性は向上しますが、低速なカメラでは過負荷になる場合があります。値を大きくするとカメラ負荷は減りますが、動きが滑らかでなくなる場合があります。一般的な範囲：100〜500ms..
  * `flip_x_movement` ([*`boolean`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/boolean.md)）：水平（パン）移動方向を反転します。カメラ映像が水平方向にミラー表示され、動きが逆に見える場合に有効にします。画像が反転しているときのカメラ移動を補正するために使用します..
  * `flip_y_movement` ([*`boolean`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/boolean.md)）：垂直（チルト）移動方向を反転します。多くのカメラではY軸が反転しているため、既定で有効になっています。垂直移動が逆に見える場合は無効にしてください..
  * `minimum_camera_speed` ([*`0から1の浮動小数`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/float-zero-to-one.md)）：最小移動速度を割合（0.0〜1.0）で指定します。このしきい値を下回る移動コマンドは、この最小値まで引き上げられます。一部のカメラは非常に低い速度を無視します。カメラが小さな動きに反応しない場合は値を上げてください。一般的な範囲：0.02〜0.1（2%〜10%）..
  * `pid_kp` ([*`float`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/float.md)）：PID比例ゲイン（Kp）。位置誤差への応答を制御します。値を大きくするとカメラの反応は速くなりますが、オーバーシュートやハンチングの原因になる場合があります。値を小さくするとハンチングは減りますが、追跡は遅くなります。既定値から始め、カメラの応答性に応じて調整してください。一般的な範囲：0.1〜0.5..
  * `pid_ki` ([*`float`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/float.md)）：PID積分ゲイン（Ki）。時間の経過とともに誤差を蓄積することで定常偏差を解消します。通常は振動の原因になるため0に保ちます。小さな誤差があるにもかかわらずカメラが常に少し中心から外れて停止する場合は、少しだけ（0.01〜0.1）上げてください..
  * `pid_kd` ([*`float`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/float.md)）：PID微分ゲイン（Kd）。将来の誤差を予測し、振動を抑えます。値を大きくすると映像遅延がある場合の安定性が向上しますが、過度に大きいとハンチングの原因になる場合があります。カメラの動きと映像フィードバックの間に大きな遅延がある場合は、値を上げてください（1〜5）。追跡がぎこちなく見える場合は下げてください..
* output
  * `predictions` ([`object_detection_prediction`](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)）：sv.Detections(...) オブジェクト形式の検出済みバウンディングボックスを含む予測。
  * `探索中` ([`boolean`](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/boolean.md)): ブールフラグ。

</details>

<details>

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

```json
{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/onvif_sink@v1",
	    "predictions": "$steps.object_detection_model.predictions",
	    "camera_ip": "<block_does_not_provide_example>",
	    "camera_port": "<block_does_not_provide_example>",
	    "camera_username": "<block_does_not_provide_example>",
	    "camera_password": "<block_does_not_provide_example>",
	    "movement_type": "Follow",
	    "simulate_variable_speed": true,
	    "zoom_if_able": true,
	    "follow_tracker": true,
	    "dead_zone": 50,
	    "default_position_preset": "",
	    "move_to_position_after_idle_seconds": "<block_does_not_provide_example>",
	    "camera_update_rate_limit": "<block_does_not_provide_example>",
	    "flip_x_movement": true,
	    "flip_y_movement": true,
	    "minimum_camera_speed": "<block_does_not_provide_example>",
	    "pid_kp": "<block_does_not_provide_example>",
	    "pid_ki": "<block_does_not_provide_example>",
	    "pid_kd": "<block_does_not_provide_example>"
	}
```

</details>
