OpenCV / RTSP Stream Integration

VigilCV's audit_stream() generator wraps any OpenCV VideoCapture loop, adding real-time quality telemetry with sub-millisecond overhead.

Basic RTSP Stream Monitor

import cv2
from vigilcv import VisionSentinel

sentinel = VisionSentinel(
    blur_threshold=80.0,
    min_entropy=2.5,
    raise_on_fail=False,  # Don't raise; return metrics with passed=False
)

cap = cv2.VideoCapture("rtsp://camera.local/stream1")
Or for webcam: cap = cv2.VideoCapture(0)

for frame, metrics in sentinel.audit_stream(cap):
    if metrics is None:
        break  # Stream ended

    # Overlay quality telemetry
    status = "PASS" if metrics.passed else "FAIL"
    color = (0, 200, 100) if metrics.passed else (0, 80, 240)  # BGR

    cv2.putText(
        frame,
        f"Blur: {metrics.blur_score:.1f} | Entropy: {metrics.shannon_entropy:.2f} | {status}",
        (10, 30),
        cv2.FONT_HERSHEY_SIMPLEX,
        0.7,
        color,
        2,
    )

    if not metrics.passed:
        # Draw red border on degraded frames
        cv2.rectangle(frame, (0, 0), (frame.shape[1], frame.shape[0]), (0, 0, 255), 4)

    cv2.imshow("VigilCV Monitor", frame)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

cap.release()
cv2.destroyAllWindows()

Frame Sampling (High-FPS Streams)

For 60fps streams, auditing every frame is overkill. Use the sample_every parameter:

for frame, metrics in sentinel.audit_stream(cap, sample_every=5):
    # Audit 1 in every 5 frames — 12 FPS effective audit rate
    ...

Forwarding Only Clean Frames

import cv2
from vigilcv import VisionSentinel

sentinel = VisionSentinel(blur_threshold=100.0)
cap = cv2.VideoCapture("rtsp://drone-camera/main")
writer = cv2.VideoWriter("clean_output.mp4", cv2.VideoWriter_fourcc(*"mp4v"), 30, (1920, 1080))

for frame, metrics in sentinel.audit_stream(cap):
    if metrics and metrics.passed:
        writer.write(frame)  # Only write pristine frames

writer.release()

Use Case: Detecting Lens Occlusion in Production

import time
import cv2
from vigilcv import VisionSentinel

sentinel = VisionSentinel(blur_threshold=50.0, min_entropy=1.5)
cap = cv2.VideoCapture(0)

fail_streak = 0
ALERT_THRESHOLD = 30  # 30 consecutive failed frames

for frame, metrics in sentinel.audit_stream(cap):
    if not metrics or not metrics.passed:
        fail_streak += 1
        if fail_streak >= ALERT_THRESHOLD:
            print(f"ALERT: Camera {cap} potentially occluded — {fail_streak} consecutive failures")
            # Trigger PagerDuty / Slack alert here
    else:
        fail_streak = 0

Performance

All measurements on AMD Ryzen 7 5800H (single-threaded NumPy).