Sync loitering-detection from metro-analytics-catalog

LICENSE

@@ -29,17 +29,17 @@ MIT License.
     THE SOFTWARE.
 
 
-YOLO11 Model
+YOLO26 Model
 ------------
 
-The YOLO11 model weights and the Ultralytics framework are developed by
+The YOLO26 model weights and the Ultralytics framework are developed by
 Ultralytics and licensed under the GNU Affero General Public License v3.0
 (AGPL-3.0).
 
     Source:  https://github.com/ultralytics/ultralytics
     License: https://github.com/ultralytics/ultralytics/blob/main/LICENSE
-    Docs:    https://docs.ultralytics.com/models/yolo11/
+    Docs:    https://docs.ultralytics.com/models/yolo26/
 
 Users must comply with the AGPL-3.0 license terms when using, modifying,
-or distributing the YOLO11 model weights or Ultralytics software.
+or distributing the YOLO26 model weights or Ultralytics software.
 For commercial licensing options, see https://www.ultralytics.com/license.

README.md

@@ -1,14 +1,12 @@
-# Loitering Detection -- Zone-Based Dwell Time on Intel Hardware
+# Loitering Detection
 
-> **Reference notebook:** [yolov11-object-detection.ipynb](https://github.com/openvinotoolkit/openvino_notebooks/blob/latest/notebooks/yolov11-optimization/yolov11-object-detection.ipynb)
->
-> **Validated with:** OpenVINO 2026.0.0, NNCF 3.0.0, Ultralytics 8.3.0, Python 3.11+
+> **Validated with:** OpenVINO 2026.0.0, NNCF 3.0.0, DLStreamer 2026.0, Ultralytics 8.3.0, Python 3.11+
 
 | Property | Value |
 |---|---|
 | **Category** | Object Detection + Tracking + Zone Analytics |
 | **Source Framework** | PyTorch (Ultralytics) |
-| **Supported Precisions** | FP16, FP16-INT8 |
+| **Supported Precisions** | FP32, FP16, FP16-INT8 |
 | **Inference Engine** | OpenVINO |
 | **Hardware** | CPU, GPU, NPU |
 | **Detected Class** | `person` (COCO class 0) |
@@ -18,7 +16,7 @@
 ## Overview
 
 Loitering Detection is a Metro Analytics use case that flags people who remain inside a configurable region of interest for longer than a dwell-time threshold.
-It is built on [YOLO11](https://docs.ultralytics.com/models/yolo11/) for person detection, paired with a multi-object tracker that assigns persistent IDs across frames.
+It is built on [YOLO26](https://docs.ultralytics.com/models/yolo26/) for person detection, paired with a multi-object tracker that assigns persistent IDs across frames.
 A polygon zone defines the area to monitor; for each tracked person whose bounding-box anchor falls inside the zone, the application accumulates dwell time and raises a loitering event when the threshold is exceeded.
 
 Typical Metro deployments include:
@@ -28,15 +26,23 @@ Typical Metro deployments include:
 - **ATM and Ticketing Security** -- identify suspicious dwell at unattended kiosks.
 - **Crowd-Free Zone Enforcement** -- monitor emergency exits and corridors that must remain clear.
 
-Available variants: `yolo11n`, `yolo11s`, `yolo11m`, `yolo11l`, `yolo11x`.
-Smaller variants (`yolo11n`, `yolo11s`) are recommended for high-FPS edge deployment.
+Available variants: `yolo26n`, `yolo26s`, `yolo26m`, `yolo26l`, `yolo26x`.
+Smaller variants (`yolo26n`, `yolo26s`) are recommended for high-FPS edge deployment.
 
 ---
 
 ## Prerequisites
 
+- Python 3.11+
 - [Install OpenVINO 2026.0.0](https://docs.openvino.ai/2026/get-started/install-openvino.html)
-- [Install Intel DLStreamer](https://dlstreamer.github.io/get_started/install/install-guide-ubuntu.html)
+- [Install Intel DLStreamer](https://docs.openedgeplatform.intel.com/2026.0/edge-ai-libraries/dlstreamer/get_started/install/install_guide_ubuntu.html)
+
+Create and activate a Python virtual environment before running the scripts:
+
+```bash
+python3 -m venv .venv --system-site-packages
+source .venv/bin/activate
+```
 
 ---
 
@@ -44,26 +50,37 @@ Smaller variants (`yolo11n`, `yolo11s`) are recommended for high-FPS edge deploy
 
 ### Download and Quantize Model
 
-Run the provided script to download, export to OpenVINO IR (FP16), and quantize to INT8:
+Run the provided script to download, export to OpenVINO IR, and optionally quantize:
 
 ```bash
 chmod +x export_and_quantize.sh
-./export_and_quantize.sh yolo11n
+./export_and_quantize.sh yolo26n        # default: FP16
+./export_and_quantize.sh yolo26n FP32   # full-precision
+./export_and_quantize.sh yolo26n INT8   # quantized
 ```
 
-Replace `yolo11n` with any variant (`yolo11s`, `yolo11m`, `yolo11l`, `yolo11x`).
+Replace `yolo26n` with any variant (`yolo26s`, `yolo26m`, `yolo26l`, `yolo26x`).
+The second argument selects the precision (`FP32`, `FP16`, `INT8`); the default is **FP16**.
 
 The script performs the following steps:
 
-1. Installs dependencies (`openvino`, `nncf`, `ultralytics`).
-2. Downloads the PyTorch weights and exports to OpenVINO IR with `half=True`.
-3. Quantizes the model to INT8 using NNCF post-training quantization.
-4. Runs `benchmark_app` to validate throughput.
+1. Installs dependencies (`openvino`, `ultralytics`; adds `nncf` for INT8).
+2. Downloads the sample surveillance video (`VIRAT_S_000101.mp4`) from the Intel Metro AI Suite project into the current directory.
+3. Downloads the PyTorch weights and exports to OpenVINO IR.
+4. *(INT8 only)* Quantizes the model using NNCF post-training quantization.
 
 Output files:
 
-- `yolo11n_openvino_model/` -- FP16 OpenVINO IR model directory.
-- `yolo11n_loitering_int8.xml` / `yolo11n_loitering_int8.bin` -- INT8 quantized model.
+- `yolo26n_openvino_model/` -- FP32 or FP16 OpenVINO IR model directory.
+- `yolo26n_loitering_int8.xml` / `yolo26n_loitering_int8.bin` -- INT8 quantized model *(only when `INT8` is selected)*.
+
+#### Precision / Device Compatibility
+
+| Precision | CPU | GPU | NPU |
+|---|---|---|---|
+| FP32 | Yes | Yes | No |
+| FP16 | Yes | Yes | Yes |
+| INT8 | Yes | Yes | Yes |
 
 > **Note:** For production accuracy, replace the random calibration tensors in
 > `export_and_quantize.sh` with a representative sample of frames from the
@@ -71,13 +88,16 @@ Output files:
 
 ### Defining the Region of Interest
 
-The zone is a list of pixel-space `(x, y)` polygon vertices in clockwise order,
-expressed in the original input frame coordinates (not the 640x640 model input).
-A typical platform-edge zone might be:
+The zone is a rectangular ROI expressed as `x_min,y_min,x_max,y_max` in the
+original input frame coordinates (not the 640x640 model input).
+DLStreamer's `gvaattachroi` element attaches the ROI to every buffer, and
+`gvadetect inference-region=1` (`roi-list`) restricts inference to that ROI
+only -- no Python polygon math required.
+A typical surveillance-zone configuration on a 1280x720 source might be:
 
-```python
-ZONE_POLYGON = [(420, 380), (1500, 380), (1500, 540), (420, 540)]
-LOITERING_SECONDS = 10.0
+```text
+roi=400,200,1100,650          # ROI for gvaattachroi (x_min,y_min,x_max,y_max)
+LOITERING_SECONDS = 5.0       # dwell threshold, in seconds
 ```
 
 Per-person dwell time is measured at the bottom-center of the bounding box
@@ -85,63 +105,21 @@ Per-person dwell time is measured at the bottom-center of the bounding box
 
 ### DLStreamer Sample
 
-The sample below runs the YOLO11 detector via `gvadetect`, attaches persistent
-track IDs with `gvatrack`, and uses the DLStreamer Python bindings
-(`gstgva.VideoFrame`) to filter `person` regions, test whether each tracked
-person's foot anchor lies inside the zone polygon, accumulate dwell time per
-`object_id`, and print a loitering event when the threshold is exceeded.
-
-> **Notes on running this sample:**
->
-> - Use the FP16 IR (`yolo11n_openvino_model/yolo11n.xml`).
->   On DLStreamer 2026.0.0, `gvadetect` cannot auto-derive a YOLO post-processor
->   from the INT8 model produced by the bundled script (the quantize/dequantize
->   layers shift the output node names away from the names the auto-postproc
->   expects).
->   To use the INT8 model, supply a matching `model-proc` JSON.
-> - `gvadetect` requires `labels-file=` to map class indices to names. The
->   sample creates a `coco.txt` next to the script.
-> - Filtering with `object-class=person` directly on `gvadetect` is rejected
->   when `inference-region` is `full-frame` (the default), so the sample
->   filters by `region.label()` in the buffer probe instead.
-> - The DLStreamer Python module is not on `sys.path` by default. Export
->   `PYTHONPATH` before running:
->
->   ```bash
->   source /opt/intel/openvino_2026/setupvars.sh
->   source /opt/intel/dlstreamer/scripts/setup_dls_env.sh
->   export PYTHONPATH=/opt/intel/dlstreamer/python:\
->   /opt/intel/dlstreamer/gstreamer/lib/python3/dist-packages:${PYTHONPATH:-}
->   ```
-
-Create the COCO labels file once (one class per line, in COCO order):
+- The DLStreamer Python module is not on `sys.path` by default. Export `PYTHONPATH` before running:
 
 ```bash
-python3 - <<'PY'
-names = [
-    "person","bicycle","car","motorcycle","airplane","bus","train","truck",
-    "boat","traffic light","fire hydrant","stop sign","parking meter","bench",
-    "bird","cat","dog","horse","sheep","cow","elephant","bear","zebra",
-    "giraffe","backpack","umbrella","handbag","tie","suitcase","frisbee",
-    "skis","snowboard","sports ball","kite","baseball bat","baseball glove",
-    "skateboard","surfboard","tennis racket","bottle","wine glass","cup",
-    "fork","knife","spoon","bowl","banana","apple","sandwich","orange",
-    "broccoli","carrot","hot dog","pizza","donut","cake","chair","couch",
-    "potted plant","bed","dining table","toilet","tv","laptop","mouse",
-    "remote","keyboard","cell phone","microwave","oven","toaster","sink",
-    "refrigerator","book","clock","vase","scissors","teddy bear","hair drier",
-    "toothbrush",
-]
-open("coco.txt", "w").write("\n".join(names))
-PY
+source /opt/intel/openvino_2026/setupvars.sh
+source /opt/intel/dlstreamer/scripts/setup_dls_env.sh
+export PYTHONPATH=/opt/intel/dlstreamer/python:\
+/opt/intel/dlstreamer/gstreamer/lib/python3/dist-packages:${PYTHONPATH:-}
 ```
 
+**Video-based loitering detection** (requires video for dwell-time tracking):
+
 ```python
 from collections import defaultdict
 
-import cv2
 import gi
-import numpy as np
 
 gi.require_version("Gst", "1.0")
 gi.require_version("GstVideo", "1.0")
@@ -150,21 +128,22 @@ from gstgva import VideoFrame
 
 Gst.init(None)
 
-MODEL_XML = "yolo11n_openvino_model/yolo11n.xml"
-LABELS_FILE = "coco.txt"
-INPUT_VIDEO = "test_video.mp4"
-ZONE_POLYGON = np.array(
-    [(420, 380), (1500, 380), (1500, 540), (420, 540)], dtype=np.int32,
-)
-LOITERING_SECONDS = 10.0
+MODEL_XML = "yolo26n_openvino_model/yolo26n.xml"
+INPUT_VIDEO = "VIRAT_S_000101.mp4"
+ROI = "0,200,300,400"  # x_min,y_min,x_max,y_max
+LOITERING_SECONDS = 5.0
 
 pipeline_str = (
-    f"filesrc location={INPUT_VIDEO} ! decodebin ! videoconvert ! "
-    f"video/x-raw,format=BGR ! "
-    f"gvadetect model={MODEL_XML} labels-file={LABELS_FILE} device=CPU "
-    f"threshold=0.4 ! queue ! "
+    f"filesrc location={INPUT_VIDEO} ! decodebin3 ! "
+    f"gvaattachroi roi={ROI} ! "
+    f"gvadetect inference-region=1 model={MODEL_XML} device=CPU "
+    f"threshold=0.5 ! queue ! "
     f"gvatrack tracking-type=short-term-imageless ! queue ! "
-    f"gvawatermark ! videoconvert ! autovideosink name=sink sync=false"
+    f"gvametaconvert add-empty-results=true ! queue ! "
+    f"gvafpscounter ! "
+    f"gvawatermark ! videoconvert ! video/x-raw,format=I420 ! "
+    f"openh264enc ! h264parse ! "
+    f"mp4mux ! filesink name=sink location=output.mp4"
 )
 pipeline = Gst.parse_launch(pipeline_str)
 
@@ -173,21 +152,16 @@ last_seen: dict[int, float] = {}
 flagged: set[int] = set()
 
 
-def point_in_zone(x: int, y: int) -> bool:
-    return cv2.pointPolygonTest(ZONE_POLYGON, (float(x), float(y)), False) >= 0
-
-
 def on_buffer(pad, info):
     buf = info.get_buffer()
     caps = pad.get_current_caps()
     frame = VideoFrame(buf, caps=caps)
 
-    # Use the buffer's presentation timestamp so dwell time tracks the source
-    # video clock and is independent of the sink's `sync` setting.
     now = buf.pts / Gst.SECOND if buf.pts != Gst.CLOCK_TIME_NONE else 0.0
     seen_ids: set[int] = set()
 
     for region in frame.regions():
+        # gvaattachroi attaches a frame-level ROI region; skip it.
         if region.label() != "person":
             continue
         object_id = region.object_id()
@@ -199,12 +173,8 @@ def on_buffer(pad, info):
         foot_y = int(rect.y + rect.h)
         seen_ids.add(object_id)
 
-        if not point_in_zone(foot_x, foot_y):
-            dwell_state.pop(object_id, None)
-            last_seen.pop(object_id, None)
-            flagged.discard(object_id)
-            continue
-
+        # gvadetect inference-region=1 already constrains detections to the
+        # gvaattachroi zone, so every tracked person here is "in zone".
         prev = last_seen.get(object_id, now)
         dwell_state[object_id] += now - prev
         last_seen[object_id] = now
@@ -243,39 +213,17 @@ bus.timed_pop_filtered(
 pipeline.set_state(Gst.State.NULL)
 ```
 
-To run on integrated GPU, change `device=CPU` to `device=GPU` and use
-`vapostproc` after `decodebin` for zero-copy color conversion.
-
-### Try It on a Sample Video
-
-Download a publicly hosted Intel sample clip that shows people walking through a scene:
-
-```bash
-wget -O test_video.mp4 \
-  https://github.com/intel-iot-devkit/sample-videos/raw/master/people-detection.mp4
-```
-
-The clip is 768x432 at 12 fps and shows people walking briskly through the field of view rather than truly loitering, so use a small zone in the busy part of the frame and a short dwell threshold for a meaningful demo:
-
-```python
-ZONE_POLYGON = np.array(
-    [(220, 180), (560, 180), (560, 360), (220, 360)], dtype=np.int32,
-)
-LOITERING_SECONDS = 1.5
-```
-
-Run the DLStreamer sample above.
-A window opened by `autovideosink` shows each frame with `gvawatermark` bounding boxes and persistent track IDs assigned by `gvatrack`.
-With the threshold above, the buffer probe prints two events on this clip, for example:
+Expected output with the sample video and the zone/threshold above:
 
 ```text
 LOITERING id=2 dwell=1.6s anchor=(529,258)
 LOITERING id=9 dwell=1.6s anchor=(527,250)
 ```
 
-Increasing `LOITERING_SECONDS` back to its operational default (around 10 s) suppresses the events on this short walking clip; reproduce a real loitering scenario with a stationary subject in your own footage.
+The annotated video is saved to `output.mp4` with green bounding boxes and
+track IDs drawn by `gvawatermark` around every detected person.
 
-To capture the annotated output instead of viewing it live, replace `autovideosink` with an encoder branch such as `x264enc ! mp4mux ! filesink location=loitering_output.mp4`.
+Increasing `LOITERING_SECONDS` back to its operational default (around 10 s) suppresses the events on this short walking clip; reproduce a real loitering scenario with a stationary subject in your own footage.
 
 ---
 
@@ -286,9 +234,9 @@ Licensed under the MIT License. See [LICENSE](LICENSE) for details.
 
 ## References
 
-- [YOLO11 Documentation](https://docs.ultralytics.com/models/yolo11/)
-- [OpenVINO YOLO11 Notebook](https://github.com/openvinotoolkit/openvino_notebooks/blob/latest/notebooks/yolov11-optimization/yolov11-object-detection.ipynb)
-- [Intel DLStreamer Object Tracking](https://dlstreamer.github.io/elements/gvatrack.html)
+- [YOLO26 Documentation](https://docs.ultralytics.com/models/yolo26/)
+- [OpenVINO YOLO26 Notebook](https://github.com/openvinotoolkit/openvino_notebooks/blob/latest/notebooks/yolov26-optimization/yolov26-object-detection.ipynb)
+- [Intel DLStreamer Object Tracking](https://docs.openedgeplatform.intel.com/2026.0/edge-ai-libraries/dlstreamer/elements/gvatrack.html)
 - [OpenVINO Documentation](https://docs.openvino.ai/)
 - [NNCF Post-Training Quantization](https://docs.openvino.ai/latest/nncf_ptq_introduction.html)
 - [COCO Dataset](https://cocodataset.org/)

export_and_quantize.sh

@@ -2,28 +2,69 @@
 # SPDX-License-Identifier: MIT
 # Copyright (C) Intel Corporation
 #
-# Export a YOLO11 person detector for loitering detection and quantize to INT8.
-# Usage: ./export_and_quantize.sh [MODEL_VARIANT]
-# Example: ./export_and_quantize.sh yolo11n
+# Export a YOLO26 person detector for loitering detection to OpenVINO IR.
+# Usage: ./export_and_quantize.sh [MODEL_VARIANT] [PRECISION]
+# Example: ./export_and_quantize.sh yolo26n FP16
+#
+# Supported precisions:
+#   FP32  -- Full-precision floating-point weights
+#   FP16  -- Half-precision floating-point weights (default)
+#   INT8  -- Quantized 8-bit integer weights (requires NNCF)
+#
+# Precision / device compatibility:
+#   | Precision | CPU | GPU | NPU |
+#   |-----------|-----|-----|-----|
+#   | FP32      | Yes | Yes | No  |
+#   | FP16      | Yes | Yes | Yes |
+#   | INT8      | Yes | Yes | Yes |
 
 set -euo pipefail
 
-MODEL_NAME="${1:-yolo11n}"
+MODEL_NAME="${1:-yolo26n}"
+PRECISION="${2:-FP16}"
+PRECISION="$(echo "${PRECISION}" | tr '[:lower:]' '[:upper:]')"
+
+if [[ "${PRECISION}" != "FP32" && "${PRECISION}" != "FP16" && "${PRECISION}" != "INT8" ]]; then
+    echo "ERROR: unsupported precision '${PRECISION}'. Choose FP32, FP16, or INT8." >&2
+    exit 1
+fi
 
 echo "--- Installing dependencies ---"
-pip install -qU "openvino>=2026.0.0" "nncf>=3.0.0" ultralytics
+if [[ "${PRECISION}" == "INT8" ]]; then
+    pip install -qU "openvino>=2026.0.0" "nncf>=3.0.0" ultralytics
+else
+    pip install -qU "openvino>=2026.0.0" ultralytics
+fi
+
+echo "--- Downloading sample test video ---"
+if [[ ! -f VIRAT_S_000101.mp4 ]]; then
+    wget -O VIRAT_S_000101.mp4 \
+        https://github.com/intel/metro-ai-suite/raw/refs/heads/videos/videos/VIRAT_S_000101.mp4
+    echo "Downloaded: VIRAT_S_000101.mp4"
+else
+    echo "Already present: VIRAT_S_000101.mp4"
+fi
 
-echo "--- Exporting ${MODEL_NAME} to OpenVINO IR (FP16) ---"
+if [[ "${PRECISION}" == "FP32" ]]; then
+    HALF_FLAG="False"
+    EXPORT_LABEL="FP32"
+else
+    HALF_FLAG="True"
+    EXPORT_LABEL="FP16"
+fi
+
+echo "--- Exporting ${MODEL_NAME} to OpenVINO IR (${EXPORT_LABEL}) ---"
 python3 -c "
 from ultralytics import YOLO
 
 model = YOLO('${MODEL_NAME}.pt')
-model.export(format='openvino', half=True, dynamic=False, imgsz=640)
+model.export(format='openvino', half=${HALF_FLAG}, dynamic=False, imgsz=640)
 print('Export complete: ${MODEL_NAME}_openvino_model/')
 "
 
-echo "--- Quantizing to INT8 with NNCF ---"
-python3 -c "
+if [[ "${PRECISION}" == "INT8" ]]; then
+    echo "--- Quantizing to INT8 with NNCF ---"
+    python3 -c "
 import nncf
 import openvino as ov
 import numpy as np
@@ -46,8 +87,5 @@ quantized = nncf.quantize(
 ov.save_model(quantized, '${MODEL_NAME}_loitering_int8.xml')
 print('Quantization complete: ${MODEL_NAME}_loitering_int8.xml')
 "
-
-echo "--- Benchmarking ---"
-benchmark_app -m "${MODEL_NAME}_loitering_int8.xml" -d CPU -niter 50 -api async
-
+fi
 echo "--- Done ---"