fiftyone.core.threed¶

Module contents¶

3D definitions for FiftyOne.

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

Classes:

`AmbientLight`(name, intensity, color[, visible])	Represents an ambient light.
`DirectionalLight`(name, target, List[float], …)	Represents a directional light.
`PointLight`(name, distance, decay, color, …)	Represents a point light.
`SpotLight`(name, target, List[float], …[, …])	Represents a spot light.
`MeshBasicMaterial`(color, wireframe, opacity)	Represents a basic mesh material.
`MeshDepthMaterial`(wireframe, opacity)	Represents a depth mesh material.
`MeshLambertMaterial`(color, emissive_color, …)	Represents a Lambert mesh material.
`MeshStandardMaterial`(color, emissive_color, …)	Represents a standard mesh material.
`MeshPhongMaterial`(shininess, specular_color, …)	Represents a Phong mesh material.
`PointCloudMaterial`(shading_mode, intensity, …)	Represents a point cloud material.
`FbxMesh`(name, fbx_path, default_material[, …])	Represents an FBX mesh.
`GltfMesh`(name, gltf_path, default_material)	Represents a gLTF mesh.
`ObjMesh`(name, obj_path, mtl_path, …[, visible])	Represents an OBJ mesh.
`PlyMesh`(name, ply_path, is_point_cloud, …)	Represents a PLY mesh.
`StlMesh`(name, stl_path, default_material[, …])	Represents an STL mesh.
`Object3D`(name[, visible])	The base class for all 3D objects in the scene.
`Quaternion`(x, y, z, w)	Represents a quaternion.
`PointCloud`(name, pcd_path, material, …[, …])	Represents a point cloud.
`Counter`([iterable])	Dict subclass for counting hashable items.
`PerspectiveCamera`(position, look_at, up, Y, …)	Represents the configuration of a 3D perspective camera.
`Light`(name, color, intensity[, visible])	Base class for 3D lights.
`Shape3D`(name, material[, visible])	Represents an abstract 3D shape.
`BaseValidatedDataClass`()
`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.
`BoxGeometry`(name, width, height, depth, …)	Represents a 3D box.
`PlaneGeometry`(name, width, height, …[, …])	Represents a 3D plane.
`SphereGeometry`(name, radius, width_segments, …)	Represents a 3D sphere.
`CylinderGeometry`(name, radius_top, …[, …])	Represents a 3D cylinder.
`Euler`(x, y, z, degrees, sequence, XZY, YXZ, …)	Represents intrinsic rotations about the object’s own principal axes.
`Vector3`(x, y, z)	Represents a three-dimensional vector.

Functions:

`convert_keys_to_snake_case`(d)	Convert all keys in a dictionary from camelCase to snake_case.
`validate_color`(v[, nullable])
`validate_list`(v[, length, nullable])

class fiftyone.core.threed.AmbientLight(name: str = 'AmbientLight', intensity: float = 0.1, color: str = '#ffffff', visible=True, position: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, scale: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, quaternion: Optional[fiftyone.core.threed.transformation.Quaternion] = None)¶

Bases: fiftyone.core.threed.lights.Light

Represents an ambient light.

This light globally illuminates all objects in the scene equally.

Parameters

name ("AmbientLight") – the name of the light
intensity (0.1) – the intensity of the light in the range [0, 1]
color ("#ffffff") – the color of the light
visible (True) – default visibility of the object in the scene
position (None) – the position of the light in object space
quaternion (None) – the quaternion of the light in object space
scale (None) – the scale of the light in object space

Methods:

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

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.

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=True)¶: Traverse the scene graph.

property uuid¶: The unique ID of the object.

class fiftyone.core.threed.DirectionalLight(name: str = 'DirectionalLight', target: Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array] = Vector3(x=0.0, y=0.0, z=0.0), color: str = '#ffffff', intensity: float = 1.0, visible=True, position: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, scale: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, quaternion: Optional[fiftyone.core.threed.transformation.Quaternion] = None)¶

Bases: fiftyone.core.threed.lights.Light

Represents a directional light.

A light that gets emitted in a specific direction. This light will behave as though it is infinitely far away and the rays produced from it are all parallel.

Parameters

name ("DirectionalLight") – the name of the light
target ([0,0,0]) – the target of the light
color ("#ffffff") – the color of the light
intensity (1.0) – the intensity of the light in the range [0, 1]
visible (True) – default visibility of the object in the scene
position (None) – the position of the light in object space
quaternion (None) – the quaternion of the light in object space
scale (None) – the scale of the light in object space

Attributes:

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

Methods:

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

target: Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array] = Vector3(x=0.0, y=0.0, z=0.0)¶

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=True)¶: Traverse the scene graph.

property uuid¶: The unique ID of the object.

class fiftyone.core.threed.PointLight(name: str = 'PointLight', distance: float = 0.0, decay: float = 2.0, color: str = '#ffffff', intensity: float = 1.0, visible=True, position: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, scale: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, quaternion: Optional[fiftyone.core.threed.transformation.Quaternion] = None)¶

Bases: fiftyone.core.threed.lights.Light

Represents a point light.

Parameters

name ("PointLight") – the name of the light
distance (0.0) – the distance at which the light’s intensity is zero
decay (2.0) – the amount the light dims along the distance of the light
color ("#ffffff") – the color of the light
intensity (1.0) – the intensity of the light in the range [0, 1]
visible (True) – default visibility of the object in the scene
position (None) – the position of the light in object space
quaternion (None) – the quaternion of the light in object space
scale (None) – the scale of the light in object space

Methods:

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

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.

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=True)¶: Traverse the scene graph.

property uuid¶: The unique ID of the object.

class fiftyone.core.threed.SpotLight(name: str = 'SpotLight', target: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, distance: float = 0.0, decay: float = 2.0, angle: float = 1.0471975511965976, penumbra: float = 0.0, color: str = '#ffffff', intensity: float = 1.0, visible=True, position: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, scale: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, quaternion: Optional[fiftyone.core.threed.transformation.Quaternion] = None)¶

Bases: fiftyone.core.threed.lights.Light

Represents a spot light.

Parameters

name ("SpotLight") – the name of the light
target ([0,0,0]) – the target of the light
distance (0.0) – the distance at which the light’s intensity is zero
decay (2.0) – the amount the light dims along the distance of the light
angle (PI / 3) – the angle of the light’s spotlight, in radians
penumbra (0.0) – the angle of the penumbra of the light’s spotlight, in radians
color ("#ffffff") – the color of the light
intensity (1.0) – the intensity of the light in the range [0, 1]
visible (True) – default visibility of the object in the scene
position (None) – the position of the light in object space
quaternion (None) – the quaternion of the light in object space
scale (None) – the scale of the light in object space

Methods:

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

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.

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=True)¶: Traverse the scene graph.

property uuid¶: The unique ID of the object.

class fiftyone.core.threed.MeshBasicMaterial(color: str = '#808080', wireframe: bool = False, opacity: float = 1.0)¶

Bases: fiftyone.core.threed.material_3d.MeshMaterial

Represents a basic mesh material.

This material is not affected by lights, and is rendered as a solid color.

Parameters

color ("#808080") – the color of the material
wireframe (False) – whether to render the mesh as a wireframe
opacity (1.0) – the opacity of the material, in the range [0, 1]

Attributes:

`color`
`opacity`
`wireframe`

Methods:

as_dict()

property color¶

as_dict()¶

property opacity¶

property wireframe¶

class fiftyone.core.threed.MeshDepthMaterial(wireframe: bool = False, opacity: float = 1.0)¶

Bases: fiftyone.core.threed.material_3d.MeshMaterial

Represents a depth mesh material.

This material is used for drawing geometry by depth, where depth is based off of the camera near and far plane. White is nearest, black is farthest.

Parameters

wireframe (False) – whether to render the mesh as a wireframe
opacity (1.0) – the opacity of the material, in the range [0, 1]

Methods:

as_dict()

Attributes:

`opacity`
`wireframe`

as_dict()¶

property opacity¶

property wireframe¶

class fiftyone.core.threed.MeshLambertMaterial(color: str = '#808080', emissive_color: str = '#000000', emissive_intensity: float = 0.0, reflectivity: float = 1.0, refraction_ratio: float = 0.98, wireframe: bool = False, opacity: float = 1.0)¶

Bases: fiftyone.core.threed.material_3d.MeshMaterial

Represents a Lambert mesh material.

This material only takes into account diffuse reflections, and ignores specular reflection. This is ideal for materials that reflect light evenly without a glossy or shiny appearance, such as unpolished surfaces.

Parameters

color ("#808080") – the color of the material
emissive_color ("#000000") – the emissive color of the material. This is the color emitted by the material itself independent of the light
emissive_intensity (0.0) – the intensity of the emissive color
reflectivity (1.0) – the reflectivity of the material
refraction_ratio (0.98) – the refraction ratio (IOR) of the material
wireframe (False) – whether to render the mesh as a wireframe
opacity (1.0) – the opacity of the material, in the range [0, 1]

Attributes:

`opacity`
`wireframe`
`color`
`emissive_color`
`emissive_intensity`
`reflectivity`
`refraction_ratio`

Methods:

as_dict()

property opacity¶

property wireframe¶

property color¶

property emissive_color¶

property emissive_intensity¶

property reflectivity¶

property refraction_ratio¶

as_dict()¶

class fiftyone.core.threed.MeshStandardMaterial(color: str = '#808080', emissive_color: str = '#000000', emissive_intensity: float = 0.0, metalness: float = 0.0, roughness: float = 1.0, wireframe: bool = False, opacity: float = 1.0)¶

Bases: fiftyone.core.threed.material_3d.MeshMaterial

Represents a standard mesh material.

This material is a standard physically-based rendering (PBR) material. This material is ideal for most use cases.

Parameters

color ("#808080") – the color of the material
emissive_color ("#000000") – the emissive color of the material. This is the color emitted by the material itself independent of the light
emissive_intensity (0.0) – the intensity of the emissive color
metalness (0.0) – the metalness of the material
roughness (1.0) – the roughness of the material
wireframe (False) – whether to render the mesh as a wireframe
opacity (1.0) – the opacity of the material, in the range [0, 1]

Attributes:

`color`
`opacity`
`wireframe`
`emissive_color`
`emissive_intensity`
`metalness`
`roughness`

Methods:

as_dict()

property color¶

property opacity¶

property wireframe¶

property emissive_color¶

property emissive_intensity¶

property metalness¶

property roughness¶

as_dict()¶

class fiftyone.core.threed.MeshPhongMaterial(shininess: float = 30.0, specular_color: str = '#111111', color: str = '#808080', emissive_color: str = '#000000', emissive_intensity: float = 0.0, reflectivity: float = 1.0, refraction_ratio: float = 0.98, wireframe: bool = False, opacity: float = 1.0)¶

Bases: fiftyone.core.threed.material_3d.MeshLambertMaterial

Represents a Phong mesh material.

This material takes into account specular reflection. This is ideal for materials that reflect light with a glossy or shiny appearance, such as polished surfaces.

Parameters

shininess (30.0) – the shininess of the material
specular_color ("#111111") – the specular color of the material
color ("#808080") – the color of the material
emissive_color ("#000000") – the emissive color of the material. This is the color emitted by the material itself independent of the light
emissive_intensity (0.0) – the intensity of the emissive color
reflectivity (1.0) – the reflectivity of the material
refraction_ratio (0.98) – the refraction ratio (IOR) of the material
wireframe (False) – whether to render the mesh as a wireframe
opacity (1.0) – the opacity of the material, in the range [0, 1]

Attributes:

`color`
`emissive_color`
`emissive_intensity`
`opacity`
`reflectivity`
`refraction_ratio`
`wireframe`
`shininess`
`specular_color`

Methods:

as_dict()

property color¶

property emissive_color¶

property emissive_intensity¶

property opacity¶

property reflectivity¶

property refraction_ratio¶

property wireframe¶

property shininess¶

property specular_color¶

as_dict()¶

class fiftyone.core.threed.PointCloudMaterial(shading_mode: Literal[height, intensity, rgb, custom] = 'height', custom_color: str = '#ffffff', point_size: float = 1.0, attenuate_by_distance: bool = False, opacity: float = 1.0)¶

Bases: fiftyone.core.threed.material_3d.Material3D

Represents a point cloud material.

Parameters

shading_mode ("height") – the shading mode to use. Supported values are “height”, “intensity”, “rgb”, and “custom”
custom_color ("#ffffff") – a custom color to use for the point cloud. This is only used when shading_mode is “custom”
point_size (1.0) – the size of the points in the point cloud
attenuate_by_distance (False) – whether to attenuate the point size based on distance from the camera
opacity (1.0) – the opacity of the material, in the range [0, 1]

Attributes:

`shading_mode`
`custom_color`
`point_size`
`attenuate_by_distance`
`opacity`

Methods:

as_dict()

property shading_mode¶

property custom_color¶

property point_size¶

property attenuate_by_distance¶

as_dict()¶

property opacity¶

class fiftyone.core.threed.FbxMesh(name: str, fbx_path: str, default_material: Optional[fiftyone.core.threed.material_3d.MeshMaterial] = None, visible=True, position: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, scale: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, quaternion: Optional[fiftyone.core.threed.transformation.Quaternion] = None)¶

Bases: fiftyone.core.threed.mesh.Mesh

Represents an FBX mesh.

Parameters

name (str) – the name of the mesh
fbx_path (str) – the path to the .fbx file. Path may be either absolute or relative to the directory containing the .fo3d file
material (fiftyone.core.threed.MeshMaterial, optional) – the default material for the mesh if FBX file does not contain material information. Defaults to fiftyone.core.threed.MeshStandardMaterial
visible (True) – default visibility of the mesh in the scene
position (None) – the position of the mesh in object space
quaternion (None) – the quaternion of the mesh in object space
scale (None) – the scale of the mesh in object space

Raises

ValueError – If fbx_path does not end with .fbx

Methods:

`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.
`set_default_material`(material)	Sets the material of the mesh.
`traverse`([include_self])	Traverse the scene graph.

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.

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.

set_default_material(material: fiftyone.core.threed.material_3d.MeshMaterial)¶

Sets the material of the mesh.

Parameters: material (MeshMaterial) – the material to set as the default

traverse(include_self=True)¶: Traverse the scene graph.

property uuid¶: The unique ID of the object.

class fiftyone.core.threed.GltfMesh(name: str, gltf_path: str, default_material: Optional[fiftyone.core.threed.material_3d.MeshMaterial] = None, visible=True, position: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, scale: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, quaternion: Optional[fiftyone.core.threed.transformation.Quaternion] = None)¶

Bases: fiftyone.core.threed.mesh.Mesh

Represents a gLTF mesh.

Parameters

name (str) – the name of the mesh
gltf_path (str) – the path to the .gltf or .glb file. The path may be either absolute or relative to the directory containing the .fo3d file
material (fiftyone.core.threed.MeshMaterial, optional) – the default material for the mesh if gLTF file does not contain material information. Defaults to fiftyone.core.threed.MeshStandardMaterial
visible (True) – default visibility of the mesh in the scene
position (None) – the position of the mesh in object space
quaternion (None) – the quaternion of the mesh in object space
scale (None) – the scale of the mesh in object space

Raises

ValueError – if gltf_path does not end with ‘.gltf’ or .glb

Methods:

`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.
`set_default_material`(material)	Sets the material of the mesh.
`traverse`([include_self])	Traverse the scene graph.

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.

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.

set_default_material(material: fiftyone.core.threed.material_3d.MeshMaterial)¶

Sets the material of the mesh.

Parameters: material (MeshMaterial) – the material to set as the default

traverse(include_self=True)¶: Traverse the scene graph.

property uuid¶: The unique ID of the object.

class fiftyone.core.threed.ObjMesh(name: str, obj_path: str, mtl_path: Optional[str] = None, default_material: Optional[fiftyone.core.threed.material_3d.MeshMaterial] = None, visible=True, position: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, scale: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, quaternion: Optional[fiftyone.core.threed.transformation.Quaternion] = None)¶

Bases: fiftyone.core.threed.mesh.Mesh

Represents an OBJ mesh.

Parameters

name (str) – the name of the mesh
obj_path (str) – the path to the .obj file. The path may be either absolute or relative to the directory containing the .fo3d file
mtl_path (str, optional) – the path to the .mtl file. Defaults to None. The path may be either absolute or relative to the directory containing the .fo3d file
material (fiftyone.core.threed.MeshMaterial, optional) – the default material for the mesh if mtl_path is not provided or if material in mtl_path is not found. Defaults to fiftyone.core.threed.MeshStandardMaterial
visible (True) – default visibility of the mesh in the scene
position (None) – the position of the mesh in object space
quaternion (None) – the quaternion of the mesh in object space
scale (None) – the scale of the mesh in object space

Raises

ValueError – if obj_path does not end with .obj
ValueError – if mtl_path does not end with .mtl

Methods:

`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.
`set_default_material`(material)	Sets the material of the mesh.
`traverse`([include_self])	Traverse the scene graph.

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.

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.

set_default_material(material: fiftyone.core.threed.material_3d.MeshMaterial)¶

Sets the material of the mesh.

Parameters: material (MeshMaterial) – the material to set as the default

traverse(include_self=True)¶: Traverse the scene graph.

property uuid¶: The unique ID of the object.

class fiftyone.core.threed.PlyMesh(name: str, ply_path: str, is_point_cloud: bool = False, center_geometry: bool = True, default_material: Optional[fiftyone.core.threed.material_3d.MeshMaterial] = None, visible=True, position: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, scale: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, quaternion: Optional[fiftyone.core.threed.transformation.Quaternion] = None)¶

Bases: fiftyone.core.threed.mesh.Mesh

Represents a PLY mesh. A PLY mesh can be a point cloud or a mesh.

Parameters

name (str) – the name of the mesh
ply_path (str) – the path to the .ply file. The path may be either absolute or relative to the directory containing the .fo3d file
is_point_cloud (bool) – whether the PLY file is a point cloud. Defaults to False
center_geometry (bool) – whether to center the geometry. Defaults to True
material (fiftyone.core.threed.MeshMaterial, optional) – default material for the mesh if PLY file does not contain vertex colors. Defaults to fiftyone.core.threed.MeshStandardMaterial. If the PLY file contains vertex colors, the material is ignored and vertex colors are used
visible (True) – default visibility of the mesh in the scene
position (None) – the position of the mesh in object space
quaternion (None) – the quaternion of the mesh in object space
scale (None) – the scale of the mesh in object space

Raises

ValueError – if ply_path does not end with .ply

Methods:

`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.
`set_default_material`(material)	Sets the material of the mesh.
`traverse`([include_self])	Traverse the scene graph.

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.

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.

set_default_material(material: fiftyone.core.threed.material_3d.MeshMaterial)¶

Sets the material of the mesh.

Parameters: material (MeshMaterial) – the material to set as the default

traverse(include_self=True)¶: Traverse the scene graph.

property uuid¶: The unique ID of the object.

class fiftyone.core.threed.StlMesh(name: str, stl_path: str, default_material: Optional[fiftyone.core.threed.material_3d.MeshMaterial] = None, visible=True, position: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, scale: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, quaternion: Optional[fiftyone.core.threed.transformation.Quaternion] = None)¶

Bases: fiftyone.core.threed.mesh.Mesh

Represents an STL mesh.

Parameters

name (str) – the name of the mesh
stl_path (str) – the path to the .stl file. The path may be either absolute or relative to the directory containing the .fo3d file
material (fiftyone.core.threed.MeshMaterial, optional) – default material for the mesh. Defaults to fiftyone.core.threed.MeshStandardMaterial
visible (True) – default visibility of the mesh in the scene
position (None) – the position of the mesh in object space
quaternion (None) – the quaternion of the mesh in object space
scale (None) – the scale of the mesh in object space

Raises

ValueError – if stl_path does not end with .stl

Methods:

`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.
`set_default_material`(material)	Sets the material of the mesh.
`traverse`([include_self])	Traverse the scene graph.

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.

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.

set_default_material(material: fiftyone.core.threed.material_3d.MeshMaterial)¶

Sets the material of the mesh.

Parameters: material (MeshMaterial) – the material to set as the default

traverse(include_self=True)¶: Traverse the scene graph.

property uuid¶: The unique ID of the object.

class fiftyone.core.threed.Object3D(name: str, visible=True, position: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, scale: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, quaternion: Optional[fiftyone.core.threed.transformation.Quaternion] = 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.
`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: fiftyone.core.threed.object_3d.Object3D) → None¶: Add one or more objects as children of this one.

clear() → None¶: Remove all children from this object.

traverse(include_self=True)¶: Traverse the scene graph.

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

class fiftyone.core.threed.Quaternion(x: float = 0.0, y: float = 0.0, z: float = 0.0, w: float = 1.0)¶

Bases: fiftyone.core.threed.validators.BaseValidatedDataClass

Represents a quaternion.

Attributes:

`x`
`y`
`z`
`w`

Methods:

`to_euler`([degrees, sequence])	Converts the quaternion into euler angles.
`to_arr`()	Converts the quaternion to a numpy array.

property x¶

property y¶

property z¶

property w¶

to_euler(degrees=False, sequence='XYZ')¶: Converts the quaternion into euler angles.

to_arr()¶: Converts the quaternion to a numpy array.

class fiftyone.core.threed.PointCloud(name: str, pcd_path: str, material: Optional[fiftyone.core.threed.material_3d.PointCloudMaterial] = None, center_geometry: bool = False, flag_for_projection: bool = False, visible=True, position: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, scale: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, quaternion: Optional[fiftyone.core.threed.transformation.Quaternion] = None)¶

Bases: fiftyone.core.threed.object_3d.Object3D

Represents a point cloud.

Parameters

name (str) – the name of the point cloud
pcd_path (str) – the path to the .pcd file. The path may be either absolute or relative to the directory containing the .fo3d file
material (fiftyone.core.threed.PointCloudMaterial, optional) – the material of the point cloud. If not specified, defaults to a new instance of fiftyone.core.threed.PointCloudMaterial with its default parameters
center_geometry (bool) – whether to center the geometry of the point cloud. Defaults to False
flag_for_projection (bool) – whether to flag the point cloud for usage in orthographic projection. Each fiftyone.core.threed.Scene can have at most one asset flagged for orthographic projection. Defaults to False. If multiple assets are flagged, the first one will be chosen
visible (True) – default visibility of the point cloud in the scene
position (None) – the position of the object in point cloud space
quaternion (None) – the quaternion of the point cloud in object space
scale (None) – the scale of the point cloud in object space

Raises

ValueError – if pcd_path does not end with .pcd

Methods:

`set_default_material`(material)	Sets the material of the point cloud.
`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.

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.

set_default_material(material: fiftyone.core.threed.material_3d.PointCloudMaterial)¶

Sets the material of the point cloud.

Parameters: material (PointCloudMaterial) – The material to set as the default

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=True)¶: Traverse the scene graph.

property uuid¶: The unique ID of the object.

class fiftyone.core.threed.Counter(iterable=None, /, **kwds)¶

Bases: dict

Dict subclass for counting hashable items. Sometimes called a bag or multiset. Elements are stored as dictionary keys and their counts are stored as dictionary values.

>>> c = Counter('abcdeabcdabcaba')  # count elements from a string

>>> c.most_common(3)                # three most common elements
[('a', 5), ('b', 4), ('c', 3)]
>>> sorted(c)                       # list all unique elements
['a', 'b', 'c', 'd', 'e']
>>> ''.join(sorted(c.elements()))   # list elements with repetitions
'aaaaabbbbcccdde'
>>> sum(c.values())                 # total of all counts
15

>>> c['a']                          # count of letter 'a'
5
>>> for elem in 'shazam':           # update counts from an iterable
...     c[elem] += 1                # by adding 1 to each element's count
>>> c['a']                          # now there are seven 'a'
7
>>> del c['b']                      # remove all 'b'
>>> c['b']                          # now there are zero 'b'
0

>>> d = Counter('simsalabim')       # make another counter
>>> c.update(d)                     # add in the second counter
>>> c['a']                          # now there are nine 'a'
9

>>> c.clear()                       # empty the counter
>>> c
Counter()

Note: If a count is set to zero or reduced to zero, it will remain in the counter until the entry is deleted or the counter is cleared:

>>> c = Counter('aaabbc')
>>> c['b'] -= 2                     # reduce the count of 'b' by two
>>> c.most_common()                 # 'b' is still in, but its count is zero
[('a', 3), ('c', 1), ('b', 0)]

Methods:

`most_common`([n])	List the n most common elements and their counts from the most common to the least.
`elements`()	Iterator over elements repeating each as many times as its count.
`fromkeys`(iterable[, v])	Create a new dictionary with keys from iterable and values set to value.
`update`([iterable])	Like dict.update() but add counts instead of replacing them.
`subtract`([iterable])	Like dict.update() but subtracts counts instead of replacing them.
`copy`()	Return a shallow copy.
`clear`()
`get`(key[, default])	Return the value for key if key is in the dictionary, else default.
`items`()
`keys`()
`pop`(k[,d])	If key is not found, default is returned if given, otherwise KeyError is raised
`popitem`()	Remove and return a (key, value) pair as a 2-tuple.
`setdefault`(key[, default])	Insert key with a value of default if key is not in the dictionary.
`values`()

most_common(n=None)¶

List the n most common elements and their counts from the most common to the least. If n is None, then list all element counts.

>>> Counter('abracadabra').most_common(3)
[('a', 5), ('b', 2), ('r', 2)]

elements()¶

Iterator over elements repeating each as many times as its count.

>>> c = Counter('ABCABC')
>>> sorted(c.elements())
['A', 'A', 'B', 'B', 'C', 'C']

# Knuth’s example for prime factors of 1836: 2**2 * 3**3 * 17**1 >>> prime_factors = Counter({2: 2, 3: 3, 17: 1}) >>> product = 1 >>> for factor in prime_factors.elements(): # loop over factors … product *= factor # and multiply them >>> product 1836

Note, if an element’s count has been set to zero or is a negative number, elements() will ignore it.

classmethod fromkeys(iterable, v=None)¶: Create a new dictionary with keys from iterable and values set to value.

update(iterable=None, /, **kwds)¶

Like dict.update() but add counts instead of replacing them.

Source can be an iterable, a dictionary, or another Counter instance.

>>> c = Counter('which')
>>> c.update('witch')           # add elements from another iterable
>>> d = Counter('watch')
>>> c.update(d)                 # add elements from another counter
>>> c['h']                      # four 'h' in which, witch, and watch
4

subtract(iterable=None, /, **kwds)¶

Like dict.update() but subtracts counts instead of replacing them. Counts can be reduced below zero. Both the inputs and outputs are allowed to contain zero and negative counts.

Source can be an iterable, a dictionary, or another Counter instance.

>>> c = Counter('which')
>>> c.subtract('witch')             # subtract elements from another iterable
>>> c.subtract(Counter('watch'))    # subtract elements from another counter
>>> c['h']                          # 2 in which, minus 1 in witch, minus 1 in watch
0
>>> c['w']                          # 1 in which, minus 1 in witch, minus 1 in watch
-1

copy()¶: Return a shallow copy.

clear() → None. Remove all items from D.¶

get(key, default=None, /)¶: Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D’s items¶

keys() → a set-like object providing a view on D’s keys¶

pop(k[, d]) → v, remove specified key and return the corresponding value.¶: If key is not found, default is returned if given, otherwise KeyError is raised

popitem()¶

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)¶

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

values() → an object providing a view on D’s values¶

class fiftyone.core.threed.PerspectiveCamera(position: Optional[fiftyone.core.threed.transformation.Vector3] = None, look_at: Optional[fiftyone.core.threed.transformation.Vector3] = None, up: Optional[Literal[X, Y, Z, - X, - Y, - Z]] = None, aspect: Optional[float] = None, fov: float = 50.0, near: float = 0.1, far: float = 2000.0)¶

Bases: fiftyone.core.threed.validators.BaseValidatedDataClass

Represents the configuration of a 3D perspective camera.

Parameters

position (None) – the position of the camera. If None, the camera position is calculated based on the bounding box of the scene
look_at (None) – the point the camera is looking at. If None, the camera looks at the center of the scene
up (None) – the orthonormal axis that is considered up. Must be one of “X”, “Y”, “Z”, “-X”, “-Y”, or “-Z”. If None, it will fallback to the global up as defined in 3D plugin settings. If that too is not defined, it will fallback to “Y”
aspect (None) – the aspect ratio of the camera. If None, the aspect ratio is calculated based on the width and height of the canvas
fov (50) – camera frustum vertical field of view in degrees. If None, the field of view is 50 degrees
near (0.1) – the near clipping plane of the camera
far (2000) – the far clipping plane of the camera

Attributes:

`position`
`look_at`
`up`
`aspect`
`fov`
`near`
`far`

Methods:

as_dict()

property position¶

property look_at¶

property up¶

property aspect¶

property fov¶

property near¶

property far¶

as_dict() → dict¶

class fiftyone.core.threed.Light(name: Optional[str] = None, color: str = '#ffffff', intensity: float = 1.0, visible=True, position: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, scale: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, quaternion: Optional[fiftyone.core.threed.transformation.Quaternion] = None)¶

Bases: fiftyone.core.threed.object_3d.Object3D

Base class for 3D lights.

Parameters

color ("#ffffff") – the color of the light
intensity (1.0) – the intensity of the light in the range [0, 1]
visible (True) – default visibility of the object in the scene
position (None) – the position of the light in object space
quaternion (None) – the quaternion of the light in object space
scale (None) – the scale of the light in object space

Methods:

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

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.

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=True)¶: Traverse the scene graph.

property uuid¶: The unique ID of the object.

class fiftyone.core.threed.Shape3D(name: str, material: Optional[fiftyone.core.threed.material_3d.MeshMaterial] = None, visible=True, position: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, scale: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, quaternion: Optional[fiftyone.core.threed.transformation.Quaternion] = None)¶

Bases: fiftyone.core.threed.mesh.Mesh

Represents an abstract 3D shape.

Parameters

name – the name of the mesh
material (fiftyone.core.threed.MeshMaterial, optional) – default material for the shape mesh. Defaults to fiftyone.core.threed.MeshStandardMaterial if not provided
visible (True) – default visibility of the mesh in the scene
position (None) – the position of the mesh in object space
quaternion (None) – the quaternion of the mesh in object space
scale (None) – the scale of the mesh in object space

Methods:

`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.
`set_default_material`(material)	Sets the material of the mesh.
`traverse`([include_self])	Traverse the scene graph.

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.

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.

set_default_material(material: fiftyone.core.threed.material_3d.MeshMaterial)¶

Sets the material of the mesh.

Parameters: material (MeshMaterial) – the material to set as the default

traverse(include_self=True)¶: Traverse the scene graph.

property uuid¶: The unique ID of the object.

fiftyone.core.threed.convert_keys_to_snake_case(d)¶

Convert all keys in a dictionary from camelCase to snake_case.

Parameters: d – the dictionary
Returns: a dictionary with snake case keys

class fiftyone.core.threed.BaseValidatedDataClass¶: Bases: object

fiftyone.core.threed.validate_color(v: Optional[str], nullable: bool = False)¶

fiftyone.core.threed.validate_list(v: Any, length: Optional[int] = None, nullable: bool = False) → list¶

class fiftyone.core.threed.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(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

class fiftyone.core.threed.BoxGeometry(name: str, width: float = 1, height: float = 1, depth: float = 1, default_material: Optional[fiftyone.core.threed.material_3d.MeshMaterial] = None, visible=True, position: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, scale: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, quaternion: Optional[fiftyone.core.threed.transformation.Quaternion] = None)¶

Bases: fiftyone.core.threed.shape_3d.Shape3D

Represents a 3D box.

Parameters

name (str) – name of the box
width (float) – the width of the box. Defaults to 1
height (float) – the height of the box. Defaults to 1
depth (float) – the depth of the box. Defaults to 1
material (fiftyone.core.threed.MeshMaterial, optional) – default material for the box. Defaults to fiftyone.core.threed.MeshStandardMaterial
visible (True) – default visibility of the mesh in the scene
position (None) – the position of the mesh in object space
quaternion (None) – the quaternion of the mesh in object space
scale (None) – the scale of the mesh in object space

Methods:

`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.
`set_default_material`(material)	Sets the material of the mesh.
`traverse`([include_self])	Traverse the scene graph.

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.

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.

set_default_material(material: fiftyone.core.threed.material_3d.MeshMaterial)¶

Sets the material of the mesh.

Parameters: material (MeshMaterial) – the material to set as the default

traverse(include_self=True)¶: Traverse the scene graph.

property uuid¶: The unique ID of the object.

class fiftyone.core.threed.PlaneGeometry(name: str, width: float = 1, height: float = 1, default_material: Optional[fiftyone.core.threed.material_3d.MeshMaterial] = None, visible=True, position: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, scale: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, quaternion: Optional[fiftyone.core.threed.transformation.Quaternion] = None)¶

Bases: fiftyone.core.threed.shape_3d.Shape3D

Represents a 3D plane.

Parameters

name (str) – name of the plane
width (float) – the width of the plane. Defaults to 1
height (float) – the height of the plane. Defaults to 1
material (fiftyone.core.threed.MeshMaterial, optional) – the default material for the plane. Defaults to fiftyone.core.threed.MeshStandardMaterial
visible (True) – default visibility of the mesh in the scene
position (None) – the position of the mesh in object space
quaternion (None) – the quaternion of the mesh in object space
scale (None) – the scale of the mesh in object space

Methods:

`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.
`set_default_material`(material)	Sets the material of the mesh.
`traverse`([include_self])	Traverse the scene graph.

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.

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.

set_default_material(material: fiftyone.core.threed.material_3d.MeshMaterial)¶

Sets the material of the mesh.

Parameters: material (MeshMaterial) – the material to set as the default

traverse(include_self=True)¶: Traverse the scene graph.

property uuid¶: The unique ID of the object.

class fiftyone.core.threed.SphereGeometry(name: str, radius: float = 1, width_segments: int = 32, height_segments: int = 16, phi_start: float = 0, phi_length: float = 6.283185307179586, theta_start: float = 0, theta_length: float = 3.141592653589793, default_material: Optional[fiftyone.core.threed.material_3d.MeshMaterial] = None, visible=True, position: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, scale: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, quaternion: Optional[fiftyone.core.threed.transformation.Quaternion] = None)¶

Bases: fiftyone.core.threed.shape_3d.Shape3D

Represents a 3D sphere.

Parameters

name (str) – the name of the sphere
radius (float) – the radius of the sphere. Defaults to 1
width_segments (int) – the number of segmented faces around the circumference of the sphere. Defaults to 32
height_segments (int) – the number of rows of faces around the circumference of the sphere. Defaults to 16
phi_start (float) – the start angle for the horizontal sweep. Defaults to 0
phi_length (float) – the angle for the horizontal sweep. Defaults to 2*math.pi, which makes for a complete sphere
theta_start (float) – the start angle for the vertical sweep. Defaults to 0
theta_length (float) – the angle for the vertical sweep. Defaults to math.pi, which makes for a complete sphere
material (fiftyone.core.threed.MeshMaterial, optional) – the default material for the sphere. Defaults to fiftyone.core.threed.MeshStandardMaterial
visible (True) – default visibility of the mesh in the scene
position (None) – the position of the mesh in object space
quaternion (None) – the quaternion of the mesh in object space
scale (None) – the scale of the mesh in object space

Methods:

`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.
`set_default_material`(material)	Sets the material of the mesh.
`traverse`([include_self])	Traverse the scene graph.

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.

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.

set_default_material(material: fiftyone.core.threed.material_3d.MeshMaterial)¶

Sets the material of the mesh.

Parameters: material (MeshMaterial) – the material to set as the default

traverse(include_self=True)¶: Traverse the scene graph.

property uuid¶: The unique ID of the object.

class fiftyone.core.threed.CylinderGeometry(name: str, radius_top: float = 1, radius_bottom: float = 1, height: float = 1, radial_segments: int = 32, height_segments: int = 1, open_ended: bool = False, theta_start: float = 0, theta_length: float = 6.283185307179586, default_material: Optional[fiftyone.core.threed.material_3d.MeshMaterial] = None, visible=True, position: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, scale: Optional[Union[fiftyone.core.threed.transformation.Vector3, List[float], Tuple[float], numpy.array]] = None, quaternion: Optional[fiftyone.core.threed.transformation.Quaternion] = None)¶

Bases: fiftyone.core.threed.shape_3d.Shape3D

Represents a 3D cylinder.

Parameters

name (str) – name of the cylinder
radius_top (float) – the radius of the top of the cylinder. Defaults to 1
radius_bottom (float) – the radius of the bottom of the cylinder. Defaults to 1
height (float) – the height of the cylinder. Defaults to 1
radial_segments (int) – number of segmented faces around the circumference of the cylinder. Defaults to 32
height_segments (int) – number of rows of faces around the circumference of the cylinder. Defaults to 1
open_ended (bool) – whether the cylinder is open-ended. Defaults to False
theta_start (float) – the start angle for the vertical sweep. Defaults to 0
theta_length (float) – the angle for the vertical sweep. Defaults to 2*Math.PI, which makes for a complete cylinder
material (fiftyone.core.threed.MeshMaterial, optional) – default material for the cylinder. Defaults to fiftyone.core.threed.MeshStandardMaterial
visible (True) – default visibility of the mesh in the scene
position (None) – the position of the mesh in object space
quaternion (None) – the quaternion of the mesh in object space
scale (None) – the scale of the mesh in object space

Methods:

`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.
`set_default_material`(material)	Sets the material of the mesh.
`traverse`([include_self])	Traverse the scene graph.

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.

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.

set_default_material(material: fiftyone.core.threed.material_3d.MeshMaterial)¶

Sets the material of the mesh.

Parameters: material (MeshMaterial) – the material to set as the default

traverse(include_self=True)¶: Traverse the scene graph.

property uuid¶: The unique ID of the object.

class fiftyone.core.threed.Euler(x: float = 0.0, y: float = 0.0, z: float = 0.0, degrees: bool = False, sequence: Literal[XYZ, XZY, YXZ, YZX, ZXY, ZYX] = 'XYZ')¶

Bases: fiftyone.core.threed.transformation.Vector3

Represents intrinsic rotations about the object’s own principal axes.

Attributes:

`degrees`
`sequence`
`x`
`y`
`z`

Methods:

`to_quaternion`()	Converts the euler angles to a quaternion.
`to_arr`()	Converts the vector to a numpy array.

property degrees¶

property sequence¶

to_quaternion()¶: Converts the euler angles to a quaternion.

to_arr()¶: Converts the vector to a numpy array.

property x¶

property y¶

property z¶

class fiftyone.core.threed.Vector3(x: float = 0.0, y: float = 0.0, z: float = 0.0)¶

Bases: fiftyone.core.threed.validators.BaseValidatedDataClass

Represents a three-dimensional vector.

Attributes:

`x`
`y`
`z`

Methods:

to_arr()

Converts the vector to a numpy array.

property x¶

property y¶

property z¶

to_arr()¶: Converts the vector to a numpy array.