Sync loitering-detection from metro-analytics-catalog

README.md

@@ -6,7 +6,7 @@
 |---|---|
 | **Category** | Object Detection + Tracking + Zone Analytics |
 | **Source Framework** | PyTorch (Ultralytics) |
-| **Supported Precisions** | FP32, FP16, FP16-INT8 |
+| **Supported Precisions** | FP32, FP16, INT8 (mixed-precision) |
 | **Inference Engine** | OpenVINO |
 | **Hardware** | CPU, GPU, NPU |
 | **Detected Class** | `person` (COCO class 0) |
@@ -44,6 +44,10 @@ 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
@@ -155,7 +159,7 @@ pipeline_str = (
     f"gvametaconvert add-empty-results=true ! queue ! "
     f"gvafpscounter ! "
     f"gvawatermark ! videoconvert ! video/x-raw,format=I420 ! "
-    f"x264enc ! h264parse ! "
+    f"openh264enc ! h264parse ! "
     f"mp4mux ! filesink name=sink location=output.mp4"
 )
 pipeline = Gst.parse_launch(pipeline_str)
@@ -231,16 +235,28 @@ bus.timed_pop_filtered(
 pipeline.set_state(Gst.State.NULL)
 ```
 
-Expected output with the sample video and the zone/threshold above:
+Expected output with the sample video and the zone/threshold above
+(exact track IDs and anchor coordinates may vary between runs due to
+tracker non-determinism):
 
 ```text
-LOITERING id=2 dwell=1.6s anchor=(529,258)
-LOITERING id=9 dwell=1.6s anchor=(527,250)
+LOITERING id=26 dwell=5.0s anchor=(147,341)
+LOITERING id=27 dwell=5.0s anchor=(122,337)
+LOITERING id=29 dwell=5.0s anchor=(90,322)
+...
 ```
 
+Approximately 10–12 loitering events are expected over the full video.
+
 The annotated video is saved to `output.mp4` with green bounding boxes and
 track IDs drawn by `gvawatermark` around every detected person.
 
+> **Known warning:** The `openh264enc` element prints
+> `[OpenH264] this = 0x..., Error:CWelsH264SVCEncoder::EncodeFrame(), cmInitParaError.`
+> on the first frame. This is a benign initialization message — the output
+> video is encoded correctly. The warning comes from the OpenH264 library's
+> internal logging and does not indicate a real error.
+
 ---
 
 ## License