lib

Interface to pygfx and wgpu.

Camera()	Abstract base camera.
Controller([camera, enabled, damping, ...])	The base camera controller.
Scene([environment])	Root of the scene graph.
Viewport(renderer[, rect])	A rectangular area on a renderer.

Camera

class fury.lib.Camera

Bases: WorldObject

Abstract base camera.

Camera’s are world objects and can be placed in the scene, but this is not required.

The purpose of a camera is to define the viewpoint for rendering a scene. This viewpoint consists of its position and orientation (in the world) and its projection.

In other words, it covers the projection of world coordinates to normalized device coordinates (NDC), by the (inverse of) the camera’s own world matrix and the camera’s projection transform. The former represent the camera’s position, the latter is specific to the type of camera.

__init__()

camera_matrix

Cache for computed properties.

This descriptor implements a minimal timestamp-based cache for computed properties. The value of the property is computed using compute_fn and the result is cached until obj.last_modified advances. At this point the value of the computed property is recomputed upon the next read.

clear_view_offset()

Remove the currently set view offset, returning to a normal view.

flag_update()

get_state()

Get the state of the camera as a dict.

property last_modified: int

projection_matrix

Cache for computed properties.

This descriptor implements a minimal timestamp-based cache for computed properties. The value of the property is computed using compute_fn and the result is cached until obj.last_modified advances. At this point the value of the computed property is recomputed upon the next read.

projection_matrix_inverse

Cache for computed properties.

This descriptor implements a minimal timestamp-based cache for computed properties. The value of the property is computed using compute_fn and the result is cached until obj.last_modified advances. At this point the value of the computed property is recomputed upon the next read.

set_state(state)

Set the state of the camera from a dict.

set_view_offset(full_width: float, full_height: float, x: float, y: float, width: float, height: float)

Set the offset in a larger viewing frustrum and override the logical size.

This is useful for advanced use-cases such as multi-window setups or taking tiled screenshots. It is the responsibility of the caller to make sure that the ratio of the width and height match that of the canvas/viewport being rendered to, so that the effective pixel_ratio is isotropic.

# Assuming a canvas with a logical size of 640x480 ...

# Use a custom logical size
camera.set_view_offset(320, 240, 0, 0, 320, 240)

# Render the bottom-left corner, sizes in screen-space become larger (relative to the screen)
camera.set_view_offset(640, 480, 0, 240, 320, 240)

# Render the bottom-left corner, sizes in screen-space stay the same (relative to the screen)
camera.set_view_offset(1280, 960, 0, 480, 640, 480)

Parameters:

• (float) (height)

• (float)

• (float)

• (float)

• (float)

• (float)

set_view_size(width, height)

Sets the logical size of the target. Set by the renderer; you should typically not use this.

property view_matrix: ndarray

Controller

class fury.lib.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)

__init__(camera=None, *, enabled=True, damping=4, auto_update=True, register_events=None)

add_camera(camera, *, include_state=None, exclude_state=None)

Add a camera to control.

If the camera is already registered, it only updates the include_state and exclude_state (without changing the order of the cameras).

The include_state and exclude_state arguments represent the camera state fields to include/exclude, when updating this camera. This can be used to “partially link” a camera. These args are None by default (i.e. no filtering).

See camera.get_state() for available fields. Useful state names for the perspective and orthographhic camera are: ‘x’, ‘y’, ‘z’ (or ‘position’ for all three), ‘width’, ‘height’, ‘rotation’, ‘zoom’, and ‘depth_range’.

add_default_event_handlers(*args)

property auto_update

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

property cameras

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

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.

property damping

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

property enabled

Whether the controller responds to events.

handle_event(event, viewport)

pause()

Context manager to temporarily disable the controller. Controller is set back to the original enabled/disabled state when leaving the context.

Usage

with controller.pause():

# do things while controller.enabled is False

# outside context manager, controller.enabled is set back to the original value

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.

register_events(viewport_or_renderer: Viewport | Renderer)

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

remove_camera(camera)

Remove a camera from the list of cameras to control.

If the camera is not registered, this does nothing.

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.

update_camera(*args)

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.

Scene

class fury.lib.Scene(environment=None, *args, **kwargs)

Bases: Group

Root of the scene graph.

The scene holds scene-level information (background color, fog, environment map) as well as all objects that take part in the rendering process as either direct or indirect children/nested objects.

Parameters:

environment (Texture | TextureMap) – The environment map for all physical materials in the scene. However, it’s not possible to overwrite an existing map assigned to individual materials. Default is None.

__init__(environment=None, *args, **kwargs)

property environment

The environment map for all physical materials in the scene. If a material has its own environment map set, it will override the scene’s environment map.

Viewport

class fury.lib.Viewport(renderer, rect=None)

Bases: object

A rectangular area on a renderer.

Parameters:

• renderer (Renderer) – The renderer on which the viewport should be defined.

• rect (tuple, [4]) – The viewport rect (x, y, w, h). If None, it is set to the full size of the renderer’s canvas.

__init__(renderer, rect=None)

classmethod from_viewport_or_renderer(x)

Convenience method. Some parts of pygfx that accept a viewport might just as well accept a renderer.

is_inside(x, y)

Get whether the given position is inside the viewport rect.

property logical_size

The logical size of the rectangular area described by this viewport.

property rect

The viewport rect (x, y, w, h). Can be set to None to set it to the full renderer size.

render(scene, camera, flush=False)

A shorthand for renderer.render(scene, camera) at the appropriate viewport. Does not flush by default.

property renderer

A reference to the renderer that this is a viewport of.