pygfx.controllers.Controller

class pygfx.controllers.Controller(camera=None, *, enabled=True, damping=4, auto_update=True, register_events=None)

Bases: object

The base camera controller.

The purpose of a controller is to provide an API to control a camera, and to convert user (mouse) events into camera adjustments.

Parameters:

  • camera (Camera) – The camera to control (optional). Must be a perspective or orthographic camera.

  • enabled (bool) – Whether the controller is enabled (i.e. responds to events).

  • damping (float) – The amount of motion damping. Zero is no damping, 10 a lot. Default 4.

  • auto_update (bool) – When True (default), the controller is pretty much plug-and-play. For more control, it can be set to False. The controller will then not update the cameras automatically, and will not request new draws. You will then need to periodically call tick(), and use the return value (a camera state dict).

  • register_events (Renderer or Viewport) – If given and not None, will call .register_events().

  • Usage –

  • ----- –

  • used. (There are multiple ways that the controller can be) –

  • and (The easiest (and most common) approach is to use the pygfx event system) –

  • register_events). (make the controller listen to viewport events (using) –

  • handle_event() (An alternative is to feed your own events into the) –

  • objects. (method. You'd have to mimic or use pygfx event) –

  • methods" (The controller can also be used programmatically by calling "action) –

  • pan() (like) –

  • rotate(). (zoom() and) –

property cameras

A tuple with the cameras under control, in the order that they were added.

add_camera(camera)

Add a camera to control.

remove_camera(camera)

Remove a camera from the list of cameras to control.

property enabled

Whether the controller responds to events.

property damping

The amount of motion damping (i.e. smoothing). Lower values dampen less. Typical values would be below 10.

property auto_update

Whether the controller automatically requests a new draw at the canvas.

property controls

A dictionary that maps buttons/keys to actions. Can be modified to configure how the controller reacts to events.

Possible keys include ‘mouse1’ to ‘mouse5’, single characters for the corresponding key presses, and ‘arrowleft’, ‘arrowright’, ‘arrowup’, ‘arrowdown’, ‘tab’, ‘enter’, ‘escape’, ‘backspace’, and ‘delete’.

Each action value is a tuple with 3 fields:

  • The action name, e.g. ‘pan’, see controller.controls.action_names for the possible names.

  • The mode: ‘drag’, ‘push’, ‘peek’, ‘repeat’. Drag represents mouse drag, push means the action is performed as the key is pushed, peek means that the action is undone once the key is released, and repeat means that while the key is held down, the value updates with the given amount per second.

  • The multiplier is the value that the set value from the event is multiplied with.

register_events(viewport_or_renderer: Viewport | Renderer)

Apply the default interaction mechanism to a wgpu autogui canvas. Needs either a viewport or renderer.

tick()

Should be called periodically to keep the camera up to date.

If auto_update is True, this is done automatically. Returns a dict with the new camera state, or None if there are no running actions.

quickzoom(delta: float, *, animate=False)

Zoom the view using the camera’s zoom property. This is intended for temporary zoom operations.

If animate is True, the motion is damped. This requires the controller to receive events from the renderer/viewport.

update_fov(delta, *, animate)

Adjust the field of view with the given delta value (Limited to [1, 179]).

If animate is True, the motion is damped. This requires the controller to receive events from the renderer/viewport.