add_nd_image#

NDWSubplot.add_nd_image(data, dims, display_dims, rgb_dim=None, window_funcs=None, window_order=None, spatial_func=None, compute_histogram=True, clim_quantiles=None, slider_maps=None, slicer_type=NDImageSlicer, colorspace='srgb', colorrange='full', name=None, graphic_kwargs=None)[source]#

Add an n-dimensional image or volume to this subplot.

Every dim that is not listed in display_dims becomes a slider dim.

Parameters:

  • data (ArrayProtocol or None) – n-dimensional image data, must have 2 or more dims. 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, ex: an array whose dims are ("col", "depth", "row", "time") with display_dims of ("row", "col").

  • display_dims (tuple[str, str] | tuple[str, str, str]) –

    The 2 or 3 spatial dims in display order, which also determines the graphic used for rendering:

    • (rows, cols), a 2D grayscale ImageGraphic

    • (rows, cols, rgb_dim), a 2D RGB(A) ImageGraphic

    • (z, rows, cols), a 3D ImageVolumeGraphic

  • 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.

  • window_funcs (dict[str, tuple[WindowFuncCallable | None, int | float | None]], optional) –

    Per-slider-dim window functions applied around the current slider position, ex: {"time": (np.mean, 2.5)}. Each value is a (func, window_size) pair where:

    • func must accept axis: int and keepdims: bool kwargs (ex: np.mean, np.max). It must return an array that has the same dims as the input, therefore the size of any dim along which it was applied should reduce to 1. These dims must not be removed by the window func.

    • window_size is in reference-space units (ex: 2.5 seconds).

  • window_order (tuple[str, ...], optional) – Order in which the window functions are applied across dims. Only dims listed here have their window function applied, window_funcs are ignored for any dim not specified in window_order.

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

  • compute_histogram (bool, default True) – Estimate a histogram of the data and display an ImguiColorbar on the right edge of the subplot, which is used to interactively set vmin, vmax. Disable if random access of the data is not blazing-fast (ex: data that uses video codecs), or if a histogram is not useful for this data.

  • clim_quantiles ((float, float), optional) – (low, high) quantiles of the histogram, within [0, 1], used as vmin, vmax. Requires compute_histogram=True, overrides any passed vmin, vmax in graphic_kwargs. The limits are recomputed whenever the histogram is, so they follow the data.

  • slider_maps (dict mapping dim_name -> Callable, an ArrayLike, or None, optional) – Per-slider-dim mapping from reference-space values to local array indices. An array of reference values may be given instead of a callable, searchsorted is then used as the transform (ex: a timestamps array). Any dim without a transform uses the identity mapping, i.e. the current reference value is rounded to the nearest integer and used as the array index.

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

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

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

  • 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, ex: {"cmap": "viridis", "interpolation": "linear"}

Return type:

NDImage