Source code documentation

VideoSlicer

class videoslicer.videoslicer.VideoSlicer(filename, axis=0, optimize='memory')[source]

VideoSlicer class

Reads dimensions from a video file and allows for slicing and iterating over the video data in arbitrary axis. Any slicing or iteration action will result in a VideoSlice object targeted at a specific part of the video data.

Slicing or iterating over the time dimension is both optimized for speed and memory usage. Slicing and iterating over spatial dimensions can be either optimized for speed (run over video once, collecting all data), or for memory usage (run over video multiple times, each time collecting the required amount of data).

Examples

>>> slicer = VideoSlicer('movie.avi')
>>> view = slicer[:10,::10,::10]
>>> for frame in view:
      frame.save('frame{:06d}.jpg'.format(frame.index))
>>> slicer = VideoSlicer('movie.avi')
>>> frame = slicer[10,...]
>>> frame.save('frame.jpg')
>>> frame.plot()
>>> slicer = VideoSlicer('movie.avi', axis=2) # loop over horizontal dimension
>>> for frame in slicer[:,:,::10]:
      frame.T.save('timestack{:06d}.jpg'.format(frame.index)) # transpose to have time on the horizontal axis

See also

VideoView

__getitem__(s)[source]

Returns a VideoView object given the provided slicing

See get_view for details.

__init__(filename, axis=0, optimize='memory')[source]

Initialization

Parameters:
  • filename (str) – Path to video file
  • axis (int, optional) – Iteration axis (default: 0)
  • optimize (str, optional) – Optimization method (speed or memory; default: memory)
__repr__()[source]

Return repr(self).

__str__()[source]

Return str(self).

__weakref__

list of weak references to the object (if defined)

close()[source]

Release video file handler

get_view(slices=())[source]

Returns a VideoView object given the provided slicing

Parameters:slices (tuple, optional) – Tuple with slice objects and/or indices that define the required data view
Returns:VideoView object that adheres to the provided slices
Return type:VideoView

See also

VideoView()

shape

Returns the shape of the open video file

time

Returns the time axis in seconds for the open video file

VideoView

class videoslicer.videoslicer.VideoView[source]

VideoView class

Provides a generator over a specific part of a video file. The generator iterates over a given axis and returns individual frames in the remaining dimensions. By default, the generator iterates over time and returns standard video frames. Alternatively, the generator can iterate over space or depth, returning timestacks from the video file.

If the slicing is chosen such that there is only one frame in the iteration axis, the VideoView falls back to being a VideoFrame.

Slicing or iterating over the time dimension is both optimized for speed and memory usage. Slicing and iterating over spatial dimensions can be either optimized for speed (run over video once, collecting all data), or for memory usage (run over video multiple times, each time collecting the required amount of data).

static __new__(cls, buffer, shape, slices, fps=None, axis=0, optimize='memory')[source]

Constructor

Returns a VideoView object, unless the view consists of a single frame in the iteration axis, then it falls back to being a VideoFrame object.

Parameters:
  • buffer (int) – Open video file buffer
  • shape (tuple) – Shape of video file
  • slices (tuple) – Tuple of slices definign the view
  • fps (int, optional) – Frame rate of video
  • axis (int, optional) – Iteration axis (default: 0)
  • optimize (str, optional) – Optimization method (speed or memory; default: memory)
__repr__()[source]

Return repr(self).

__str__()[source]

Return str(self).

__weakref__

list of weak references to the object (if defined)

generator(slices=None, axis=None)[source]

Generator method that provides individual VideoFrame objects along a given axis

Parameters:
  • slices (tuple, optional) – Tuple with slices to overwrite the object’s default slicing
  • axis (int, optional) – Iteration axis to overwrite the object’s default iteration axis

See also

VideoFrame()

iterable_slices(slices=None)[source]

Converts arbitrary slices into iterable lists, given the video dimensions

Parameters:slices (tuple, optional) – Tuple of slices to overwrite the object’s default slicing
Returns:List with lists with indices corresponding to the provided slices and shape of the video file
Return type:list
shape

Returns the shape of the video view

time

Returns the time axis in seconds for the video view

VideoFrame

class videoslicer.videoslicer.VideoFrame[source]

VideoFrame class

A numpy.ndarray with video frame specific methods: T (transpose), resize, plot and save. The dimensions of the array need to be valid image dimensions (i.e. 2 or 3) and the depth dimension need to be 1, 3 or 4 depending on the number of color and alpha channels.

With respect to the original numpy.ndarray an additional attribute index contains the index of the current frame in the original video file.

See also

VideoView

T

Returns the transposed image

__array_finalize__(obj)[source]

None.

static __new__(cls, arr, index=None, *args, **kwargs)[source]

Constructor

Parameters:
  • arr (iterable) – Image data
  • index (int, optional) – Index of video frame in original video file
plot(ax=None)[source]

Plot image

Parameters:ax (matplotlib.pyplot.Axes, optional) – Axes to plot onto
Returns:ax – Axes containing plot
Return type:matplotlib.pyplot.Axes
classmethod read(filename, **kwargs)[source]

Initialize VideoFrame object from image file

Parameters:filename (str) – Path to image file
Returns:VideoFrame object with image data
Return type:VideoFrame
resize(shape)[source]

Resize video frame to given dimensions

Parameters:shape (tuple) – Target image shape
set_index(index)[source]

Set index of video frame in original video file

shape

Returns the shape of the image (always 3 dimensions)

write(filename)[source]

Write VideoFrame to image file

Parameters:filename (str) – Path to image file

VideoFrameCRS

class videoslicer.crs.VideoFrameCRS[source]

VideoFrame class with built-in coordinate reference system (crs)

Extension of the VideoFrame class that supports marker detection in the video frame. Distances between the markers and an arbitrarily chosen origin should be given to derive a coordinate reference system of the image frame. The markers are assumed to be in a plane perpendicular to the camera.

A marker is assumed to be a white square with a red centered dot. The diameter of the dot is assumed to be half of the width/height of the square. Markers are numbered from top to bottom.

__array_finalize__(obj)[source]

None.

static __new__(cls, arr, distances_markers=[], distances_origin=[], n_markers=4, method='redness', method_args={}, *args, **kwargs)[source]

Constructor

See VideoFrame for more details.

Parameters:
  • distances_markers (list of 2-tuples) – List of 2-tuples where each item contains another 2-tuple and a float. The 2-tuple contains the marker numbers for which the interdistance is defined by the float.
  • distance_origin (list of 2-tuples) – List of 2-tuples where each item contains an integer and a float. The integer is the marker number for which the distance to the origin of the coordinate reference system is defined by the float.
  • n_markers (int) – Number of markers in the frame
  • method (str) – Detection method (redness or template)
  • method_args (dict) – Keyword-value arguments to the detection method (see videoslicer.markers)
__repr__()[source]

Return repr(self).

compute_derivatives()[source]

Compute derined values from detected values

determine_origin(p0=[0, 0])[source]

Determine the origin in pixel coordinates from the distances between markers and origin

Parameters:p0 (tuple) – Initial guess of origin location
determine_resolution()[source]

Determine the average resolution from the distances between detected markers

find_markers()[source]

Find markers in the video frame given a specific method

plot(ax=None, crs=True)[source]

Plot the video frame including detected coordinate reference system

Parameters:
  • ax (matplotlib.pyplot.Axes, optional) – Axes to plot onto
  • crs (bool) – Flag to disable plotting of the coordinate reference system
Returns:

ax – Axes containing plot

Return type:

matplotlib.pyplot.Axes

x

Returns x-coordinates of given indexes in the first dimension

xy

Returns x- and y-coordinates of given indexes in the both dimensions

y

Returns x-coordinates of given indexes in the second dimension

Marker detection

videoslicer.markers.find_markers_redness(frame, n_markers=4, min_redness=0.5, max_iter=10, max_distance=50)[source]

Detects markers in image frame based on pixel redness

Red pixels are clustered in a predefined number of marker clusters. The centers of the clusters are returned as the assumed marker centers.

After a first estimate is obtained, red pixels far from the cluster center that the pixel belongs to are discarded and the clustering is recomputed. This procedure is repeated until all red pixels are within a given distance from the cluster center and the solution converges.

Parameters:
  • frame (VideoFrame or np.ndarray) – Image data
  • n_markers (int, optional) – Number of markers in frame (default: 4)
  • min_redness (float, optional) – Minimal value for the redness needed to take a pixel into account (default: 0.5)
  • max_iter (int, optional) – Maximum number of iterations (default: 10)
  • max_distance (int, optional) – Maximum size of markers to consider (default: 50)
Returns:

List with locations of the marker centers

Return type:

list of 2-tuples

videoslicer.markers.find_markers_template(frame, size_min=25, size_max=75, n_markers=4, threshold=0.6, max_variance=10)[source]

Detects markers in image frame based on template matching

The template size is varied to find the best matching size. From the best matching template size, all matches are clustered using a K-means algorithm in the assumed number of clusters. The centers of the clusters are returned as the assumed marker centers.

Matches are validated against the scatter within a single cluster and the interdistance between clusters. If the scatter is too large or the interdistance is too small, the match is ignored and the next template size is validated.

Parameters:
  • frame (VideoFrame or np.ndarray) – Image data
  • size_min (int, optional) – Minimum size of the template (default: 25)
  • size_max (int, optional) – Maximum size of the template (default: 75)
  • n_markers (int, optional) – Number of markers in frame (default: 4)
  • threshold (float, optional) – Matching threshold for cv2.matchTemplate (default: 0.6)
  • max_variance (float, optional) – Maximum variance in a cluster of match locations in order to assume the match locations belong to the same marker. (default: 10)
Returns:

List with locations of the marker centers

Return type:

list of 2-tuples

Utils

videoslicer.utils.preprocess_getitem_args(s, shape)[source]

Guarantees to return a slice tuple with ellipses expanded

Parameters:
  • s (tuple or slice) – Slice or tuple with slices
  • shape (tuple) – Shape of the matrix to apply slices on
Returns:

s – Tuple with expanded slices and ellipses

Return type:

tuple