| --- |
| license: mit |
| license_link: LICENSE |
| library_name: openvino |
| pipeline_tag: object-detection |
| tags: |
| - openvino |
| - intel |
| - yolo |
| - yolo26 |
| - perimeter-breach-detection |
| - intrusion-detection |
| - zone-analytics |
| - tracking |
| - gstanalytics |
| - gvaanalytics |
| - edge-ai |
| - metro |
| - dlstreamer |
| language: |
| - en |
| --- |
| |
| # Perimeter Breach Detection |
|
|
| | Property | Value | |
| |---|---| |
| | **Category** | Object Detection + Tracking + Zone Analytics (GstAnalytics) | |
| | **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** | `person` (COCO class 0) | |
|
|
| --- |
|
|
| ## Overview |
|
|
| Perimeter Breach Detection is a Metro Analytics use case that flags people who breach a secured perimeter marked by yellow and black safety tape. |
| 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. |
| The restricted region is a polygon that traces the safety tape: in the bundled sample video the yellow and black tape forms a diagonal boundary across the floor, and the default zone covers the keep-out side of that boundary. |
| A person whose center falls inside the polygon is reported as a perimeter breach. |
| The model is a quantized (INT8) state-of-the-art detector; smaller variants run at high FPS on edge hardware. |
|
|
| Typical Metro deployments include: |
|
|
| - **Fence-Line Protection** -- trigger when a person crosses a fence or barrier around depots, yards, or substations. |
| - **Secured-Transportation Facilities** -- monitor taped-off loading docks, platforms, and maintenance bays that must stay clear. |
| - **Work-Zone Safety** -- alert when a worker or bystander enters a taped hazard area near equipment or track work. |
| - **Restricted-Area Enforcement** -- raise alerts when anyone enters a standoff boundary marked with safety tape. |
|
|
| Available variants: `yolo26n`, `yolo26s`, `yolo26m`, `yolo26l`, `yolo26x`. |
| Smaller variants (`yolo26n`, `yolo26s`) are recommended for high-FPS edge deployment. |
|
|
| --- |
|
|
| ## 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`, `opencv-python`; adds `nncf` for INT8). |
| 2. Downloads the sample worker-zone video (`worker-zone-detection.mp4`) 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: |
|
|
| - `yolo26n_openvino_model/` -- FP32 or FP16 OpenVINO IR model directory. |
| - `yolo26n_perimeter_int8.xml` / `yolo26n_perimeter_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 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 runs YOLO26 inference on the sample video and flags any person whose center falls inside the restricted zone as a breach. |
| The zone is the `RESTRICTED_ZONE` polygon, which traces the yellow and black safety tape in the sample video's `1920x1080` pixel space: the tape runs as a diagonal boundary from `(1577, 0)` to `(434, 1079)`, and the polygon covers the keep-out side of that line. |
| To adapt the perimeter to a different camera, edit the `RESTRICTED_ZONE` points. |
| YOLO26 is end-to-end (NMS-free), so no manual non-maximum suppression is needed. |
| Breaching people are drawn with a red box and a `BREACH` label; the annotated result is written to `output_openvino.mp4`. |
| Change the `device` string to run on CPU, GPU, or NPU. |
|
|
| ```python |
| import cv2 |
| import numpy as np |
| import openvino as ov |
| |
| PERSON_CLASS_ID = 0 |
| CONF_THRESHOLD = 0.4 |
| INPUT_SIZE = 640 |
| INPUT_VIDEO = "worker-zone-detection.mp4" |
| |
| # Restricted zone traced from the yellow-and-black safety tape in the sample |
| # video (1920x1080). The tape runs diagonally from (1577, 0) to (434, 1079); |
| # this polygon covers the keep-out side of that boundary. Edit these points to |
| # retrace the tape for a different camera. |
| RESTRICTED_ZONE = np.array([[0, 0], [1577, 0], [434, 1079], [0, 1080]], dtype=np.int32) |
| |
| 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(INPUT_VIDEO) |
| fps = cap.get(cv2.CAP_PROP_FPS) or 25.0 |
| w0 = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)) |
| h0 = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT)) |
| |
| zone = RESTRICTED_ZONE |
| |
| writer = cv2.VideoWriter( |
| "output_openvino.mp4", cv2.VideoWriter_fourcc(*"mp4v"), fps, (w0, h0) |
| ) |
| |
| sx, sy = w0 / INPUT_SIZE, h0 / INPUT_SIZE |
| 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])[compiled.output(0)][0] |
| mask = (output[:, 4] >= CONF_THRESHOLD) & (output[:, 5].astype(int) == PERSON_CLASS_ID) |
| |
| # Draw the translucent restricted zone first, then the person boxes on top. |
| overlay = frame.copy() |
| cv2.fillPoly(overlay, [zone], (0, 0, 255)) |
| cv2.addWeighted(overlay, 0.25, frame, 0.75, 0, frame) |
| cv2.polylines(frame, [zone], True, (0, 255, 255), 2) |
| |
| breaches = 0 |
| for det in output[mask]: |
| x1, y1 = int(det[0] * sx), int(det[1] * sy) |
| x2, y2 = int(det[2] * sx), int(det[3] * sy) |
| center = (int((x1 + x2) / 2), int((y1 + y2) / 2)) |
| inside = cv2.pointPolygonTest(zone, center, False) >= 0 |
| color = (0, 0, 255) if inside else (0, 255, 0) |
| cv2.rectangle(frame, (x1, y1), (x2, y2), color, 2) |
| if inside: |
| breaches += 1 |
| cv2.putText( |
| frame, "BREACH", (x1, max(y1 - 6, 12)), |
| cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 0, 255), 2, |
| ) |
| |
| cv2.putText( |
| frame, f"Breaches: {breaches}", (10, 30), |
| cv2.FONT_HERSHEY_SIMPLEX, 1.0, (0, 0, 255), 2, |
| ) |
| if breaches: |
| print(f"frame {frame_idx}: perimeter breach - {breaches} person(s) inside zone", flush=True) |
| writer.write(frame) |
| |
| cap.release() |
| writer.release() |
| print("Saved: output_openvino.mp4") |
| ``` |
|
|
| **Device targets:** |
|
|
| - `"CPU"` -- default, works on all Intel platforms. |
| - `"GPU"` -- Intel integrated or discrete GPU. |
| - `"NPU"` -- Intel NPU (different throughput profile; validate with `benchmark_app -d NPU`). |
|
|
| #### Expected Output |
|
|
|  |
|
|
| `output_openvino.mp4` shows the restricted perimeter shaded in red, a green box around each person outside the zone, and a red `BREACH` box around anyone inside it. |
|
|
| ### DLStreamer Sample |
|
|
| The pipeline below runs the FP16 YOLO26 detector on the sample video via `gvadetect`, tracks each person with `gvatrack`, and uses DLStreamer's `gvaanalytics` element to test membership in the restricted zone. |
| The zone is the same `RESTRICTED_ZONE` polygon used by the OpenVINO sample, passed to `gvaanalytics` as a JSON zone, so no polygon math is required in the code. |
| `gvaanalytics` attaches `GstAnalyticsZoneMtd` to every tracked person whose center falls inside the polygon. |
| The pipeline ends in an `appsink`; for each frame a callback reads the analytics metadata, shades the restricted zone, draws a green box around people outside it and a red `BREACH` box around anyone inside, and writes the annotated result to `output_dlstreamer.mp4`. |
| A perimeter-breach event is printed the first time each tracked person enters the zone. |
|
|
| > **Notes on running this sample:** |
| > |
| > - Use the FP16 IR (`yolo26n_openvino_model/yolo26n.xml`). |
| > On DLStreamer 2026.1, `gvadetect` cannot auto-derive a YOLO post-processor |
| > from the INT8 model produced by the bundled script. |
| > To use the INT8 model, supply a matching `model-proc` JSON. |
| > - 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 json |
| import sys |
| import gi |
| |
| gi.require_version("Gst", "1.0") |
| gi.require_version("GstApp", "1.0") |
| gi.require_version("GstAnalytics", "1.0") |
| gi.require_version("DLStreamerMeta", "1.0") |
| from gi.repository import Gst, GLib, GstApp, GstAnalytics, DLStreamerMeta |
| |
| Gst.init([]) |
| |
| # Register DLStreamerMeta types so GstAnalytics iteration can handle them. |
| _ov = sys.modules["gi.overrides.GstAnalytics"] |
| _ov.__mtd_types__[DLStreamerMeta.ZoneMtd.get_mtd_type()] = DLStreamerMeta.relation_meta_get_zone_mtd |
| |
| # Import OpenCV after Gst.init to avoid a GStreamer re-initialization conflict. |
| import cv2 |
| import numpy as np |
| |
| MODEL = "yolo26n_openvino_model/yolo26n.xml" |
| VIDEO = "worker-zone-detection.mp4" |
| DEVICE = "GPU" # change to "CPU" or "NPU" as needed |
| |
| # Restricted zone traced from the yellow-and-black safety tape in the sample |
| # video (1920x1080), matching the OpenVINO sample. Edit these points to retrace |
| # the tape for a different camera. |
| RESTRICTED_ZONE = np.array([[0, 0], [1577, 0], [434, 1079], [0, 1080]], dtype=np.int32) |
| ZONE_JSON = json.dumps([{ |
| "id": "restricted_zone", |
| "type": "polygon", |
| "points": [{"x": int(x), "y": int(y)} for x, y in RESTRICTED_ZONE], |
| }]) |
| |
| pipeline = Gst.parse_launch( |
| f"filesrc location={VIDEO} ! decodebin3 ! videoconvert ! " |
| f"gvadetect model={MODEL} device={DEVICE} threshold=0.4 ! queue ! " |
| f"gvatrack tracking-type=short-term-imageless ! queue ! " |
| f"gvaanalytics name=analytics ! queue ! " |
| f"videoconvert ! video/x-raw,format=BGR ! " |
| f"appsink name=sink emit-signals=true max-buffers=4 drop=false sync=false" |
| ) |
| pipeline.get_by_name("analytics").set_property("zones", ZONE_JSON) |
| |
| writer = {"w": None} |
| # Track IDs that have already triggered a breach event, so each intruder is |
| # reported only once. |
| flagged = set() |
| |
| |
| def on_sample(appsink): |
| sample = appsink.emit("pull-sample") |
| if sample is None: |
| return Gst.FlowReturn.OK |
| buf = sample.get_buffer() |
| caps = sample.get_caps().get_structure(0) |
| w = caps.get_value("width") |
| h = caps.get_value("height") |
| ok_fr, fr_n, fr_d = caps.get_fraction("framerate") |
| fps = (fr_n / fr_d) if (ok_fr and fr_d) else 30.0 |
| |
| ok, minfo = buf.map(Gst.MapFlags.READ) |
| if not ok: |
| return Gst.FlowReturn.OK |
| frame = np.ndarray((h, w, 3), buffer=minfo.data, dtype=np.uint8).copy() |
| buf.unmap(minfo) |
| |
| now = buf.pts / Gst.SECOND if buf.pts != Gst.CLOCK_TIME_NONE else 0.0 |
| |
| # Shade the restricted zone and outline the tape boundary. |
| overlay = frame.copy() |
| cv2.fillPoly(overlay, [RESTRICTED_ZONE], (0, 0, 255)) |
| cv2.addWeighted(overlay, 0.25, frame, 0.75, 0, frame) |
| cv2.polylines(frame, [RESTRICTED_ZONE], True, (0, 255, 255), 2) |
| |
| breaches = 0 |
| rmeta = GstAnalytics.buffer_get_analytics_relation_meta(buf) |
| if rmeta: |
| for od in rmeta.iter_on_type(GstAnalytics.ODMtd): |
| if GLib.quark_to_string(od.get_obj_type()) != "person": |
| continue |
| _, x, y, bw, bh, _ = od.get_location() |
| |
| # Find the tracking ID via the direct relation. |
| track_id = None |
| for trk in od.iter_direct_related(GstAnalytics.RelTypes.RELATE_TO, GstAnalytics.TrackingMtd): |
| success, tid, *_ = trk.get_info() |
| if success: |
| track_id = tid |
| break |
| |
| # gvaanalytics attaches a ZoneMtd relation when the person is in the zone. |
| in_zone = any( |
| True for _ in od.iter_direct_related(GstAnalytics.RelTypes.RELATE_TO, DLStreamerMeta.ZoneMtd) |
| ) |
| color = (0, 0, 255) if in_zone else (0, 255, 0) |
| cv2.rectangle(frame, (int(x), int(y)), (int(x + bw), int(y + bh)), color, 3) |
| label = f"id {track_id}" if track_id is not None else "person" |
| if in_zone: |
| breaches += 1 |
| cv2.putText(frame, f"BREACH {label}", (int(x), max(int(y) - 8, 14)), |
| cv2.FONT_HERSHEY_SIMPLEX, 0.7, (0, 0, 255), 2) |
| if track_id is not None and track_id not in flagged: |
| flagged.add(track_id) |
| print(f"PERIMETER BREACH id={track_id} t={now:.1f}s " |
| f"entered restricted zone at ({int(x + bw / 2)},{int(y + bh)})", flush=True) |
| else: |
| cv2.putText(frame, label, (int(x), max(int(y) - 8, 14)), |
| cv2.FONT_HERSHEY_SIMPLEX, 0.7, (0, 255, 0), 2) |
| |
| cv2.putText(frame, f"Breaches: {breaches}", (10, 40), |
| cv2.FONT_HERSHEY_SIMPLEX, 1.1, (0, 0, 255), 3) |
| if writer["w"] is None: |
| writer["w"] = cv2.VideoWriter( |
| "output_dlstreamer.mp4", cv2.VideoWriter_fourcc(*"mp4v"), fps, (w, h) |
| ) |
| writer["w"].write(frame) |
| return Gst.FlowReturn.OK |
| |
|
|
| pipeline.get_by_name("sink").connect("new-sample", on_sample) |
| pipeline.set_state(Gst.State.PLAYING) |
| pipeline.get_bus().timed_pop_filtered(Gst.CLOCK_TIME_NONE, Gst.MessageType.EOS | Gst.MessageType.ERROR) |
| pipeline.set_state(Gst.State.NULL) |
| if writer["w"] is not None: |
| writer["w"].release() |
| ``` |
| |
| Expected output: |
|
|
| ```text |
| PERIMETER BREACH id=2 t=3.8s entered restricted zone at (799,1067) |
| PERIMETER BREACH id=8 t=13.7s entered restricted zone at (789,1069) |
| ... |
| ``` |
|
|
| The annotated video is saved to `output_dlstreamer.mp4`. |
| It shows the restricted zone shaded in red with the tape boundary outlined, a green box around each person outside the zone, and a red `BREACH` box around anyone inside it -- matching the OpenVINO output. |
|
|
| #### Expected Output |
|
|
|  |
|
|
| **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"` for the Intel NPU. |
|
|
| --- |
|
|
| ## 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) |
| - [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) |
|
|
