Skip to main content
`Ctrl`+`K`

# vispy.scene.cameras package

## Subpackages

- vispy.scene.cameras.tests package
  - Submodules
    - vispy.scene.cameras.tests.test_cameras module
    - vispy.scene.cameras.tests.test_link module
    - vispy.scene.cameras.tests.test_perspective module
  - Module contents

## Submodules

- vispy.scene.cameras.arcball module
  - `ArcballCamera`
- vispy.scene.cameras.base_camera module
  - `BaseCamera`
    - `BaseCamera.center`
    - `BaseCamera.depth_value`
    - `BaseCamera.flip`
    - `BaseCamera.fov`
    - `BaseCamera.get_state()`
    - `BaseCamera.interactive`
    - `BaseCamera.link()`
    - `BaseCamera.on_canvas_change()`
    - `BaseCamera.pre_transform`
    - `BaseCamera.reset()`
    - `BaseCamera.set_default_state()`
    - `BaseCamera.set_range()`
    - `BaseCamera.set_state()`
    - `BaseCamera.up`
    - `BaseCamera.view_changed()`
    - `BaseCamera.viewbox`
    - `BaseCamera.viewbox_key_event()`
    - `BaseCamera.viewbox_mouse_event()`
    - `BaseCamera.viewbox_resize_event()`
    - `BaseCamera.zoom_factor`
  - `nested_getattr()`
  - `nested_setattr()`
- vispy.scene.cameras.fly module
  - `FlyCamera`
    - `FlyCamera.auto_roll`
    - `FlyCamera.keymap`
    - `FlyCamera.on_timer()`
    - `FlyCamera.rotation`
    - `FlyCamera.rotation1`
    - `FlyCamera.rotation2`
    - `FlyCamera.viewbox_key_event()`
    - `FlyCamera.viewbox_mouse_event()`
- vispy.scene.cameras.magnify module
  - `Magnify1DCamera`
    - `Magnify1DCamera.transform_class`
  - `MagnifyCamera`
    - `MagnifyCamera.on_timer()`
    - `MagnifyCamera.transform_class`
    - `MagnifyCamera.view_changed()`
    - `MagnifyCamera.viewbox_mouse_event()`
    - `MagnifyCamera.viewbox_resize_event()`
- vispy.scene.cameras.panzoom module
  - `PanZoomCamera`
    - `PanZoomCamera.aspect`
    - `PanZoomCamera.center`
    - `PanZoomCamera.pan()`
    - `PanZoomCamera.rect`
    - `PanZoomCamera.viewbox_mouse_event()`
    - `PanZoomCamera.viewbox_resize_event()`
    - `PanZoomCamera.zoom()`
- vispy.scene.cameras.perspective module
  - `Base3DRotationCamera`
    - `Base3DRotationCamera.distance`
    - `Base3DRotationCamera.viewbox_mouse_event()`
  - `PerspectiveCamera`
    - `PerspectiveCamera.near_clip_distance`
    - `PerspectiveCamera.scale_factor`
    - `PerspectiveCamera.viewbox_mouse_event()`
    - `PerspectiveCamera.viewbox_resize_event()`
- vispy.scene.cameras.turntable module
  - `TurntableCamera`
    - `TurntableCamera.azimuth`
    - `TurntableCamera.elevation`
    - `TurntableCamera.orbit()`
    - `TurntableCamera.roll`

## Module contents

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

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

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

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

  Bases: `Base3DRotationCamera`

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

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

  Parameters:
    fov float

      Field of view. Zero (default) means orthographic projection.

    distance float | None

      The distance of the camera from the rotation point (only makes sense if fov > 0). If None (default) the distance is determined from the scale_factor and fov.

    translate_speed float

      Scale factor on translation speed when moving the camera center point.

    **kwargs dict

      Keyword arguments to pass to BaseCamera.

  Notes

  Interaction:

  > - LMB: orbits the view around its center point.

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

  > - SHIFT + LMB: translate the center point

  > - SHIFT + RMB: change FOV

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

  Bases: `Node`

  Base camera class.

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

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

  Parameters:
    interactive bool

      Whether the camera processes mouse and keyboard events.

    flip tuple of bools

      For each dimension, specify whether it is flipped.

    up{‘+z’, ‘-z’, ‘+y’, ‘-y’, ‘+x’, ‘-x’}

      The direction that is considered up. Default ‘+z’. Not all camera’s may support this (yet).

    parent Node

      The parent of the camera.

    name str

      Name used to identify the camera in the scene.

  property center

    The center location for this camera

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

  property depth_value

    The depth value to use in orthographic and perspective projection

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

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

  property flip
  property fov

    Field-of-view angle of the camera. If 0, the camera is in orthographic mode.

  get_state(props=None)

    Get the current view state of the camera

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

    Parameters:
      props list of strings | None

        List of properties to include in the returned dict. If None, all of camera state is returned.

  property interactive

    Boolean describing whether the camera should enable or disable user interaction.

  link(camera, props=None, axis=None)

    Link this camera with another camera of the same type

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

    Parameters:
      camera instance of Camera

        The other camera to link.

      props list of strings | tuple of strings | None

        List of camera state properties to keep in sync between the two cameras. If None, all of camera state is kept in sync.

      axis“x” | “y” | None

        An axis to link between two PanZoomCamera instances. If not None, view limits in the selected axis only will be kept in sync between the cameras.

  on_canvas_change(event)

    Canvas change event handler

    Parameters:
      event instance of Event

        The event.

  property pre_transform

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

  reset()

    Reset the view to the default state.

  set_default_state()

    Set the current state to be the default state to be applied when calling reset().

  set_range(x=None, y=None, z=None, margin=0.05)

    Set the range of the view region for the camera

    Parameters:
      x tuple | None

        X range.

      y tuple | None

        Y range.

      z tuple | None

        Z range.

      margin float

        Margin to use.

    Notes

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

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

  set_state(state=None, **kwargs)

    Set the view state of the camera

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

    Parameters:
      state dict

        The camera state.

      **kwargs dict

        Unused keyword arguments.

  property up

    The dimension that is considered up.

  view_changed()

    Called when this camera is changes its view. Also called when its associated with a viewbox.

  property viewbox

    The viewbox that this camera applies to.

  viewbox_key_event(event)

    The ViewBox key event handler

    Parameters:
      event instance of Event

        The event.

  viewbox_mouse_event(event)

    Viewbox mouse event handler

    Parameters:
      event instance of Event

        The event.

  viewbox_resize_event(event)

    The ViewBox resize handler to update the transform

    Parameters:
      event instance of Event

        The event.

  zoom_factor = 0.007

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

  Bases: `PerspectiveCamera`

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

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

  Parameters:
    fov float

      Field of view. Default 60.0.

    rotation float | None

      Rotation to use.

    **kwargs dict

      Keyword arguments to pass to BaseCamera.

  Notes

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

  Moving:

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

  > - F and C keys move up and down

  > - Space bar to brake

  Viewing:

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

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

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

  property auto_roll

    Whether to rotate the camera automaticall to try and attempt to keep Z up.

  property keymap

    A dictionary that maps keys to thruster directions

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

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

  on_timer(event)

    Timer event handler

    Parameters:
      event instance of Event

        The event.

  property rotation

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

  property rotation1

    rotation1 records confirmed camera rotation

  property rotation2

    rotation2 records on going camera rotation.

  viewbox_key_event(event)

    The ViewBox key event handler

    Parameters:
      event instance of Event

        The event.

  viewbox_mouse_event(event)

    The ViewBox mouse event handler

    Parameters:
      event instance of Event

        The event.

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

  Bases: `MagnifyCamera`

  Camera implementing a MagnifyTransform combined with PanZoomCamera.

  Parameters:
    size_factor float

      The size factor to use.

    radius_ratio float

      The radius ratio to use.

    **kwargs dict

      Keyword arguments to pass to PanZoomCamera and create a transform.

  Notes

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

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

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

  transform_class

    alias of `Magnify1DTransform`

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

  Bases: `PanZoomCamera`

  Camera implementing a MagnifyTransform combined with PanZoomCamera.

  Parameters:
    size_factor float

      The size factor to use.

    radius_ratio float

      The radius ratio to use.

    **kwargs dict

      Keyword arguments to pass to PanZoomCamera and create a transform.

  Notes

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

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

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

  on_timer(event=None)

    Timer event handler

    Parameters:
      event instance of Event

        The timer event.

  transform_class

    alias of `MagnifyTransform`

  view_changed()

    Called when this camera is changes its view. Also called when its associated with a viewbox.

  viewbox_mouse_event(event)

    The ViewBox mouse event handler

    Parameters:
      event instance of Event

        The mouse event.

  viewbox_resize_event(event)

    The ViewBox resize event handler

    Parameters:
      event instance of Event

        The viewbox resize event.

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

  Bases: `BaseCamera`

  Camera implementing 2D pan/zoom mouse interaction.

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

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

  Parameters:
    rect Rect

      A Rect object or 4-element tuple that specifies the rectangular area to show.

    aspect float | None

      The aspect ratio (i.e. scaling) between x and y dimension of the scene. E.g. to show a square image as square, the aspect should be 1. If None (default) the x and y dimensions are scaled independently.

    **kwargs dict

      Keyword arguments to pass to BaseCamera.

  Notes

  Interaction:

  > - LMB: pan the view

  > - RMB or scroll: zooms the view

  property aspect

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

  property center

    The center location for this camera

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

  pan(*pan)

    Pan the view.

    Parameters:
      *pan length-2 sequence

        The distance to pan the view, in the coordinate system of the scene.

  property rect

    The rectangular border of the ViewBox visible area.

    This is expressed in the coordinate system of the scene. See `Rect` for different ways this can be specified.

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

  viewbox_mouse_event(event)

    The SubScene received a mouse event; update transform accordingly.

    Parameters:
      event instance of Event

        The event.

  viewbox_resize_event(event)

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

    Parameters:
      event instance of Event

        The event.

  zoom(factor, center=None)

    Zoom in (or out) at the given center

    Parameters:
      factor float or tuple

        Fraction by which the scene should be zoomed (e.g. a factor of 2 causes the scene to appear twice as large).

      center tuple of 2-4 elements

        The center of the view. If not given or None, use the current center.

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

  Bases: `Base3DRotationCamera`

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

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

  When `elevation` and `azimuth` are set to 0, the camera points along the +y axis.

  Parameters:
    fov float

      Field of view. 0.0 means orthographic projection, default is 45.0 (some perspective)

    elevation float

      Elevation angle in degrees. The elevation angle represents a rotation of the camera around the current scene x-axis. The camera points along the x-y plane when the angle is 0.

    azimuth float

      Azimuth angle in degrees. The azimuth angle represents a rotation of the camera around the scene z-axis according to the right-hand screw rule. The camera points along the y-z plane when the angle is 0.

    roll float

      Roll angle in degrees. The roll angle represents a rotation of the camera around the current scene y-axis.

    distance float | None

      The distance of the camera from the rotation point (only makes sense if fov > 0). If None (default) the distance is determined from the scale_factor and fov.

    translate_speed float

      Scale factor on translation speed when moving the camera center point.

    **kwargs dict

      Keyword arguments to pass to BaseCamera.

  Notes

  Interaction:

  > - LMB: orbits the view around its center point.

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

  > - SHIFT + LMB: translate the center point

  > - SHIFT + RMB: change FOV

  property azimuth

    Get the camera azimuth angle in degrees.

    The camera points along the y-z plane when the angle is 0.

  property elevation

    Get the camera elevation angle in degrees.

    The camera points along the x-y plane when the angle is 0.

  orbit(azim, elev)

    Orbits the camera around the center position.

    Parameters:
      azim float

        Angle in degrees to rotate horizontally around the center point.

      elev float

        Angle in degrees to rotate vertically around the center point.

  property roll

    Get the camera roll angle in degrees.