Back to Top

Material Shape Attributes

In this topic

    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.color.r).

    Syntax

    string material.name

    The name of the material.

    string material.shader

    The 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.rgb

    Diffuse 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.opacity

    Opacity factor. 1 is fully opaque, 0 is fully transparent. Default is 1.

    float material.reflectivity

    Reflectivity 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.shininess

    Phong specular exponent in the range [0, 128]. Default is 1.

    float material.bumpValue

    Controls the bump scaling factor (if material.bumpmap is set). Default is 1.

    float material.metallic

    Controls the metallic factor (if material.metallicmap is set). 0 is a dielectric material, 1 is a metallic material. Default is 0.

    float material.roughness

    Controls 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.colormap

    Texture 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}.rw

    Per-channel texture rotation factors. The texture is rotated around the w-axis (w is the cross product of u and v).

    string material.opacitymap.mode

    Controls how the opacitymap is combined with the colormap. Valid values are "blend", "mask" and "opaque". Default is "blend".

    float material.opacitymap.cutoff

    When 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.opacity

    pbrMetallicRoughness.baseColorFactor, A component

    material.colormap

    pbrMetallicRoughness.baseColorTexture, RGB channels

    material.opacitymap

    pbrMetallicRoughness.baseColorTexture, A channel

    material.metallic

    pbrMetallicRoughness.metallicFactor

    material.roughness

    pbrMetallicRoughness.roughnessFactor

    material.metallicmap, B channel

    pbrMetallicRoughness.metallicRoughnessTexture, B channel

    material.roughnessmap, G channel

    pbrMetallicRoughness.metallicRoughnessTexture , G channel

    material.normalmap

    normalTexture

    material.occlusionmap, R channel

    occlusionTexture, R channel

    material.emissivemap

    emissiveTexture

    material.emissive

    emissiveFactor

    material.opacitymap.mode

    alphaMode

    material.opacitymap.cutoff

    alphaCutoff

    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

    Extensions

    name

    shader

    color

    colormap

    dirtmap

    Display

    Asset Preview / 3D Viewport

    N

    Y1

    Y2

    Y2

    Y2

    Import

    Khronos Collada

    .dae/.kml/.kmz

    Y

    N

    Y3

    Y3

    Y

    Autodesk DWG

    .dwg

    N

    N

    Y

    Y

    N

    Autodesk FBX

    .fbx

    Y

    N

    Y

    Y

    Y

    Khronos glTF

    .gltf/.glb

    Y

    N

    Y

    Y

    N

    buildingSMART IFC

    .ifc

    N

    N

    Y

    N

    N

    Wavefront OBJ

    .obj

    Y

    N

    Y

    Y

    N

    Universal Scene Description (USD)

    .usda/.usdc/.usdz

    N

    N

    Y

    Y

    N

    Export

    Alembic

    .abc

    Y

    Y

    Y

    Y

    Y

    Khronos Collada

    .dae/.kml/.kmz

    Y

    N

    Y3

    Y3

    Y

    Autodesk DWG

    .dwg

    N

    N

    Y

    Y

    N

    Autodesk FBX

    .fbx

    Y

    N

    Y

    Y

    Y

    Esri FileGDB

    .gdb

    N

    N

    Y

    Y

    N

    Khronos glTF

    .gltf/.glb

    Y

    N

    Y

    Y

    N

    buildingSMART IFC

    .ifc

    N

    N

    Y

    N

    N

    Wavefront OBJ

    .obj

    Y

    N

    Y

    Y

    N

    SceneLayer Package (SLPK)

    .slpk

    N

    N

    Y

    Y

    N

    Unreal Datasmith

    .udatasmith

    Y

    Y

    Y

    Y

    Y

    Universal Scene Description (USD)

    .usdc/.usdz

    Y

    Y4

    Y5

    Y

    N

    Vue

    .vob

    Y

    N

    Y

    Y

    Y

    CityEngine WebScene 3ws

    .3ws

    N

    N

    Y

    Y

    N

    • 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

    opacity

    opacitymap

    opacitymap.mode

    opacitymap.cutoff

    normalmap

    Display

    Viewport

    Y

    Y

    Y

    Y

    Y

    Import

    Collada

    Y

    Y

    N

    N

    Y

    DWG

    Y

    Y

    N

    N

    N

    FBX

    Y

    Y

    N

    N

    Y

    glTF

    Y

    Y

    Y

    Y

    Y

    IFC

    Y

    N

    N

    N

    N

    OBJ

    Y

    Y

    N

    N

    N

    USD

    Y

    Y

    Y

    Y

    Y

    Export

    Alembic

    Y

    Y

    Y

    N

    Y

    Collada

    Y

    Y

    N

    N

    Y

    DWG

    Y

    Y

    N

    N

    N

    FBX

    Y

    Y

    N

    N

    Y

    FileGDB

    Y

    N

    N

    N

    N

    glTF

    Y

    Y

    Y

    Y

    Y

    IFC

    Y

    N

    N

    N

    N

    OBJ

    Y

    Y

    N

    N

    N

    SLPK

    Y

    Y

    N

    N

    Y

    Unreal

    Y

    Y

    Y

    N

    Y

    USD

    Y5

    Y

    Y

    Y

    Y

    Vue

    Y

    Y

    N

    N

    N

    WebScene

    Y

    Y6

    N

    N

    N

    • 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

    ambient

    specular

    specularmap

    reflectivity

    shininess

    bumpValue

    bumpmap

    Display

    Viewport

    Y

    Y

    Y

    Y

    Y

    Y

    Y

    Import

    Collada

    Y

    Y

    Y

    Y

    Y

    Y

    Y

    DWG

    Y

    Y

    Y

    Y

    Y

    Y

    Y

    FBX

    Y

    Y

    Y

    Y

    Y

    N

    Y

    glTF

    N

    N

    N

    N

    N

    N

    N

    IFC

    N

    N

    N

    N

    N

    N

    N

    OBJ

    Y

    Y

    Y

    N

    Y

    Y

    Y

    USD

    N

    N

    N

    N

    N

    N

    N

    Export

    Alembic

    Y

    Y

    Y

    Y

    Y

    Y

    Y

    Collada

    Y

    Y

    Y

    Y

    Y

    Y

    Y

    DWG

    Y

    Y

    Y

    Y

    Y

    Y

    Y

    FBX

    Y

    Y

    Y

    Y

    Y

    N

    Y

    FileGDB

    N

    N

    N

    N

    N

    N

    N

    glTF

    N

    N

    N

    N

    N

    N

    N

    IFC

    N

    N

    N

    N

    N

    N

    N

    OBJ

    Y

    Y

    Y

    N

    Y

    Y

    Y

    SLPK

    Y

    N

    N

    N

    N

    N

    N

    Unreal

    Y

    Y

    Y

    Y

    Y

    Y

    Y

    USD

    N

    N

    N

    Y

    Y

    Y

    Y

    Vue

    N

    Y

    Y

    N

    N

    N

    N

    WebScene

    Y

    Y

    N

    Y

    Y

    N

    N

     

    Physically-Based Rendering Material Attributes

    emissive

    emissivemap

    metallic

    metallicmap

    roughness

    roughnessmap

    occlusionmap

    Display

    Viewport

    Y

    Y

    Y

    Y

    Y

    Y

    Y

    Import

    Collada

    N

    N

    N

    N

    N

    N

    N

    DWG

    N

    N

    N

    N

    N

    N

    N

    FBX

    N

    N

    N

    N

    N

    N

    N

    glTF

    Y

    Y

    Y

    Y

    Y

    Y

    Y

    IFC

    N

    N

    N

    N

    N

    N

    N

    OBJ

    N

    N

    N

    N

    N

    N

    N

    USD

    Y

    Y

    Y

    Y

    Y

    Y

    Y

    Export

    Alembic

    Y

    Y

    Y

    Y

    Y

    Y

    Y

    Collada

    N

    N

    N

    N

    N

    N

    N

    DWG

    N

    N

    N

    N

    N

    N

    N

    FBX

    N

    N

    N

    N

    N

    N

    N

    FileGDB

    N

    N

    N

    N

    N

    N

    N

    glTF

    Y

    Y

    Y

    Y

    Y

    Y

    Y

    IFC

    N

    N

    N

    N

    N

    N

    N

    OBJ

    N

    N

    N

    N

    N

    N

    N

    SLPK

    Y

    Y

    Y

    Y

    Y

    Y

    Y

    Unreal

    Y

    Y

    Y

    Y

    Y

    Y

    Y

    USD

    Y

    Y

    Y5

    Y

    Y5

    Y

    Y

    Vue

    N

    N

    N

    N

    N

    N

    N

    WebScene

    N

    N

    N

    N

    N

    N

    N

    • 5 If a map is present the corresponding scalar value is ignored.

    Map Transform Material Attributes

    map.tu/.tv

    map.su/.sv

    map.rw

    Display

    Viewport

    Y

    Y

    Y

    Import

    Collada

    Y

    Y

    Y

    DWG

    N

    N

    N

    FBX

    Y

    Y

    Y

    glTF

    Y 7

    Y 7

    Y 7

    IFC

    N

    N

    N

    OBJ

    N

    Y

    N

    USD

    N

    N

    N

    Export

    Alembic

    Y

    Y

    Y

    Collada

    Y

    Y

    Y

    DWG

    N

    N

    N

    FBX

    Y

    Y

    Y

    FileGDB

    N

    N

    N

    glTF

    Y 7

    Y 7

    Y 7

    IFC

    N

    N

    N

    OBJ

    N

    N

    N

    SLPK

    N

    N

    N

    Unreal

    N

    N

    N

    USD

    Y

    Y

    Y

    Vue

    Y

    Y

    N

    WebScene

    N

    N

    N

    • 7 Transforms are read and written using the KHR_texture_transform extension.

    Related

    • print operation
    • projectUV operation
    • set operation
    • setupProjection operation
    • resetMaterial operation
    • setMaterial operation
    • getMaterial function
    • Texturing: Essential Knowledge
    • Export models overview

    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)

    Feedback on this topic?

    In this topic