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: Optional[str] = None, image: Optional[str] = None, cube: Optional[List[str]] = None, intensity: Optional[float] = 1.0)¶

Bases: fiftyone.core.threed.validators.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¶

property image¶

property cube¶

property intensity¶

as_dict() → dict¶

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

Bases: fiftyone.core.threed.object_3d.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.
`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: fiftyone.core.threed.object_3d.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.

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.

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