blenderproc.loader package

Module contents

blenderproc.loader.get_random_world_background_hdr_img_path_from_haven(data_path)

Sets the world background to a random .hdr file from the given directory.

Parameters:

data_path (str) – A path pointing to a directory containing .hdr files.

Return type:

str

Returns:

The path to a random selected path

blenderproc.loader.load_AMASS(data_path, sub_dataset_id, temp_dir=None, body_model_gender=None, subject_id='', sequence_id=-1, frame_id=-1, num_betas=10, num_dmpls=8)

use the pose parameters to generate the mesh and loads it to the scene.

Parameters:

  • data_path (str) – The path to the AMASS Dataset folder in resources folder.

  • sub_dataset_id (str) – Identifier for the sub dataset, the dataset which the human pose object should be extracted from. Available: [‘CMU’, ‘Transitions_mocap’, ‘MPI_Limits’, ‘SSM_synced’, ‘TotalCapture’, ‘Eyes_Japan_Dataset’, ‘MPI_mosh’, ‘MPI_HDM05’, ‘HumanEva’, ‘ACCAD’, ‘EKUT’, ‘SFU’, ‘KIT’, ‘H36M’, ‘TCD_handMocap’, ‘BML’]

  • temp_dir (Optional[str]) – A temp directory which is used for writing the temporary .obj file.

  • body_model_gender (Optional[str]) – The model gender pose is represented by either using male, female or neutral body shape. Available:[male, female, neutral]. If None is selected a random one is chosen.

  • subject_id (str) – Type of motion from which the pose should be extracted, this is dataset dependent parameter. If left empty a random subject id is picked.

  • sequence_id (int) – Sequence id in the dataset, sequences are the motion recorded to represent certain action. If set to -1 a random sequence id is selected.

  • frame_id (int) – Frame id in a selected motion sequence. If none is selected a random one is picked

  • num_betas (int) – Number of body parameters

  • num_dmpls (int) – Number of DMPL parameters

Return type:

List[MeshObject]

Returns:

The list of loaded mesh objects.

blenderproc.loader.load_blend(path, obj_types=None, name_regrex=None, data_blocks='objects', link=False)

Loads entities (everything that can be stored in a .blend file’s folders, see Blender’s documentation for bpy.types.ID for more info) that match a name pattern from a specified .blend file’s section/data_block.

Parameters:

  • path (str) – Path to a .blend file.

  • obj_types (Union[List[str], str, None]) – The type of objects to load. This parameter is only relevant when data_blocks is set to “objects”. Available options are: [‘mesh’, ‘curve’, ‘hair’, ‘armature’, ‘empty’, ‘light’, ‘camera’]

  • name_regrex (Optional[str]) – Regular expression representing a name pattern of entities’ (everything that can be stored in a .blend file’s folders, see Blender’s documentation for bpy.types.ID for more info) names.

  • data_blocks (Union[List[str], str]) – The data block or a list of data blocks which should be loaded from the given .blend file. Available options are: [‘armatures’, ‘cameras’, ‘curves’, ‘hairs’, ‘images’, ‘lights’, ‘materials’, ‘meshes’, ‘objects’, ‘textures’]

  • link (bool) – whether to link instead of append data blocks from .blend file. Linked objects can not be modified.

Return type:

List[Entity]

Returns:

The list of loaded mesh objects.

blenderproc.loader.load_bop_intrinsics(bop_dataset_path, split='test', cam_type='')

Load and set the camera matrix and image resolution of a specified BOP dataset

Parameters:

  • bop_dataset_path (str) – Full path to a specific bop dataset e.g. /home/user/bop/tless.

  • split (str) – Optionally, train, test or val split depending on BOP dataset, defaults to “test”

  • cam_type (str) – Camera type. If not defined, dataset-specific default camera type is used.

Return type:

Tuple[ndarray, int, int]

Returns:

camera matrix K, W, H

blenderproc.loader.load_bop_objs(bop_dataset_path, model_type='', obj_ids=None, sample_objects=False, num_of_objs_to_sample=None, obj_instances_limit=-1, mm2m=None, object_model_unit='m', move_origin_to_x_y_plane=False)

Loads all or a subset of 3D models of any BOP dataset

Parameters:

  • bop_dataset_path (str) – Full path to a specific bop dataset e.g. /home/user/bop/tless.

  • model_type (str) – Optionally, specify type of BOP model. Available: [reconst, cad or eval].

  • obj_ids (Optional[List[int]]) – List of object ids to load. Default: [] (load all objects from the given BOP dataset)

  • sample_objects (bool) – Toggles object sampling from the specified dataset.

  • num_of_objs_to_sample (Optional[int]) – Amount of objects to sample from the specified dataset. If this amount is bigger than the dataset actually contains, then all objects will be loaded.

  • obj_instances_limit (int) – Limits the amount of object copies when sampling. Default: -1 (no limit).

  • mm2m (Optional[bool]) – Specify whether to convert poses and models to meters (deprecated).

  • object_model_unit (str) – The unit the object model is in. Object model will be scaled to meters. This does not affect the annotation units. Available: [‘m’, ‘dm’, ‘cm’, ‘mm’].

  • move_origin_to_x_y_plane (bool) – Move center of the object to the lower side of the object, this will not work when used in combination with pose estimation tasks! This is designed for the use-case where BOP objects are used as filler objects in the background.

Return type:

List[MeshObject]

Returns:

The list of loaded mesh objects.

blenderproc.loader.load_bop_scene(bop_dataset_path, scene_id, model_type='', cam_type='', split='test', source_frame=None, mm2m=None, object_model_unit='m')
Replicate a BOP scene from the given dataset: load scene objects, object poses, camera intrinsics and

extrinsics

  • Interfaces with the bob_toolkit, allows loading of train, val and test splits

  • Relative camera poses are loaded/computed with respect to a reference model

  • Sets real camera intrinsics

Parameters:

  • bop_dataset_path (str) – Full path to a specific bop dataset e.g. /home/user/bop/tless.

  • scene_id (int) – Specify BOP dataset scene to synthetically replicate. Default: -1 (no scene is replicated, only BOP Objects are loaded).

  • model_type (str) – Optionally, specify type of BOP model. Available: [reconst, cad or eval].

  • cam_type (str) – Camera type. If not defined, dataset-specific default camera type is used.

  • split (str) – Optionally, test or val split depending on BOP dataset.

  • source_frame (Optional[List[str]]) – Can be used if the given positions and rotations are specified in frames different from the blender frame. Has to be a list of three strings. Example: [‘X’, ‘-Z’, ‘Y’]: Point (1,2,3) will be transformed to (1, -3, 2). Default: [“X”, “-Y”, “-Z”], Available: [‘X’, ‘Y’, ‘Z’, ‘-X’, ‘-Y’, ‘-Z’].

  • mm2m (Optional[bool]) – Specify whether to convert poses and models to meters (deprecated).

  • object_model_unit (str) – The unit the object model is in. Object model will be scaled to meters. This does not affect the annotation units. Available: [‘m’, ‘dm’, ‘cm’, ‘mm’].

Return type:

List[MeshObject]

Returns:

The list of loaded mesh objects.

blenderproc.loader.load_ccmaterials(folder_path='resources/cctextures', used_assets=None, preload=False, fill_used_empty_materials=False, add_custom_properties=None, use_all_materials=False, skip_transparent_materials=True)

This method loads all textures obtained from https://ambientCG.com, use the script (scripts/download_cc_textures.py) to download all the textures to your pc.

All textures here support Physically based rendering (PBR), which makes the textures more realistic.

All materials will have the custom property “is_cc_texture”: True, which will make the selection later on easier.

Parameters:

  • folder_path (str) – The path to the downloaded cc0textures.

  • used_assets (Optional[list]) – A list of all asset names, you want to use. The asset-name must not be typed in completely, only the beginning the name starts with. By default, all assets will be loaded, specified by an empty list.

  • preload (bool) – If set true, only the material names are loaded and not the complete material.

  • fill_used_empty_materials (bool) – If set true, the preloaded materials, which are used are now loaded completely.

  • add_custom_properties (Optional[dict]) – A dictionary of materials and the respective properties.

  • use_all_materials (bool) – If this is false only a selection of probably useful textures is used. This excludes some see through texture and non tileable texture.

  • skip_transparent_materials (bool) – If set to true, all materials with transparent portions are skipped.

Return type:

List[Material]

Returns:

a list of all loaded materials, if preload is active these materials do not contain any textures yet and have to be filled before rendering (by calling this function again, no need to save the prior returned list)

blenderproc.loader.load_front3d(json_path, future_model_path, front_3D_texture_path, label_mapping, ceiling_light_strength=0.8, lamp_light_strength=7.0)

Loads the 3D-Front scene specified by the given json file.

Parameters:

  • json_path (str) – Path to the json file, where the house information is stored.

  • future_model_path (str) – Path to the models used in the 3D-Front dataset.

  • front_3D_texture_path (str) – Path to the 3D-FRONT-texture folder.

  • label_mapping (LabelIdMapping) – A dict which maps the names of the objects to ids.

  • ceiling_light_strength (float) – Strength of the emission shader used in the ceiling.

  • lamp_light_strength (float) – Strength of the emission shader used in each lamp.

Return type:

List[MeshObject]

Returns:

The list of loaded mesh objects.

blenderproc.loader.load_haven_mat(folder_path='resources/haven', used_assets=None, preload=False, fill_used_empty_materials=False, add_cp=None, return_random_element=False)

Loads all specified haven textures from the given directory.

Parameters:

  • folder_path (Union[str, Path]) – The path to the downloaded haven.

  • used_assets (Optional[List[str]]) – A list of all asset names, you want to use. The asset-name must not be typed in completely, only the beginning the name starts with. By default, all assets will be loaded, specified by an empty list or None.

  • preload (bool) – If set true, only the material names are loaded and not the complete material.

  • fill_used_empty_materials (bool) – If set true, the preloaded materials, which are used are now loaded completely.

  • add_cp (Optional[Dict[str, Any]]) – A dictionary of materials and the respective properties.

  • return_random_element (bool) – If this is True only a single Material is loaded and returned, if you want to sample many materials load them all with the preload option, use them and then fill the used empty materials instead of calling this function multiple times.

Return type:

Union[List[Material], Material]

Returns:

a list of all loaded materials, if preload is active these materials do not contain any textures yet and have to be filled before rendering (by calling this function again, there is no need to save the prior returned list) or if return_random_element is True only a single Material is returned

blenderproc.loader.load_ikea(data_dir='resources/IKEA', obj_categories=None, obj_style=None)

Loads ikea objects based on selected type and style.

If there are multiple options it picks one randomly or if style or type is None it picks one randomly.

Parameters:

  • data_dir (str) – The directory with all the IKEA models.

  • obj_categories (Union[List[str], str, None]) – The category to use for example: ‘bookcase’. This can also be a list of elements. Available: [‘bed’, ‘bookcase’, ‘chair’, ‘desk’, ‘sofa’, ‘table’, ‘wardrobe’]

  • obj_style (Optional[str]) – The IKEA style to use for example: ‘hemnes’. See data_dir for other options.

Return type:

List[MeshObject]

Returns:

The list of loaded mesh objects.

blenderproc.loader.load_matterport3d(data_folder, used_house_id=None, compare_floor_angle_in_degrees=15.0)

Load a scene from the Matterport3D dataset.

Parameters:

  • data_folder (Union[Path, str]) – Path to the downloaded Matterport3D dataset, please use blenderproc download matterport

  • used_house_id (Optional[str]) – A possible used_house_id for example: “X7HyMhZNoso” or “Z6MFQCViBuw”, if None is given a random one is selected

  • compare_floor_angle_in_degrees (float) – The angle which is used to check if a face is pointing upwards, all faces pointing upwards are used to extract the floor object

Return type:

Tuple[MeshObject, MeshObject]

Returns:

The general scene and the floor object as a tuple of MeshObject

blenderproc.loader.load_obj(filepath, cached_objects=None, use_legacy_obj_import=False, **kwargs)

Import all objects for the given file and returns the loaded objects

In .obj files a list of objects can be saved in. In .ply files only one object can be saved so the list has always at most one element

Parameters:

  • filepath (str) – the filepath to the location where the data is stored

  • cached_objects (Optional[Dict[str, List[MeshObject]]]) – a dict of filepath to objects, which have been loaded before, to avoid reloading (the dict is updated in this function)

  • use_legacy_obj_import (bool) – If this is true the old legacy obj importer in python is used. It is slower, but it correctly imports the textures in the ShapeNet dataset.

  • kwargs – all other params are handed directly to the bpy loading fct. check the corresponding documentation

Return type:

List[MeshObject]

Returns:

The list of loaded mesh objects.

blenderproc.loader.load_pix3d(used_category, data_path='resources/pix3d')

Loads one random Pix3D object from the given category.

Parameters:

  • used_category (str) – The category to use for example: ‘bed’, check the data_path/model folder for more categories. Available: [‘bed’, ‘bookcase’, ‘chair’, ‘desk’, ‘misc’, ‘sofa’, ‘table’, ‘tool’, ‘wardrobe’]

  • data_path (str) – The path to the Pix3D folder.

Return type:

List[MeshObject]

Returns:

The list of loaded mesh objects.

blenderproc.loader.load_replica(data_path, data_set_name, use_smooth_shading=False)

Just imports the configured .ply file straight into blender for the replica case.

Parameters:

  • data_path (str) – The path to the data folder, where all rooms are saved.

  • data_set_name (str) – Name of the room (for example: apartment_0).

  • use_smooth_shading (bool) – Enable smooth shading on all surfaces, instead of flat shading.

Return type:

List[MeshObject]

Returns:

The list of loaded mesh objects.

blenderproc.loader.load_replica_segmented_mesh(data_path, data_set_name, use_smooth_shading=False)

Loads a segmented replica file

Parameters:

  • data_path (Union[str, Path]) – The path to the data folder, where all rooms are saved.

  • data_set_name (str) – Name of the room (for example: apartment_0).

  • use_smooth_shading (bool) – if set to True all objects loaded, will have smooth shading activated

Return type:

List[MeshObject]

Returns:

The list of loaded and separated mesh objects.

blenderproc.loader.load_scenenet(file_path, texture_folder, label_mapping, unknown_texture_folder=None)

Loads all SceneNet objects at the given “file_path”.

The textures for each object are sampled based on the name of the object, if the name is not represented in the texture folder the unknown folder is used. This folder does not exist, after downloading the texture dataset. Make sure to create and put some textures, you want to use for these instances there.

All objects get “category_id” set based on the data in the “resources/id_mappings/nyu_idset.csv”

Each object will have the custom property “is_scene_net_obj”.

Parameters:

  • file_path (str) – The path to the .obj file from SceneNet.

  • label_mapping (LabelIdMapping) – A dict which maps the names of the objects to ids.

  • texture_folder (str) – The path to the texture folder used to sample the textures.

  • unknown_texture_folder (Optional[str]) – The path to the textures, which are used if the texture type is unknown. The default path does not exist if the dataset was just downloaded, it has to be created manually.

Return type:

List[MeshObject]

Returns:

The list of loaded mesh objects.

blenderproc.loader.load_shapenet(data_path, used_synset_id, used_source_id='', move_object_origin=True)

This loads an object from ShapeNet based on the given synset_id, which specifies the category of objects to use.

From these objects one is randomly sampled and loaded.

Todo: not good: Note: if this module is used with another loader that loads objects with semantic mapping, make sure the other module is loaded first in the config file.

Parameters:

  • data_path (str) – The path to the ShapeNetCore.v2 folder.

  • used_synset_id (str) – The synset id for example: ‘02691156’, check the data_path folder for more ids.

  • used_source_id (str) – Object identifier of the a particular ShapeNet category, see inside any ShapeNet category for identifiers

  • move_object_origin (bool) – Moves the object center to the bottom of the bounding box in Z direction and also in the middle of the X and Y plane, this does not change the .location of the object. Default: True

Return type:

MeshObject

Returns:

The loaded mesh object.

blenderproc.loader.load_suncg(house_path, label_mapping, suncg_dir=None)

Loads a house.json file into blender.

  • Loads all objects files specified in the house.json file.

  • Orders them hierarchically (level -> room -> object)

  • Writes metadata into the custom properties of each object

Parameters:

  • house_path (str) – The path to the house.json file which should be loaded.

  • label_mapping (LabelIdMapping) – A dict which maps the names of the objects to ids.

  • suncg_dir (Optional[str]) – The path to the suncg root directory which should be used for loading objects, rooms, textures etc.

Return type:

List[Union[Entity, MeshObject]]

Returns:

The list of loaded mesh objects.

blenderproc.loader.load_texture(path, colorspace='sRGB')

Loads images and creates image textures.

Depending on the form of the provided path: 1. Loads an image, creates an image texture, and assigns the loaded image to the texture, when a path to an image is provided. 2. Load images and for each creates a texture, and assigns an image to this texture, if a path to a folder with images is provided.

NOTE: Same image file can be loaded once to avoid unnecessary overhead. If you really need the same image in different colorspaces, then have a copy per desired colorspace and load them in different instances of this Loader.

Parameters:

  • path (str) – The path to the folder with assets/to the asset.

  • colorspace (str) – Colorspace type to assign to loaded assets. Available: [‘Filmic Log’, ‘Linear’, ‘Linear ACES’, ‘Non-Color’, ‘Raw’, ‘sRGB’, ‘XYZ’].

Return type:

List[Texture]

Returns:

The list of created textures.

blenderproc.loader.load_urdf(urdf_file, weight_distribution='rigid', fk_offset=None, ik_offset=None)

Loads an urdf object from an URDF file.

Parameters:

  • urdf_file (str) – Path to the URDF file.

  • weight_distribution (str) – One of [‘envelope’, ‘automatic’, ‘rigid’]. For more information please see https://docs.blender.org/manual/en/latest/animation/armatures/skinning/parenting.html.

  • fk_offset (Union[List[float], Vector, array, None]) – Offset between fk (forward kinematic) bone chain and link bone chain. This does not have any effect on the transformations, but can be useful for visualization in blender.

  • ik_offset (Union[List[float], Vector, array, None]) – Offset between ik (inverse kinematic) bone chain and link bone chain. Effects on the transformation (e.g. urdf_object.set_location_ik()) are being handled internally. Useful for visualization in blender.

Return type:

URDFObject

Returns:

URDF object instance.