scene_synthesizer.scene.Scene

class scene_synthesizer.scene.Scene(base_frame='world', trimesh_scene=None, seed=None, keep_collision_manager_synchronized=True, share_geometry=False, default_use_collision_geometry=True)

Create a new empty scene.

Parameters:

base_frame (str, optional) – Name of the base frame. Defaults to “world”.
trimesh_scene (trimesh.Scene, optional) – The trimesh scene object that this scene is based on. Defaults to None.
seed (int, numpy.random._generator.Generator, optional) – A seed or random number generator. Defaults to None which creates a new default random number generator.
keep_collision_manager_synchronized (bool, optional) – Whether to keep the collision manager in sync (after each object add or removal). Defaults to True.
share_geometry (bool, optional) – Whether to share geometry between objects if hashes are the same. Can improve performance for large scenes with multiple objects of the same kind. Note, that unintended side effects can happen since e.g. visual properties are not part of the hash. Defaults to False.
default_use_collision_geometry (bool or None, optional) – The default value for use_collision_geometry when adding objects to the scene and not specifically set. Can be either True, False or None. Defaults to True.

property metadata

The metadata of the scene in form of a dict. This holds all information that is not part of the trimesh.Scene object self.scene.

Returns:: Metadata of the scene.
Return type:: dict

property graph

The scene graph.

Returns:: The scene graph.
Return type:: trimesh.scene.transforms.SceneGraph

property scene

The trimesh scene object that contains most scene information.

Returns:: The scene.
Return type:: trimesh.Scene

property geometry

The trimesh geometries that this scene contains.

Returns:: A dict of identifiers and trimesh.Trimesh’s.
Return type:: OrderedDict[str, trimesh.Trimesh]

classmethod single_object_scene(asset, obj_id=None, base_frame='world', seed=None, **kwargs)

Creates a scene and adds an asset. Only for convenience.

Parameters:

asset (scene.Asset) – Object asset.
obj_id (str) – Object identifier.
base_frame (str, optional) – Name of the base frame of the scene. Defaults to “world”.
seed (int, numpy.random._generator.Generator, optional) – A seed or random number generator. Defaults to None which creates a new default random number generator.
**kwargs – Additional keyword arguments that will be piped to the add_object method.

Returns:

A scene object.

Return type:

scene.Scene

copy()

Return a deep copy of the current scene.

Returns:: Copy of the current scene.
Return type:: (scene.Scene)

invalidate_scenegraph_cache(): Invalidate cache of the trimesh scene graph and run forward kinematics with current configuration.

add_base_frame(name, **kwargs)

Add a new root node to the scene graph.

Parameters:

name (str) – New name of root node / base frame.
**matrix – Homogenous transform between new base frame and previous one.

Raises:

ValueError – If node name already exists in the scene graph.

remove_base_frame(keep_transform=True)

Remove root of scene graph. Only works, if current root has one child. Its child will become the new root of the scene graph.

Parameters:: keep_transform (bool, optional) – Fold the potentially removed transform into the edge of the roots child. Defaults to True.
Raises:: ValueError – Current root doesn’t have one child.

add_base_frame_transform(matrix)

Transform the base_frame of the scene, i.e., move the entire scene.

Parameters:: matrix (np.ndarray) – 4x4 homogenous transform

is_watertight(obj_id, layers=None)

Check wheter object geometries are all watertight.

Parameters:

obj_id (str) – Object identifier.
layers (list[str]) – Layers.

Raises:

ValueError – Unknown object identifier.
ValueError – No geometries found.

Returns:

Whether object geometries are all watertight.

Return type:

bool

get_volume(obj_id)

Get volume of a single object in the scene.

Parameters:: obj_id (str) – Object identifier.
Raises:: ValueError – Unknown object identifier.
Returns:: Volume of the object.
Return type:: float

set_mass(obj_id, mass)

Sets mass of a single object in the scene. Note, that in case the object consists of multiple geometries, masses are distributed according to volume. If meshes are not watertight this migth lead to unexpected distributions. Internally, this method sets the density according to the mass to ensure the two are always consistent.

Parameters:

obj_id (str) – Object identifier.
mass (float) – Mass of the object.

Raises:

ValueError – Unknown object identifier.
ValueError – Object has no geometries.

get_mass(obj_id)

Get mass of a single object in the scene.

Parameters:: obj_id (str) – Object identifier.
Raises:: ValueError – Unknown object identifier.
Returns:: Mass of the object.
Return type:: float

set_density(obj_id, density)

Set density of a single object in the scene.

Parameters:

obj_id (str) – Object identifier.
density (float) – Density of the object.

Raises:

ValueError – Unkown object identifier.
ValueError – Object has no geometries.

get_density(obj_id)

Get density of a single object in the scene.

Parameters:

obj_id (str) – Object identifier.

Raises:

ValueError – Unknown object identifier.
ValueError – Object has no geometries.

Returns:

Density of the object.

Return type:

float

get_bounds(query=None, frame=None)

Return bounds for subscene defined through nodes selected by query.

Parameters:

query (list[str] or str) – A list, string, or regular expression referring to a subset of all geometry of this scene, or list of objects. None means entire scene. Defaults to None.
frame (str, optional) – The reference frame to use. None means scene’s base frame is used. Defaults to None.

Returns:

A 2x3 matrix of minimum and maximum coordinates for each dimension.

Return type:

np.ndarray

get_extents(query=None, frame=None)

Return extents for subscene defined through nodes selected by query.

Parameters:

query (list[str] or str) – A list, string, or regular expression referring to a subset of all geometry of this scene, or list of objects. None means entire scene. Defaults to None.
frame (str, optional) – The reference frame to use. None means scene’s base frame is used. Defaults to None.

Returns:

A 3-vector describing the extents of each dimension.

Return type:

np.ndarray

get_center_mass(query=None, frame=None)

Return center of mass for subscene defined through nodes selected by query.

Parameters:

query (list[str] or str) – A list, string, or regular expression referring to a subset of all geometry of this scene, or list of objects. None means entire scene. Defaults to None.
frame (str, optional) – The reference frame to use. None means scene’s base frame is used. Defaults to None.

Returns:

A 3-vector describing the center of mass of the queried subscene.

Return type:

np.ndarray

get_centroid(query=None, frame=None)

Return centroid for subscene defined through nodes selected by query.

Parameters:

query (list[str] or str) – A list, string, or regular expression referring to a subset of all geometry of this scene, or list of objects. None means entire scene. Defaults to None.
frame (str, optional) – The reference frame to use. None means scene’s base frame is used. Defaults to None.

Returns:

A 3-vector describing the centroid of the queried subscene.

Return type:

np.ndarray

get_reference_frame(xyz, query=None, frame=None)

Return reference frame for subscene defined through nodes selected by query.

Parameters:

xyz (tuple[str]) – A 3-tuple/list of [‘top’, ‘center’, ‘bottom’, ‘com’, ‘centroid’]
query (list[str] or str) – A list, string, or regular expression referring to a subset of all geometry of this scene, or list of objects. None means entire scene. Defaults to None.
frame (str, optional) – The reference frame to use. None means scene’s base frame is used. Defaults to None.

Raises:

ValueError – Unknown reference string.

Returns:

A 4x4 homogenous matrix.

Return type:

np.ndarray

remove_object(obj_id_regex)

Remove object(s) from the scene.

Parameters:: obj_id_regex (str) – A regular expression (or just an object identifier). All objects that match this string will be removed.
Raises:: ValueError – No object identifier matches the regular expression string.

collapse_nodes(keep_object_root_nodes=True)

Remove nodes from the scene graph that do not have geometries attached and no adjacent edges with joints.

Parameters:: keep_object_root_nodes (bool, optional) – Whether to keep nodes that are object roots. Defaults to True. Note: USD export relies on a node with the same name as the object. The result could create a graph that can’t be exported to USD, if keep_object_root_nodes=False.

rename_joints(mappings)

Rename joints in the scene graph.

Parameters:: mappings (list[(str, str)]) – List of tuples of joints to be renamed and their new names respectively.

rename_nodes(mappings)

Rename nodes in the scene graph.

Parameters:: mappings (list[(str, str)]) – List of tuples of nodes to be renamed and their new names respectively.

rename_geometries(mappings)

Rename geometries in the scene graph.

Parameters:: mappings (list[(str, str)]) – List of tuples of nodes to be renamed and their new names respectively.

topological_sorted_object_nodes()

Returns a list of object node names that is ordered topologically: Leaf –> …. –> Root (scene.base_frame).

Returns:: List of object node names in topolical order.
Return type:: list(str)

flatten(): Flatten the scene graph such that all object nodes are children of the base_frame.

simplify_node_names(): Change node names such that all names of the format {namespace}/{identifier} are simplified to {namespace} if only one node with this namespace exists.

add_walls(dimensions, thickness=0.15, overhang=0.0, offset=0.0, hole_extents=(0, 0), hole_offset=(0, 0), use_primitives=True, object_ids=None, use_collision_geometry=True, joint_type=None)

Add walls/box assets to any combination of the six faces of the scene volume.

Parameters:

dimensions (list[str]) – In which dimension to add a wall. Any subset of [‘x’, ‘-x’, ‘y’, ‘-y’, ‘z’, ‘-z’].
thickness (float, optional) – Thickness of the wall. Defaults to 0.15.
overhang (float, optional) – The amount of overhang of the wall. Can be a single scalar or a len(dimensions)-dim list. Defaults to 0.0.
offset (float, optional) – The distance between wall and closest scene geometry. Can be a single scalar or a len(dimensions)-dim list. Defaults to 0.0.
hole_extents (list[float], optional) – 2-dim extents of the hole in the wall. Defaults to (0, 0).
hole_offset (tuple[float], optional) – 2-dim position offset of the hole in the wall. Defaults to (0, 0).
use_primitives (bool, optional) – Whether to create a mesh or use a primitive. Defaults to True.
object_ids (list[str], optional) – A list of object names used for adding walls, needs to have same length as dimensions. If None, names will be “wall_{dim}”. Defaults to None
use_collision_geometry (bool, optional) – Defaults to True.
joint_type (str, optional) – Defaults to None.

Raises:

ValueError – If overhang is not a float, or a list of length len(dimensions).
ValueError – If object_ids is not None and len(object_ids) != len(dimensions).

distance_matrix_geometry(nodes_geometry=None, return_names=False)

Calculate pair-wise distances of the specified geometries in the scene.

Parameters:

nodes_geometry (list[str], optional) – List of geometry nodes to include. None includes all geometry nodes. Defaults to None.
return_names (bool, optional) – Whether to return the geometry node names that each row/column refers to. Defaults to False.

Returns:

NxN matrix of distances where N = len(nodes_geometry). list[str]: List of geometry node names that each row/column in the matrix refers to. Only returned if return_names == True.

Return type:

np.ndarray

connected_component_geometry(node_name, max_distance=1e-3, exclude_node_name=True)

Return the list of geometry nodes that are within a maximum distance of the geometry node node_name. Can be used to identify which geometries/objects are touching a specific one.

Parameters:

node_name (str, list[str]) – A single geometry node identifier or a list of identifiers.
max_distance (float, optional) – Maximum distance to be considered part of the same connected component. Defaults to 1e-3.
exclude_node_name (bool, optional) – Whether to exclude node_name(s) itself in the returned set. Defaults to True.

Raises:

ValueError – Raised if node_name is not a geometry node in the scene.

Returns:

The list of geometry nodes in the scene that are within max_distance of node_name.

Return type:

list[str]

connected_components_geometry(nodes_geometry=None, max_distance=1e-3)

Get all connected components of the specified list of geometry nodes. Can be used to identify “islands” of geometry touching each other.

Parameters:

nodes_geometry (list[str]) – A list of geometry nodes for which to compute the connected components.
max_distance (float, optional) – Maximum distance to be considered part of the same connected component. Defaults to 1e-3.

Returns:

A list of connected components.

Return type:

list[list[str]]

add_object(asset, obj_id=None, transform=None, translation=None, parent_id=None, connect_obj_id=None, connect_obj_anchor=None, connect_parent_id=None, connect_parent_anchor=None, joint_type='fixed', **kwargs)

Add a named object mesh to the scene.

Parameters:

asset (scene.Asset) – Asset to be added.
obj_id (str) – Name of the object. If None, automatically generates a string.
transform (np.ndarray) – Homogenous 4x4 matrix describing the objects pose in scene coordinates. If None, is identity. Defaults to None.
translation (list[float], tuple[float]) – 3-vector describing the translation of the object. Cannot be set together with transform. Defaults to None.
parent_id (str) – Name of the parent object/frame in the scene graph. Defaults to base frame of scene.
connect_obj_id (str) – Name of a geometry in the asset to which to which the connect_obj_anchor refers. If this is None, the entire object is considered.
connect_obj_anchor (tuple(str)) – ([“center”, “com”, “centroid”, “bottom”, “top”])*3 defining the coordinate origin of the object in all three dimensions (x, y, z).
connect_parent_id (str) – Name of an existing object in the scene next to which the new one will be added. If this is base_frame or None, all objects are considered.
connect_parent_anchor (tuple(str)) – ([“center”, “com”, “centroid”, “bottom”, “top”])*3 defining the coordinate origin of the parent subscene/object in all three dimensions (x, y, z).
joint_type (str, optional) – The type of joint that will be used to connect this object to the scene (“floating” or “fixed”). None has a similar effect as “fixed”. Defaults to “fixed”.
**use_collision_geometry (bool, optional) – Whether to use collision or visual geometry, or both (if None). Defaults to default_use_collision_geometry.

Returns:

obj_id of added object.

Return type:

str

add_object_without_collision(obj_id, obj_asset, obj_pose_iterator, max_attempts=300, **kwargs)

Add object without colliding with the exisiting scene.

This function is different from the place_object function since it is not restricted to place on a support surface.

Parameters:

obj_id (str) – Name of the object to place.
obj_asset (scene.Asset) – The asset that represents the object.
obj_pose_iterator – Iterator specifying the pose to place the object
max_attempts (int, optional) – Maximum number of attempts to find a placement pose. Defaults to 300.
**use_collision_geometry (bool, optional) – Whether to use collision or visual geometry or both. Defaults to default_use_collision_geometry.
**kwargs – Keyword arguments that will be delegated to add_object.

Returns:

Success.

Return type:

bool

get_geometries(query=None)

Returns a list of trimesh geometries associated with the query.

Parameters:: query (str) – A regular expression that gets matched against geometry names. None will include all geometries. Defaults to None.
Returns:: Geometries matching the query.
Return type:: List[trimesh.Trimesh]

get_geometry_names(query=None, obj_id=None)

Return all geometry node names associated with that object or all geometry node names in the scene.

Parameters:

query (str or list[str]) – A geometry name or list of names or regular expression. None will include all geometries if obj_id is also None. Defaults to None.
obj_id (str, optional) – Object identifier. If None, and query is None entire scene is considered. Defaults to None.

Returns:

List of geometry names.

Return type:

list(str)

get_object_name(node_id)

Return object name given a scene graph node.

Parameters:: node_id (str) – Name of the scene graph node.
Returns:: Name of the object or None if not found.
Return type:: str

get_object_names()

Return a list of all object names in the scene.

Returns:: List of object names.
Return type:: list[str]

get_object_nodes(obj_id)

Return list of scene graph nodes pertaining to this object.

Parameters:: obj_id (str) – Name of the object.
Returns:: A list of graph nodes that this object consists of.
Return type:: list[str]

get_object_graph()

Get a subgraph that only contains nodes of objects and the scene’s base frame.

Returns:: The object graph of the scene.
Return type:: nx.networkx.Graph

get_links(nodes=None)

Return a partioning of the scene graph into nodes pertaining to the same link, their root, and list of joints between the links.

Parameters:: nodes (list[str]) – Nodes of scene graph to consider. If None, considers entire scene graph. Defaults to None.
Returns:: List of sets of nodes, each set representing a link. list[str]: List of root nodes, one per link. list[(str, str, dict]: List of joints.
Return type:: list[set[str]]

get_object_transforms(frame_from=None)

Return a dictionary of all object’s transformations.

Parameters:: frame_from (str, optional) – The frame in which the transforms are returned. Defaults to None which is the graph’s base_frame.
Returns:: A dictionary with obj_id’s as keys and homogeneous matrices as values.
Return type:: dict[str, np.ndarray]

get_transform(node, frame_from=None)

Returns the transform of node node.

Parameters:

node (str) – Node identifier.
frame_from (str) – Node identifier.

Returns:

4x4 homogeneous matrix transformation

Return type:

np.ndarray

set_transform(node, frame_from, transform)

Set the transform between nodes node and frame_from. Only allows setting transforms for existing edges in the scene graph.

Parameters:

node (str) – Node identifier.
frame_from (str) – Node identifier.
transform (np.ndarray) – 4x4 homogeneous matrix transformation.

Raises:

ValueError – Raise error if there is no edge in the scene graph between the nodes.

get_transforms(nodes=None, frames_from=None)

Return a list of all or a subset of all transformations in the scene graph.

Parameters:

nodes (list[str]) – List of node identifiers. None means all. Defaults to None.
frames_from (list[str]) – List of node identifiers. None means all. Defaults to None.

Returns:

A list of transformations with tuples of the form (parent [str], child [str], attr [dict]).

Return type:

list

set_transforms(transforms, only_update_existing=False)

Sets the transforms in the scene. Inverse of get_transforms().

Parameters:

only_update_existing (bool) – Only update transforms that already exist in the scene. Defaults to False.
transforms (list) – A list of transformations with tuples of the form (parent [str], child [str], attr [dict]).

set_joint_configuration(configuration, obj_id=None, joint_ids=None)

Set configuration of articulated objects, indiviual joints, or for the entire scene at once. If obj_id and joint_ids are specified the joint names will be a concatenation of obj_id and joint_ids.

Note: This is the same as update_configuration

Parameters:

configuration (list[float]) – New configuration value(s).
obj_id (str, optional) – Object identifier to configure. If None and joint_ids=None, all joints in the scene are expected to be updated. Defaults to None.
joint_ids (list[str], optional) – List of joint names to update. If None, all joints of the object are expected to be updated. Defaults to None.

Raises:

ValueError – The obj_id is not part of the scene.
ValueError – The joint_ids doe not exist.
ValueError – The len(configuration) does not match the object’s number of joints.
ValueError – The len(configuration) does not match len(joint_ids) if joint_ids is specified.
ValueError – The len(configuration) does not match the number of joints in the scene if neither obj_id nor joint_ids are specified.

Examples

>>> s = synth.Scene()
>>> s.add_object(pa.RefrigeratorAsset.random(), 'fridge')
>>> s.get_joint_names()
>>> s.set_joint_configuration([1, 0.5])
>>> s.set_joint_configuration([1, 0.5], obj_id='fridge')
>>> s.set_joint_configuration([1], joint_ids=['fridge/door_joint'])
>>> s.set_joint_configuration([1], obj_id='fridge', joint_ids=['door_joint'])

update_configuration(configuration, obj_id=None, joint_ids=None)

Set configuration of articulated objects, indiviual joints, or for the entire scene at once. If obj_id and joint_ids are specified the joint names will be a concatenation of obj_id and joint_ids.

Parameters:

configuration (list[float]) – New configuration value(s).
obj_id (str, optional) – Object identifier to configure. If None and joint_ids=None, all joints in the scene are expected to be updated. Defaults to None.
joint_ids (list[str], optional) – List of joint names to update. If None, all joints of the object are expected to be updated. Defaults to None.

Raises:

ValueError – The obj_id is not part of the scene.
ValueError – The joint_ids doe not exist.
ValueError – The len(configuration) does not match the object’s number of joints.
ValueError – The len(configuration) does not match len(joint_ids) if joint_ids is specified.
ValueError – The len(configuration) does not match the number of joints in the scene if neither obj_id nor joint_ids are specified.

Examples

>>> s = synth.Scene()
>>> s.add_object(pa.RefrigeratorAsset.random(), 'fridge')
>>> s.get_joint_names()
>>> s.update_configuration([1, 0.5])
>>> s.update_configuration([1, 0.5], obj_id='fridge')
>>> s.update_configuration([1], joint_ids=['fridge/door_joint'])
>>> s.update_configuration([1], obj_id='fridge', joint_ids=['door_joint'])

get_joint_names(obj_id=None, include_fixed_floating_joints=False, joint_type_query=None)

Return list of joint names for an object or the entire scene. The order of this list is the same as the values of get_configuration.

Parameters:

obj_id (str, optional) – Name of the object. If None will return all joint names in the scene. Defaults to None.
include_fixed_floating_joints (bool, optional) – Whether to include fixed and floating joints. Defaults to False.
joint_type_query (str/regex or tuple, optional) – Filter for specific joint types. Will override include_fixed_floating_joints if not None. Defaults to None.

Returns:

List of joint names that belong to this articulated object, or of entire scene. Empty if no such object exists or object/scene is not articulated.

Return type:

list[str]

is_articulated(obj_id=None)

Check if object or scene is articulated, i.e., has joints.

Parameters:: obj_id (str, optional) – Name of the object. If None, will check entire scene. Defaults to None.
Returns:: True if object/scene is articulated.
Return type:: bool

get_joint_properties(obj_id=None, include_fixed_floating_joints=False)

Return joint properties of scene or specific object in scene.

Parameters:

obj_id (str, optional) – Object identifier. If none, entire scene is considered. Defaults to None.
include_fixed_floating_joints (bool, optional) – Whether to include fixed and floating joints. Defaults to False.

Returns:

A dictionary with properties of each joint.

Return type:

dict

update_joint_properties(joint_id, **kwargs)

Update the properties of a joint.

Parameters:

joint_id (str) – Name of the joint to update.
**q (float, optional) – Configuration of the joint.
**type (str, optional) – Type of the joint.
**origin (np.ndarray, optional) – Homogenous matrix representing origin of joint.
**axis (list[float], optional) – Axis of the joint.
**limit_velocity (float, optional) – Joint velocity limit.
**limit_effort (float, optional) – Joint effort limit.
**limit_lower (float, optional) – Lower joint limit.
**limit_upper (float, optional) – Upper joint limit.
**stiffness (float, optional) – Joint stiffness. Will add a drive to the joint during USD export.
**damping (float, optional) – Joint damping. Will add a drive to the joint during USD export.

Raises:

ValueError – Error raised if property is unknown.

get_joint_limits(obj_id=None, joint_ids=None)

Return upper and lower joint limits.

Parameters:

obj_id (str, optional) – Only consider a specific object in the scene. Defaults to None.
joint_ids (list[str], optional) – Only consider certain joints. Defaults to None.

Returns:

Nx2 array of lower and upper limits for N joints.

Return type:

np.ndarray

set_joint_zero_configuration(obj_id=None, joint_ids=None)

This sets the zero configuration of a joint by using its current configuration. I.e., the current configuration will be the new zero configuration and joint limits are adapted accordingly.

Parameters:

obj_id (str, optional) – Only consider a specific object in the scene. Defaults to None.
joint_ids (list[str], optional) – Only consider certain joints. Defaults to None.

get_joint_types(obj_id=None, joint_ids=None, include_fixed_floating_joints=False)

Return joint types.

Parameters:

obj_id (str, optional) – Only consider a specific object in the scene. Defaults to None.
joint_ids (list[str], optional) – Only consider certain joints. Defaults to None.
include_fixed_floating_joints (bool, optional) – Whether to include fixed and floating joints. Defaults to False.

Returns:

A list of joint types. In the same order as get_joint_names.

Return type:

list[str]

set_joint_types(joint_types, obj_id=None, joint_ids=None, include_fixed_floating_joints=False)

Change the type of a joint. Note, this is mostly helpful for changing between floating, fixed, or no (None) joints. Since other types of joints (e.g. prismatic, revolute) also require additional properties (e.g. axis, origin). If a joint type is set to None this will internally call the remove_joint function.

Parameters:

joint_types (list[str]) – List of desired joint types.
obj_id (str, optional) – Only consider a specific object in the scene. Defaults to None.
joint_ids (list[str], optional) – Only consider certain joints. Defaults to None.
include_fixed_floating_joints (bool, optional) – Whether to include fixed and floating joints. Defaults to False.

Raises:

ValueError – The length of joint_types does not match the number of joints queried through obj_id, joint_ids, and include_fixed_floating_joints.
ValueError – The joint_types contain an unknown type of joint.

zero_configurations(): Set all articulations to the zero configuration.

lower_configurations(): Set all articulations to their lower limit configuration.

upper_configurations(): Set all articulations to their upper limit configuration.

random_configurations(): Randomize all joint configurations, within their limits.

get_configuration(obj_id=None, joint_ids=None)

Return value(s) of joint configuration(s) of object obj_id and joint name joint_ids, or for the entire scene if both are None.

Parameters:

obj_id (str, optional) – Object identifier. If None will use full joint_name qualifier. Defaults to None.
joint_ids (str, List[str], optional) – Joint identifier(s). If None will return list of values belonging to this object. Defaults to None.

Returns:

Joint configuration.

Return type:

np.ndarray

add_joint(parent_node, child_node, name, type, **kwargs)

Add a new joint to the scene.

Parameters:

parent_node (str) – Parent node in the scene graph.
child_node (str) – Child node in the scene graph.
name (str) – Identifier of the joint. Should be of the form <obj_id>/<joint_id>.
type (str) – ‘revolute’, ‘prismatic’, ‘floating’, or ‘fixed’.
**q (float, optional) – Configuration of the joint. Defaults to 0.0.
**origin (np.ndarray, optional) – Homogenous matrix representing origin of joint. Defaults to self.get_transform(frame_to=child_node, frame_from=parent_node).
**axis (list[float], optional) – Axis of the joint. Defaults to [1, 0, 0].
**limit_velocity (float, optional) – Joint velocity limit. Defaults to None.
**limit_effort (float, optional) – Joint effort limit. Defaults to None.
**limit_lower (float, optional) – Lower joint limit. Defaults to None.
**limit_upper (float, optional) – Upper joint limit. Defaults to None.
**stiffness (float, optional) – Joint stiffness. Defaults to None.
**damping (float, optional) – Joint damping. Defaults to None.

Raises:

ValueError – If name already exists.
ValueError – If type is not one of the predefined ones.
ValueError – If there’s no edge in the scene graph between parent_node and child_node.
ValueError – If there’s already a joint in the scene graph between parent_node and child_node.

remove_joints(joint_query)

Remove one or more joint from the scene.

Parameters:: joint_query (str or list) – Identifier of joint(s). Can be a regex.
Raises:: ValueError – Joint doesn’t exist.

find_joint(node_name, include_fixed_floating_joints=False)

Find first joint in kinematic tree, going from node_name to the root of the tree.

Parameters:

node_name (str) – Name of the node in the scene graph / kinematic tree.
include_fixed_floating_joints (bool, optional) – Whether to consider joints of type ‘fixed’ or ‘floating’. Defaults to False.

Returns:

Name of joint found. None if no joint was found.

Return type:

str

get_joint_parent_child_node(joint_id)

Return parent and child node of scene graph with joint attribute.

Parameters:: joint_id (str) – Name of the joint.
Raises:: ValueError – Joint with this name doesn’t exist.
Returns:: Tuple of parent and child node.
Return type:: (str, str)

stack_box(obj_id, thickness, stack_parent_obj_ids=None, offset=0.0, direction='z', joint_type='fixed')

Add a named box mesh to the scene by stacking it next to an existing object.

Parameters:

obj_id (str) – Name of the box.
thickness (float) – Box extent along the stacking direction.
stack_parent_obj_ids (list[str], optional) – List of names of existing objects in the scene next to which the box will be placed. Also defines the dimensions of the box. If None all existing objects in the scene will be considered. Defaults to None.
offset (float, optional) – Distance between stacked objects. Defaults to 0.0.
direction (str, optional) – Either ‘x’, ‘-x’, ‘y’, ‘-y’, ‘z’, or ‘-z’. Defines along which direction to stack the box. Defaults to ‘z’.
joint_type (str, optional) – The type of joint that will be used to connect this object to the scene (“floating” or “fixed”). None has a similar effect as “fixed”. Defaults to “fixed”.

Returns:

obj_id of added box.

Return type:

str

create_surface_coverage_test(max_surface_coverage=0.9, **kwargs)

Creates a test for whether a surface is covered.

Parameters:

max_surface_coverage (float, optional) – The maximum fraction of the surface that can be covered.
**kwargs – Keyword arguments that will be delegated to _estimate_surface_coverage.

Returns:

Boolean function that tests whether a surface is covered.

Return type:

function

label_part(label, geometry_name_regex)

Label specific geometries in the scene based on a regular expression of the name in the scene graph.

Parameters:

label (str) – A label for a part.
geometry_name_regex (str) – A regular expression. All matched scene geometries will be referenced to this labeled part.

Returns:

Returns all geometry names in the scene that match the regular expression.

Return type:

list[str]

add_containment(label, parent_node_name, transform, extents)

Add box containment. Can be used for sampling poses.

Parameters:

label (str) – Identifier of the containment.
parent_node_name (str) – Name of the scene graph node this containment will be attached to.
transform (np.ndarray) – 4x4 homogeneous matrix.
extents (np.ndarray, list) – 3-dimensional vector representing the box size.

label_containment(label, min_area=0.01, min_volume=0.00001, gravity=np.array([0, 0, -1.0]), gravity_tolerance=0.1, erosion_distance=0.02, distance_above_support=0.001, **kwargs)

Label containers in the scene. This is done by selecting support surfaces of the scene geometry and extruding volumes along the gravity direction until collision. Collision checking is done via sampling ray casts and might be imperfect depending on parameter settings. All parameters of the label_support function apply.

Parameters:

label (str) – Identifier of the container volume.
min_area (float, optional) – Minimum support area of the container. Defaults to 0.01.
min_volume (float, optional) – Minimum volume of the container. Defaults to 0.00001.
gravity (np.ndarray, optional) – Gravity direction of support surface and extrusion direction of container. Defaults to np.array([0, 0, -1.0]).
gravity_tolerance (float, optional) – Tolerance for gravity vector when selecting support surfaces. Defaults to 0.1.
erosion_distance (float, optional) – Erosion distance of support surface. Defaults to 0.02.
distance_above_support (float, optional) – Offset of container above support surface. Defaults to 0.001.
**obj_ids (str) – Regular expression of object identifiers to use for finding supports.
**geom_ids (str) – Regular expression of geometry identifiers to use for finding supports.
**min_area (float) – Minimum area of support facets [m^2]. Defaults to 0.01.
**min_x (float) – Minimum x coordinate in scene.
**min_y (float) – Minimum y coordinate in scene.
**min_z (float) – Minimum z coordinate in scene.
**max_x (float) – Maximum x coordinate in scene.
**max_y (float) – Maximum y coordinate in scene.
**max_z (float) – Maximum z coordinate in scene.

Returns:

Container volume description.

Return type:

scene.Container

label_support(label, gravity=np.array([0, 0, -1.0]), gravity_tolerance=0.1, erosion_distance=0.02, layer='collision', **kwargs)

Gives one or multiple support areas in the scene a string identifier which can be used for e.g. placement.

Parameters:

label (str) – String identifier.
gravity ([np.ndarray], optional) – Gravity vector in scene coordinates. Defaults to np.array([0, 0, -1.0]).
gravity_tolerance (float, optional) – Tolerance for comparsion between surface normals and gravity vector (dot product). Defaults to 0.5.
erosion_distance (float, optional) – Clearance from support surface edges. Defaults to 0.02.
layer (str, optional) – Layer name to search for support geometries. Defaults to ‘collision’.
**obj_ids (str) – Regular expression of object identifiers to use for finding supports.
**geom_ids (str) – Regular expression of geometry identifiers to use for finding supports.
**min_area (float) – Minimum area of support facets [m^2]. Defaults to 0.01.
**consider_support_polyhedra (bool) – If set to True, will sample raycasts to ensure support surface has a “roof”. Can be used to exclude top surfaces in shelves.
**min_x (float) – Minimum x coordinate in scene.
**min_y (float) – Minimum y coordinate in scene.
**min_z (float) – Minimum z coordinate in scene.
**max_x (float) – Maximum x coordinate in scene.
**max_y (float) – Maximum y coordinate in scene.
**max_z (float) – Maximum z coordinate in scene.

Returns:

List of support polygons. list[np.ndarray]: List of homogenous 4x4 matrices describing the polygon poses in scene coordinates. list[str]: List of node names that represent the reference frames for the transformations. list[int]: List of facet indices of the mesh that form the support polygon.

Return type:

list[trimesh.path.polygons.Polygon]

in_collision(return_names=False, return_data=False, ignore_object_self_collisions=False, ignore_penetration_depth=None)

Check if any pair of geometries in the scene collide with one another.

Parameters:

return_names (bool, optional) – If true, a set is returned containing the names of all pairs of geometries in collision. Defaults to False.
return_data (bool, optional) – If true, a list of ContactData is returned as well. Defaults to False.
ignore_object_self_collisions (bool, optional) – If true, any pair of colliding geometries that belongs to the same object is ignored. Defaults to False.
ignore_penetration_depth (float, optional) – Any collisions whose penetration depth is lower than this number is ignored. If None, nothing is ignored. Defaults to None.

Returns:

True if a collision occurred between any pair of geometry in the scene and False otherwise. list[tuple[str, str]]: The set of pairwise collisions. Each tuple contains two names in alphabetical order indicating that the two corresponding geometries are in collision. Only returned if return_names = True. list[fcl.Contact]: List of all contacts detected. Only returned if return_data = True.

Return type:

bool

in_collision_single(mesh, transform, min_distance=0.0, epsilon=1.0 / 1e3)

Check whether the scene is in collision with mesh. Optional: Define a minimum distance.

Parameters:

mesh (trimesh.Scene) – Object Trimesh model to test with scene.
transform (np.ndarray) – Pose of the object mesh as a 4x4 homogenous matrix.
min_distance (float, optional) – Minimum distance that is considered in collision. Defaults to 0.0.
epsilon (float, optional) – Epsilon for minimum distance check. Defaults to 1.0/1e3.

Returns:

Whether the object mesh is colliding with anything in the scene.

Return type:

bool

in_collision_other(other_manager, min_distance=0.0, epsilon=1.0 / 1e3, return_names=False, return_data=False)

Check whether the scene is in collision with another collision manager. Optional: Define a minimum distance.

Parameters:

other_manager (trimesh.collision.CollisionManager) – Collision manager to test against.
min_distance (float, optional) – Minimum distance that is considered in collision. Defaults to 0.0.
epsilon (float, optional) – Epsilon for minimum distance check. Defaults to 1.0/1e3.
return_names (bool, optional) – If true, a set is returned containing the names of all pairs of objects in collision. Defaults to false
return_data (bool, optional) – If true, a list of ContactData is returned as well. Defaults to False.

Returns:

Whether the object mesh is colliding with anything in the scene. set[2-tuples]: Set of 2-tuples of pairwaise collisions. list[ContactData]: List of contacts.

Return type:

bool

container_generator(container_ids=None, sampling_fn=itertools.cycle)

A generator for iterating through the scene’s labelled containers.

Parameters:

container_ids (list[str] or str, optional) – A list or single container identifier. None will use all labelled containers. Defaults to None.
sampling_fn (fn, optional) – An iterator to be applied to the list of containers. Defaults to itertools.cycle.

Returns:

The resulting generator over a list of scene.Container.

Return type:

fn[scene.Container]

support_generator(support_ids=None, sampling_fn=itertools.cycle)

A generator for iterating through the scene’s labelled support surfaces.

Parameters:

support_ids (list[str] or str, optional) – A list or single support surface identifier. None will use all labelled surfaces. Defaults to None.
sampling_fn (fn, optional) – An iterator to be applied to the list of support surfaces. Defaults to itertools.cycle.

Returns:

The resulting generator over a list of scene.SupportSurface.

Return type:

fn[scene.SupportSurface]

place_object(obj_id, obj_asset, support_id=None, parent_id=None, obj_position_iterator=None, obj_orientation_iterator=None, obj_support_id_iterator=None, max_iter=100, distance_above_support=0.001, joint_type='floating', valid_placement_fn=lambda obj_asset, support, placement_T: ..., **kwargs)

Add object by placing it in a non-colliding pose on top of a support surface or inside a container.

Parameters:

obj_id (str) – Name of the object to place.
obj_asset (scene.Asset) – The asset that represents the object to be placed.
support_id (str, optional) – Defines the support that will be used for placing. Defaults to None.
parent_id (str) – Name of the object in the scene on which to place the object. Or None if any support surface works. Defaults to None.
obj_position_iterator (iterator, optional) – Iterator for sampling object positions in the support frame. Defaults to PositionIteratorUniform.
obj_orientation_iterator (iterator, optional) – Iterator for sampling object orientation in the object asset frame. Defaults to utils.orientation_generator_uniform_around_z.
obj_support_id_iterator (iterator, optional) – Iterator for sampling ids for support surface or container. Defaults to None.
max_iter (int, optional) – Maximum number of attempts to find a placement pose. Defaults to 100.
distance_above_support (float, optional) – Distance the object mesh will be placed above the support surface. Defaults to 0.0.
joint_type (str, optional) – The type of joint that will be used to connect this object to the scene (“floating” or “fixed”). None has a similar effect as “fixed”. Defaults to “floating”.
valid_placement_fn (function, optional) – Function for testing valid placements. Defaults to returning True.
**use_collision_geometry (bool, optional) – Defaults to default_use_collision_geometry.
**kwargs – Keyword arguments that will be delegated to add_object.

Raises:

RuntimeError – In case the support_id does not exist.

Returns:

Success.

Return type:

bool

property keep_collision_manager_synchronized

Whether collision manager synchronization (after each object add or removal) is off or on.

Returns:: Whether collision manager synchronization is off or on.
Return type:: bool

synchronize_collision_manager(reset=False)

Synchronize the collision manager with the scene.

Parameters:: reset (bool, optional) – Wheter to create BvH’s from scratch. Defaults to False.

collision_manager()

Return a collision manager for this scene.

Returns:: A collision manager of the scene.
Return type:: trimesh.collision.CollisionManager

place_objects(obj_id_iterator, obj_asset_iterator, obj_support_id_iterator, obj_position_iterator, obj_orientation_iterator, parent_id=None, max_iter=100, max_iter_per_support=10, distance_above_support=0.002, joint_type='floating', valid_placement_fn=lambda obj_asset, support, placement_T: ..., debug=False, **kwargs)

Add objects and place them in a non-colliding pose on top of a support surface or inside a container.

Parameters:

obj_id_iterator (iterator) – Iterator for sampling name of the object to place.
obj_asset_iterator (iterator) – Iterator for sampling asset to be placed.
obj_support_id_iterator (iterator, optional) – Iterator for sampling ids for support surface or container. Defaults to None.
obj_position_iterator (iterator, optional) – Iterator for sampling object positions in the support frame.
obj_orientation_iterator (iterator, optional) – Iterator for sampling object orientation in the object asset frame.
parent_id (str) – Name of the node in the scene graph at which to attach the object. Or None if same as support node. Defaults to None.
max_iter (int, optional) – Maximum number of attempts to find a placement pose. Defaults to 100.
max_iter_per_support (int, optional) – Maximum number of attempts per support surface. Defaults to 10.
distance_above_support (float, optional) – Distance the object mesh will be placed above the support surface. Defaults to 0.002.
joint_type (str, optional) – The type of joint that will be used to connect this object to the scene (“floating” or “fixed”). None has a similar effect as “fixed”. Defaults to “floating”.
valid_placement_fn (function, optional) – Function for testing valid placements. Defaults to returning True.
debug (bool, optional) – In case the placement is not valide, this will show a window with a scene with the attempted object placement. Defaults to False.
**use_collision_geometry (bool, optional) – Defaults to default_use_collision_geometry.
**kwargs – Keyword arguments that will be delegated to add_object.

Returns:

Success.

Return type:

bool

asset(obj_id=None, try_to_remove_base_frame=True, **kwargs)

Create an asset of this scene or an object in the scene. Works well in conjuction with subscene.

Parameters:

obj_id (str, optional) – If None, takes the entire scene. Defaults to None.
try_to_remove_base_frame (bool, optional) – Remove root node if possible. Defaults to True.

Returns:

The scene as an asset.

Return type:

TrimeshAsset or TrimeshSceneAsset

move_object(obj_id, support_id=None, obj_support_id_iterator=None, **kwargs)

Move existing object in scene by placing it in a non-colliding pose on top of a support surface. Internally, creates another asset from the existing object, removes the existing object, and places the asset again.

Parameters:

obj_id (str) – Name of the object to move.
support_id (str, optional) – Defines the support that will be used for placing. Defaults to None.
obj_support_id_iterator (iterator, optional) – Iterator for sampling ids for support surface or container. Defaults to None.
**kwargs (optional) – Arguments delegated to place_object(..).

Raises:

ValueError – The obj_id is not part of the scene.

subscene(obj_ids, base_frame=None)

Return a part of the scene, made from a sub-graph of the original scene graph.

Parameters:

obj_ids (list[str]) – Objects to be included in the subscene.
base_frame (str, optional) – The base frame of the resulting subscene. If None, it’s the same as the base frame of self.

Raises:

ValueError – The base_frame doesn’t exist in the scene.
ValueError – The subgraphs overlap each other.

Returns:

A new scene that contains a subset of the original objects.

Return type:

trimesh.Scene

colorize(specific_objects={}, specific_geometries={}, color=None, reset_visuals=True, **kwargs)

Colorize meshes.

Parameters:

specific_objects (dict, optional) – A dictionary of object id’s to be colored. Defaults to {}.
color (list[float]) – The RGB color to be used. If None, a random color will be chosen. Defaults to None.
reset_visuals (bool, optional) – Whether to overwrite existing visuals of a geometry such as textures. Defaults to True.
**brightness – Brightness of color. Defaults to 1.0.
**transparency – Transparency of color. Defaults to 1.0.

Returns:

The colorized scene.

Return type:

scene.Scene

colorize_support(color=[0, 255, 0, 255])

Colorize faces of meshes that belong to support areas.

Parameters:: color (list[float], optional) – Color. Defaults to [0, 255, 0, 255].
Returns:: The colorized scene.
Return type:: scene.Scene

colorize_parts(color=[0, 255, 0, 255])

Colorize geometries that belong to parts.

Parameters:: color (list[float], optional) – Color. Defaults to [0, 255, 0, 255].
Returns:: The colorized scene.
Return type:: scene.Scene

remove_visuals(): Remove all texture and color visuals. Objects in scene will be gray.

get_colors()

Returns a dictionary of geometry identifiers and their the main color. Can be used in combination with colorize(specific_geometries={}).

Returns:: Dictionary of geometry names and associated main color.
Return type:: dict[str, np.ndarray]

get_visuals()

Returns the visual elements (color, texture) of all scene geometries. This is handy to store a color scheme for later reuse.

Note

Do not use this across different scenes! The visuals contain face/vertex-specific information and are tied to the original geometry.

Returns:: Dictionary of geometry names and associated visuals.
Return type:: dict[str, trimesh.visual.color.Visuals]

set_visuals(visuals)

Sets the visual elements (color, texture) of geometries in the scene. This is handy to reproduce a previous color scheme.

Note

Do not apply visuals from a different scene! The visuals contain face/vertex-specific information and are tied to the original geometry.

Parameters:: visuals (dict[str, trimesh.visual.color.Visuals]) – Dictionary of geometry names and associated visuals.

support_scene(support_id_query=None, layer='support', color=None, use_path_geometry=False, extruded_polygon_height=1e-3, **kwargs)

Return a trimesh.Scene that only contains the scene’s labelled supports.

Parameters:

support_id_query (str or list or regex, optional) – A string, list, or regular expression that refers to support IDs. None means all supports. Defaults to None.
layer (str, optional) – The new geometry will be part of a new layer of this name. Defaults to “support”.
color (list[int], optional) – An RGBA value defining the geometry’s color. If none, random colors will be chosen. Defaults to None.
use_path_geometry (bool, optional) – Whether to use a trimesh.path.Path3D or an extruded polygon (trimesh.Trimesh) as geometry. Defaults to False (trimesh.Trimesh).
extruded_polygon_height (bool, optional) – If use_path_geometry=False this defines the height of the extrusion. Defaults to 1e-3.
**kwargs – Additional keyword arguments that will be piped to _support_scene.

Returns:

A trimesh scene with labelled supports.

Return type:

trimesh.Scene

add_supports_as_layer(support_id_query=None, layer='support', color=None, add_to_base_frame=True, use_path_geometry=False, extruded_polygon_height=1e-3, **kwargs)

Add all supports as geometries to the scene and put them into a layer.

Parameters:

support_id_query (str or list or regex, optional) – A string, list, or regular expression that refers to support IDs. None means all supports. Defaults to None.
layer (str, optional) – The new geometry will be part of a new layer of this name. Defaults to “support”.
color (list[int], optional) – An RGBA value defining the geometry’s color. If none, random colors will be chosen. Defaults to None.
add_to_base_frame (bool, optional) – Whether to add the supports to the scene’s base frame or their original nodes. Defaults to True.
use_path_geometry (bool, optional) – Whether to use a trimesh.path.Path3D or an extruded polygon (trimesh.Trimesh) as geometry. Defaults to False (trimesh.Trimesh).
extruded_polygon_height (bool, optional) – If use_path_geometry=False this defines the height of the extrusion. Defaults to 1e-3.
**kwargs – Additional keyword arguments that will be piped to _support_scene.

container_scene(container_id_query=None, layer='container', color=None)

Return a trimesh.Scene that only contains the scene’s labelled containers.

Parameters:

container_id_query (str or list or regex, optional) – A string, list, or regular expression that refers to container IDs. None means all containers. Defaults to None.
layer (str, optional) – The new geometry will be part of a new layer of this name. Defaults to “container”.
color (list[int], optional) – An RGBA value defining the geometry’s color. If none, random colors will be chosen. Defaults to None.

Returns:

A trimesh scene with labelled containers.

Return type:

trimesh.Scene

add_containers_as_layer(container_id_query=None, layer='container', color=None, add_to_base_frame=True)

Add all containers as geometries to the scene and put them into a layer.

Parameters:

container_id_query (str or list or regex, optional) – A string, list, or regular expression that refers to container IDs. None means all containers. Defaults to None.
layer (str, optional) – The new geometry will be part of a new layer of this name. Defaults to “container”.
color (list[int], optional) – An RGBA value defining the geometry’s color. If none, random colors will be chosen. Defaults to None.
add_to_base_frame (bool, optional) – Whether to add the containers to the scene’s base frame or their original nodes. Defaults to True.

part_scene(part_id_query=None, layer='part', color=None)

Return a trimesh.Scene that only contains the scene’s labelled parts.

Parameters:

part_id_query (str or list or regex, optional) – A string, list, or regular expression that refers to part IDs. None means all parts. Defaults to None.
layer (str, optional) – The new geometry will be part of a new layer of this name. Defaults to “part”.
color (list[int], optional) – An RGBA value defining the geometry’s color. If none, random colors will be chosen. Defaults to None.

Returns:

The scene with parts.

Return type:

trimesh.Scene

add_parts_as_layer(part_id_query=None, layer='part', color=None, add_to_base_frame=True)

Add all parts as geometries to the scene and put them into a layer.

Parameters:

part_id_query (str or list or regex, optional) – A string, list, or regular expression that refers to part IDs. None means all parts. Defaults to None.
layer (str, optional) – The new geometry will be part of a new layer of this name. Defaults to “part”.
color (list[int], optional) – An RGBA value defining the geometry’s color. If none, random colors will be chosen. Defaults to None.
add_to_base_frame (bool, optional) – Whether to add the parts to the scene’s base frame or their original nodes. Defaults to True.

show_graph(layers=None, with_labels=True, edge_color='lightgrey', edge_color_joint='cyan', edge_color_joint_fixed='orange', edge_color_joint_floating='blue', edge_color_joint_prismatic='green', edge_color_joint_revolute='red', edge_color_joint_continuous='brown', node_color='lightgreen', font_size=10, node_size=80, **kwargs)

Plots the scene graph. Nicer layout than scene.graph.show().

But requires networkx and pygraphviz: sudo apt-get install graphviz graphviz-dev python -m pip install pygraphviz

Parameters:

layers (list[str], optional) – Which layers to show. None means every layer. Defaults to None.
with_labels (bool, optional) – Whether to display node names. Defaults to True.
edge_color (str, optional) – Color of graph edges. Defaults to “lightgrey”.
edge_color_joint (str, optional) – Color of graph edges that constitute a joint. Defaults to “cyan”.
edge_color_joint_fixed (str, optional) – Color of graph edges that constitute a fixed joint. Defaults to “orange”.
edge_color_joint_floating (str, optional) – Color of graph edges that constitute a floating joint. Defaults to “blue”.
edge_color_joint_prismatic (str, optional) – Color of graph edges that constitute a prismatic joint. Defaults to “green”.
edge_color_joint_revolute (str, optional) – Color of graph edges that constitute a revolute joint. Defaults to “red”.
edge_color_joint_continuous (str, optional) – Color of graph edges that constitute a continuous joint. Defaults to “brown”.
node_color (str, optional) – Color of graph nodes. Defaults to “lightgreen”.
font_size (int, optional) – Font size of node names. Defaults to 10.
node_size (int, optional) – Size of graph nodes. Defaults to 40.
**kwargs – Keyword arguments that will be delegated to nx.draw().

show_supports(support_id_query=None, layers=None, color=None, use_path_geometry=False, extruded_polygon_height=1e-3)

Show labelled supports in trimesh viewer, optionally on top of scene.

Note: If only supports need to be shown, use argument layers=[‘support’].

Parameters:

support_id_query (str or list or regex, optional) – A string, list, or regular expression that refers to support IDs. None means all supports. Defaults to None.
layers (list[str], optional) – A list of visible layer names. If None everything will be visible. Defaults to None.
color (list[int], optional) – An RGBA value used to color the supports. If None, random color is chosen. Defaults to None.
use_path_geometry (bool, optional) – Whether to use a trimesh.path.Path3D or an extruded polygon (trimesh.Trimesh) as geometry. Defaults to False (trimesh.Trimesh).
extruded_polygon_height (bool, optional) – If use_path_geometry=False this defines the height of the extrusion. Defaults to 1e-3.

show_containers(container_id_query=None, layers=None, color=None)

Show labelled containers in trimesh viewer, optionally on top of scene.

Note: If only containers need to be shown, use argument layers=[‘container’].

Parameters:

container_id_query (str or list or regex, optional) – A string, list, or regular expression that refers to container IDs. None means all containers. Defaults to None.
layers (list[str], optional) – A list of visible layer names. If None everything will be visible. Defaults to None.
color (list[int], optional) – An RGBA value used to color the parts. If None, random color is chosen. Defaults to None.

show_parts(part_id_query=None, layers=None, color=None)

Show labelled parts in trimesh viewer, optionally on top of scene.

Note: If only parts need to be shown, use argument layers=[‘part’].

Parameters:

part_id_query (str or list or regex, optional) – A string, list, or regular expression that refers to part IDs. None means all parts. Defaults to None.
layers (list[str], optional) – A list of visible layer names. If None everything will be visible. Defaults to None.
color (list[int], optional) – An RGBA value used to color the parts. If None, random color is chosen. Defaults to None.

show(layers=None, other_scene=None)

Show scene using the trimesh viewer.

Parameters:

layers (list[str], optional) – Filter to show only certain layers, e.g. ‘visual’ or ‘collision’. Defaults to None, showing everything.
other_scene (trimesh.Scene, optional) – Another trimesh scene that will be appended to the scene itself. Defaults to None.

Returns:

The viewer.

Return type:

trimesh.viewer.windowed.SceneViewer

save_image(fname, resolution=[1920, 1080], visible=True, camera_transform=None, camera_rotation=None, **kwargs)

Save image of the current scene.

Parameters:

fname (str) – Filename, including ending. If fname == ‘bytes’ the raw png bytes will be returned.
resolution (list, optional) – Resolution of the stored image. Defaults to [1920, 1080].
visible (bool, optional) – Whether to open the viewer during saving. This can avoid problems sometimes. Defaults to True.
camera_transform (np.ndarray, optional) – The 4x4 homogeneous matrix that represents the pose of the virtual camera which takes the image. This can be used to create images from the exact same viewpoint. Defaults to None.
camera_rotation (np.ndarray, optional) – Just the 3x3 rotation part of the homogeneous matrix. Defaults to None.

Returns:

The raw png bytes are returned if fname == ‘bytes’. They can be turned into a PIL Image object via:: image = PIL.Image.open(io.BytesIO(image_data))

Return type:

image_data (bytes)

get_layer_names()

Return the names of all layers that are currently present in the graph. Also returns None as an element, if a geometry is missing the layer metadata.

Returns:: A set of all layer names in the graph.
Return type:: set

set_layer_name(name, existing_layer=None)

Sets the layer name of all geometries. Or renames an existing layer.

Parameters:

name (str) – New layer name.
existing_layer (str, optional) – If set only geometries belonging to this layer will be changed. Effectively renames an existing layer. Defaults to None.

remove_layer(name)

Remove all geometries that belong to a specific layer.

Parameters:: name (str) – Name of the layer to be removed.

add_convex_decomposition(input_layer=None, output_layer='collision')

Add convex geometries for all geometries in a particular layer. Uses trimesh’s VHACD interface.

Parameters:

input_layer (str, optional) – Name of layer whose geometries will be decomposed. None considers all geometries.
output_layer (str, optional) – Name of layer convex geometries will belong to. Defaults to “collision”.

add_voxel_decomposition(input_layer, output_layer='voxels', pitch=0.01)

Add voxels for all geometries in a particular layer. Note, that these voxels will not be aligned to a common grid, but with each geometry’s coordinate system.

Parameters:

input_layer (str) – Name of layer whose geometries will be voxelized. None considers all geometries.
output_layer (list, optional) – Name of layer voxels will belong to. Defaults to “voxels”.
pitch (float, optional) – Edge length of a single voxel. Defaults to 0.01.

add_bounding_boxes(input_layer, output_layer='bboxes')

Add aligned bounding boxes for all geometries in a particular layer.

Parameters:

input_layer (str) – Name of layer whose geometries will be used to calculate bounding boxes. None considers all geometries.
output_layer (str, optional) – Name of layer bounding boxes will belong to. Defaults to “bboxes”.

add_bounding_boxes_oriented(input_layer, output_layer='obb')

Add oriented bounding boxes for all geometries in a particular layer.

Parameters:

input_layer (str) – Name of layer whose geometries will be used to calculate bounding boxes. None considers all geometries.
output_layer (str, optional) – Name of layer bounding boxes will belong to. Defaults to “obb”.

add_bounding_cylinders(input_layer, output_layer='bcylinders')

Add bounding cylinders for all geometries in a particular layer.

Parameters:

input_layer (str) – Name of layer whose geometries will be used to calculate bounding cylinders. None considers all geometries.
output_layer (str, optional) – Name of layer bounding cylinders will belong to. Defaults to “bcylinders”.

add_bounding_spheres(input_layer, output_layer='bspheres')

Add bounding spheres for all geometries in a particular layer.

Parameters:

input_layer (str) – Name of layer whose geometries will be used to calculate bounding spheres. None considers all geometries.
output_layer (str, optional) – Name of layer bounding spheres will belong to. Defaults to “bspheres”.

add_bounding_primitives(input_layer, output_layer='bprimitive')

Add bounding primitives (cylinder, sphere, box - chose the one with smallest volume) for all geometries in a particular layer.

Parameters:

input_layer (str) – Name of layer whose geometries will be used to calculate bounding primitives. None considers all geometries.
output_layer (str, optional) – Name of layer bounding primitives will belong to. Defaults to “bprimitive”.

add_convex_hulls(input_layer, output_layer='chull')

Add convex hulls for all geometries in a particular layer.

Parameters:

input_layer (str) – Name of layer whose geometries will be used to calculate convex hulls. None considers all geometries.
output_layer (str, optional) – Name of layer convex hulls will belong to. Defaults to “chull”.

explode(distance, direction=None, origin=None)

Explode the current scene in-place around a point and vector.

Parameters:

vector ((3,) float or float) – Explode radially around a direction vector or spherically
origin ((3,) float) – Point to explode around

Return type:

None

classmethod load(fname)

Loads scene from file.

Parameters:: fname (str) – File name of scene. Currently only json is supported. (generate via export(…))
Returns:: The loaded scene object.
Return type:: scene.Scene

remove_lights(): Remove all lights in the scene. Note, that lights might even exist without explicitly adding them (added automatically).

unwrap_geometries(query=None)

Adds uv textures to geometries. Primitives will be converted to meshes. the vertices have been assigned uv texture coordinates. Vertices may be duplicated by the unwrapping algorithm. This uses xatlas internally (requires pip install xatlas).

Parameters:: query (str or list[str]) – A geometry name or list of names or regular expression. None will include all geometries. Defaults to None.

export(fname=None, file_type=None, **kwargs)

Export scene as either: glb, gltf, obj, stl, ply, dict, json, urdf, usd, or usda.

Parameters:

fname (str, optional) – Filename. If None, data is returned instead of written to disk. Defaults to None.
file_type (str, optional) – File format. If file_type is None, the type is deducted from the filename. If fname is None, file_type needs to be specified.
**kwargs (optional) – The export is highly configurable, each format has different parameters and flags. For details, see the format-specific docstrings in exchange.export_*.

Returns:

If fname is None, data will be returned in the specified file_type.

Return type:

str or bytes or dict (optional)