> 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）
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カメラが必要です。カメラは、FollowモードではONVIF ContinuousMove サービスを、プリセット移動ではGotoPreset サービスをサポートしている必要があります。最適な性能のためには、可変速度移動に対応したカメラを使用してください。ネイティブの可変速度に対応していないカメラでは simulate\_variable\_speed オプションを使用できますが、動きがぎこちなくなる場合があります。このブロックはローカル実行モードで実行する必要があります（リモート／クラウド実行には適していません）。滑らかな追跡を実現し、行き過ぎやハンチングを防ぐには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` | `整数` | カメラの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` | `整数` | フレーム中心の周囲でカメラの動きが停止するデッドゾーンのピクセルサイズです。対象が中心付近にあるときのハンチング動作を防ぎます。大きい値はパン／チルトのハンチングを減らしますが、ズームのハンチングを引き起こす可能性があります。小さい値はズームの安定性を向上させますが、パン／チルトの振動を引き起こす可能性があります。一般的な範囲：30～100ピクセル。 | ✅ |
| `default_position_preset` | `str` | デフォルト／ホーム位置のプリセット名です。カメラは、アイドル期間後（move\_to\_position\_after\_idle\_seconds が設定されている場合）または Go To Preset モード使用時にこのプリセットへ戻ります。カメラ上で設定されたプリセット名と完全に一致している必要があります。プリセット移動機能に必須です。 | ✅ |
| `move_to_position_after_idle_seconds` | `整数` | 自動リセットまでの秒数です。カメラがこの時間だけ探索／移動を停止した後、default\_position\_preset に自動的に移動します。0 に設定すると自動リセットを無効にします。default\_position\_preset の設定が必要です。 | ✅ |
| `camera_update_rate_limit` | `整数` | カメラ移動コマンド間の最小時間（ミリ秒）です。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）。追跡がぎこちなく見える場合は減らしてください。 | ✅ |
この **参照** 列は、で利用可能な動的値を使ってプロパティをパラメータ化できる可能性を示します `ワークフロー` 実行時。参照 *バインディング* 詳細は。
### ランタイム互換性
`ハード` - 実行 `リモート` : ブロックは step\_execution\_mode=local を要求し、それ以外の場合は ValueError を送出します。ONVIFコマンドは、ワークフローを駆動するのと同じプロセスから発行する必要があります。
`ハード` - ランタイム `hosted_serverless`, `dedicated_deployment` : ブロックにはPTZカメラへのLANアクセスが必要です。Hosted Serverless と Roboflow Dedicated Deployments は顧客のLANに到達できません。
### 入力と出力のバインディング
利用可能な接続は、そのバインディング種別によって異なります。どのバインディング種別が `PTZ追跡（ONVIF）` のバージョン `v1` あるか確認してください。
入力と出力のバインディング
* 入力
* `predictions` (*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)*]*): 追跡する対象検出またはインスタンスセグメンテーションの予測です。Followモードでは、ブロックは最も信頼度の高い予測、またはトラッカーIDがある場合は追跡対象を追従します。予測にはバウンディングボックス座標を含め、永続追跡のために必要に応じてトラッカーIDも含める必要があります。
* `camera_ip` ([*`string`*](/workflows/ja/gaido/developer-guide/kinds/string.md)): ONVIF接続用のカメラIPアドレスまたはホスト名。ワークフローの実行環境から到達可能である必要があります。
* `camera_port` ([*`整数`*](/workflows/ja/gaido/developer-guide/kinds/integer.md)): カメラのONVIFサービスのポート（通常は80、8080、またはカメラ固有のポート）。カメラのONVIF設定と一致している必要があります。
* `camera_username` ([*`string`*](/workflows/ja/gaido/developer-guide/kinds/string.md)): ONVIF認証用のカメラユーザー名。カメラのPTZ制御権限を持っている必要があります。
* `camera_password` ([*`secret`*](/workflows/ja/gaido/developer-guide/kinds/secret.md)): ONVIF認証用のカメラパスワード。セキュリティのためシークレットとして保存してください。
* `simulate_variable_speed` ([*`boolean`*](/workflows/ja/gaido/developer-guide/kinds/boolean.md)): ネイティブの可変速度に対応していないカメラ向けに、可変速度のシミュレーションを有効にします。有効にすると、100%速度コマンドの後に停止コマンドを送信して、割合ベースの速度を近似します。動きがぎこちなくなる場合があります。カメラに可変速度機能がない場合のみ使用してください。
* `zoom_if_able` ([*`boolean`*](/workflows/ja/gaido/developer-guide/kinds/boolean.md)): 追跡対象でフレームを埋めるための自動ズームを有効にします。有効にすると、カメラはまずパン／チルトで対象を中央に合わせ、その後、対象がフレームいっぱいになるまでズームインします。カメラがズーム機能をサポートしている必要があります。
* `follow_tracker` ([*`boolean`*](/workflows/ja/gaido/developer-guide/kinds/boolean.md)): トラッカーIDを使用した永続追跡を有効にします。有効にすると、カメラは最も信頼度の高い検出結果のトラッカーIDをロックし、その特定の対象が消えるか追跡がリセットされるまで追従し続けます。トラッカーIDを割り当てるには、ワークフロー内に Byte Tracker ブロックが必要です。
* `dead_zone` ([*`整数`*](/workflows/ja/gaido/developer-guide/kinds/integer.md)): フレーム中心の周囲でカメラの動きが停止するデッドゾーンのピクセルサイズです。対象が中心付近にあるときのハンチング動作を防ぎます。大きい値はパン／チルトのハンチングを減らしますが、ズームのハンチングを引き起こす可能性があります。小さい値はズームの安定性を向上させますが、パン／チルトの振動を引き起こす可能性があります。一般的な範囲：30～100ピクセル。
* `default_position_preset` ([*`string`*](/workflows/ja/gaido/developer-guide/kinds/string.md)): デフォルト／ホーム位置のプリセット名です。カメラは、アイドル期間後（move\_to\_position\_after\_idle\_seconds が設定されている場合）または Go To Preset モード使用時にこのプリセットへ戻ります。カメラ上で設定されたプリセット名と完全に一致している必要があります。プリセット移動機能に必須です。
* `move_to_position_after_idle_seconds` ([*`整数`*](/workflows/ja/gaido/developer-guide/kinds/integer.md)): 自動リセットまでの秒数です。カメラがこの時間だけ探索／移動を停止した後、default\_position\_preset に自動的に移動します。0 に設定すると自動リセットを無効にします。default\_position\_preset の設定が必要です。
* `camera_update_rate_limit` ([*`整数`*](/workflows/ja/gaido/developer-guide/kinds/integer.md)): カメラ移動コマンド間の最小時間（ミリ秒）です。ONVIF更新をレート制限して、カメラへの負荷を防ぎます。低い値は応答性の高い追跡を提供しますが、低速なカメラでは過負荷になる可能性があります。高い値はカメラ負荷を減らしますが、動きが滑らかでなくなる可能性があります。一般的な範囲：100～500ms。
* `flip_x_movement` ([*`boolean`*](/workflows/ja/gaido/developer-guide/kinds/boolean.md)): 水平（パン）移動方向を反転します。カメラ映像が水平にミラー表示され、動きが逆に見える場合に有効にします。映像が反転しているときにカメラの動きを補正するために使用します。
* `flip_y_movement` ([*`boolean`*](/workflows/ja/gaido/developer-guide/kinds/boolean.md)): 垂直（チルト）移動方向を反転します。多くのカメラではY軸が反転しているため、既定で有効です。垂直移動が逆に見える場合は無効にしてください。
* `minimum_camera_speed` ([*`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": ""
}
```