add_video#

NDWSubplot.add_video(data, dims, display_dims, rgb_dim=None, colorspace='yuv420p', colorrange='limited', slicer_type=VideoSlicer, window_funcs=None, window_order=None, spatial_func=None, slider_maps=None, name=None, graphic_kwargs=None)[source]#

Add a video to this subplot.

This is usually what you want for video data. Videos are usually stored in a YUV colorspace, and sending the YUV planes to the GPU is much faster than converting each frame to RGB and copying it into an sRGB texture.

We strongly recommend using asyncvideo for the data object, it is the most efficient async video reader that we know of for visualization purposes: https://pypi.org/project/asyncvideo/

Same as add_nd_image() but uses a VideoSlicer and YUV defaults. The VideoSlicer reads the frame at the current index directly, it does not apply window_funcs.

Parameters:

  • data (ArrayProtocol or None) – video data, an object that decodes frames on demand, ex: an asyncvideo reader. Pass None to create the NDImage without a graphic and set the data later using nd_image.data, the slider dims then require an explicit reference range in the NDWidget.

  • dims (Sequence[str]) – name for every dim of data, in order. They do not need to be in display order.

  • display_dims (tuple[str, str] | tuple[str, str, str]) – The 2 or 3 spatial dims in display order, see add_nd_image().

  • rgb_dim (str, optional) – Name of the RGB(A) dim, if present. It must be listed in display_dims and be of size 3 or 4.

  • colorspace ("yuv420p" | "yuv444p" | "srgb" | "tex-srgb" | "physical", default "yuv420p") – Colorspace in which to interpret the data. The YUV colorspaces are rendered using an ImageYUVGraphic, see ImageYUVGraphic. The RGB colorspaces are rendered using an ImageGraphic or ImageVolumeGraphic, see ImageGraphic.

  • colorrange ("full" | "limited", default "limited") – Used only for the YUV colorspaces, see ImageYUVGraphic. Most videos use “limited”.

  • slicer_type (type[NDImageSlicer], default VideoSlicer) – NDImageSlicer subclass that manages the data and produces the data slices.

  • window_funcs (dict[str, tuple[WindowFuncCallable | None, int | float | None]], optional) – Per-slider-dim window functions, see add_nd_image(). Ignored by the default VideoSlicer.

  • window_order (tuple[str, ...], optional) – Order in which the window functions are applied across dims. Ignored by the default VideoSlicer.

  • spatial_func (Callable[[ArrayProtocol], ArrayProtocol], optional) – A function applied to the spatial slice right before rendering. It is given the frame in display_dims order, i.e. the array as it is rendered, and must return an array with those same dims.

  • slider_maps (dict mapping dim_name -> Callable, an ArrayLike, or None, optional) – Per-slider-dim mapping from reference-space values to local array indices, ex: an array of frame timestamps to map seconds onto frame indices. See add_nd_image().

  • name (str, optional) – Name for this NDGraphic, used to retrieve it with nd_subplot[name].

  • graphic_kwargs (dict, optional) – passed to the underlying image graphic

Return type:

NDImage