> 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 を抽出して、異なる動画ごとに個別の追跡状態を維持します
   * video ファイルでは frame\_number/fps を、ストリームでは frame\_timestamp を使用して現在のタイムスタンプを決定します
3. 検出に tracker ID があることを検証します（フレーム間でオブジェクトの移動を追跡するために必要です）
4. オブジェクトの中心位置を計算します:
   * 現在のフレーム内の各バウンディングボックスの中心点（x, y）を計算します
   * バウンディングボックスの座標を使用して幾何学的中心を求めます
5. 追跡状態を取得または初期化します:
   * 各 video ごとの各 tracker\_id について、前回の位置とタイムスタンプを保持します
   * 各 video ごとの各 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 情報を含む追跡済み検出結果が必要です（検出結果は Byte Tracker のような追跡ブロックから取得する必要があります）。画像の video\_metadata には、動画ファイル用の frame rate（fps）またはストリーミング動画用の frame\_timestamp を含めて、正確な時間差を計算できるようにする必要があります。このブロックは 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 は変換なしを意味します（結果はピクセル毎秒になります）.. | ✅  |

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

### ランタイム互換性

`ソフト` - ランタイム `hosted_serverless`, `dedicated_deployment`; 実行 `リモート`; 入力 `動画` : このブロックは、動画ごとの状態をプロセスメモリ内に保持します（video\_metadata.video\_identifierでキー付け）。ステートレスまたは複数レプリカのHTTPランタイムでリモートステップ実行を行うと、連続したリクエストが異なるワーカープロセスで処理される可能性があるため、呼び出し間で状態がリセットされ、トラッキング／カウント／集計には出力が無意味になります。フレーム間で安定した結果を得るには、InferencePipeline内でローカルステップ実行を使用してください。

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

### 入力と出力のバインディング

利用可能な接続は、そのバインディングの種類によって異なります。どのバインディングの種類を `速度` バージョン `v1` があるか確認してください。

<details>

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

* 入力
  * `画像` ([*`画像`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/image.md)): 画像に埋め込まれた動画メタデータ。video\_metadata には fps、frame\_number、frame\_timestamp、video\_identifier が含まれます。時間差の計算と、異なる動画ごとに個別の速度追跡状態を維持するために必要です..
  * `detections` (*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)*]*): 追跡済みオブジェクト検出またはインスタンスセグメンテーションの予測。追跡ブロックからの tracker\_id 情報を含める必要があります。速度は、バウンディングボックス中心の時間経過に伴う変位に基づいて計算されます。出力される検出結果には、検出メタデータ内に velocity（m/s ベクトル）、speed（m/s スカラー）、smoothed\_velocity（m/s ベクトル）、smoothed\_speed（m/s スカラー）が含まれます。
  * `smoothing_alpha` ([*`float`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/float.md)): 指数移動平均の平滑化係数（alpha）で、範囲は 0 < alpha <= 1 です。速度測定にどの程度の平滑化を適用するかを制御します。値が小さいほど（0 に近いほど）平滑化が強くなり、変化への応答は遅くなり、ノイズは少なくなります。値が大きいほど（1 に近いほど）平滑化は弱くなり、変化への応答は速くなりますが、ノイズは増えます。デフォルトの 0.5 は、滑らかさと応答性のバランスを取ります..
  * `pixels_per_meter` ([*`float`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/float.md)): 実世界の速度計算のための、ピクセルからメートルへの変換係数です。ピクセル毎秒の速度測定値をこの値で割ることで、メートル毎秒に変換します。0 より大きい必要があります。正確な実世界速度を得るには、カメラの高さ、角度、シーンの幾何に基づいて較正してください。例: 1 ピクセル = 0.01 メートル（1cm）の場合、0.01 を使用します。デフォルトの 1.0 は変換なしを意味します（結果はピクセル毎秒になります）..
* 出力
  * `velocity_detections` (*Union\[*[*`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)*,* [*`instance_segmentation_prediction`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/instance-segmentation-prediction.md)*]*): 検出されたバウンディングボックスと検出されたキーポイントを含む予測。sv.Detections(...) オブジェクトの形式で、もし `keypoint_detection_prediction` または、検出されたバウンディングボックスを含む予測。sv.Detections(...) オブジェクトの形式で、もし `object_detection_prediction` または、検出されたバウンディングボックスとセグメンテーションマスクを含む予測。sv.Detections(...) 形式のオブジェクトで、もし `instance_segmentation_prediction`.

</details>

<details>

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

```json
{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/velocity@v1",
	    "image": "<block_does_not_provide_example>",
	    "detections": "$steps.object_detection_model.predictions",
	    "smoothing_alpha": 0.5,
	    "pixels_per_meter": 0.01
	}
```

</details>
