fiftyone.core.threed.object_3d

FiftyOne 3D Object3D base class.

Copyright 2017-2025, Voxel51, Inc.

voxel51.com

Classes:

Object3D(name[, visible, position, scale, ...])

The base class for all 3D objects in the scene.

class fiftyone.core.threed.object_3d.Object3D(name: str, visible=True, position: Vector3 | List[float] | Tuple[float] | array | None = None, scale: Vector3 | List[float] | Tuple[float] | array | None = None, quaternion: Quaternion | None = None)

Bases: object

The base class for all 3D objects in the scene.

Parameters:

• name – the name of the object

• visible (True) – default visibility of the object in the scene

• position (None) – the position of the object in object space

• quaternion (None) – the quaternion of the object in object space

• scale (None) – the scale of the object in object space

Attributes:

uuid	The unique ID of the object.
position	The position of the object in object space.
rotation	The rotation of the object in object space.
quaternion	The quaternion of the object in object space.
scale	The scale of the object in object space.
local_transform_matrix	The local transform matrix of the object.

Methods:

add(*objs)	Add one or more objects as children of this one.
clear()	Remove all children from this object.
find_and_execute(node, predicate, on_match)	Recursively search the scene graph and execute an action on matching nodes.
remove(*objs)	Remove one or more objects from the scene graph recursively.
remove_by_name(name)	Remove all objects with the given name from the scene graph recursively.
remove_by_uuid(target_uuid)	Remove the object with the given UUID from the scene graph recursively.
traverse([include_self])	Traverse the scene graph.
as_dict()	Converts the object to a dict.

property uuid

The unique ID of the object.

property position

The position of the object in object space.

property rotation

The rotation of the object in object space.

property quaternion

The quaternion of the object in object space.

property scale

The scale of the object in object space.

property local_transform_matrix

The local transform matrix of the object.

Setting this property also decomposes the matrix into its constituent position, quaternion, and scale components. However, decomposition of matrices with skew / shear components (non-uniform scaling) might have unexpected results.

add(*objs: Object3D) → None

Add one or more objects as children of this one.

clear() → None

Remove all children from this object.

find_and_execute(node: Object3D, predicate, on_match, stop_on_first_match: bool = False) → bool

Recursively search the scene graph and execute an action on matching nodes.

This is a generic method for traversing the scene graph and performing operations on nodes that match a given predicate. It can be used for finding and removing nodes, collecting nodes, updating nodes, etc.

The traversal continues into the subtrees of both matching and non-matching nodes. For matching nodes, the subtree is traversed when on_match returns True and stop_on_first_match is False.

Parameters:

• node – the node to start searching from

• predicate – a function that takes a child Object3D and returns

• criteria (True if it matches the search)

• on_match – a function called when a match is found, takes

• (parent

• searching (child) and returns True to continue)

• to (False)

• stop

• stop_on_first_match – if True, stop searching after first match

• processed (is)

Returns:

True if a match was found and we should stop, False otherwise

Example

# Find all nodes with a specific name and collect them matches = [] def predicate(child):

return child.name == “target”

def on_match(parent, child):

matches.append(child) return True # continue searching

scene.find_and_execute(scene, predicate, on_match)

remove(*objs: Object3D) → None

Remove one or more objects from the scene graph recursively.

This method searches recursively through the entire scene graph starting from this object and removes any matching objects from their parent’s children list.

Parameters:

*objs – one or more Object3D instances to remove

Raises:

• ValueError – if any of the objects to remove is this object itself

• ValueError – if any of the objects is not found in the scene graph

remove_by_name(name: str) → None

Remove all objects with the given name from the scene graph recursively.

This method searches recursively through the entire scene graph starting from this object and removes all objects matching the given name from their parent’s children lists.

Parameters:

name – the name of the objects to remove

Raises:

• ValueError – if attempting to remove this object itself by name

• ValueError – if no objects with the given name are found

remove_by_uuid(target_uuid: str) → None

Remove the object with the given UUID from the scene graph recursively.

This method searches recursively through the entire scene graph starting from this object and removes the object matching the given UUID from its parent’s children list. UUIDs should be unique, so only one match is expected.

Parameters:

target_uuid – the UUID of the object to remove

Raises:

• ValueError – if attempting to remove this object itself by UUID

• ValueError – if no object with the given UUID is found

traverse(include_self=True)

Traverse the scene graph.

as_dict()

Converts the object to a dict.