window

FURY window module.

This module provides functionality for creating and managing rendering windows using PyGfx. It includes classes and functions for handling scenes, cameras, controllers, and rendering multiple screens.

Scene(*[, background, skybox, lights])	Scene class to hold the actors in the scene.
Screen(viewport, scene, camera, controller)	Define an independent viewport within the window.
ShowManager(*[, renderer, scene, camera, ...])	Show manager for the rendering window.
add_ui_to_scene(ui_scene, ui_obj)	Recursively traverse and add UI hierarchy to the UI scene.
remove_ui_from_scene(ui_scene, ui_obj)	Recursively traverse and remove UI hierarchy from the UI scene.
create_screen(renderer, *[, rect, scene, ...])	Compose a Screen object with viewport, scene, camera, and controller.
update_camera(camera, size, target)	Update the camera's view to encompass the target object or scene.
set_camera_from_axis(screen, axis_direction)	Set camera based on the axis direction proposed.
update_viewports(screens, screen_bbs)	Update the bounding boxes and cameras of multiple screens.
render_screens(renderer, screens[, stats, ...])	Render multiple screens within a single renderer update cycle.
reposition_ui(screens)	Update the positions of all UI elements across multiple screens.
calculate_screen_sizes(screens, size)	Calculate screen bounding boxes based on a layout configuration.
snapshot(*[, scene, screen_config, fname, ...])	Take a snapshot using an offscreen window.
analyze_snapshot(im, *[, colors, ...])	Analyze snapshot from memory or file.
show(actors, *[, window_type])	Display one or more actors in a new window quickly.

Scene

class fury.window.Scene(*, background=(0, 0, 0, 1), skybox=None, lights=None)

Bases: Group

Scene class to hold the actors in the scene.

Data Structure to arrange the logical and spatial representation of the actors in the graphical scene. It is a subclass of PyGfx Scene class. It holds the background color and skybox texture. It also holds the lights in the scene. The background color and skybox texture can be set using the background property. The lights can be set using the lights property. The scene can be cleared using the clear method. The scene can be rendered using the render method.

Parameters:

• background (tuple, optional) – The background color of the scene. It is a tuple of 4 floats (R, G, B, A).

• skybox (Texture, optional) – The skybox texture of the scene. It is a PyGfx Texture object.

• lights (list of Light, optional) – The lights in the scene. It is a list of PyGfx Light objects. If None, a default AmbientLight is added.

__init__(*, background=(0, 0, 0, 1), skybox=None, lights=None)

Arrange the logical and spatial representation of actors.

This class acts as a scene graph container, managing actors, background, and lighting for rendering.

add(*objects)

Add actors or UI elements to the scene.

Parameters:

*objects (list of Mesh or UI) – A list objects to be added to the scene.

property background

Get the background color of the scene.

Returns:

The current background color as an (R, G, B, A) tuple.

Return type:

tuple

clear()

Remove all actors from the scene, keeping background and lights.

remove(*objects)

Remove actors or UI elements from the scene.

Parameters:

*objects (list of Mesh or UI) – A list of objects to be removed from the scene.

set_skybox(cube_map)

Set a skybox as the scene background using a cubemap texture.

This replaces the current background actor (color or skybox) with a new skybox background.

Parameters:

cube_map (Texture) – A PyGfx Texture object (cubemap) for the skybox.

Screen

class fury.window.Screen(viewport: Viewport, scene: Scene, camera: Camera, controller: Controller)

Bases: object

Define an independent viewport within the window.

Holds a scene graph, camera, and controller for rendering actors within a specific rectangular area of the window.

__init__(viewport: Viewport, scene: Scene, camera: Camera, controller: Controller) → None

property bounding_box

Get the bounding box of the screen viewport within the window.

Returns:

The position and size (x, y, w, h) of the viewport.

Return type:

tuple

camera: Camera

controller: Controller

property position

Get the position of the screen viewport within the window.

Returns:

The x and y coordinates (x, y) of the viewport’s top-left corner.

Return type:

tuple

scene: Scene

property size

Get the size of the screen viewport.

Returns:

The width and height (w, h) of the viewport in pixels.

Return type:

tuple

viewport: Viewport

ShowManager

class fury.window.ShowManager(*, renderer=None, scene=None, camera=None, controller=None, title='FURY 2.0', size=(800, 800), window_type='default', pixel_ratio=1.25, camera_light=True, screen_config=None, enable_events=True, qt_app=None, qt_parent=None, show_fps=False, max_fps=60, imgui=False, imgui_draw_function=None)

Bases: object

Show manager for the rendering window.

It manages the rendering of the scene(s) in the window. It also handles the events from the window and the controller.

Parameters:

• renderer (Renderer) – The PyGfx Renderer object associated with the window.

• scene (Scene) – The scene graph to be rendered in the window.

• camera (Camera) – The PyGfx camera used to view the scene.

• controller (Controller) – The PyGfx controller for camera interaction.

• title (str) – The title of the window.

• size (tuple) – The size (width, height) of the window in pixels.

• window_type (str) – The type of window canvas to create (‘default’, ‘qt’, ‘jupyter’, ‘offscreen’).

• pixel_ratio (float) – The ratio between render buffer and display buffer pixels.

• camera_light (bool) – Whether to attach a DirectionalLight to the camera.

• screen_config (list) – Defines the screen layout. Can be a list of integers (vertical/horizontal sections) or a list of explicit bounding box tuples (x, y, w, h).

• enable_events (bool) – Whether to enable mouse and keyboard interactions initially.

• qt_app (QApplication) – An existing QtWidgets QApplication instance (if window_type is ‘qt’).

• qt_parent (QWidget) – An existing QWidget to embed the QtCanvas within (if window_type is ‘qt’).

• show_fps (bool) – Whether to display FPS statistics using an on-screen overlay.

• max_fps (int) – Maximum frames per second for the canvas.

• imgui (bool, optional) – Whether to enable ImGui UI rendering support.

• imgui_draw_function (callable, optional) – A function that updates the ImGui UI elements each frame.

__init__(*, renderer=None, scene=None, camera=None, controller=None, title='FURY 2.0', size=(800, 800), window_type='default', pixel_ratio=1.25, camera_light=True, screen_config=None, enable_events=True, qt_app=None, qt_parent=None, show_fps=False, max_fps=60, imgui=False, imgui_draw_function=None)

Manage the rendering window, scenes, and interactions.

Handles window creation, screen layout, rendering loop, and event handling.

property app

Get the associated QApplication instance, if any.

Returns:

The QApplication instance if the window type is ‘qt’, otherwise None.

Return type:

QApplication or None

property callbacks

Get the registered callbacks.

This only returns the callbacks that are set to repeat.

Returns:

A dictionary of registered callbacks with their names as keys.

Return type:

dict

cancel_callback(name)

Cancel a registered callback by its name.

Parameters:

name (str) – The unique name of the callback to cancel.

cancel_resize_callback()

Cancel the window resize callback function.

close()

Close the rendering window and terminate the application if necessary.

property device

Get the underlying GPU device from the renderer.

Returns:

The GPU device used by the renderer for rendering operations.

Return type:

wgpu.GPUDevice

disable_imgui()

Disable ImGui UI rendering support.

enable_imgui(*, imgui_draw_function=None)

Enable ImGui UI rendering support.

Parameters:

imgui_draw_function (callable, optional) – A function that updates the ImGui UI elements each frame. If None, no UI update function is set initially.

get_fps()

Get the current FPS from the stats overlay if available.

Returns:

The current FPS value, or None if stats are not initialized or FPS has not been computed yet.

Return type:

int or None

property imgui

Get the ImGui UI renderer if enabled.

Returns:

The UIRenderer instance if ImGui is enabled, otherwise None.

Return type:

UIRenderer or None

property pixel_ratio

Get the current pixel ratio of the renderer.

Returns:

The ratio between render buffer and display buffer pixels.

Return type:

float

register_callback(func, time, repeat, name, *args)

Register a callback function to be called after a time interval.

Parameters:

• func (callable) – The function to be called.

• time (float) – The time interval in seconds after which the function is called.

• repeat (bool) – If True, the function is called repeatedly every time seconds. If False, it is called only once.

• name (str) – A unique name for the callback.

• *args (tuple) – Additional arguments to pass to the function.

render()

Request a redraw of all screens in the window.

resize_callback(func)

Set a callback function to be called on window resize events.

Parameters:

func (callable) – A function that takes a single argument (size tuple) and is called whenever the window is resized.

set_enable_events(value)

Enable or disable mouse and keyboard interactions for all screens.

Parameters:

value (bool) – Set to True to enable events, False to disable them.

set_imgui_render_callback(imgui_draw_function)

Set the ImGui rendering callback function.

Parameters:

imgui_draw_function (callable) – A function that updates the ImGui UI elements each frame.

show_axes_gizmo(*, screen=0, size=30, thickness=2, position=None, labels=None, click_callback=None)

Add an axes helper to the first screen for orientation reference.

Parameters:

• screen (int, optional) – Index of the screen whose viewport should host the gizmo. If None, defaults to 0 (the first screen). If the index is out of bounds, it will be clamped to the valid range of available screens.

• size (float, optional) – The length of the axes lines.

• thickness (float, optional) – The thickness of the axes lines.

• position (tuple, optional) – The (x, y) position of the axes helper in screen coordinates. If None, it defaults to (60, 60) pixels from the bottom-left corner. The position is relative to the screen’s viewport, not the entire window. The origin is bottom-left of the screen viewport.

• labels (list of str, optional) – Custom labels for the axes. Defaults to [“-X”, “+X”, “-Y”, “+Y”, “-Z”, “+Z”] if None.

• click_callback (callable, optional) – A function to be called when an axis disk or label is clicked. The function should accept a single argument, which will be the axis direction vector corresponding to the clicked axis.

property size

Get the current size of the window.

Returns:

The current (width, height) of the window in logical pixels.

Return type:

tuple

snapshot(fname)

Save a snapshot of the current rendered content to a file.

The window must have been rendered at least once before calling this.

Parameters:

fname (str) – The file path (including extension, e.g., ‘image.png’) where the snapshot will be saved.

Returns:

A NumPy array representing the captured image data (RGBA).

Return type:

ndarray

start()

Start the rendering event loop and display the window.

This call blocks until the window is closed, unless running in an offscreen or specific environment (like FURY_OFFSCREEN).

property title

Get the current window title.

Returns:

The text displayed in the window’s title bar.

Return type:

str

add_ui_to_scene

fury.window.add_ui_to_scene(ui_scene, ui_obj)

Recursively traverse and add UI hierarchy to the UI scene.

Parameters:

• ui_scene (GfxScene) – Scene dedicated to UI elements.

• ui_obj (UI) – UI element to add into scene.

remove_ui_from_scene

fury.window.remove_ui_from_scene(ui_scene, ui_obj)

Recursively traverse and remove UI hierarchy from the UI scene.

Parameters:

• ui_scene (GfxScene) – Scene dedicated to UI elements.

• ui_obj (UI) – UI element to be removed from the scene.

create_screen

fury.window.create_screen(renderer, *, rect=None, scene=None, camera=None, controller=None, camera_light=True)

Compose a Screen object with viewport, scene, camera, and controller.

Parameters:

• renderer (Renderer) – The PyGfx Renderer object associated with the window.

• rect (tuple, optional) – The bounding box (x, y, w, h) for the screen’s viewport. If None, the viewport covers the entire renderer area initially. Defaults to None.

• scene (Scene, optional) – The scene graph to be rendered in this screen. If None, a new empty Scene is created. Defaults to None.

• camera (Camera, optional) – The PyGfx camera used to view the scene. If None, a PerspectiveCamera is created. Defaults to None.

• controller (Controller, optional) – The PyGfx controller for camera interaction. If None, an OrbitController is created and associated with the camera and viewport. Defaults to None.

• camera_light (bool, optional) – If True, attach a DirectionalLight to the camera. Defaults to True.

Returns:

A configured Screen object ready for rendering.

Return type:

Screen

update_camera

fury.window.update_camera(camera, size, target)

Update the camera’s view to encompass the target object or scene.

If the target is a non-empty scene or another object, the camera adjusts to show it. If the target is an empty scene, the camera’s aspect ratio is updated based on the provided size.

Parameters:

• camera (Camera) – The PyGfx camera object to update.

• size (tuple) – The size (width, height) of the viewport, used if the target is empty.

• target (Object or Scene) – The PyGfx object or scene the camera should focus on.

set_camera_from_axis

fury.window.set_camera_from_axis(screen, axis_direction)

Set camera based on the axis direction proposed.

This method will preserves the distance it actually had from the center of the scene. It will only move the camera to the new angle based on the direction.

Parameters:

• screen (Screen) – Screen in which the camera needs to be updated.

• axis_direction (tuple or ndarray) – The axis direction to set the camera to from the center of the scene.

update_viewports

fury.window.update_viewports(screens, screen_bbs)

Update the bounding boxes and cameras of multiple screens.

Parameters:

• screens (list of Screen) – The list of Screen objects to update.

• screen_bbs (list of tuple) – A list of bounding boxes (x, y, w, h), one for each screen in screens.

render_screens

fury.window.render_screens(renderer, screens, stats=None, is_dirty=False)

Render multiple screens within a single renderer update cycle.

Parameters:

• renderer (Renderer) – The PyGfx Renderer object to draw into.

• screens (list of Screen) – The list of Screen objects to render.

• stats (Stats, optional) – Stats helper to display FPS overlay.

• is_dirty (bool, optional) – If True, triggers layout recalculations for UI elements.

reposition_ui

fury.window.reposition_ui(screens)

Update the positions of all UI elements across multiple screens.

Parameters:

screens (list of Screen) – The list of Screen objects containing UI elements to reposition.

calculate_screen_sizes

fury.window.calculate_screen_sizes(screens, size)

Calculate screen bounding boxes based on a layout configuration.

The screens list defines vertical sections, and each element within specifies the number of horizontal sections in that vertical column.

Parameters:

• screens (list of int or list of tuple or None) – Layout configuration. If a list of integers is provided, each integer represents a vertical column and specifies the number of horizontal rows within it based on the size. If a list of tuples is provided, and each tuple has 4 elements, they are treated as explicit bounding boxes (x, y, w, h) for each screen. regardless of the size parameter. If None or empty, assumes a single screen covering the full size.

• size (tuple) – The total size (width, height) of the window or area to divide.

Returns:

A list of calculated bounding boxes (x, y, w, h) for each screen.

Return type:

list of tuple

snapshot

fury.window.snapshot(*, scene=None, screen_config=None, fname='output.png', actors=None, return_array=False)

Take a snapshot using an offscreen window.

Creates a temporary offscreen ShowManager, renders the scene(s), saves the image, and optionally returns the image data.

Parameters:

• scene (Scene or list of Scene, optional) – The scene(s) to render. If actors is provided, this is ignored. Defaults to None.

• screen_config (list, optional) – Screen layout configuration (see ShowManager). Defaults to None (single screen).

• fname (str, optional) – The file path to save the snapshot image. Defaults to “output.png”.

• actors (Object or list of Object, optional) – Convenience parameter. If provided, a new Scene is created containing these actors, and the scene parameter is ignored. Defaults to None.

• return_array (bool, optional) – If True, the function returns the image data as a NumPy array in addition to saving the file. Defaults to False.

Returns:

If return_array is True, returns the RGBA image data as a NumPy array. Otherwise, returns None.

Return type:

ndarray or None

analyze_snapshot

fury.window.analyze_snapshot(im, *, colors=None, find_objects=True, strel=None)

Analyze snapshot from memory or file.

Parameters:

• im (str or array) – If string then the image is read from a file otherwise the image is read from a numpy array. The array is expected to be of shape (X, Y, 3) or (X, Y, 4) where the last dimensions are the RGB or RGBA values.

• colors (tuple or list of tuples, optional) – List of colors to search in the image.

• find_objects (bool, optional) – If True it will calculate the number of objects that are different from the background and return their position in a new image.

• strel (2d array, optional) – Structure element to use for finding the objects of size (3, 3).

Returns:

This is an object with attributes like colors_found that give information about what was found in the current snapshot array im.

Return type:

ReportSnapshot

show

fury.window.show(actors, *, window_type='default')

Display one or more actors in a new window quickly.

A convenience function to quickly visualize actors without manually setting up a Scene or ShowManager.

Parameters:

• actors (Object or list of Object) – The PyGfx actor(s) to display.

• window_type (str, optional) – The type of window canvas to create (‘default’, ‘glfw’, ‘qt’, ‘jupyter’, ‘offscreen’). Defaults to ‘default’.