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

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