Skip to main content
`Ctrl`+`K`

# vispy.visuals.image module

Primitive 2D image visual class.

class vispy.visuals.image.ImageVisual(data=None, method='auto', grid=(1, 1), cmap='viridis', clim='auto', gamma=1.0, interpolation='nearest', texture_format=None, custom_kernel=array([[1.]]), **kwargs)

  Bases: `Visual`

  Visual subclass displaying an image.

  Parameters:
    data ndarray

      ImageVisual data. Can be shape (M, N), (M, N, 3), or (M, N, 4). If floating point data is provided and contains NaNs, they will be made transparent (discarded) for the single band data case when scaling is done on the GPU (see `texture_format`). On the CPU, single band NaNs are mapped to 0 as they are sent to the GPU which result in them using the lowest `clim` value in the GPU. For RGB data, NaNs will be mapped to the lowest `clim` value. If the Alpha band is NaN it will be mapped to 0 (transparent). Note that NaN handling is not required by some OpenGL implementations and NaNs may be treated differently on some systems (ex. as 0s).

    method str

      Selects method of rendering image in case of non-linear transforms. Each method produces similar results, but may trade efficiency and accuracy. If the transform is linear, this parameter is ignored and a single quad is drawn around the area of the image.

      > - ‘auto’: Automatically select ‘impostor’ if the image is drawn with a nonlinear transform; otherwise select ‘subdivide’.

      > - ‘subdivide’: ImageVisual is represented as a grid of triangles with texture coordinates linearly mapped.

      > - ‘impostor’: ImageVisual is represented as a quad covering the entire view, with texture coordinates determined by the transform. This produces the best transformation results, but may be slow.

    grid: tuple (rows, cols)

      If method=’subdivide’, this tuple determines the number of rows and columns in the image grid.

    cmap str | ColorMap

      Colormap to use for luminance images.

    clim str | tuple

      Limits to use for the colormap. I.e. the values that map to black and white in a gray colormap. Can be ‘auto’ to auto-set bounds to the min and max of the data. If not given or None, ‘auto’ is used.

    gamma float

      Gamma to use during colormap lookup. Final color will be cmap(val**gamma). by default: 1.

    interpolation str

      Selects method of texture interpolation. Makes use of the two hardware interpolation methods and the available interpolation methods defined in vispy/gloo/glsl/misc/spatial_filters.frag

      > - ‘nearest’: Default, uses ‘nearest’ with Texture interpolation.

      > - ‘linear’: uses ‘linear’ with Texture interpolation.

      > - ‘hanning’, ‘hamming’, ‘hermite’, ‘kaiser’, ‘quadric’, ‘cubic’,

      >     ‘catrom’, ‘mitchell’, ‘spline16’, ‘spline36’, ‘gaussian’, ‘bessel’, ‘sinc’, ‘lanczos’, ‘blackman’

      > - ‘custom’: uses the sampling kernel provided through ‘custom_kernel’.

    texture_format: numpy.dtype | str | None

      How to store data on the GPU. OpenGL allows for many different storage formats and schemes for the low-level texture data stored in the GPU. Most common is unsigned integers or floating point numbers. Unsigned integers are the most widely supported while other formats may not be supported on older versions of OpenGL or with older GPUs. Default value is `None` which means data will be scaled on the CPU and the result stored in the GPU as an unsigned integer. If a numpy dtype object, an internal texture format will be chosen to support that dtype and data will not be scaled on the CPU. Not all dtypes are supported. If a string, then it must be one of the OpenGL internalformat strings described in the table on this page: https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/glTexImage2D.xhtml The name should have GL_ removed and be lowercase (ex. GL_R32F becomes `'r32f'`). Lastly, this can also be the string `'auto'` which will use the data type of the provided image data to determine the internalformat of the texture. When this is specified (not `None`) data is scaled on the GPU which allows for faster color limit changes. Additionally, when 32-bit float data is provided it won’t be copied before being transferred to the GPU.

    custom_kernel: numpy.ndarray

      Kernel used for texture sampling when interpolation is set to ‘custom’.

    **kwargs dict

      Keyword arguments to pass to Visual.

  Notes

  The colormap functionality through `cmap` and `clim` are only used if the data are 2D.

  property bad_color

    Color used to render NaN values.

  property clim

    Get color limits used when rendering the image (cmin, cmax).

  property cmap

    Get the colormap object applied to luminance (single band) data.

  property custom_kernel

    Kernel used by ‘custom’ interpolation for texture sampling

  property gamma

    Get the gamma used when rendering the image.

  property interpolation

    Get interpolation algorithm name.

  property interpolation_functions

    Get names of possible interpolation methods.

  property method

    Get rendering method name.

  set_data(image, copy=False)

    Set the image data.

    Parameters:
      image array-like

        The image data.

      texture_format str or None
  property size

    Get size of the image (width, height).

  view()

    Get the `vispy.visuals.visual.VisualView` for this visual.