StatsManager — PySceneDetect 0.6.5-dev1 documentation

# StatsManager

`scenedetect.stats_manager` Module

This module contains the `StatsManager` class, which provides a key-value store for each `SceneDetector` to write the metrics calculated for each frame. The `StatsManager` must be registered to a `SceneManager` upon construction.

The entire `StatsManager` can be `saved to` a human-readable CSV file, allowing for precise determination of the ideal threshold (or other detection parameters) for the given input.

exception scenedetect.stats_manager.StatsFileCorrupt(message='Could not load frame metric data data from passed CSV file.')

  Raised when frame metrics/stats could not be loaded from a provided CSV file.

  Parameters:

    message (str) –

class scenedetect.stats_manager.StatsManager(base_timecode=None)

  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.

  Initialize a new StatsManager.

  Parameters:

    base_timecode (FrameTimecode) – Timecode associated with this object. Must not be None (default value will be removed in a future release).

  get_metrics(frame_number, metric_keys)

    Return the requested statistics/metrics for a given frame.

    Parameters:

      - frame_number (int) – Frame number to retrieve metrics for.

      - metric_keys (List[str]) – A list of metric keys to look up.

    Returns:

      A list containing the requested frame metrics for the given frame number in the same order as the input list of metric keys. If a metric could not be found, None is returned for that particular metric.

    Return type:

      List[Any]

  is_save_required()

    Is Save Required: Checks if the stats have been updated since loading.

    Returns:

      True if there are frame metrics/statistics not yet written to disk, False otherwise.

    Return type:

      bool

  metrics_exist(frame_number, metric_keys)

    Metrics Exist: Checks if the given metrics/stats exist for the given frame.

    Returns:

      True if the given metric keys exist for the frame, False otherwise.

    Return type:

      bool

    Parameters:

      - frame_number (int) –

      - metric_keys (Iterable[str]) –

  register_metrics(metric_keys)

    Register a list of metric keys that will be used by the detector.

    Parameters:

      metric_keys (Iterable[str]) –

    Return type:

      None

  save_to_csv(csv_file, base_timecode=None, force_save=True)

    Save To CSV: Saves all frame metrics stored in the StatsManager to a CSV file.

    Parameters:

      - csv_file (str | bytes | TextIO) – A file handle opened in write mode (e.g. open(’…’, ‘w’)) or a path as str.

      - base_timecode (FrameTimecode | None) – [DEPRECATED] DO NOT USE. For backwards compatibility.

      - force_save – If True, writes metrics out even if an update is not required.

    Raises:

      OSError – If path cannot be opened or a write failure occurs.

    Return type:

      None

  set_metrics(frame_number, metric_kv_dict)

    Set Metrics: Sets the provided statistics/metrics for a given frame.

    Parameters:

      - frame_number (int) – Frame number to retrieve metrics for.

      - metric_kv_dict (Dict[str, Any]) – A dict mapping metric keys to the respective integer/floating-point metric values to set.

    Return type:

      None

  static valid_header(row)

    Check that the given CSV row is a valid header for a statsfile.

    Parameters:

      row (List[str]) – A row decoded from the CSV reader.

    Returns:

      True if row is a valid statsfile header, False otherwise.

    Return type:

      bool

scenedetect.stats_manager.COLUMN_NAME_FRAME_NUMBER = 'Frame Number'

  Name of column containing frame numbers in the statsfile CSV.

scenedetect.stats_manager.COLUMN_NAME_TIMECODE = 'Timecode'

  Name of column containing timecodes in the statsfile CSV.