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, **kwargs)[source]

Bases: vispy.visuals.visual.Visual

Visual subclass displaying an image.


ImageVisual data. Can be shape (M, N), (M, N, 3), or (M, N, 4).


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. Can be ‘auto’ to auto-set bounds to the min and max of the data.


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


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

  • ‘nearest’: Default, uses ‘nearest’ with Texture2D interpolation.

  • ‘bilinear’: uses ‘linear’ with Texture2D interpolation.

  • ‘hanning’, ‘hamming’, ‘hermite’, ‘kaiser’, ‘quadric’, ‘bicubic’,

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

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, WebGL (without enabling some extensions), 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.


Keyword arguments to pass to Visual.


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

FRAGMENT_SHADER = '\nuniform vec2 image_size;\nuniform int method;  // 0=subdivide, 1=impostor\nuniform sampler2D u_texture;\nvarying vec2 v_texcoord;\n\nvec4 map_local_to_tex(vec4 x) {\n    // Cast ray from 3D viewport to surface of image\n    // (if $transform does not affect z values, then this\n    // can be optimized as simply $ )\n    vec4 p1 = $transform(x);\n    vec4 p2 = $transform(x + vec4(0, 0, 0.5, 0));\n    p1 /= p1.w;\n    p2 /= p2.w;\n    vec4 d = p2 - p1;\n    float f = p2.z / d.z;\n    vec4 p3 = p2 - d * f;\n\n    // finally map local to texture coords\n    return vec4(p3.xy / image_size, 0, 1);\n}\n\n\nvoid main()\n{\n    vec2 texcoord;\n    if( method == 0 ) {\n        texcoord = v_texcoord;\n    }\n    else {\n        // vertex shader outputs clip coordinates;\n        // fragment shader maps to texture coordinates\n        texcoord = map_local_to_tex(vec4(v_texcoord, 0, 1)).xy;\n    }\n\n    gl_FragColor = $color_transform($get_data(texcoord));\n}\n'
VERTEX_SHADER = '\nuniform int method;  // 0=subdivide, 1=impostor\nattribute vec2 a_position;\nattribute vec2 a_texcoord;\nvarying vec2 v_texcoord;\n\nvoid main() {\n    v_texcoord = a_texcoord;\n    gl_Position = $transform(vec4(a_position, 0., 1.));\n}\n'
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 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 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.