blenderfunc.object

Camera

set_camera(opencv_matrix=None, image_resolution=None, distort_coeffs=None, pose=None, clip_start=0.1, clip_end=100)

Set the camera in the Blender environment

Parameters

• opencv_matrix (List of Lists) – 3x3 intrinsics matrix, [[fx, 0, cx], [0, fy, cy], [0, 0, 1]]

• image_resolution (List) – [image_width, image_height]

• distort_coeffs (List) – [k1, k2, p1, p2, k3]

• pose (List of Lists) – 4x4 extrinsic matrix

• clip_start (float) – near_z of frustum

• clip_end (float) – far_z of frustum

Returns

object_name

Return type

str

LightSource

set_projector(opencv_matrix=None, distort_coeffs=None, image_path=None, pose=None, energy=100.0)

Set the projector in the Blender environment

Parameters

• opencv_matrix (List of Lists) – 3x3 intrinsics matrix, [[fx, 0, cx], [0, fy, cy], [0, 0, 1]]

• distort_coeffs (List) – [k1, k2, p1, p2, k3]

• image_path (str) – path to the image to be projected

• pose (List of Lists) – 4x4 extrinsic matrix

• energy (float) – projector energy

Returns

object_name

Return type

str

set_background_light(color=None, strength=1.0)

Set background lighting

Parameters

• color (List of float) – light color, black=[0,0,0], white=[1,1,1]

• strength (float) – light strength

add_light(location=[0, 0, 1], energy=10, name='Light')

Add a point light source to the scene

Parameters

• location (List of float) – location of light

• energy (float) – light energy

• name (str) – object_name

Returns

object_name

Return type

str

Mesh

add_object_from_file(filepath=None, name='Model', max_faces=None, uv_project=False, properties=None)

Add an object from model file

Parameters

• filepath (str) – model file path, supported format: ply | stl | obj

• name (str) – object_name

• max_faces (int) – decimate the model if the number of faces larger than this value. if this value is None, do nothing

• uv_project (bool) – automatically generate the uv map of this object

• properties (dict) –

  custom properties for physics simulation, useful properties:

  • physics(bool) – if true, the object will be moved in physics simulation, otherwise, only do collision check

  • collision_shape(str) – collision shape in physics simulation, options: “MESH” or “CONVEX_HULL”

  • class_id(int) – class id in render_class_segmap

Returns

object_name

Return type

str

add_plane(size=1.0, location=None, name='Plane', properties=None)

Add a plane to the scene

add_cube(size=2.0, name='Cube', properties=None)

Add a cube to the scene

add_cylinder(radius=0.1, depth=0.3, vertices=64, name='Cylinder', properties=None)

Add a cylinder to the scene

add_ball(radius=1.0, subdivisions=4, name='Ball', properties=None)

Add a ball to the scene

add_tote(length=1.0, width=1.0, height=0.5, thickness=0.02, name='Tote', properties=None)

Add a tote to the scene

decimate_mesh_object(obj_name, max_faces=10000)

Decimate the mesh object to target number of faces

Parameters

• obj_name (str) – the name of object to be decimated

• max_faces (int) – the number of faces of mesh object will be decimate to this value

remove_mesh_object(obj_name)

Remove the mesh object by its name

remove_mesh_objects_out_box(box, mesh_objects=None)

Remove the mesh objects above a certain height

Parameters

• box (List of float) – objects out of box will be removed, [xmin, xmax, ymin, ymax, zmin, zmax]

• mesh_objects (List of bpy.types.Object) – the objects will be checker, if this value is None, all objects with custom properties “physics = True” will be selected

Returns

number of removed objects

Return type

int

duplicate_mesh_object(obj_name)

Duplicate the mesh object by its name, use this function instead of loop to add new object to save memory

Parameters

obj_name (str) – the name of object to be duplicated

Returns

object_name of new object

Return type

str

separate_isolated_meshes(obj_name)

Separate a mesh into multiple meshes if they have no linked parts

Parameters

obj_name (str) – name of object to be separated

Returns

list of separated object names

Return type

List of str

export_mesh_object(filepath, obj_name, center_of_mass=False)

Export the mesh object to a specified filepath

Parameters

• filepath (str) – output filepath, supported file format: ply | stl

• obj_name (str) – name of object to be exported

• center_of_mass (bool) – if true, reset the origin of object to its center of mass

export_meshes_info(filepath='/tmp/temp.csv', visible_ratio=None)

Export information of all objects in the scene to a csv file, an example of csv file:

instance_id(int), class_id(int), name(str), visible_ratio(float), pose(flattened 3x4 matrix)

1, 1, Plane, 0.5, 1.0 0.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 0.0 1.0 0.0

…

Parameters

• filepath – output filepath

• visible_ratio – visible ratio of objects

get_all_mesh_objects()

Get all mesh objects in the scene

Returns

list of blender objects

Return type

List of bpy.types.Object

get_mesh_objects_by_custom_properties(properties=None)

Get mesh objects have the specified custom properties

Parameters

properties (dict) – object custom properties

Returns

list of blender objects

Return type

List of bpy.types.Object

set_origin_to_center_of_mass(obj_name, mode='volume')

Set the origin of object to its center of mass

Parameters

• obj_name (str) – the name of object

• mode (str) – the type of center fo mass: volume | surface

Texture

load_image(path)

Load an image to Blender environment, the name of loaded image will be set to its basename

Parameters

path – path to the image to be loaded

Returns

blender image object

Return type

bpy.types.Image

get_pbr_material_infos(texture_root='resources/cctextures')

Get the information of PBR materials, we use free textures from cc0textures.com

Parameters

texture_root – root directory of downloaded textures. each texture with a folder, in the folder there are multiple texture images

Returns

textures information

Return type

dict, key=texture_name, value=texture_folder

add_pbr_material(texture_folder, name='Material', loc_x=0.0, loc_y=0.0, rot_z=0.0, scale_x=1.0, scale_y=1.0)

Add a PBR texture from a texture folder

Parameters

• texture_folder (str) – the texture folder contains multiple texture images

• name (str) – texture_name

• loc_x (float) – texture mapping x-axis offset

• loc_y (float) – texture mapping y-axis offset

• rot_z (float) – texture mapping z-axis rotation in degree

• scale_x (float) – texture mapping x-axis scale

• scale_y (float) – texture mapping y-axis scale

Returns

texture_name

Return type

str

add_simple_material(color=None, metallic=0.0, roughness=0.5, name='Material')

Add a simple uniform material

Parameters

• color (List) – rgb value, black=[0,0,0], white=[1,1,1]

• metallic (float) – control the metallic of material, valid range: [0,1]

• roughness (float) – control the roughness of material, valid range: [0,1]

• name (str) – material_name

Returns

material_name

Return type

str

set_material(obj_name, mat_name)

Set the material to the object

Parameters

• obj_name (str) – object name

• mat_name (str) – material name

get_hdr_material_infos(hdr_root='resources/hdr')

Get the information of HDR materials, we use free textures from polyhaven.com

Parameters

hdr_root – root directory of downloaded textures

Returns

textures information

Return type

dict, key=texture_name, value=texture_filepath

set_hdr_background(filepath, rot_x=0.0, rot_y=0.0, rot_z=0.0, scale_x=1.0, scale_y=1.0, scale_z=1.0)

Set background light to specified HDR texture

Parameters

• filepath – hdr texture filepath

• rot_x – texture mapping x-axis rotation in degree

• rot_y (float) – texture mapping y-axis rotation in degree

• rot_z (float) – texture mapping z-axis rotation in degree

• scale_x (float) – texture mapping x-axis scale

• scale_y (float) – texture mapping y-axis scale

• scale_z (float) – texture mapping z-axis scale

add_transparent_material(name='Material', emission_strength=1.0)

Add a transparent material

Parameters

• name (str) – material_name

• emission_strength (float) – control the emission strength of principled volume shader

Returns

material_name

Return type

str

Physics

physics_simulation(min_simulation_time=1.0, max_simulation_time=10.0, substeps_per_frame=10, max_faces=500)

Run physics simulation for a few seconds then freeze the scene. Simulation will stop automatically if the object is no longer moving or if the max_simulation_time has been reached

Parameters

• min_simulation_time (float) – the simulation will at least run min_simulation_time seconds

• max_simulation_time (float) – the simulation will at most run max_simulation_time seconds

• substeps_per_frame (int) – number of substeps to solve physics computation per frame, higher value for more stable simulation

• max_faces (int) – reduce the number of faces to speed up collision checking, only works in physics simulation

collision_free_positioning(obj_name, pose_sampler, max_trials=100)

Placing an object in a collision free position

Parameters

• obj_name (str) – the name of object to be placed

• pose_sampler (function) – a random pose generator

• max_trials (int) – max number of trials

Returns

True if no collision

Return type

bool

PoseSampler

in_tote_sampler(tote_name, obj_name, num)

Return a random pose sampler that only generates poses above the tote, which ensures the objects will fall inside the tote eventually after physics simulation.

Parameters

• tote_name – name of tote

• obj_name – name of object

• num – number of objects that will be in the tote

Returns

random pose sampler

Return type

function

in_view_checker(cam_pose, cam_intrinsics, image_resolution)

Return a checker function to check if all points can be seen in a camera view

Parameters

• cam_pose (List of Lists) – 4x4 camera extrinsic matrix

• cam_intrinsics (List of Lists) – 3x3 camera intrinsic matrix, [[fx,0,cx],[0,fy,cy],[0,0,1]]

• image_resolution (List) – [image_width, image_width]

Returns

in view checker

Return type

function

in_views_sampler(obj_name, rand_loc, rand_rot, checkers)

Randomly sample poses and check whether an object can be observed completely by multiple cameras

Parameters

• obj_name (str) – name of object to be sampled

• rand_loc (List of Lists) – range of random location, [[min_x, max_x], [min_y, max_y], [min_z, max_z]]

• rand_rot (List of Lists) – range of random euler angle in degree, [[min_r, max_r], [min_p, max_p], [min_y, max_y]]

• checkers (List of functions) – checker functions