scenex.adaptors#
scenex.adaptors
#
Backend adaptors that translate scenex models into graphics library calls.
Adaptors bridge the gap between scenex's declarative models and rendering backends
(e.g. pygfx). For each model class in scenex.model, there should be a corresponding
adaptor class for each backend that handles the actual GPU rendering.
When you call scenex.show(), adaptors are automatically created for each object
in your scene graph. The adaptors translate model properties (colors, transforms,
data) into backend-specific commands. As you modify the models, events trigger updates
in the adaptors to keep the rendered scene synced.
Architecture
The adaptor system uses a registry pattern::
Model (declarative) → Adaptor (imperative) → Backend (GPU library)
Image model → ImageAdaptor → pygfx.Mesh + texture
or
→ ImageAdaptor → vispy.scene.Image
Each backend (pygfx, vispy) has its own set of adaptors implementing the same model-to-native translation logic tailored to that backend's API.
Main Components
- AdaptorRegistry: Maps model classes to adaptor classes
- Adaptor: Base class for all adaptors, handles event subscription
- Backend-specific adaptors: In _pygfx and _vispy subpackages
Supported Backends
pygfx (WebGPU-based): - Modern GPU API with advanced rendering features vispy (OpenGL-based): - Mature, widely-supported OpenGL renderer
See Also
scenex.model : Declarative model classes scenex.use : Function to select rendering backend scenex.show : Function that creates adaptors
Classes:
-
Adaptor–ABC for backend adaptor classes.
-
AdaptorRegistry–Weak registry for Adaptor objects.
Functions:
-
get_adaptor_registry–Get the backend adaptor registry.
-
get_all_adaptors–Get all loaded adaptors for the given object.
-
use–Set the graphics backend for rendering scenex visualizations.
Adaptor
#
Adaptor(obj: TModel)
Bases: ABC, Generic[TModel, TNative]
flowchart TD
scenex.adaptors.Adaptor[Adaptor]
click scenex.adaptors.Adaptor href "" "scenex.adaptors.Adaptor"
ABC for backend adaptor classes.
An adaptor converts model change events into into native calls for the given backend.
All backend adaptor objects receive the object they are adapting.
Methods:
-
handle_event–Receive info from psygnal callback and convert to adaptor call.
Source code in src/scenex/adaptors/_base.py
43 44 45 | |
handle_event
#
handle_event(info: EmissionInfo) -> None
Receive info from psygnal callback and convert to adaptor call.
Source code in src/scenex/adaptors/_base.py
47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 | |
AdaptorRegistry
#
AdaptorRegistry()
Weak registry for Adaptor objects.
Each backend should subclass this and implement the get_adaptor_class method.
And expose an instance of the subclass as adaptors in the top level of the backend
module.
Methods:
-
all–Return an iterator over all adaptors in the registry.
-
create_adaptor–Create a new adaptor for the given model object.
-
get_adaptor–Get the adaptor for the given model object, create if
createis True. -
get_adaptor_class–Return the adaptor class for the given model object.
-
initialize_adaptor–Initialize the adaptor for the given model object.
-
validate_adaptor_class–Validate that the given class is a valid adaptor for the given object.
Source code in src/scenex/adaptors/_registry.py
33 34 | |
all
#
Return an iterator over all adaptors in the registry.
Source code in src/scenex/adaptors/_registry.py
36 37 38 | |
create_adaptor
#
Create a new adaptor for the given model object.
Source code in src/scenex/adaptors/_registry.py
143 144 145 146 147 148 149 | |
get_adaptor
#
get_adaptor(obj: EventedBase, create: bool = ...) -> Adaptor
Get the adaptor for the given model object, create if create is True.
Source code in src/scenex/adaptors/_registry.py
84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 | |
get_adaptor_class
#
get_adaptor_class(obj: EventedBase) -> type[Adaptor]
Return the adaptor class for the given model object.
Source code in src/scenex/adaptors/_registry.py
127 128 129 130 131 132 133 134 | |
initialize_adaptor
#
initialize_adaptor(model: EventedBase, adaptor: Adaptor) -> None
Initialize the adaptor for the given model object.
Source code in src/scenex/adaptors/_registry.py
102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 | |
validate_adaptor_class
classmethod
#
validate_adaptor_class(obj: EventedBase, adaptor_cls: type[Adaptor]) -> None
Validate that the given class is a valid adaptor for the given object.
Source code in src/scenex/adaptors/_registry.py
136 137 138 139 140 141 | |
get_adaptor_registry
#
get_adaptor_registry(backend: KnownBackend | str | None = None) -> AdaptorRegistry
Get the backend adaptor registry.
Source code in src/scenex/adaptors/_auto.py
30 31 32 33 34 35 36 37 38 39 40 | |
get_all_adaptors
#
Get all loaded adaptors for the given object.
Source code in src/scenex/adaptors/_auto.py
43 44 45 46 47 48 49 | |
use
#
use(backend: KnownBackend | None = None) -> None
Set the graphics backend for rendering scenex visualizations.
This function allows you to explicitly select which graphics library (backend) scenex should use for rendering. It is the goal of scenex to support the full range of model API for each backend.
If not called, scenex will automatically select an arbitrary available backend. You can also set the backend via the SCENEX_CANVAS_BACKEND environment variable.
Parameters:
-
(backend#Literal['pygfx', 'vispy'] | None, default:None) –The graphics backend to use: - "pygfx": Modern WebGPU-based renderer with advanced features - "vispy": OpenGL-based renderer with broad compatibility - None: Reset to auto-detection
Raises:
-
ValueError–If the specified backend is not one of the known backends.
Examples:
Use pygfx backend explicitly:
>>> import scenex as snx
>>> snx.use("pygfx")
>>> canvas = snx.show(snx.View())
Use vispy backend:
>>> snx.use("vispy")
>>> canvas = snx.show(snx.Scene())
Reset to auto-detection:
>>> snx.use(None)
Notes
The backend selection follows this priority order: 1. Backend specified by this function 2. SCENEX_CANVAS_BACKEND environment variable 3. Auto-detection (pygfx preferred, then vispy)
This function should be called before creating any visualizations.
Source code in src/scenex/adaptors/_auto.py
77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 | |