# 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:
    vshare instance 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:
      filt object

        The filter to attach.

      view instance of VisualView | None

        The view to use.

  bounds(axis, view=None)

    Get the bounds of the Visual

    Parameters:
      axis int

        The axis.

      view instance of VisualView

        The view to use.

  detach(filt, view=None)

    Detach a filter.

    Parameters:
      filt object

        The filter to detach.

      view instance 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_from str

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

      map_to str

        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:
    subvisuals list of BaseVisual instances

      The list of visuals to be combined in this compound visual.

  add_subvisual(visual)

    Add a subvisual

    Parameters:
      visual instance 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:
      filt object

        The filter to attach.

      view instance of VisualView | None

        The view to use.

  detach(filt, view=None)

    Detach a filter.

    Parameters:
      filt object

        The filter to detach.

      view instance 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:
      *args tuple

        Arguments.

      **kwargs dict

        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:
      *args tuple

        Arguments.

      **kwargs dict

        Keyword arguments.

  remove_subvisual(visual)

    Remove a subvisual

    Parameters:
      visual instance 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:
      preset str

        Preset to use.

      **kwargs dict

        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:
      *args tuple

        Arguments.

      **kwargs dict

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

      Vertex shader code.

    fcode str

      Fragment shader code.

    gcode str or None

      Optional geometry shader code.

    program instance of Program | None

      The program to use. If None, a program will be constructed using `vcode` and `fcode`.

    vshare instance 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:
      filt object

        The filter to attach.

      view instance of VisualView | None

        The view to use.

  detach(filt, view=None)

    Detach a filter.

    Parameters:
      filt object

        The filter to detach.

      view instance 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:
      *args tuple

        Arguments.

      **kwargs dict

        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:
      *args tuple

        Arguments.

      **kwargs dict

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

        Preset to use.

      **kwargs dict

        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:
      *args tuple

        Arguments.

      **kwargs dict

        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)

previous

vispy.visuals.tube module

next

vispy.visuals.volume module