> 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/timein-zone.md).

# ゾーン滞在時間

オブジェクトのゾーン内滞在時間を追跡します。

## v3

1つ以上の定義済みのポリゴンゾーン内で追跡オブジェクトが費やした時間を計算して追跡し、特定の領域におけるオブジェクトの存在時間を測定し（オブジェクトがいずれかのゾーンに存在すれば「ゾーン内」と見なす複数ゾーンをサポート）、ゾーン所属に基づいて検出をフィルタリングし、オブジェクトがゾーンを離れたときに時間追跡をリセットし、ゾーンベースの分析、滞在時間分析、存在監視のワークフローを有効にします。

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

このブロックは、各固有の track ID ごとの入退場時刻を追跡することで、各追跡オブジェクトが1つ以上の定義済みポリゴンゾーン内にどれだけの時間いたかを測定します。このブロックは複数ゾーンをサポートし、定義済みゾーンのいずれかに存在すればオブジェクトを「ゾーン内」と見なします。このブロックは次のとおりです。

1. track ID を持つ追跡済み検出予測、埋め込みビデオメタデータを含む画像、およびポリゴンゾーン定義（単一ゾーンまたはゾーンのリスト）を受け取ります
2. 画像から動画メタデータを抽出します:
   * WorkflowImageData オブジェクトから video\_metadata にアクセスします
   * fps、frame\_number、frame\_timestamp、video\_identifier、およびビデオソース情報を抽出します
   * video\_identifier を使用して、異なるビデオごとに個別の追跡状態を維持します
3. 検出に track ID があることを検証します（tracker\_id が存在している必要があります）：
   * 追跡ブロック（例：Byte Tracker）からの検出を必要とします
   * 各オブジェクトは、フレーム間で保持される一意の tracker\_id を持っている必要があります
   * tracker\_id がない場合はエラーを発生させます
4. ゾーン入力をポリゴンのリストに正規化します：
   * 単一のポリゴンゾーンまたはポリゴンゾーンのリストを受け付けます
   * 一貫した処理のために、単一のポリゴンを自動的にリストに包みます
   * すべてのゾーンについて、ネストの深さと座標形式を検証します
   * 柔軟なゾーン入力形式（単一ゾーンまたは複数ゾーン）を可能にします
5. ビデオのポリゴンゾーンを初期化または取得します：
   * 各固有のゾーンの組み合わせごとに、ゾーン座標から PolygonZone オブジェクトのリストを作成します
   * ゾーン座標を検証します（各ゾーンは、各点が2つの座標を持つ少なくとも3点のリストでなければなりません）
   * ゾーンキャッシュ付きの OrderedDict にゾーン設定を保存します（最大100ゾーンの組み合わせ）
   * キャッシュ検索に、video\_identifier とゾーン座標を組み合わせたゾーンキーを使用します
   * キャッシュが100ゾーンの組み合わせを超えた場合は FIFO 置換を実装します
   * ゾーン検出用のトリガーアンカー点（例：CENTER、BOTTOM\_CENTER）を設定します
6. ビデオの時間追跡状態を初期化または取得します：
   * 各 track\_id がどのゾーンに入ったかを追跡する辞書を維持します
   * video\_identifier を使用して、ビデオごとに入場タイムスタンプを保存します
   * ビデオごとに個別の追跡状態を維持します
7. 時間計測のための現在のタイムスタンプを計算します：
   * ビデオファイルの場合：timestamp を frame\_number / fps として計算します
   * ストリーミングビデオの場合：メタデータの frame\_timestamp を使用します
   * 継続時間計算のために正確な時間計測を提供します
8. どの検出がいずれかのゾーン内にあるかを確認します：
   * ポリゴンゾーントリガーを使用して、各検出をすべてのポリゴンゾーンに対してテストします
   * ゾーン所属の行列（ゾーン×検出）を作成します
   * 論理 OR 演算を使用します。オブジェクトは、いずれかのゾーンに入っていれば「ゾーン内」と見なされます
   * triggering\_anchor は、どのバウンディングボックス上の点をチェックするかを決定します（CENTER、BOTTOM\_CENTER など）
   * 各検出について、いずれかのゾーンへの所属を示すブール値を返します
9. 各追跡オブジェクトの時間追跡を更新します：
   * **いずれかのゾーンに入ったオブジェクトについて**: まだ追跡されていなければ入場タイムスタンプを記録します
   * **いずれかのゾーン内にあるオブジェクトについて**: 経過時間を current\_timestamp - entry\_timestamp として計算します
   * **すべてのゾーンから出たオブジェクトについて**:
     * reset\_out\_of\_zone\_detections が True の場合: 入場タイムスタンプを削除します（0 にリセット）
     * reset\_out\_of\_zone\_detections が False の場合: 入場タイムスタンプを保持します（追跡を継続）
10. ゾーン外検出を処理します：
    * **remove\_out\_of\_zone\_detections が True の場合**: 出力からすべてのゾーンの外にある検出を除外します
    * **remove\_out\_of\_zone\_detections が False の場合**: ゾーン外の検出を time = 0 で含めます
11. 各検出に time\_in\_zone 情報を追加します：
    * 各検出に time\_in\_zone の値（秒単位）をメタデータとして付与します
    * いずれかのゾーン内のオブジェクト: 時間は、いずれかのゾーン内で費やした継続時間を表します
    * すべてのゾーン外のオブジェクト: 時間は 0（リセットされていない場合）または未定義（削除された場合）です
12. time\_in\_zone 情報付きの検出を返します：
    * time\_in\_zone メタデータで強化された追跡済み検出を出力します
    * remove\_out\_of\_zone\_detections 設定に応じてフィルタリングまたは非フィルタリングです
    * すべての元の検出プロパティに加えて、時間追跡情報を保持します

このブロックはフレーム間で永続的な追跡状態を維持し、複数フレームにわたっていずれかのゾーン内に留まるオブジェクトの正確な累積時間測定を可能にします。時間は、オブジェクトが（track\_id に基づいて）いずれかのゾーンに最初に入った時点から現在のフレームまで測定され、リアルタイムの継続時間追跡を提供します。複数のゾーンが与えられた場合、オブジェクトのアンカーポイントがいずれかのゾーン内にあるときに「ゾーン内」と見なされ、複数領域を1つの結合ゾーンとして追跡できます。ゾーンキャッシュは、FIFO 置換を使用して複数のゾーン設定をビデオごとに効率的に管理し、メモリ使用量を抑えます。triggering\_anchor は、ゾーン検出に使用するバウンディングボックスのどの部分を使うかを決定し、オブジェクトの位置に基づいた異なる入退場動作を可能にします。

## 一般的な使用例

* **マルチゾーン滞在時間分析**: 行動分析のために、オブジェクトが複数の領域のいずれかにどれだけ留まるかを測定します（例：店舗の各売場セクションでの顧客滞在時間の測定、複数の駐車エリアでの滞在時間の追跡、重複するゾーンでの時間分析）。マルチゾーンの滞在時間分析ワークフローを可能にします
* **ゾーンベースの監視**: セキュリティと安全のために、複数の定義済み領域にわたるオブジェクトの存在を監視します（例：制限区域のいずれかでの長時間滞留の検出、複数の危険ゾーンでの時間監視、安全区域全体での存在追跡）。マルチゾーン監視ワークフローを可能にします
* **小売分析**: 小売インサイトのために、複数の売場セクションにわたる顧客の滞在時間を追跡します（例：商品通路のいずれかでの時間測定、売場間の買い物パターン分析、複数ゾーンでのエンゲージメント追跡）。マルチゾーン小売分析ワークフローを可能にします
* **占有管理**: 空間利用のために、オブジェクトが複数の空間のいずれかで費やす時間を測定します（例：複数の駐車場での車両駐車時間の追跡、ゾーン全体でのテーブル占有率の測定、複数領域での空間使用状況の分析）。マルチゾーン占有管理ワークフローを可能にします
* **安全コンプライアンス**: 複数の制限区域または時間制限付きゾーンにわたる時間違反を監視します（例：危険区域のいずれかでの長時間滞在の検出、ゾーン全体での時間制限違反の監視、複数領域での安全コンプライアンスの追跡）。マルチゾーン安全監視ワークフローを可能にします
* **交通分析**: オブジェクトが複数の交通ゾーンや交差点のいずれかで費やす時間を測定します（例：複数交差点での滞在時間の追跡、ゾーン全体での待ち行列の待機時間の測定、複数領域での交通流分析）。マルチゾーン交通分析ワークフローを可能にします

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

このブロックは、埋め込みビデオメタデータ、追跡済み検出、およびゾーン座標を含む画像を受け取り、time\_in\_zone メタデータ付きの timed\_detections を生成します：

* **Byte Tracker ブロックの後** 複数ゾーンにわたる追跡オブジェクトの時間を測定するために（例：追跡オブジェクトの複数ゾーンでの時間の追跡、一貫した ID による滞在時間の測定、複数ゾーンにおける追跡オブジェクトの存在分析）、tracking-to-time ワークフローを可能にします
* **ゾーン定義ブロックの後に** 定義された複数領域に時間追跡を適用するために（例：複数のポリゴンゾーンにわたる時間の測定、カスタムのマルチゾーン構成での継続時間の追跡、ゾーンベースの存在の分析）、zone-to-time ワークフローを可能にします
* **ロジックブロックの前** Continue If のように、いずれかのゾーンでの時間に基づいて判断するために（例：いずれかのゾーンで時間がしきい値を超えた場合に継続する、ゾーンをまたいだ滞在時間に基づいてフィルタする、複数領域での時間違反に対してアクションをトリガーする）、時間ベースの判断ワークフローを可能にします
* **分析ブロックの前に** 複数ゾーンにわたる時間ベースの指標を分析するために（例：ゾーン全体の滞在時間パターンの分析、複数領域の time-in-zone データ処理、ゾーン全体の継続時間指標の処理）、時間分析ワークフローを可能にします
* **通知ブロックの前に** いずれかのゾーンでの時間違反やしきい値を通知するために（例：いずれかのゾーンでの長時間滞在の警告、領域全体での時間制限違反の通知、複数ゾーンへの時間ベースのアラートのトリガー）、時間ベースの通知ワークフローを可能にします
* **データ保存ブロックの前に** 複数ゾーンにわたる時間指標を記録するために（例：複数領域の滞在時間データの保存、ゾーン全体の time-in-zone 指標のログ記録、複数ゾーンの継続時間測定の記録）、時間指標のログ記録ワークフローを可能にします

## バージョンの違い

**v2 からの強化点：**

* **複数ゾーンのサポート**: 複数のポリゴンゾーンにまたがる時間追跡を同時にサポートし、オブジェクトは定義済みゾーンのいずれかに存在すれば「ゾーン内」と見なされるため、マルチゾーンの時間追跡と分析が可能になります
* **柔軟なゾーン入力**: 単一のポリゴンゾーンまたはポリゴンゾーンのリストのいずれかを受け付け、両方の形式をシームレスに扱うために入力を自動的に正規化します
* **ゾーンキャッシュ管理**: FIFO 置換（最大100ゾーンの組み合わせ）を備えたゾーンキャッシュを実装し、メモリ使用量を抑えながらビデオごとの複数ゾーン設定を効率的に管理します
* **結合ゾーンロジック**: すべてのゾーンに対して論理 OR 演算を使用し、複数領域を統合されたゾーンシステムとして追跡できるようにすることで、包括的な存在監視を実現します
* **強化されたゾーンキーシステム**: キャッシュ検索に結合ゾーンキー（video\_identifier + ゾーン座標）を使用し、ゾーン設定の効率的な保存と取得を可能にします

## 要件

このブロックは、tracker\_id 情報を含む追跡済み検出を必要とします（検出は Byte Tracker のような追跡ブロックから来る必要があります）。ゾーンは単一のポリゴンまたはポリゴンのリストとして定義できます。各ポリゴンは、少なくとも3点のリストとして定義され、各点はちょうど2つの座標（x, y）を持つリストまたはタプルでなければなりません。画像の video\_metadata には、正確な時間測定を計算するために、ビデオファイルの場合はフレームレート（fps）、ストリーミングビデオの場合はフレームタイムスタンプを含める必要があります。このブロックは各ビデオのフレーム間で永続的な追跡状態を維持するため、フレームを順次処理するビデオワークフローで使用する必要があります。正確な時間測定のため、検出は有効な track ID とともにフレーム間で一貫して提供される必要があります。複数のゾーンが与えられた場合、オブジェクトはいずれかのゾーンに存在すれば「ゾーン内」と見なされます。

### タイプ識別子

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

### プロパティ

| **名前**                          | **型**       | **説明**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | 参照 |
| ------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| `name`                          | `str`       | このステップの一意の識別子を入力してください。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | ❌  |
| `zone`                          | `List[Any]` | 時間測定のための1つ以上の領域を定義するポリゴンゾーン座標。単一のポリゴンゾーンまたはポリゴンゾーンのリストのいずれかにできます。各ゾーンは少なくとも3点のリストでなければならず、各点はちょうど2つの座標 \[x, y] または (x, y) を持つリストまたはタプルです。座標は画像サイズに一致するピクセル空間である必要があります。単一ゾーンの例: \[(100, 100), (100, 200), (300, 200), (300, 100)]。複数ゾーンの例: \[\[(100, 100), (100, 200), (300, 200), (300, 100)], \[(400, 400), (400, 500), (600, 500), (600, 400)]]. オブジェクトは、triggering\_anchor 点が提供されたゾーンのいずれかの内部にある場合に「ゾーン内」と見なされます。ゾーン座標は検証され、各ゾーンに対して PolygonZone オブジェクトが作成されます。ゾーン設定は FIFO 置換付きでキャッシュされます（最大100組み合わせ）.. | ✅  |
| `triggering_anchor`             | `str`       | オブジェクトを「ゾーン内」と見なすために、検出バウンディングボックス上でゾーン内にある必要がある点。オプションには、'CENTER'（デフォルト、バウンディングボックスの中心）、'BOTTOM\_CENTER'（下中央点）、'TOP\_CENTER'（上中央点）、'CENTER\_LEFT'（中央左点）、'CENTER\_RIGHT'（中央右点）、およびその他の Position enum 値が含まれます。triggering\_anchor は、オブジェクトのバウンディングボックスのどの部分をゾーンポリゴンに対してチェックするかを決定します。複数のゾーンが与えられた場合、アンカーポイントがいずれかのゾーンの内部にあれば、オブジェクトは「ゾーン内」と見なされます。標準的なゾーン検出には CENTER を、地面レベルのゾーンには BOTTOM\_CENTER を（例：足元/車両の底部の追跡）、または検出ニーズに応じて他のアンカーを使用してください。デフォルトは 'CENTER' です..                                           | ✅  |
| `remove_out_of_zone_detections` | `bool`      | True の場合（デフォルト）、すべてのゾーン外で見つかった検出は除外され、出力に含まれません。少なくとも1つのゾーン内にある検出のみが返されます。False の場合、すべての検出が出力に含まれ、すべてのゾーン外にあるオブジェクトには time\_in\_zone = 0 が設定されます。いずれかのゾーン内のオブジェクトだけに分析を集中させるには True を、ゾーン状態を保持しながらすべての検出を維持するには False を使用します。複数のゾーンが与えられた場合、オブジェクトはどれかのゾーンに存在すれば「ゾーン内」と見なされます。ゾーンの活動に焦点を当てた、よりすっきりした出力のためのデフォルトは True です..                                                                                                                                                                                  | ✅  |
| `reset_out_of_zone_detections`  | `bool`      | True の場合（デフォルト）、追跡オブジェクトがすべてのゾーンを離れると、その時間追跡はリセットされます（入場タイムスタンプがクリアされます）。オブジェクトがいずれかのゾーンに再入場すると、時間追跡は再び 0 から始まります。False の場合、すべてのゾーンを離れた後も時間追跡は継続され、再入場時には累積時間が保持されます。現在の継続的なゾーン内時間を測定するには True（すべてのゾーン退出時にリセット）、複数回の入場にわたる累積時間を測定するには False を使用します。複数のゾーンが与えられた場合、時間はオブジェクトがすべてのゾーンを離れたときにのみリセットされます。継続的な存在継続時間を測定するためのデフォルトは True です..                                                                                                                                                                     | ✅  |

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

### 実行時互換性

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

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

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

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

<details>

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

* input
  * `image` ([*`image`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/image.md)）：時間計算と状態管理に必要な、埋め込みビデオメタデータ（fps、frame\_number、frame\_timestamp、video\_identifier、video source）を含む現在のビデオフレーム用の入力画像です。このブロックは WorkflowImageData オブジェクトから video\_metadata を抽出します。fps と frame\_number は、ビデオファイルのタイムスタンプを計算するために使用されます（timestamp = frame\_number / fps）。ストリーミングビデオでは frame\_timestamp が直接使用されます。video\_identifier は、異なるビデオごとに個別の追跡状態とゾーン設定を維持するために使用されます。ゾーンの可視化と参照に使用されます。画像の寸法はゾーン座標の検証に使用されます。このバージョンは、複数ゾーンをビデオごとに効率的にゾーンキャッシュ管理しながらサポートします。..
  * `detections` (*Union\[*[*`instance_segmentation_prediction`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/instance-segmentation-prediction.md)*,* [*`object_detection_prediction`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)*]*）：tracker\_id 情報を含む追跡済み検出予測（物体検出またはインスタンスセグメンテーション）です。検出は、フレーム間で保持される一意の tracker\_id を割り当てた追跡ブロック（例：Byte Tracker）から来る必要があります。各検出は時間追跡を可能にするために tracker\_id を持っている必要があります。このブロックは、各追跡オブジェクトについて、その track\_id が最初にいずれかのゾーンに入った時点に基づいて time\_in\_zone を計算します。オブジェクトは、アンカーポイントが提供されたゾーンのいずれかの内部にある場合に「ゾーン内」と見なされます。出力には、time\_in\_zone メタデータ（秒単位の継続時間）で強化された同じ検出が含まれます。remove\_out\_of\_zone\_detections が True の場合、いずれかのゾーン内の検出のみが出力に含まれます。..
  * `zone` ([*`list_of_values`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/list-of-values.md)）：時間測定のための1つ以上の領域を定義するポリゴンゾーン座標。単一のポリゴンゾーンまたはポリゴンゾーンのリストにできます。各ゾーンは少なくとも3点のリストでなければならず、各点はちょうど2つの座標 \[x, y] または (x, y) を持つリストまたはタプルです。座標は画像サイズに一致するピクセル空間である必要があります。単一ゾーンの例: \[(100, 100), (100, 200), (300, 200), (300, 100)]。複数ゾーンの例: \[\[(100, 100), (100, 200), (300, 200), (300, 100)], \[(400, 400), (400, 500), (600, 500), (600, 400)]]. オブジェクトは、triggering\_anchor 点が提供されたゾーンのいずれかの内部にある場合に「ゾーン内」と見なされます。ゾーン座標は検証され、各ゾーンに対して PolygonZone オブジェクトが作成されます。ゾーン設定は FIFO 置換付きでキャッシュされます（最大100組み合わせ）..
  * `triggering_anchor` ([*`string`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/string.md)）：オブジェクトを「ゾーン内」と見なすために、検出バウンディングボックス上でゾーン内にある必要がある点。オプションには、'CENTER'（デフォルト、バウンディングボックスの中心）、'BOTTOM\_CENTER'（下中央点）、'TOP\_CENTER'（上中央点）、'CENTER\_LEFT'（中央左点）、'CENTER\_RIGHT'（中央右点）、およびその他の Position enum 値が含まれます。triggering\_anchor は、オブジェクトのバウンディングボックスのどの部分をゾーンポリゴンに対してチェックするかを決定します。複数のゾーンが与えられた場合、アンカーポイントがいずれかのゾーンの内部にあれば、オブジェクトは「ゾーン内」と見なされます。標準的なゾーン検出には CENTER を、地面レベルのゾーンには BOTTOM\_CENTER を（例：足元/車両の底部の追跡）、または検出ニーズに応じて他のアンカーを使用してください。デフォルトは 'CENTER' です..
  * `remove_out_of_zone_detections` ([*`boolean`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/boolean.md)）：True の場合（デフォルト）、すべてのゾーン外で見つかった検出は除外され、出力に含まれません。少なくとも1つのゾーン内にある検出のみが返されます。False の場合、すべての検出が出力に含まれ、すべてのゾーン外にあるオブジェクトには time\_in\_zone = 0 が設定されます。いずれかのゾーン内のオブジェクトだけに分析を集中させるには True を、ゾーン状態を保持しながらすべての検出を維持するには False を使用します。複数のゾーンが与えられた場合、オブジェクトはどれかのゾーンに存在すれば「ゾーン内」と見なされます。ゾーンの活動に焦点を当てた、よりすっきりした出力のためのデフォルトは True です..
  * `reset_out_of_zone_detections` ([*`boolean`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/boolean.md)）：True の場合（デフォルト）、追跡オブジェクトがすべてのゾーンを離れると、その時間追跡はリセットされます（入場タイムスタンプがクリアされます）。オブジェクトがいずれかのゾーンに再入場すると、時間追跡は再び 0 から始まります。False の場合、すべてのゾーンを離れた後も時間追跡は継続され、再入場時には累積時間が保持されます。現在の継続的なゾーン内時間を測定するには True（すべてのゾーン退出時にリセット）、複数回の入場にわたる累積時間を測定するには False を使用します。複数のゾーンが与えられた場合、時間はオブジェクトがすべてのゾーンを離れたときにのみリセットされます。継続的な存在継続時間を測定するためのデフォルトは True です..
* output
  * `timed_detections` (*Union\[*[*`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(...)オブジェクト形式で持つ予測、もし `object_detection_prediction` 、または検出されたバウンディングボックスとセグメンテーションマスクをsv.Detections(...)オブジェクト形式で持つ予測、もし `instance_segmentation_prediction`.

</details>

<details>

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

```json
{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/time_in_zone@v3",
	    "image": "$inputs.image",
	    "detections": "$steps.object_detection_model.predictions",
	    "zone": [
	        [
	            100,
	            100
	        ],
	        [
	            100,
	            200
	        ],
	        [
	            300,
	            200
	        ],
	        [
	            300,
	            100
	        ]
	    ],
	    "triggering_anchor": "CENTER",
	    "remove_out_of_zone_detections": true,
	    "reset_out_of_zone_detections": true
	}
```

</details>

## v2

1つの定義済みポリゴンゾーン内で追跡オブジェクトが費やした時間を計算して追跡し、特定の領域におけるオブジェクトの存在時間を測定し、ゾーン所属に基づいて検出をフィルタリングし、オブジェクトがゾーンを離れたときに時間追跡をリセットし、ゾーンベースの分析、滞在時間分析、存在監視のワークフローを有効にします。

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

このブロックは、各固有の track ID ごとの入退場時刻を追跡することで、各追跡オブジェクトが定義済みのポリゴンゾーン内にどれだけの時間いたかを測定します。このブロックは次のとおりです。

1. track ID を持つ追跡済み検出予測、埋め込みビデオメタデータを含む画像、およびポリゴンゾーン定義を受け取ります
2. 画像から動画メタデータを抽出します:
   * WorkflowImageData オブジェクトから video\_metadata にアクセスします
   * fps、frame\_number、frame\_timestamp、video\_identifier、およびビデオソース情報を抽出します
   * video\_identifier を使用して、異なるビデオごとに個別の追跡状態を維持します
3. 検出に track ID があることを検証します（tracker\_id が存在している必要があります）：
   * 追跡ブロック（例：Byte Tracker）からの検出を必要とします
   * 各オブジェクトは、フレーム間で保持される一意の tracker\_id を持っている必要があります
   * tracker\_id がない場合はエラーを発生させます
4. ビデオのポリゴンゾーンを初期化または取得します：
   * 各固有のビデオごとに、ゾーン座標から PolygonZone オブジェクトを作成します
   * ゾーン座標を検証します（少なくとも3点のリストでなければならず、各点は2つの座標を持つ必要があります）
   * video\_identifier を使用してビデオごとにゾーン設定を保存します
   * ゾーン検出用のトリガーアンカー点（例：CENTER、BOTTOM\_CENTER）を設定します
5. ビデオの時間追跡状態を初期化または取得します：
   * 各 track\_id がゾーンに入ったタイミングを追跡する辞書を維持します
   * video\_identifier を使用して、ビデオごとに入場タイムスタンプを保存します
   * ビデオごとに個別の追跡状態を維持します
6. 時間計測のための現在のタイムスタンプを計算します：
   * ビデオファイルの場合：timestamp を frame\_number / fps として計算します
   * ストリーミングビデオの場合：メタデータの frame\_timestamp を使用します
   * 継続時間計算のために正確な時間計測を提供します
7. どの検出がゾーン内にあるかを確認します：
   * ポリゴンゾーントリガーを使用して、各検出のアンカーポイントがゾーン内にあるかをテストします
   * triggering\_anchor は、どのバウンディングボックス上の点をチェックするかを決定します（CENTER、BOTTOM\_CENTER など）
   * 各検出について、ゾーン所属を示すブール値を返します
8. 各追跡オブジェクトの時間追跡を更新します：
   * **ゾーンに入るオブジェクトについて**: まだ追跡されていなければ入場タイムスタンプを記録します
   * **ゾーン内のオブジェクトについて**: 経過時間を current\_timestamp - entry\_timestamp として計算します
   * **ゾーンを離れるオブジェクトについて**:
     * reset\_out\_of\_zone\_detections が True の場合: 入場タイムスタンプを削除します（0 にリセット）
     * reset\_out\_of\_zone\_detections が False の場合: 入場タイムスタンプを保持します（追跡を継続）
9. ゾーン外検出を処理します：
   * **remove\_out\_of\_zone\_detections が True の場合**: 出力からゾーン外の検出を除外します
   * **remove\_out\_of\_zone\_detections が False の場合**: ゾーン外の検出を time = 0 で含めます
10. 各検出に time\_in\_zone 情報を追加します：
    * 各検出に time\_in\_zone の値（秒単位）をメタデータとして付与します
    * ゾーン内のオブジェクト: 時間はゾーン内で費やした継続時間を表します
    * ゾーン外のオブジェクト: 時間は 0（リセットされていない場合）または未定義（削除された場合）です
11. time\_in\_zone 情報付きの検出を返します：
    * time\_in\_zone メタデータで強化された追跡済み検出を出力します
    * remove\_out\_of\_zone\_detections 設定に応じてフィルタリングまたは非フィルタリングです
    * すべての元の検出プロパティに加えて、時間追跡情報を保持します

このブロックはフレーム間で永続的な追跡状態を維持し、複数フレームにわたってゾーン内に留まるオブジェクトの正確な累積時間測定を可能にします。時間は、オブジェクトが（track\_id に基づいて）最初にゾーンに入った時点から現在のフレームまで測定され、リアルタイムの継続時間追跡を提供します。ゾーンは複数の点を持つポリゴンとして定義されており、柔軟な領域定義が可能です。triggering\_anchor は、ゾーン検出に使用するバウンディングボックスのどの部分を使うかを決定し、オブジェクトの位置に基づいた異なるゾーン入退場動作を可能にします。

## 一般的な使用例

* **滞在時間分析**: 行動分析のために、オブジェクトが特定の領域にどれだけ留まるかを測定します（例：店舗の売場での顧客滞在時間の測定、駐車スペースでの滞在時間の追跡、待機エリアでの時間分析）。滞在時間分析ワークフローを可能にします
* **ゾーンベースの監視**: セキュリティと安全のために、定義済みの領域におけるオブジェクトの存在を監視します（例：制限区域での徘徊検出、危険ゾーンでの時間監視、安全区域での存在追跡）。ゾーン監視ワークフローを可能にします
* **小売分析**: 小売インサイトのために、異なる売場セクションでの顧客の滞在時間を追跡します（例：商品通路での時間測定、買い物パターンの分析、売場ごとのエンゲージメントの追跡）。小売分析ワークフローを可能にします
* **占有管理**: 空間利用のために、オブジェクトがスペースで費やす時間を測定します（例：車両の駐車時間の追跡、テーブル占有時間の測定、空間使用パターンの分析）。占有管理ワークフローを可能にします
* **安全コンプライアンス**: 制限区域または時間制限付きゾーンでの時間違反を監視します（例：危険区域での長時間滞在の検出、時間制限違反の監視、安全コンプライアンスの追跡）。安全監視ワークフローを可能にします
* **交通分析**: 交通ゾーンや交差点で車両が費やす時間を測定します（例：交差点での滞在時間の追跡、待ち行列の待機時間の測定、交通流パターンの分析）。交通分析ワークフローを可能にします

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

このブロックは、埋め込みビデオメタデータ、追跡済み検出、およびゾーン座標を含む画像を受け取り、time\_in\_zone メタデータ付きの timed\_detections を生成します：

* **Byte Tracker ブロックの後** 追跡オブジェクトの時間を測定するために（例：追跡オブジェクトのゾーン内時間の追跡、一貫した ID による滞在時間の測定、追跡オブジェクトの存在分析）、tracking-to-time ワークフローを可能にします
* **ゾーン定義ブロックの後に** 定義済みの領域に時間追跡を適用するために（例：ポリゴンゾーンでの時間測定、カスタムゾーンでの継続時間の追跡、ゾーンベースの存在分析）、zone-to-time ワークフローを可能にします
* **ロジックブロックの前** Continue If のように、ゾーン内時間に基づいて判断するために（例：時間がしきい値を超えた場合に継続する、滞在時間に基づいてフィルタする、時間違反時にアクションをトリガーする）、時間ベースの判断ワークフローを可能にします
* **分析ブロックの前に** 時間ベースの指標を分析するために（例：滞在時間パターンの分析、time-in-zone データの処理、継続時間指標の取り扱い）、時間分析ワークフローを可能にします
* **通知ブロックの前に** 時間違反やしきい値を通知するために（例：長時間滞在の警告、時間制限違反の通知、時間ベースのアラートのトリガー）、時間ベースの通知ワークフローを可能にします
* **データ保存ブロックの前に** 時間指標を記録するために（例：滞在時間データの保存、time-in-zone 指標のログ記録、継続時間測定の記録）、時間指標のログ記録ワークフローを可能にします

## バージョンの違い

**v1 からの強化点：**

* **簡素化された入力**: `image` 埋め込みビデオメタデータを含む `メタデータ` 入力を使用し、別個の
* **統合の改善**: 画像オブジェクトから直接ビデオメタデータにアクセスできるため、画像ベースのワークフローとの統合が向上し、別個のメタデータ入力を必要としません
* **ワークフローの簡略化**: 必要な入力数を減らし、画像とメタデータが同じソースから来るワークフローへの接続を容易にします

## 要件

このブロックは、tracker\_id 情報を含む追跡済み検出を必要とします（検出は Byte Tracker のような追跡ブロックから来る必要があります）。ゾーンは少なくとも3点のリストとして定義され、各点はちょうど2つの座標（x, y）を持つリストまたはタプルでなければなりません。画像の video\_metadata には、正確な時間測定を計算するために、ビデオファイルの場合はフレームレート（fps）、ストリーミングビデオの場合はフレームタイムスタンプを含める必要があります。このブロックは各ビデオのフレーム間で永続的な追跡状態を維持するため、フレームを順次処理するビデオワークフローで使用する必要があります。正確な時間測定のため、検出は有効な track ID とともにフレーム間で一貫して提供される必要があります。

### タイプ識別子

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

### プロパティ

| **名前**                          | **型**       | **説明**                                                                                                                                                                                                                                                                                                                                                                                               | 参照 |
| ------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| `name`                          | `str`       | このステップの一意の識別子を入力してください。                                                                                                                                                                                                                                                                                                                                                                              | ❌  |
| `zone`                          | `List[Any]` | 時間測定のための領域を定義するポリゴンゾーン座標。少なくとも3点のリストでなければならず、各点はちょうど2つの座標 \[x, y] または (x, y) を持つリストまたはタプルです。座標は画像サイズに一致するピクセル空間である必要があります。例: 四角形ゾーン \[(100, 100), (100, 200), (300, 200), (300, 100)]。ゾーンは、時間追跡が行われるポリゴン領域を定義します。オブジェクトは、triggering\_anchor 点がこのポリゴン内にあるときに「ゾーン内」と見なされます。ゾーン座標は検証され、各ビデオに対して PolygonZone オブジェクトが作成されます..                                                                             | ✅  |
| `triggering_anchor`             | `str`       | オブジェクトを「ゾーン内」と見なすために、検出バウンディングボックス上でゾーン内にある必要がある点。オプションには、'CENTER'（デフォルト、バウンディングボックスの中心）、'BOTTOM\_CENTER'（下中央点）、'TOP\_CENTER'（上中央点）、'CENTER\_LEFT'（中央左点）、'CENTER\_RIGHT'（中央右点）、およびその他の Position enum 値が含まれます。triggering\_anchor は、オブジェクトのバウンディングボックスのどの部分をゾーンポリゴンに対してチェックするかを決定します。標準的なゾーン検出には CENTER を、地面レベルのゾーンには BOTTOM\_CENTER を（例：足元/車両の底部の追跡）、または検出ニーズに応じて他のアンカーを使用してください。デフォルトは 'CENTER' です.. | ✅  |
| `remove_out_of_zone_detections` | `bool`      | True の場合（デフォルト）、ゾーン外で見つかった検出は除外され、出力に含まれません。ゾーン内の検出のみが返されます。False の場合、すべての検出が出力に含まれ、ゾーン外のオブジェクトには time\_in\_zone = 0 が設定されます。ゾーン内のオブジェクトだけに分析を集中させるには True を、ゾーン状態を保持しながらすべての検出を維持するには False を使用します。デフォルトは、ゾーンの活動に焦点を当てた、よりすっきりした出力のための True です..                                                                                                                                                    | ✅  |
| `reset_out_of_zone_detections`  | `bool`      | True の場合（デフォルト）、追跡オブジェクトがゾーンを離れると、その時間追跡はリセットされます（入場タイムスタンプがクリアされます）。オブジェクトがゾーンに再入場すると、時間追跡は再び 0 から始まります。False の場合、ゾーンを離れた後も時間追跡は継続され、再入場時には累積時間が保持されます。現在のゾーン内継続時間を測定するには True（退出時にリセット）、複数回の入場にわたる累積時間を測定するには False を使用します。デフォルトは、継続的な存在継続時間を測定するための True です..                                                                                                                                     | ✅  |

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

### 実行時互換性

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

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

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

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

<details>

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

* input
  * `image` ([*`image`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/image.md)）：時間計算と状態管理に必要な、埋め込みビデオメタデータ（fps、frame\_number、frame\_timestamp、video\_identifier、video source）を含む現在のビデオフレーム用の入力画像です。このブロックは WorkflowImageData オブジェクトから video\_metadata を抽出します。fps と frame\_number は、ビデオファイルのタイムスタンプを計算するために使用されます（timestamp = frame\_number / fps）。ストリーミングビデオでは frame\_timestamp が直接使用されます。video\_identifier は、異なるビデオごとに個別の追跡状態とゾーン設定を維持するために使用されます。ゾーンの可視化と参照に使用されます。画像の寸法はゾーン座標の検証に使用されます。このバージョンは、別個のメタデータフィールドを必要とする代わりに、メタデータを画像オブジェクトに埋め込むことで入力を簡略化しています。..
  * `detections` (*Union\[*[*`instance_segmentation_prediction`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/instance-segmentation-prediction.md)*,* [*`object_detection_prediction`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)*]*）：tracker\_id 情報を含む追跡済み検出予測（物体検出またはインスタンスセグメンテーション）です。検出は、フレーム間で保持される一意の tracker\_id 値を割り当てた追跡ブロック（例：Byte Tracker）から来る必要があります。各検出は時間追跡を可能にするために tracker\_id を持っている必要があります。このブロックは、各追跡オブジェクトについて、その track\_id が最初にゾーンに入った時点に基づいて time\_in\_zone を計算します。出力には、time\_in\_zone メタデータ（秒単位の継続時間）で強化された同じ検出が含まれます。remove\_out\_of\_zone\_detections が True の場合、ゾーン内の検出のみが出力に含まれます。..
  * `zone` ([*`list_of_values`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/list-of-values.md)）：時間測定のための領域を定義するポリゴンゾーン座標。少なくとも3点のリストでなければならず、各点はちょうど2つの座標 \[x, y] または (x, y) を持つリストまたはタプルです。座標は画像サイズに一致するピクセル空間である必要があります。例: 四角形ゾーン \[(100, 100), (100, 200), (300, 200), (300, 100)]。ゾーンは、時間追跡が行われるポリゴン領域を定義します。オブジェクトは、triggering\_anchor 点がこのポリゴン内にあるときに「ゾーン内」と見なされます。ゾーン座標は検証され、各ビデオに対して PolygonZone オブジェクトが作成されます..
  * `triggering_anchor` ([*`string`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/string.md)）：オブジェクトを「ゾーン内」と見なすために、検出バウンディングボックス上でゾーン内にある必要がある点。オプションには、'CENTER'（デフォルト、バウンディングボックスの中心）、'BOTTOM\_CENTER'（下中央点）、'TOP\_CENTER'（上中央点）、'CENTER\_LEFT'（中央左点）、'CENTER\_RIGHT'（中央右点）、およびその他の Position enum 値が含まれます。triggering\_anchor は、オブジェクトのバウンディングボックスのどの部分をゾーンポリゴンに対してチェックするかを決定します。標準的なゾーン検出には CENTER を、地面レベルのゾーンには BOTTOM\_CENTER を（例：足元/車両の底部の追跡）、または検出ニーズに応じて他のアンカーを使用してください。デフォルトは 'CENTER' です..
  * `remove_out_of_zone_detections` ([*`boolean`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/boolean.md)True の場合（デフォルト）、ゾーン外で見つかった検出は除外され、出力に含まれません。ゾーン内の検出のみが返されます。False の場合、すべての検出が出力に含まれ、ゾーン外のオブジェクトには time\_in\_zone = 0 が設定されます。ゾーン内のオブジェクトだけに分析を集中させるには True を、ゾーン状態を保持しながらすべての検出を維持するには False を使用します。デフォルトは、ゾーンの活動に焦点を当てた、よりすっきりした出力のための True です..
  * `reset_out_of_zone_detections` ([*`boolean`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/boolean.md)True の場合（デフォルト）、追跡オブジェクトがゾーンを離れると、その時間追跡はリセットされます（入場タイムスタンプがクリアされます）。オブジェクトがゾーンに再入場すると、時間追跡は再び 0 から始まります。False の場合、ゾーンを離れた後も時間追跡は継続され、再入場時には累積時間が保持されます。現在のゾーン内継続時間を測定するには True（退出時にリセット）、複数回の入場にわたる累積時間を測定するには False を使用します。デフォルトは、継続的な存在継続時間を測定するための True です..
* output
  * `timed_detections` (*Union\[*[*`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(...)オブジェクト形式で持つ予測、もし `object_detection_prediction` 、または検出されたバウンディングボックスとセグメンテーションマスクをsv.Detections(...)オブジェクト形式で持つ予測、もし `instance_segmentation_prediction`.

</details>

<details>

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

```json
{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/time_in_zone@v2",
	    "image": "$inputs.image",
	    "detections": "$steps.object_detection_model.predictions",
	    "zone": [
	        [
	            100,
	            100
	        ],
	        [
	            100,
	            200
	        ],
	        [
	            300,
	            200
	        ],
	        [
	            300,
	            100
	        ]
	    ],
	    "triggering_anchor": "CENTER",
	    "remove_out_of_zone_detections": true,
	    "reset_out_of_zone_detections": true
	}
```

</details>

## v1

1つの定義済みポリゴンゾーン内で追跡オブジェクトが費やした時間を計算して追跡し、特定の領域におけるオブジェクトの存在時間を測定し、ゾーン所属に基づいて検出をフィルタリングし、オブジェクトがゾーンを離れたときに時間追跡をリセットし、ゾーンベースの分析、滞在時間分析、存在監視のワークフローを有効にします。

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

このブロックは、各固有の track ID ごとの入退場時刻を追跡することで、各追跡オブジェクトが定義済みのポリゴンゾーン内にどれだけの時間いたかを測定します。このブロックは次のとおりです。

1. track ID を持つ追跡済み検出予測、画像、ビデオメタデータ、およびポリゴンゾーン定義を受け取ります
2. 検出に track ID があることを検証します（tracker\_id が存在している必要があります）：
   * 追跡ブロック（例：Byte Tracker）からの検出を必要とします
   * 各オブジェクトは、フレーム間で保持される一意の tracker\_id を持っている必要があります
   * tracker\_id がない場合はエラーを発生させます
3. ビデオのポリゴンゾーンを初期化または取得します：
   * 各固有のビデオごとに、ゾーン座標から PolygonZone オブジェクトを作成します
   * ゾーン座標を検証します（少なくとも3点のリストでなければならず、各点は2つの座標を持つ必要があります）
   * video\_identifier を使用してビデオごとにゾーン設定を保存します
   * ゾーン検出用のトリガーアンカー点（例：CENTER、BOTTOM\_CENTER）を設定します
4. ビデオの時間追跡状態を初期化または取得します：
   * 各 track\_id がゾーンに入ったタイミングを追跡する辞書を維持します
   * video\_identifier を使用して、ビデオごとに入場タイムスタンプを保存します
   * ビデオごとに個別の追跡状態を維持します
5. 時間計測のための現在のタイムスタンプを計算します：
   * ビデオファイルの場合：timestamp を frame\_number / fps として計算します
   * ストリーミングビデオの場合：メタデータの frame\_timestamp を使用します
   * 継続時間計算のために正確な時間計測を提供します
6. どの検出がゾーン内にあるかを確認します：
   * ポリゴンゾーントリガーを使用して、各検出のアンカーポイントがゾーン内にあるかをテストします
   * triggering\_anchor は、どのバウンディングボックス上の点をチェックするかを決定します（CENTER、BOTTOM\_CENTER など）
   * 各検出について、ゾーン所属を示すブール値を返します
7. 各追跡オブジェクトの時間追跡を更新します：
   * **ゾーンに入るオブジェクトについて**: まだ追跡されていなければ入場タイムスタンプを記録します
   * **ゾーン内のオブジェクトについて**: 経過時間を current\_timestamp - entry\_timestamp として計算します
   * **ゾーンを離れるオブジェクトについて**:
     * reset\_out\_of\_zone\_detections が True の場合: 入場タイムスタンプを削除します（0 にリセット）
     * reset\_out\_of\_zone\_detections が False の場合: 入場タイムスタンプを保持します（追跡を継続）
8. ゾーン外検出を処理します：
   * **remove\_out\_of\_zone\_detections が True の場合**: 出力からゾーン外の検出を除外します
   * **remove\_out\_of\_zone\_detections が False の場合**: ゾーン外の検出を time = 0 で含めます
9. 各検出に time\_in\_zone 情報を追加します：
   * 各検出に time\_in\_zone の値（秒単位）をメタデータとして付与します
   * ゾーン内のオブジェクト: 時間はゾーン内で費やした継続時間を表します
   * ゾーン外のオブジェクト: 時間は 0（リセットされていない場合）または未定義（削除された場合）です
10. time\_in\_zone 情報付きの検出を返します：
    * time\_in\_zone メタデータで強化された追跡済み検出を出力します
    * remove\_out\_of\_zone\_detections 設定に応じてフィルタリングまたは非フィルタリングです
    * すべての元の検出プロパティに加えて、時間追跡情報を保持します

このブロックはフレーム間で永続的な追跡状態を維持し、複数フレームにわたってゾーン内に留まるオブジェクトの正確な累積時間測定を可能にします。時間は、オブジェクトが（track\_id に基づいて）最初にゾーンに入った時点から現在のフレームまで測定され、リアルタイムの継続時間追跡を提供します。ゾーンは複数の点を持つポリゴンとして定義されており、柔軟な領域定義が可能です。triggering\_anchor は、ゾーン検出に使用するバウンディングボックスのどの部分を使うかを決定し、オブジェクトの位置に基づいた異なるゾーン入退場動作を可能にします。

## 一般的な使用例

* **滞在時間分析**: 行動分析のために、オブジェクトが特定の領域にどれだけ留まるかを測定します（例：店舗の売場での顧客滞在時間の測定、駐車スペースでの滞在時間の追跡、待機エリアでの時間分析）。滞在時間分析ワークフローを可能にします
* **ゾーンベースの監視**: セキュリティと安全のために、定義済みの領域におけるオブジェクトの存在を監視します（例：制限区域での徘徊検出、危険ゾーンでの時間監視、安全区域での存在追跡）。ゾーン監視ワークフローを可能にします
* **小売分析**: 小売インサイトのために、異なる売場セクションでの顧客の滞在時間を追跡します（例：商品通路での時間測定、買い物パターンの分析、売場ごとのエンゲージメントの追跡）。小売分析ワークフローを可能にします
* **占有管理**: 空間利用のために、オブジェクトがスペースで費やす時間を測定します（例：車両の駐車時間の追跡、テーブル占有時間の測定、空間使用パターンの分析）。占有管理ワークフローを可能にします
* **安全コンプライアンス**: 制限区域または時間制限付きゾーンでの時間違反を監視します（例：危険区域での長時間滞在の検出、時間制限違反の監視、安全コンプライアンスの追跡）。安全監視ワークフローを可能にします
* **交通分析**: 交通ゾーンや交差点で車両が費やす時間を測定します（例：交差点での滞在時間の追跡、待ち行列の待機時間の測定、交通流パターンの分析）。交通分析ワークフローを可能にします

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

このブロックは、追跡済み検出、画像、ビデオメタデータ、およびゾーン座標を受け取り、time\_in\_zone メタデータ付きの timed\_detections を生成します：

* **Byte Tracker ブロックの後** 追跡オブジェクトの時間を測定するために（例：追跡オブジェクトのゾーン内時間の追跡、一貫した ID による滞在時間の測定、追跡オブジェクトの存在分析）、tracking-to-time ワークフローを可能にします
* **ゾーン定義ブロックの後に** 定義済みの領域に時間追跡を適用するために（例：ポリゴンゾーンでの時間測定、カスタムゾーンでの継続時間の追跡、ゾーンベースの存在分析）、zone-to-time ワークフローを可能にします
* **ロジックブロックの前** Continue If のように、ゾーン内時間に基づいて判断するために（例：時間がしきい値を超えた場合に継続する、滞在時間に基づいてフィルタする、時間違反時にアクションをトリガーする）、時間ベースの判断ワークフローを可能にします
* **分析ブロックの前に** 時間ベースの指標を分析するために（例：滞在時間パターンの分析、time-in-zone データの処理、継続時間指標の取り扱い）、時間分析ワークフローを可能にします
* **通知ブロックの前に** 時間違反やしきい値を通知するために（例：長時間滞在の警告、時間制限違反の通知、時間ベースのアラートのトリガー）、時間ベースの通知ワークフローを可能にします
* **データ保存ブロックの前に** 時間指標を記録するために（例：滞在時間データの保存、time-in-zone 指標のログ記録、継続時間測定の記録）、時間指標のログ記録ワークフローを可能にします

## 要件

このブロックは、tracker\_id 情報を含む追跡済み検出を必要とします（検出は Byte Tracker のような追跡ブロックから来る必要があります）。ゾーンは少なくとも3点のリストとして定義され、各点はちょうど2つの座標（x, y）を持つリストまたはタプルでなければなりません。このブロックは、正確な時間測定を計算するために、ビデオファイルの場合はフレームレート（fps）、ストリーミングビデオの場合はフレームタイムスタンプを含むビデオメタデータを必要とします。このブロックは各ビデオのフレーム間で永続的な追跡状態を維持するため、フレームを順次処理するビデオワークフローで使用する必要があります。正確な時間測定のため、検出は有効な track ID とともにフレーム間で一貫して提供される必要があります。

### タイプ識別子

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

### プロパティ

| **名前**                          | **型**       | **説明**                                                                                                                                                                                                                                                                                                                                                                                               | 参照 |
| ------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| `name`                          | `str`       | このステップの一意の識別子を入力してください。                                                                                                                                                                                                                                                                                                                                                                              | ❌  |
| `zone`                          | `List[Any]` | 時間測定のための領域を定義するポリゴンゾーン座標。少なくとも3点のリストでなければならず、各点はちょうど2つの座標 \[x, y] または (x, y) を持つリストまたはタプルです。座標は画像サイズに一致するピクセル空間である必要があります。例: 四角形ゾーン \[\[x1, y1], \[x2, y2], \[x3, y3], \[x4, y4]]。ゾーンは、時間追跡が行われるポリゴン領域を定義します。オブジェクトは、triggering\_anchor 点がこのポリゴン内にあるときに「ゾーン内」と見なされます。ゾーン座標は検証され、各ビデオに対して PolygonZone オブジェクトが作成されます..                                                                                 | ✅  |
| `triggering_anchor`             | `str`       | オブジェクトを「ゾーン内」と見なすために、検出バウンディングボックス上でゾーン内にある必要がある点。オプションには、'CENTER'（デフォルト、バウンディングボックスの中心）、'BOTTOM\_CENTER'（下中央点）、'TOP\_CENTER'（上中央点）、'CENTER\_LEFT'（中央左点）、'CENTER\_RIGHT'（中央右点）、およびその他の Position enum 値が含まれます。triggering\_anchor は、オブジェクトのバウンディングボックスのどの部分をゾーンポリゴンに対してチェックするかを決定します。標準的なゾーン検出には CENTER を、地面レベルのゾーンには BOTTOM\_CENTER を（例：足元/車両の底部の追跡）、または検出ニーズに応じて他のアンカーを使用してください。デフォルトは 'CENTER' です.. | ✅  |
| `remove_out_of_zone_detections` | `bool`      | True の場合（デフォルト）、ゾーン外で見つかった検出は除外され、出力に含まれません。ゾーン内の検出のみが返されます。False の場合、すべての検出が出力に含まれ、ゾーン外のオブジェクトには time\_in\_zone = 0 が設定されます。ゾーン内のオブジェクトだけに分析を集中させるには True を、ゾーン状態を保持しながらすべての検出を維持するには False を使用します。デフォルトは、ゾーンの活動に焦点を当てた、よりすっきりした出力のための True です..                                                                                                                                                    | ✅  |
| `reset_out_of_zone_detections`  | `bool`      | True の場合（デフォルト）、追跡オブジェクトがゾーンを離れると、その時間追跡はリセットされます（入場タイムスタンプがクリアされます）。オブジェクトがゾーンに再入場すると、時間追跡は再び 0 から始まります。False の場合、ゾーンを離れた後も時間追跡は継続され、再入場時には累積時間が保持されます。現在のゾーン内継続時間を測定するには True（退出時にリセット）、複数回の入場にわたる累積時間を測定するには 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)）：現在のビデオフレーム用の入力画像。ゾーンの可視化と参照に使用されます。このブロックは画像の寸法を使用してゾーン座標を検証します。フレームタイムスタンプが必要な場合、画像メタデータは時間計算に使用されることがあります。..
  * `メタデータ` ([*`video_metadata`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/video-metadata.md)）：時間計算と状態管理に必要な、フレームレート（fps）、フレーム番号、フレームタイムスタンプ、ビデオ識別子、およびビデオソース情報を含むビデオメタデータです。fps と frame\_number は、ビデオファイルのタイムスタンプを計算するために使用されます（timestamp = frame\_number / fps）。ストリーミングビデオでは frame\_timestamp が直接使用されます。video\_identifier は、異なるビデオごとに個別の追跡状態とゾーン設定を維持するために使用されます。メタデータには、正確な時間測定を可能にするために、ビデオファイルの場合は有効な fps、ストリームの場合は frame\_timestamp が含まれている必要があります。..
  * `detections` (*Union\[*[*`instance_segmentation_prediction`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/instance-segmentation-prediction.md)*,* [*`object_detection_prediction`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)*]*）：tracker\_id 情報を含む追跡済み検出予測（物体検出またはインスタンスセグメンテーション）です。検出は、フレーム間で保持される一意の tracker\_id 値を割り当てた追跡ブロック（例：Byte Tracker）から来る必要があります。各検出は時間追跡を可能にするために tracker\_id を持っている必要があります。このブロックは、各追跡オブジェクトについて、その track\_id が最初にゾーンに入った時点に基づいて time\_in\_zone を計算します。出力には、time\_in\_zone メタデータ（秒単位の継続時間）で強化された同じ検出が含まれます。remove\_out\_of\_zone\_detections が True の場合、ゾーン内の検出のみが出力に含まれます。..
  * `zone` ([*`list_of_values`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/list-of-values.md)）：時間測定のための領域を定義するポリゴンゾーン座標。少なくとも3点のリストでなければならず、各点はちょうど2つの座標 \[x, y] または (x, y) を持つリストまたはタプルです。座標は画像サイズに一致するピクセル空間である必要があります。例: 四角形ゾーン \[\[x1, y1], \[x2, y2], \[x3, y3], \[x4, y4]]。ゾーンは、時間追跡が行われるポリゴン領域を定義します。オブジェクトは、triggering\_anchor 点がこのポリゴン内にあるときに「ゾーン内」と見なされます。ゾーン座標は検証され、各ビデオに対して PolygonZone オブジェクトが作成されます..
  * `triggering_anchor` ([*`string`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/string.md)）：オブジェクトを「ゾーン内」と見なすために、検出バウンディングボックス上でゾーン内にある必要がある点。オプションには、'CENTER'（デフォルト、バウンディングボックスの中心）、'BOTTOM\_CENTER'（下中央点）、'TOP\_CENTER'（上中央点）、'CENTER\_LEFT'（中央左点）、'CENTER\_RIGHT'（中央右点）、およびその他の Position enum 値が含まれます。triggering\_anchor は、オブジェクトのバウンディングボックスのどの部分をゾーンポリゴンに対してチェックするかを決定します。標準的なゾーン検出には CENTER を、地面レベルのゾーンには BOTTOM\_CENTER を（例：足元/車両の底部の追跡）、または検出ニーズに応じて他のアンカーを使用してください。デフォルトは 'CENTER' です..
  * `remove_out_of_zone_detections` ([*`boolean`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/boolean.md)True の場合（デフォルト）、ゾーン外で見つかった検出は除外され、出力に含まれません。ゾーン内の検出のみが返されます。False の場合、すべての検出が出力に含まれ、ゾーン外のオブジェクトには time\_in\_zone = 0 が設定されます。ゾーン内のオブジェクトだけに分析を集中させるには True を、ゾーン状態を保持しながらすべての検出を維持するには False を使用します。デフォルトは、ゾーンの活動に焦点を当てた、よりすっきりした出力のための True です..
  * `reset_out_of_zone_detections` ([*`boolean`*](https://docs.roboflow.com/workflows/ja/gaido/developer-guide/kinds/boolean.md)True の場合（デフォルト）、追跡オブジェクトがゾーンを離れると、その時間追跡はリセットされます（入場タイムスタンプがクリアされます）。オブジェクトがゾーンに再入場すると、時間追跡は再び 0 から始まります。False の場合、ゾーンを離れた後も時間追跡は継続され、再入場時には累積時間が保持されます。現在のゾーン内継続時間を測定するには True（退出時にリセット）、複数回の入場にわたる累積時間を測定するには False を使用します。デフォルトは、継続的な存在継続時間を測定するための True です..
* output
  * `timed_detections` (*Union\[*[*`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(...)オブジェクト形式で持つ予測、もし `object_detection_prediction` 、または検出されたバウンディングボックスとセグメンテーションマスクをsv.Detections(...)オブジェクト形式で持つ予測、もし `instance_segmentation_prediction`.

</details>

<details>

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

```json
{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/time_in_zone@v1",
	    "image": "$inputs.image",
	    "metadata": "<block_does_not_provide_example>",
	    "detections": "$steps.object_detection_model.predictions",
	    "zone": "$inputs.zones",
	    "triggering_anchor": "CENTER",
	    "remove_out_of_zone_detections": true,
	    "reset_out_of_zone_detections": true
	}
```

</details>
