Sync vehicle-entry-exit-logging from metro-analytics-catalog

.gitattributes

@@ -33,3 +33,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+expected_output_dlstreamer.gif filter=lfs diff=lfs merge=lfs -text
+expected_output_openvino.gif filter=lfs diff=lfs merge=lfs -text

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Intel Corporation.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE

README.md

@@ -0,0 +1,423 @@
+---
+license: mit
+license_link: LICENSE
+library_name: openvino
+pipeline_tag: object-detection
+tags:
+  - openvino
+  - intel
+  - yolo
+  - yolo26
+  - vehicle-entry-exit
+  - tracking
+  - short-term-imageless
+  - line-crossing
+  - edge-ai
+  - metro
+  - dlstreamer
+language:
+  - en
+---
+
+# Vehicle Entry/Exit Logging
+
+| Property | Value |
+|---|---|
+| **Category** | Object Detection + Tracking + Line Crossing |
+| **Base Model** | [YOLO26](https://docs.ultralytics.com/models/yolo26/) (Ultralytics) |
+| **Source Framework** | PyTorch (Ultralytics) |
+| **Supported Precisions** | FP32, FP16, INT8 (mixed-precision) |
+| **Inference Engine** | OpenVINO |
+| **Hardware** | CPU, GPU, NPU |
+| **Detected Class(es)** | `car` (2), `motorcycle` (3), `bus` (5), `truck` (7) |
+
+---
+
+## Overview
+
+Vehicle Entry/Exit Logging is a Metro Analytics use case that detects vehicles,
+tracks them across frames with BoT-SORT, and logs directional entry and exit
+events when a tracked vehicle crosses a configurable virtual line.
+It is built on [YOLO26](https://docs.ultralytics.com/models/yolo26/), a
+state-of-the-art real-time object detector, quantized to INT8 for efficient
+inference on Intel hardware.
+
+The tracking and line-crossing logic runs as a thin post-processing layer on
+top of the strongest vehicle detector available, keeping the solution accurate
+and extensible to other zone shapes.
+
+Typical Metro deployments include:
+
+- **Parking Garage Management** -- count vehicles entering and leaving a lot.
+- **Toll Gate Analytics** -- log each vehicle that passes through a toll point.
+- **Depot and Fleet Monitoring** -- track bus/truck entry and exit from depots.
+- **Traffic Flow Analysis** -- measure directional flow at intersections.
+
+Available variants: `yolo26n`, `yolo26s`, `yolo26m`, `yolo26l`, `yolo26x`.
+Smaller variants (`yolo26n`, `yolo26s`) are recommended for high-FPS edge
+deployment; larger variants improve recall for distant vehicles.
+
+---
+
+## Prerequisites
+
+- Python 3.11+
+- [Install OpenVINO](https://docs.openvino.ai/2026/get-started/install-openvino.html) (latest version)
+- [Install Intel DLStreamer](https://docs.openedgeplatform.intel.com/2026.0/edge-ai-libraries/dlstreamer/get_started/install/install_guide_ubuntu.html) (latest version)
+
+Create and activate a Python virtual environment before running the scripts:
+
+```bash
+python3 -m venv .venv --system-site-packages
+source .venv/bin/activate
+```
+
+> **Note:** The `--system-site-packages` flag is required so the virtual
+> environment can access the system-installed OpenVINO and DLStreamer Python
+> packages.
+
+---
+
+## Getting Started
+
+### Download and Quantize Model
+
+Run the provided script to download, export to OpenVINO IR, and optionally quantize:
+
+```bash
+chmod +x export_and_quantize.sh
+./export_and_quantize.sh
+```
+
+This exports the default **yolo26n** model in **FP16** precision.
+
+#### Optional: Select a Different Variant or Precision
+
+```bash
+./export_and_quantize.sh yolo26n FP32   # full-precision
+./export_and_quantize.sh yolo26n INT8   # quantized
+./export_and_quantize.sh yolo26s        # larger variant, default FP16
+```
+
+The script performs the following steps:
+
+1. Installs dependencies (`openvino`, `ultralytics`; adds `nncf` for INT8).
+2. Downloads a sample test image (`test.jpg`) and the smart-parking sample video (`smart_parking_720p_30fps.mp4`).
+3. Downloads the PyTorch weights and exports to OpenVINO IR.
+4. *(INT8 only)* Quantizes the model using NNCF post-training quantization.
+
+Output files:
+
+- `yolo26n_openvino_model/` -- FP32 or FP16 OpenVINO IR model directory.
+- `yolo26n_vehicle_entry_exit_int8.xml` / `.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 |
+
+### OpenVINO Sample
+
+The sample below runs YOLO26 inference on a video, keeps only the `car` class,
+applies simple centroid tracking with track IDs, and logs an entry or exit
+event -- with the wall-clock timestamp inside the video -- when a tracked car's
+centroid crosses a horizontal virtual line placed at 60% of the frame height.
+The saved output video shows only the car detection bounding boxes (no counter
+overlay or line).
+Change the `device` string to run on CPU, GPU, or NPU.
+
+```python
+import cv2
+import numpy as np
+import openvino as ov
+
+VEHICLE_CLASS_IDS = {2: "car"}
+CONF_THRESHOLD = 0.4
+INPUT_SIZE = 640
+LINE_RATIO = 0.6
+MAX_DIST = 80
+
+core = ov.Core()
+model = core.read_model("yolo26n_openvino_model/yolo26n.xml")
+
+# Change device to "GPU" or "NPU" to run on integrated GPU or NPU.
+compiled = core.compile_model(model, "CPU")
+
+cap = cv2.VideoCapture("smart_parking_720p_30fps.mp4")
+fps = cap.get(cv2.CAP_PROP_FPS) or 30.0
+width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+line_y = int(height * LINE_RATIO)
+
+
+def fmt_time(seconds: float) -> str:
+    """Format elapsed video time as MM:SS.mmm."""
+    minutes, secs = divmod(seconds, 60)
+    return f"{int(minutes):02d}:{secs:06.3f}"
+
+
+writer = cv2.VideoWriter(
+    "output_openvino.mp4", cv2.VideoWriter_fourcc(*"mp4v"), fps, (width, height))
+
+tracks: dict[int, tuple[int, int]] = {}
+entry_time: dict[int, float] = {}
+next_id = 0
+entered = 0
+exited = 0
+frame_idx = 0
+
+while True:
+    ok, frame = cap.read()
+    if not ok:
+        break
+    frame_idx += 1
+    h0, w0 = frame.shape[:2]
+    sx, sy = w0 / INPUT_SIZE, h0 / INPUT_SIZE
+
+    blob = cv2.resize(frame, (INPUT_SIZE, INPUT_SIZE))
+    blob = cv2.cvtColor(blob, cv2.COLOR_BGR2RGB).astype(np.float32) / 255.0
+    blob = blob.transpose(2, 0, 1)[np.newaxis, ...]
+
+    output = compiled([blob])[compiled.output(0)][0]
+    mask = (output[:, 4] >= CONF_THRESHOLD) & np.isin(
+        output[:, 5].astype(int), list(VEHICLE_CLASS_IDS.keys()))
+    dets = output[mask]
+
+    centroids = []
+    for det in dets:
+        cx = int(((det[0] + det[2]) / 2) * sx)
+        cy = int(((det[1] + det[3]) / 2) * sy)
+        centroids.append((cx, cy))
+
+    new_tracks: dict[int, tuple[int, int]] = {}
+    used = set()
+    for tid, (px, py) in tracks.items():
+        best_d = MAX_DIST
+        best_j = -1
+        for j, (cx, cy) in enumerate(centroids):
+            if j in used:
+                continue
+            d = abs(cx - px) + abs(cy - py)
+            if d < best_d:
+                best_d = d
+                best_j = j
+        if best_j >= 0:
+            cx, cy = centroids[best_j]
+            used.add(best_j)
+            t = frame_idx / fps
+            if py < line_y <= cy:
+                exited += 1
+                enter_t = entry_time.pop(tid, None)
+                if enter_t is not None:
+                    print(
+                        f"EXIT  track={tid:<3} entry={fmt_time(enter_t)} "
+                        f"exit={fmt_time(t)}", flush=True)
+                else:
+                    print(f"EXIT  track={tid:<3} exit={fmt_time(t)}", flush=True)
+            elif py >= line_y > cy:
+                entered += 1
+                entry_time[tid] = t
+                print(f"ENTRY track={tid:<3} entry={fmt_time(t)}", flush=True)
+            new_tracks[tid] = (cx, cy)
+    for j, (cx, cy) in enumerate(centroids):
+        if j not in used:
+            new_tracks[next_id] = (cx, cy)
+            next_id += 1
+    tracks = new_tracks
+
+    for det in dets:
+        x1 = int(det[0] * sx)
+        y1 = int(det[1] * sy)
+        x2 = int(det[2] * sx)
+        y2 = int(det[3] * sy)
+        cv2.rectangle(frame, (x1, y1), (x2, y2), (0, 255, 0), 2)
+        cv2.putText(frame, "car", (x1, max(y1 - 6, 0)),
+                    cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 255, 0), 2)
+    writer.write(frame)
+
+cap.release()
+writer.release()
+print(f"Total: entered={entered} exited={exited}", flush=True)
+```
+
+**Device targets:**
+
+- `"CPU"` -- default, works on all Intel platforms.
+- `"GPU"` -- Intel integrated or discrete GPU.
+- `"NPU"` -- Intel NPU (validate with `benchmark_app -d NPU`).
+
+#### Expected Output
+
+Each line prints the track ID with the entry timestamp, and on exit the paired
+entry and exit timestamps (`MM:SS.mmm` within the video):
+
+```text
+ENTRY track=3   entry=00:02.400
+ENTRY track=7   entry=00:05.133
+EXIT  track=3   entry=00:02.400 exit=00:09.867
+ENTRY track=12  entry=00:11.267
+EXIT  track=7   entry=00:05.133 exit=00:14.700
+EXIT  track=12  entry=00:11.267 exit=00:18.933
+Total: entered=3 exited=3
+```
+
+![OpenVINO expected output](expected_output_openvino.gif)
+
+### DLStreamer Sample
+
+The pipeline below runs the FP16 YOLO26 detector with `gvatrack`
+(BoT-SORT) for stable vehicle IDs, keeping only the `car` class.
+A buffer probe reads the tracking metadata and fires entry/exit events
+-- logging the entry and exit timestamps taken from each buffer's
+presentation time -- when a tracked car crosses the virtual line.
+The annotated result is saved to `output_dlstreamer.mp4`.
+
+> **Notes on running this sample:**
+>
+> - Use the FP16 IR (`yolo26n_openvino_model/yolo26n.xml`). Class names are
+>   read automatically from the model's embedded `metadata.yaml` by
+>   DLStreamer 2026.0+ -- no external `labels-file` is required.
+> - Detections are read with the `gstgva` `VideoFrame` API
+>   (`region.object_id()` carries the `gvatrack` ID).
+> - Export `PYTHONPATH` so the DLStreamer Python module is importable:
+>
+>   ```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:-}
+>   ```
+
+```python
+import gi
+
+gi.require_version("Gst", "1.0")
+from gi.repository import Gst
+from gstgva import VideoFrame
+
+Gst.init([])
+
+INPUT_VIDEO = "smart_parking_720p_30fps.mp4"
+VEHICLE_LABELS = {"car"}
+LINE_RATIO = 0.6
+
+# For CPU: change device=GPU to device=CPU.
+# For NPU: change device=GPU to device=NPU (batch-size=1, nireq=4 recommended).
+pipeline_str = (
+    f"filesrc location={INPUT_VIDEO} ! decodebin3 ! "
+    "videoconvert ! "
+    "gvadetect model=yolo26n_openvino_model/yolo26n.xml "
+    "device=GPU "
+    "threshold=0.4 ! queue ! "
+    "gvatrack tracking-type=short-term-imageless ! queue ! "
+    "identity name=probe ! "
+    "gvawatermark displ-cfg=show-roi=car ! "
+    "videoconvert ! video/x-raw,format=I420 ! "
+    "openh264enc ! h264parse ! "
+    "mp4mux ! filesink location=output_dlstreamer.mp4"
+)
+pipeline = Gst.parse_launch(pipeline_str)
+
+prev_positions: dict[int, int] = {}
+entry_time: dict[int, float] = {}
+entered = 0
+exited = 0
+frame_height = 0
+
+
+def fmt_time(seconds: float) -> str:
+    """Format elapsed video time as MM:SS.mmm."""
+    minutes, secs = divmod(seconds, 60)
+    return f"{int(minutes):02d}:{secs:06.3f}"
+
+
+def on_buffer(pad, info):
+    global entered, exited, frame_height
+    buf = info.get_buffer()
+    caps = pad.get_current_caps()
+    if caps and frame_height == 0:
+        frame_height = caps.get_structure(0).get_value("height") or 720
+    line_y = int(frame_height * LINE_RATIO)
+
+    t = buf.pts / Gst.SECOND if buf.pts != Gst.CLOCK_TIME_NONE else 0.0
+    frame = VideoFrame(buf, caps=caps)
+    current: dict[int, int] = {}
+    for region in frame.regions():
+        if region.label() not in VEHICLE_LABELS:
+            continue
+        rect = region.rect()
+        cy = int(rect.y + rect.h / 2)
+        tid = region.object_id()
+        current[tid] = cy
+        if tid in prev_positions:
+            py = prev_positions[tid]
+            if py < line_y <= cy:
+                exited += 1
+                enter_t = entry_time.pop(tid, None)
+                if enter_t is not None:
+                    print(
+                        f"EXIT  track={tid:<3} entry={fmt_time(enter_t)} "
+                        f"exit={fmt_time(t)}", flush=True)
+                else:
+                    print(f"EXIT  track={tid:<3} exit={fmt_time(t)}", flush=True)
+            elif py >= line_y > cy:
+                entered += 1
+                entry_time[tid] = t
+                print(f"ENTRY track={tid:<3} entry={fmt_time(t)}", flush=True)
+    prev_positions.clear()
+    prev_positions.update(current)
+    return Gst.PadProbeReturn.OK
+
+
+probe = pipeline.get_by_name("probe")
+probe.get_static_pad("src").add_probe(Gst.PadProbeType.BUFFER, on_buffer)
+
+pipeline.set_state(Gst.State.PLAYING)
+bus = pipeline.get_bus()
+bus.timed_pop_filtered(
+    Gst.CLOCK_TIME_NONE,
+    Gst.MessageType.EOS | Gst.MessageType.ERROR,
+)
+pipeline.set_state(Gst.State.NULL)
+print(f"Total: entered={entered} exited={exited}", flush=True)
+```
+
+**Device targets:**
+
+- `device=GPU` -- default in the sample code.
+- `device=CPU` -- change `device=GPU` to `device=CPU`.
+- `device=NPU` -- change `device=GPU` to `device=NPU`; use `batch-size=1` and `nireq=4` for best NPU utilization.
+
+#### Expected Output
+
+The terminal logs each vehicle's entry timestamp and, on exit, the paired
+entry and exit timestamps (`MM:SS.mmm` within the video):
+
+```text
+ENTRY track=1   entry=00:01.900
+ENTRY track=4   entry=00:04.633
+EXIT  track=1   entry=00:01.900 exit=00:08.767
+ENTRY track=9   entry=00:10.500
+EXIT  track=4   entry=00:04.633 exit=00:13.400
+EXIT  track=9   entry=00:10.500 exit=00:17.833
+Total: entered=3 exited=3
+```
+
+![DLStreamer expected output](expected_output_dlstreamer.gif)
+
+---
+
+## License
+
+Licensed under the MIT License. See [LICENSE](LICENSE) for details.
+
+## References
+
+- [YOLO26 Documentation](https://docs.ultralytics.com/models/yolo26/)
+- [Intel DLStreamer gvatrack](https://docs.openedgeplatform.intel.com/2026.0/edge-ai-libraries/dlstreamer/elements/gvatrack.html)
+- [BoT-SORT: Robust Multi-Object Tracking](https://arxiv.org/abs/2206.14651)
+- [OpenVINO Documentation](https://docs.openvino.ai/)
+- [Intel DLStreamer](https://docs.openedgeplatform.intel.com/2026.0/edge-ai-libraries/dlstreamer/index.html)

export_and_quantize.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MIT
+# Copyright (C) Intel Corporation
+#
+# Export a YOLO26 detector to OpenVINO IR for the vehicle-entry-exit-logging
+# use case with BoT-SORT tracking and virtual-line crossing.
+# Usage: ./export_and_quantize.sh [MODEL_VARIANT] [PRECISION]
+# Example: ./export_and_quantize.sh yolo26n FP16
+
+set -euo pipefail
+
+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 ---"
+if [[ "${PRECISION}" == "INT8" ]]; then
+    pip install -qU openvino nncf ultralytics
+else
+    pip install -qU openvino ultralytics
+fi
+
+# Ask for approval before downloading models and sample files
+echo ""
+echo "This script will download:"
+echo "  - Model weights and/or sample files"
+echo ""
+read -p "Continue with downloads? (yes/no): " APPROVAL
+if [[ "${APPROVAL}" != "yes" ]]; then
+    echo "Download cancelled by user."
+    exit 0
+fi
+echo ""
+echo "--- Downloading sample test image ---"
+if [[ ! -f test.jpg ]]; then
+    wget -q -O test.jpg https://ultralytics.com/images/bus.jpg
+    echo "Downloaded: test.jpg"
+else
+    echo "Already present: test.jpg"
+fi
+echo ""
+echo "--- Downloading sample test video ---"
+if [[ ! -f smart_parking_720p_30fps.mp4 ]]; then
+    wget -q -O smart_parking_720p_30fps.mp4 \
+        "https://github.com/open-edge-platform/edge-ai-resources/raw/main/videos/smart_parking_720p_30fps.mp4"
+    echo "Downloaded: smart_parking_720p_30fps.mp4"
+else
+    echo "Already present: smart_parking_720p_30fps.mp4"
+fi
+
+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=${HALF_FLAG}, dynamic=False, imgsz=640)
+print('Export complete: ${MODEL_NAME}_openvino_model/')
+"
+
+if [[ "${PRECISION}" == "INT8" ]]; then
+    echo "--- Quantizing to INT8 with NNCF ---"
+    python3 -c "
+import nncf
+import openvino as ov
+import numpy as np
+import cv2
+
+core = ov.Core()
+model = core.read_model('${MODEL_NAME}_openvino_model/${MODEL_NAME}.xml')
+
+img = cv2.imread('test.jpg')
+img = cv2.resize(img, (640, 640))
+img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB).astype(np.float32) / 255.0
+img = img.transpose(2, 0, 1)[np.newaxis, ...]
+
+def transform_fn(data_item):
+    return img
+
+calibration_dataset = nncf.Dataset(list(range(300)), transform_fn)
+
+quantized = nncf.quantize(
+    model,
+    calibration_dataset,
+    preset=nncf.QuantizationPreset.MIXED,
+    subset_size=300,
+)
+
+ov.save_model(quantized, '${MODEL_NAME}_vehicle_entry_exit_int8.xml')
+print('Quantization complete: ${MODEL_NAME}_vehicle_entry_exit_int8.xml')
+"
+fi
+echo "--- Done ---"