Material

API reference

Materials are entities containing visual definitions. Materials can be attached to part components or occurrences. Use core.setProperty(occ, "Material", str(materialId)) to set an occurrence material property (value can be set to "0" to clear the property).

They are defined by a pattern and properties that are specific to each pattern.

PBR pattern

Physically Based Rendering materials are a more complex way of decribing lightning than what standard materials is offering. It allows to achieve a better visual quality than with more simple lit materials. Almost all 3D realtime engine implement PBR approach, and some 3D file formats like glTF have standardized channels and shader implementation.

This table shows the properties of Pixyz PBR materials:

Property	Type	Description
Name	String
albedo	ColorOrTexture
normal	ColorOrTexture
metallic	CoeffOrTexture
roughness	CoeffOrTexture
ao	CoeffOrTexture
opacity	CoeffOrTexture
emissive	ColorOrTexture
Id	Ident	A unique unsigned int identifier
DepthTestEnabled	Boolean
BackFaceMode	Enum: - 0 - 1 - 2
R	Boolean	Red mask
G	Boolean	Green mask
B	Boolean	Blue mask
A	Boolean	Alpha mask

Tip

Exporting your scene and objects using format supporting standardized PBR materials like glTF, will ensure you to preserve a good visual quality when you will import your file in another tool.

Code example

Create a sphere with a PBR material attached

Let's create a test scene with PBR material assigned to a sphere

sphere = scene.createSphere(30, 16, 16, True)
mat1 = material.createMaterial("my_custom_PBR_material", "PBR")
scene.setOccurrenceMaterial(sphere, mat1)
core.setProperty(mat1, "albedo", "COLOR([1.0, 0, 1.0])")
core.setProperty(mat1, "roughness", "COEFF(0.1)")
core.setProperty(mat1, "metallic", "COEFF(0.2)")
core.setProperty(mat1, "opacity", "COEFF(0.3)")

# We can check all the properties from the Occurence material
properties = core.listProperties(mat1)
print("My material properties: " + str(properties))

# By knowning it's a PBR material, we can access to material properties in an easier way
if material.getMaterialPattern(mat1) == "PBR":
    materialInfo = material.getPBRMaterialInfos(mat1)
    print("My material PBR metallic value is: " + str(materialInfo.metallic))

Retrieve material, convert it to PBR and assign texture

To enhance the visual quality of our model, we want to retrieve a specific material, convert it to PBR then assign a texture.

# Create a sphere and add a "standard" material to it
def createTestOccurrenceWithMaterial():
    sphere = scene.createSphere(30, 30, 30, True)
    mat2 = material.createMaterial("my_material", "standard")
    scene.setOccurrenceMaterial(sphere, mat2)
    core.setProperty(mat2, "diffuse", "COLOR([0.0, 0.0, 0.8])")
    core.setProperty(mat2, "specular", "COLOR([1.0, 1.0, 1.0])")
    core.setProperty(mat2, "ambient", "COLOR([1.0, 0.0, 0.0])")
    return sphere


def convertOccurrenceMaterialToPBR(occurrence):
    materialList = scene.getMaterialsFromSubtree(occurrence)
    print("My initial material pattern is: " + material.getMaterialPattern(materialList[0]))
    scene.convertMaterialsToPBR(materialList)
    print("My new material pattern is: " + material.getMaterialPattern(materialList[0]))
    return materialList[0]


def createAnImageAndAssignItToPBRTexture(pbrMaterial):
    # We could use material.importImage(path) to import an image
    # But let's create a red image with 4 pixels from RAW data for learning purpose
    imageDefinition = material.ImageDefinition(name="my custom image",
                                               id=0,  # Filled later when we will create the image
                                               width=2,
                                               height=2,
                                               bitsPerComponent=8,
                                               componentsCount=3,  # encoded as R,G,B
                                               data=bytearray([255, 0, 0, 255, 0, 0, 255, 0, 0, 255, 0, 0]))
    image = material.createImageFromDefinition(imageDefinition)
    imageDefinition.id = image
    albedo_texture = material.Texture(image=image, channel=0, offset=geom.Point2(0, 0), tilling=geom.Point2(0, 0))
    materialInfo = material.getPBRMaterialInfos(pbrMaterial)
    materialInfo.albedo = ['texture', albedo_texture]
    material.setPBRMaterialInfos(pbrMaterial, materialInfo)


sphere = createTestOccurrenceWithMaterial() #Sphere is blue in standard material
pbrMaterial = convertOccurrenceMaterialToPBR(sphere)
createAnImageAndAssignItToPBRTexture(pbrMaterial) #Sphere is now red with a texture as albedo in PBR material