material

The material shape attributes control the shading, texturing and export of the shape’s geometry. CityEngine supports ten texture channels with a fixed semantic.

All of these attributes can be changed using the set or setMaterial operations. You can use the print operation to output the value of a certain material attribute, eg. print(material.colormap.r).

Syntax

string material.nameThe name of the material.
string material.shaderThe shader name.Default is “CityEngineShader”. Setting it to “CityEnginePBRShader” signals that the physically-based rendering attributes should be used, see PBR material attributes.
float material.color.{r|g|b}Diffuse color. Individual access to each color component. Default is white. See material.color attribute.
string material.color.rgbDiffuse color. Access to the complete color as hex-formatted string, eg. RED = “#ff0000”. Default is “#ffffff”. See material.color attribute.
float material.ambient.{r|g|b}Ambient color. Individual access to each color component. Default is black.
float material.specular.{r|g|b}Specular color. Individual access to each color component. Default is black.
float material.emissive.{r|g|b}Emissive color. Individual access to each color component. Default is black.
float material.opacityOpacity factor. 1 is fully opaque, 0 is fully transparent. Default is 1.
float material.reflectivityReflectivity factor. 0 is no reflection, 1 is full reflection (of the Reflection Map set in the Panorama settings). Note that reflection depends on the specular color: the default black color means no reflection.
float material.shininessPhong specular exponent in the range [0, 128]. Default is 1.
float material.bumpValueControls the bump scaling factor (if material.bumpmap is set). Default is 1.
float material.metallicControls the metallic factor (if material.metallicmap is set). 0 is a dielectric material, 1 is a metallic material. Default is 0.
float material.roughnessControls the roughness factor (if material.roughnessmap is set). 0 is a completely smooth material, 1 is a completely rough material. Default is 1.
string material.colormapTexture file paths for the texture channels. See material.map attribute.
string material.bumpmap
string material.dirtmap
string material.specularmap
string material.opacitymap
string material.normalmap
string material.emissivemap
string material.occlusionmap
string material.roughnessmap
string material.metallicmap
float material.{colormap|…|metallicmap}.s{u|v}Per-channel texture scaling factors.
float material.{colormap|…|metallicmap}.t{u|v}Per-channel texture translation factors.
float material.{colormap|…|metallicmap}.rwPer-channel texture rotation factors. The texture is rotated around the w-axis (w is the cross product of u and v).
string material.opacitymap.modeControls how the opacitymap is combined with the colormap. Valid values are “blend”, “mask” and “opaque”. Default is “blend”.
float material.opacitymap.cutoffWhen material.opacitymap.mode is set to “mask”, the material.opacitymap.cutoff attribute specifies the cutoff threshold. If the alpha value is greater than or equal to the cutoff value then it is rendered as fully opaque, otherwise it is rendered as fully transparent. This attribute is ignored for other modes than “mask”. Default is 0.5.

PBR material attributes

Some material attributes are designed to be exclusively used for physically-based rendering (PBR) shaders. These are:

  • material.emissivemap
  • material.occlusionmap
  • material.roughnessmap
  • material.metallicmap
  • material.emissive.{r|g|b}
  • material.metallic
  • material.roughness

If the shader name is set to “CityEnginePBRShader”, the Viewport and encoders which support PBR materials use those attributes as well as the

  • material.color.{r|g|b}
  • material.colormap
  • material.normalmap
  • material.opacity
  • material.opacitymap
  • material.opacitymap.mode
  • material.opacitymap.cutoff

attributes.

Here is how the CGA material attributes correspond to the GLTF material specification, which is based on Physically-Based Rendering (PBR).

CGA material attributesGLTF material specification
material.color.{r|g|b}pbrMetallicRoughness.baseColorFactor, RGB components
material.opacitypbrMetallicRoughness.baseColorFactor, A component
material.colormappbrMetallicRoughness.baseColorTexture, RGB channels
material.opacitymappbrMetallicRoughness.baseColorTexture, A channel
material.metallicpbrMetallicRoughness.metallicFactor
material.roughnesspbrMetallicRoughness.roughnessFactor
material.metallicmap, B channelpbrMetallicRoughness.metallicRoughnessTexture, B channel
material.roughnessmap, G channelpbrMetallicRoughness.metallicRoughnessTexture , G channel
material.normalmapnormalTexture
material.occlusionmap, R channelocclusionTexture, R channel
material.emissivemapemissiveTexture
material.emissiveemissiveFactor
material.opacitymap.modealphaMode
material.opacitymap.cutoffalphaCutoff

Rendering, import, and export

For asset and generated model preview, importing and for exporting the generated models, the material attributes need to be mapped to and from the respective format. The following tables show what format implements which feature. This tables only list the formats relevant for CGA, not general CityEngine.

Basic Material Attributes

Extensionsnameshadercolorcolormapdirtmap
DisplayAsset Preview / 3D ViewportNY1Y2Y2Y2
ImportKhronos Collada.dae/.kml/.kmzYNY3Y3Y
Autodesk DWG.dwgNNYYN
Autodesk FBX.fbxYNYYY
Khronos glTF.gltf/.glbYNYYN
Wavefront OBJ.objYNYYN
Universal Scene Description (USD).usda/.usdc/.usdzNNYYN
ExportAlembic.abcYYYYY
Khronos Collada.dae/.kml/.kmzYNY3Y3Y
Autodesk DWG.dwgNNYYN
Autodesk FBX.fbxYNYYY
Esri FileGDB.gdbNNYYN
Khronos glTF.gltf/.glbYNYYN
Wavefront OBJ.objYNYYN
SceneLayer Package (SLPK).slpkNNYYN
Unreal Datasmith.udatasmithYYYYY
Universal Scene Description (USD).usdc/.usdzYY4Y5YN
Vue.vobYNYYY
CityEngine WebScene 3ws.3wsNNYYN
  • 1 For the Viewport, the shader name is used to switch between standard and PBR rendering, see the PBR Material Attributes section above.
  • 2 In the Viewport, the colormap and dirtmap values are multiplied with the (diffuse) color.
  • 3 The official COLLADA standard does not support a diffuse solid color and a diffuse texture at the same time.
  • 4 The USD exporter always creates an USDPreviewSurface shader. If the shader name is set to PBR, the PBR attributes will be exported as well (see PBR Material Attributes above).
  • 5 If a map is present the corresponding scalar value is ignored.

Advanced Material Attributes

opacityopacitymapopacitymap.modeopacitymap.cutoffnormalmap
DisplayViewportYYYYY
ImportColladaYYNNY
DWGYYNNN
FBXYYNNY
glTFYYYYY
OBJYYNNN
USDYYYYY
ExportAlembicYYYNY
ColladaYYNNY
DWGYYNNN
FBXYYNNY
FileGDBYNNNN
glTFYYYYY
OBJYYNNN
SLPKYYNNY
UnrealYYYNY
USDY5YYYY
VueYYNNN
WebSceneYY6NNN
  • 5 If a map is present the corresponding scalar value is ignored.
  • 6 The opacitymap attribute is exported if it is pointing to the same image as the colormap attribute and if the image has an alpha channel.

Legacy Material Attributes

ambientspecularspecularmapreflectivityshininessbumpValuebumpmap
DisplayViewportYYYYYYY
ImportColladaYYYYYYY
DWGYYYYYYY
FBXYYYYYNY
glTFNNNNNNN
OBJYYYNYYY
USDNNNNNNN
ExportAlembicYYYYYYY
ColladaYYYYYYY
DWGYYYYYYY
FBXYYYYYNY
FileGDBNNNNNNN
glTFNNNNNNN
OBJYYYNYYY
SLPKYNNNNNN
UnrealYYYYYYY
USDNNNYYYY
VueNYYNNNN
WebSceneYYNYYNN

Physically-Based Rendering Material Attributes

emissiveemissivemapmetallicmetallicmaproughnessroughnessmapocclusionmap
DisplayViewportYYYYYYY
ImportColladaNNNNNNN
DWGNNNNNNN
FBXNNNNNNN
glTFYYYYYYY
OBJNNNNNNN
USDYYYYYYY
ExportAlembicYYYYYYY
ColladaNNNNNNN
DWGNNNNNNN
FBXNNNNNNN
FileGDBNNNNNNN
glTFYYYYYYY
OBJNNNNNNN
SLPKYYYYYYY
UnrealYYYYYYY
USDYYY5YY5YY
VueNNNNNNN
WebSceneNNNNNNN
  • 5 If a map is present the corresponding scalar value is ignored.

Map Transform Material Attributes

map.tu/.tvmap.su/.svmap.rw
DisplayViewportYYY
ImportColladaYYY
DWGNNN
FBXYYY
glTFNNN
OBJNYN
USDNNN
ExportAlembicYYY
ColladaYYY
DWGNNN
FBXYYY
FileGDBNNN
glTFNNN
OBJNNN
SLPKNNN
UnrealNNN
USDNNN
VueYYN
WebSceneNNN

Examples

attr wallC       = "#FFFFFF"
attr wallTexture = "facade/walls/wall.c.09.tif"
attr dirtTexture = "dirtmaps/dirtmap.16.tif"
...
Wall --> 
    primitiveCube() color(wallC)
    set(material.colormap, wallTexture) projectUV(0)
    set(material.dirtmap, dirtTexture) projectUV(2)

Was this article helpful?