vispy.scene.cameras package#

Subpackages#

Submodules#

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:
fovfloat

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

distancefloat | None

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

translate_speedfloat

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

**kwargsdict

Keyword arguments to pass to BaseCamera.

Notes

Interaction:

  • LMB: orbits the view around its center point.

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

  • SHIFT + LMB: translate the center point

  • SHIFT + RMB: change FOV

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

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:
interactivebool

Whether the camera processes mouse and keyboard events.

fliptuple of bools

For each dimension, specify whether it is flipped.

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

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

parentNode

The parent of the camera.

namestr

Name used to identify the camera in the scene.

property center#

The center location for this camera

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

property depth_value#

The depth value to use in orthographic and perspective projection

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

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

property 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:
propslist of strings | None

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

property interactive#

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

Link this camera with another camera of the same type

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

Parameters:
camerainstance of Camera

The other camera to link.

propslist of strings | tuple of strings | None

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

axis“x” | “y” | None

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

on_canvas_change(event)#

Canvas change event handler

Parameters:
eventinstance of Event

The event.

property pre_transform#

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

reset()#

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:
xtuple | None

X range.

ytuple | None

Y range.

ztuple | None

Z range.

marginfloat

Margin to use.

Notes

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

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

set_state(state=None, **kwargs)#

Set the view state of the camera

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

Parameters:
statedict

The camera state.

**kwargsdict

Unused keyword arguments.

property up#

The dimension that is considered up.

view_changed()#

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:
eventinstance of Event

The event.

viewbox_mouse_event(event)#

Viewbox mouse event handler

Parameters:
eventinstance of Event

The event.

viewbox_resize_event(event)#

The ViewBox resize handler to update the transform

Parameters:
eventinstance 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:
fovfloat

Field of view. Default 60.0.

rotationfloat | None

Rotation to use.

**kwargsdict

Keyword arguments to pass to BaseCamera.

Notes

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

Moving:

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

  • F and C keys move up and down

  • Space bar to brake

Viewing:

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

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

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

property auto_roll#

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

property keymap#

A dictionary that maps keys to thruster directions

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

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

on_timer(event)#

Timer event handler

Parameters:
eventinstance of Event

The event.

property rotation#

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

property rotation1#

rotation1 records confirmed camera rotation

property rotation2#

rotation2 records on going camera rotation.

viewbox_key_event(event)#

The ViewBox key event handler

Parameters:
eventinstance of Event

The event.

viewbox_mouse_event(event)#

The ViewBox mouse event handler

Parameters:
eventinstance 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_factorfloat

The size factor to use.

radius_ratiofloat

The radius ratio to use.

**kwargsdict

Keyword arguments to pass to PanZoomCamera and create a transform.

Notes

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

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

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

transform_class#

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_factorfloat

The size factor to use.

radius_ratiofloat

The radius ratio to use.

**kwargsdict

Keyword arguments to pass to PanZoomCamera and create a transform.

Notes

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

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

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

on_timer(event=None)#

Timer event handler

Parameters:
eventinstance 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:
eventinstance of Event

The mouse event.

viewbox_resize_event(event)#

The ViewBox resize event handler

Parameters:
eventinstance of Event

The viewbox resize event.

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

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:
rectRect

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

aspectfloat | None

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

**kwargsdict

Keyword arguments to pass to BaseCamera.

Notes

Interaction:

  • LMB: pan the view

  • RMB or scroll: zooms the view

property aspect#

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

property center#

The center location for this camera

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

pan(*pan)#

Pan the view.

Parameters:
*panlength-2 sequence

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

property rect#

The rectangular border of the ViewBox visible area.

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:
eventinstance of Event

The event.

viewbox_resize_event(event)#

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

Parameters:
eventinstance of Event

The event.

zoom(factor, center=None)#

Zoom in (or out) at the given center

Parameters:
factorfloat or tuple

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

centertuple of 2-4 elements

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

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

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:
fovfloat

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

elevationfloat

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.

azimuthfloat

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.

rollfloat

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

distancefloat | None

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

translate_speedfloat

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

**kwargsdict

Keyword arguments to pass to BaseCamera.

Notes

Interaction:

  • LMB: orbits the view around its center point.

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

  • SHIFT + LMB: translate the center point

  • SHIFT + RMB: change FOV

property azimuth#

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:
azimfloat

Angle in degrees to rotate horizontally around the center point.

elevfloat

Angle in degrees to rotate vertically around the center point.

property roll#

Get the camera roll angle in degrees.