Sync scene-change-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,204 @@
+---
+license: mit
+license_link: LICENSE
+library_name: opencv
+tags:
+  - opencv
+  - intel
+  - scene-change-detection
+  - histogram
+  - edge-ai
+  - metro
+language:
+  - en
+---
+
+# Scene Change Detection
+
+| Property | Value |
+|---|---|
+| **Category** | Scene Analytics (classical computer vision) |
+| **Base Model** | Not applicable -- uses frame histogram comparison |
+| **Source Framework** | OpenCV |
+| **Supported Precisions** | Not applicable |
+| **Inference Engine** | OpenCV (CPU) |
+| **Hardware** | CPU, GPU (OpenCV UMat optional) |
+| **Detected Class(es)** | Scene-change events |
+
+---
+
+## Overview
+
+Scene Change Detection is a Metro Analytics use case that flags abrupt or
+sustained changes in what a camera is showing, such as a shot cut, a camera
+being repositioned, or a large change in the field of view.
+It compares the color-histogram signature of each frame against the previous
+frame using the Bhattacharyya distance and raises an event when the distance
+exceeds a threshold.
+
+Histogram and similarity scoring is more robust and far cheaper than running
+an object detector for this signal, so this use case intentionally avoids a
+neural model.
+For semantic scene understanding (for example "platform" versus "concourse"),
+pair this with the [object-detection](../object-detection/) use case.
+
+Typical Metro deployments include:
+
+- **Camera Repositioning Alerts** -- detect when a PTZ camera moves to a new view.
+- **Video Segmentation** -- split long recordings into scenes for indexing.
+- **Content Validation** -- confirm a feed switched to the expected source.
+- **Pre-filter for Analytics** -- re-initialize trackers when the scene changes.
+
+---
+
+## Prerequisites
+
+- Python 3.11+
+- [Install OpenVINO](https://docs.openvino.ai/2026/get-started/install-openvino.html) (latest version)
+- `ffmpeg` (used by `export_and_quantize.sh` to build the sample montage)
+
+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 Python packages
+> (which provide OpenCV).
+
+---
+
+## Getting Started
+
+### Download the Sample Video
+
+This use case does not export or quantize a model.
+Run the provided script to prepare the sample test video:
+
+```bash
+chmod +x export_and_quantize.sh
+./export_and_quantize.sh
+```
+
+A single continuous shot never triggers a scene change, so the script
+downloads several distinct sample clips and joins them with hard cuts into
+`test_video.mp4` (four 2-second scenes). This produces a clear scene change
+every two seconds for the detector to flag. The script requires `ffmpeg` to
+build the montage.
+
+### OpenCV Sample
+
+The sample below computes a normalized HSV histogram for each frame, compares
+it to the previous frame with the Bhattacharyya distance, and flags a scene
+change when the distance exceeds `CHANGE_THRESHOLD`.
+The annotated frames are written to `output_opencv.mp4`.
+
+```python
+import cv2
+import numpy as np
+
+INPUT_VIDEO = "test_video.mp4"
+CHANGE_THRESHOLD = 0.45  # Bhattacharyya distance in [0, 1]; higher = more change
+
+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))
+
+
+def frame_histogram(bgr):
+    hsv = cv2.cvtColor(bgr, cv2.COLOR_BGR2HSV)
+    hist = cv2.calcHist([hsv], [0, 1], None, [50, 60], [0, 180, 0, 256])
+    cv2.normalize(hist, hist, 0, 1, cv2.NORM_MINMAX)
+    return hist
+
+
+prev_hist = None
+frame_idx = 0
+scene_changes = 0
+while True:
+    ok, frame = cap.read()
+    if not ok:
+        break
+    frame_idx += 1
+    hist = frame_histogram(frame)
+
+    distance = 0.0
+    changed = False
+    if prev_hist is not None:
+        distance = cv2.compareHist(prev_hist, hist, cv2.HISTCMP_BHATTACHARYYA)
+        changed = distance >= CHANGE_THRESHOLD
+    prev_hist = hist
+
+    if changed:
+        scene_changes += 1
+        print(f"Frame {frame_idx}: SCENE CHANGE (distance={distance:.3f})",
+              flush=True)
+    color = (0, 0, 255) if changed else (0, 255, 0)
+    label = f"dist={distance:.3f}" + (" CHANGE" if changed else "")
+    cv2.putText(frame, label, (10, 30),
+                cv2.FONT_HERSHEY_SIMPLEX, 0.8, color, 2)
+    writer.write(frame)
+
+cap.release()
+writer.release()
+print(f"Scene changes detected: {scene_changes}", flush=True)
+```
+
+**Device targets:**
+
+- `"CPU"` -- default for OpenCV histogram comparison.
+- `"GPU"` -- wrap frames in `cv2.UMat` to use the OpenCV transparent API on Intel GPUs.
+- `"NPU"` -- not applicable; histogram comparison is not a neural workload.
+
+### Scene-Change Terminal Logging
+
+Every time the Bhattacharyya distance crosses `CHANGE_THRESHOLD`, the sample
+treats it as a new scene and prints a line to the terminal with the frame
+number and the distance that triggered it. A running total is printed when the
+video ends. This makes the terminal a lightweight event log you can pipe to a
+file or another process without inspecting the annotated video.
+
+The relevant lines in the sample are:
+
+```python
+if changed:
+    scene_changes += 1
+    print(f"Frame {frame_idx}: SCENE CHANGE (distance={distance:.3f})",
+          flush=True)
+```
+
+#### Expected Terminal Output
+
+Running the sample against the four-scene montage produces one log line per cut
+(at ~2s, ~4s, and ~6s), followed by the summary:
+
+```text
+Frame 61: SCENE CHANGE (distance=0.949)
+Frame 121: SCENE CHANGE (distance=0.988)
+Frame 181: SCENE CHANGE (distance=0.854)
+Scene changes detected: 3
+```
+
+#### Expected Output
+
+The annotated video draws each frame's distance in green and turns the label
+red on the frame where a scene change is detected:
+
+![OpenCV expected output](expected_output_openvino.gif)
+
+---
+
+## License
+
+Licensed under the MIT License. See [LICENSE](LICENSE) for details.
+
+## References
+
+- [OpenCV Histogram Comparison](https://docs.opencv.org/4.x/d8/dc8/tutorial_histogram_comparison.html)
+- [OpenCV calcHist Reference](https://docs.opencv.org/4.x/d6/dc7/group__imgproc__hist.html)
+- [OpenVINO Documentation](https://docs.openvino.ai/)

export_and_quantize.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MIT
+# Copyright (C) Intel Corporation
+#
+# Prepare the sample video for the scene-change-detection use case.
+# This use case uses classical computer vision (frame histogram
+# comparison) with OpenCV; no model export or quantization is required.
+#
+# A single continuous shot never triggers a scene change, so this script
+# builds a short montage (test_video.mp4) from several distinct sample
+# clips joined with hard cuts. Each clip is normalized to the same size and
+# frame rate and trimmed to 2 seconds, producing a scene change every 2
+# seconds that the histogram detector flags.
+# Usage: ./export_and_quantize.sh
+
+set -euo pipefail
+
+SAMPLE_BASE_URL="https://github.com/intel-iot-devkit/sample-videos/raw/master"
+# Distinct scenes joined into the montage, in order.
+SAMPLE_CLIPS=(
+    "one-by-one-person-detection.mp4"
+    "bottle-detection.mp4"
+    "person-bicycle-car-detection.mp4"
+    "head-pose-face-detection-female.mp4"
+)
+CLIP_SECONDS=2      # length of each scene in the montage
+CLIP_WIDTH=640
+CLIP_HEIGHT=360
+CLIP_FPS=30
+
+# 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
+
+command -v ffmpeg >/dev/null 2>&1 || {
+    echo "ERROR: ffmpeg is required to build the montage sample video." >&2
+    exit 1
+}
+
+echo ""
+if [[ -f test_video.mp4 ]]; then
+    echo "Already present: test_video.mp4"
+else
+    echo "--- Downloading sample clips and building montage ---"
+    WORK_DIR="$(mktemp -d)"
+    trap 'rm -rf "${WORK_DIR}"' EXIT
+    CONCAT_LIST="${WORK_DIR}/concat.txt"
+    : > "${CONCAT_LIST}"
+
+    idx=0
+    for clip in "${SAMPLE_CLIPS[@]}"; do
+        src="${WORK_DIR}/src_${idx}.mp4"
+        norm="${WORK_DIR}/clip_${idx}.mp4"
+        echo "Downloading: ${clip}"
+        wget -q -O "${src}" "${SAMPLE_BASE_URL}/${clip}"
+        # Trim to CLIP_SECONDS and normalize size/fps so the clips concatenate
+        # cleanly and every join is a clean scene cut.
+        ffmpeg -nostdin -y -loglevel error -t "${CLIP_SECONDS}" -i "${src}" \
+            -vf "scale=${CLIP_WIDTH}:${CLIP_HEIGHT},fps=${CLIP_FPS},setsar=1" \
+            -an -pix_fmt yuv420p "${norm}"
+        echo "file 'clip_${idx}.mp4'" >> "${CONCAT_LIST}"
+        idx=$((idx + 1))
+    done
+
+    ffmpeg -nostdin -y -loglevel error -f concat -safe 0 -i "${CONCAT_LIST}" \
+        -c copy test_video.mp4
+    echo "Built: test_video.mp4 (${#SAMPLE_CLIPS[@]} scenes, ${CLIP_SECONDS}s each)"
+fi
+
+echo "--- Done ---"
+echo "Sample : $(pwd)/test_video.mp4"
+echo "Note   : This use case requires no model; run the README samples directly."