fiftyone.core.threed.scene_3d#

3D scene definitions.

Copyright 2017-2025, Voxel51, Inc.
voxel51.com

Classes:

`SceneBackground`([color, image, cube, intensity])	Represents the background of the scene.
`Scene`([camera, lights, background])	Represents a scene graph which contains a hierarchy of 3D objects.

class fiftyone.core.threed.scene_3d.SceneBackground(color: str | None = None, image: str | None = None, cube: List[str] | None = None, intensity: float | None = 1.0)#

Bases: BaseValidatedDataClass

Represents the background of the scene.

Parameters:

color (str, optional) – the background color of the scene
image (str, optional) – the path to the background image. Defaults to None. This takes precedence over color if provided
cube (list, optional) – the paths to the six faces of the background. The order of the faces is: +X, -X, +Y, -Y, +Z, -Z. Defaults to None. This takes precedence over the image and color if provided. This can be used to build a skybox
intensity (float, optional) – the intensity of the background. Defaults to 1.0. This only applies for image and cube backgrounds

Attributes:

`color`
`image`
`cube`
`intensity`

Methods:

as_dict()

property color: str | None#

property image: str | None#

property cube: List[str] | None#

property intensity: float | None#

as_dict() → dict#

class fiftyone.core.threed.scene_3d.Scene(camera: PerspectiveCamera | None = None, lights: List[Light] | None = None, background: SceneBackground | None = None)#

Bases: Object3D

Represents a scene graph which contains a hierarchy of 3D objects.

Example usage:

import fiftyone as fo

scene = fo.Scene()

obj_mesh = fo.ObjMesh(
    "obj_mesh_name", "/path/to/mesh.obj", mtl_path="/path/to/mesh.mtl"
)
gltf_mesh = fo.GltfMesh("gltf_mesh_name", "/path/to/mesh.gltf")
pcd = fo.PointCloud("pcd_name", "/path/to/points.pcd")

scene.add(obj_mesh)
scene.add(gltf_mesh)
scene.add(pcd)

scene.write("/path/to/scene.fo3d")

sample = fo.Sample("/path/to/scene.fo3d")

dataset = fo.Dataset()
dataset.add_sample(sample)

Parameters:

camera (None) – the default camera of the scene. If None, a default fiftyone.core.threed.PerspectiveCamera is created with reasonable defaults
lights (None) – a list of lights in the scene. If``None``, a default set of lights is used, which includes an ambient light and six directional lights placed at different angles around the scene
background (None) – the background for the scene. May be a color, image, or a skybox

Methods:

`copy`()	Returns a deep copy of the scene.
`write`(fo3d_path[, resolve_relative_paths, ...])	Export the scene to a `.fo3d` file.
`add`(*objs)	Add one or more objects as children of this one.
`as_dict`()	Converts the object to a dict.
`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.
`update_asset_paths`(asset_rewrite_paths)	Update asset paths in this scene according to an input dict mapping.
`get_scene_summary`()	Returns a summary of the scene.
`get_asset_paths`()	Returns a list of all asset paths in the scene.
`from_fo3d`(path)	Loads a scene from an FO3D file.

Attributes:

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

copy()#: Returns a deep copy of the scene.

write(fo3d_path: str, resolve_relative_paths=False, pprint=False)#

Export the scene to a .fo3d file.

Parameters:

fo3d_path – the path to write the scene to
resolve_relative_paths – whether to resolve relative paths in the scene to absolute paths. If True, all asset paths in the scene are resolved to absolute paths. If False, asset paths are left as-is. Defaults to False.
pprint – whether to pretty-print the JSON output. Defaults to False.

add(*objs: Object3D) → None#: Add one or more objects as children of this one.

as_dict()#: Converts the object to a dict.

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)

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.

property position#: The position of the object in object space.

property quaternion#: The quaternion of the object in object space.

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

property rotation#: The rotation of the object in object space.

property scale#: The scale of the object in object space.

traverse(include_self=False)#

Traverse the scene graph.

Parameters:: include_self – whether to include the current node in the traversal
Returns:: a generator that yields Object3D instances

property uuid#: The unique ID of the object.

update_asset_paths(asset_rewrite_paths: dict)#

Update asset paths in this scene according to an input dict mapping.

Asset path is unchanged if it does not exist in asset_rewrite_paths

Parameters:: asset_rewrite_paths – dict mapping asset path to new asset path
Returns:: True if the scene was modified.

get_scene_summary()#: Returns a summary of the scene.

get_asset_paths()#

Returns a list of all asset paths in the scene.

Note that any relative asset paths are not resolved to absolute paths.

Returns:: a list of asset paths

static from_fo3d(path: str)#

Loads a scene from an FO3D file.

Parameters:: path – the path to an .fo3d file
Returns:: a Scene