> 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-trackingonvif.md).
# PTZ 追跡（ONVIF）
検出されたオブジェクトを自動追従し、プリセット位置へ移動し、PID制御を使って滑らかな追跡を維持するために、ONVIF対応のPTZ（パン・チルト・ズーム）カメラを制御します。監視、セキュリティ監視、自動カメラ制御ワークフロー向けです。
## このブロックの仕組み
このブロックは、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 オプションを使用できますが、動きがぎこちなくなる場合があります。このブロックはローカル実行モードで実行する必要があります（リモート／クラウド実行には適していません）。滑らかで、オーバーシュートやハンチングのない追跡を実現するにはPID調整を推奨します。camera の応答性と動画遅延に応じて pid\_kp、pid\_ki、pid\_kd パラメータを調整してください。正確な追跡のために、カメラの動きと映像フィードバックの間の遅延を最小限にする積極的なバッファ消費戦略を使用してください。プリセット移動または自動リセット機能を使用する場合は、カメラにプリセットが設定されている必要があります。
### 種別識別子
ステップで次の識別子を使用します `"type"` フィールド: `roboflow_core/onvif_sink@v1` ワークフローにステップとしてブロックを追加するには。
### プロパティ
| **名前** | **型** | **説明** | 参照 |
| -------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| `name` | `str` | このステップの一意の識別子を入力してください。 | ❌ |
| `カメラIPアドレス` | `str` | ONVIF接続用のカメラIPアドレスまたはホスト名。ワークフローの実行環境から到達可能である必要があります。 | ✅ |
| `カメラポート` | `int` | カメラのONVIFサービスのポート（通常は80、8080、またはカメラ固有のポート）。カメラのONVIF設定と一致している必要があります。 | ✅ |
| `カメラユーザー名` | `str` | ONVIF認証用のカメラユーザー名。カメラ上でPTZ制御権限を持っている必要があります。 | ✅ |
| `カメラパスワード` | `str` | ONVIF認証用のカメラパスワード。セキュリティのためシークレットとして保存してください。 | ✅ |
| `移動モード` | `str` | カメラの移動モードです。'Follow' モードはPID制御を使って検出されたオブジェクトを追跡します。'Go To Preset' モードはカメラをあらかじめ定義されたプリセット位置へ移動します（default\_position\_preset の設定が必要です）。 | ❌ |
| `可変速度シミュレーション` | `bool` | ネイティブの可変速度に対応していないカメラ向けに、可変速度シミュレーションを有効にします。有効にすると、100%速度のコマンドに続けて停止コマンドを送信し、割合速度を近似します。動きがぎこちなくなる場合があります。カメラに可変速度機能がない場合にのみ使用してください。 | ✅ |
| `ズーム可能なら` | `bool` | 追跡中のオブジェクトでフレームを埋めるための自動ズームを有効にします。有効にすると、カメラはまずパン／チルトでオブジェクトを中央に合わせ、その後、オブジェクトがフレームいっぱいになるまでズームインします。カメラがズーム機能をサポートしている必要があります。 | ✅ |
| `トラッカー追従` | `bool` | トラッカーIDを使用した永続的な追跡を有効にします。有効にすると、カメラは最も信頼度の高い検出結果のトラッカーIDにロックし、その特定のオブジェクトが消えるか追跡がリセットされるまで追跡を続けます。ワークフロー内にトラッカーIDを割り当てる Byte Tracker ブロックが必要です。 | ✅ |
| `デッドゾーン` | `int` | フレーム中心の周囲でカメラの動きが停止するピクセル単位のデッドゾーンサイズです。オブジェクトが中心付近にあるときのハンチング動作を防ぎます。値を大きくするとパン／チルトのハンチングは減りますが、ズームのハンチングが発生する場合があります。値を小さくするとズームの安定性は向上しますが、パン／チルトの振動が発生する場合があります。一般的な範囲：30～100ピクセル。 | ✅ |
| `デフォルト位置プリセット` | `str` | デフォルト／ホーム位置のプリセット名です。カメラは、アイドル期間後（move\_to\_position\_after\_idle\_seconds が設定されている場合）または Go To Preset モード使用時に、このプリセットへ戻ります。カメラで設定されたプリセット名と完全に一致している必要があります。プリセット移動機能に必須です。 | ✅ |
| `アイドル後の自動移動` | `int` | 自動リセット時間（秒）。カメラがこの時間、探索／移動を停止した後、自動的に default\_position\_preset に移動します。自動リセットを無効にするには 0 に設定します。default\_position\_preset の設定が必要です。 | ✅ |
| `カメラ更新レート制限` | `int` | カメラの移動コマンド間の最小時間（ミリ秒）。ONVIF更新をレート制限して、カメラに負荷をかけすぎないようにします。低い値は追跡応答性を高めますが、遅いカメラでは過負荷になる場合があります。高い値はカメラ負荷を減らしますが、動きが滑らかでなくなることがあります。一般的な範囲：100～500ms。 | ✅ |
| `X方向移動反転` | `bool` | 水平（パン）方向の移動を反転します。カメラ映像が水平にミラー表示され、動きが逆に見える場合に有効にしてください。映像が反転しているときのカメラ移動の補正に使用します。 | ✅ |
| `Y方向移動反転` | `bool` | 垂直（チルト）方向の移動を反転します。多くのカメラではY軸が反転しているため、既定で有効になっています。垂直移動が逆に見える場合は無効にしてください。 | ✅ |
| `最小カメラスピード` | `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）増やしてください。追跡がぎこちなく見える場合は減らしてください。 | ✅ |
この **参照** 列は、で利用可能な動的値を使用してプロパティをパラメータ化できる可能性を示します `ワークフロー` 実行時。参照 *バインディング* 詳細情報
### ランタイム互換性
`ハード` - 実行 `リモート` ：step\_execution\_mode=local が必要です。それ以外の場合は ValueError を送出します。ONVIFコマンドは、ワークフローを駆動するのと同じプロセスから発行する必要があります。
`ハード` - ランタイム `ホステッド・サーバーレス`, `専用デプロイ` ：PTZカメラへのLANアクセスが必要です。Hosted Serverless と Roboflow Dedicated Deployments では、顧客のLANに到達できません。
### 入出力バインディング
利用可能な接続は、そのバインディング種別によって異なります。どのバインディング種別が `PTZトラッキング（ONVIF）` のバージョン `v1` 持つか確認してください。
入出力バインディング
* 入力
* `predictions` (*Union\[*[*`instance_segmentation_prediction`*](/workflows/ja/gaido/developer-guide/kinds/instance-segmentation-prediction.md)*,* [*`object_detection_prediction`*](/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)*]*）：追跡対象となる物体検出またはインスタンスセグメンテーションの予測。Follow モードでは、トラッカーIDがある場合は追跡済みのオブジェクト、なければ信頼度が最も高い予測を追従します。予測にはバウンディングボックス座標を含め、永続追跡のために必要に応じてトラッカーIDを含めてください。
* `カメラIPアドレス` ([*`string`*](/workflows/ja/gaido/developer-guide/kinds/string.md)）：ONVIF接続用のカメラIPアドレスまたはホスト名。ワークフローの実行環境から到達可能である必要があります。
* `カメラポート` ([*`integer`*](/workflows/ja/gaido/developer-guide/kinds/integer.md)）：カメラのONVIFサービスのポート（通常は80、8080、またはカメラ固有のポート）。カメラのONVIF設定と一致している必要があります。
* `カメラユーザー名` ([*`string`*](/workflows/ja/gaido/developer-guide/kinds/string.md)）：ONVIF認証用のカメラユーザー名。カメラ上でPTZ制御権限を持っている必要があります。
* `カメラパスワード` ([*`シークレット`*](/workflows/ja/gaido/developer-guide/kinds/secret.md)）：ONVIF認証用のカメラパスワード。セキュリティのためシークレットとして保存してください。
* `可変速度シミュレーション` ([*`boolean`*](/workflows/ja/gaido/developer-guide/kinds/boolean.md)）：ネイティブの可変速度に対応していないカメラ向けに、可変速度シミュレーションを有効にします。有効にすると、100%速度のコマンドに続けて停止コマンドを送信し、割合速度を近似します。動きがぎこちなくなる場合があります。カメラに可変速度機能がない場合にのみ使用してください。
* `ズーム可能なら` ([*`boolean`*](/workflows/ja/gaido/developer-guide/kinds/boolean.md)）：追跡中のオブジェクトでフレームを埋めるための自動ズームを有効にします。有効にすると、カメラはまずパン／チルトでオブジェクトを中央に合わせ、その後、オブジェクトがフレームいっぱいになるまでズームインします。カメラがズーム機能をサポートしている必要があります。
* `トラッカー追従` ([*`boolean`*](/workflows/ja/gaido/developer-guide/kinds/boolean.md)）：トラッカーIDを使用した永続的な追跡を有効にします。有効にすると、カメラは最も信頼度の高い検出結果のトラッカーIDにロックし、その特定のオブジェクトが消えるか追跡がリセットされるまで追跡を続けます。ワークフロー内にトラッカーIDを割り当てる Byte Tracker ブロックが必要です。
* `デッドゾーン` ([*`integer`*](/workflows/ja/gaido/developer-guide/kinds/integer.md)）：フレーム中心の周囲でカメラの動きが停止するピクセル単位のデッドゾーンサイズです。オブジェクトが中心付近にあるときのハンチング動作を防ぎます。値を大きくするとパン／チルトのハンチングは減りますが、ズームのハンチングが発生する場合があります。値を小さくするとズームの安定性は向上しますが、パン／チルトの振動が発生する場合があります。一般的な範囲：30～100ピクセル。
* `デフォルト位置プリセット` ([*`string`*](/workflows/ja/gaido/developer-guide/kinds/string.md)）：デフォルト／ホーム位置のプリセット名です。カメラは、アイドル期間後（move\_to\_position\_after\_idle\_seconds が設定されている場合）または Go To Preset モード使用時に、このプリセットへ戻ります。カメラで設定されたプリセット名と完全に一致している必要があります。プリセット移動機能に必須です。
* `アイドル後の自動移動` ([*`integer`*](/workflows/ja/gaido/developer-guide/kinds/integer.md)）：自動リセット時間（秒）。カメラがこの時間、探索／移動を停止した後、自動的に default\_position\_preset に移動します。自動リセットを無効にするには 0 に設定します。default\_position\_preset の設定が必要です。
* `カメラ更新レート制限` ([*`integer`*](/workflows/ja/gaido/developer-guide/kinds/integer.md)）：カメラの移動コマンド間の最小時間（ミリ秒）。ONVIF更新をレート制限して、カメラに負荷をかけすぎないようにします。低い値は追跡応答性を高めますが、遅いカメラでは過負荷になる場合があります。高い値はカメラ負荷を減らしますが、動きが滑らかでなくなることがあります。一般的な範囲：100～500ms。
* `X方向移動反転` ([*`boolean`*](/workflows/ja/gaido/developer-guide/kinds/boolean.md)）：水平（パン）方向の移動を反転します。カメラ映像が水平にミラー表示され、動きが逆に見える場合に有効にしてください。映像が反転しているときのカメラ移動の補正に使用します。
* `Y方向移動反転` ([*`boolean`*](/workflows/ja/gaido/developer-guide/kinds/boolean.md)）：垂直（チルト）方向の移動を反転します。多くのカメラではY軸が反転しているため、既定で有効になっています。垂直移動が逆に見える場合は無効にしてください。
* `最小カメラスピード` ([*`float_zero_to_one`*](/workflows/ja/gaido/developer-guide/kinds/float-zero-to-one.md)）：最小移動速度の割合（0.0～1.0）。この閾値を下回る移動コマンドは、この最小値まで引き上げられます。一部のカメラは非常に低い速度を無視します。小さな移動にカメラが反応しない場合は値を上げてください。一般的な範囲：0.02～0.1（2%～10%）。
* `PID比例ゲイン（Kp）` ([*`float`*](/workflows/ja/gaido/developer-guide/kinds/float.md)）：PID比例ゲイン（Kp）。位置誤差への応答を制御します。値が大きいほどカメラの反応は速くなりますが、オーバーシュートやハンチングが発生する場合があります。値が小さいほどハンチングは減りますが、追跡は遅くなります。まずは既定値から始め、カメラの応答性に応じて調整してください。一般的な範囲：0.1～0.5。
* `PID積分ゲイン（Ki）` ([*`float`*](/workflows/ja/gaido/developer-guide/kinds/float.md)）：PID積分ゲイン（Ki）。誤差を時間とともに蓄積することで定常誤差を解消します。通常は振動を引き起こす可能性があるため 0 のままにします。小さな誤差があるのにカメラが常に中心から少しずれて停止する場合は、わずかに（0.01～0.1）増やしてください。
* `PID微分ゲイン（Kd）` ([*`float`*](/workflows/ja/gaido/developer-guide/kinds/float.md)）：PID微分ゲイン（Kd）。将来の誤差を予測し、振動を抑えます。値が大きいほど動画遅延がある環境で安定性が向上しますが、過剰だとハンチングを引き起こす可能性があります。カメラの動きと映像フィードバックの間に大きな遅延がある場合は、（1～5）増やしてください。追跡がぎこちなく見える場合は減らしてください。
* 出力
* `predictions` ([`object_detection_prediction`](/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)): sv.Detections(...) オブジェクト形式の、検出されたバウンディングボックスを含む予測。
* `探索中` ([`boolean`](/workflows/ja/gaido/developer-guide/kinds/boolean.md)): ブールフラグ。
JSON 定義の例
```json
{
"name": "",
"type": "roboflow_core/onvif_sink@v1",
"predictions": "$steps.object_detection_model.predictions",
"camera_ip": "",
"camera_port": "",
"camera_username": "",
"camera_password": "",
"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": "",
"camera_update_rate_limit": "",
"flip_x_movement": true,
"flip_y_movement": true,
"minimum_camera_speed": "",
"pid_kp": "",
"pid_ki": "",
"pid_kd": ""
}
```