Sync motion-tracking from metro-analytics-catalog

LICENSE

@@ -0,0 +1,57 @@
+This directory contains two categories of content under different licenses.
+
+
+Scripts and Documentation
+-------------------------
+
+The scripts (export_and_quantize.sh) and documentation (README.md) in this
+directory are original works by Intel Corporation, licensed under the
+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.
+
+
+YOLO26 Model
+------------
+
+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/yolo26/
+
+Users must comply with the AGPL-3.0 license terms when using, modifying,
+or distributing the YOLO26 model weights or Ultralytics software.
+For commercial licensing options, see https://www.ultralytics.com/license.
+
+
+BoT-SORT / ByteTrack Trackers
+------------------------------
+
+The BoT-SORT and ByteTrack tracking algorithms are integrated into the
+Ultralytics framework. Original implementations:
+
+    BoT-SORT:  https://github.com/NirAharon/BoT-SORT
+    ByteTrack: https://github.com/FoundationVision/ByteTrack
+
+Users should consult the respective repositories for license terms.

README.md

@@ -1,5 +1,336 @@
----
-license: other
-license_name: other
-license_link: LICENSE
----
+# Motion Tracking
+
+> **Validated with:** OpenVINO 2026.1.0, NNCF 3.0.0, DLStreamer 2026.0, Ultralytics 8.3.0, Python 3.11+
+
+| Property | Value |
+|---|---|
+| **Category** | Object Detection + Multi-Object Tracking |
+| **Base Model** | [YOLO26](https://docs.ultralytics.com/models/yolo26/) (Ultralytics) + [BoT-SORT](https://github.com/NirAharon/BoT-SORT) tracker |
+| **Source Framework** | PyTorch (Ultralytics) |
+| **Supported Precisions** | FP32, FP16, FP16-INT8 |
+| **Inference Engine** | OpenVINO |
+| **Hardware** | CPU, GPU, NPU |
+| **Detected Class(es)** | Configurable (default: all 80 COCO classes) |
+
+---
+
+## Overview
+
+Motion Tracking is a Metro Analytics use case that detects objects and assigns persistent track IDs across frames, enabling trajectory analysis and temporal event detection.
+It is built on [YOLO26](https://docs.ultralytics.com/models/yolo26/), a state-of-the-art real-time object detector quantized to INT8, paired with a multi-object tracker:
+
+- **OpenVINO pipeline:** YOLO26 INT8 detection + Ultralytics built-in [BoT-SORT](https://github.com/NirAharon/BoT-SORT) or [ByteTrack](https://github.com/FoundationVision/ByteTrack) tracker via `model.track()`.
+- **DLStreamer pipeline:** YOLO26 FP16 detection via `gvadetect` + `gvatrack` element with `tracking-type=short-term-imageless`.
+
+Each detected object receives a unique `track_id` that persists across frames as long as the object remains visible.
+Outputs include per-object trajectories suitable for path analysis, dwell-time computation, and zone-based event triggers.
+
+Typical Metro deployments include:
+
+- **Pedestrian Trajectory Analysis** -- map walking paths through stations for flow optimization.
+- **Dwell-Time Measurement** -- measure how long individuals stay in specific zones.
+- **Zone-Based Event Detection** -- trigger alerts when tracked objects enter or exit defined areas.
+- **Traffic Flow Analytics** -- track vehicles through intersections for signal timing optimization.
+- **Incident Replay** -- reconstruct object paths for post-event forensic review.
+
+Available YOLO26 variants: `yolo26n`, `yolo26s`, `yolo26m`, `yolo26l`, `yolo26x`.
+Smaller variants (`yolo26n`, `yolo26s`) are recommended for high-FPS edge deployment.
+The default tracker is BoT-SORT; ByteTrack is available as an alternative with lower computational overhead.
+
+---
+
+## 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
+```
+
+---
+
+## 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 yolo26n        # default: FP16
+./export_and_quantize.sh yolo26n FP32   # full-precision
+./export_and_quantize.sh yolo26n INT8   # quantized
+```
+
+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`, `ultralytics`; adds `nncf` for INT8).
+2. Downloads the sample test video (`test_video.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_tracking_int8.xml` / `yolo26n_tracking_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
+> target deployment site.
+
+### OpenVINO Sample
+
+The sample below uses the Ultralytics `model.track()` API with the FP16
+OpenVINO model directory to detect and track objects in a video, assigning
+persistent track IDs via the built-in BoT-SORT tracker.
+Each annotated frame -- with bounding boxes, track IDs, and per-track
+trajectory polylines -- is written to `output.mp4`.
+Change the `device` string to run on CPU, GPU, or NPU.
+
+> **Note:** Ultralytics requires the OpenVINO model directory (e.g.,
+> `yolo26n_openvino_model/`) rather than a bare `.xml` file.
+> The INT8 model (`yolo26n_tracking_int8.xml`) can be used directly
+> with the OpenVINO Python API but not with Ultralytics `YOLO()`.
+
+```python
+import subprocess
+from collections import defaultdict
+
+import cv2
+import numpy as np
+from ultralytics import YOLO
+
+# Load the FP16 OpenVINO model directory for tracking.
+# Change device to "gpu:0" or "npu:0" for GPU/NPU.
+model = YOLO("yolo26n_openvino_model", task="detect")
+
+video_path = "test_video.mp4"
+cap = cv2.VideoCapture(video_path)
+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))
+
+# Pipe frames to ffmpeg for H.264 output (universally playable).
+proc = subprocess.Popen(
+    ["ffmpeg", "-y", "-f", "rawvideo", "-pix_fmt", "bgr24",
+     "-s", f"{width}x{height}", "-r", str(fps),
+     "-i", "pipe:0", "-c:v", "libx264", "-pix_fmt", "yuv420p",
+     "-movflags", "+faststart", "output.mp4"],
+    stdin=subprocess.PIPE, stderr=subprocess.DEVNULL,
+)
+
+# Distinct colors for trajectory lines (one per track ID).
+COLORS = [
+    (255, 0, 0), (0, 255, 0), (0, 0, 255), (255, 255, 0),
+    (255, 0, 255), (0, 255, 255), (128, 0, 255), (255, 128, 0),
+]
+track_history: dict[int, list[tuple[float, float]]] = defaultdict(list)
+
+while cap.isOpened():
+    success, frame = cap.read()
+    if not success:
+        break
+
+    # Run YOLO26 tracking with BoT-SORT (default).
+    # Use tracker="bytetrack.yaml" for ByteTrack alternative.
+    results = model.track(frame, persist=True, conf=0.4, tracker="botsort.yaml")
+    result = results[0]
+
+    annotated = result.plot()
+
+    if result.boxes and result.boxes.is_track:
+        boxes = result.boxes.xywh.cpu()
+        track_ids = result.boxes.id.int().cpu().tolist()
+        classes = result.boxes.cls.int().cpu().tolist()
+
+        for box, track_id in zip(boxes, track_ids):
+            x, y, _w, _h = box
+            track = track_history[track_id]
+            track.append((float(x), float(y)))
+            if len(track) > 30:
+                track.pop(0)
+
+            color = COLORS[track_id % len(COLORS)]
+            points = np.array(track, dtype=np.int32).reshape((-1, 1, 2))
+            cv2.polylines(annotated, [points], False, color, 2)
+
+        for tid, cls_id in zip(track_ids, classes):
+            cx, cy = track_history[tid][-1]
+            print(f"  Track {tid}: class={cls_id} center=({cx:.0f},{cy:.0f})", flush=True)
+
+    proc.stdin.write(annotated.tobytes())
+
+cap.release()
+proc.stdin.close()
+proc.wait()
+print("Wrote output.mp4", flush=True)
+```
+
+**Device targets:**
+
+- Default runs on CPU via OpenVINO.
+- For GPU: set `device="gpu:0"` in the `model.track()` call.
+- For NPU: set `device="npu:0"` (validate availability with `benchmark_app -d NPU`).
+
+### DLStreamer Sample
+
+The pipeline below runs the YOLO26 FP16 detector via `gvadetect` on
+`test_video.mp4`, attaches persistent track IDs with `gvatrack`
+(`short-term-imageless` tracker), and overlays bounding boxes with
+`gvawatermark`.  Frames are pulled from an `appsink`, per-track trajectory
+polylines are drawn with OpenCV, and the result is muxed to `output.mp4`
+(H.264 via ffmpeg).
+
+> **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.
+> - 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 subprocess
+from collections import defaultdict
+
+import cv2
+import numpy as np
+import gi
+
+gi.require_version("Gst", "1.0")
+from gi.repository import Gst
+from gstgva import VideoFrame
+
+Gst.init(None)
+
+# For GPU: change device=CPU to device=GPU and add vapostproc after decodebin.
+# For NPU: change device=CPU to device=NPU (batch-size=1, nireq=4 recommended).
+pipeline_str = (
+    "filesrc location=test_video.mp4 ! decodebin ! videoconvert ! "
+    "video/x-raw,format=BGR ! "
+    "gvadetect model=yolo26n_openvino_model/yolo26n.xml "
+    "device=CPU threshold=0.4 ! queue ! "
+    "gvatrack tracking-type=short-term-imageless ! queue ! "
+    "gvawatermark ! appsink name=sink emit-signals=false sync=false"
+)
+pipeline = Gst.parse_launch(pipeline_str)
+appsink = pipeline.get_by_name("sink")
+
+# Distinct colors for trajectory lines (one per track ID).
+COLORS = [
+    (255, 0, 0), (0, 255, 0), (0, 0, 255), (255, 255, 0),
+    (255, 0, 255), (0, 255, 255), (128, 0, 255), (255, 128, 0),
+]
+track_history: dict[int, list[tuple[int, int]]] = defaultdict(list)
+
+pipeline.set_state(Gst.State.PLAYING)
+
+proc = None
+
+while True:
+    sample = appsink.emit("pull-sample")
+    if sample is None:
+        break
+
+    buf = sample.get_buffer()
+    caps = sample.get_caps()
+    struct = caps.get_structure(0)
+    width = struct.get_value("width")
+    height = struct.get_value("height")
+
+    # Start ffmpeg encoder on the first frame.
+    if proc is None:
+        ok, fps_num, fps_den = struct.get_fraction("framerate")
+        fps = fps_num / fps_den if ok and fps_den > 0 else 30.0
+        proc = subprocess.Popen(
+            ["ffmpeg", "-y", "-f", "rawvideo", "-pix_fmt", "bgr24",
+             "-s", f"{width}x{height}", "-r", str(fps),
+             "-i", "pipe:0", "-c:v", "libx264", "-pix_fmt", "yuv420p",
+             "-movflags", "+faststart", "output.mp4"],
+            stdin=subprocess.PIPE, stderr=subprocess.DEVNULL,
+        )
+
+    # Read detection / tracking metadata.
+    frame = VideoFrame(buf, caps=caps)
+    regions_data = []
+    for region in frame.regions():
+        tid = region.object_id()
+        label = region.label()
+        rect = region.rect()
+        cx = int(rect.x + rect.w / 2)
+        cy = int(rect.y + rect.h / 2)
+        regions_data.append((tid, label, cx, cy))
+
+    # Map buffer read-only and copy pixels to a writable numpy array.
+    success, map_info = buf.map(Gst.MapFlags.READ)
+    if not success:
+        continue
+    arr = np.ndarray((height, width, 3), dtype=np.uint8,
+                     buffer=map_info.data).copy()
+    buf.unmap(map_info)
+
+    # Draw per-track trajectory polylines on the frame copy.
+    for tid, label, cx, cy in regions_data:
+        track = track_history[tid]
+        track.append((cx, cy))
+        if len(track) > 30:
+            track.pop(0)
+        color = COLORS[tid % len(COLORS)]
+        pts = np.array(track, dtype=np.int32).reshape((-1, 1, 2))
+        cv2.polylines(arr, [pts], False, color, 2)
+        print(f"  Track {tid}: {label} center=({cx},{cy})", flush=True)
+
+    proc.stdin.write(arr.tobytes())
+
+pipeline.set_state(Gst.State.NULL)
+if proc:
+    proc.stdin.close()
+    proc.wait()
+print("Wrote output.mp4", flush=True)
+```
+
+**Device targets:**
+
+- `device=CPU` -- default in the sample code.
+- `device=GPU` -- add `vapostproc` after `decodebin` for zero-copy color conversion.
+- `device=NPU` -- use `batch-size=1` and `nireq=4` for best NPU utilization.
+
+---
+
+## License
+
+Copyright (C) Intel Corporation. All rights reserved.
+Licensed under the MIT License. See [LICENSE](LICENSE) for details.
+
+## References
+
+- [YOLO26 Documentation](https://docs.ultralytics.com/models/yolo26/)
+- [Ultralytics Multi-Object Tracking](https://docs.ultralytics.com/modes/track/)
+- [BoT-SORT Tracker](https://github.com/NirAharon/BoT-SORT)
+- [ByteTrack Tracker](https://github.com/FoundationVision/ByteTrack)
+- [Intel DLStreamer gvatrack](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)
+- [Intel DLStreamer](https://docs.openedgeplatform.intel.com/2026.0/edge-ai-libraries/dlstreamer/index.html)

export_and_quantize.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MIT
+# Copyright (C) Intel Corporation
+#
+# Export a YOLO26 detector for motion tracking to OpenVINO IR.
+# The tracker itself (BoT-SORT / ByteTrack) runs at inference time via
+# Ultralytics or DLStreamer gvatrack; no separate model export is needed.
+# 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:-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>=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 test_video.mp4 ]]; then
+    wget -q -O test_video.mp4 \
+        https://github.com/intel-iot-devkit/sample-videos/raw/master/people-detection.mp4
+    echo "Downloaded: test_video.mp4"
+else
+    echo "Already present: test_video.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
+
+core = ov.Core()
+model = core.read_model('${MODEL_NAME}_openvino_model/${MODEL_NAME}.xml')
+
+def transform_fn(data_item):
+    return np.random.rand(1, 3, 640, 640).astype(np.float32)
+
+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}_tracking_int8.xml')
+print('Quantization complete: ${MODEL_NAME}_tracking_int8.xml')
+"
+fi
+echo "--- Done ---"