pytha.create_material

Creates a new material in the current PYTHA project.

Adds a material entry, sets its name and initial attributes, and returns an element handle that can be passed to set_element_material and set_element_attributes like any other element handle.

pytha.create_material(name [,options])

Parameter	Type	Description
name	string	Material name. The name has special significance: it is used as the key when materials are saved to .pymat files and shared across documents.
options	{...}	Optional: a table that may contain any of the attribute keys listed below.

Attribute keys (usable in options and in set_element_attributes):

Key	Type	Description
color	{r, g, b}	Base colour in linear sRGB, components in [0, 1].
diffuse	number	Diffuse reflection factor [0, 1].
reflective	number	Specular reflection factor [0, 1].
transparent	number	Transparency factor [0, 1] (0 = opaque).
luminous	number	Self-luminance factor [0, 1].
refractive_index	number	Index of refraction (e.g. 1.5 for glass).
glossiness	number	Gloss sharpness [0, 1] (0 = matte, 1 = mirror).
roughness	number	Surface micro-roughness [0, 1] (physically based; higher values broaden the specular lobe).
texture	path handle	Diffuse texture image (any format PYTHA supports, e.g. PNG, JPG). Takes a path handle, e.g. from pyio.get_plugin_folder_path or pyux.get_library_handle. Raw path strings are not accepted.
bump	path handle	Bump/normal map image. Same rules as texture.
bump_height	number	Strength of the bump map, given as a slope angle in degrees [0, 89]. 0 disables the bump effect; values outside the range are clamped.
texture_mapping	string	Texture projection mode: "flat" (default), "sphere", "cylinder", or "none".
texture_repeat	{u, v}	Texture repeat distance in mm: {width, height} of one tile.
side_material	string	Name of the material used for the narrow faces that run along the grain (the long edges of a board). Must name a material in the current document; an empty string removes the reference, any other non-string value is an error.
front_material	string	Name of the material used for the narrow faces that run across the grain (the end grain faces of a board). Same rules as side_material.
hidden	boolean	true hides the material in the material library UI.
update_thumbnail	boolean	true regenerates the material thumbnail after applying all other options. Pass this last or as part of the same options table; it is applied after all other keys.

Return value:

Type	Description
element_handle	An element handle of type "material" for the newly created material.

Notes:

• The returned handle is a first-class element handle: get_element_type returns "material", handles can be compared with ==.
• Material names must be unique within the document. If a material with the given name already exists, use find_material to retrieve its handle instead of creating a duplicate.
• This function requires modify access and cannot be called from a read-only context.
• side_material and front_material are applied per face: the large faces of a board keep the material itself, the narrow faces along the grain get the side_material, and the end grain faces get the front_material. A face material or an edge banding material takes precedence over both.
• If only side_material is set, it is used for the end grain faces as well. If only front_material is set, the faces along the grain keep the material itself.
• Which faces count as end grain follows the grain direction of the part.
• A material may reference itself.
• get_element_attribute returns the name of the referenced material, or nil if nothing is referenced. A reference to a material that has been deleted in the meantime reads back as empty.

Example:

Create a brass material and assign it to a part:

local brass = pytha.create_material("Brass", {
    color            = { 0.83, 0.69, 0.22 },
    diffuse          = 0.6,
    reflective       = 0.7,
    glossiness       = 0.8,
    roughness        = 0.15,
    update_thumbnail = true,
})

local part = pytha.create_block(50, 30, 10)
pytha.set_element_material(part, brass)

Modify an attribute after creation:

pytha.set_element_attributes(brass, { transparent = 0.2, update_thumbnail = true })

Read an attribute back:

local r = pytha.get_element_attribute(brass, "reflective")  -- returns number
local c = pytha.get_element_attribute(brass, "color")       -- returns {r, g, b}

Create a material with a texture shipped in the plugin folder:

local tex = pyio.get_plugin_folder_path("resource/textures/oak.png")
local wood = pytha.create_material("Oak", {
    texture          = tex,
    texture_mapping  = "flat",
    texture_repeat   = { 600, 600 },
    update_thumbnail = true,
})
pytha.set_element_material(part, wood)

Give a board material its own edge material for the long edges and for the end grain:

pytha.create_material("Oak Edge", {
    color            = { 0.72, 0.55, 0.33 },
    update_thumbnail = true,
})

local board = pytha.create_material("Oak Board", {
    texture          = pyio.get_plugin_folder_path("resource/textures/oak.png"),
    texture_mapping  = "flat",
    texture_repeat   = { 600, 600 },
    side_material    = "Oak Edge",
    front_material   = "Oak Edge",
    update_thumbnail = true,
})

Read the reference back and remove it again:

local edge = pytha.get_element_attribute(board, "side_material")  -- returns "Oak Edge"
pytha.set_element_attributes(board, { side_material = "", front_material = "" })

Let the material reference itself, so that its texture is oriented separately on the edges:

pytha.set_element_attributes(board, {
    side_material  = "Oak Board",
    front_material = "Oak Board",
})

Rename a material:

pytha.set_element_name(brass, "Polished Brass")

Version Support:

Minimum PYTHA Version: V27

See also:

pytha, element handles, path handles, find_material, enumerate_materials, get_element_material, set_element_material, set_element_attributes, get_element_attribute, set_element_name, set_grain_direction, apply_edge_banding