Material Shape Attributes

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

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

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

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

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

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

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

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

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

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

N

N

N

OBJ

N

N

N

SLPK

N

N

N

Unreal

N

N

N

USD

N

N

N

Vue

Y

Y

N

WebScene

N

N

N

Related

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)

In this topic