Skip to main content

OpenCV utilities for reading video frames

Project description

Video Utilities for OpenCV

videoutils lets you get rid of writing boilerplate code for reading video and adds some convenience on top of that.


pip install videoutils

How to use

from import read_video, as_tensor, bgr2rgb, resize
fname = 'files/interstellar-waves-edit.mp4'
x = read_video(fname)

(480, 720, 3)

By default, read_video returns a list of np.arrays of shape (height, width, channels).
However, you can define precisely which frames you'd like to grab in a number of ways. This is done by using either the {start_idx, end_idx, frame_stride} or target_frames arguments.

Grab the first n frames

n = 50
x  = read_video(fname, end_idx=n)
x2 = read_video(fname, target_frames=(0,n))

len(x) == len(x2)


Grab every nth frame

x = read_video(fname, frame_stride=n, end_idx=50)
x = read_video(fname, frame_stride=50) # total frames = 1578

Grab frames at specific indices

x = read_video(fname, target_frames=[10, 50, 76, 420])
x  = read_video(fname, start_idx=10, end_idx=15)
x2 = read_video(fname, target_frames=(10, 15))

len(x) == len(x2)


Return as torch.Tensor

You can pass any function that transforms a np.array of shape (height, width, channels) to the apply argument. videoutils provides as_tensor for convenience -- if you use this function, read_video will automatically call torch.stack and return the collection of frames as a 4D tensor, else it will return a list of 3D arrays/tensors.

import torch
from functools import partial

x  = read_video(fname, end_idx=10, apply=as_tensor)
x2 = read_video(fname, end_idx=10, apply=partial(as_tensor, normalise=True))
x2 = torch.stack(x2) # since we aren't using `as_tensor`, but a partial (thus different) function

x.shape == x2.shape
x.mean(), x2.mean()
torch.Size([10, 480, 720, 3])


(tensor(36.8276), tensor(0.1443))

Resize Video

read_video has an optional argument resize_func which is meant to be a function that resizes a np.array of shape (height, width, channels).
You can use the predefined resize function or pass in a custom function here.

Help on function resize in module videoutils.utils:

resize(image, height=None, width=None, keep_aspect_ratio=True, scale_factor=1.0)
    Resize by `scale_factor` if preserving aspect ratio else
    resize by custom `height` and `width`
x = read_video(fname, target_frames=[0,1,2], apply=as_tensor,
               resize_func=partial(resize, scale_factor=2.))
torch.Size([3, 960, 1440, 3])
x = read_video(fname, target_frames=[0,1,2], apply=as_tensor,
               resize_func=partial(resize, width=200, height=100, keep_aspect_ratio=False))
torch.Size([3, 100, 200, 3])

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for videoutils, version 0.0.35
Filename, size File type Python version Upload date Hashes
Filename, size videoutils-0.0.35-py3-none-any.whl (10.3 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size videoutils-0.0.35.tar.gz (6.8 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page