pytha.create_material

Creates a new material in the current PYTHA document.

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

Note: Front-side material and per-face material are not supported.

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	string or file_handle	Path to a diffuse texture image (any format PYTHA supports, e.g. PNG, JPG). Accepts a raw path string or a file handle returned by pyux.select_file.
bump	string or file_handle	Path to a bump/normal map image. Same format rules as texture.
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.
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 ==, and get_element_own_pid returns its persistent ID.
• 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.

Example:

Create a brass material and assign it to a part:

local brass = pytha.create_material("Messing", {
    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_box(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 picked interactively:

local tex = pyux.select_file(".png")
if tex then
    local wood = pytha.create_material("Eiche", {
        texture         = tex,
        texture_mapping = "flat",
        texture_repeat  = { 600, 600 },
        update_thumbnail = true,
    })
    pytha.set_element_material(part, wood)
end

Rename a material:

pytha.set_element_name(brass, "Messing poliert")

Version Support:

Minimum PYTHA Version: V27

See also:

pytha, element handles, find_material, enumerate_materials, get_element_material, set_element_material, set_element_attributes, get_element_attribute, set_element_name