Sync object-classification 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,388 @@
+---
+license: mit
+license_link: LICENSE
+library_name: openvino
+pipeline_tag: object-detection
+tags:
+  - openvino
+  - intel
+  - yolo
+  - yolo26
+  - object-classification
+  - classification
+  - smart-city
+  - situational-awareness
+  - traffic
+  - edge-ai
+  - metro
+  - dlstreamer
+language:
+  - en
+---
+
+# Object Classification
+
+| Property | Value |
+|---|---|
+| **Category** | Object Classification (Traffic Categorization: People / Vehicles) |
+| **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)** | `person` and vehicle classes grouped into `People` and `Vehicles` |
+
+---
+
+## Overview
+
+Object Classification is a Metro Analytics use case that detects objects with [YOLO26](https://docs.ultralytics.com/models/yolo26/) and then categorizes each detection into higher-level city-operations groups.
+It is built on the state-of-the-art YOLO26 real-time detector, quantized to INT8 for efficient inference on Intel hardware.
+Where the general object-detection use case reports every one of the 80 COCO classes individually, this use case rolls the traffic-relevant classes up into two semantic categories, `People` and `Vehicles`, so operators get an at-a-glance picture of a scene.
+
+The traffic categories are:
+
+- **People** -- the COCO `person` class.
+- **Vehicles** -- the COCO `bicycle`, `car`, `motorcycle`, `bus`, `train`, and `truck` classes.
+
+Objects outside these categories are ignored to keep the output focused on traffic situational awareness.
+
+Typical Metro deployments include:
+
+- **Situational Awareness** -- summarize each camera feed as live People and Vehicles counts.
+- **Automated City Operations** -- feed category counts into signal timing, congestion, and dispatch logic.
+- **Intersection and Roundabout Monitoring** -- track the mix of pedestrians and vehicles at busy junctions.
+- **Trend Analytics** -- aggregate category counts over time to understand traffic patterns.
+
+Available variants: `yolo26n`, `yolo26s`, `yolo26m`, `yolo26l`, `yolo26x`.
+Smaller variants (`yolo26n`, `yolo26s`) are recommended for high-FPS edge deployment; larger variants improve recall for small objects.
+
+---
+
+## 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
+```
+
+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 a sample traffic video (`test_video.mp4`) of an urban roundabout at low resolution (640x360).
+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_objcls_int8.xml` / `yolo26n_objcls_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:** The INT8 calibration uses a frame 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 runs YOLO26 inference on the sample traffic video, maps each
+detection into the `People` or `Vehicles` category, draws boxes colored per
+category, overlays live category counts, and writes the annotated result to
+`output_openvino.mp4`.
+YOLO26 is end-to-end (NMS-free), so no manual non-maximum suppression is needed.
+Change the `device` string to run on CPU, GPU, or NPU.
+
+```python
+import cv2
+import numpy as np
+import openvino as ov
+
+CONF_THRESHOLD = 0.4
+INPUT_SIZE = 640
+
+# Map the traffic-relevant COCO class ids into higher-level city categories.
+# People and Vehicles are the two categories tracked for situational awareness.
+CATEGORY_BY_CLASS_ID = {
+    0: "People",      # person
+    1: "Vehicles",    # bicycle
+    2: "Vehicles",    # car
+    3: "Vehicles",    # motorcycle
+    5: "Vehicles",    # bus
+    6: "Vehicles",    # train
+    7: "Vehicles",    # truck
+}
+# BGR overlay colors for each category.
+CATEGORY_COLORS = {
+    "People": (0, 200, 0),
+    "Vehicles": (255, 128, 0),
+}
+
+core = ov.Core()
+model = core.read_model("yolo26n_openvino_model/yolo26n.xml")
+
+# YOLO26 embeds the 80 COCO class names in rt_info. Ultralytics separates
+# multi-word names with underscores (e.g. "traffic_light"), so restore spaces.
+COCO_NAMES = [
+    name.replace("_", " ")
+    for name in model.get_rt_info()["model_info"]["labels"].value.split()
+]
+
+# Change device to "GPU" or "NPU" to run on integrated GPU or NPU.
+compiled = core.compile_model(model, "CPU")
+output_port = compiled.output(0)
+
+cap = cv2.VideoCapture("test_video.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))
+writer = cv2.VideoWriter(
+    "output_openvino.mp4", cv2.VideoWriter_fourcc(*"mp4v"), fps, (width, height)
+)
+
+totals = {"People": 0, "Vehicles": 0}
+frame_idx = 0
+while True:
+    ok, frame = cap.read()
+    if not ok:
+        break
+    frame_idx += 1
+
+    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, ...]  # NCHW
+
+    # YOLO26 end-to-end output: [1, 300, 6] = [x1, y1, x2, y2, confidence, class_id].
+    output = compiled([blob])[output_port][0]
+
+    sx, sy = width / INPUT_SIZE, height / INPUT_SIZE
+    counts = {"People": 0, "Vehicles": 0}
+    for x1, y1, x2, y2, conf, class_id in output:
+        if conf < CONF_THRESHOLD:
+            continue
+        category = CATEGORY_BY_CLASS_ID.get(int(class_id))
+        if category is None:
+            continue  # not a traffic-relevant object
+        counts[category] += 1
+        totals[category] += 1
+        color = CATEGORY_COLORS[category]
+        px1, py1 = int(x1 * sx), int(y1 * sy)
+        px2, py2 = int(x2 * sx), int(y2 * sy)
+        label = f"{category}: {COCO_NAMES[int(class_id)]} {conf:.2f}"
+        cv2.rectangle(frame, (px1, py1), (px2, py2), color, 2)
+        cv2.putText(frame, label, (px1, py1 - 5),
+                    cv2.FONT_HERSHEY_SIMPLEX, 2.0, color, 2)
+
+    # Overlay the per-category counts for this frame.
+    banner = f"People: {counts['People']}  Vehicles: {counts['Vehicles']}"
+    cv2.rectangle(frame, (0, 0), (width, 60), (0, 0, 0), -1)
+    cv2.putText(frame, banner, (15, 45),
+                cv2.FONT_HERSHEY_SIMPLEX, 2.0, (255, 255, 255), 2)
+
+    if frame_idx % 30 == 0:
+        print(f"frame {frame_idx}: {banner}", flush=True)
+
+    writer.write(frame)
+
+cap.release()
+writer.release()
+print(f"Summary: People={totals['People']} Vehicles={totals['Vehicles']}")
+print("Saved: output_openvino.mp4")
+```
+
+**Device targets:**
+
+- `"CPU"` -- default, works on all Intel platforms.
+- `"GPU"` -- Intel integrated or discrete GPU.
+- `"NPU"` -- Intel NPU (validate with `benchmark_app -d NPU`).
+
+### Try It on a Sample Video
+
+The `export_and_quantize.sh` script downloads `test_video.mp4` automatically.
+Re-run the OpenVINO sample above.
+The script reads `test_video.mp4`, prints the running People and Vehicles counts to the console, and writes the annotated video to `output_openvino.mp4`.
+
+Expected console output (representative):
+
+```text
+frame 30: People: 4  Vehicles: 6
+frame 60: People: 3  Vehicles: 7
+frame 90: People: 5  Vehicles: 5
+Summary: People=372 Vehicles=548
+Saved: output_openvino.mp4
+```
+
+#### Expected Output
+
+![OpenVINO expected output](expected_output_openvino.gif)
+
+### DLStreamer Sample
+
+The pipeline below runs the FP16 YOLO26 detector on the sample video via
+`gvadetect`, overlays bounding boxes with `gvawatermark` for the traffic-relevant
+classes only (non-traffic detections such as `handbag` are filtered out via
+`show-roi`), saves the annotated result to `output_dlstreamer.mp4`, and prints the
+`People` and `Vehicles` category counts per frame from the detection metadata.
+
+> **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 gi
+
+gi.require_version("Gst", "1.0")
+gi.require_version("GstAnalytics", "1.0")
+from gi.repository import Gst, GLib, GstAnalytics
+
+Gst.init([])
+
+INPUT_VIDEO = "test_video.mp4"
+
+# Traffic-relevant COCO labels grouped into higher-level city categories.
+CATEGORY_BY_LABEL = {
+    "person": "People",
+    "bicycle": "Vehicles",
+    "car": "Vehicles",
+    "motorcycle": "Vehicles",
+    "bus": "Vehicles",
+    "train": "Vehicles",
+    "truck": "Vehicles",
+}
+
+# For CPU: change device=GPU to device=CPU.
+# For NPU: change device=GPU to device=NPU (batch-size=1, nireq=4 recommended).
+# gvawatermark displ-cfg:
+#   show-roi=... draws only the traffic-relevant classes (person + vehicles),
+#     so non-traffic detections such as handbag/backpack are not boxed.
+#   font-scale=1.5 enlarges the label text for better visualization.
+pipeline_str = (
+    f"filesrc location={INPUT_VIDEO} ! decodebin3 ! "
+    "videoconvert ! "
+    "gvadetect model=yolo26n_openvino_model/yolo26n.xml "
+    "device=GPU "
+    "threshold=0.4 ! queue ! "
+    "gvawatermark "
+    "displ-cfg=show-roi=person:bicycle:car:motorcycle:bus:train:truck,font-scale=2.5 ! "
+    "videoconvert ! video/x-raw,format=I420 ! "
+    "openh264enc ! h264parse ! "
+    "mp4mux ! filesink name=sink location=output_dlstreamer.mp4"
+)
+pipeline = Gst.parse_launch(pipeline_str)
+
+totals = {"People": 0, "Vehicles": 0}
+
+
+def on_buffer(pad, info):
+    buf = info.get_buffer()
+    rmeta = GstAnalytics.buffer_get_analytics_relation_meta(buf)
+    if rmeta is None:
+        return Gst.PadProbeReturn.OK
+    counts = {"People": 0, "Vehicles": 0}
+    idx = 1
+    while True:
+        ok, od = rmeta.get_od_mtd(idx)
+        if not ok:
+            break
+        label = GLib.quark_to_string(od.get_obj_type())
+        category = CATEGORY_BY_LABEL.get(label)
+        if category is not None:
+            counts[category] += 1
+            totals[category] += 1
+        idx += 1
+    if counts["People"] or counts["Vehicles"]:
+        print(f"frame: People={counts['People']} Vehicles={counts['Vehicles']}",
+              flush=True)
+    return Gst.PadProbeReturn.OK
+
+
+sink = pipeline.get_by_name("sink")
+sink_pad = sink.get_static_pad("sink")
+sink_pad.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"Summary: People={totals['People']} Vehicles={totals['Vehicles']}")
+```
+
+#### Expected Output
+
+![DLStreamer expected output](expected_output_dlstreamer.gif)
+
+**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.
+
+---
+
+## License
+
+Licensed under the MIT License. See [LICENSE](LICENSE) for details.
+
+## References
+
+- [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)
+- [Sample video: Urban roundabout with cars and pedestrian (Pexels)](https://www.pexels.com/video/urban-roundabout-with-cars-and-pedestrian-30119018/)
+- [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,116 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MIT
+# Copyright (C) Intel Corporation
+#
+# Export a YOLO26 detector to OpenVINO IR for the object-classification use case.
+# The accompanying samples group detected objects into higher-level city
+# categories (People, Vehicles) for traffic situational awareness.
+# 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 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 a sample traffic video"
+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 video (urban roundabout) ---"
+if [[ ! -f test_video.mp4 ]]; then
+    wget -q -O test_video.mp4 \
+        "https://www.pexels.com/download/video/30119018/?fps=59.94&h=720&w=1280"
+    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
+import cv2
+
+core = ov.Core()
+model = core.read_model('${MODEL_NAME}_openvino_model/${MODEL_NAME}.xml')
+
+# Calibrate on a representative frame from the sample traffic video.
+cap = cv2.VideoCapture('test_video.mp4')
+ok, frame = cap.read()
+cap.release()
+if not ok:
+    raise SystemExit('Could not read a calibration frame from test_video.mp4')
+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, ...]  # NCHW
+
+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}_objcls_int8.xml')
+print('Quantization complete: ${MODEL_NAME}_objcls_int8.xml')
+"
+fi
+echo "--- Done ---"