pygfx.objects.WorldObject
- class pygfx.objects.WorldObject(geometry=None, material=None, *, visible=True, render_order=0, render_mask='auto', name='')
Bases:
EventTarget
,RootTrackable
Base class for objects.
This class represents objects in the world, i.e., the scene graph.Each WorldObject has geometry to define it’s data, and material to define its appearance. The object itself is only responsible for defining object hierarchies (parent / children) and its position and orientation in the world.
- Parameters:
geometry (Geometry) – The data defining the shape of the object.
material (Material) – The data defining the appearance of the object.
visible (bool) – Whether the object is visible.
render_order (float) – Value that helps controls the order in which objects are rendered.
render_mask (str | RenderMask) – Determines the render passes that the object is rendered in. It’s recommended to let the renderer decide, using “auto”.
name (str) – The name of the object.
Notes
Use
Group
to collect multiple world objects into a single empty world object.See also
pygfx.utils.transform.AffineBase
Various getters and setters defined on
obj.local
andobj.world
.pygfx.utils.transform.AffineTransform
The class used to implement
obj.local
.pygfx.utils.transform.RecursiveTransform
The class used to implement
obj.world
.
- local
The object’s transform expressed in parent space.
- world
The object’s transform expressed in world space.
- uniform_buffer
The GPU data of this WorldObject.
- property up
Relic of old WorldObjects that aliases with the new
transform.up
direction. Prefer obj.world.reference_up instead.
- property id
An integer id smaller than 2**31 (read-only).
- property visible
Whether is object is rendered or not. Default True.
- property render_order
A number that helps control the order in which objects are rendered. Objects with higher
render_order
get rendered later. Default 0. Also seeRenderer.sort_objects
.
- property render_mask
Indicates in what render passes to render this object:
See
pygfx.utils.enums.RenderMask
:If “auto” (the default), the renderer attempts to determine whether all fragments will be either opaque or all transparent, and only apply the needed render passes. If this cannot be determined, it falls back to “all”.
Some objects may contain both transparent and opaque fragments, and should be rendered in all passes - the object’s contribution to each pass is determined on a per-fragment basis.
For clarity, rendering objects in all passes even though they are fully opaque/transparent yields correct results and is generally the “safest” option. The only cost is performance. Rendering transparent fragments in the opaque pass makes them invisible. Rendering opaque fragments in the transparent pass blends them as if they are transparent with an alpha of 1.
- property geometry
The object’s geometry, the data that defines (the shape of) this object.
- property material
Whether is object is rendered or not. Default True.
- property cast_shadow
Whether this object casts shadows, i.e. whether it is rendered into a shadow map. Default False.
- property receive_shadow
Whether this object receives shadows. Default False.
- property parent: WorldObject
Object’s parent in the scene graph (read-only). An object can have at most one parent.
- property children: Tuple[WorldObject]
tuple of children of this object. (read-only)
- add(*objects, before=None, keep_world_matrix=False) WorldObject
Add child objects.
Any number of objects may be added. Any current parent on an object passed in here will be removed, since an object can have at most one parent. If
before
argument is given, then the items are inserted before the given element.- Parameters:
*objects (WorldObject) – The world objects to add as children.
before (WorldObject) – If not None, insert the objects before this child object.
keep_world_matrix (bool) – If True, the child will keep it’s world transform. It moves in the scene graph but will visually remain in the same place. If False, the child will keep it’s parent transform.
- remove(*objects, keep_world_matrix=False)
Removes object as child of this object. Any number of objects may be removed.
- clear(*, keep_world_matrix=False)
Removes all children.
- traverse(callback, skip_invisible=False)
Executes the callback on this object and all descendants.
If
skip_invisible
is given and True, objects whosevisible
property is False - and their children - are skipped. Note that modifying the scene graph inside the callback is discouraged.
- iter(filter_fn=None, skip_invisible=False)
Create a generator that iterates over this objects and its children. If
filter_fn
is given, only objects for which it returnsTrue
are included.
- get_bounding_box()
Axis-aligned bounding box in parent space.
- Returns:
aabb – An axis-aligned bounding box, or None when the object does not take up a particular space.
- Return type:
ndarray, [2, 3] or None
- get_bounding_sphere()
Bounding Sphere in parent space.
- Returns:
bounding_shere – A sphere (x, y, z, radius), or None when the object does not take up a particular space.
- Return type:
ndarray, [4] or None
- get_world_bounding_box()
Axis aligned bounding box in world space.
- Returns:
aabb – The transformed axis-aligned bounding box, or None when the object does not take up a particular space.
- Return type:
ndarray, [2, 3] or None
- get_world_bounding_sphere()
Bounding Sphere in world space.
- Returns:
bounding_shere – A sphere (x, y, z, radius), or None when the object does not take up a particular space.
- Return type:
ndarray, [4] or None
- look_at(target) None
Orient the object so it looks at the given position.
This sets the object’s rotation such that its
forward
direction points towardstarget
(given in world space). This rotation takes reference_up into account, i.e., the rotation is chosen in such a way that a camera lookingforward
follows the rotation of a human head looking around without tilting the head sideways.