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.


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


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.

cmapstr | ColorMap

Colormap to use for luminance images.

climstr | 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 to use during colormap lookup. Final color will be cmap(val**gamma). by default: 1.


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: 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’.


Keyword arguments to pass to Visual.


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

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.


The image data.

texture_formatstr or None
property size#

Get size of the image (width, height).


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