Material
Learn about materials in Pixyz, including PBR patterns, properties, and code examples for creation and modification.
Read time 3 minutesLast updated 8 months ago
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: Inherited, BackFaceCulled, DoubleSided | |
| 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 materialproperties = 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 wayif 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 itdef 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 spheredef 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, layout=material.ImageLayout.RGB, type=material.ImageComponentType.UInt8_Norm, data=bytearray([255, 0, 0, 255, 0, 0, 255, 0, 0, 255, 0, 0])) image = material.createImageFromDefinition(imageDefinition) 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 materialpbrMaterial = convertOccurrenceMaterialToPBR(sphere)createAnImageAndAssignItToPBRTexture(pbrMaterial) #Sphere is now red with a texture as albedo in PBR material