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:

  1. Create a SceneCanvas to display the scene. This object has a scene property that is the top-level Node in the scene.
  2. Create one or more Node instances (see vispy.scene.visuals)
  3. 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
class vispy.scene.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')

Bases: vispy.app.canvas.Canvas

A Canvas that automatically draws the contents of a scene

Parameters:

title : str

The widget title

size : (width, height)

The size of the window.

position : (x, y)

The position of the window in screen coordinates.

show : bool

Whether to show the widget immediately. Default False.

autoswap : bool

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.

app : Application | 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_native : bool

Whether to create the widget immediately. Default True.

vsync : bool

Enable vertical synchronization.

resizable : bool

Allow the window to be resized.

decorate : bool

Decorate the window. Default True.

fullscreen : bool | int

If False, windowed mode is used (default). If True, the default monitor is used. If int, the given monitor number is used.

config : dict

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.

shared : Canvas | GLContext | None

An existing canvas or context to share OpenGL objects with.

keys : str | 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.

parent : widget-object

The parent widget if this makes sense for the used backend.

dpi : float | 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_top : bool

If True, try to create the window in always-on-top mode.

px_scale : int > 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.

bgcolor : Color

The background color to use.

See also

vispy.app.Canvas

Notes

Receives the following events:

  • initialize
  • resize
  • draw
  • mouse_press
  • mouse_release
  • mouse_double_click
  • mouse_move
  • mouse_wheel
  • key_press
  • key_release
  • stylus
  • touch
  • close

The ordering of the mouse_double_click, mouse_press, and mouse_release events are not guaranteed to be consistent between backends. Only certain backends natively support double-clicking (currently Qt and WX); on other backends, they are detected manually with a fixed time delay. This can cause problems with accessibility, as increasing the OS detection time or using a dedicated double-click button will not be respected.

Methods

close() Close the canvas
connect(fun) Connect a function to an event
create_native() Create the native widget if not already done so.
draw_visual(visual[, event, viewport]) Draw a visual to the canvas or currently active framebuffer.
measure_fps([window, callback]) Measure the current FPS
on_draw(event) Draw handler
on_resize(event) Resize handler
pop_fbo() Pop an FBO from the stack.
pop_viewport() Pop a viewport from the stack.
push_fbo(fbo, offset, csize) Push an FBO on the stack, together with the new viewport.
push_viewport(viewport) Push a viewport on the stack
render([region, size]) Render the scene to an offscreen buffer and return the image array.
set_current([event]) Make this the active GL canvas
show([visible, run]) Show or hide the canvas
swap_buffers([event]) Swap GL buffers such that the offscreen buffer becomes visible
update([event]) Inform the backend that the Canvas needs to be redrawn
canvas_fb_transform

The transform that maps from the canvas coordinate system to the current framebuffer coordinate system.

The framebuffer coordinate system is used for antialiasing calculations, and is also the system used when specifying coordinates for glViewport (or gloo.set_viewport). Its origin is in the lower-left corner (as opposed to the document / canvas coordinate system, which has its origin in the upper-left corner).

Often the canvas and framebuffer coordinate systems are identical. However, some systems with high-resolution displays may use framebuffers with higher resolution than the reported size of the canvas. Likewise, when rendering to an FBO, the resolution and offset of the framebuffer may not match the canvas.

central_widget

Returns the default widget that occupies the entire area of the canvas.

draw_visual(visual, event=None, viewport=None)

Draw a visual to the canvas or currently active framebuffer.

Parameters:

visual : Visual

The visual to draw

event : None or DrawEvent

Optionally specifies the original canvas draw event that initiated this draw.

viewport : tuple | None

Optionally specifies the viewport to use. If None, the entire physical size is used.

fb_ndc_transform

The transform that maps from the framebuffer coordinate system to normalized device coordinates (which is the obligatory output coordinate system for all vertex shaders). This transform accounts for the current glViewport.

on_draw(event)

Draw handler

Parameters:

event : instance of Event

The draw event.

on_resize(event)

Resize handler

Parameters:

event : instance of Event

The resize event.

pop_fbo()

Pop an FBO from the stack.

pop_viewport()

Pop a viewport from the stack.

push_fbo(fbo, offset, csize)

Push an FBO on the stack, together with the new viewport. and the transform to the FBO.

Parameters:

fbo : instance of FrameBuffer

The framebuffer.

offset : tuple

The offset.

csize : tuple

The size to use.

push_viewport(viewport)

Push a viewport on the stack

It is the responsibility of the caller to ensure the given values are int. The viewport's origin is defined relative to the current viewport.

Parameters:

viewport : tuple

The viewport as (x, y, w, h).

render(region=None, size=None)

Render the scene to an offscreen buffer and return the image array.

Parameters:

region : tuple | None

Specifies the region of the canvas to render. Format is (x, y, w, h). By default, the entire canvas is rendered.

size : tuple | None

Specifies the size of the image array to return. If no size is given, then the size of the region is used. This argument allows the scene to be rendered at resolutions different from the native canvas resolution.

Returns:

image : array

Numpy array of type ubyte and shape (h, w, 4). Index [0, 0] is the upper-left corner of the rendered region.

render_transform

The transform that maps from the Canvas pixel coordinate system <(0, 0) at top-left, (w, h) at bottom-right> to normalized device coordinates within the current glViewport and FBO.

Most visuals should use this transform when drawing.

scene

The SubScene object that represents the root node of the scene graph to be displayed.

class vispy.scene.Node(parent=None, name=None)

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 or parents, although it is uncommon to have more than one parent.

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 though of as coordinate systems connected by transformation functions.

Parameters:

parent : Node

The parent of the Node.

name : str

The name used to identify the node.

Methods

add_parent(parent) Add a parent
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that properties of this Node or its children have changed.
add_parent(parent)

Add a parent

Parameters:

parent : instance of Node

The parent.

children

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

common_parent(node)

Return the common parent of two entities

If the entities have no common parent, return None. Does not search past multi-parent branches.

Parameters:

node : instance of Node

The other node.

Returns:

parent : instance of Node | None

The parent.

describe_tree(with_transform=False)

Create tree diagram of children

Parameters:

with_transform : bool

If true, add information about node transform types.

Returns:

tree : str

The tree diagram.

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

node_path(node)

Return two lists describing the path from this node to another

Parameters:

node : instance of Node

The other node.

Returns:

p1 : list

First path (see below).

p2 : list

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

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

node_path_to_child(node)

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

This method assumes that the given node is a child node. Multiple parenting is allowed.

Parameters:

node : instance of Node

The child node.

Returns:

path : list | None

The path.

node_path_transforms(node)

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:

node : instance of Node

The other node.

Returns:

transform : instance of Transform

The transform.

node_transform(node)

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:

node : instance of Node

The other node.

Returns:

transform : instance of ChainTransform

The transform.

parent

Get/set the parent. If the node has multiple parents while using this property as a getter, an error is raised.

parents

Get/set a tuple of parents.

remove_parent(parent)

Remove a parent

Parameters:

parent : instance of Node

The parent.

set_transform(type_, *args, **kwargs)

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.

*args : tuple

Arguments.

**kwargs : dict

Keywoard arguments.

transform

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

update()

Emit an event to inform listeners that properties of this Node or its children have changed.

visible

Whether this node should be drawn or not. Only applicable to nodes that can be drawn.


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.


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

Bases: vispy.app.canvas.Canvas

A Canvas that automatically draws the contents of a scene

Parameters:

title : str

The widget title

size : (width, height)

The size of the window.

position : (x, y)

The position of the window in screen coordinates.

show : bool

Whether to show the widget immediately. Default False.

autoswap : bool

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.

app : Application | 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_native : bool

Whether to create the widget immediately. Default True.

vsync : bool

Enable vertical synchronization.

resizable : bool

Allow the window to be resized.

decorate : bool

Decorate the window. Default True.

fullscreen : bool | int

If False, windowed mode is used (default). If True, the default monitor is used. If int, the given monitor number is used.

config : dict

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.

shared : Canvas | GLContext | None

An existing canvas or context to share OpenGL objects with.

keys : str | 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.

parent : widget-object

The parent widget if this makes sense for the used backend.

dpi : float | 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_top : bool

If True, try to create the window in always-on-top mode.

px_scale : int > 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.

bgcolor : Color

The background color to use.

See also

vispy.app.Canvas

Notes

Receives the following events:

  • initialize
  • resize
  • draw
  • mouse_press
  • mouse_release
  • mouse_double_click
  • mouse_move
  • mouse_wheel
  • key_press
  • key_release
  • stylus
  • touch
  • close

The ordering of the mouse_double_click, mouse_press, and mouse_release events are not guaranteed to be consistent between backends. Only certain backends natively support double-clicking (currently Qt and WX); on other backends, they are detected manually with a fixed time delay. This can cause problems with accessibility, as increasing the OS detection time or using a dedicated double-click button will not be respected.

Methods

close() Close the canvas
connect(fun) Connect a function to an event
create_native() Create the native widget if not already done so.
draw_visual(visual[, event, viewport]) Draw a visual to the canvas or currently active framebuffer.
measure_fps([window, callback]) Measure the current FPS
on_draw(event) Draw handler
on_resize(event) Resize handler
pop_fbo() Pop an FBO from the stack.
pop_viewport() Pop a viewport from the stack.
push_fbo(fbo, offset, csize) Push an FBO on the stack, together with the new viewport.
push_viewport(viewport) Push a viewport on the stack
render([region, size]) Render the scene to an offscreen buffer and return the image array.
set_current([event]) Make this the active GL canvas
show([visible, run]) Show or hide the canvas
swap_buffers([event]) Swap GL buffers such that the offscreen buffer becomes visible
update([event]) Inform the backend that the Canvas needs to be redrawn
canvas_fb_transform

The transform that maps from the canvas coordinate system to the current framebuffer coordinate system.

The framebuffer coordinate system is used for antialiasing calculations, and is also the system used when specifying coordinates for glViewport (or gloo.set_viewport). Its origin is in the lower-left corner (as opposed to the document / canvas coordinate system, which has its origin in the upper-left corner).

Often the canvas and framebuffer coordinate systems are identical. However, some systems with high-resolution displays may use framebuffers with higher resolution than the reported size of the canvas. Likewise, when rendering to an FBO, the resolution and offset of the framebuffer may not match the canvas.

central_widget

Returns the default widget that occupies the entire area of the canvas.

draw_visual(visual, event=None, viewport=None)

Draw a visual to the canvas or currently active framebuffer.

Parameters:

visual : Visual

The visual to draw

event : None or DrawEvent

Optionally specifies the original canvas draw event that initiated this draw.

viewport : tuple | None

Optionally specifies the viewport to use. If None, the entire physical size is used.

fb_ndc_transform

The transform that maps from the framebuffer coordinate system to normalized device coordinates (which is the obligatory output coordinate system for all vertex shaders). This transform accounts for the current glViewport.

on_draw(event)

Draw handler

Parameters:

event : instance of Event

The draw event.

on_resize(event)

Resize handler

Parameters:

event : instance of Event

The resize event.

pop_fbo()

Pop an FBO from the stack.

pop_viewport()

Pop a viewport from the stack.

push_fbo(fbo, offset, csize)

Push an FBO on the stack, together with the new viewport. and the transform to the FBO.

Parameters:

fbo : instance of FrameBuffer

The framebuffer.

offset : tuple

The offset.

csize : tuple

The size to use.

push_viewport(viewport)

Push a viewport on the stack

It is the responsibility of the caller to ensure the given values are int. The viewport's origin is defined relative to the current viewport.

Parameters:

viewport : tuple

The viewport as (x, y, w, h).

render(region=None, size=None)

Render the scene to an offscreen buffer and return the image array.

Parameters:

region : tuple | None

Specifies the region of the canvas to render. Format is (x, y, w, h). By default, the entire canvas is rendered.

size : tuple | None

Specifies the size of the image array to return. If no size is given, then the size of the region is used. This argument allows the scene to be rendered at resolutions different from the native canvas resolution.

Returns:

image : array

Numpy array of type ubyte and shape (h, w, 4). Index [0, 0] is the upper-left corner of the rendered region.

render_transform

The transform that maps from the Canvas pixel coordinate system <(0, 0) at top-left, (w, h) at bottom-right> to normalized device coordinates within the current glViewport and FBO.

Most visuals should use this transform when drawing.

scene

The SubScene object that represents the root node of the scene graph to be displayed.


vispy.scene.node

class vispy.scene.node.Node(parent=None, name=None)

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 or parents, although it is uncommon to have more than one parent.

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 though of as coordinate systems connected by transformation functions.

Parameters:

parent : Node

The parent of the Node.

name : str

The name used to identify the node.

Methods

add_parent(parent) Add a parent
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that properties of this Node or its children have changed.
add_parent(parent)

Add a parent

Parameters:

parent : instance of Node

The parent.

children

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

common_parent(node)

Return the common parent of two entities

If the entities have no common parent, return None. Does not search past multi-parent branches.

Parameters:

node : instance of Node

The other node.

Returns:

parent : instance of Node | None

The parent.

describe_tree(with_transform=False)

Create tree diagram of children

Parameters:

with_transform : bool

If true, add information about node transform types.

Returns:

tree : str

The tree diagram.

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

node_path(node)

Return two lists describing the path from this node to another

Parameters:

node : instance of Node

The other node.

Returns:

p1 : list

First path (see below).

p2 : list

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

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

node_path_to_child(node)

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

This method assumes that the given node is a child node. Multiple parenting is allowed.

Parameters:

node : instance of Node

The child node.

Returns:

path : list | None

The path.

node_path_transforms(node)

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:

node : instance of Node

The other node.

Returns:

transform : instance of Transform

The transform.

node_transform(node)

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:

node : instance of Node

The other node.

Returns:

transform : instance of ChainTransform

The transform.

parent

Get/set the parent. If the node has multiple parents while using this property as a getter, an error is raised.

parents

Get/set a tuple of parents.

remove_parent(parent)

Remove a parent

Parameters:

parent : instance of Node

The parent.

set_transform(type_, *args, **kwargs)

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.

*args : tuple

Arguments.

**kwargs : dict

Keywoard arguments.

transform

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

update()

Emit an event to inform listeners that properties of this Node or its children have changed.

visible

Whether this node should be drawn or not. Only applicable to nodes that can be drawn.


vispy.scene.events

class vispy.scene.events.SceneEvent(type, canvas, transform_cache=None)

Bases: vispy.util.event.Event, vispy.visuals.transforms.transform_system.TransformSystem

SceneEvent is an Event that tracks its path through a scenegraph, beginning at a Canvas. It exposes information useful during drawing and user interaction.

Methods

auto_configure() Automatically configure the TransformSystem:
get_full_transform() Return the transform that maps from the current node to normalized device coordinates within the current glViewport and FBO.
node_transform([map_to, map_from]) Return the transform from map_from to map_to, using the current node stack to resolve parent ambiguities if needed.
pop_document()
pop_fbo() Pop an FBO from the stack.
pop_node() Pop an node from the stack.
pop_viewbox()
pop_viewport() Pop a viewport from the stack.
push_document(doc)
push_fbo(viewport, fbo, transform) Push an FBO on the stack, together with the new viewport.
push_node(node) Push an node on the stack.
push_viewbox(viewbox)
push_viewport(viewport) Push a viewport (x, y, w, h) on the stack.
canvas

The Canvas that originated this SceneEvent

canvas_cs

The node for the current canvas coordinate system. This cs represents the logical pixels of the canvas being drawn, with the origin in upper-left, and the canvas (width, height) in the bottom right. This coordinate system is most often used for handling mouse input.

document_cs

The node for the current document coordinate system. The coordinate system of this Node is used for making physical measurements--px, mm, in, etc.

document_to_framebuffer

Transform mapping from document coordinate frame to the framebuffer (physical pixel) coordinate frame.

framebuffer_cs

The node for the current framebuffer coordinate system. This coordinate system corresponds to the physical pixels being rendered to, with the origin in lower-right, and the framebufer (width, height) in upper-left. It is used mainly for making antialiasing measurements.

framebuffer_to_render

Transform mapping from pixel coordinate frame to rendering coordinate frame.

get_full_transform()

Return the transform that maps from the current node to normalized device coordinates within the current glViewport and FBO.

This transform consists of the full_transform prepended by a correction for the current glViewport and/or FBO.

Most entities will use this transform when drawing.

handled_children

List of children of the current node that have already been handled.

Nodes that manually process their children (as opposed to allowing drawing / mouse systems to handle them automatically) may append nodes to this list to prevent systems from handling them.

node_cs

The node at the top of the node stack.

node_transform(map_to=None, map_from=None)

Return the transform from map_from to map_to, using the current node stack to resolve parent ambiguities if needed.

By default, map_to is the normalized device coordinate system, and map_from is the current top node on the stack.

path

The path of Entities leading from the root SubScene to the current recipient of this Event.

pop_fbo()

Pop an FBO from the stack.

pop_node()

Pop an node from the stack.

pop_viewport()

Pop a viewport from the stack.

push_fbo(viewport, fbo, transform)

Push an FBO on the stack, together with the new viewport. and the transform to the FBO.

push_node(node)

Push an node on the stack.

push_viewport(viewport)

Push a viewport (x, y, w, h) on the stack. It is the responsibility of the caller to ensure the given values are int. The viewport's origin is defined relative to the current viewport.

render_cs

Return node for the normalized device coordinate system. This coordinate system is the obligatory output of GLSL vertex shaders, with (-1, -1) in bottom-left, and (1, 1) in top-right. This coordinate system is frequently used for rendering visuals because all vertices must ultimately be mapped here.

scene_transform

The transform that maps from the current node to the first scene in its ancestry.

view_transform

The transform that maps from the current node to the first viewbox in its ancestry.

viewbox

The current viewbox.

visual_to_canvas

Transform mapping from visual local coordinate frame to canvas coordinate frame.

visual_to_document

Transform mapping from visual local coordinate frame to document coordinate frame.

visual_to_framebuffer

Transform mapping from visual coordinate frame to the framebuffer (physical pixel) coordinate frame.

class vispy.scene.events.SceneMouseEvent(event, canvas, **kwargs)

Bases: vispy.scene.events.SceneEvent

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

Methods

auto_configure() Automatically configure the TransformSystem:
copy()
get_full_transform() Return the transform that maps from the current node to normalized device coordinates within the current glViewport and FBO.
map_from_canvas(obj)
map_to_canvas(obj)
node_transform([map_to, map_from]) Return the transform from map_from to map_to, using the current node stack to resolve parent ambiguities if needed.
pop_document()
pop_fbo() Pop an FBO from the stack.
pop_node() Pop an node from the stack.
pop_viewbox()
pop_viewport() Pop a viewport from the stack.
push_document(doc)
push_fbo(viewport, fbo, transform) Push an FBO on the stack, together with the new viewport.
push_node(node) Push an node on the stack.
push_viewbox(viewbox)
push_viewport(viewport) Push a viewport (x, y, w, h) on the stack.
button

The button pressed or released on this event.

buttons

A list of all buttons currently pressed on the mouse.

delta

The increment by which the mouse wheel has moved.

last_event

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

pos

The position of this event in the local coordinate system of the visual.

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.Axis(*args, **kwargs)

Bases: vispy.visuals.axis.AxisVisual, vispy.scene.node.Node

Axis visual

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

Parameters:

pos : array

Co-ordinates of start and end of the axis.

domain : tuple

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_direction : array

The tick direction to use (in document coordinates).

scale_type : str

The type of scale. For now only 'linear' is supported.

axis_color : tuple

RGBA values for the axis colour. Default is black.

tick_color : tuple

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.

parent : Node

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

name : string

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

**kwargs : dict

Keyword arguments to pass to Visual.

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Get the bounds
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_gl_state([preset]) Define the set of GL state parameters to use when drawing
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_state(*args, **kwargs) Modify the set of GL state parameters to use when drawing
class vispy.scene.visuals.Box(*args, **kwargs)

Bases: vispy.visuals.box.BoxVisual, vispy.scene.node.Node

Visual that displays a box.

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

Parameters:

width : float

Box width.

height : float

Box height.

depth : float

Box depth.

width_segments : int

Box segments count along the width.

height_segments : float

Box segments count along the height.

depth_segments : float

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_colors : ndarray

Same as for MeshVisual class. See create_plane for vertex ordering.

face_colors : ndarray

Same as for MeshVisual class. See create_plane for vertex ordering.

color : Color

The Color to use when drawing the cube faces.

edge_color : tuple or Color

The Color to use when drawing the cube edges. If None, then no cube edges are drawn.

parent : Node

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

name : string

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

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Get the bounds
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
mesh_data_changed()
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_data([vertices, faces, vertex_colors, ...]) Set the mesh data
set_gl_state([preset]) Define the set of GL state parameters to use when drawing
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_state(*args, **kwargs) Modify the set of GL state parameters to use when drawing
class vispy.scene.visuals.ColorBar(*args, **kwargs)

Bases: vispy.visuals.colorbar.ColorBarVisual, vispy.scene.node.Node

Visual subclass displaying a colorbar

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

Parameters:

center_pos : tuple (x, y)

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

halfdim : tuple (half_width, half_height)

Half the dimensions of the colorbar measured from the center. That way, the total dimensions of the colorbar is (x - half_width) to (x + half_width) and (y - half_height) to (y + half_height)

cmap : str | 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

label_str : str

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

clim : tuple (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_width : float (in px)

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

border_color : str | 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

parent : Node

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

name : string

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

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Return the (min, max) bounding values describing the location of this node in its local coordinate system.
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_gl_state([preset]) Define the set of GL state parameters to use when drawing
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_state(*args, **kwargs) Modify the set of GL state parameters to use when drawing
class vispy.scene.visuals.Cube(*args, **kwargs)

Bases: vispy.visuals.cube.CubeVisual, vispy.scene.node.Node

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:

size : float 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_colors : ndarray

Same as for MeshVisual class. See create_cube for vertex ordering.

face_colors : ndarray

Same as for MeshVisual class. See create_cube for vertex ordering.

color : Color

The Color to use when drawing the cube faces.

edge_color : tuple or Color

The Color to use when drawing the cube edges. If None, then no cube edges are drawn.

parent : Node

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

name : string

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

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Get the bounds
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
mesh_data_changed()
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_data([vertices, faces, vertex_colors, ...]) Set the mesh data
set_gl_state([preset]) Define the set of GL state parameters to use when drawing
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_state(*args, **kwargs) Modify the set of GL state parameters to use when drawing
class vispy.scene.visuals.Ellipse(*args, **kwargs)

Bases: vispy.visuals.ellipse.EllipseVisual, vispy.scene.node.Node

Displays a 2D ellipse

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

Parameters:

pos : array

Center of the ellipse

color : instance of Color

The face color to use.

border_color : instance of Color

The border color to use.

radius : float | tuple

Radius or radii of the ellipse Defaults to (0.1, 0.1)

start_angle : float

Start angle of the ellipse in degrees Defaults to 0.

span_angle : float

Span angle of the ellipse in degrees Defaults to 0.

num_segments : int

Number of segments to be used to draw the ellipse Defaults to 100

parent : Node

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

name : string

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

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Return the (min, max) bounding values describing the location of this node in its local coordinate system.
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_gl_options(*args, **kwargs)
set_gl_state([preset]) Define the set of GL state parameters to use when drawing
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_options(*args, **kwargs)
update_gl_state(*args, **kwargs) Modify the set of GL state parameters to use when drawing
class vispy.scene.visuals.GridLines(*args, **kwargs)

Bases: vispy.visuals.gridlines.GridLinesVisual, vispy.scene.node.Node

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:

scale : tuple

The scale to use.

parent : Node

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

name : string

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

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Return the (min, max) bounding values describing the location of this node in its local coordinate system.
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_gl_state([preset]) Define the set of GL state parameters to use when drawing
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_state(*args, **kwargs) Modify the set of GL state parameters to use when drawing
class vispy.scene.visuals.Histogram(*args, **kwargs)

Bases: vispy.visuals.histogram.HistogramVisual, vispy.scene.node.Node

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:

data : array-like

Data to histogram. Currently only 1D data is supported.

bins : int | array-like

Number of bins, or bin edges.

color : instance of Color

Color of the histogram.

orientation : {'h', 'v'}

Orientation of the histogram.

parent : Node

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

name : string

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

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Get the bounds
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
mesh_data_changed()
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_data([vertices, faces, vertex_colors, ...]) Set the mesh data
set_gl_state([preset]) Define the set of GL state parameters to use when drawing
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_state(*args, **kwargs) Modify the set of GL state parameters to use when drawing
class vispy.scene.visuals.Image(*args, **kwargs)

Bases: vispy.visuals.image.ImageVisual, vispy.scene.node.Node

Visual subclass displaying an image.

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

Parameters:

data : ndarray

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

method : str

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

  • 'auto': Automatically select 'impostor' if the image is drawn with a nonlinear transform; otherwise select 'subdivide'.
  • 'subdivide': ImageVisual is represented as a grid of triangles with texture coordinates linearly mapped.
  • 'impostor': ImageVisual is represented as a quad covering the entire view, with texture coordinates determined by the transform. This produces the best transformation results, but may be slow.

grid: tuple (rows, cols) :

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

cmap : str | ColorMap

Colormap to use for luminance images.

clim : str | tuple

Limits to use for the colormap. Can be 'auto' to auto-set bounds to the min and max of the data.

parent : Node

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

name : string

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

**kwargs : dict

Keyword arguments to pass to Visual.

Notes

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

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Get the bounds
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_data(image) Set the data
set_gl_state([preset]) Define the set of GL state parameters to use when drawing
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_state(*args, **kwargs) Modify the set of GL state parameters to use when drawing
class vispy.scene.visuals.Isocurve(*args, **kwargs)

Bases: vispy.visuals.isocurve.IsocurveVisual, vispy.scene.node.Node

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:

data : ndarray | None

2D scalar array.

level: float | None :

The level at which the isocurve is constructed from data.

parent : Node

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

name : string

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

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Get the bounds
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_data(data) Set the scalar array data
set_gl_state(**kwargs)
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_state(**kwargs)
class vispy.scene.visuals.Isoline(*args, **kwargs)

Bases: vispy.visuals.isoline.IsolineVisual, vispy.scene.node.Node

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:

vertices : ndarray, shape (Nv, 3) | None

Vertex coordinates.

tris : ndarray, shape (Nf, 3) | None

Indices into the vertex array.

data : ndarray, shape (Nv,) | None

scalar at vertices

levels : ndarray, shape (Nlev,) | None

The levels at which the isocurve is constructed from "data".

color_lev : Color, 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.

parent : Node

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

name : string

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

**kwargs : dict

Keyword arguments to pass to LineVisual.

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Get the bounds
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_color(color) Set the color
set_data([vertices, tris, data]) Set the data
set_gl_state(**kwargs)
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_state(**kwargs)
class vispy.scene.visuals.Isosurface(*args, **kwargs)

Bases: vispy.visuals.isosurface.IsosurfaceVisual, vispy.scene.node.Node

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:

data : ndarray | None

3D scalar array.

level: float | None :

The level at which the isosurface is constructed from data.

parent : Node

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

name : string

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

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Get the bounds
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
mesh_data_changed()
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_data(data) Set the scalar array data
set_gl_state([preset]) Define the set of GL state parameters to use when drawing
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_state(*args, **kwargs) Modify the set of GL state parameters to use when drawing
class vispy.scene.visuals.LinePlot(*args, **kwargs)

Bases: vispy.visuals.line_plot.LinePlotVisual, vispy.scene.node.Node

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:

data : array-like

Arguments can be passed as (Y,), (X, Y) or np.array((X, Y)).

color : instance of Color

Color of the line.

symbol : str

Marker symbol to use.

line_kind : str

Kind of line to draw. For now, only solid lines ('-') are supported.

width : float

Line width.

marker_size : float

Marker size. If size == 0 markers will not be shown.

edge_color : instance of Color

Color of the marker edge.

face_color : instance of Color

Color of the marker face.

edge_width : float

Edge width of the marker.

connect : str | array

See LineVisual.

parent : Node

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

name : string

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

**kwargs : keyword arguments

Argements to pass to the super class.

See also

LineVisual, MarkersVisual, marker_types

Examples

All of these syntaxes will work:

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

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Get the bounds
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_data(data, **kwargs) Set the line data
set_gl_state([preset]) Define the set of GL state parameters to use when drawing
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_state(*args, **kwargs) Modify the set of GL state parameters to use when drawing
class vispy.scene.visuals.Line(*args, **kwargs)

Bases: vispy.visuals.line.line.LineVisual, vispy.scene.node.Node

Line visual

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

Parameters:

pos : array

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

color : Color, 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.

parent : Node

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

name : string

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.

connect : str 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.

method : str

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.

antialias : bool

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.

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Get the bounds
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_data([pos, color, width, connect]) Set the data used to draw this visual.
set_gl_state(**kwargs)
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_state(**kwargs)
class vispy.scene.visuals.Markers(*args, **kwargs)

Bases: vispy.visuals.markers.MarkersVisual, vispy.scene.node.Node

Visual displaying marker symbols.

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

Parameters:

parent : Node

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

name : string

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

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Get the bounds
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_data([pos, symbol, size, edge_width, ...]) Set the data used to display this visual.
set_gl_state([preset]) Define the set of GL state parameters to use when drawing
set_symbol([symbol]) Set the symbol
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_state(*args, **kwargs) Modify the set of GL state parameters to use when drawing
class vispy.scene.visuals.Mesh(*args, **kwargs)

Bases: vispy.visuals.mesh.MeshVisual, vispy.scene.node.Node

Mesh visual

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

Parameters:

vertices : array-like | None

The vertices.

faces : array-like | None

The faces.

vertex_colors : array-like | None

Colors to use for each vertex.

face_colors : array-like | None

Colors to use for each face.

color : instance of Color

The color to use.

meshdata : instance of MeshData | None

The meshdata.

shading : str | None

Shading to use.

mode : str

The drawing mode.

parent : Node

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

name : string

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

**kwargs : dict

Keyword arguments to pass to Visual.

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Get the bounds
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
mesh_data_changed()
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_data([vertices, faces, vertex_colors, ...]) Set the mesh data
set_gl_state([preset]) Define the set of GL state parameters to use when drawing
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_state(*args, **kwargs) Modify the set of GL state parameters to use when drawing
class vispy.scene.visuals.Plane(*args, **kwargs)

Bases: vispy.visuals.plane.PlaneVisual, vispy.scene.node.Node

Visual that displays a plane.

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

Parameters:

width : float

Plane width.

height : float

Plane height.

width_segments : int

Plane segments count along the width.

height_segments : float

Plane segments count along the height.

direction: unicode :

{'-x', '+x', '-y', '+y', '-z', '+z'} Direction the plane will be facing.

vertex_colors : ndarray

Same as for MeshVisual class. See create_plane for vertex ordering.

face_colors : ndarray

Same as for MeshVisual class. See create_plane for vertex ordering.

color : Color

The Color to use when drawing the cube faces.

edge_color : tuple or Color

The Color to use when drawing the cube edges. If None, then no cube edges are drawn.

parent : Node

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

name : string

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

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Get the bounds
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
mesh_data_changed()
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_data([vertices, faces, vertex_colors, ...]) Set the mesh data
set_gl_state([preset]) Define the set of GL state parameters to use when drawing
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_state(*args, **kwargs) Modify the set of GL state parameters to use when drawing
class vispy.scene.visuals.Polygon(*args, **kwargs)

Bases: vispy.visuals.polygon.PolygonVisual, vispy.scene.node.Node

Displays a 2D polygon

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

Parameters:

pos : array

Set of vertices defining the polygon.

color : str | tuple | list of colors

Fill color of the polygon.

border_color : str | tuple | list of colors

Border color of the polygon.

border_width : int

Border width in pixels.

parent : Node

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

name : string

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

**kwargs : dict

Keyword arguments to pass to PolygonVisual.

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Return the (min, max) bounding values describing the location of this node in its local coordinate system.
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_gl_options(*args, **kwargs)
set_gl_state([preset]) Define the set of GL state parameters to use when drawing
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_options(*args, **kwargs)
update_gl_state(*args, **kwargs) Modify the set of GL state parameters to use when drawing
class vispy.scene.visuals.Rectangle(*args, **kwargs)

Bases: vispy.visuals.rectangle.RectangleVisual, vispy.scene.node.Node

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:

pos : array

Center of the rectangle

color : instance of Color

The fill color to use.

border_color : instance of Color

The border color to use.

height : float

Length of the rectangle along y-axis Defaults to 1.0

width : float

Length of the rectangle along x-axis Defaults to 1.0

radius : float | array

Radii of curvatures of corners in clockwise order from top-left Defaults to 0.

parent : Node

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

name : string

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

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Return the (min, max) bounding values describing the location of this node in its local coordinate system.
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_gl_options(*args, **kwargs)
set_gl_state([preset]) Define the set of GL state parameters to use when drawing
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_options(*args, **kwargs)
update_gl_state(*args, **kwargs) Modify the set of GL state parameters to use when drawing
class vispy.scene.visuals.RegularPolygon(*args, **kwargs)

Bases: vispy.visuals.regular_polygon.RegularPolygonVisual, vispy.scene.node.Node

Displays a regular polygon

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

Parameters:

pos : array

Center of the regular polygon

color : str | tuple | list of colors

Fill color of the polygon

border_color : str | tuple | list of colors

Border color of the polygon

radius : float

Radius of the regular polygon Defaults to 0.1

sides : int

Number of sides of the regular polygon

parent : Node

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

name : string

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

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Return the (min, max) bounding values describing the location of this node in its local coordinate system.
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_gl_options(*args, **kwargs)
set_gl_state([preset]) Define the set of GL state parameters to use when drawing
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_options(*args, **kwargs)
update_gl_state(*args, **kwargs) Modify the set of GL state parameters to use when drawing
class vispy.scene.visuals.Spectrogram(*args, **kwargs)

Bases: vispy.visuals.spectrogram.SpectrogramVisual, vispy.scene.node.Node

Calculate and show a spectrogram

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

Parameters:

x : array-like

1D signal to operate on. If len(x) < n_fft, x will be zero-padded to length n_fft.

n_fft : int

Number of FFT points. Much faster for powers of two.

step : int | None

Step size between calculations. If None, n_fft // 2 will be used.

fs : float

The sample rate of the data.

window : str | None

Window function to use. Can be 'hann' for Hann window, or None for no windowing.

color_scale : {'linear', 'log'}

Scale to apply to the result of the STFT. 'log' will use 10 * log10(power).

cmap : str

Colormap name.

clim : str | tuple

Colormap limits. Should be 'auto' or a two-element tuple of min and max values.

parent : Node

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

name : string

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

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Get the bounds
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_data(image) Set the data
set_gl_state([preset]) Define the set of GL state parameters to use when drawing
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_state(*args, **kwargs) Modify the set of GL state parameters to use when drawing
class vispy.scene.visuals.SurfacePlot(*args, **kwargs)

Bases: vispy.visuals.surface_plot.SurfacePlotVisual, vispy.scene.node.Node

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:

x : ndarray | None

1D array of values specifying the x positions of vertices in the grid. If None, values will be assumed to be integers.

y : ndarray | None

1D array of values specifying the x positions of vertices in the grid. If None, values will be assumed to be integers.

z : ndarray

2D array of height values for each grid vertex.

colors : ndarray

(width, height, 4) array of vertex colors.

parent : Node

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

name : string

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.

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Get the bounds
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
generate_faces()
mesh_data_changed()
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_data([x, y, z, colors]) Update the data in this surface plot.
set_gl_state([preset]) Define the set of GL state parameters to use when drawing
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_state(*args, **kwargs) Modify the set of GL state parameters to use when drawing
class vispy.scene.visuals.Text(*args, **kwargs)

Bases: vispy.visuals.text.text.TextVisual, vispy.scene.node.Node

Visual that displays text

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

Parameters:

text : str | 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.

color : instance of Color

Color to use.

bold : bool

Bold face.

italic : bool

Italic face.

face : str

Font face to use.

font_size : float

Point size to use.

pos : tuple | 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.

rotation : float

Rotation (in degrees) of the text clockwise.

anchor_x : str

Horizontal text anchor.

anchor_y : str

Vertical text anchor.

font_manager : object | None

Font manager to use (can be shared if the GLContext is shared).

parent : Node

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

name : string

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

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Return the (min, max) bounding values describing the location of this node in its local coordinate system.
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the Text
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_gl_state([preset]) Define the set of GL state parameters to use when drawing
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_state(*args, **kwargs) Modify the set of GL state parameters to use when drawing
class vispy.scene.visuals.Tube(*args, **kwargs)

Bases: vispy.visuals.tube.TubeVisual, vispy.scene.node.Node

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:

points : ndarray

An array of (x, y, z) points describing the path along which the tube will be extruded.

radius : float

The radius of the tube. Defaults to 1.0.

closed : bool

Whether the tube should be closed, joining the last point to the first. Defaults to False.

color : Color | 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_points : int

The number of points in the circle-approximating polygon of the tube's cross section. Defaults to 8.

shading : str | 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.

mode : str

Same as for the MeshVisual class. Defaults to 'triangles'.

parent : Node

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

name : string

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

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Get the bounds
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
mesh_data_changed()
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_data([vertices, faces, vertex_colors, ...]) Set the mesh data
set_gl_state([preset]) Define the set of GL state parameters to use when drawing
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_state(*args, **kwargs) Modify the set of GL state parameters to use when drawing
class vispy.scene.visuals.Volume(*args, **kwargs)

Bases: vispy.visuals.volume.VolumeVisual, vispy.scene.node.Node

Displays a 3D Volume

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

Parameters:

vol : ndarray

The volume to display. Must be ndim==3.

clim : tuple 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'.

threshold : float

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

relative_step_size : float

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.

cmap : str

Colormap to use.

emulate_texture : bool

Use 2D textures to emulate a 3D texture. OpenGL ES 2.0 compatible, but has lower performance on desktop platforms.

parent : Node

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

name : string

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

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Get the visual bounds
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_data(vol[, clim]) Set the volume data.
set_gl_state([preset]) Define the set of GL state parameters to use when drawing
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_state(*args, **kwargs) Modify the set of GL state parameters to use when drawing
class vispy.scene.visuals.XYZAxis(*args, **kwargs)

Bases: vispy.visuals.xyz_axis.XYZAxisVisual, vispy.scene.node.Node

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:

parent : Node

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

name : string

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

Methods

add_parent(parent) Add a parent
attach(filt) Attach a Filter to this visual
bounds(mode, axis) Get the bounds
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
detach(filt) Detach a filter
draw(transforms) Draw the visual
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
remove_parent(parent) Remove a parent
set_data([pos, color, width, connect]) Set the data used to draw this visual.
set_gl_state(**kwargs)
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that this Visual needs to be redrawn.
update_gl_state(**kwargs)

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.Console(text_color='black', font_size=12.0, **kwargs)

Bases: vispy.scene.widgets.widget.Widget

Fast and failsafe text console

Parameters:

text_color : instance of Color

Color to use.

font_size : float

Point size to use.

Methods

add_grid(*args, **kwargs) Create a new Grid and add it as a child widget.
add_parent(parent) Add a parent
add_view(*args, **kwargs) Create a new ViewBox and add it as a child widget.
add_widget(widget) Add a Widget as a managed child of this Widget.
clear() Clear the console
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
draw(event) Draw the widget
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
on_resize(event) On resize handler
remove_parent(parent) Remove a parent
remove_widget(widget) Remove a Widget as a managed child of this Widget.
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that properties of this Node or its children have changed.
write([text, wrap]) Write text and scroll
clear()

Clear the console

draw(event)

Draw the widget

Parameters:

event : instance of Event

The draw event.

font_size

The font size (in points) of the text

text_color

The color of the text

write(text='', wrap=True)

Write text and scroll

Parameters:

text : str

Text to write. '' can be used for a blank line, as a newline is automatically added to the end of each line.

wrap : str

If True, long messages will be wrapped to span multiple lines.

class vispy.scene.widgets.Grid(spacing=6, **kwargs)

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:

spacing : int

Spacing between widgets.

**kwargs : dict

Keyword arguments to pass to Widget.

Methods

add_grid([row, col, row_span, col_span]) Create a new Grid and add it as a child widget.
add_parent(parent) Add a parent
add_view([row, col, row_span, col_span]) Create a new ViewBox and add it as a child widget.
add_widget([widget, row, col, row_span, ...]) Add a new widget to this grid.
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
draw(event) Draw the widget borders
next_row()
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
on_resize(event) On resize handler
remove_parent(parent) Remove a parent
remove_widget(widget) Remove a Widget as a managed child of this Widget.
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that properties of this Node or its children have changed.
add_grid(row=None, col=None, row_span=1, col_span=1, **kwargs)

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

Parameters:

row : int

The row in which to add the widget (0 is the topmost row)

col : int

The column in which to add the widget (0 is the leftmost column)

row_span : int

The number of rows to be occupied by this widget. Default is 1.

col_span : int

The number of columns to be occupied by this widget. Default is 1.

**kwargs : dict

Keyword arguments to pass to the new Grid.

add_view(row=None, col=None, row_span=1, col_span=1, **kwargs)

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

Parameters:

row : int

The row in which to add the widget (0 is the topmost row)

col : int

The column in which to add the widget (0 is the leftmost column)

row_span : int

The number of rows to be occupied by this widget. Default is 1.

col_span : int

The number of columns to be occupied by this widget. Default is 1.

**kwargs : dict

Keyword arguments to pass to ViewBox.

add_widget(widget=None, row=None, col=None, row_span=1, col_span=1)

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.

Parameters:

widget : Widget

The Widget to add

row : int

The row in which to add the widget (0 is the topmost row)

col : int

The column in which to add the widget (0 is the leftmost column)

row_span : int

The number of rows to be occupied by this widget. Default is 1.

col_span : int

The number of columns to be occupied by this widget. Default is 1.

Notes

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

class vispy.scene.widgets.ViewBox(camera=None, scene=None, clip_method='fragment', **kwargs)

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:

camera : None, Camera, or str

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

scene : None or SubScene

The SubScene instance to view. If None, a new SubScene is created.

clip_method : str

Clipping method to use.

**kwargs : dict

Extra keyword arguments to pass to Widget.

Methods

add(node) Add an Node to the scene for this ViewBox.
add_grid(*args, **kwargs) Create a new Grid and add it as a child widget.
add_parent(parent) Add a parent
add_view(*args, **kwargs) Create a new ViewBox and add it as a child widget.
add_widget(widget) Add a Widget as a managed child of this Widget.
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
draw(event) Draw the viewbox border/background
get_scene_bounds([dim]) Get the total bounds based on the visuals present in the scene
is_in_scene(node) Get whether the given node is inside the scene of this viewbox.
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
on_resize(event) On resize handler
remove_parent(parent) Remove a parent
remove_widget(widget) Remove a Widget as a managed child of this Widget.
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that properties of this Node or its children have changed.
add(node)

Add an Node to the scene for this ViewBox.

This is a convenience method equivalent to node.add_parent(viewbox.scene)

Parameters:

node : instance of Node

The node to add.

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.

clip_method

The method used to clip the subscene to the boundaries of the viewbox.

Clipping methods are:

  • None - do not perform clipping. The default for now.
  • 'viewport' - use glViewPort to provide a clipped sub-grid onto the parent pixel grid, if possible.
  • 'fbo' - use an FBO to draw the subscene to a texture, and then render the texture in the parent scene.
  • 'fragment' - clipping in the fragment shader
  • 'stencil' - TODO

Notes

The 'viewport' method requires that the transformation (from the pixel grid to this viewbox) is translate+scale only. If this is not the case, the method falls back to the default.

The 'fbo' method is convenient when the result of the viewbox should be reused. Otherwise the overhead can be significant and the image can get slightly blurry if the transformations do not match.

It is possible to have a graph with multiple stacked viewboxes which each use different methods (subject to the above restrictions).

draw(event)

Draw the viewbox border/background

This also prepares to draw the subscene using the configured clipping method.

Parameters:

event : instance of Event

The draw event.

get_scene_bounds(dim=None)

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

Parameters:

dim : int | None

Dimension to return.

Returns:

bounds : list | tuple

If dim is None, Returns a list of 3 tuples, otherwise the bounds for the requested dimension.

is_in_scene(node)

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

Parameters:

node : instance of Node

The node.

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, bgcolor=None, clip=False, padding=0, margin=0, **kwargs)

Bases: vispy.scene.node.Node

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_color : color

The color of the border.

bgcolor : color

The background color.

clip : bool

Not used :)

padding : int

The amount of padding in the widget (i.e. the space reserved between the contents and the border).

margin : int

The margin to keep outside the widget's border.

Methods

add_grid(*args, **kwargs) Create a new Grid and add it as a child widget.
add_parent(parent) Add a parent
add_view(*args, **kwargs) Create a new ViewBox and add it as a child widget.
add_widget(widget) Add a Widget as a managed child of this Widget.
common_parent(node) Return the common parent of two entities
describe_tree([with_transform]) Create tree diagram of children
draw(event) Draw the widget borders
node_path(node) Return two lists describing the path from this node to another
node_path_to_child(node) Return a list describing the path from this node to a child node
node_path_transforms(node) Return the list of transforms along the path to another node.
node_transform(node) Return the transform that maps from the coordinate system of self to the local coordinate system of node.
on_resize(event) On resize handler
remove_parent(parent) Remove a parent
remove_widget(widget) Remove a Widget as a managed child of this Widget.
set_transform(type_, *args, **kwargs) Create a new transform of type and assign it to this node.
update() Emit an event to inform listeners that properties of this Node or its children have changed.
add_grid(*args, **kwargs)

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

All arguments are given to Grid().

add_view(*args, **kwargs)

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

All arguments are given to ViewBox().

add_widget(widget)

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:

widget : instance of Widget

The widget to add.

Returns:

widget : instance of Widget

The widget.

bgcolor

The background color of the Widget.

border_color

The color of the border.

draw(event)

Draw the widget borders

Parameters:

event : instance of Event

The event containing the transforms.

inner_rect

The rectangular area inside the margin, border and padding.

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

on_resize(event)

On resize handler

Parameters:

event : instance of Event

The resize event.

remove_widget(widget)

Remove a Widget as a managed child of this Widget.

Parameters:

widget : instance of Widget

The widget to remove.