> 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/velocity.md).
# 速度
ビデオフレーム全体でオブジェクト中心の移動量を時間とともに測定し、指数移動平均による平滑化でノイズを低減し、ピクセル毎秒からメートル毎秒へ変換することで、交通速度監視、移動分析、行動追跡、パフォーマンス測定のワークフロー向けに、追跡対象オブジェクトの速度とスピードを計算します。
## このブロックの仕組み
このブロックは、ビデオフレームをまたいで位置を追跡することで、オブジェクトがどれだけ速く移動しているかを測定します。このブロックは、
1. 一意のトラッカーIDを持つ追跡済み検出予測と、埋め込みビデオメタデータを含む画像を受け取ります
2. 画像からビデオメタデータを抽出します：
* video\_metadataにアクセスして、フレームタイムスタンプまたはフレーム番号とフレームレート（fps）を取得します
* 異なる動画ごとに追跡状態を分けて保持するためにvideo\_identifierを抽出します
* 動画ファイルではframe\_number/fps、ストリームではframe\_timestampを使って現在のタイムスタンプを決定します
3. 検出にトラッカーIDがあることを検証します（フレーム間でオブジェクトの移動を追跡するために必要）
4. オブジェクトの中心位置を計算します：
* 現在のフレーム内の各バウンディングボックスの中心点（x, y）を計算します
* バウンディングボックス座標を使って幾何学的中心を求めます
5. 追跡状態を取得または初期化します：
* 動画ごとの各tracker\_idについて、前回位置とタイムスタンプを保持します
* 動画ごとの各tracker\_idについて、平滑化された速度履歴を保存します
* 初めて現れるオブジェクトの新しい追跡エントリを作成します
6. 追跡対象オブジェクトごとに速度とスピードを計算します：
* **前回の位置を持つオブジェクトについて**：現在のフレームと前のフレームの間の変位（位置の変化）と時間差（時間の変化）を計算します
* **速度**：変位を時間差で割って速度ベクトルを計算します（ピクセル毎秒）
* **スピード**：速度ベクトルの大きさ（長さ）としてスピードを計算します（方向に関係なく、合計のピクセル毎秒）
* **新しいオブジェクトについて**：速度とスピードを0に設定します（まだ移動データがありません）
7. 指数移動平均による平滑化を適用します：
* 設定可能な平滑化係数（alpha）を用いた指数移動平均で速度測定を平滑化します
* 検出のばらつきによる速度計算のノイズとジッターを低減します
* alpha値が低いほど平滑化が強くなり（変化への応答は遅くなる）、alpha値が高いほど平滑化は弱くなります（変化への応答は速くなる）
* 各オブジェクトの平滑化速度と平滑化スピードを計算します
8. 単位をメートル毎秒に変換します：
* ピクセルベースの速度とスピードをpixels\_per\_meter変換係数で割ります
* すべての測定値（velocity、speed、smoothed\_velocity、smoothed\_speed）を実世界の単位に変換します
* 実世界の速度測定値（例：km/h、mph）と比較できるようにします
9. 速度データを検出メタデータに保存します：
* 各検出に4つの速度メトリクスを追加します：velocity（m/s）、speed（m/s）、smoothed\_velocity（m/s）、smoothed\_speed（m/s）
* Velocityは、移動の方向と大きさを表す2次元ベクトル \[vx, vy] です
* Speedは、方向に関係なく総合的な速さを表すスカラー値です
* すべての測定値は下流処理で使用するため detections.data に保存されます
10. 次のフレームのために追跡状態を更新します：
* 追跡中のすべてのオブジェクトの現在位置とタイムスタンプを保存します
* 次のフレームの平滑化計算用に平滑化速度を保存します
11. 速度情報で強化された検出結果を返します：
* 追加の速度メタデータを付与した同じ検出オブジェクトを出力します
* 各検出には、メタデータ内に速度とスピードのデータが含まれるようになりました
速度は、時間経過に伴うオブジェクト中心（バウンディングボックスの中心）の移動量に基づいて計算されます。このブロックは動画ごとに個別の追跡状態を保持するため、複数の動画ストリームにわたって速度を計算できます。遠近歪みやカメラの位置の影響により、計算される速度はフレーム内のオブジェクトの出現位置によって変わる場合があります。カメラに近いオブジェクトや異なる奥行きにあるオブジェクトは、同じ実世界速度でもピクセル毎秒の値が異なります。平滑化は、検出精度のばらつきやフレーム間変動によるノイズを低減するのに役立ちます。
## 一般的な使用例
* **交通速度監視**：道路や高速道路上の車両速度を測定します（例：交通速度の監視、速度超過違反の検出、交通流量の分析）。これにより、交通取締りと分析のワークフローが可能になります
* **スポーツパフォーマンス分析**：スポーツ中のアスリートの移動と速度を追跡します（例：選手の速度測定、スプリントパフォーマンスの分析、移動パターンの追跡）。これにより、スポーツ分析のワークフローが可能になります
* **セキュリティと監視**：セキュリティシナリオで人や物体の移動速度を監視します（例：走行や不審な急激な移動の検出、群衆の流れの速度監視、物体の移動率の追跡）。これにより、セキュリティ監視のワークフローが可能になります
* **小売分析**：小売空間での顧客の移動パターンや歩行速度を分析します（例：来客数の流れを測定、購買行動パターンの分析、移動効率の追跡）。これにより、小売行動分析のワークフローが可能になります
* **野生動物の行動研究**：自然生息地における動物の移動速度とパターンを追跡します（例：動物の速度測定、移動パターンの分析、移動行動の研究）。これにより、野生動物研究のワークフローが可能になります
* **産業監視**：産業環境での車両、機器、製品の速度を監視します（例：コンベヤー速度の追跡、施設内車両速度の測定、生産ラインの移動率の監視）。これにより、産業オートメーションのワークフローが可能になります
## 他のブロックへの接続
このブロックは、追跡済み検出と埋め込みビデオメタデータを含む画像を受け取り、速度メタデータが付与された検出結果を出力します：
* **Byte Trackerブロックの後** 追跡対象オブジェクトの速度を計算するために（例：追跡中の車両の速度を測定、追跡中の人物の移動を分析、追跡中のオブジェクトの速度を監視）。これにより、追跡から速度へのワークフローが可能になります
* **物体検出またはインスタンスセグメンテーションブロックの後** 追跡を有効にして移動速度を測定するために（例：車両速度の計算、人物の移動速度の追跡、オブジェクト速度の監視）。これにより、検出から速度へのワークフローが可能になります
* **可視化ブロックの前** 速度情報を表示するために（例：速度オーバーレイの可視化、速度ベクトルの表示、移動速度注釈の表示）。これにより、速度の可視化ワークフローが可能になります
* **ロジックブロックの前** Continue Ifのように、速度しきい値に基づいて判断するために（例：速度が上限を超えたら続行、速度範囲に基づいてフィルタリング、速度違反でアクションをトリガー）。これにより、速度ベースの判断ワークフローが可能になります
* **通知ブロックの前** 速度違反やしきい値イベントを通知するために（例：速度超過違反の警告、急速な移動の通知、速度ベースのアラートのトリガー）。これにより、速度ベースの通知ワークフローが可能になります
* **データ保存ブロックの前** 速度測定値を記録するために（例：速度データのログ、速度統計の保存、移動メトリクスの記録）。これにより、速度データのログ記録ワークフローが可能になります
## 要件
このブロックは、tracker\_id情報を含む追跡済み検出（detectionsはByte Trackerのような追跡ブロックから来る必要があります）を必要とします。画像のvideo\_metadataには、正確な時間差を計算するために、動画ファイル用のフレームレート（fps）またはストリーミング動画用のフレームタイムスタンプを含める必要があります。このブロックはvideo\_identifierを使用してフレーム間で各動画の永続的な追跡状態を保持するため、フレームが順次処理される動画ワークフローで使用する必要があります。正確な速度測定のため、検出は有効なtracker IDとともにフレーム間で一貫して提供されるべきです。pixels\_per\_meter変換係数は、正確な実世界速度測定のためにカメラの設定とシーンの幾何に基づいて較正する必要があります。なお、速度の精度は、オブジェクトのフレーム内位置に応じた遠近歪みにより変化する場合があります。
### 型識別子
ステップで次の識別子を使用してください `"type"` フィールド： `roboflow_core/velocity@v1` ワークフローにこのブロックをステップとして追加するには。
### プロパティ
| **名前** | **型** | **説明** | 参照 |
| ------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| `name` | `str` | このステップの一意の識別子を入力してください。 | ❌ |
| `smoothing_alpha` | `float` | 指数移動平均の平滑化係数（alpha）で、範囲は 0 < alpha <= 1 です。速度測定にどの程度の平滑化を適用するかを制御します。値が低いほど（0に近いほど）平滑化が強くなり、変化への応答は遅くなり、ノイズは少なくなります。値が高いほど（1に近いほど）平滑化は弱くなり、変化への応答は速くなり、ノイズは多くなります。デフォルトは0.5で、滑らかさと応答性のバランスを取ります。 | ✅ |
| `pixels_per_meter` | `float` | 実世界の速度計算のための、ピクセルからメートルへの変換係数です。ピクセル毎秒での速度測定値は、この値で割ってメートル毎秒に変換します。0より大きい必要があります。正確な実世界速度を得るには、カメラの高さ、角度、シーンの幾何に基づいて較正してください。例：1ピクセル = 0.01メートル（1cm）の場合は0.01を使用します。デフォルト1.0は変換なし（結果はピクセル毎秒）を意味します。 | ✅ |
この **参照** 列は、で利用可能な動的値を使ってプロパティをパラメータ化できる可能性を示します `ワークフロー` 実行時。参照 *バインディング* 詳細は。
### ランタイム互換性
`soft` - ランタイム `hosted_serverless`, `dedicated_deployment`；実行 `リモート`; 入力 `動画` このブロックは、プロセスメモリ内に動画ごとの状態を保持します（video\_metadata.video\_identifier をキーとする）。ステートレスまたは複数レプリカのHTTPランタイムでリモートステップ実行を行うと、連続するリクエストが別々のワーカープロセスによって処理される可能性があるため、呼び出し間で状態がリセットされ、追跡／カウント／集計には意味のない出力になります。安定したフレーム間結果を得るには、永続的な WebRTC セッションでローカルステップ実行を使用してください。
`soft` - 入力 `image` このブロックは、動画または繰り返しフレームのワークフローからの時間的コンテキストに依存します。静止画像／写真では、追跡、比較、集計、可視化に使える意味のある履歴がないため、このブロックの利点はほとんど、またはまったくありません。
### 入力と出力のバインディング
利用可能な接続は、そのバインディング種別によって異なります。どのバインディング種別が `速度` のバージョン `v1` あるか確認してください。
入力と出力のバインディング
* 入力
* `image` ([*`image`*](/workflows/ja/gaido/developer-guide/kinds/image.md)): 埋め込みビデオメタデータを含む画像。video\_metadataにはfps、frame\_number、frame\_timestamp、video\_identifierが含まれます。時間差の計算と、異なる動画の速度追跡状態を個別に維持するために必要です。
* `検出` (*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)*,* [*`keypoint_detection_prediction`*](/workflows/ja/gaido/developer-guide/kinds/keypoint-detection-prediction.md)*]*): バウンディングボックスと検出されたキーポイントを含む追跡対象オブジェクトの検出またはインスタンスセグメンテーション予測。追跡ブロック由来のtracker\_id情報を含める必要があります。速度はバウンディングボックス中心の移動量に基づいて時間経過とともに計算されます。出力検出には、検出メタデータ内に velocity（m/sベクトル）、speed（m/sスカラー）、smoothed\_velocity（m/sベクトル）、smoothed\_speed（m/sスカラー）が含まれます。
* `smoothing_alpha` ([*`float`*](/workflows/ja/gaido/developer-guide/kinds/float.md)）：指数移動平均の平滑化係数（alpha）で、範囲は 0 < alpha <= 1 です。速度測定にどの程度の平滑化を適用するかを制御します。値が低いほど（0に近いほど）平滑化が強くなり、変化への応答は遅くなり、ノイズは少なくなります。値が高いほど（1に近いほど）平滑化は弱くなり、変化への応答は速くなり、ノイズは多くなります。デフォルトは0.5で、滑らかさと応答性のバランスを取ります。
* `pixels_per_meter` ([*`float`*](/workflows/ja/gaido/developer-guide/kinds/float.md)）：実世界の速度計算のための、ピクセルからメートルへの変換係数です。ピクセル毎秒での速度測定値は、この値で割ってメートル毎秒に変換します。0より大きい必要があります。正確な実世界速度を得るには、カメラの高さ、角度、シーンの幾何に基づいて較正してください。例：1ピクセル = 0.01メートル（1cm）の場合は0.01を使用します。デフォルト1.0は変換なし（結果はピクセル毎秒）を意味します。
* 出力
* `velocity_detections` (*Union\[*[*`keypoint_detection_prediction`*](/workflows/ja/gaido/developer-guide/kinds/keypoint-detection-prediction.md)*,* [*`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)*]*）：検出されたバウンディングボックスと検出されたキーポイントを含む、sv.Detections(...) オブジェクト形式の予測結果。もし `keypoint_detection_prediction` または、検出されたバウンディングボックスを sv.Detections(...) オブジェクトの形式で持つ Prediction の場合 `object_detection_prediction` または、sv.Detections(...) 形式の検出バウンディングボックスとセグメンテーションマスクを含む予測。 `instance_segmentation_prediction`.
JSON 定義の例
```json
{
"name": "",
"type": "roboflow_core/velocity@v1",
"image": "",
"detections": "$steps.object_detection_model.predictions",
"smoothing_alpha": 0.5,
"pixels_per_meter": 0.01
}
```