> 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/motion-detection.md).

# 動き検出

OpenCVを使って動画内の動きを検出します。

OpenCVの背景差分アルゴリズムを使って、動画ストリーム内の動きを検出します。

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

このブロックは背景差分（具体的には MOG2 アルゴリズム）を使って、動画フレーム内の動きを検出します。ブロックはフレーム間で状態を保持し、背景モデルを構築して動きのパターンを追跡します：

1. **背景モデルを初期化します** - 最初のフレームで、指定された履歴としきい値パラメータを使用して背景差分器を作成します
2. **各フレームを処理します** - 学習済みの背景モデルと異なる画素を識別するために背景差分を適用します
3. **ノイズを除去します** - モルフォロジー演算を適用してノイズを除去し、近接する動き領域をまとまりのある輪郭にまとめます
4. **動きの領域を抽出します** - 動き領域を表す輪郭を見つけ、最小サイズでフィルタリングし、必要に応じて検出ゾーンにクリップします
5. **輪郭を簡略化します** - 検出データを扱いやすくするために輪郭の複雑さを減らします
6. **出力を生成します** - バウンディングボックス付きの物体検出予測を作成し、動作状態を判定し、動きが始まるとアラームを発動し、動きゾーンの多角形を提供します

このブロックはフレーム間で動きの状態を追跡します -  **アラーム** 出力は、動きが未検出から検出済みに切り替わったときにのみ true になり、動きが最初に現れたときにアクションをトリガーするのに便利です。

## 一般的な使用例

* **セキュリティ監視**: 監視カメラで動きを検出し、活動が検出されたときにアラート、録画、通知をトリガーします
* **リソース最適化**: 高コストな推論処理（例：物体検出、分類）を、動きが検出されたときのみ条件付きで実行して計算リソースを節約します
* **活動検出**: エリア内の動きを監視して占有状況を追跡し、出入りイベントを特定したり、不正アクセスを検出したりします
* **動画解析**: 動画ストリームを解析して動きのパターンを特定し、活動レベルを追跡し、監視エリア内の異常を検出します
* **スマート録画**: 動きが検出されたときに動画録画やスナップショット取得を開始し、連続録画と比べて保存容量を削減します
* **ゾーン監視**: 検出ゾーンを使ってフレーム内の特定領域を監視し、重要な領域に動き検出を集中させつつ、混雑していても関係のない領域は無視します

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

このブロックの動き検出出力は次に接続できます：

* **条件分岐ブロック** （例：Continue If） 動きが検出されたとき、またはアラームが発動したときのみワークフローステップを実行します
* **物体検出ブロック** 動きのあるフレームにのみ検出モデルを実行して、計算リソースを節約します
* **通知ブロック** （例：Email Notification、Slack Notification） 動きが検出されたとき、またはアラームが発動したときに通知を送信します
* **データ保存ブロック** （例：Roboflow Dataset Upload、CSV Formatter） 動きイベント、タイムスタンプ、検出データを記録して分析に活用します
* **可視化ブロック** 検出された動きを示すフレーム上に、動きゾーン、バウンディングボックス、注釈を描画します
* **フィルターブロック** 下流の処理に渡す前に、動き状態に基づいて画像やデータをフィルタリングします

### タイプ識別子

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

### プロパティ

| **名前**            | **型**                   | **説明**                                                                                                                                                                                                                                                                    | 参照 |
| ----------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| `name`            | `str`                   | このステップの一意の識別子を入力してください。                                                                                                                                                                                                                                                   | ❌  |
| `最小輪郭面積`          | `int`                   | 動き領域として検出するための最小面積（平方ピクセル）。このしきい値より小さい輪郭は、ノイズ、小さな影、わずかな画素変動を無視するために除外されます。値を小さくすると感度は上がりますが、誤検出が増える場合があります（例：100 は非常に高感度、500 は大きな物体のみ）。デフォルトは 200 平方ピクセルです。                                                                                                               | ✅  |
| `モルフォロジー・カーネルサイズ` | `int`                   | 近接する動き領域をまとめ、ノイズを除去するために使用するモルフォロジー・カーネルのサイズ（ピクセル）。値を大きくすると、離れた動き領域も 1 つの輪郭にまとめられますが、別々の物体が統合されることもあります。値を小さくすると、より詳細を保持できますが、検出が断片化する場合があります。カーネルの形状は楕円です。デフォルトは 3 ピクセルです。                                                                                               | ✅  |
| `しきい値`            | `int`                   | MOG2背景差分アルゴリズムで使用される、二乗マハラノビス距離のしきい値です。動きに対する感度を制御します。値を小さくすると感度が上がり（小さな変化を検出）、誤検出が増える可能性があります。値を大きくすると感度が下がり（大きな変化のみを検出）、微妙な動きを見逃す可能性があります。推奨範囲は8〜32です。デフォルトは16です。                                                                                                       | ✅  |
| `履歴`              | `int`                   | 背景モデルの構築に使用する過去フレーム数です。背景が変化にどれだけ早く適応するかを制御します。大きい値（例: 50〜100）は、一時的な変化にはあまり敏感でない、より安定した背景モデルを作りますが、恒久的な背景変化への適応は遅くなります。小さい値（例: 10〜20）は、より速い適応を可能にしますが、動いている物体が停止した場合に背景として扱ってしまうことがあります。デフォルトは30フレームです。                                                                   | ✅  |
| `検出ゾーン`           | `Union[List[Any], str]` | フレーム内の特定領域に動き検出を制限するための任意の多角形ゾーン。動きはこのゾーン内でのみ検出され、外側の活動は無視されます。形式: \[\[x1, y1], \[x2, y2], \[x3, y3], ...]。座標はピクセル単位です。多角形は 4 点以上である必要があります。リスト、JSON文字列、または他のブロックのゾーン出力を参照するセレクタとして指定できます。出入口、窓、立入制限区域など特定の領域に集中しつつ、混雑していても関係のない領域を無視したい場合に便利です。指定しない場合、動きはフレーム全体で検出されます。 | ✅  |
| `最初の検出を抑制`        | `bool`                  | true の場合、背景モデルが十分なフレーム数（history パラメータで指定）で初期化されるまで、動き検出を抑制します。これにより、背景モデルがまだシーンを学習していない初期フレームでの誤検出を防げます。false の場合、ブロックは即座に動きの検出を試みますが、初期化中は信頼性の低い結果になることがあります。デフォルトは true です（ほとんどのユースケースで推奨）。                                                                             | ✅  |

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

### 実行時互換性

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

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

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

利用可能な接続は、そのバインディング種別に依存します。 `モーション検出` バージョン `v1` に、どのバインディング種別があるか確認してください。

<details>

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

* input
  * `image` ([*`image`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/image.md)): 動きを解析するための入力画像または動画フレーム。ブロックはフレームを順次処理して背景モデルを構築します - 各フレームで背景モデルを更新し、学習した背景パターンに対する動きを検出します。ワークフローの入力や前のステップから接続できます。
  * `最小輪郭面積` ([*`integer`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/integer.md)): 動き領域として検出するための最小面積（平方ピクセル）。このしきい値より小さい輪郭は、ノイズ、小さな影、わずかな画素変動を無視するために除外されます。値を小さくすると感度は上がりますが、誤検出が増える場合があります（例：100 は非常に高感度、500 は大きな物体のみ）。デフォルトは 200 平方ピクセルです。
  * `モルフォロジー・カーネルサイズ` ([*`integer`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/integer.md)): 近接する動き領域をまとめ、ノイズを除去するために使用するモルフォロジー・カーネルのサイズ（ピクセル）。値を大きくすると、離れた動き領域も 1 つの輪郭にまとめられますが、別々の物体が統合されることもあります。値を小さくすると、より詳細を保持できますが、検出が断片化する場合があります。カーネルの形状は楕円です。デフォルトは 3 ピクセルです。
  * `しきい値` ([*`integer`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/integer.md)）：MOG2背景差分アルゴリズムで使用される、二乗マハラノビス距離のしきい値です。動きに対する感度を制御します。値を小さくすると感度が上がり（小さな変化を検出）、誤検出が増える可能性があります。値を大きくすると感度が下がり（大きな変化のみを検出）、微妙な動きを見逃す可能性があります。推奨範囲は8〜32です。デフォルトは16です。
  * `履歴` ([*`integer`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/integer.md)）：背景モデルの構築に使用する過去フレーム数です。背景が変化にどれだけ早く適応するかを制御します。大きい値（例: 50〜100）は、一時的な変化にはあまり敏感でない、より安定した背景モデルを作りますが、恒久的な背景変化への適応は遅くなります。小さい値（例: 10〜20）は、より速い適応を可能にしますが、動いている物体が停止した場合に背景として扱ってしまうことがあります。デフォルトは30フレームです。
  * `検出ゾーン` (*Union\[*[*`list_of_values`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/list-of-values.md)*,* [*`ゾーン`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/zone.md)*]*): フレーム内の特定領域に動き検出を制限するための任意の多角形ゾーン。動きはこのゾーン内でのみ検出され、外側の活動は無視されます。形式: \[\[x1, y1], \[x2, y2], \[x3, y3], ...]。座標はピクセル単位です。多角形は 4 点以上である必要があります。リスト、JSON文字列、または他のブロックのゾーン出力を参照するセレクタとして指定できます。出入口、窓、立入制限区域など特定の領域に集中しつつ、混雑していても関係のない領域を無視したい場合に便利です。指定しない場合、動きはフレーム全体で検出されます。
  * `最初の検出を抑制` ([*`boolean`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/boolean.md)): true の場合、背景モデルが十分なフレーム数（history パラメータで指定）で初期化されるまで、動き検出を抑制します。これにより、背景モデルがまだシーンを学習していない初期フレームでの誤検出を防げます。false の場合、ブロックは即座に動きの検出を試みますが、初期化中は信頼性の低い結果になることがあります。デフォルトは true です（ほとんどのユースケースで推奨）。
* output
  * `動き` ([`boolean`](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/boolean.md)): ブールフラグ。
  * `アラーム` ([`boolean`](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/boolean.md)): ブールフラグ。
  * `detections` ([`object_detection_prediction`](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)）：sv.Detections(...) オブジェクト形式の検出済みバウンディングボックスを含む予測。
  * `動きゾーン` ([`list_of_values`](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/list-of-values.md)) : 任意の型の値のリスト。

</details>

<details>

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

```json
{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/motion_detection@v1",
	    "image": "$inputs.image",
	    "minimum_contour_area": 200,
	    "morphological_kernel_size": 3,
	    "threshold": 16,
	    "history": 30,
	    "detection_zone": "<block_does_not_provide_example>",
	    "suppress_first_detections": true
	}
```

</details>
