trimesh.scene.transforms

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, frame_from=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 – Homogeneous transformation matrix

Return type:

(4, 4) float

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