blenderproc.object package

Module contents

blenderproc.object.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.object.convert_to_entities(blender_objects, convert_to_subclasses=False)

Converts the given list of blender objects to entities

Parameters:

blender_objects (list) – List of blender objects.
convert_to_subclasses (bool) – If True, each blender object will be wrapped into an entity subclass based on the type of object.

Return type:

List[Entity]

Returns:

The list of entities.

blenderproc.object.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.object.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.object.create_empty(entity_name, empty_type='plain_axes')

Creates an empty entity.

Parameters:

entity_name (str) – The name of the new entity.
empty_type (str) – Type of the newly created empty entity. Available: [“plain_axes”, “arrows”, “single_arrow”, “circle”, “cube”, “sphere”, “cone”]

Return type:

Entity

Returns:

The new Mesh entity.

blenderproc.object.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.object.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.object.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.object.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.object.delete_multiple(entities, remove_all_offspring=False)

Deletes multiple entities at once

Parameters:

entities (List[Entity]) – A list of entities that should be deleted
remove_all_offspring (bool) – If this is True all children and their children are recursively deleted

blenderproc.object.disable_all_rigid_bodies(): Disables the rigidbody element of all objects

blenderproc.object.extract_floor(mesh_objects, compare_angle_degrees=7.5, compare_height=0.15, up_vector_upwards=True, height_list_path=None, new_name_for_object='Floor', should_skip_if_object_is_already_there=False)

Extracts floors in the following steps: 1. Searchs for the specified object. 2. Splits the surfaces which point upwards at a specified level away.

Parameters:

mesh_objects (List[MeshObject]) – Objects to where all polygons will be extracted.
compare_angle_degrees (float) – Maximum difference between the up vector and the current polygon normal in degrees.
compare_height (float) – Maximum difference in Z direction between the polygons median point and the specified height of the room.
up_vector_upwards (bool) – If this is True the up_vec points upwards -> [0, 0, 1] if not it points downwards: [0, 0, -1] in world coordinates. This vector is used for the compare_angle_degrees option.
height_list_path (Optional[str]) – Path to a file with height values. If none is provided, a ceiling and floor is automatically detected. This might fail. The height_list_values can be specified in a list like fashion in the file: [0.0, 2.0]. These values are in the same size the dataset is in, which is usually meters. The content must always be a list, e.g. [0.0].
new_name_for_object (str) – Name for the newly created object, which faces fulfill the given parameters.
should_skip_if_object_is_already_there (bool) – If this is true no extraction will be done, if an object is there, which has the same name as name_for_split_obj, which would be used for the newly created object.

Return type:

List[MeshObject]

Returns:

The extracted floor objects.

blenderproc.object.get_all_mesh_objects()

Returns all mesh objects in scene

Return type:: List[MeshObject]
Returns:: List of all MeshObjects

blenderproc.object.merge_objects(objects, merged_object_name='merged_object')

Generates an empty object and sets this as parent object for all objects in the list which do not already: have a parent set.

Parameters:

objects (List[Entity]) – A list of objects to be merged.
merged_object_name (str) – The name of the parent object.

Return type:

Entity

blenderproc.object.replace_objects(objects_to_be_replaced, objects_to_replace_with, ignore_collision_with=None, replace_ratio=1, copy_properties=True, max_tries=100, relative_pose_sampler=None)

Replaces mesh objects with another mesh objects and scales them accordingly, the replaced objects and the objects to replace with in following steps:

Randomly select a subset of objects_to_be_replaced.
For each of these objects, sample other objects from objects_to_replace_with and try to replace them.
In each try, the poses of the objects are aligned and a check for collisions with other objects is done.
An object is skipped if max_tries is reached.

Parameters:

objects_to_be_replaced (List[MeshObject]) – Objects, which should be removed from the scene.
objects_to_replace_with (List[MeshObject]) – Objects, which will be tried to be added to the scene.
ignore_collision_with (Optional[List[MeshObject]]) – Objects, which are not checked for collisions with.
replace_ratio (float) – Ratio of objects in the original scene, which will be replaced.
copy_properties (bool) – Copies the custom properties of the objects_to_be_replaced to the objects_to_replace_with.
max_tries (int) – Maximum number of tries to replace one object.
relative_pose_sampler (Optional[Callable[[MeshObject], None]]) – A function that randomly perturbs the pose of the object to replace with (after it has been aligned to the object to replace).

blenderproc.object.sample_poses(objects_to_sample, sample_pose_func, objects_to_check_collisions=None, max_tries=1000, mode_on_failure='last_pose')

Samples positions and rotations of selected object inside the sampling volume while performing mesh and bounding box collision checks.

Parameters:

objects_to_sample (List[MeshObject]) – A list of mesh objects whose poses are sampled based on the given function.
sample_pose_func (Callable[[MeshObject], None]) – The function to use for sampling the pose of a given object.
objects_to_check_collisions (Optional[List[MeshObject]]) – A list of mesh objects who should not be considered when checking for collisions.
max_tries (int) – Amount of tries before giving up on an object and moving to the next one.
mode_on_failure (str) – Define final state of objects that could not be placed without collisions within max_tries attempts. Options: ‘last_pose’, ‘initial_pose’

Return type:

Dict[Entity, Tuple[int, bool]]

Returns:

A dict with the objects to sample as keys and a Tuple with the number of executed attempts to place the object as first element, and a bool whether it has been successfully placed without collisions.

blenderproc.object.sample_poses_on_surface(objects_to_sample, surface, sample_pose_func, max_tries=100, min_distance=0.25, max_distance=0.6, up_direction=None, check_all_bb_corners_over_surface=True)

Samples objects poses on a surface.

The objects are positioned slightly above the surface due to the non-axis aligned nature of used bounding boxes and possible non-alignment of the sampling surface (i.e. on the X-Y hyperplane, can be somewhat mitigated with precise “up_direction” value), which leads to the objects hovering slightly above the surface. So it is recommended to use the PhysicsPositioning module afterwards for realistically looking placements of objects on the sampling surface. If placing fails due to collisions, the object will be moved back to the intial pose and hidden from rendering.

Parameters:

objects_to_sample (List[MeshObject]) – A list of objects that should be sampled above the surface.
surface (MeshObject) – Object to place objects_to_sample on.
sample_pose_func (Callable[[MeshObject], None]) – The function to use for sampling the pose of a given object.
max_tries (int) – Amount of tries before giving up on an object (deleting it) and moving to the next one.
min_distance (float) – Minimum distance to the closest other object from objects_to_sample. Center to center.
max_distance (float) – Maximum distance to the closest other object from objects_to_sample. Center to center.
up_direction (Optional[ndarray]) – Normal vector of the side of surface the objects should be placed on.
check_all_bb_corners_over_surface (bool) – If this is True all bounding box corners have to be above the surface, else only the center of the object has to be above the surface

Return type:

List[MeshObject]

Returns:

The list of placed objects.

blenderproc.object.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.

blenderproc.object.simulate_physics(min_simulation_time=4.0, max_simulation_time=40.0, check_object_interval=2.0, object_stopped_location_threshold=0.01, object_stopped_rotation_threshold=0.1, substeps_per_frame=10, solver_iters=10, verbose=False)

Simulates the current scene.

The simulation is run for at least min_simulation_time seconds and at a maximum max_simulation_time seconds. Every check_object_interval seconds, it is checked if the maximum object movement in the last second is below a given threshold. If that is the case, the simulation is stopped.

The origin of all objects is set to their center of mass in this function which is necessary to achieve a realistic simulation in blender (see https://blender.stackexchange.com/questions/167488/physics-not-working-as-expected) Also the scale of each participating object is persisted as scale != 1 can make the simulation unstable.

Parameters:

min_simulation_time (float) – The minimum number of seconds to simulate.
max_simulation_time (float) – The maximum number of seconds to simulate.
check_object_interval (float) – The interval in seconds at which all objects should be checked if they are still moving. If all objects have stopped moving, then the simulation will be stopped.
object_stopped_location_threshold (float) – The maximum difference per second and per coordinate in the rotation Euler vector that is allowed such that an object is still recognized as ‘stopped moving’.
object_stopped_rotation_threshold (float) – The maximum difference per second and per coordinate in the rotation Euler vector that is allowed such that an object is still recognized as ‘stopped moving’.
substeps_per_frame (int) – Number of simulation steps taken per frame.
solver_iters (int) – Number of constraint solver iterations made per simulation step.
verbose (bool) – If True, more details during the physics simulation are printed.

Return type:

dict

Returns:

A dict containing for every active object the shift that was added to their origins.

blenderproc.object.simulate_physics_and_fix_final_poses(min_simulation_time=4.0, max_simulation_time=40.0, check_object_interval=2.0, object_stopped_location_threshold=0.01, object_stopped_rotation_threshold=0.1, substeps_per_frame=10, solver_iters=10, verbose=False)

Simulates the current scene and in the end fixes the final poses of all active objects.

The simulation is run for at least min_simulation_time seconds and at a maximum max_simulation_time seconds. Every check_object_interval seconds, it is checked if the maximum object movement in the last second is below a given threshold. If that is the case, the simulation is stopped.

After performing the simulation, the simulation cache is removed, the rigid body components are disabled and the pose of the active objects is set to their final pose in the simulation.

Parameters:

min_simulation_time (float) – The minimum number of seconds to simulate.
max_simulation_time (float) – The maximum number of seconds to simulate.
check_object_interval (float) – The interval in seconds at which all objects should be checked if they are still moving. If all objects have stopped moving, then the simulation will be stopped.
object_stopped_location_threshold (float) – The maximum difference per second and per coordinate in the rotation Euler vector that is allowed such that an object is still recognized as ‘stopped moving’.
object_stopped_rotation_threshold (float) – The maximum difference per second and per coordinate in the rotation Euler vector that is allowed such that an object is still recognized as ‘stopped moving’.
substeps_per_frame (int) – Number of simulation steps taken per frame.
solver_iters (int) – Number of constraint solver iterations made per simulation step.
verbose (bool) – If True, more details during the physics simulation are printed.

blenderproc.object.slice_faces_with_normals(mesh_object, compare_angle_degrees=7.5, up_vector_upwards=None, new_name_for_object='Surface')

Extracts normal faces like floors in the following steps: 1. Searchs for the specified object. 2. Splits the surfaces which point upwards at a specified level away.

Parameters:

mesh_object (MeshObject) – Object to which all polygons will be extracted.
compare_angle_degrees (float) – Maximum difference between the up vector and the current polygon normal in degrees.
up_vector_upwards (Optional[array]) – If this is True the up_vec points upwards -> [0, 0, 1] if not it points downwards: [0, 0, -1] in world coordinates. This vector is used for the compare_angle_degrees option.
new_name_for_object (str) – Name for the newly created object, which faces fulfill the given parameters.

Return type:

Optional[MeshObject]

Returns:

The extracted surface of the object.