I/O functions

Note that all functions within terran.io.video.* and terran.io.image.* are re-exported at the level of terran.io.*, and that’s the recommended place to import them from.


There are two functions related to video I/O, and are the main entry points for this purpose.

Module containig I/O-related functions for video handling.

terran.io.video.open_video(*args, **kwargs)

Opens a video file or stream.

The function will guess whether the input is a video file, a capture device or a stream and will proceed as needed.

Arguments are passed verbatim to Video.

Returns:Video instance representing the video at path.
Return type:Video
terran.io.video.write_video(*args, **kwargs)

Creates a writer for a video.

Arguments are passed verbatim to VideoWriter.

Returns:VideoWriter instance representing the writer object that can be fed frames.
Return type:VideoWriter

These functions are, however, just simple wrappers around the following two classes, which contain the actual logic of reading and writing videos.

class terran.io.video.reader.Video(path, batch_size=None, framerate=None, is_stream=None, read_for=None, start_time=None, ydl_format='best')

Container class for a video, for interfacing with an underlying input.

Is tasked with handling the file descriptiors, with buffering the stream, with dropping frames when needed, with decoding frames out of the video, and more.

Initializes the reading of the video, performing the necessary checks.

Note that if duration is None and path points to a stream, Video will return frames indefinitely.

  • path (str) – Path to a video file, stream URL or capture device.
  • batch_size (int or None) – Batch size for the returned frames. If None, no batching will occur (thus, a rank 3 array will be returned).
  • framerate (int, str or None) – Framerate to output frames as. Will pass along to ffmpeg, which will drop or add frames as needed. Can be an int with the frames per second, a str with a fraction (e.g. ‘5000/1001’) or None to leave as-is.
  • is_stream (bool or None) – Whether the video is a capture device, a stream or somehow a never-ending video file. If None, will try to guess.
  • read_for (int, float or None) –

    Maximum number of seconds to read, or None for reading until the end.

    If read_for is bigger than the source duration (considering the start time), the actual video duration might be less than this value.

  • start_time (int, str or None) – Time to start video from. If an int, specified in seconds. If str, specified as a timestamp with the format HH:MM:SS.ms.
  • ydl_format (str) – The format filtering option for YouTube-DL. Check out the YouTube-DL “Format Selection” documentation for more information: https://github.com/ytdl-org/youtube-dl#format-selection
class terran.io.video.writer.VideoWriter(output_path, framerate=None, copy_format_from=None, size_hint=None, **kwargs)

Initialize the writing of a video.

Video format (codecs, framerate, etc.) can be specified using the keyword arguments, which will be fed to ffmpeg as-is, or by copying them from an existing Video.

  • (int, str or None) (framerate) – along to ffmpeg. Can be an int with the frames per second, a str with a fraction (e.g. ‘5000/1001’). Default is 30, or the framerate of copy_format_from, if specified.
  • copy_format_from (str, pathlib.Path or Video) – Either Video instance or path to video to copy format from.
  • size_hint (tuple) – (height, width) tuple indicating the frame size the video will have. Defaults to None, meaning that it will be infered from the first frame.
write_frame(frame_or_func, *args)

Write a frame or the result of a rendering function to the video.

Note that if no size_hint is provided when creating the writer, and a rendering function is passed as argument, the rendering function might be executed twice, in order to infer the size of the video to write.



Opens and returns image at uri.

Always returns a HxWxC np.array containing the image, ready to be consumed by any Terran algorithm. If the image is grayscale or has an alpha channel, it’ll get converted into RGB, so the number of channels will always be 3.

Parameters:uri (str or pathlib.Path) – URI pointing to an image, which may be a filesystem location or a URL.
Returns:Array of size HxWxC containing the pixel values for the image, as numpy.uint8.
Return type:numpy.ndarray
terran.io.image.resolve_images(path, batch_size=None)

Collects the path for all images under path, returning them by batches.

Validates that the image is valid before returning it by attempting to open it with PIL.

Parameters:path (str or pathlib.Path) – Path to recursively search for images in.
Yields:pathlib.Path or [pathlib.Path] – Path to every valid image found under path.