pygfx.objects.WorldObject

class pygfx.objects.WorldObject(geometry: Geometry | None = None, material: Material | None = None, *, visible: bool = True, render_order: float = 0, 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.

  • 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

Per-object rendering priority used to fine-tune the draw order within a render queue.

Objects with higher render_order values are rendered later than those with lower values. This affects both opaque and transparent objects and can be used to resolve z-fighting, or control draw order beyond automatic depth sorting.

If the object is part of a Group, the group’s render_order is considered first (that is the group_order of the object).

The order in wich objects are rendered is:

  1. the material.render_queue.

  2. the ob.parent.render_order (if isinstance(ob.parent, gfx.Group)).

  3. the ob.render_order.

  4. the distance to camera (if renderer.sort_objects==True).

  5. the position of the object in the scene graph.

Also see material.render_queue.

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 local model 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 local model 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.