blenderproc.python.modules.manipulators.EntityManipulator module¶

class blenderproc.python.modules.manipulators.EntityManipulator.EntityManipulator(config)[source]¶

Bases: blenderproc.python.modules.main.Module.Module

Performs manipulation on selected entities of different Blender built-in types, e.g. Mesh objects, Camera objects, Light objects, etc.

Example 1: For all ‘MESH’ type objects with a name matching a ‘Cube.*’ pattern set rotation Euler vector and set custom property physics.

{
  "module": "manipulators.EntityManipulator",
  "config": {
    "selector": {
      "provider": "getter.Entity",
      "conditions": {
        "name": 'Cube.*',
        "type": "MESH"
      }
    },
    "rotation_euler": [1, 1, 0],
    "cp_physics": True
  }
}

Example 2: Set a shared (sampled once and set for all selected objects) location for all ‘MESH’ type objects with a name matching a ‘Cube.*’ pattern.

{
  "module": "manipulators.EntityManipulator",
  "config": {
    "selector": {
      "provider": "getter.Entity",
      "conditions": {
        "name": 'Cube.*',
        "type": "MESH"
      }
    },
    "mode": "once_for_all",
    "location": {
      "provider": "sampler.Uniform3d",
      "max":[1, 2, 3],
      "min":[0, 1, 2]
    }
  }
}

Example 3: Set a unique (sampled once for each selected object) location and apply a ‘Solidify’ object modifier with custom ‘thickness’ attribute value to all ‘MESH’ type objects with a name matching a ‘Cube.*’ pattern.

{
  "module": "manipulators.EntityManipulator",
  "config": {
    "selector": {
      "provider": "getter.Entity",
      "conditions": {
        "name": 'Cube.*',
        "type": "MESH"
      }
    },
    "mode": "once_for_each",    # can be omitted, `once_for_each` is a default value of `mode` parameter
    "location": {
      "provider": "sampler.Uniform3d",
      "max":[1, 2, 3],
      "min":[0, 1, 2]
    },
    "cf_add_modifier": {
      "name": "Solidify",
      "thickness": 0.001
    }
  }
}

Example 4: Add a displacement modifier with a newly generated texture.

{
  "module": "manipulators.EntityManipulator",
  "config": {
    "selector": {
      "provider": "getter.Entity",
      "conditions": {
        "name": 'Cube.*',
        "type": "MESH"
      }
    },
    "cf_add_displace_modifier_with_texture": {
      "texture": 'VORONOI'
    }
  }
}

Example 5: Add a displacement modifier with a newly random generated texture with custom texture, noise scale, modifier mid_level, modifier render_level and modifier strength. With prior addition of a uv_map to all object without an uv map and adding of a Subdivision Surface Modifier if the number of vertices of an object is less than 10000.

{
  "module": "manipulators.EntityManipulator",
  "config": {
    "selector": {
      "provider": "getter.Entity",
      "conditions": {
        "name": 'apple',
        "type": "MESH"
      }
    },
    "cf_add_uv_mapping":{
      "projection": "cylinder"
    },
    "cf_add_displace_modifier_with_texture": {
      "texture": {
        "provider": "sampler.Texture"
      },
      "min_vertices_for_subdiv": 10000,
      "mid_level": 0.5,
      "subdiv_level": {
        "provider": "sampler.Value",
        "type": "int",
        "min": 1,
        "max": 3
      },
      "strength": {
        "provider": "sampler.Value",
        "type": "float",
        "mode": "normal",
        "mean": 0.0,
        "std_dev": 0.7
      }
    }
  }
}

Configuration:

Parameter	Description	Type
selector	Objects to become subjects of manipulation.	Provider
mode	Default: “once_for_each”. Available: ‘once_for_each’ (if samplers are called, new sampled value is set to each selected entity), ‘once_for_all’ (if samplers are called, value is sampled once and set to all selected entities).	string

Values to set:

Parameter	Description	Type
key	Name of the attribute/custom property to change or a name of a custom function to perform on entities. ” In order to specify, what exactly one wants to modify (e.g. attribute, custom property, etc.): For attribute: key of the pair must be a valid attribute name of the selected object. For custom property: key of the pair must start with cp_ prefix. For calling custom function: key of the pair must start with cf_ prefix. See table below for supported custom function names.	string
value	Value of the attribute/custom prop. to set or input value(s) for a custom function.	string

Custom functions

Parameter	Description	Type
cf_add_modifier	Adds a modifier to the selected object.	dict
cf_add_modifier/name	Name of the modifier to add. Available values: ‘Solidify’.	string.
cf_add_modifier/thickness	‘thickness’ attribute of the ‘Solidify’ modifier.	float
cf_set_shading	Custom function to set the shading of the selected object. Default: ‘FLAT’. Available: [‘FLAT’, ‘SMOOTH’, ‘AUTO’].	str
cf_shading_auto_smooth_angle_in_deg	Angle in degrees at which flat shading is activated in AUTO mode. Default: 30.	float
cf_add_displace_modifier_with_texture	Adds a displace modifier with texture to an object.	dict
cf_add_displace_modifier_with_texture/texture	The structure is either a given or a random texture. Default: []. Available:[‘CLOUDS’,” ‘DISTORTED_NOISE’, ‘MAGIC’, ‘MARBLE’, ‘MUSGRAVE’, ‘NOISE’, ‘STUCCI’, ‘VORONOI’, ‘WOOD’]	str
cf_add_displace_modifier_with_texture/min_vertices_for_subdiv	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. Default: 10000.	int
cf_add_displace_modifier_with_texture/mid_level	Texture value that gives no displacement. Parameter of displace modifier. Default: 0.5	float
cf_add_displace_modifier_with_texture/subdiv_level	Numbers of Subdivisions to perform when rendering. Parameter of Subdivision modifier. Default: 2	int
cf_add_displace_modifier_with_texture/strength	Amount to displace geometry. Parameter of displace modifier. Default: 0.1	float
cf_add_uv_mapping	Adds a uv map to an object if uv map is missing.	dict
cf_add_uv_mapping/projection	Name of the projection as str. Default: []. Available: [“cube”, “cylinder”, “smart”, “sphere”]	str
cf_add_uv_mapping/forced_recalc_of_uv_maps	If this is set to True, all UV maps are recalculated not just the missing ones	bool
cf_randomize_materials	Randomizes the materials for the selected objects with certain probability.	dict
cf_randomize_materials/randomization_level	Expected fraction of the selected objects for which the texture should be randomized. Default: 0.2. Range: [0, 1]	float
cf_randomize_materials/materials_to_replace_with	Material(s) to participate in randomization. Sampling from the pool of elegible material (that comply with conditions is performed in the Provider). Make sure you use ‘random_samples” config parameter of the Provider, if multiple materials are returned, the first one will be considered as a substitute during randomization. Default: random material.	Provider
cf_randomize_materials/obj_materials_cond_to_be_replaced	A dict of materials and corresponding conditions making it possible to only replace materials with certain properties. These are similar to the conditions mentioned in the getter.Material. Default: {}.	dict
cf_randomize_materials/add_to_objects_without_material	If set to True, objects which didn’t have any material before will also get a random material assigned. Default: False.	bool

_add_displace(entity, value)[source]¶

Adds a displace modifier with texture to an object.

Parameters:	entity (`Object`) – An object to modify. Type: bpy.types.Object. value (`dict`) – Configuration data. Type: dict.

_add_modifier(entity, value)[source]¶

Adds modifier to a selected entity.

Parameters:	entity (`Object`) – An entity to modify. Type: bpy.types.Object value (`dict`) – Configuration data. Type: dict.

_add_uv_mapping(entity, value)[source]¶

Adds a uv map to an object if uv map is missing.

Parameters:	entity (`Object`) – An object to modify. Type: bpy.types.Object. value (`dict`) – Configuration data. Type: dict.

_get_the_set_params(params_conf)[source]¶

Extracts actual values to set from a Config object.

Parameters:	params_conf (`Config`) – Object with all user-defined data. Type: Config.
Returns:	Parameters to set as {name of the parameter: it’s value} pairs. Type: dict.

_randomize_materials(entity, value)[source]¶

Replaces each material of an entity with certain probability.

Parameters:	entity (`Object`) – An object to modify. Type: bpy.types.Object. value (`dict`) – Configuration data. Type: dict.

_set_shading(entity, value)[source]¶

Switches shading mode of the selected entity.

Parameters:	entity (`Object`) – An entity to modify. Type: bpy.types.Object value (`dict`) – Configuration data. Type: dict.

_unpack_params(param_config, instructions)[source]¶

Unpacks the data from a config object following the instructions in the dict.

Parameters:	param_config (`Config`) – Structure that contains the unpacked data. Type: Config. instructions (`dict`) – Instruction for unpacking: keys, corresponding Config method to extract the value, default value, and a function to perform on the value after extraction. Type: dict.
Returns:	Unpacked data. Type: dict.

run()[source]¶: Sets according values of defined attributes/custom properties or applies custom functions to the selected entities.