fiftyone.core.threed.mesh

Mesh definitions for 3D visualization.

Copyright 2017-2025, Voxel51, Inc.

voxel51.com

Classes:

Mesh(name, material[, visible])	Represents an abstract 3D mesh.
ObjMesh(name, obj_path, mtl_path, …[, visible])	Represents an OBJ mesh.
FbxMesh(name, fbx_path, default_material[, …])	Represents an FBX mesh.
GltfMesh(name, gltf_path, default_material)	Represents a gLTF mesh.
PlyMesh(name, ply_path, is_point_cloud, …)	Represents a PLY mesh.
StlMesh(name, stl_path, default_material[, …])	Represents an STL mesh.

class fiftyone.core.threed.mesh.Mesh(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.object_3d.Object3D

Represents an abstract 3D mesh.

Parameters

• name – the name of the mesh

• material (fiftyone.core.threed.MeshMaterial, optional) – the default material for the 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:

set_default_material(material)	Sets the material of the mesh.
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.MeshMaterial)

Sets the material of the mesh.

Parameters

material (MeshMaterial) – 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.mesh.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.mesh.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.mesh.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.mesh.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.mesh.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.