Tutorial Notes – 03 Map Control

GIS professionals typically work with raster files, usually TIFs, whose individual cell values represent some kind of geographic data such as elevation.  In CityEngine, we can use use raster files to build mapping layers that drive attributes in our models. In this tutorial, mappings created from color channels in two PNG files control building height (Figure 2, left) and delineate land use classifications (Figure 2, right).

Figure 2: PNG files used to create mapping layers for building heights and land use

First, we are shown how attributes we write in CGA rule files (e.g. attr height = 80) appear as default values in the Shape Inspector>Rules dropdown (Figure 3). The default attribute is applied to buildings generated with the rule file. We change building height by entering a new value in the Inspector; we can return the value to default by selecting “Rule default” from the drop-down menu in the Inspector.

Figure 3: The Shape Inspector > Rules dropdown

Next, we create two new mapping layers in the scene inspector by selecting a PNG image file and resizing it to fit the extent (bounds) of our model (3000 x 3000 pixels).  Under Mappings (Figure 4) we create a map of values — in this case, to control building heights in our model — using the PNG image’s red color channel. Building heights are set at a minimum of 20 meters for cells with 0% red values and a maximum 200 meters for cells with 100% red values. The amount of red in individual cells can be seen when the image is magnified. Note that we connect model attributes to mappings by using the Shape Inspector>Rules dropdown and selecting “Connect Attribute”.

Figure 4: Creating a mapping file using the image red channel (L); a close-up of the image file shows pixels with red channel values between 0% and 100%.


What if we wanted to vary building heights and modify land use areas during a design session?

  • We would need the ability to change the PNG raster files “on the fly”.  I experimented with the building height raster and discovered when I modified and saved the file during an open session, it would update in CityEngine in as little as 5 seconds without my doing anything, though some refresh times were 10 seconds or longer. After the refresh, the model could be regenerated. In Figure 5, note the narrow strip of tall buildings created with a modified mapping layer, in this case, with all red values either 0% or 100%. Buildings retained their colors and land use assignments. Figure 6 shows the window where code is modified.
  • Note that the values we set when creating a mapping can be changed in the model. Remember, building height values were set for a minimum of 20 meters in 0% red pixels and 200 meters in 100% red pixels. When you select the mapping in the Scene Inspector, it’s parameters will appear as code in the Layer Inspector. Simply change the value in the code and regenerate the layer. REMEMBER TO SAVE ANY CHANGES YOU WANT TO KEEP!
Figure 5: a narrow strip of tall buildings created with red in a modified mapping layer
Figure 6: Mapping Layer parameters shown in the Layer Inspector. Simply change and regenerate the layer to which they apply.


  • Understand the relation between attribute values (attr = X) created in CGA rule files and their appearance in the Rule Inspector.
  • Know how to alter attribute values in the Rule inspector and how to return them to their defaults.
  • Create mapping layers using color (r,g,b) values in PNG or other raster files; know how to create or modify these raster files.
  • Know how CGA code can be used in conjunction with a mapping layer to set parameters in the model.
  • Use the Rule Inspector to link an attribute value to a mapping layer.

Leave a Reply

Your email address will not be published. Required fields are marked *