blenderproc.types package

Module contents

class blenderproc.types.Armature(bpy_object)

Bases: Entity

An armature object, which can be connected with Link objects to other armature objects.

It enables the transformation of different objects.

_clip_value_from_constraint(value, constraint_name, axis)

Checks if an axis is constraint, and clips the value to the min/max of this constraint. If the constraint does not exist, nothing is done.

Parameters:

• value (float) – Value to be clipped.

• constraint_name (str) – Name of the constraint.

• axis (str) – Axis to check.

Return type:

float

Returns:

Clipped value if a constraint is set, else the initial value.

_determine_rotation_axis()

Determines the single rotation axis and checks if the constraints are set well to have only one axis of freedom.

Returns:

The single rotation axis (‘X’, ‘Y’ or ‘Z’).

add_constraint_if_not_existing(constraint_name)

Adds a new constraint if it doesn’t exist, and returns the specified constraint.

Parameters:

constraint_name (str) – Name of the desired constraint.

Return type:

Constraint

get_constraint(constraint_name)

Returns the desired constraint if existing; otherwise None.

Parameters:

constraint_name (str) – Name of the constraint.

Return type:

Optional[Constraint]

Returns:

Constraint if it exists; else None.

get_location_constraint()

Returns the location constraint if existing; otherwise None.

Return type:

Optional[Constraint]

Returns:

Location constraint if it exists; else None.

get_rotation_constraint()

Returns the rotation constraint if existing; otherwise None.

Return type:

Optional[Constraint]

Returns:

Rotation constraint if it exists; else None.

hide(hide_object=True)

Sets the visibility of the object.

Parameters:

hide_object (bool) – Determines whether the object should be hidden in rendering.

remove_constraint(constraint_key)

Removes a specified constraint.

Parameters:

constraint_key (str) – Key to be removed.

remove_constraints()

Removes all constraints of the armature.

set_location_constraint(x_limits=None, y_limits=None, z_limits=None)

Sets location constraints on the armature’s bone.

Parameters:

• x_limits (Optional[List[float]]) – A list of two float values specifying min/max values along the x-axis or None if no constraint should be applied.

• y_limits (Optional[List[float]]) – A list of two float values specifying min/max values along the y-axis or None if no constraint should be applied.

• z_limits (Optional[List[float]]) – A list of two float values specifying min/max values along the z-axis or None if no constraint should be applied.

set_rotation_constraint(x_limits=None, y_limits=None, z_limits=None)

Sets rotation constraints on the armature’s bone.

Parameters:

• x_limits (Optional[List[float]]) – A list of two float values specifying min/max radiant values along the x-axis or None if no constraint should be applied.

• y_limits (Optional[List[float]]) – A list of two float values specifying min/max radiant values along the y-axis or None if no constraint should be applied.

• z_limits (Optional[List[float]]) – A list of two float values specifying min/max radiant values along the z-axis or None if no constraint should be applied.

set_rotation_euler(rotation_euler, frame=None, mode='absolute')

Rotates the armature based on euler angles. Validate values with given constraints.

Parameters:

• rotation_euler (Union[float, list, Euler, ndarray]) – The amount of rotation (in radians). Either three floats for x, y and z axes, or a single float. In the latter case, the axis of rotation is derived based on the rotation constraint. If these are not properly set (i.e., two axes must have equal min/max values) an exception will be thrown.

• frame (Optional[int]) – Keyframe where to insert the respective rotations.

• mode (str) – One of [“absolute”, “relative”]. For absolute rotations we clip the rotation value based on the constraints. For relative, we don’t - this will result in inverse motion after the constraint’s limits have been reached.

class blenderproc.types.Entity(bpy_object)

Bases: Struct

The entity class of all objects which can be placed inside the scene. They have a 6D pose consisting of location and rotation.

apply_T(transform)

Apply the given transformation to the pose of the entity.

Parameters:

transform (Union[ndarray, Matrix]) – A 4x4 matrix representing the transformation.

clear_parent()

Removes the object’s parent and moves the object into the root level of the scene graph.

delete(remove_all_offspring=False)

Deletes the entity and maybe all of its offspring

Parameters:

remove_all_offspring (bool) – If this is True all children and their children are recursively deleted

deselect()

Deselects the entity.

duplicate(duplicate_children=True, linked=False)

Duplicates the object.

Parameters:

• duplicate_children (bool) – If True, also all children objects are recursively duplicated.

• linked (bool) – If True, object data is not copied.

Return type:

Entity

Returns:

A new mesh object, which is a duplicate of this object.

get_children(return_all_offspring=False)

Returns the children objects.

Parameters:

return_all_offspring (bool) – If this is True all children and their children are recursively found and returned

Return type:

List[Entity]

Returns:

A list of all children objects.

get_local2world_mat()

Returns the pose of the object in the form of a local2world matrix.

Return type:

ndarray

Returns:

The 4x4 local2world matrix.

get_location(frame=None)

Returns the location of the entity in 3D world coordinates.

Parameters:

frame (Optional[int]) – The frame number which the value should be set to. If None is given, the current frame number is used.

Return type:

ndarray

Returns:

The location at the specified frame.

get_parent()

Returns the parent of the entity.

Return type:

Optional[Entity]

Returns:

The parent.

get_rotation(frame=None)

Returns the rotation of the entity in euler angles.

Parameters:

frame (Optional[int]) – The frame number which the value should be set to. If None is given, the current frame number is used.

Return type:

ndarray

Returns:

The rotation at the specified frame.

get_rotation_euler(frame=None)

Returns the rotation of the entity in euler angles.

Parameters:

frame (Optional[int]) – The frame number which the value should be set to. If None is given, the current frame number is used.

Return type:

ndarray

Returns:

The rotation at the specified frame.

get_rotation_mat(frame=None)

Gets the rotation matrix of the entity.

Parameters:

frame (Optional[int]) – The frame number which the value should be set to. If None is given, the current frame number is used.

Return type:

ndarray

Returns:

The 3x3 local2world rotation matrix.

get_scale(frame=None)

Returns the scale of the entity along all three axes.

Parameters:

frame (Optional[int]) – The frame number which the value should be set to. If None is given, the current frame number is used.

Return type:

ndarray

Returns:

The scale at the specified frame.

hide(hide_object=True)

Sets the visibility of the object.

Parameters:

hide_object (bool) – Determines whether the object should be hidden in rendering.

is_empty()

Returns whether the entity is from type “EMPTY”.

Return type:

bool

Returns:

True, if its an empty.

is_hidden()

Returns whether the object is hidden in rendering.

Return type:

bool

Returns:

True, if it is hidden.

select()

Selects the entity.

set_local2world_mat(matrix_world)

Sets the pose of the object in the form of a local2world matrix.

Parameters:

matrix_world (Union[ndarray, Matrix]) – A 4x4 matrix.

set_location(location, frame=None)

Sets the location of the entity in 3D world coordinates.

Parameters:

• location (Union[list, Vector, ndarray]) – The location to set.

• frame (Optional[int]) – The frame number which the value should be set to. If None is given, the current frame number is used.

set_parent(new_parent)

Sets the parent of this object.

Parameters:

new_parent (Entity) – The parent entity to set.

set_rotation_euler(rotation_euler, frame=None)

Sets the rotation of the entity in euler angles.

Parameters:

• rotation_euler (Union[list, Euler, ndarray]) – The euler angles to set.

• frame (Optional[int]) – The frame number which the value should be set to. If None is given, the current frame number is used.

set_rotation_mat(rotation_mat, frame=None)

Sets the rotation of the entity using a rotation matrix.

Parameters:

• rotation_mat (Union[Matrix, ndarray]) – The 3x3 local to world rotation matrix.

• frame (Optional[int]) – The frame number which the value should be set to. If None is given, the current frame number is used.

set_scale(scale, frame=None)

Sets the scale of the entity along all three axes.

Parameters:

• scale (Union[list, ndarray, Vector]) – The scale to set.

• frame (Optional[int]) – The frame number which the value should be set to. If None is given, the current frame number is used.

update_blender_ref(name)

Updates the contained blender reference using the given name of the instance.

Parameters:

name (str) – The name of the instance which will be used to update its blender reference.

class blenderproc.types.Light(light_type='POINT', name='light', blender_obj=None)

Bases: Entity

This class allows the creation and management of lights in the scene. However, we advise to use emissive materials on objects to light a scene as these produce more realistic light scenarios as the lighting does not directly start from a small point in space.

get_color(frame=None)

Returns the RGB color of the light.

Parameters:

frame (Optional[int]) – The frame number which the value should be set to. If None is given, the current frame number is used.

Return type:

Color

Returns:

The color at the specified frame.

get_distance(frame=None)

Returns the falloff distance of the light (point where light is half the original intensity).

Parameters:

frame (Optional[int]) – The frame number which the value should be set to. If None is given, the current frame number is used.

Return type:

float

Returns:

The falloff distance at the specified frame.

get_energy(frame=None)

Returns the energy of the light.

Parameters:

frame (Optional[int]) – The frame number which the value should be set to. If None is given, the current frame number is used.

Return type:

float

Returns:

The energy at the specified frame.

get_radius(frame=None)

Returns the radius / shadow_soft_size of the light.

Parameters:

frame (Optional[int]) – The frame number which the value should be set to. If None is given, the current frame number is used.

Return type:

float

Returns:

The radius at the specified frame.

get_type(frame=None)

Returns the type of the light.

Parameters:

frame (Optional[int]) – The frame number which the value should be set to. If None is given, the current frame number is used.

Return type:

str

Returns:

The type at the specified frame.

set_color(color, frame=None)

Sets the color of the light.

Parameters:

• color (Union[list, Color]) – The rgb color to set.

• frame (Optional[int]) – The frame number which the value should be set to. If None is given, the current frame number is used.

set_distance(distance, frame=None)

Sets the falloff distance of the light = point where light is half the original intensity.

Parameters:

• distance (float) – The falloff distance to set.

• frame (Optional[int]) – The frame number which the value should be set to. If None is given, the current frame number is used.

set_energy(energy, frame=None)

Sets the energy of the light.

Parameters:

• energy (float) – The energy to set. If the type is SUN this value is interpreted as Watt per square meter, otherwise it is interpreted as Watt.

• frame (Optional[int]) – The frame number which the value should be set to. If None is given, the current frame number is used.

set_radius(radius, frame=None)

Sets the radius / shadow_soft_size of the light.

Parameters:

• radius (float) – Light size for ray shadow sampling (Raytraced shadows).

• frame (Optional[int]) – The frame number which the value should be set to. If None is given, the current frame number is used.

set_type(light_type, frame=None)

Sets the type of the light.

Parameters:

• light_type (str) – The type to set, can be one of [POINT, SUN, SPOT, AREA].

• frame (Optional[int]) – The frame number which the value should be set to. If None is given, the current frame number is used.

setup_as_projector(pattern, frame=None)

Sets a spotlight source as projector of a pattern image. Sets location and angle of projector to current camera. Adjusts scale of pattern image to fit field-of-view of camera: where $F$ is focal length and $r$ aspect ratio. WARNING: This should be done after the camera parameters are set!

Parameters:

• pattern (ndarray) – pattern image to be projected onto scene as np.ndarray.

• frame (Optional[int]) – The frame number which the value should be set to. If None is given, the current frame number is used.

class blenderproc.types.Material(material)

Bases: Struct

The material class containing the texture and material properties, which are assigned to the surfaces of MeshObjects.

duplicate()

Duplicates the material.

Return type:

Material

Returns:

The new material which is a copy of this one.

get_node_connected_to_the_output_and_unlink_it()

Searches for the OutputMaterial in the material and finds the connected node to it, removes the connection between this node and the output and returns this node and the material_output

get_nodes_created_in_func(created_in_func)

Returns all nodes which are of the given node_type

Parameters:

created_in_func (str) – return all nodes created in the given function

Return type:

List[Node]

Returns:

The list of nodes with the given type.

get_nodes_with_type(node_type, created_in_func='')

Returns all nodes which are of the given node_type

Parameters:

• node_type (str) – The note type to look for.

• created_in_func (str) – only return nodes created by the specified function

Return type:

List[Node]

Returns:

The list of nodes with the given type.

get_principled_shader_value(input_name)

Gets the default value or the connected node socket to an input socket of the principled shader node of the material.

Parameters:

input_name (str) – The name of the input socket of the principled shader node.

Return type:

Union[float, NodeSocket]

Returns:

the connected socket to the input socket or the default_value of the given input_name

get_the_one_node_with_type(node_type, created_in_func='')

Returns the one node which is of the given node_type

This function will only work if there is only one of the nodes of this type.

Parameters:

• node_type (str) – The node type to look for.

• created_in_func (str) – only return node created by the specified function

Return type:

Node

Returns:

The node.

get_users()

Returns the number of users of the material.

Return type:

int

Returns:

The number of users.

infuse_material(material, mode='mix', mix_strength=0.5)

Infuse a material inside another material. The given material, will be adapted and the used material, will be added, depending on the mode either as add or as mix. This change is applied to all outputs of the material, this includes the Surface (Color) and also the displacement and volume. For displacement mix means multiply.

Parameters:

• material (Material) – Material to infuse.

• mode (str) – The mode determines how the two materials are mixed. There are two options “mix” in which the preexisting material is mixed with the selected one in “used_material” or “add” in which they are just added on top of each other. Available: [“mix”, “add”]

• mix_strength (float) – In the “mix” mode a strength can be set to determine how much of each material is going to be used. A strength of 1.0 means that the new material is going to be used completely.

infuse_texture(texture, mode='overlay', connection='Base Color', texture_scale=0.05, strength=0.5, invert_texture=False)

Overlays the selected material with a texture, this can be either a color texture like for example dirt or it can be a texture, which is used as an input to the Principled BSDF of the given material.

Parameters:

• texture (Texture) – A texture which should be infused in the material.

• mode (str) – The mode determines how the texture is used. There are three options: “overlay” in which the selected texture is overlayed over a preexisting one. If there is none, nothing happens. The second option: “mix” is similar to overlay, just that the textures are mixed there. The last option: “set” replaces any existing texture and is even added if there was none before.

• connection (str) – By default the “Base Color” input of the principled shader will be used. This can be changed to any valid input of a principled shader. Default: “Base Color”. For available check the blender documentation.

• texture_scale (float) – The used texture can be scaled down or up by a factor, to make it match the preexisting UV mapping. Make sure that the object has a UV mapping beforehand.

• strength (float) – The strength determines how much the newly generated texture is going to be used.

• invert_texture (bool) – It might be sometimes useful to invert the input texture, this can be done by setting this to True.

insert_node_instead_existing_link(source_socket, new_node_dest_socket, new_node_src_socket, dest_socket)

Replaces the node between source_socket and dest_socket with a new node.

Before: source_socket -> dest_socket After: source_socket -> new_node_dest_socket and new_node_src_socket -> dest_socket

Parameters:

• source_socket (NodeSocket) – The source socket.

• new_node_dest_socket (NodeSocket) – The new destination for the link starting from source_socket.

• new_node_src_socket (NodeSocket) – The new source for the link towards dest_socket.

• dest_socket (NodeSocket) – The destination socket

link(source_socket, dest_socket)

Creates a new link between the two given sockets.

Parameters:

• source_socket (NodeSocket) – The source socket.

• dest_socket (NodeSocket) – The destination socket

make_emissive(emission_strength, replace=False, emission_color=None, non_emissive_color_socket=None)

Makes the material emit light.

Parameters:

• emission_strength (float) – The strength of the emitted light.

• replace (bool) – When replace is set to True, the existing material will be completely replaced by the emission shader, otherwise it still looks the same, while emitting light.

• emission_color (Optional[List[float]]) – The color of the light to emit. Default: Color of the original object.

• non_emissive_color_socket (Optional[NodeSocket]) – An output socket that defines how the material should look like. By default, that is the output of the principled shader node. Has no effect if replace is set to True.

map_vertex_color(layer_name='Col', active_shading=True)

Maps existing vertex color to the base color of the principled bsdf node or a new background color node.

Parameters:

• layer_name (str) – Name of the vertex color layer. Type: string.

• active_shading (bool) – Whether to keep the principled bsdf shader. If True, the material properties influence light reflections such as specularity, roughness, etc. alter the object’s appearance. Type: bool.

new_node(node_type, created_in_func='')

Creates a new node in the material’s node tree.

Parameters:

• node_type (str) – The desired type of the new node.

• created_in_func (str) – Save the function name in which this node was created as a custom property. Allows to later retrieve and delete specific nodes again.

Return type:

Node

Returns:

The new node.

remove_emissive()

Remove emissive part of the material.

remove_node(node)

Removes the node from the material’s node tree.

Parameters:

node (Node) – The node to remove.

set_displacement_from_principled_shader_value(input_name, multiply_factor)

Connects the node that is connected to the specified input of the principled shader node with the displacement output of the material.

Parameters:

• input_name (str) – The name of the input socket of the principled shader node.

• multiply_factor (float) – A factor by which the displacement should be multiplied.

set_principled_shader_value(input_name, value)

Sets value of an input to the principled shader node.

Parameters:

• input_name (str) – The name of the input socket of the principled shader node.

• value (Union[float, Image, NodeSocket]) – The value to set. Can be a simple value to use as default_value, a socket which will be connected to the input or an image which will be used for a new TextureNode connected to the input.

unlink(source_socket, dest_socket)

Removes the link between the two given sockets.

Parameters:

• source_socket (NodeSocket) – The source socket.

• dest_socket (NodeSocket) – The destination socket

update_blender_ref(name)

Updates the contained blender reference using the given name of the instance.

Parameters:

name – The name of the instance which will be used to update its blender reference.

class blenderproc.types.MeshObject(bpy_object)

Bases: Entity

Every instance of this class is a mesh which can be rendered in the scene. It can have multiple materials and different configurations of vertices with faces and edges.

add_displace_modifier(texture, mid_level=0.5, strength=0.1, min_vertices_for_subdiv=10000, subdiv_level=2)

Adds a displace modifier with a texture to an object.

If the mesh has less than min_vertices_for_subdiv vertices, also a subdivision modifier is added.

Parameters:

• texture (Texture) – The texture that will be used to displace the vertices.

• mid_level (float) – Texture value that gives no displacement. Parameter of displace modifier.

• strength (float) – Amount to displace geometry. Parameter of displace modifier.

• min_vertices_for_subdiv (int) – Checks if a subdivision is necessary. If the vertices of a object are less than ‘min_vertices_for_subdiv’ a Subdivision modifier will be add to the object.

• subdiv_level (int) – Numbers of Subdivisions to perform when rendering. Parameter of Subdivision modifier.

add_geometry_nodes()

Adds a new geometry nodes modifier to the object.

add_material(material)

Adds a new material to the object.

Parameters:

material (Material) – The material to add.

add_modifier(name, **kwargs)

Adds a new modifier to the object.

Parameters:

• name (str) – The name/type of the modifier to add.

• kwargs – Additional attributes that should be set to the modifier.

add_uv_mapping(projection, overwrite=False)

Adds a UV mapping to the object based on the given projection type.

Parameters:

• projection (str) – The kind of projection to use. Available: [“cube, “cylinder”, “smart”, “sphere”].

• overwrite (bool) – If True, the uv mapping will be changed, even if the object already has an uv mapping.

build_convex_decomposition_collision_shape(vhacd_path, temp_dir=None, cache_dir='blenderproc_resources/decomposition_cache')

Builds a collision shape of the object by decomposing it into near convex parts using V-HACD

Parameters:

• vhacd_path (str) – The directory in which vhacd should be installed or is already installed.

• temp_dir (Optional[str]) – The temp dir to use for storing the object files created by v-hacd.

• cache_dir (str) – If a directory is given, convex decompositions are stored there named after the meshes hash. If the same mesh is decomposed a second time, the result is loaded from the cache and the actual decomposition is skipped.

clear_materials()

Removes all materials from the object.

create_bvh_tree()

Builds a bvh tree based on the object’s mesh.

Return type:

BVHTree

Returns:

The new bvh tree

disable_rigidbody()

Disables the rigidbody element of the object

edit_mode()

Switch into edit mode of this mesh object

enable_rigidbody(active, collision_shape='CONVEX_HULL', collision_margin=0.001, collision_mesh_source='FINAL', mass=None, mass_factor=1, friction=0.5, angular_damping=0.1, linear_damping=0.04)

Enables the rigidbody component of the object which makes it participate in physics simulations.

Parameters:

• active (bool) – If True, the object actively participates in the simulation and its key frames are ignored. If False, the object still follows its keyframes and only acts as an obstacle, but is not influenced by the simulation.

• collision_shape (str) – Collision shape of object in simulation. Default: ‘CONVEX_HULL’. Available: ‘BOX’, ‘SPHERE’, ‘CAPSULE’, ‘CYLINDER’, ‘CONE’, ‘CONVEX_HULL’, ‘MESH’, ‘COMPOUND’.

• collision_margin (float) – The margin around objects where collisions are already recognized. Higher values improve stability, but also make objects hover a bit.

• collision_mesh_source (str) – Source of the mesh used to create collision shape. Default: ‘FINAL’. Available: [‘BASE’, ‘DEFORM’, ‘FINAL’].

• mass (Optional[float]) – The mass in kilogram the object should have. If None is given the mass is calculated based on its bounding box volume and the given mass_factor.

• mass_factor (float) – Scaling factor for mass. This is only considered if the given mass is None. Defines the linear function mass=bounding_box_volume*mass_factor (defines material density).

• friction (float) – Resistance of object to movement.

• angular_damping (float) – Amount of angular velocity that is lost over time.

• linear_damping (float) – Amount of linear velocity that is lost over time.

get_bound_box(local_coords=False)

Return type:

ndarray

Returns:

8x3 array describing the object aligned bounding box coordinates in world coordinates

get_bound_box_volume()

Gets the volume of the object aligned bounding box.

Return type:

float

Returns:

volume of a bounding box.

get_materials()

Returns the materials used by the mesh.

Return type:

List[Optional[Material]]

Returns:

A list of materials.

get_mesh()

Returns the blender mesh of the object.

Return type:

Mesh

Returns:

The mesh.

get_origin()

Returns the origin of the object.

Return type:

ndarray

Returns:

The origin in world coordinates.

get_rigidbody()

Returns the rigid body component

Return type:

Optional[RigidBodyObject]

Returns:

The rigid body component of the object.

has_materials()

Returns True if the object has material slots. This does not necessarily mean any Material is assigned to it.

Return type:

bool

Returns:

True if the object has material slots.

has_rigidbody_enabled()

Checks whether object has rigidbody element enabled

Return type:

bool

Returns:

True if object has rigidbody element enabled

has_uv_mapping()

Returns whether the mesh object has a valid uv mapping.

join_with_other_objects(objects)

Joins the given list of objects with this object.

Does not change the global selection. The given object-references become invalid after the join operation.

Parameters:

objects (List[MeshObject]) – List of objects which will be merged with this object

mesh_as_bmesh(return_copy=False)

Returns a bmesh based on the object’s mesh.

Independent of return_copy, changes to the returned bmesh only take into effect after calling update_from_bmesh().

Parameters:

return_copy – If True, a copy of the objects bmesh will be returned, otherwise the bmesh owned by blender is returned (the object has to be in edit mode for that).

Return type:

BMesh

Returns:

The bmesh

mesh_as_trimesh()

Returns a trimesh.Trimesh instance of the MeshObject.

Return type:

Trimesh

Returns:

The object as trimesh.Trimesh.

move_origin_to_bottom_mean_point()

Moves the object center to bottom of the bounding box in Z direction and also in the middle of the X and Y plane, which then makes the placement easier.

new_material(name)

Creates a new material and adds it to the object.

Parameters:

name (str) – The name of the new material.

Return type:

Material

object_mode()

Switch back into object mode

persist_transformation_into_mesh(location=True, rotation=True, scale=True)

Apply the current transformation of the object, which are saved in the location, scale or rotation attributes to the mesh and sets them to their init values.

Parameters:

• location (bool) – Determines whether the object’s location should be persisted.

• rotation (bool) – Determines whether the object’s rotation should be persisted.

• scale (bool) – Determines whether the object’s scale should be persisted.

position_is_above_object(position, down_direction=None, check_no_objects_in_between=True)

Make sure the given position is straight above the given object.

If check_no_objects_in_between is True, this also checks that there are no other objects in between.

Parameters:

• position (Union[Vector, ndarray]) – The position to check.

• down_direction (Union[Vector, ndarray, None]) – A vector specifying the direction straight down. If None is given, a vector into -Z direction is used.

• check_no_objects_in_between – If True, it is also checked that no other objects are in between position and object.

Returns:

True, if a ray sent into negative z-direction starting from the position hits the object first.

ray_cast(origin, direction, max_distance=1.70141e+38)

Cast a ray onto evaluated geometry, in object space.

Parameters:

• origin (Union[Vector, list, ndarray]) – Origin of the ray, in object space.

• direction (Union[Vector, list, ndarray]) – Direction of the ray, in object space.

• max_distance (float) – Maximum distance.

Return type:

Tuple[bool, ndarray, ndarray, int]

Returns:

Whether the ray successfully hit the geometry The hit location of this ray cast, float array of 3 items in [-inf, inf] The face normal at the ray cast hit location, float array of 3 items in [-inf, inf] The face index, -1 when original data isn’t available, int in [-inf, inf]

replace_materials(material)

Replaces all materials of the object with the given new material.

Parameters:

material (Material) – A material that should exclusively be used as new material for the object.

scale_uv_coordinates(factor)

Scales the UV coordinates of an object by a given factor. Scaling with a factor greater than one has the effect of making the texture look smaller on the object.

Parameters:

factor (float) – The amount the UV coordinates will be scaled.

set_material(index, material)

Sets the given material at the given index of the objects material list.

Parameters:

• index (int) – The index to set the material to.

• material (Material) – The material to set.

set_origin(point=None, mode='POINT')

Sets the origin of the object.

This will not change the appearing pose of the object, as the vertex locations experience the inverse transformation applied to the origin.

Parameters:

• point (Union[list, ndarray, Vector, None]) – The point in world coordinates to which the origin should be set. This parameter is only relevant if mode is set to “POINT”.

• mode (str) – The mode specifying how the origin should be set. Available options are: [“POINT”, “CENTER_OF_MASS”, “CENTER_OF_VOLUME”]

Return type:

ndarray

Returns:

The new origin in world coordinates.

set_shading_mode(mode, angle_value=30)

Sets the shading mode of all faces of the object.

Parameters:

• mode (str) – Desired mode of the shading. Available: [“FLAT”, “SMOOTH”, “AUTO”]. Type: str

• angle_value (float) – Angle in degrees at which flat shading is activated in AUTO mode. Type: float

update_from_bmesh(bm, free_bm_mesh=True)

Updates the object’s mesh based on the given bmesh.

Parameters:

• bm (BMesh) – The bmesh to set.

• free_bm_mesh – If True and the given bmesh is not owned by blender, it will be deleted in the end.

Return type:

BMesh

class blenderproc.types.Struct(bpy_object)

Bases: object

The base class of all things in BlenderProc, this can be an Entity in the scene or a Material which is only applied to a MeshObject.

clear_all_cps()

Removes all existing custom properties the struct has.

del_cp(key)

Removes the custom property with the given key.

Parameters:

key (str) – The key of the custom property to remove.

get_all_cps()

Returns all custom properties as key, value pairs.

Return type:

Dict[str, Any]

Returns:

A dictionary of custom properties as key, value pairs

get_attr(attr_name)

Returns the value of the attribute with the given name.

Parameters:

attr_name (str) – The name of the attribute.

Return type:

Any

Returns:

The value of the attribute

get_cp(key, frame=None)

Returns the custom property with the given key.

Parameters:

• key (str) – The key of the custom property.

• frame (Optional[int]) – The frame number which the value should be set to. If None is given, the current frame number is used.

Return type:

Any

Returns:

The value of the custom property.

get_name()

Returns the name of the struct.

Return type:

str

Returns:

The name.

has_cp(key)

Return whether a custom property with the given key exists.

Parameters:

key (str) – The key of the custom property to check.

Return type:

bool

Returns:

True, if the custom property exists.

is_valid()

Check whether the contained blender reference is valid.

The reference might become invalid after an undo operation or when the referenced struct is deleted.

Returns:

True, if it is valid.

set_cp(key, value, frame=None)

Sets the custom property with the given key. The key can not be the same as any member over the stored blender object.

Keyframes can be only set for custom properties for the types int, float or bool.

Parameters:

• key (str) – The key of the custom property.

• value (Any) – The value to set.

• frame (Optional[int]) – The frame number which the value should be set to. If None is given, the current frame number is used.

set_name(name)

Sets the name of the struct.

Parameters:

name (str) – The new name.

class blenderproc.types.URDFObject(armature, links, xml_tree=None)

Bases: Entity

This class represents an URDF object, which is comprised of an armature and one or multiple links. Among others, it serves as an interface for manipulation of the URDF model.

_set_fk_ik_mode(mode='fk')

Sets the mode of the bone chain.

Parameters:

mode (str) – One of “fk” or “ik” for forward / inverse kinematic.

_set_ik_bone_constraint(bone)

Sets the ik bone constraint.

Parameters:

bone (PoseBone) – Bone to set as ik constraint bone.

_set_ik_bone_controller(bone)

Sets the ik bone controller.

Parameters:

bone (PoseBone) – Bone to set as ik control bone.

_set_ik_bone_offset(offset)

Sets the location offset between the control and constraint bone.

Parameters:

offset (Matrix) – The location offset.

_set_ik_link(ik_link)

Sets the ik link constraint.

Parameters:

ik_link (Optional[Link]) – Link to set as ik link.

_set_keyframe(name, frame=0)

Sets a keyframe for a specific name for all bones of all links, as well as the copy_rotation constraint for

revolute joints.

Parameters:

• name (str) – Name of the keyframe to be inserted.

• frame (int) – Where to insert the keyframe.

_switch_fk_ik_mode(mode='fk', keep_pose=True)

Switches between forward and inverse kinematics mode. Will do this automatically when switching between e.g.

set_rotation_euler_fk() and set_rotation_euler_ik().

Parameters:

• mode (str) – One of for forward / inverse kinematik.

• keep_pose (bool) – If specified, will keep the pose when switching modes. Otherwise, will return to the old pose of the previously selected mode.

create_ik_bone_controller(link=None, relative_location=None, use_rotation=True, chain_length=0)

Creates an ik bone controller and a corresponding constraint bone for the respective link.

Parameters:

• link (Optional[Link]) – The link to create an ik bone for. If None, will use the last link.

• relative_location (Union[List[float], Vector, None]) – Relative location of the ik bone controller w.r.t. the bone’s location. This can be used to shift the point of control further away from the end effector.

• use_rotation (bool) – Whether to rotate the child links as well. Defaults to True.

• chain_length (int) – The number of parent links which are influenced by this ik bone. Defaults to 0 for all parents.

get_all_collision_local2world_mats()

Returns all transformations from the world frame to the collision objects.

Return type:

array

Returns:

Numpy array of shape (num_bones, 4, 4).

get_all_collision_objs()

Returns a list of all collision objects.

Return type:

List[MeshObject]

Returns:

List of all collision objects.

get_all_inertial_local2world_mats()

Returns all transformations from the world frame to the inertial objects.

Return type:

array

Returns:

Numpy array of shape (num_bones, 4, 4).

get_all_inertial_objs()

Returns a list of all inertial objects.

Return type:

List[Inertial]

Returns:

List of all inertial objects.

get_all_local2world_mats()

Returns all matrix_world matrices from every joint.

Return type:

array

Returns:

Numpy array of shape (num_bones, 4, 4).

get_all_urdf_objs()

Returns a list of all urdf-related objects.

Return type:

List[Union[Link, Inertial, MeshObject]]

Returns:

List of all urdf-related objects.

get_all_visual_local2world_mats()

Returns all transformations from world frame to the visual objects.

Return type:

array

Returns:

Numpy array of shape (num_bones, 4, 4).

get_all_visual_objs()

Returns a list of all visual objects.

Return type:

List[MeshObject]

Returns:

List of all visual objects.

get_links_with_revolute_joints()

Returns all revolute joints.

Return type:

List[Link]

Returns:

List of revolute joints.

has_reached_ik_pose(location_error=0.01, rotation_error=0.01)

Checks whether the urdf object was able to move to the currently set pose.

Parameters:

• location_error (float) – Tolerable location error in m.

• rotation_error (float) – Tolerable rotation error in radians.

Return type:

bool

Returns:

True if the link is at the desired ik pose; else False.

hide(hide_object=True)

Sets the visibility of the object.

Parameters:

hide_object (bool) – Determines whether the object should be hidden in rendering.

hide_links_and_collision_inertial_objs()

Hides links and their respective collision and inertial objects from rendering.

remove_link_by_index(index=0)

Removes a link and all its associated objects given an index. Also handles relationship of the link’s child

with its parent. This is useful for removing a ‘world link’ which could be a simple flat surface, or if someone wants to shorten the whole urdf object.

Parameters:

index (int) – Index of the joint to be removed.

set_ascending_category_ids(category_ids=None)

Sets semantic categories to the links and their associated objects.

Parameters:

category_ids (Optional[List[int]]) – List of ‘category_id’s for every link. If None, will create a list from [1 … len(links)].

set_location_ik(location, frame=0)

Performs location change in inverse kinematics mode.

Parameters:

• location (Union[List[float], array, Vector]) – Location vector.

• frame (int) – The keyframe where to insert the rotation.

set_rotation_euler_fk(link, rotation_euler, mode='absolute', frame=0)

Rotates one specific link or all links based on euler angles in forward kinematic mode. Validates values

with given constraints.

Parameters:

• link (Optional[Link]) – The link to be rotated. If None, will perform the rotation on all revolute joints.

• rotation_euler (Union[float, List[float], Euler, ndarray]) – The amount of rotation (in radians). Either three floats for x, y and z axes, or a single float. In the latter case, the axis of rotation is derived based on the rotation constraint. If these are not properly set (i.e., two axes must have equal min/max values) an exception will be thrown.

• mode (str) – One of [“absolute”, “relative”]. For absolute rotations we clip the rotation value based on the constraints. For relative we don’t - this will result in inverse motion after the constraint’s limits have been reached.

• frame (int) – The keyframe where to insert the rotation.

set_rotation_euler_ik(rotation_euler, mode='absolute', frame=0)

Performs rotation in inverse kinematics mode.

Parameters:

• rotation_euler (Union[float, List[float], Euler, ndarray]) – The amount of rotation (in radians). Either three floats for x, y and z axes, or a single float. In the latter case, the axis of rotation is derived based on the rotation constraint. If these are not properly set (i.e., two axes must have equal min/max values) an exception will be thrown.

• mode (str) – One of [“absolute”, “relative”]. For absolute rotations we clip the rotation value based on the constraints. For relative we don’t - this will result in inverse motion after the constraint’s limits have been reached.

• frame (int) – The keyframe where to insert the rotation.