vispy.visuals.visual module#

Definitions#

Visual : an object that (1) can be drawn on-screen, (2) can be manipulated by configuring the coordinate transformations that it uses.

View : a special type of visual that (1) draws the contents of another visual, (2) using a different set of transforms. Views have only the basic visual interface (draw, bounds, attach, etc.) and lack access to the specific features of the visual they are linked to (for example, LineVisual has a set_data() method, but there is no corresponding method on a view of a LineVisual).

Class Structure#

BaseVisual - provides transforms and view creation This class lays out the basic API for all visuals: draw(), bounds(), view(), and attach() methods, as well as a TransformSystem instance that determines where the visual will be drawn.
Visual - defines a shader program to draw. Subclasses are responsible for supplying the shader code and configuring program variables, including transforms.
VisualView - clones the shader program from a Visual instance. Instances of VisualView contain their own shader program, transforms and filter attachments, and generally behave like a normal instance of Visual.
CompoundVisual - wraps multiple Visual instances. These visuals provide no program of their own, but instead rely on one or more internally generated Visual instances to do their drawing. For example, a PolygonVisual consists of an internal LineVisual and MeshVisual.
CompoundVisualView - wraps multiple VisualView instances. This allows a CompoundVisual to be viewed with a different set of transforms and filters.

Making Visual Subclasses#

When making subclasses of Visual, it is only necessary to reimplement the _prepare_draw(), _prepare_transforms(), and _compute_bounds() methods. These methods will be called by the visual automatically when it is needed for itself or for a view of the visual.

It is important to remember when implementing these methods that most changes made to the visual’s shader program should also be made to the programs for each view. To make this easier, the visual uses a MultiProgram, which allows all shader programs across the visual and its views to be accessed simultaneously. For example:

def _prepare_draw(self, view):
    # This line applies to the visual and all of its views
    self.shared_program['a_position'] = self._vbo

    # This line applies only to the view that is about to be drawn
    view.view_program['u_color'] = (1, 1, 1, 1)

Under most circumstances, it is not necessary to reimplement VisualView because a view will directly access the _prepare and _compute methods from the visual it is viewing. However, if the Visual to be viewed is a subclass that reimplements other methods such as draw() or bounds(), then it will be necessary to provide a new matching VisualView subclass.

Making CompoundVisual Subclasses#

Compound visual subclasses are generally very easy to construct:

class PlotLineVisual(visuals.CompoundVisual):
    def __init__(self, ...):
        self._line = LineVisual(...)
        self._point = PointVisual(...)
        visuals.CompoundVisual.__init__(self, [self._line, self._point])

A compound visual will automatically handle forwarding transform system changes and filter attachments to its internally-wrapped visuals. To the user, this will appear to behave as a single visual.

class vispy.visuals.visual.BaseVisual(vshare=None)#

Bases: Frozen

Superclass for all visuals.

This class provides:

A TransformSystem.

Two events: update and bounds_change.

Minimal framework for creating views of the visual.

A data structure that is shared between all views of the visual.

Abstract draw, bounds, attach, and detach methods.

Parameters:

vshareinstance of VisualShare | None: The visual share.

Notes

When used in the scenegraph, all Visual classes are mixed with vispy.scene.Node in order to implement the methods, attributes and capabilities required for their usage within it.

This subclasses Frozen so that subclasses can easily freeze their properties.

attach(filt, view=None)#

Attach a Filter to this visual.

Each filter modifies the appearance or behavior of the visual.

Parameters:

filtobject: The filter to attach.
viewinstance of VisualView | None: The view to use.

bounds(axis, view=None)#

Get the bounds of the Visual

Parameters:

axisint: The axis.
viewinstance of VisualView: The view to use.

detach(filt, view=None)#

Detach a filter.

Parameters:

filtobject: The filter to detach.
viewinstance of VisualView | None: The view to use.

draw()#

get_transform(map_from='visual', map_to='render')#

Return a transform mapping between any two coordinate systems.

Parameters:

map_fromstr: The starting coordinate system to map from. Must be one of: visual, scene, document, canvas, framebuffer, or render.
map_tostr: The ending coordinate system to map to. Must be one of: visual, scene, document, canvas, framebuffer, or render.

property transform#

property transforms#

update()#: Update the Visual

view()#: Return a new view of this visual.

property visible#

class vispy.visuals.visual.BaseVisualView(visual)#

Bases: object

Base class for a view on a visual.

This class must be mixed with another Visual class to work properly. It works mainly by forwarding the calls to _prepare_draw, _prepare_transforms, and _compute_bounds to the viewed visual.

property visual#

class vispy.visuals.visual.CompoundVisual(subvisuals)#

Bases: BaseVisual

Visual consisting entirely of sub-visuals.

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

Parameters:

subvisualslist of BaseVisual instances: The list of visuals to be combined in this compound visual.

add_subvisual(visual)#

Add a subvisual

Parameters:

visualinstance of Visual: The visual to add.

attach(filt, view=None)#

Attach a Filter to this visual

Each filter modifies the appearance or behavior of the visual.

Parameters:

filtobject: The filter to attach.
viewinstance of VisualView | None: The view to use.

detach(filt, view=None)#

Detach a filter.

Parameters:

filtobject: The filter to detach.
viewinstance of VisualView | None: The view to use.

draw()#: Draw the visual

pop_gl_state()#

Restore a previous set of GL state parameters if available.

If no previous GL state is available (see push_gl_state()), this has no effect.

push_gl_state(*args, **kwargs)#

Define the set of GL state parameters to use when drawing.

The arguments are forwarded to vispy.gloo.wrappers.set_state().

This differs from set_gl_state() in that it stashes the current state. See pop_gl_state() for restoring the state.

Parameters:

*argstuple: Arguments.
**kwargsdict: Keyword arguments.

push_gl_state_update(*args, **kwargs)#

Modify the set of GL state parameters to use when drawing.

The arguments are forwarded to vispy.gloo.wrappers.set_state().

This differs from update_gl_state() in that it stashes the current state. See pop_gl_state() for restoring the state.

Parameters:

*argstuple: Arguments.
**kwargsdict: Keyword arguments.

remove_subvisual(visual)#

Remove a subvisual

Parameters:

visualinstance of Visual: The visual to remove.

set_gl_state(preset=None, **kwargs)#

Define the set of GL state parameters to use when drawing.

The arguments are forwarded to vispy.gloo.wrappers.set_state().

This can also be used as a context manager that will revert the gl_state on exit.

Parameters:

presetstr: Preset to use.
**kwargsdict: Keyword arguments.

update_gl_state(*args, **kwargs)#

Modify the set of GL state parameters to use when drawing.

The arguments are forwarded to vispy.gloo.wrappers.set_state().

This can also be used as a context manager that will revert the gl_state on exit.

Parameters:

*argstuple: Arguments.
**kwargsdict: Keyword arguments.

class vispy.visuals.visual.CompoundVisualView(visual)#: Bases: BaseVisualView, CompoundVisual

class vispy.visuals.visual.Visual(vcode='', fcode='', gcode=None, program=None, vshare=None)#

Bases: BaseVisual

Base class for all visuals that can be drawn using a single shader program.

This class creates a MultiProgram, which is an object that behaves like a normal shader program (you can assign shader code, upload values, set template variables, etc.) but internally manages multiple ModularProgram instances, one per view.

Subclasses generally only need to reimplement _compute_bounds, _prepare_draw, and _prepare_transforms.

Parameters:

vcodestr: Vertex shader code.
fcodestr: Fragment shader code.
gcodestr or None: Optional geometry shader code.
programinstance of Program | None: The program to use. If None, a program will be constructed using vcode and fcode.
vshareinstance of VisualShare | None: The visual share, if necessary.

attach(filt, view=None)#

Attach a Filter to this visual

Each filter modifies the appearance or behavior of the visual.

Parameters:

filtobject: The filter to attach.
viewinstance of VisualView | None: The view to use.

detach(filt, view=None)#

Detach a filter.

Parameters:

filtobject: The filter to detach.
viewinstance of VisualView | None: The view to use.

draw()#

pop_gl_state()#

Restore a previous set of GL state parameters if available.

If no previous GL state is available (see push_gl_state()), this has no effect.

push_gl_state(*args, **kwargs)#

Define the set of GL state parameters to use when drawing.

The arguments are forwarded to vispy.gloo.wrappers.set_state().

This differs from set_gl_state() in that it stashes the current state. See pop_gl_state() for restoring the state.

Parameters:

*argstuple: Arguments.
**kwargsdict: Keyword arguments.

push_gl_state_update(*args, **kwargs)#

Modify the set of GL state parameters to use when drawing.

The arguments are forwarded to vispy.gloo.wrappers.set_state().

This differs from update_gl_state() in that it stashes the current state. See pop_gl_state() for restoring the state.

Parameters:

*argstuple: Arguments.
**kwargsdict: Keyword arguments.

set_gl_state(preset=None, **kwargs)#

Define the set of GL state parameters to use when drawing.

The arguments are forwarded to vispy.gloo.wrappers.set_state().

This can also be used as a context manager that will revert the gl_state on exit. When used as a context manager, this function is designed to be constructed directly in the header of the with statement to avoid confusion about what state will be restored on exit.

Parameters:

presetstr: Preset to use.
**kwargsdict: Keyword arguments.

property shared_program#

update_gl_state(*args, **kwargs)#

Modify the set of GL state parameters to use when drawing.

The arguments are forwarded to vispy.gloo.wrappers.set_state().

This can also be used as a context manager that will revert the gl_state on exit.

Parameters:

*argstuple: Arguments.
**kwargsdict: Keyword arguments.

property view_program#

class vispy.visuals.visual.VisualShare#

Bases: object

Contains data that is shared between all views of a visual.

This includes:

GL state variables (blending, depth test, etc.)

A weak dictionary of all views

A list of filters that should be applied to all views

A cache for bounds.

class vispy.visuals.visual.VisualView(visual)#

Bases: BaseVisualView, Visual

A view on another Visual instance.

View instances are created by calling visual.view().

Because this is a subclass of Visual, all instances of VisualView define their own shader program (which is a clone of the viewed visual’s program), transforms, and filter attachments.

class vispy.visuals.visual.updating_property(fget=None, fset=None, doc=None)#

Bases: object

A property descriptor that autoupdates the Visual during attribute setting.

Use this as a decorator in place of the @property when you want the attribute to trigger an immediate update to the visual upon change. You may additionally declare an @setter, and if you do, it will be called in addition to the standard logic: self._attr_name = value.

For example, the following code examples are equivalent:

class SomeVisual1(Visual):
    def __init__(self, someprop=None):
        self._someprop = someprop

    @property
    def someprop(self):
        return self._someprop

    @someprop.setter
    def someprop(self, value):
        previous = self._someprop
        if (previous is None) or np.any(value != previous):
            self._someprop = value
            self._need_update = True
            if hasattr(self, 'events'):
                self.update()

class SomeVisual2(Visual):
    def __init__(self, someprop=None):
        self._someprop = someprop

    @updating_property
    def someprop(self):
        pass

NOTE: by default the __get__ method here will look for the conventional _attr_name property on the object. The result of this is that you don’t actually have to put anything in the body of a method decorated with @updating_property if you don’t want to do anything other than retrieve the property. So you may see this slightly strange pattern being used:

class SomeVisual2(Visual):
    def __init__(self, someprop=None):
        self._someprop = someprop

    @updating_property
    def someprop(self):
        '''the docstring (or pass) is all that is needed'''

setter(fset)#