vispy.scene.visuals module#

The classes in scene.visuals are visuals that may be added to a scenegraph using the methods and properties defined in vispy.scene.Node such as name, visible, parent, children, etc…

These classes are automatically generated by mixing vispy.scene.Node with the Visual classes found in vispy.visuals.

For developing custom visuals, it is recommended to subclass from vispy.visuals.Visual rather than vispy.scene.Node.

class vispy.scene.visuals.Arrow(*args, **kwargs)#

Bases: VisualNode, ArrowVisual

Arrow visual

This class inherits from visuals.ArrowVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

A special line visual which can also draw optional arrow heads at the specified vertices.

You add an arrow head by specifying two vertices v1 and v2 which represent the arrow body. This visual will draw an arrow head using v2 as center point, and the orientation of the arrow head is automatically determined by calculating the direction vector between v1 and v2. The arrow head can be detached from arrow body.

Parameters:

posarray

Array of shape (…, 2) or (…, 3) specifying vertex coordinates of arrow body.

colorColor, tuple, or array

The color to use when drawing the line. If an array is given, it must be of shape (…, 4) and provide one rgba color per vertex. Can also be a colormap name, or appropriate Function.

parentNode

The parent node to assign to this node (optional).

namestring

A name for this node, used primarily for debugging (optional).

width:

The width of the line in px. Line widths > 1px are only guaranteed to work when using ‘agg’ method.

connectstr or array

Determines which vertices are connected by lines.

“strip” causes the line to be drawn with each vertex connected to the next.

“segments” causes each pair of vertices to draw an independent line segment

numpy arrays specify the exact set of segment pairs to connect.

methodstr

Mode to use for drawing.

“agg” uses anti-grain geometry to draw nicely antialiased lines with proper joins and endcaps.

“gl” uses OpenGL’s built-in line rendering. This is much faster, but produces much lower-quality results and is not guaranteed to obey the requested line width or join/endcap styles.

antialiasbool

Enables or disables antialiasing. For method=’gl’, this specifies whether to use GL’s line smoothing, which may be unavailable or inconsistent on some platforms.

arrowsarray

A (N, 4) or (N, 6) matrix where each row contains the (x, y) or the (x, y, z) coordinates of the first and second vertex of the arrow head. Remember that the second vertex is used as center point for the arrow head, and the first vertex is only used for determining the arrow head orientation.

arrow_typestring

Specify the arrow head type, the currently available arrow head types are:

stealth

curved

triangle_30

triangle_60

triangle_90

angle_30

angle_60

angle_90

inhibitor_round

arrow_sizefloat

Specify the arrow size

arrow_colorColor, tuple, or array

The arrow head color. If an array is given, it must be of shape (…, 4) and provide one rgba color per arrow head. Can also be a colormap name, or appropriate Function.

class vispy.scene.visuals.Axis(*args, **kwargs)#

Bases: VisualNode, AxisVisual

Axis visual

This class inherits from visuals.AxisVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

posarray: Co-ordinates of start and end of the axis.
domaintuple: The data values at the beginning and end of the axis, used for tick labels. i.e. (5, 10) means the axis starts at 5 and ends at 10. Default is (0, 1).
tick_directionarray: The tick direction to use (in document coordinates).
scale_typestr: The type of scale. For now only ‘linear’ is supported.
axis_colortuple: RGBA values for the axis colour. Default is black.
tick_colortuple: RGBA values for the tick colours. The colour for the major and minor ticks is currently fixed to be the same. Default is a dark grey.
text_colorColor: The color to use for drawing tick and axis labels
minor_tick_lengthfloat: The length of minor ticks, in pixels
major_tick_lengthfloat: The length of major ticks, in pixels
tick_widthfloat: Line width for the ticks
tick_label_marginfloat: Margin between ticks and tick labels
tick_font_sizefloat: The font size to use for rendering tick labels.
axis_widthfloat: Line width for the axis
axis_labelstr: Text to use for the axis label
axis_label_marginfloat: Margin between ticks and axis labels
axis_font_sizefloat: The font size to use for rendering axis labels.
font_sizefloat: Font size for both the tick and axis labels. If this is set, tick_font_size and axis_font_size are ignored.
anchorsiterable: A 2-element iterable (tuple, list, etc.) giving the horizontal and vertical alignment of the tick labels. The first element should be one of ‘left’, ‘center’, or ‘right’, and the second element should be one of ‘bottom’, ‘middle’, or ‘top’. If this is not specified, it is determined automatically.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).

class vispy.scene.visuals.Box(*args, **kwargs)#

Bases: VisualNode, BoxVisual

Visual that displays a box.

This class inherits from visuals.BoxVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

widthfloat: Box width.
heightfloat: Box height.
depthfloat: Box depth.
width_segmentsint: Box segments count along the width.
height_segmentsfloat: Box segments count along the height.
depth_segmentsfloat: Box segments count along the depth.
planes: array_like: Any combination of {'-x', '+x', '-y', '+y', '-z', '+z'} Included planes in the box construction.
vertex_colorsndarray: Same as for MeshVisual class. See create_plane for vertex ordering.
face_colorsndarray: Same as for MeshVisual class. See create_plane for vertex ordering.
colorColor: The Color to use when drawing the cube faces.
edge_colortuple or Color: The Color to use when drawing the cube edges. If None, then no cube edges are drawn.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).

class vispy.scene.visuals.ColorBar(*args, **kwargs)#

Bases: VisualNode, ColorBarVisual

Visual subclass displaying a colorbar

This class inherits from visuals.ColorBarVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

cmapstr | vispy.color.ColorMap

Either the name of the ColorMap to be used from the standard set of names (refer to vispy.color.get_colormap), or a custom ColorMap object. The ColorMap is used to apply a gradient on the colorbar.

orientation{‘left’, ‘right’, ‘top’, ‘bottom’}

The orientation of the colorbar, used for rendering. The orientation can be thought of as the position of the label relative to the color bar.

When the orientation is ‘left’ or ‘right’, the colorbar is vertically placed. When it is ‘top’ or ‘bottom’, the colorbar is horizontally placed.

‘top’: the colorbar is horizontal. Color is applied from left to right. Minimum corresponds to left and maximum to right. Label is to the top of the colorbar

‘bottom’: Same as top, except that label is to the bottom of the colorbar

‘left’: the colorbar is vertical. Color is applied from bottom to top. Minimum corresponds to bottom and maximum to top. Label is to the left of the colorbar

‘right’: Same as left, except that the label is placed to the right of the colorbar

size(major_axis_length, minor_axis_length)

lengths with respect to the major and minor axes. The minor axis is the shorter axis, while the major axis is the longer axis with respect to the orientation

For orientations ‘top’ and ‘bottom’, the major axis is along the length.

For orientations ‘left’ and ‘right’, the major axis is along the breadth

postuple (x, y)

Position where the colorbar is to be placed with respect to the center of the colorbar

labelstr | vispy.visuals.TextVisual

The label that is to be drawn with the colorbar that provides information about the colorbar. If a TextVisual object then ‘label_color’ is ignored.

label_colorstr | vispy.color.Color

The color of the label and tick labels. This can either be a str as the color’s name or an actual instace of a vipy.color.Color

climtuple (min, max)

the minimum and maximum values of the data that is given to the colorbar. This is used to draw the scale on the side of the colorbar.

border_widthfloat (in px)

The width of the border the colormap should have. This measurement is given in pixels

border_colorstr | vispy.color.Color

The color of the border of the colormap. This can either be a str as the color’s name or an actual instace of a vipy.color.Color

parentNode

The parent node to assign to this node (optional).

namestring

A name for this node, used primarily for debugging (optional).

.. versionchanged:: 0.7

Keyword argument label_str renamed to label.

class vispy.scene.visuals.ComplexImage(*args, **kwargs)#

Bases: VisualNode, ComplexImageVisual

ImageVisual subclass displaying a complex-valued image.

This class inherits from visuals.ComplexImageVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

This class handles complex values by using an rg32f float texture behind the scenes, storing the real component in the “r” value and the imaginary in the “g” value.

Parameters:

datandarray

Complex valued ImageVisual data. Should be a two dimensional array with a dtype of np.complex64 or np.complex128.

complex_modestr

The mode used to convert the complex value in each pixel into a scalar:

‘real’: show only the real component.
‘imaginary’: show only the imaginary component.
‘magnitude’: show the magnitude (np.abs) of the complex value.
‘phase’: show the phase (np.angle) of the complex value.

parentNode

The parent node to assign to this node (optional).

namestring

A name for this node, used primarily for debugging (optional).

class vispy.scene.visuals.Compound(*args, **kwargs)#

Bases: VisualNode, CompoundVisual

Visual consisting entirely of sub-visuals.

This class inherits from visuals.CompoundVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

To the user, a compound visual behaves exactly like a normal visual–it has a transform system, draw() and bounds() methods, etc. Internally, the compound visual automatically manages proxying these transforms and methods to its sub-visuals.

Parameters:

subvisualslist of BaseVisual instances: The list of visuals to be combined in this compound visual.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).

class vispy.scene.visuals.Cube(*args, **kwargs)#

Bases: VisualNode, CubeVisual

Visual that displays a cube or cuboid

This class inherits from visuals.CubeVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

sizefloat or tuple: The size of the cuboid. A float gives a cube, whereas tuples may specify the size of each axis (x, y, z) independently.
vertex_colorsndarray: Same as for MeshVisual class. See create_cube for vertex ordering.
face_colorsndarray: Same as for MeshVisual class. See create_cube for vertex ordering.
colorColor: The Color to use when drawing the cube faces.
edge_colortuple or Color: The Color to use when drawing the cube edges. If None, then no cube edges are drawn.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).

class vispy.scene.visuals.Ellipse(*args, **kwargs)#

Bases: VisualNode, EllipseVisual

Displays a 2D ellipse

This class inherits from visuals.EllipseVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

centerarray: Center of the ellipse
colorinstance of Color: The face color to use.
border_colorinstance of Color: The border color to use.
border_width: float: The width of the border in pixels Line widths > 1px are only guaranteed to work when using border_method=’agg’ method.
radiusfloat | tuple | list | numpy.ndarray: Radius or radii of the ellipse Defaults to (0.1, 0.1)
start_anglefloat: Start angle of the ellipse in degrees Defaults to 0.
span_anglefloat: Span angle of the ellipse in degrees Defaults to 360.
num_segmentsint: Number of segments to be used to draw the ellipse Defaults to 100
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).
**kwargsdict: Keyword arguments to pass to PolygonVisual.

class vispy.scene.visuals.Graph(*args, **kwargs)#

Bases: VisualNode, GraphVisual

Visual for displaying graphs or networks.

This class inherits from visuals.GraphVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

adjacency_matarray or sparse: The adjacency matrix of the graph.
directedbool: Whether the graph is directed or not. If True, then this visual will draw arrows for the directed edges.
layoutstr: They layout to use.
animatebool: Whether or not to animate.
line_colorstr or vispy.color.colormap.ColorMap: The color to use for the edges.
line_widthnumber: The edge thickness.
arrow_typestr: The kind of arrow head to use. See vispy.visuals.ArrowHead for more information.
arrow_sizenumber: The size of the arrow head.
node_symbolstring: The marker to use for nodes. See vispy.visuals.MarkersVisual for more information.
node_sizenumber: The size of the node
border_colorstr or vispy.color.colormap.ColorMap: The border color for nodes.
face_colorstr or vispy.color.colormap.ColorMap: The face color for nodes.
border_widthnumber: The border size for nodes.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).

See also

ArrowVisual, MarkersVisual

class vispy.scene.visuals.GridLines(*args, **kwargs)#

Bases: VisualNode, GridLinesVisual

Displays regularly spaced grid lines in any coordinate system and at any scale.

This class inherits from visuals.GridLinesVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

scaletuple: The scale factors to apply when determining the spacing of grid lines.
colorColor: The base color for grid lines. The final color may have its alpha channel modified.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).

class vispy.scene.visuals.GridMesh(*args, **kwargs)#

Bases: VisualNode, GridMeshVisual

Displays a mesh in a Cartesian grid about x,y,z coordinates.

This class inherits from visuals.GridMeshVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

This makes it simple to generate a mesh from e.g. the output of numpy.meshgrid.

All arguments are optional, though they can be changed individually later with the set_data method.

Parameters:

xsndarray: A 2d array of x coordinates for the vertices of the mesh. Must have the same dimensions as ys and zs.
ysndarray: A 2d array of y coordinates for the vertices of the mesh. Must have the same dimensions as xs and zs.
zsndarray: A 2d array of z coordinates for the vertices of the mesh. Must have the same dimensions as xs and ys.
colorsndarray | None: The colors of the points of the mesh. Should be either a (width, height, 4) array of rgba colors at each grid point or a (width, height, 3) array of rgb colors at each grid point. Defaults to None, in which case the default color of a MeshVisual is used.
shadingstr | None: Same as for the MeshVisual class. Defaults to ‘smooth’.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).
**kwargs: Other arguments are passed directly to MeshVisual.

class vispy.scene.visuals.Histogram(*args, **kwargs)#

Bases: VisualNode, HistogramVisual

Visual that calculates and displays a histogram of data

This class inherits from visuals.HistogramVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

dataarray-like: Data to histogram. Currently only 1D data is supported.
binsint | array-like: Number of bins, or bin edges.
colorinstance of Color: Color of the histogram.
orientation{‘h’, ‘v’}: Orientation of the histogram.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).

class vispy.scene.visuals.Image(*args, **kwargs)#

Bases: VisualNode, ImageVisual

Visual subclass displaying an image.

This class inherits from visuals.ImageVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

datandarray

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

methodstr

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.

gammafloat

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

interpolationstr

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

parentNode

The parent node to assign to this node (optional).

namestring

A name for this node, used primarily for debugging (optional).

**kwargsdict

Keyword arguments to pass to Visual.

Notes

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

class vispy.scene.visuals.InfiniteLine(*args, **kwargs)#

Bases: VisualNode, InfiniteLineVisual

Infinite horizontal or vertical line for 2D plots.

This class inherits from visuals.InfiniteLineVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

posfloat: Position of the line along the axis.
colorlist, tuple, or array: The color to use when drawing the line. If an array is given, it must be of shape (1, 4) and provide one rgba color per vertex.
line_width: float: The width of the Infinite line, in pixels
antialias: bool: If the line is drawn with antialiasing
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).
vertical:: True for drawing a vertical line, False for an horizontal line

class vispy.scene.visuals.InstancedMesh(*args, **kwargs)#

Bases: VisualNode, InstancedMeshVisual

Instanced Mesh visual.

This class inherits from visuals.InstancedMeshVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Mostly identical to MeshVisual, but additionally takes arrays of of positions and transforms (optionally colors) to create multiple instances of the mesh.

Instancing is a rendering technique that re-uses the same mesh data by applying transformations to vertices and vertex data or textures, wich can drastically improve performance compared to having many simple MeshVisuals.

Parameters:

instance_positions(I, 3) array: Coordinates for each instance of the mesh.
instance_transforms(I, 3, 3) array: Matrices for the transforms to apply to each instance.
instance_colorsColorArray: Matrices of colors for each instance. Colors
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).
*argslist: Positional arguments to pass to MeshVisual.
**kwargsdict: Keyword arguments to pass to MeshVisual.

Examples

See example scene/instanced_mesh_visual.py in the gallery.

class vispy.scene.visuals.Isocurve(*args, **kwargs)#

Bases: VisualNode, IsocurveVisual

Displays an isocurve of a 2D scalar array.

This class inherits from visuals.IsocurveVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

datandarray | None: 2D scalar array.
levelsndarray, shape (Nlev,) | None: The levels at which the isocurve is constructed from “data”.
color_levColor, colormap name, tuple, list or array: The color to use when drawing the line. If a list is given, it must be of shape (Nlev), if an array is given, it must be of shape (Nlev, …). and provide one color per level (rgba, colorname).
climtuple: (min, max) limits to apply when mapping level values through a colormap.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).
**kwargsdict: Keyword arguments to pass to LineVisual.

class vispy.scene.visuals.Isoline(*args, **kwargs)#

Bases: VisualNode, IsolineVisual

Isocurves of a tri mesh with data at vertices at different levels.

This class inherits from visuals.IsolineVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

verticesndarray, shape (Nv, 3) | None: Vertex coordinates.
trisndarray, shape (Nf, 3) | None: Indices into the vertex array.
datandarray, shape (Nv,) | None: scalar at vertices
levelsndarray, shape (Nlev,) | None: The levels at which the isocurve is constructed from “data”.
color_levColor, tuple, colormap name or array: The color to use when drawing the line. If an array is given, it must be of shape (Nlev, 4) and provide one rgba color by level.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).
**kwargsdict: Keyword arguments to pass to LineVisual.

class vispy.scene.visuals.Isosurface(*args, **kwargs)#

Bases: VisualNode, IsosurfaceVisual

Displays an isosurface of a 3D scalar array.

This class inherits from visuals.IsosurfaceVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

datandarray | None: 3D scalar array.
level: float | None: The level at which the isosurface is constructed from data.
vertex_colorsndarray | None: The vertex colors to use.
face_colorsndarray | None: The face colors to use.
colorndarray | None: The color to use.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).
**kwargsdict: Keyword arguments to pass to the mesh construction.

class vispy.scene.visuals.Line(*args, **kwargs)#

Bases: VisualNode, LineVisual

Line visual

This class inherits from visuals.LineVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

posarray

Array of shape (…, 2) or (…, 3) specifying vertex coordinates.

colorColor, tuple, or array

The color to use when drawing the line. If an array is given, it must be of shape (…, 4) and provide one rgba color per vertex. Can also be a colormap name, or appropriate Function.

parentNode

The parent node to assign to this node (optional).

namestring

A name for this node, used primarily for debugging (optional).

width:

The width of the line in px. Line widths > 1px are only guaranteed to work when using ‘agg’ method.

connectstr or array

Determines which vertices are connected by lines.

“strip” causes the line to be drawn with each vertex connected to the next.

“segments” causes each pair of vertices to draw an independent line segment

numpy arrays specify the exact set of segment pairs to connect.

methodstr

Mode to use for drawing.

“agg” uses anti-grain geometry to draw nicely antialiased lines with proper joins and endcaps.

“gl” uses OpenGL’s built-in line rendering. This is much faster, but produces much lower-quality results and is not guaranteed to obey the requested line width or join/endcap styles.

antialiasbool

Enables or disables antialiasing. For method=’gl’, this specifies whether to use GL’s line smoothing, which may be unavailable or inconsistent on some platforms.

class vispy.scene.visuals.LinePlot(*args, **kwargs)#

Bases: VisualNode, LinePlotVisual

Visual displaying a plot line with optional markers.

This class inherits from visuals.LinePlotVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

dataarray-like: Arguments can be passed as (Y,), (X, Y), (X, Y, Z) or np.array((X, Y)), np.array((X, Y, Z)).
colorinstance of Color: Color of the line.
symbolstr: Marker symbol to use.
line_kindstr: Kind of line to draw. For now, only solid lines ('-') are supported.
widthfloat: Line width.
marker_sizefloat: Marker size. If size == 0 markers will not be shown.
edge_colorinstance of Color: Color of the marker edge.
face_colorinstance of Color: Color of the marker face.
edge_widthfloat: Edge width of the marker.
connectstr | array: See LineVisual.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).
**kwargskeyword arguments: Argements to pass to the super class.

See also

LineVisual, MarkersVisual

Examples

All of these syntaxes will work:

>>> LinePlotVisual(y_vals)
>>> LinePlotVisual(x_vals, y_vals)
>>> LinePlotVisual(xy_vals)

class vispy.scene.visuals.LinearRegion(*args, **kwargs)#

Bases: VisualNode, LinearRegionVisual

Infinite horizontal or vertical region for 2D plots.

This class inherits from visuals.LinearRegionVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

poslist, tuple or numpy array: Bounds of the region along the axis. len(pos) must be >=2.
colorlist, tuple, or array: The color to use when drawing the line. It must have a shape of (1, 4) for a single color region or (len(pos), 4) for a multicolor region.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).
vertical:: True for drawing a vertical region, False for an horizontal region

class vispy.scene.visuals.Markers(*args, **kwargs)#

Bases: VisualNode, MarkersVisual

Visual displaying marker symbols.

This class inherits from visuals.MarkersVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

posarray: The array of locations to display each symbol.
sizefloat or array: The symbol size in screen (or data, if scaling is on) px.
edge_widthfloat or array or None: The width of the symbol outline in screen (or data, if scaling is on) px. Defaults to 1.0 if None or not provided and edge_width_rel is not provided.
edge_width_relfloat or array or None: The width as a fraction of marker size. Can not be specified along with edge_width. A ValueError will be raised if both are provided.
edge_colorColor | ColorArray: The color used to draw each symbol outline.
face_colorColor | ColorArray: The color used to draw each symbol interior.
symbolstr or array: The style of symbol used to draw each marker (see Notes).
scalingstr | bool: Scaling method of individual markers. If set to “fixed” (default) then no scaling is done and markers will always be the same number of pixels on the screen. If set to “scene” then the chain of transforms from the Visual’s transform to the transform mapping to the OpenGL framebuffer are used to scaling the marker. This has the effect of the marker staying the same size in the “scene” coordinate space and changing size as the visualization is zoomed in and out. If set to “visual” the marker is scaled only using the transform of the Visual and not the rest of the scene/camera. This means that something like a camera changing the view will not affect the size of the marker, but the user can still scale it using the Visual’s transform. For backwards compatibility this can be set to the boolean False for “fixed” or True for “scene”.
alphafloat: The opacity level of the visual.
antialiasfloat: Antialiasing amount (in px).
sphericalbool: Whether to add a spherical effect on the marker using lighting.
light_colorColor | ColorArray: The color of the light used to create the spherical effect.
light_positionarray: The coordinates of the light used to create the spherical effect.
light_ambientfloat: The amount of ambient light used to create the spherical effect.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).

Notes

Allowed style strings are: disc, arrow, ring, clobber, square, diamond, vbar, hbar, cross, tailed_arrow, x, triangle_up, triangle_down, and star.

class vispy.scene.visuals.Mesh(*args, **kwargs)#

Bases: VisualNode, MeshVisual

Mesh visual

This class inherits from visuals.MeshVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

verticesarray-like | None: The vertices.
facesarray-like | None: The faces.
vertex_colorsarray-like | None: Colors to use for each vertex.
face_colorsarray-like | None: Colors to use for each face.
colorinstance of Color: The color to use.
vertex_valuesarray-like | None: The values to use for each vertex (for colormapping).
meshdatainstance of MeshData | None: The meshdata.
shadingstr | None: Shading to use. This uses the ShadingFilter filter introduced in VisPy 0.7. This class provides additional features that are available when the filter is attached manually. See ‘examples/basics/scene/mesh_shading.py’ for an example.
modestr: The drawing mode.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).
**kwargsdict: Keyword arguments to pass to Visual.

Notes

Additional functionality is available through filters. Mesh-specific filters can be found in the vispy.visuals.filters.mesh module.

This class emits a data_updated event when the mesh data is updated. This is used for example by filters for synchronization.

Examples

Create a primitive shape from a helper function:

>>> from vispy.geometry import create_sphere
>>> meshdata = create_sphere()
>>> mesh = MeshVisual(meshdata=meshdata)

Create a custom shape:

>>> # A rectangle made out of two triangles.
>>> vertices = [(0, 0, 0), (1, 0, 1), (1, 1, 1), (0, 1, 0)]
>>> faces = [(0, 1, 2), (0, 2, 3)]
>>> mesh = MeshVisual(vertices=vertices, faces=faces)

class vispy.scene.visuals.MeshNormals(*args, **kwargs)#

Bases: VisualNode, MeshNormalsVisual

Display mesh normals as lines.

This class inherits from visuals.MeshNormalsVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

meshdatainstance of MeshData: The mesh data.
primitive{‘face’, ‘vertex’}: The primitive type on which to compute and display the normals.
lengthNone or float or array-like, optional: The length(s) of the normals. If None, the length is computed with length_method.
length_method{‘median_edge’, ‘max_extent’}, default=’median_edge’: The method to compute the length of the normals (when length=None). Methods: ‘median_edge’, the median edge length; ‘max_extent’, the maximum side length of the bounding box of the mesh.
length_scalefloat, default=1.0: A scale factor applied to the length computed with length_method.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).
**kwargsdict, optional: Extra arguments to define the appearance of lines. Refer to LineVisual.

Examples

Create a MeshVisual on which to display the normals and get the MeshData:

>>> mesh = MeshVisual(vertices=vertices, faces=faces, ...)
>>> meshdata = mesh.mesh_data

Create a visual for the mesh normals:

>>> normals = MeshNormalsVisual(meshdata)

Display the face normals:

>>> MeshNormalsVisual(..., primitive='face')
>>> MeshNormalsVisual(...)  # equivalent (default values)

Display the vertex normals:

>>> MeshNormalsVisual(..., primitive='vertex')

Fixed length for all normals:

>>> MeshNormalsVisual(..., length=0.25)

Individual length per normal:

>>> lengths = np.array([0.5, 0.2, 0.7, ..., 0.7], dtype=float)
>>> MeshNormalsVisual(..., length=lengths)
>>> assert len(lengths) == len(faces)  # for face normals
>>> assert len(lengths) == len(vertices)  # for vertex normals

Normals at about the length of a triangle:

>>> MeshNormalsVisual(..., length_method='median_edge', length_scale=1.0)
>>> MeshNormalsVisual(...)  # equivalent (default values)

Normals at about 10% the size of the mesh:

>>> MeshNormalsVisual(..., length_method='max_extent', length_scale=0.1)

class vispy.scene.visuals.Plane(*args, **kwargs)#

Bases: VisualNode, PlaneVisual

Visual that displays a plane.

This class inherits from visuals.PlaneVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

widthfloat: Plane width.
heightfloat: Plane height.
width_segmentsint: Plane segments count along the width.
height_segmentsfloat: Plane segments count along the height.
direction: unicode: {'-x', '+x', '-y', '+y', '-z', '+z'} Direction the plane will be facing.
vertex_colorsndarray: Same as for MeshVisual class. See create_plane for vertex ordering.
face_colorsndarray: Same as for MeshVisual class. See create_plane for vertex ordering.
colorColor: The Color to use when drawing the cube faces.
edge_colortuple or Color: The Color to use when drawing the cube edges. If None, then no cube edges are drawn.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).

class vispy.scene.visuals.Polygon(*args, **kwargs)#

Bases: VisualNode, PolygonVisual

Displays a 2D polygon

This class inherits from visuals.PolygonVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

posarray

Set of vertices defining the polygon.

colorstr | tuple | list of colors

Fill color of the polygon.

border_colorstr | tuple | list of colors

Border color of the polygon.

border_widthint

Border width in pixels. Line widths > 1px are only guaranteed to work when using border_method=’agg’ method.

border_methodstr

Mode to use for drawing the border line (see LineVisual).

“agg” uses anti-grain geometry to draw nicely antialiased lines with proper joins and endcaps.

“gl” uses OpenGL’s built-in line rendering. This is much faster, but produces much lower-quality results and is not guaranteed to obey the requested line width or join/endcap styles.

triangulateboolean

Triangulate the set of vertices

parentNode

The parent node to assign to this node (optional).

namestring

A name for this node, used primarily for debugging (optional).

**kwargsdict

Keyword arguments to pass to CompoundVisual.

class vispy.scene.visuals.Rectangle(*args, **kwargs)#

Bases: VisualNode, RectangleVisual

Displays a 2D rectangle with optional rounded corners

This class inherits from visuals.RectangleVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

centerarray: Center of the rectangle
colorinstance of Color: The fill color to use.
border_colorinstance of Color: The border color to use.
border_widthint: Border width in pixels. Line widths > 1px are only guaranteed to work when using border_method=’agg’ method.
heightfloat: Length of the rectangle along y-axis Defaults to 1.0
widthfloat: Length of the rectangle along x-axis Defaults to 1.0
radiusfloat | array: Radii of curvatures of corners in clockwise order from top-left Defaults to 0.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).
**kwargsdict: Keyword arguments to pass to PolygonVisual.

class vispy.scene.visuals.RegularPolygon(*args, **kwargs)#

Bases: VisualNode, RegularPolygonVisual

Displays a regular polygon

This class inherits from visuals.RegularPolygonVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

centerarray-like (x, y): Center of the regular polygon
colorstr | tuple | list of colors: Fill color of the polygon
border_colorstr | tuple | list of colors: Border color of the polygon
border_width: float: The width of the border in pixels
radiusfloat: Radius of the regular polygon Defaults to 0.1
sidesint: Number of sides of the regular polygon
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).

class vispy.scene.visuals.ScrollingLines(*args, **kwargs)#

Bases: VisualNode, ScrollingLinesVisual

Displays many line strips of equal length, with the option to add new vertex data to one end of the lines.

This class inherits from visuals.ScrollingLinesVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

n_linesint: The number of independent line strips to draw.
line_sizeint: The number of samples in each line strip.
dxfloat: The x distance between samples
colorarray-like: An array of colors to assign to each line strip.
pos_offsetarray-like: An array of x, y position offsets to apply to each line strip.
columnsint: Arrange line strips into a grid with this number of columns. This option is not compatible with pos_offset.
cell_sizetuple: The x, y distance between cells in the grid.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).

class vispy.scene.visuals.Spectrogram(*args, **kwargs)#

Bases: VisualNode, SpectrogramVisual

Calculate and show a spectrogram

This class inherits from visuals.SpectrogramVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

xarray-like: 1D signal to operate on. If len(x) < n_fft, x will be zero-padded to length n_fft.
n_fftint: Number of FFT points. Much faster for powers of two.
stepint | None: Step size between calculations. If None, n_fft // 2 will be used.
fsfloat: The sample rate of the data.
windowstr | None: Window function to use. Can be 'hann' for Hann window, or None for no windowing.
normalizebool: Normalization of spectrogram values across frequencies.
color_scale{‘linear’, ‘log’}: Scale to apply to the result of the STFT. 'log' will use 10 * log10(power).
cmapstr: Colormap name.
climstr | tuple: Colormap limits. Should be 'auto' or a two-element tuple of min and max values.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).

class vispy.scene.visuals.Sphere(*args, **kwargs)#

Bases: VisualNode, SphereVisual

Visual that displays a sphere

This class inherits from visuals.SphereVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

radiusfloat: The size of the sphere.
colsint: Number of cols that make up the sphere mesh (for method=’latitude’ and ‘cube’).
rowsint: Number of rows that make up the sphere mesh (for method=’latitude’ and ‘cube’).
depthint: Number of depth segments that make up the sphere mesh (for method=’cube’).
subdivisionsint: Number of subdivisions to perform (for method=’ico’).
methodstr: Method for generating sphere. Accepts ‘latitude’ for latitude-longitude, ‘ico’ for icosahedron, and ‘cube’ for cube based tessellation.
vertex_colorsndarray: Same as for MeshVisual class. See create_sphere for vertex ordering.
face_colorsndarray: Same as for MeshVisual class. See create_sphere for vertex ordering.
colorColor: The Color to use when drawing the sphere faces.
edge_colortuple or Color: The Color to use when drawing the sphere edges. If None, then no sphere edges are drawn.
shadingstr | None: Shading to use.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).

class vispy.scene.visuals.SurfacePlot(*args, **kwargs)#

Bases: VisualNode, SurfacePlotVisual

Displays a surface plot on a regular x,y grid

This class inherits from visuals.SurfacePlotVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

xndarray | None: 1D/2D array of values specifying the x positions of vertices in the grid. In case 1D array given as input, the values will be replicated to fill the 2D array of size(z). If None, values will be assumed to be integers.
yndarray | None: 1D/2D array of values specifying the y positions of vertices in the grid. In case 1D array given as input, the values will be replicated to fill the 2D array of size(z). If None, values will be assumed to be integers.
zndarray: 2D array of height values for each grid vertex.
colorsndarray: (width, height, 4) array of vertex colors.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).

Notes

All arguments are optional.

Note that if vertex positions are updated, the normal vectors for each triangle must be recomputed. This is somewhat expensive if the surface was initialized with smooth=False and very expensive if smooth=True. For faster performance, initialize with compute_normals=False and use per-vertex colors or a material that does not require normals.

class vispy.scene.visuals.Text(*args, **kwargs)#

Bases: VisualNode, TextVisual

Visual that displays text

This class inherits from visuals.TextVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

textstr | list of str: Text to display. Can also be a list of strings. Note: support for list of str might be removed soon in favor of text collections.
colorinstance of Color: Color to use.
boldbool: Bold face.
italicbool: Italic face.
facestr: Font face to use.
font_sizefloat: Point size to use.
postuple | list of tuple: Position (x, y) or (x, y, z) of the text. Can also be a list of tuple if text is a list.
rotationfloat: Rotation (in degrees) of the text clockwise.
anchor_xstr: Horizontal text anchor.
anchor_ystr: Vertical text anchor.
methodstr: Rendering method for text characters. Either ‘cpu’ (default) or ‘gpu’. The ‘cpu’ method should perform better on remote backends. The ‘gpu’ method should produce higher quality results.
font_managerobject | None: Font manager to use (can be shared if the GLContext is shared).
depth_testbool: Whether to apply depth testing. Default False. If False, the text behaves like an overlay that does not get hidden behind other visuals in the scene.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).

class vispy.scene.visuals.Tube(*args, **kwargs)#

Bases: VisualNode, TubeVisual

Displays a tube around a piecewise-linear path.

This class inherits from visuals.TubeVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

The tube mesh is corrected following its Frenet curvature and torsion such that it varies smoothly along the curve, including if the tube is closed.

Parameters:

pointsndarray: An array of (x, y, z) points describing the path along which the tube will be extruded.
radiusfloat | ndarray: The radius of the tube. Use array of floats as input to set radii of points individually. Defaults to 1.0.
closedbool: Whether the tube should be closed, joining the last point to the first. Defaults to False.
colorColor | ColorArray: The color(s) to use when drawing the tube. The same color is applied to each vertex of the mesh surrounding each point of the line. If the input is a ColorArray, the argument will be cycled; for instance if ‘red’ is passed then the entire tube will be red, or if [‘green’, ‘blue’] is passed then the points will alternate between these colours. Defaults to ‘purple’.
tube_pointsint: The number of points in the circle-approximating polygon of the tube’s cross section. Defaults to 8.
shadingstr | None: Same as for the MeshVisual class. Defaults to ‘smooth’.
vertex_colors: ndarray | None: Same as for the MeshVisual class.
face_colors: ndarray | None: Same as for the MeshVisual class.
modestr: Same as for the MeshVisual class. Defaults to ‘triangles’.
parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).

class vispy.scene.visuals.VisualNode(parent=None, name=None)#

Bases: Node

draw()#

property interactive#: Whether this widget should be allowed to accept mouse and touch events.

property picking#: Boolean that determines whether this node (and its children) are drawn in picking mode.

class vispy.scene.visuals.Volume(*args, **kwargs)#

Bases: VisualNode, VolumeVisual

Displays a 3D Volume

This class inherits from visuals.VolumeVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

volndarray

The volume to display. Must be ndim==3. Array is assumed to be stored as (z, y, x).

climstr | tuple

method{‘mip’, ‘attenuated_mip’, ‘minip’, ‘translucent’, ‘additive’,

‘iso’, ‘average’} The render method to use. See corresponding docs for details. Default ‘mip’.

thresholdfloat

The threshold to use for the isosurface render method. By default the mean of the given volume is used.

attenuation: float

The attenuation rate to apply for the attenuated mip render method. Default: 1.0.

relative_step_sizefloat

The relative step size to step through the volume. Default 0.8. Increase to e.g. 1.5 to increase performance, at the cost of quality.

cmapstr

Colormap to use.

gammafloat

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

interpolationstr

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’

texture_formatnumpy.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 volume 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. Note this visual is limited to “luminance” formatted data (single band). This is equivalent to GL_RED format in OpenGL 4.0.

raycasting_mode{‘volume’, ‘plane’}

Whether to cast a ray through the whole volume or perpendicular to a plane through the volume defined.

plane_positionArrayLike

A (3,) array containing a position on a plane of interest in the volume. The position is defined in data coordinates. Only relevant in raycasting_mode = ‘plane’.

plane_normalArrayLike

A (3,) array containing a vector normal to the plane of interest in the volume. The normal vector is defined in data coordinates. Only relevant in raycasting_mode = ‘plane’.

plane_thicknessfloat

A value defining the total length of the ray perpendicular to the plane interrogated during rendering. Defined in data coordinates. Only relevant in raycasting_mode = ‘plane’.

parentNode

The parent node to assign to this node (optional).

namestring

A name for this node, used primarily for debugging (optional).

.. versionchanged: 0.7

Deprecate ‘emulate_texture’ keyword argument.

class vispy.scene.visuals.Windbarb(*args, **kwargs)#

Bases: VisualNode, WindbarbVisual

Visual displaying windbarbs.

This class inherits from visuals.WindbarbVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).

class vispy.scene.visuals.XYZAxis(*args, **kwargs)#

Bases: VisualNode, XYZAxisVisual

Simple 3D axis for indicating coordinate system orientation. Axes are x=red, y=green, z=blue.

This class inherits from visuals.XYZAxisVisual and scene.Node, allowing the visual to be placed inside a scenegraph.

Parameters:

parentNode: The parent node to assign to this node (optional).
namestring: A name for this node, used primarily for debugging (optional).