Sync motion-tracking from metro-analytics-catalog

README.md

@@ -1,6 +1,6 @@
 # Motion Tracking
 
-> **Validated with:** OpenVINO 2026.1.0, NNCF 3.0.0, DLStreamer 2026.0, Ultralytics 8.3.0, Python 3.11+
+> **Validated with:** OpenVINO 2026.1.0, NNCF 3.0.0, DLStreamer 2026.0, Ultralytics 8.4.46, Python 3.11+
 
 | Property | Value |
 |---|---|
@@ -62,9 +62,17 @@ Run the provided script to download, export to OpenVINO IR, and optionally quant
 
 ```bash
 chmod +x export_and_quantize.sh
-./export_and_quantize.sh yolo26n        # default: FP16
+./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
 ```
 
 Replace `yolo26n` with any variant (`yolo26s`, `yolo26m`, `yolo26l`, `yolo26x`).
@@ -90,23 +98,27 @@ Output files:
 | 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.
+> **Note:** The INT8 calibration uses frames from the bundled sample video.
+> For production accuracy, replace it with a representative set 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.
+The sample below uses the Ultralytics `model.track()` API with the PyTorch
+weights 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()`.
+> **Important:** The `model.track()` API requires PyTorch weights (`.pt`).
+> Using the OpenVINO model directory with `model.track()` produces zero
+> detections in Ultralytics 8.4.x due to an incompatibility in the tracker
+> integration. Use `model.predict()` for single-frame inference with the
+> OpenVINO backend, or use the DLStreamer sample below for OpenVINO-accelerated
+> tracking.
+>
+> The INT8 model (`yolo26n_tracking_int8.xml`) can be used directly with the
+> OpenVINO Python API but not with the Ultralytics `YOLO()` wrapper.
 
 ```python
 import subprocess
@@ -116,9 +128,9 @@ 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")
+# Use PyTorch weights for tracking -- model.track() requires the .pt backend.
+# The OpenVINO model directory works with model.predict() but not model.track().
+model = YOLO("yolo26n.pt", task="detect")
 
 video_path = "test_video.mp4"
 cap = cv2.VideoCapture(video_path)
@@ -188,6 +200,23 @@ print("Wrote output.mp4", flush=True)
 - For GPU: set `device="gpu:0"` in the `model.track()` call.
 - For NPU: set `device="npu:0"` (validate availability with `benchmark_app -d NPU`).
 
+### Try It on a Sample Video
+
+The `export_and_quantize.sh` script downloads `test_video.mp4` automatically.
+Run the OpenVINO sample above.
+The script processes each frame, prints per-track positions to the console,
+and writes the annotated video to `output.mp4`.
+
+Expected console output (representative):
+
+```text
+  Track 1: class=0 center=(320,240)
+  Track 2: class=0 center=(450,300)
+```
+
+`output.mp4` shows bounding boxes with track IDs and colored trajectory
+polylines for each tracked object.
+
 ### DLStreamer Sample
 
 The pipeline below runs the YOLO26 FP16 detector via `gvadetect` on
@@ -225,10 +254,10 @@ from gstgva import VideoFrame
 
 Gst.init(None)
 
-# For GPU: change device=CPU to device=GPU and add vapostproc after decodebin.
+# For GPU: change device=CPU to device=GPU and add vapostproc after decodebin3.
 # For NPU: change device=CPU to device=NPU (batch-size=1, nireq=4 recommended).
 pipeline_str = (
-    "filesrc location=test_video.mp4 ! decodebin ! videoconvert ! "
+    "filesrc location=test_video.mp4 ! decodebin3 ! videoconvert ! "
     "video/x-raw,format=BGR ! "
     "gvadetect model=yolo26n_openvino_model/yolo26n.xml "
     "device=CPU threshold=0.4 ! queue ! "
@@ -314,7 +343,7 @@ 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=GPU` -- add `vapostproc` after `decodebin3` for zero-copy color conversion.
 - `device=NPU` -- use `batch-size=1` and `nireq=4` for best NPU utilization.
 
 ---

export_and_quantize.sh

@@ -70,12 +70,27 @@ if [[ "${PRECISION}" == "INT8" ]]; then
 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')
 
+# Extract frames from the sample video for calibration.
+cap = cv2.VideoCapture('test_video.mp4')
+frames = []
+while len(frames) < 300:
+    ret, frame = cap.read()
+    if not ret:
+        cap.set(cv2.CAP_PROP_POS_FRAMES, 0)
+        continue
+    img = cv2.resize(frame, (640, 640))
+    img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB).astype(np.float32) / 255.0
+    img = img.transpose(2, 0, 1)[np.newaxis, ...]
+    frames.append(img)
+cap.release()
+
 def transform_fn(data_item):
-    return np.random.rand(1, 3, 640, 640).astype(np.float32)
+    return frames[data_item % len(frames)]
 
 calibration_dataset = nncf.Dataset(list(range(300)), transform_fn)