vispy.scene.cameras package

Subpackages

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

Submodules

• vispy.scene.cameras.arcball module
• vispy.scene.cameras.base_camera module
• vispy.scene.cameras.fly module
• vispy.scene.cameras.magnify module
• vispy.scene.cameras.panzoom module
• vispy.scene.cameras.perspective module
• vispy.scene.cameras.turntable module

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: vispy.scene.cameras.perspective.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: vispy.scene.node.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(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

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)

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: vispy.scene.cameras.perspective.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)

ViewBox key event handler

Parameters

eventinstance of Event

The event.

viewbox_mouse_event(event)

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: vispy.scene.cameras.magnify.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 vispy.visuals.transforms.nonlinear.Magnify1DTransform

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

Bases: vispy.scene.cameras.panzoom.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 vispy.visuals.transforms.nonlinear.MagnifyTransform

view_changed()

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

viewbox_mouse_event(event)

ViewBox mouse event handler

Parameters

eventinstance of Event

The mouse event.

viewbox_resize_event(event)

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: vispy.scene.cameras.base_camera.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, expressed in the coordinate system of the scene.

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: vispy.scene.cameras.perspective.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.

elevationfloat

Elevation angle in degrees. Positive angles place the camera above the cente point, negative angles place the camera below the center point.

azimuthfloat

Azimuth angle in degrees. Zero degrees places the camera on the positive x-axis, pointing in the negative x direction.

rollfloat

Roll angle in degrees

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

The angle of the camera in degrees around the y axis. An angle of 0 places the camera within the (y, z) plane.

property elevation

The angle of the camera in degrees above the horizontal (x, z) plane.

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

The angle of the camera in degrees around the z axis. An angle of 0 places puts the camera upright.

vispy.scene package vispy.scene.cameras.tests package