Scenegraph¶

The vispy.scene subpackage provides high-level, flexible, and easy to use functionality for creating scenes composed of multiple visual objects.

Overview¶

Scenegraphs are a commonly used system for describing a scene as a hierarchy of visual objects. Users need only create these visual objects and specify their location in the scene, and the scenegraph system will automatically draw the entire scene whenever an update is required.

Using the vispy scenegraph requires only a few steps:

Create a SceneCanvas to display the scene. This object has a scene property that is the top-level Node in the scene.
Create one or more Node instances (see vispy.scene.visuals)
Add these Node instances to the scene by making them children of canvas.scene, or children of other nodes that are already in the scene.

For more information see:

complete scenegraph documentation
scene examples
scene API reference

vispy.scene.cameras¶

Cameras are responsible for determining which part of a scene is displayed in a viewbox and for handling user input to change the view.

Several Camera subclasses are available to customize the projection of the scene such as 3D perspective and orthographic projections, 2D scale/translation, and other specialty cameras. A variety of user interaction styles are available for each camera including arcball, turntable, first-person, and pan/zoom interactions.

Internally, Cameras work by setting the transform of a SubScene object such that a certain part of the scene is mapped to the bounding rectangle of the ViewBox.

class vispy.scene.cameras.ArcballCamera(fov=45.0, distance=None, translate_speed=1.0, **kwargs)[source]¶

Bases: vispy.scene.cameras.perspective.Base3DRotationCamera

3D camera class that orbits around a center point while maintaining a view on a center point.

For this camera, the scale_factor indicates the zoom level, and the center indicates the position to put at the center of the view.

Parameters:

Parameters:	fovfloat Field of view. Zero (default) means orthographic projection. distancefloat \| None The distance of the camera from the rotation point (only makes sense if fov > 0). If None (default) the distance is determined from the scale_factor and fov. translate_speedfloat Scale factor on translation speed when moving the camera center point. **kwargsdict Keyword arguments to pass to BaseCamera.

fovfloat: Field of view. Zero (default) means orthographic projection.
distancefloat | None: The distance of the camera from the rotation point (only makes sense if fov > 0). If None (default) the distance is determined from the scale_factor and fov.
translate_speedfloat: Scale factor on translation speed when moving the camera center point.
**kwargsdict: Keyword arguments to pass to BaseCamera.

Notes

Interaction:

LMB: orbits the view around its center point.

RMB or scroll: change scale_factor (i.e. zoom level)

SHIFT + LMB: translate the center point

SHIFT + RMB: change FOV

class vispy.scene.cameras.BaseCamera(interactive=True, flip=None, up='+z', parent=None, name=None)[source]¶

Bases: vispy.scene.node.Node

Base camera class.

The Camera describes the perspective from which a ViewBox views its subscene, and the way that user interaction affects that perspective.

Most functionality is implemented in subclasses. This base class has no user interaction and causes the subscene to use the same coordinate system as the ViewBox.

Parameters:

Parameters:	interactivebool Whether the camera processes mouse and keyboard events. fliptuple of bools For each dimension, specify whether it is flipped. up{‘+z’, ‘-z’, ‘+y’, ‘-y’, ‘+x’, ‘-x’} The direction that is considered up. Default ‘+z’. Not all camera’s may support this (yet). parentNode The parent of the camera. namestr Name used to identify the camera in the scene.

interactivebool: Whether the camera processes mouse and keyboard events.
fliptuple of bools: For each dimension, specify whether it is flipped.
up{‘+z’, ‘-z’, ‘+y’, ‘-y’, ‘+x’, ‘-x’}: The direction that is considered up. Default ‘+z’. Not all camera’s may support this (yet).
parentNode: The parent of the camera.
namestr: Name used to identify the camera in the scene.

property center¶

The center location for this camera

The exact meaning of this value differs per type of camera, but generally means the point of interest or the rotation point.

property depth_value¶

The depth value to use in orthographic and perspective projection

For orthographic projections, depth_value is the distance between the near and far clipping planes. For perspective projections, it is the ratio between the near and far clipping plane distances.

GL has a fixed amount of precision in the depth buffer, and a fixed constant will not work for both a very large range and very high precision. This property provides the user a way to override the default value if necessary.

property fov¶: Field-of-view angle of the camera. If 0, the camera is in orthographic mode.

get_state(props=None)[source]¶

Get the current view state of the camera

Returns a dict of key-value pairs. The exact keys depend on the camera. Can be passed to set_state() (of this or another camera of the same type) to reproduce the state.

Parameters:	propslist of strings \| None List of properties to include in the returned dict. If None, all of camera state is returned.

property interactive¶: Boolean describing whether the camera should enable or disable user interaction.

link(camera, props=None, axis=None)[source]¶

Link this camera with another camera of the same type

Linked camera’s keep each-others’ state in sync.

Parameters:

Parameters:	camerainstance of Camera The other camera to link. propslist of strings \| tuple of strings \| None List of camera state properties to keep in sync between the two cameras. If None, all of camera state is kept in sync. axis“x” \| “y” \| None An axis to link between two PanZoomCamera instances. If not None, view limits in the selected axis only will be kept in sync between the cameras.

camerainstance of Camera: The other camera to link.
propslist of strings | tuple of strings | None: List of camera state properties to keep in sync between the two cameras. If None, all of camera state is kept in sync.
axis“x” | “y” | None: An axis to link between two PanZoomCamera instances. If not None, view limits in the selected axis only will be kept in sync between the cameras.

on_canvas_change(event)[source]¶

Canvas change event handler

Parameters:	eventinstance of Event The event.

property pre_transform¶: A transform to apply to the beginning of the scene transform, in addition to anything else provided by this Camera.

reset()[source]¶: Reset the view to the default state.

set_default_state()[source]¶: Set the current state to be the default state to be applied when calling reset().

set_range(x=None, y=None, z=None, margin=0.05)[source]¶

Set the range of the view region for the camera

Parameters:	xtuple \| None X range. ytuple \| None Y range. ztuple \| None Z range. marginfloat Margin to use.

Notes

The view is set to the given range or to the scene boundaries if ranges are not specified. The ranges should be 2-element tuples specifying the min and max for each dimension.

For the PanZoomCamera the view is fully defined by the range. For e.g. the TurntableCamera the elevation and azimuth are not set. One should use reset() for that.

set_state(state=None, **kwargs)[source]¶

Set the view state of the camera

Should be a dict (or kwargs) as returned by get_state. It can be an incomlete dict, in which case only the specified properties are set.

Parameters:	statedict The camera state. **kwargsdict Unused keyword arguments.

property up¶: The dimension that is considered up.

view_changed()[source]¶: Called when this camera is changes its view. Also called when its associated with a viewbox.

property viewbox¶: The viewbox that this camera applies to.

viewbox_key_event(event)[source]¶

ViewBox key event handler

Parameters:	eventinstance of Event The event.

viewbox_mouse_event(event)[source]¶

Viewbox mouse event handler

Parameters:	eventinstance of Event The event.

viewbox_resize_event(event)[source]¶

The ViewBox resize handler to update the transform

Parameters:	eventinstance of Event The event.

class vispy.scene.cameras.FlyCamera(fov=60, rotation=None, **kwargs)[source]¶

Bases: vispy.scene.cameras.perspective.PerspectiveCamera

The fly camera provides a way to explore 3D data using an interaction style that resembles a flight simulator.

For this camera, the scale_factor indicates the speed of the camera in units per second, and the center indicates the position of the camera.

Parameters:	fovfloat Field of view. Default 60.0. rotationfloat \| None Rotation to use. **kwargsdict Keyword arguments to pass to BaseCamera.

Notes

Interacting with this camera might need a bit of practice. The reaction to key presses can be customized by modifying the keymap property.

Moving:

arrow keys, or WASD to move forward, backward, left and right

F and C keys move up and down

Space bar to brake

Viewing:

Use the mouse while holding down LMB to control the pitch and yaw.

Alternatively, the pitch and yaw can be changed using the keys IKJL

The camera auto-rotates to make the bottom point down, manual rolling can be performed using Q and E.

property auto_roll¶: Whether to rotate the camera automaticall to try and attempt to keep Z up.

property keymap¶

A dictionary that maps keys to thruster directions

The keys in this dictionary are vispy key descriptions (from vispy.keys) or characters that represent keys. These are matched to the “key” attribute of key-press and key-release events.

The values are tuples, in which the first element specifies the magnitude of the acceleration, using negative values for “backward” thrust. A value of zero means to brake. The remaining elements specify the dimension to which the acceleration should be applied. These are 1, 2, 3 for forward/backward, left/right, up/down, and 4, 5, 6 for pitch, yaw, roll.

on_timer(event)[source]¶

Timer event handler

Parameters:	eventinstance of Event The event.

property rotation¶: Get the full rotation. This rotation is composed of the normal rotation plus the extra rotation due to the current interaction of the user.

property rotation1¶: rotation1 records confirmed camera rotation

property rotation2¶: rotation2 records on going camera rotation.

viewbox_key_event(event)[source]¶

ViewBox key event handler

Parameters:	eventinstance of Event The event.

viewbox_mouse_event(event)[source]¶

ViewBox mouse event handler

Parameters:	eventinstance of Event The event.

class vispy.scene.cameras.Magnify1DCamera(size_factor=0.25, radius_ratio=0.9, **kwargs)[source]¶

Bases: vispy.scene.cameras.magnify.MagnifyCamera

Camera implementing a MagnifyTransform combined with PanZoomCamera.

Parameters:	size_factorfloat The size factor to use. radius_ratiofloat The radius ratio to use. **kwargsdict Keyword arguments to pass to PanZoomCamera and create a transform.

Notes

This Camera uses the mouse cursor position to set the center position of the MagnifyTransform, and uses mouse wheel events to adjust the magnification factor.

At high magnification, very small mouse movements can result in large changes, so we use a timer to animate transitions in the transform properties.

The camera also adjusts the size of its “lens” area when the view is resized.

transform_class[source]¶: alias of vispy.visuals.transforms.nonlinear.Magnify1DTransform

class vispy.scene.cameras.MagnifyCamera(size_factor=0.25, radius_ratio=0.9, **kwargs)[source]¶

Bases: vispy.scene.cameras.panzoom.PanZoomCamera

Camera implementing a MagnifyTransform combined with PanZoomCamera.

Parameters:	size_factorfloat The size factor to use. radius_ratiofloat The radius ratio to use. **kwargsdict Keyword arguments to pass to PanZoomCamera and create a transform.

Notes

This Camera uses the mouse cursor position to set the center position of the MagnifyTransform, and uses mouse wheel events to adjust the magnification factor.

At high magnification, very small mouse movements can result in large changes, so we use a timer to animate transitions in the transform properties.

The camera also adjusts the size of its “lens” area when the view is resized.

on_timer(event=None)[source]¶

Timer event handler

Parameters:	eventinstance of Event The timer event.

transform_class[source]¶: alias of vispy.visuals.transforms.nonlinear.MagnifyTransform

view_changed()[source]¶: Called when this camera is changes its view. Also called when its associated with a viewbox.

viewbox_mouse_event(event)[source]¶

ViewBox mouse event handler

Parameters:	eventinstance of Event The mouse event.

viewbox_resize_event(event)[source]¶

ViewBox resize event handler

Parameters:	eventinstance of Event The viewbox resize event.

class vispy.scene.cameras.PanZoomCamera(rect=0, 0, 1, 1, aspect=None, **kwargs)[source]¶

Bases: vispy.scene.cameras.base_camera.BaseCamera

Camera implementing 2D pan/zoom mouse interaction.

For this camera, the scale_factor indicates the zoom level, and the center indicates the center position of the view.

By default, this camera inverts the y axis of the scene. This usually results in the scene +y axis pointing upward because widgets (including ViewBox) have their +y axis pointing downward.

Parameters:	rectRect A Rect object or 4-element tuple that specifies the rectangular area to show. aspectfloat \| None The aspect ratio (i.e. scaling) between x and y dimension of the scene. E.g. to show a square image as square, the aspect should be 1. If None (default) the x and y dimensions are scaled independently. **kwargsdict Keyword arguments to pass to BaseCamera.

Notes

Interaction:

LMB: pan the view

RMB or scroll: zooms the view

property aspect¶: The ratio between the x and y dimension. E.g. to show a square image as square, the aspect should be 1. If None, the dimensions are scaled automatically, dependening on the available space. Otherwise the ratio between the dimensions is fixed.

property center¶

The center location for this camera

The exact meaning of this value differs per type of camera, but generally means the point of interest or the rotation point.

pan(*pan)[source]¶

Pan the view.

Parameters:	*panlength-2 sequence The distance to pan the view, in the coordinate system of the scene.

property rect¶

The rectangular border of the ViewBox visible area, expressed in the coordinate system of the scene.

Note that the rectangle can have negative width or height, in which case the corresponding dimension is flipped (this flipping is independent from the camera’s flip property).

viewbox_mouse_event(event)[source]¶

The SubScene received a mouse event; update transform accordingly.

Parameters:	eventinstance of Event The event.

viewbox_resize_event(event)[source]¶

Modify the data aspect and scale factor, to adjust to the new window size.

Parameters:	eventinstance of Event The event.

zoom(factor, center=None)[source]¶

Zoom in (or out) at the given center

Parameters:	factorfloat or tuple Fraction by which the scene should be zoomed (e.g. a factor of 2 causes the scene to appear twice as large). centertuple of 2-4 elements The center of the view. If not given or None, use the current center.

class vispy.scene.cameras.TurntableCamera(fov=45.0, elevation=30.0, azimuth=30.0, roll=0.0, distance=None, translate_speed=1.0, **kwargs)[source]¶

Bases: vispy.scene.cameras.perspective.Base3DRotationCamera

3D camera class that orbits around a center point while maintaining a view on a center point.

For this camera, the scale_factor indicates the zoom level, and the center indicates the position to put at the center of the view.

Parameters:

Parameters:	fovfloat Field of view. Zero (default) means orthographic projection. elevationfloat Elevation angle in degrees. Positive angles place the camera above the cente point, negative angles place the camera below the center point. azimuthfloat Azimuth angle in degrees. Zero degrees places the camera on the positive x-axis, pointing in the negative x direction. rollfloat Roll angle in degrees distancefloat \| None The distance of the camera from the rotation point (only makes sense if fov > 0). If None (default) the distance is determined from the scale_factor and fov. translate_speedfloat Scale factor on translation speed when moving the camera center point. **kwargsdict Keyword arguments to pass to BaseCamera.

fovfloat: Field of view. Zero (default) means orthographic projection.
elevationfloat: Elevation angle in degrees. Positive angles place the camera above the cente point, negative angles place the camera below the center point.
azimuthfloat: Azimuth angle in degrees. Zero degrees places the camera on the positive x-axis, pointing in the negative x direction.
rollfloat: Roll angle in degrees
distancefloat | None: The distance of the camera from the rotation point (only makes sense if fov > 0). If None (default) the distance is determined from the scale_factor and fov.
translate_speedfloat: Scale factor on translation speed when moving the camera center point.
**kwargsdict: Keyword arguments to pass to BaseCamera.

Notes

Interaction:

LMB: orbits the view around its center point.

RMB or scroll: change scale_factor (i.e. zoom level)

SHIFT + LMB: translate the center point

SHIFT + RMB: change FOV

property azimuth¶: The angle of the camera in degrees around the y axis. An angle of 0 places the camera within the (y, z) plane.

property elevation¶: The angle of the camera in degrees above the horizontal (x, z) plane.

orbit(azim, elev)[source]¶

Orbits the camera around the center position.

Parameters:	azimfloat Angle in degrees to rotate horizontally around the center point. elevfloat Angle in degrees to rotate vertically around the center point.

property roll¶: The angle of the camera in degrees around the z axis. An angle of 0 places puts the camera upright.

vispy.scene.canvas¶

class vispy.scene.canvas.SceneCanvas(title='VisPy canvas', size=800, 600, position=None, show=False, autoswap=True, app=None, create_native=True, vsync=False, resizable=True, decorate=True, fullscreen=False, config=None, shared=None, keys=None, parent=None, dpi=None, always_on_top=False, px_scale=1, bgcolor='black')[source]¶

Bases: vispy.app.canvas.Canvas, vispy.util.frozen.Frozen

A Canvas that automatically draws the contents of a scene

Parameters:

Parameters:	titlestr The widget title size(width, height) The size of the window. position(x, y) The position of the window in screen coordinates. showbool Whether to show the widget immediately. Default False. autoswapbool Whether to swap the buffers automatically after a draw event. Default True. If True, the `swap_buffers` Canvas method will be called last (by default) by the `canvas.draw` event handler. appApplication \| str Give vispy Application instance to use as a backend. (vispy.app is used by default.) If str, then an application using the chosen backend (e.g., ‘pyglet’) will be created. Note the canvas application can be accessed at `canvas.app`. create_nativebool Whether to create the widget immediately. Default True. vsyncbool Enable vertical synchronization. resizablebool Allow the window to be resized. decoratebool Decorate the window. Default True. fullscreenbool \| int If False, windowed mode is used (default). If True, the default monitor is used. If int, the given monitor number is used. configdict A dict with OpenGL configuration options, which is combined with the default configuration options and used to initialize the context. See `canvas.context.config` for possible options. sharedCanvas \| GLContext \| None An existing canvas or context to share OpenGL objects with. keysstr \| dict \| None Default key mapping to use. If ‘interactive’, escape and F11 will close the canvas and toggle full-screen mode, respectively. If dict, maps keys to functions. If dict values are strings, they are assumed to be `Canvas` methods, otherwise they should be callable. parentwidget-object The parent widget if this makes sense for the used backend. dpifloat \| None Resolution in dots-per-inch to use for the canvas. If dpi is None, then the value will be determined by querying the global config first, and then the operating system. always_on_topbool If True, try to create the window in always-on-top mode. px_scaleint > 0 A scale factor to apply between logical and physical pixels in addition to the actual scale factor determined by the backend. This option allows the scale factor to be adjusted for testing. bgcolorColor The background color to use.

titlestr: The widget title
size(width, height): The size of the window.
position(x, y): The position of the window in screen coordinates.
showbool: Whether to show the widget immediately. Default False.
autoswapbool: Whether to swap the buffers automatically after a draw event. Default True. If True, the swap_buffers Canvas method will be called last (by default) by the canvas.draw event handler.
appApplication | str: Give vispy Application instance to use as a backend. (vispy.app is used by default.) If str, then an application using the chosen backend (e.g., ‘pyglet’) will be created. Note the canvas application can be accessed at canvas.app.
create_nativebool: Whether to create the widget immediately. Default True.
vsyncbool: Enable vertical synchronization.
resizablebool: Allow the window to be resized.
decoratebool: Decorate the window. Default True.
fullscreenbool | int: If False, windowed mode is used (default). If True, the default monitor is used. If int, the given monitor number is used.
configdict: A dict with OpenGL configuration options, which is combined with the default configuration options and used to initialize the context. See canvas.context.config for possible options.
sharedCanvas | GLContext | None: An existing canvas or context to share OpenGL objects with.
keysstr | dict | None: Default key mapping to use. If ‘interactive’, escape and F11 will close the canvas and toggle full-screen mode, respectively. If dict, maps keys to functions. If dict values are strings, they are assumed to be Canvas methods, otherwise they should be callable.
parentwidget-object: The parent widget if this makes sense for the used backend.
dpifloat | None: Resolution in dots-per-inch to use for the canvas. If dpi is None, then the value will be determined by querying the global config first, and then the operating system.
always_on_topbool: If True, try to create the window in always-on-top mode.
px_scaleint > 0: A scale factor to apply between logical and physical pixels in addition to the actual scale factor determined by the backend. This option allows the scale factor to be adjusted for testing.
bgcolorColor: The background color to use.

Parameters:	visualVisual The visual to draw eventNone or DrawEvent Optionally specifies the original canvas draw event that initiated this draw.

Parameters:	eventinstance of Event The draw event.

Parameters:	eventinstance of Event The resize event.

Parameters:	fboinstance of FrameBuffer The framebuffer object . offsettuple The location of the fbo origin relative to the canvas’s framebuffer origin. csizetuple The size of the region in the canvas’s framebuffer that should be covered by this framebuffer object.

Parameters:	viewporttuple The viewport as (x, y, w, h).

Parameters:	regiontuple \| None Specifies the region of the canvas to render. Format is (x, y, w, h). By default, the entire canvas is rendered. sizetuple \| None Specifies the size of the image array to return. If no size is given, then the size of the region is used, multiplied by the pixel scaling factor of the canvas (see pixel_scale). This argument allows the scene to be rendered at resolutions different from the native canvas resolution. bgcolorinstance of Color \| None The background color to use. croparray-like \| None If specified it determines the pixels read from the framebuffer. In the format (x, y, w, h), relative to the region being rendered.
Returns:	imagearray Numpy array of type ubyte and shape (h, w, 4). Index [0, 0] is the upper-left corner of the rendered region.

Parameters:	nodeinstance of Node Not used.

Parameters:	postuple The position in logical coordinates to query.
Returns:	visualinstance of Visual \| None The visual at the position, if it exists.

Parameters:	postuple (x, y) position at which to find visuals. radiusint Distance away from pos to search for visuals.

vispy.scene.node¶

class vispy.scene.node.Node(parent=None, name=None, transforms=None)[source]¶

Bases: object

Base class representing an object in a scene.

A group of nodes connected through parent-child relationships define a scenegraph. Nodes may have any number of children.

Each Node defines a transform property, which describes the position, orientation, scale, etc. of the Node relative to its parent. The Node’s children inherit this property, and then further apply their own transformations on top of that.

With the transform property, each Node implicitly defines a “local” coordinate system, and the Nodes and edges in the scenegraph can be thought of as coordinate systems connected by transformation functions.

Parameters:	parentNode The parent of the Node. namestr The name used to identify the node. transformsinstance of TransformSystem \| None The associated transforms.

property canvas¶: The canvas in which this node’s scenegraph is being drawn.

property children¶: A copy of the list of children of this node. Do not add items to this list, but use x.parent = y instead.

property clip_children¶: Boolean indicating whether children of this node will inherit its clipper.

property clipper¶: A visual filter that can be used to clip visuals to the boundaries of this node.

common_parent(node)[source]¶

Return the common parent of two entities

If the entities have no common parent, return None.

Parameters:	nodeinstance of Node The other node.
Returns:	parentinstance of Node \| None The parent.

describe_tree(with_transform=False)[source]¶

Create tree diagram of children

Parameters:	with_transformbool If true, add information about node transform types.
Returns:	treestr The tree diagram.

property document¶

The document is an optional property that is an node representing the coordinate system from which this node should make physical measurements such as px, mm, pt, in, etc. This coordinate system should be used when determining line widths, font sizes, and any other lengths specified in physical units.

The default is None; in this case, a default document is used during drawing (usually this is supplied by the SceneCanvas).

property document_node¶

The node to be used as the document coordinate system.

By default, the document node is self.root_node.

is_child(node)[source]¶

Check if a node is a child of the current node

Parameters:	nodeinstance of Node The potential child.
Returns:	childbool Whether or not the node is a child.

node_path(node)[source]¶

Return two lists describing the path from this node to another

Parameters:	nodeinstance of Node The other node.
Returns:	p1list First path (see below). p2list Second path (see below).

Notes

The first list starts with this node and ends with the common parent between the endpoint nodes. The second list contains the remainder of the path from the common parent to the specified ending node.

For example, consider the following scenegraph:

A --- B --- C --- D
                           --- E --- F

Calling D.node_path(F) will return:

([D, C, B], [E, F])

node_path_to_child(node)[source]¶

Return a list describing the path from this node to a child node

If node is not a (grand)child of this node, then raise RuntimeError.

Parameters:	nodeinstance of Node The child node.
Returns:	pathlist \| None The path.

node_path_transforms(node)[source]¶

Return the list of transforms along the path to another node.

The transforms are listed in reverse order, such that the last transform should be applied first when mapping from this node to the other.

Parameters:	nodeinstance of Node The other node.
Returns:	transformslist A list of Transform instances.

node_transform(node)[source]¶

Return the transform that maps from the coordinate system of self to the local coordinate system of node.

Note that there must be a _single_ path in the scenegraph that connects the two entities; otherwise an exception will be raised.

Parameters:	nodeinstance of Node The other node.
Returns:	transforminstance of ChainTransform The transform.

on_parent_change(event)[source]¶

Parent change event handler

Parameters:	eventinstance of Event The event.

property order¶

A value used to determine the order in which nodes are drawn.

Greater values are drawn later. Children are always drawn after their parent.

property parent¶

The parent of this node in the scenegraph.

Nodes inherit coordinate transformations and some filters (opacity and clipping by default) from their parents. Setting this property assigns a new parent, changing the topology of the scenegraph.

May be set to None to remove this node (and its children) from a scenegraph.

parent_chain()[source]¶: Return the list of parents starting from this node. The chain ends at the first node with no parents.

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

property scene_node¶: The first ancestor of this node that is a SubScene instance, or self if no such node exists.

set_transform(type_, *args, **kwargs)[source]¶

Create a new transform of type and assign it to this node.

All extra arguments are used in the construction of the transform.

Parameters:	type_str The transform type. argstuple Arguments. *kwargsdict Keywoard arguments.

property transform¶: The transform that maps the local coordinate frame to the coordinate frame of the parent.

update()[source]¶: Emit an event to inform listeners that properties of this Node have changed. Also request a canvas update.

property visible¶: Whether this node should be drawn or not. Only applicable to nodes that can be drawn.

vispy.scene.events¶

class vispy.scene.events.SceneMouseEvent(event, visual)[source]¶

Bases: vispy.util.event.Event

Represents a mouse event that occurred on a SceneCanvas. This event is delivered to all entities whose mouse interaction area is under the event.

property button¶: The button pressed or released on this event.

property buttons¶: A list of all buttons currently pressed on the mouse.

property delta¶: The increment by which the mouse wheel has moved.

property last_event¶: The mouse event immediately prior to this one. This property is None when no mouse buttons are pressed.

property pos¶: The position of this event in the local coordinate system of the visual.

property press_event¶: The mouse press event that initiated a mouse drag, if any.

vispy.scene.visuals¶

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)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.line.arrow.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.

Parameters:

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. arrowsarray A (N, 4) or (N, 6) matrix where each row contains the (x, y) or the (x, y, z) coordinate of the first and second vertex of the arrow body. 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.

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.

arrowsarray

A (N, 4) or (N, 6) matrix where each row contains the (x, y) or the (x, y, z) coordinate of the first and second vertex of the arrow body. 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)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.axis.AxisVisual

Axis visual

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

Parameters:

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

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)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.box.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:

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

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)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.colorbar.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

label_strstr

The label that is to be drawn with the colorbar that provides information about the colorbar.

label_colorstr | vispy.color.Color

The color of the 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).

class vispy.scene.visuals.Compound(*args, **kwargs)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.visual.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)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.cube.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)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.ellipse.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: 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)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.graphs.graph.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

LineVisual, MarkersVisual, marker_types

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)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.linear_region.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)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.markers.MarkersVisual

Visual displaying marker symbols.

This class inherits from visuals.MarkersVisual 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.Mesh(*args, **kwargs)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.mesh.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.
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.

class vispy.scene.visuals.Plane(*args, **kwargs)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.plane.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)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.polygon.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)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.rectangle.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)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.regular_polygon.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)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.scrolling_lines.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)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.spectrogram.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)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.sphere.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)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.surface_plot.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)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.text.text.TextVisual

Visual that displays text

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

Note: SDF GPU is not currently supported in WebGL without additional: extensions (see comments in fragment shader below).

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 like those based on WebGL. The ‘gpu’ method should produce higher quality results.
font_managerobject | None: Font manager to use (can be shared if the GLContext is shared).
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)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.tube.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)[source]¶

Bases: vispy.scene.node.Node

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)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.volume.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.
climtuple of two floats | None: The contrast limits. The values in the volume are mapped to black and white corresponding to these values. Default maps between min and max.
method{‘mip’, ‘translucent’, ‘additive’, ‘iso’}: 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.
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.
clim_range_thresholdfloat: When changing the clims, if the new clim range is smaller than this fraction of the last-used texture data range, then it will trigger a rescaling of the texture data. For instance: if the texture data was last scaled from 0-1, and the clims are set to 0.4-0.5, then a texture rescale will be triggered if clim_range_threshold < 0.1. To prevent rescaling, set this value to 0. To always rescale, set the value to >= 1. By default, 0.2
emulate_texturebool: Use 2D textures to emulate a 3D texture. OpenGL ES 2.0 compatible, but has lower performance on desktop platforms.
interpolation{‘linear’, ‘nearest’}: Selects method of image interpolation.
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.Windbarb(*args, **kwargs)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.windbarb.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)[source]¶

Bases: vispy.scene.visuals.VisualNode, vispy.visuals.xyz_axis.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).

vispy.scene.widgets¶

The vispy.scene.widgets namespace provides a range of widgets to allow user interaction. Widgets are rectangular Visual objects such as buttons and sliders.

class vispy.scene.widgets.AxisWidget(orientation='left', **kwargs)[source]¶

Bases: vispy.scene.widgets.widget.Widget

Widget containing an axis

Parameters:	orientationstr Orientation of the axis, ‘left’ or ‘bottom’. **kwargsdict Keyword arguments to pass to AxisVisual.

link_view(view)[source]¶

Link this axis to a ViewBox

This makes it so that the axis’s domain always matches the visible range in the ViewBox.

Parameters:	viewinstance of ViewBox The ViewBox to link.

on_resize(event)[source]¶

Resize event handler

Parameters:	eventinstance of Event The event.

class vispy.scene.widgets.ColorBarWidget(cmap, orientation, label='', label_color='black', clim='', '', border_width=0.0, border_color='black', padding=0.2, 0.2, axis_ratio=0.05, **kwargs)[source]¶

Bases: vispy.scene.widgets.widget.Widget

Widget containing a ColorBar

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. The colorbar automatically resizes when its container’s dimension changes.

‘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

labelstr

The label that is to be drawn with the colorbar that provides information about the colorbar.

label_colorstr | vispy.color.Color

The color of 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

paddingtuple (major_axis, minor_axis) [0, 1]

padding with respect to the major and minor axis

axis_ratiofloat

ratio of minor axis to major axis

property border_color¶: The color of the border around the ColorBar in pixels

property border_width¶: The width of the border around the ColorBar in pixels

on_resize(event)[source]¶

Resize event handler

Parameters:	eventinstance of Event The event.

class vispy.scene.widgets.Console(text_color='black', font_size=12.0, **kwargs)[source]¶

Bases: vispy.scene.widgets.widget.Widget

Fast and failsafe text console

Parameters:	text_colorinstance of Color Color to use. font_sizefloat Point size to use.

clear()[source]¶: Clear the console

property font_size¶: The font size (in points) of the text

on_resize(event)[source]¶

Resize event handler

Parameters:	eventinstance of Event The event.

property text_color¶: The color of the text

write(text='', wrap=True)[source]¶

Write text and scroll

Parameters:	textstr Text to write. `''` can be used for a blank line, as a newline is automatically added to the end of each line. wrapstr If True, long messages will be wrapped to span multiple lines.

class vispy.scene.widgets.Grid(spacing=6, **kwargs)[source]¶

Bases: vispy.scene.widgets.widget.Widget

Widget that automatically sets the position and size of child Widgets to proportionally divide its internal area into a grid.

Parameters:	spacingint Spacing between widgets. **kwargsdict Keyword arguments to pass to Widget.

add_grid(row=None, col=None, row_span=1, col_span=1, **kwargs)[source]¶

Create a new Grid and add it as a child widget.

Parameters:	rowint The row in which to add the widget (0 is the topmost row) colint The column in which to add the widget (0 is the leftmost column) row_spanint The number of rows to be occupied by this widget. Default is 1. col_spanint The number of columns to be occupied by this widget. Default is 1. **kwargsdict Keyword arguments to pass to the new Grid.

add_view(row=None, col=None, row_span=1, col_span=1, **kwargs)[source]¶

Create a new ViewBox and add it as a child widget.

Parameters:	rowint The row in which to add the widget (0 is the topmost row) colint The column in which to add the widget (0 is the leftmost column) row_spanint The number of rows to be occupied by this widget. Default is 1. col_spanint The number of columns to be occupied by this widget. Default is 1. **kwargsdict Keyword arguments to pass to ViewBox.

add_widget(widget=None, row=None, col=None, row_span=1, col_span=1, **kwargs)[source]¶

Add a new widget to this grid. This will cause other widgets in the grid to be resized to make room for the new widget. Can be used to replace a widget as well

Parameters:

widgetWidget | None: The Widget to add. New widget is constructed if widget is None.
rowint: The row in which to add the widget (0 is the topmost row)
colint: The column in which to add the widget (0 is the leftmost column)
row_spanint: The number of rows to be occupied by this widget. Default is 1.
col_spanint: The number of columns to be occupied by this widget. Default is 1.
**kwargsdict: parameters sent to the new Widget that is constructed if widget is None

Notes

The widget’s parent is automatically set to this grid, and all other parent(s) are removed.

remove_widget(widget)[source]¶

Remove a widget from this grid

Parameters:	widgetWidget The Widget to remove

resize_widget(widget, row_span, col_span)[source]¶

Resize a widget in the grid to new dimensions.

Parameters:	widgetWidget The widget to resize row_spanint The number of rows to be occupied by this widget. col_spanint The number of columns to be occupied by this widget.

class vispy.scene.widgets.Label(text, rotation=0.0, **kwargs)[source]¶

Bases: vispy.scene.widgets.widget.Widget

Label widget

Parameters:	textstr The label. rotationfloat The rotation of the label. **kwargsdict Keyword arguments to pass to TextVisual.

on_resize(event)[source]¶

Resize event handler

Parameters:	eventinstance of Event The event.

class vispy.scene.widgets.ViewBox(camera=None, **kwargs)[source]¶

Bases: vispy.scene.widgets.widget.Widget

Provides a rectangular widget to which its subscene is rendered.

Three classes work together when using a ViewBox: * The SubScene class describes a “world” coordinate system and the entities that live inside it. * ViewBox is a “window” through which we view the subscene. Multiple ViewBoxes may view the same subscene. * Camera describes both the perspective from which the subscene is rendered, and the way user interaction affects that perspective.

In general it is only necessary to create the ViewBox; a SubScene and Camera will be generated automatically.

Parameters:	camerainstance of Camera \| str \| None The camera through which to view the SubScene. If None, then a PanZoomCamera (2D interaction) is used. If str, then the string is used as the argument to `make_camera()`. **kwargsdict Extra keyword arguments to pass to Widget.

add(node)[source]¶

Add an Node to the scene for this ViewBox.

This is a convenience method equivalent to node.parent = viewbox.scene

Parameters:	nodeinstance of Node The node to add.

property camera¶

Get/set the Camera in use by this ViewBox

If a string is given (e.g. ‘panzoom’, ‘turntable’, ‘fly’). A corresponding camera is selected if it already exists in the scene, otherwise a new camera is created.

The camera object is made a child of the scene (if it is not already in the scene).

Multiple cameras can exist in one scene, although only one can be active at a time. A single camera can be used by multiple viewboxes at the same time.

get_scene_bounds(dim=None)[source]¶

Get the total bounds based on the visuals present in the scene

Parameters:	dimint \| None Dimension to return.
Returns:	boundslist \| tuple If `dim is None`, Returns a list of 3 tuples, otherwise the bounds for the requested dimension.

is_in_scene(node)[source]¶

Get whether the given node is inside the scene of this viewbox.

Parameters:	nodeinstance of Node The node.

on_resize(event)[source]¶

Resize event handler

Parameters:	eventinstance of Event The event.

property scene¶: The root node of the scene viewed by this ViewBox.

class vispy.scene.widgets.Widget(pos=0, 0, size=10, 10, border_color=None, border_width=1, bgcolor=None, padding=0, margin=0, **kwargs)[source]¶

Bases: vispy.scene.visuals.Compound

A widget takes up a rectangular space, intended for use in a 2D pixel coordinate frame.

The widget is positioned using the transform attribute (as any node), and its extent (size) is kept as a separate property.

Parameters:

pos(x, y): A 2-element tuple to specify the top left corner of the widget.
size(w, h): A 2-element tuple to spicify the size of the widget.
border_colorcolor: The color of the border.
border_widthfloat: The width of the border line in pixels.
bgcolorcolor: The background color.
paddingint: The amount of padding in the widget (i.e. the space reserved between the contents and the border).
marginint: The margin to keep outside the widget’s border.

add_grid(*args, **kwargs)[source]¶

Create a new Grid and add it as a child widget.

All arguments are given to Grid().

add_view(*args, **kwargs)[source]¶

Create a new ViewBox and add it as a child widget.

All arguments are given to ViewBox().

add_widget(widget)[source]¶

Add a Widget as a managed child of this Widget.

The child will be automatically positioned and sized to fill the entire space inside this Widget (unless _update_child_widgets is redefined).

Parameters:	widgetinstance of Widget The widget to add.
Returns:	widgetinstance of Widget The widget.

property bgcolor¶: The background color of the Widget.

property border_color¶: The color of the border.

property height¶: The actual height of the widget

property height_max¶: The maximum height of the widget

property height_min¶: The minimum height of the widget

property inner_rect¶

The rectangular area inside the margin, border, and padding.

Generally widgets should avoid drawing or placing sub-widgets outside this rectangle.

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

remove_widget(widget)[source]¶

Remove a Widget as a managed child of this Widget.

Parameters:	widgetinstance of Widget The widget to remove.

property size¶

The size (w, h) of this widget.

If the widget is a child of another widget, then its size is assigned automatically by its parent.

property stretch¶

Stretch factors (w, h) used when determining how much space to allocate to this widget in a layout.

If either stretch factor is None, then it will be assigned when the widget is added to a layout based on the number of columns or rows it occupies.

property width¶: The actual width of this widget

property width_max¶: The maximum width the widget can have

property width_min¶: The minimum width the widget can have