pygfx.objects.WorldObject

class pygfx.objects.WorldObject(geometry: Geometry | None = None, material: Material | None = None, *, visible: bool = True, render_order: float = 0, render_mask: str | int = 'auto', name: str = '')

Bases: EventTarget, Trackable

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. See the documentation on the different WorldObject subclasses for what attributes the geometry should and may have.
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 and obj.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: ndarray: Relic of old WorldObjects that aliases with the new transform.up direction. Prefer obj.world.reference_up instead.

property id: int: An integer id smaller than 2**31 (read-only).

property visible: bool: Whether is object is rendered or not. Default True.

property render_order: float: A number that helps control the order in which objects are rendered. Objects with higher render_order get rendered later. Default 0. Also see Renderer.sort_objects.

property render_mask: int

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: Geometry | None: The object’s geometry, the data that defines (the shape of) this object.

property material: Material | None: The object’s material, the data that defines the appearance of this object.

property cast_shadow: bool: Whether this object casts shadows, i.e. whether it is rendered into a shadow map. Default False.

property receive_shadow: bool: Whether this object receives shadows. Default False.

property parent: WorldObject | None: 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: WorldObject, before: WorldObject | None = None, keep_world_matrix: bool = 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: WorldObject, keep_world_matrix: bool = False) → None: Removes object as child of this object. Any number of objects may be removed.

clear(*, keep_world_matrix: bool = False) → None: Removes all children.

traverse(callback: Callable[[WorldObject], Any], skip_invisible: bool = False)

Executes the callback on this object and all descendants.

If skip_invisible is given and True, objects whose visible property is False - and their children - are skipped. Note that modifying the scene graph inside the callback is discouraged.

iter(filter_fn: Callable[[WorldObject], bool] | None = None, skip_invisible: bool = False) → Iterator[WorldObject]: Create a generator that iterates over this objects and its children. If filter_fn is given, only objects for which it returns True are included.

get_bounding_box() → ndarray | None

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() → ndarray | None

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() → ndarray | None

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() → ndarray | None

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: WorldObject) → None

Orient the object so it looks at the given position.

This sets the object’s rotation such that its forward direction points towards target (given in world space). This rotation takes reference_up into account, i.e., the rotation is chosen in such a way that a camera looking forward follows the rotation of a human head looking around without tilting the head sideways.