Class StatsManager

scenedetect/stats_manager.py:85–314

Provides a key-value store for frame metrics/calculations which can be used for two-pass detection algorithms, as well as saving stats to a CSV file. Analyzing a statistics CSV file is also very useful for finding the optimal algorithm parameters for certain detection methods. Additiona

# TODO(v1.0): Relax restriction on metric types only being float or int when loading from disk
# is fully deprecated.
class StatsManager:
    """Provides a key-value store for frame metrics/calculations which can be used
    for two-pass detection algorithms, as well as saving stats to a CSV file.

    Analyzing a statistics CSV file is also very useful for finding the optimal
    algorithm parameters for certain detection methods. Additionally, the data
    may be plotted by a graphing module (e.g. matplotlib) by obtaining the
    metric of interest for a series of frames by iteratively calling get_metrics(),
    after having called the detect_scenes(...) method on the SceneManager object
    which owns the given StatsManager instance.

    Only metrics consisting of `float` or `int` should be used currently.
    """

    def __init__(self, base_timecode: int | FrameTimecode | None = None):
        """Initialize a new StatsManager.

        Arguments:
            base_timecode: Timecode associated with this object. Must not be None (default value
                will be removed in a future release).
        """
        # Frame metrics keyed by either an `int` frame number or a `FrameTimecode`. Both forms
        # hash/compare to the same dict slot (`FrameTimecode.__hash__` returns `frame_num`), so
        # public methods accept both interchangeably for the same frame.
        self._frame_metrics: dict[int | FrameTimecode, dict[str, float]] = dict()
        self._metric_keys: set[str] = set()
        self._metrics_updated: bool = False  # Flag indicating if metrics require saving.
        self._base_timecode: int | FrameTimecode | None = (
            base_timecode  # Used for timing calculations.
        )

    @property
    def metric_keys(self) -> ty.Iterable[str]:
        return self._metric_keys

    def register_metrics(self, metric_keys: ty.Iterable[str]) -> None:
        """Register a list of metric keys that will be used by the detector."""
        self._metric_keys = self._metric_keys.union(set(metric_keys))

    # TODO(https://scenedetect.com/issues/507): We should support the dictionary protocol instead
    # of using this bespoke interface. It would be useful for Pandas compatibility as well.
    def get_metrics(
        self, timecode: int | FrameTimecode, metric_keys: ty.Iterable[str]
    ) -> list[ty.Any]:
        """Return the requested statistics/metrics for a given timecode.

        Returns:
            A list containing the requested frame metrics for the given frame number, ordered as
            they are in `metric_keys`.
        """
        return [self._get_metric(timecode, metric_key) for metric_key in metric_keys]

    def set_metrics(self, timecode: int | FrameTimecode, metric_kv_dict: dict[str, ty.Any]) -> None:
        """Set Metrics: Sets the provided statistics/metrics for a given frame.

        Arguments:
            timecode: Timecode to set metrics for.
            metric_kv_dict: Key value mapping of metrics to their values for `timecode`.