sampling¶

Classes

Functions

Description

class ApiContext[source]¶

Bases: object

Small per-run cache of API-fetched project/dataset/video metadata to avoid repeated requests.

class SamplingSettings[source]¶

Bases: object

Keys used in the sampling settings dict for sample_video.

async async_stream_video_frames(api, video_id, start=None, end=None, queue_maxsize=32, show_decoding_progress=False)[source]¶

Async generator that streams decoded video frames by frame index.

Builds a PTS map by demuxing the video, then decodes and yields frames in the requested range. Automatically selects the optimal decoding strategy: seek-based for most videos, or full decode from start for B-frame streams without a CTTS box.

Parameters:

api : Api¶

Supervisely API object.

video_id : int¶

Video ID in Supervisely.

start : int, optional¶

First frame index to yield (inclusive, 0-based). Defaults to 0.

end : int, optional¶

Last frame index to yield (inclusive, 0-based). Defaults to the last frame.

queue_maxsize : int, optional¶

Decode prefetch buffer size in frames (default 32). Increase on memory-rich systems for higher throughput. Peak RAM ≈ (queue_maxsize + 1) x H x W x 3 bytes.

show_decoding_progress : bool, optional¶

If True, display tqdm progress bars for the low-level I/O phases: the demuxing phase (building the PTS map) and, for the B-frame full-decode path, the decoding phase. Both bars count packets (pkt) and are independent of the per-frame progress_cb. Default False.

Yields:

Tuple of (frame_index, rgb_image) where rgb_image is a numpy.ndarray of shape (H, W, 3) in RGB uint8 format.

Return type:

AsyncGenerator[Tuple[int, numpy.ndarray], None]

Usage Example:

import supervisely as sly
from supervisely.video.sampling import async_stream_video_frames

api = sly.Api.from_env()

async for frame_idx, img in async_stream_video_frames(api, video_id=123, start=0, end=9):
    print(frame_idx, img.shape)

async async_stream_video_frames_to_dir(api, video_id, output_dir, start=None, end=None, ext='png', progress_cb=None, image_writer=None, max_write_workers=4, queue_maxsize=32, show_decoding_progress=False)[source]¶

Async version of stream_video_frames_to_dir().

Streams decoded video frames and saves them to output_dir as image files named frame_<index:06d>.<ext>.

Parameters:

api : Api¶

Supervisely API object.

video_id : int¶

Video ID in Supervisely.

output_dir : str¶

Directory where frame images will be saved.

start : int, optional¶

First frame index to save (inclusive, 0-based). Defaults to 0.

end : int, optional¶

Last frame index to save (inclusive, 0-based). Defaults to the last frame.

ext : str, optional¶

Image file extension (e.g. "png", "jpg"). Defaults to "png".

progress_cb : callable, optional¶

Callable invoked with 1 after each frame is saved.

image_writer : callable, optional¶

Custom function (path, image) -> None for writing frames. Defaults to supervisely.imaging.image.write().

max_write_workers : int, optional¶

Number of parallel write threads (default 4).

queue_maxsize : int, optional¶

Decode prefetch buffer size in frames (default 32).

show_decoding_progress : bool, optional¶

If True, display tqdm progress bars for the demuxing and (B-frame) decoding phases. See async_stream_video_frames() for details.

Returns:

List of absolute paths to saved frame files.

Return type:

List[str]

stream_video_frames_to_dir(api, video_id, output_dir, start=None, end=None, ext='png', progress_cb=None, image_writer=None, max_write_workers=4, queue_maxsize=32, show_decoding_progress=False)[source]¶

Stream decoded video frames and save them to a directory.

Decodes the requested frame range from the video (identified by video_id) and writes each frame as an image file to output_dir. Files are named frame_<index:06d>.<ext> (e.g. frame_000162.png).

Parameters:

api : Api¶

Supervisely API object.

video_id : int¶

Video ID in Supervisely.

output_dir : str¶

Directory where frame images will be saved. Created automatically if it does not exist.

start : int, optional¶

First frame index to save (inclusive, 0-based). Defaults to 0.

end : int, optional¶

Last frame index to save (inclusive, 0-based). Defaults to the last frame.

ext : str, optional¶

Image file extension (e.g. "png", "jpg"). Defaults to "png".

progress_cb : callable, optional¶

Callable invoked with 1 after each frame is saved. Useful for progress bars.

image_writer : callable, optional¶

Custom function (path, image) -> None for writing frames. Defaults to supervisely.imaging.image.write().

max_write_workers : int, optional¶

Number of parallel write threads (default 4). Increase on memory-rich systems for higher write throughput.

queue_maxsize : int, optional¶

Decode prefetch buffer size in frames (default 32). Peak RAM ≈ (queue_maxsize + max_write_workers + 1) x frame_bytes.

show_decoding_progress : bool, optional¶

If True, display tqdm progress bars for the demuxing and (B-frame) decoding phases. See async_stream_video_frames() for details.

Returns:

List of absolute paths to the saved frame files.

Return type:

List[str]

Usage Example:

import supervisely as sly
from supervisely.video.sampling import stream_video_frames_to_dir

api = sly.Api.from_env()

paths = stream_video_frames_to_dir(
    api, video_id=123, output_dir="/tmp/frames", start=0, end=9
)
print(paths)  # ['/tmp/frames/frame_000000.png', ...]