Sync light-level-anomaly-detection from metro-analytics-catalog

.gitattributes

@@ -33,3 +33,4 @@ 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_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,162 @@
+---
+license: mit
+license_link: LICENSE
+library_name: opencv
+tags:
+  - opencv
+  - intel
+  - light-level-anomaly
+  - exposure
+  - edge-ai
+  - metro
+language:
+  - en
+---
+
+# Light-Level Anomaly Detection
+
+| Property | Value |
+|---|---|
+| **Category** | Image-Quality Analytics (classical computer vision) |
+| **Base Model** | Not applicable -- uses luminance statistics |
+| **Source Framework** | OpenCV |
+| **Supported Precisions** | Not applicable |
+| **Inference Engine** | OpenCV (CPU) |
+| **Hardware** | CPU, GPU (OpenCV UMat optional) |
+| **Detected Class(es)** | Underexposure, overexposure, sudden light change |
+
+---
+
+## Overview
+
+Light-Level Anomaly Detection is a Metro Analytics use case that monitors the
+overall brightness of a camera feed and flags abnormal lighting conditions:
+the scene going dark (lights off, lens covered, night), the scene blowing out
+(glare, headlights, overexposure), or a sudden change in light level.
+It tracks the mean luminance of each frame against a rolling baseline and
+raises an event when the level leaves the acceptable band or jumps sharply.
+
+A global luminance signal is best measured directly from pixels, so this use
+case intentionally avoids a neural model.
+It is a strong building block for real-time alerting use cases.
+
+Typical Metro deployments include:
+
+- **Lighting Fault Detection** -- alert when platform or tunnel lighting fails.
+- **Day/Night Transition Handling** -- switch analytics profiles by light level.
+- **Exposure QA** -- flag cameras that are blown out or too dark to analyze.
+- **Tamper Indicator** -- a covered lens shows up as a sudden drop in light.
+
+---
+
+## Prerequisites
+
+- Python 3.11+
+- OpenCV and NumPy
+
+Create and activate a Python virtual environment before running the sample:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install opencv-python numpy
+```
+
+---
+
+## Getting Started
+
+### Download the Sample Video
+
+This use case does not export or quantize a model.
+Run the provided script to download the sample test video:
+
+```bash
+chmod +x export_and_quantize.sh
+./export_and_quantize.sh
+```
+
+The script downloads `test_video.mp4` into the current directory.
+
+### OpenCV Sample
+
+The sample below computes the mean luminance of each frame from the V channel
+of HSV, compares it against fixed dark/bright bounds and against a rolling
+baseline, and classifies each frame as `normal`, `dark`, `bright`, or
+`sudden-change`.
+The annotated frames are written to `output_opencv.mp4`.
+
+```python
+import cv2
+import numpy as np
+
+INPUT_VIDEO = "test_video.mp4"
+DARK_BOUND = 40.0    # mean luminance below this is underexposed
+BRIGHT_BOUND = 215.0  # mean luminance above this is overexposed
+JUMP_BOUND = 35.0    # frame-to-frame luminance jump that counts as sudden
+
+cap = cv2.VideoCapture(INPUT_VIDEO)
+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_opencv.mp4", cv2.VideoWriter_fourcc(*"mp4v"), fps, (width, height))
+
+prev_level = None
+frame_idx = 0
+anomalies = 0
+while True:
+    ok, frame = cap.read()
+    if not ok:
+        break
+    frame_idx += 1
+
+    v = cv2.cvtColor(frame, cv2.COLOR_BGR2HSV)[:, :, 2]
+    level = float(np.mean(v))
+
+    status = "normal"
+    if level < DARK_BOUND:
+        status = "dark"
+    elif level > BRIGHT_BOUND:
+        status = "bright"
+    elif prev_level is not None and abs(level - prev_level) >= JUMP_BOUND:
+        status = "sudden-change"
+    prev_level = level
+
+    if status != "normal":
+        anomalies += 1
+        print(f"Frame {frame_idx}: LIGHT ANOMALY ({status}) level={level:.1f}",
+              flush=True)
+    color = (0, 255, 0) if status == "normal" else (0, 0, 255)
+    label = f"level={level:.1f} {status}"
+    (_, text_height), _ = cv2.getTextSize(
+        label, cv2.FONT_HERSHEY_SIMPLEX, 5.0, 2)
+    cv2.putText(frame, label, (10, text_height + 10),
+                cv2.FONT_HERSHEY_SIMPLEX, 5.0, color, 2)
+    writer.write(frame)
+
+cap.release()
+writer.release()
+print(f"Light-level anomalies detected: {anomalies}", flush=True)
+```
+
+**Device targets:**
+
+- `"CPU"` -- default for OpenCV luminance statistics.
+- `"GPU"` -- wrap frames in `cv2.UMat` to use the OpenCV transparent API on Intel GPUs.
+- `"NPU"` -- not applicable; luminance statistics are not a neural workload.
+
+#### Expected Output
+
+![OpenCV expected output](expected_output_openvino.gif)
+
+---
+
+## License
+
+Licensed under the MIT License. See [LICENSE](LICENSE) for details.
+
+## References
+
+- [OpenCV Color Space Conversions](https://docs.opencv.org/4.x/d8/d01/group__imgproc__color__conversions.html)
+- [OpenCV Operations on Arrays (mean)](https://docs.opencv.org/4.x/d2/de8/group__core__array.html)

export_and_quantize.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MIT
+# Copyright (C) Intel Corporation
+#
+# Download the sample video for the light-level-anomaly-detection use case.
+# This use case uses classical computer vision (luminance statistics);
+# no model export or quantization is required.
+# Usage: ./export_and_quantize.sh
+
+set -euo pipefail
+
+SAMPLE_VIDEO_URL="https://www.pexels.com/download/video/1229535/"
+
+# Ask for approval before downloading models and sample files
+echo ""
+echo "This script will download:"
+echo "  - Model weights and/or sample files"
+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 ---"
+if [[ ! -f test_video.mp4 ]]; then
+    wget -q -O test_video.mp4 "${SAMPLE_VIDEO_URL}"
+    echo "Downloaded: test_video.mp4"
+else
+    echo "Already present: test_video.mp4"
+fi
+
+echo "--- Done ---"
+echo "Sample : $(pwd)/test_video.mp4"
+echo "Note   : This use case requires no model; run the README samples directly."