blenderproc.python.modules.manipulators.MaterialManipulator module

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

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

Performs manipulation os selected materials.

Example 1: Link image texture output of the ‘Material.001’ material to displacement input of the shader with a
strength factor of 1.5.
{
  "module": "manipulators.MaterialManipulator",
  "config": {
    "selector": {
      "provider": "getter.Material",
      "conditions": {
        "name": "Material.001"
      }
    },
    "cf_color_link_to_displacement": 1.5
  }
}

Example 2: Set base color of all materials matching the name pattern to white.

{
  "module": "manipulators.MaterialManipulator",
  "config": {
    "selector": {
      "provider": "getter.Material",
      "conditions": {
        "name": ".*material.*"
      }
    },
    "cf_set_base_color": [1, 1, 1, 1]
  }
}

Example 3: For all materials matching the name pattern switch to the Emission shader with emitted light of red color of energy 15.

{
  "module": "manipulators.MaterialManipulator",
  "config": {
    "selector": {
      "provider": "getter.Material",
      "conditions": {
        "name": ".*material.*"
      }
    },
    "cf_switch_to_emission_shader": {
      "color": [1, 0, 0, 1],
      "strength": 15
    }
  }
}

Example 4: Add a layer of dust to all materials. By using a random generated dust texture. The strength here determines how thick the dust layer is. The texture scale determines the size of the dust flakes. At one it gets the same as the normal texture on the object. Be aware that each object needs a UV map so that the dust flakes are properly displayed.

{
  "module": "manipulators.MaterialManipulator",
  "config":{
    "selector": {
      "provider": "getter.Material",
      "conditions": {
        "name": ".*",
        "use_nodes": True
      }
    },
    "cf_add_dust": {
      "strength": 0.8,
      "texture_scale": 0.05
    }
  }
}

Example 5: Add a layer of dust to all materials. In this example the focus is on loading a texture with the TextureLoader and using it with the MaterialManipulator.

{
  "module": "loader.TextureLoader",
  "config": {
    "path": "<args:0>",
    "add_properties": {
      "cp_dust_texture": True
    }
  }
},
{
  "module": "manipulators.MaterialManipulator",
  "config":{
    "selector": {
      "provider": "getter.Material",
      "conditions": {
        "name": ".*",
        "use_nodes": True
      }
    },
    "cf_add_dust": {
      "strength": 0.8,
      "used_dust_texture": {
        "provider": "getter.Texture",
        "conditions": {
          "cp_dust_texture": True
        }
      },
      "texture_scale": 0.05
    }
  }
}

Example 6: Adds a texture as an overlay over all materials, which are currently used. First the texture is loaded, via the TextureLoader and then it is used inside of the “cf_infuse_texture”

{
  "module": "loader.TextureLoader",
  "config":{
    "path": "<args:3>",
    "add_properties": {
      "cp_dust_texture": True
    }
  }
},
{
  "module": "manipulators.MaterialManipulator",
  "config": {
    "selector": {
      "provider": "getter.Material",
      "conditions": {
       "cf_use_materials_of_objects": {
         "provider": "getter.Entity",
         "conditions": {
           "type": "MESH"
         }
       },
      }
    },
    "cf_infuse_texture": {
      "mode": "mix",
      "texture_scale": 1.0,
      "used_texture": {
        "provider": "getter.Texture",
        "conditions": {
          "cp_dust_texture": True
        }
      }
    }
  }
}

Example 7: Combines two materials, this mixes all currently used materials, with all cc materials.

{
  "module": "manipulators.MaterialManipulator",
  "config": {
   "selector": {
     "provider": "getter.Material",
     "conditions": {
      "cf_use_materials_of_objects": {
        "provider": "getter.Entity",
        "conditions": {
          "type": "MESH"
        }
      },
     }
   },
   "cf_infuse_material": {
    "mode": "mix",
    "used_material": {
      "provider": "getter.Material",
      "check_empty": True,
      "conditions": {
        "cp_is_cc_texture": True
      }
    }
   }
  }
}

Configuration:

Parameter Description Type
selector Materials to become subjects of manipulation. Provider
mode Mode of operation. Default: “once_for_each”. Available: ‘once_for_each’ (if samplers are called, new sampled value is set to each selected material), ‘once_for_all’ (sampling once for all of the selected materials). string

Values to set:

Parameter Description Type
key Name of the attribute to change or a name of a custom function to perform on materials. ” 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 material. 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, list/Vector, int, bool or float

Available custom functions:

Parameter Description Type
cf_color_link_to_displacement Factor that determines the strength of the displacement via linking the output of the texture image to the displacement float
cf_change_to_vertex_color The name of the vertex color layer, used for changing the material to a vertex coloring mode. The object is still able to reflect light and influence the light around it string
change_to_vertex_color_no_shading The name of the vertex color layer, used for changing the material to a vertex coloring mode. For this no shading is used. string
cf_textures Texture data as {texture_type (type of the image/map, i.e. color, roughness, reflection, etc.): texture_path} pairs. Texture_type should be equal to the Shader input name in order to be assigned to a ShaderTexImage node that will be linked to this input. Label represents to which shader input this node is connected. dict
cf_textures/texture_path Path to a texture image. string
cf_switch_to_emission_shader Adds the Emission shader to the target material, sets it’s ‘color’ and ‘strength’ values, connects it to the Material Output node. dict
cf_switch_to_emission_shader/color [R, G, B, A] vector representing the color of the emitted light. mathutils.Vector
cf_switch_to_emission_shader/strength Strength of the emitted light. Must be >0. float
cf_add_dust Adds a layer of dust on all target materials. Dust is always presented on every surface facing upwards in Z-direction. dict
cf_add_dust/strength This determines the strength of the dust, 0 means no dust 1.0 means full dust. Values above 1.0 are possible, but create a thick film out of dust, which hides the material completely. float
cf_add_dust/used_dust_texture If a specific dust texture should be used, this can be specified. Use a getter.Texture to return a loaded texture. If this is empty a random noise texture is generated. getter.Texture
cf_add_dust/texture_scale This scale is used to scale down the used noise texture (even for the case where a random noise texture is used). Default: 0.1. float
cf_infuse_texture With this custom function it is possible to overlay materials with a certain texture. This only works if there is one principled BSDF shader in this material, it will be used as a reference point. dict
cf_infuse_texture/mode The mode determines how the texture is used. There are three options: “overlay” in which the selected texture is overlayed over a preexisting one. If there is none, nothing happens. The second option: “mix” is similar to overlay, just that the textures are mixed there. The last option: “set” replaces any existing texture and is even added if there was none before. Default: “overlay”. Available: [“overlay”, “mix”, “set”]. str
cf_infuse_texture/used_texture A getter.Texture can be used here to select the texture, which should be infused in the material. getter.Texture
cf_infuse_texture/connection By default the “Base Color” input of the principled shader will be used. This can be changed to any valid input of a principled shader. Default: “Base Color”. For available check the blender documentation. str
cf_infuse_texture/strength The strength determines how much the newly generated texture is going to be used. Default: 0.5. float
cf_infuse_texture/texture_scale The used texture can be scaled down or up by a factor, to make it match the preexisting UV mapping. Make sure that the object has a UV mapping beforehand. Default: 0.05. float
cf_infuse_texture/invert_texture It might be sometimes useful to invert the input texture, this can be done by setting this to True. Default: False. bool
cf_infuse_material This can be used to fuse two materials together, this is applied to the selected materials. One can select inside of this the materials which will be copied inside of the other materials. Be aware this affects more than just the color it will also affect the displacement and the volume of the material. dict
cf_infuse_material/used_material This selector (getter.Material) is used to select the materials, which will be copied into the materials selected by the “selector”. getter.Material
cf_infuse_material/mode The mode determines how the two materials are mixed. There are two options “mix” in which the preexisting material is mixed with the selected one in “used_material” or “add” in which they are just added on top of each other. Default: “mix”. Available: [“mix”, “add”] str
cf_infuse_material/mix_strength In the “mix” mode a strength can be set to determine how much of each material is going to be used. A strength of 1.0 means that the new material is going to be used completely. Default: 0.5. float
cf_set_* Sets value to the * (suffix) input of the Principled BSDF shader. Replace * with all lower-case name of the input (use ‘_’ if those are represented by multiple nodes, e.g. ‘Base Color’ -> ‘base_color’). Also deletes any links to this shader’s input point. list/Vector, int or float
cf_add_* Adds value to the * (suffix) input of the Principled BSDF shader. Replace * with all lower-case name of the input (use ‘_’ if those are represented by multiple nodes, e.g. ‘Base Color’ -> ‘base_color’). Also deletes any links to this shader’s input point. The values are not clipped in the end. list/Vector, int or float
_add_dust_to_material(material, value)[source]

Adds a dust film to the material, where the strength determines how much dust is used.

This will be added right before the output of the material.

Parameters:
  • material (Material) – Used material
  • value (dict) – dict with all used keys
_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.
Return type:dict
Returns:Parameters to set as {name of the parameter: it’s value} pairs.
static _infuse_material(material, config)[source]

Infuse a material inside of another material. The given material, will be adapted and the used material, will be added, depending on the mode either as add or as mix. This change is applied to all outputs of the material, this include the Surface (Color) and also the displacement and volume. For displacement mix means multiply.

Parameters:
  • material (Material) – Used material
  • config (Config) – Used config
static _infuse_texture(material, config)[source]

Overlays the selected material with a texture, this can be either a color texture like for example dirt or it can be a texture, which is used as an input to the Principled BSDF of the given material.

Parameters:
  • material (Material) – Material, which will be changed
  • config (Config) – containing the config information

Link the output of the texture image to the displacement. Fails if there is more than one texture image.

Parameters:
  • material (Material) – Material to be modified.
  • multiply_factor (float) – Multiplication factor of the displacement.
_load_textures(text_paths)[source]

Loads textures.

Parameters:text_paths (dict) – Texture data.
Return type:dict
Returns:Loaded texture data.
static _map_vertex_color(material, layer_name, active_shading=True)[source]

Replaces the material with a mapping of the vertex color to a background color node.

Parameters:
  • material (Material) – Material to be modified.
  • layer_name (str) – Name of the vertex color layer.
  • active_shading (bool) – Whether to keep the principled bsdf shader. If True, the material properties influence light reflections such as specularity, roughness, etc. alter the object’s appearance. Type: bool.
static _op_principled_shader_value(material, shader_input_key, value, operation)[source]

Sets or adds the given value to the shader_input_key of the principled shader in the material

Parameters:
  • material (Material) – Material to be modified.
  • shader_input_key (str) – Name of the shader’s input.
  • value (Any) – Value to set.
_set_textures(loaded_textures, material)[source]
Creates a ShaderNodeTexImage node, assigns a loaded image to it and connects it to the shader of the
selected material.
Parameters:
  • loaded_textures (dict) – Loaded texture data.
  • material (Material) – Material to be modified.
_switch_to_emission_shader(material, value)[source]
Adds the Emission shader to the target material, sets it’s color and strength values, connects it to
the Material Output node.
Parameters:
  • material (Material) – Material to be modified.
  • value (dict) – Light color and strength data.
run()[source]

Sets according values of defined attributes or applies custom functions to the selected materials. 1. Select materials. 2. For each parameter to modify, set it’s value to all selected objects.