blenderproc.python.types.MeshObjectUtility module

All mesh objects are captured in this class.

class blenderproc.python.types.MeshObjectUtility.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

blenderproc.python.types.MeshObjectUtility.compute_poi(objects)

Computes a point of interest in the scene. Point is defined as a location of the one of the selected objects that is the closest one to the mean location of the bboxes of the selected objects.

Parameters:

objects (List[MeshObject]) – The list of mesh objects that should be considered.

Return type:

ndarray

Returns:

Point of interest in the scene.

blenderproc.python.types.MeshObjectUtility.convert_to_meshes(blender_objects)

Converts the given list of blender objects to mesh objects

Parameters:

blender_objects (list) – List of blender objects.

Return type:

List[MeshObject]

Returns:

The list of meshes.

blenderproc.python.types.MeshObjectUtility.create_bvh_tree_multi_objects(mesh_objects)

Creates a bvh tree which contains multiple mesh objects.

Such a tree is later used for fast raycasting.

Parameters:

mesh_objects (List[MeshObject]) – The list of mesh objects that should be put into the BVH tree.

Return type:

BVHTree

Returns:

The built BVH tree.

blenderproc.python.types.MeshObjectUtility.create_from_blender_mesh(blender_mesh, object_name=None)

Creates a new Mesh object using the given blender mesh.

Parameters:

• blender_mesh (Mesh) – The blender mesh.

• object_name (Optional[str]) – The name of the new object. If None is given, the name of the given mesh is used.

Return type:

MeshObject

Returns:

The new Mesh object.

blenderproc.python.types.MeshObjectUtility.create_from_point_cloud(points, object_name, add_geometry_nodes_visualization=False)

Create a mesh from a point cloud.

The mesh’s vertices are filled with the points from the given point cloud.

Parameters:

• points (ndarray) – The points of the point cloud. Should be in shape [N, 3]

• object_name (str) – The name of the new object.

• add_geometry_nodes_visualization (bool) – If yes, a geometry nodes modifier is added, which adds a sphere to every point. In this way, the point cloud will appear in renderings.

Return type:

MeshObject

Returns:

The new Mesh object.

blenderproc.python.types.MeshObjectUtility.create_primitive(shape, **kwargs)

Creates a new primitive mesh object.

Parameters:

shape (str) – The name of the primitive to create. Available: [“CUBE”, “CYLINDER”, “CONE”, “PLANE”, “SPHERE”, “MONKEY”]

Return type:

MeshObject

Returns:

The newly created MeshObject

blenderproc.python.types.MeshObjectUtility.create_with_empty_mesh(object_name, mesh_name=None)

Creates an object with an empty mesh. :type object_name: str :param object_name: The name of the new object. :type mesh_name: Optional[str] :param mesh_name: The name of the contained blender mesh. If None is given, the object name is used. :rtype: MeshObject :return: The new Mesh object.

blenderproc.python.types.MeshObjectUtility.disable_all_rigid_bodies()

Disables the rigidbody element of all objects

blenderproc.python.types.MeshObjectUtility.get_all_mesh_objects()

Returns all mesh objects in scene

Return type:

List[MeshObject]

Returns:

List of all MeshObjects

blenderproc.python.types.MeshObjectUtility.scene_ray_cast(origin, direction, max_distance=1.70141e+38)

Cast a ray onto all geometry from the scene, in world space.

Parameters:

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

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

• max_distance (float) – Maximum distance.

Return type:

Tuple[bool, ndarray, ndarray, int, MeshObject, ndarray]

Returns:

Whether the ray successfully hit any 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] If any object has been hit, the MeshObject otherwise None. Some 4x4 matrix.