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
-
__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)
-
__weakref__
¶ list of weak references to the object (if defined)
-
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
-
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).
See also
-
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)
-
__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
-
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
-
static
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
-
T
¶ Returns the transposed image
-
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
-
shape
¶ Returns the shape of the image (always 3 dimensions)
-
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.
-
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)
-
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
-
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
-
static
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