Scene Cut Detector

DeGirum Tools API Reference Guide. Detect scene cuts in video for use with ObjectTracker and other analyzers.

This API Reference is based on DeGirum Tools version 1.2.0.

Scene Cut Detector Analyzer Module Overview

This module provides an analyzer (SceneCutDetector) for detecting scene cuts in video streams by comparing frame-to-frame differences using an adaptive thresholding approach. The detector is based on the PySceneDetect adaptive algorithm, which calculates differences in HSV color space and uses a rolling average to adapt to local changes.

Key Features

• Adaptive Thresholding: Uses rolling average of previous frames to adapt to gradual changes

• HSV Color Space: Analyzes differences in hue, saturation, and luminance channels

• Fast Processing: Supports luma-only mode and automatic frame resizing for performance

• Configurable Parameters: Adjustable sensitivity, minimum scene length, and window size

• Real-time Detection: Causal approach using only past frames for zero latency

• Scene Cut Flag: Adds scene_cut boolean attribute to inference results

Typical Usage

1. Create a SceneCutDetector instance with desired parameters

2. Attach it to a model or inference pipeline

3. Process video frames through the analyzer

4. Check result.scene_cut flag to detect scene transitions

5. Use scene cut information for downstream processing or triggering actions

Put it before ObjectTracker in the analyzer pipeline to ensure cuts are detected before tracking is applied, allowing you to reset object tracker on scene changes.

Integration Notes

• Works with any inference results that contain image data

• Can be combined with other analyzers in a pipeline

• Useful for video segmentation, activity detection, and content analysis

• Maintains internal state to track frame history

Configuration Options

• adaptive_threshold: Sensitivity ratio for detecting cuts (higher = less sensitive)

• min_scene_len: Minimum frames between detected cuts to avoid false positives

• window_width: Number of previous frames for rolling average calculation

• min_content_val: Minimum absolute change threshold for scene cuts

• luma_only: Use only brightness changes for faster processing

Key Classes

• SceneCutDetector: Main analyzer class for scene cut detection

Classes

SceneCutDetector

SceneCutDetector

Bases: ResultAnalyzerBase

Analyzer for detecting scene cuts using adaptive thresholding.

This analyzer examines consecutive frames and detects scene cuts when the frame-to-frame difference significantly exceeds the rolling average of recent frames. It uses HSV color space analysis to detect content changes while adapting to gradual variations like camera motion or lighting changes.

The detector adds a scene_cut boolean attribute to each inference result indicating whether a scene cut was detected at that frame.

Attributes:

Name	Type	Description
adaptive_threshold	float	Ratio threshold for scene cut detection.
min_scene_len	int	Minimum frames between consecutive scene cuts.
window_width	int	Number of previous frames used for rolling average.
min_content_val	float	Minimum absolute content change threshold.
luma_only	bool	Whether to use only luminance channel for comparison.
resize_limit	int	Maximum image dimension to apply frame resizing to improve performance.

SceneCutDetector Methods

__init__(*, ...)

__init__(*, adaptive_threshold=3.0, min_scene_len=15, window_width=4, min_content_val=15.0, luma_only=False, resize_limit=240)

Initialize the scene cut detector.

Parameters:

Name	Type	Description	Default
adaptive_threshold	float	Ratio that the frame score must exceed relative to the average of surrounding frames to trigger a cut. Default 3.0 means the frame must have 3x more change than its neighbors.	3.0
min_scene_len	int	Minimum number of frames between detected cuts. Default 15 frames.	15
window_width	int	Number of previous frames to use for computing the rolling average. Must be at least 1. Default 4.	4
min_content_val	float	Minimum absolute change threshold. Even if the adaptive ratio is exceeded, the absolute change must be at least this value. Default 15.0.	15.0
luma_only	bool	If True, only considers changes in luminance (brightness), ignoring color information for faster processing. Default False.	False
resize_limit	int	Maximum image dimension to apply frame resizing to improve performance. Frames larger than 1.5x this limit will be resized. Default 240.	240

analyze(result)

analyze(result)

Analyze a frame and detect scene cuts using adaptive thresholding.

This method processes the image from the inference result, calculates the frame-to-frame content difference, and sets result.scene_cut to True if a scene cut is detected, False otherwise.

Uses a causal approach: compares the current frame score against the average of previous frame scores, enabling real-time detection with no latency.

Parameters:

Name	Type	Description	Default
result	InferenceResults	The inference result containing the image to analyze.	required

Returns:

Name	Type	Description
None	None	Modifies result in place by adding the scene_cut attribute.