trimesh.scene.transforms module¶

class trimesh.scene.transforms.EnforcedForest¶

Bases: object

A simple forest graph data structure: every node is allowed to have exactly one parent. This makes traversal and implementation much simpler than a full graph data type; by storing only one parent reference, it enforces the structure for “free.”

__init__()¶

add_edge(u, v, **kwargs)¶

Add an edge to the forest cleanly.

Parameters:

u (any) – Hashable node key.
v (any) – Hashable node key.
kwargs (dict) – Stored as (u, v) edge data.

Returns:

changed – Return if this operation changed anything.

Return type:

bool

property children¶

Get the children of each node.

Returns:: children – Keyed {node : [child, child, …]}
Return type:: dict

property nodes¶

Get a set of every node.

Returns:: nodes – Every node currently stored.
Return type:: set

remove_node(u)¶

Remove a node from the forest.

Parameters:: u (any) – Hashable node key.
Returns:: changed – Return if this operation changed anything.
Return type:: bool

shortest_path(u, v)¶

Find the shortest path between u and v, returning a path where the first element is always u and the last element is always v, disregarding edge direction.

Parameters:

u (any) – Hashable node key.
v (any) – Hashable node key.

Returns:

path – Path between u and v

Return type:

(n,)

successors(node)¶

Get all nodes that are successors to specified node, including the specified node.

Parameters:: node (any) – Hashable key for a node.
Returns:: successors – Nodes that succeed specified node.
Return type:: set

class trimesh.scene.transforms.SceneGraph(base_frame='world', repair_rigid=1e-05)¶

Bases: object

Hold data about positions and instances of geometry in a scene. This includes a forest (i.e. multi-root tree) of transforms and information on which node is the base frame, and which geometries are affiliated with which nodes.

__init__(base_frame='world', repair_rigid=1e-05)¶

Create a scene graph, holding homogeneous transformation matrices and instance information about geometry.

Parameters:

base_frame (any) – The root node transforms will be positioned from.
repair_rigid (None or float) – If a float will attempt to repair rotation matrices where M @ M.T differs from an identity matrix by more than floating point zero but less than this value. This can happen in a deep tree with a lot of matrix multiplies.

clear()¶

copy()¶

Return a copy of the current TransformForest.

Returns:: copied – Copy of current object.
Return type:: TransformForest

from_edgelist(edges, strict=True)¶

Load transform data from an edge list into the current scene graph.

Parameters:

edgelist ((n,) tuples) – Keyed (node_a, node_b, {key: value})
strict (bool) – If True raise a ValueError when a malformed edge is passed in a tuple.

property geometry_nodes¶

Which nodes have this geometry? Inverse of nodes_geometry.

Returns:: geometry_nodes – Keyed {geometry_name : node name}
Return type:: dict

get(frame_to: Hashable, frame_from: Hashable | None = None) → tuple[ndarray[tuple[int, ...], dtype[float64]], Hashable | None]¶

Get the transform from one frame to another.

Parameters:

frame_to (hashable) – Node name, usually a string (eg ‘mesh_0’)
frame_from (hashable) – Node name, usually a string (eg ‘world’). If None it will be set to self.base_frame

Returns:

transform ((4, 4) float) – Homogeneous transformation matrix
geometry – The name of the geometry if it exists

Raises:

ValueError – If the frames aren’t connected.

load(edgelist)¶

Load transform data from an edge list into the current scene graph.

Parameters:: edgelist ((n,) tuples) – Structured (node_a, node_b, {key: value})

property nodes¶

A list of every node in the graph.

Returns:: nodes – All node names.
Return type:: (n,) array

property nodes_geometry¶

The nodes in the scene graph with geometry attached.

Returns:: nodes_geometry – Node names which have geometry associated
Return type:: (m,) array

remove_geometries(geometries: str | set | Sequence)¶

Remove the reference for specified geometries from nodes without deleting the node.

Parameters:: geometries (list or str) – Name of scene.geometry to dereference.

show(**kwargs)¶

Plot the scene graph using networkx.draw_networkx which uses matplotlib to display the graph.

Parameters:: kwargs (dict) – Passed to networkx.draw_networkx

to_edgelist()¶

Export the current transforms as a list of edge tuples, with each tuple having the format: (node_a, node_b, {metadata})

Returns:: edgelist – Of edge tuples
Return type:: (n,) list

to_flattened()¶

Export the current transform graph with all transforms baked into world->instance.

Returns:: flat – Keyed {node : {transform, geometry}
Return type:: dict

to_gltf(scene, mesh_index=None)¶

Export a transforms as the ‘nodes’ section of the GLTF header dict.

Parameters:

scene (trimesh.Scene) – Scene with geometry.
mesh_index (dict or None) – Mapping { key in scene.geometry : int }

Returns:

gltf – With ‘nodes’ referencing a list of dicts

Return type:

dict

to_networkx()¶

Return a networkx copy of this graph.

Returns:: graph – Directed graph.
Return type:: networkx.DiGraph

update(frame_to, frame_from=None, **kwargs)¶

Update a transform in the tree.

Parameters:

frame_from (hashable object) – Usually a string (eg ‘world’). If left as None it will be set to self.base_frame
frame_to (hashable object) – Usually a string (eg ‘mesh_0’)
matrix ((4,4) float) – Homogeneous transformation matrix
quaternion ((4,) float) – Quaternion ordered [w, x, y, z]
axis ((3,) float) – Axis of rotation
angle (float) – Angle of rotation, in radians
translation ((3,) float) – Distance to translate
geometry (hashable) – Geometry object name, e.g. ‘mesh_0’
metadata (dictionary) – Optional metadata attached to the new frame (exports to glTF node ‘extras’).

trimesh.scene.transforms.kwargs_to_matrix(matrix=None, quaternion=None, translation=None, axis=None, angle=None, **kwargs)¶

Take multiple keyword arguments and parse them into a homogeneous transformation matrix.

Returns:: matrix – Homogeneous transformation matrix.
Return type:: (4, 4) float