Tutorial 3: Map control

To access the tutorial projects in ArcGIS CityEngine, open CityEngine and click Help > Download Tutorials and Examples in the main menu. After choosing a tutorial or example, the project is automatically downloaded and added to your CityEngine workspace.

Final generated building scene

Cities are vast and complex and contain a large number of shapes and objects, so it can be difficult controlling the attributes one building at a time. In this tutorial, you'll learn how to use maps to control how your city looks.

Explore CGA parameters in Inspector

First, you'll look at CGA rule parameters in the Inspector.

  1. Open the mapcontrolTutorial_01.cej scene in the /scenes/ folder in the Navigator.
    Scene with map and shapes
  2. Select a shape.

    When you explore the shape in the Inspector, you can see the shape doesn't have rule parameters assigned.

    Shape without rules assigned

  3. Right-click the Streetnetwork layer in the Scene Editor and click Select Objects.
  4. Next, you'll assign a building rule to the selected shapes.

     There several ways to assign a rule file to shapes. Do one of the following:

    • Click the Assign rule file tool Assign rule on the toolbar.
    • Click the Assign button in the Inspector.
    • Click Shapes > Assign Rule File in the main menu.

    The Assign Rule File dialog box appears.

  5. Click the  simpleBuildingShells_01.cga rule and click Open.

    Assign Rule File dialog box

  6. Select a shape again.
  7. Expand the Rules section to view the rule attributes.

    The height attribute is now assigned to the shapes.

    Inspector window showing attributes

  8. Click the Rule File link to open the simpleBuildingShells_01.cga rule file in the CGA Editor.

    // height value
    attr height = 80

    The height attribute defines the height of the buildings.

  9. Click the Generate button Generate (Ctrl+G) to generate the selected shape.
  10. Change the height value from 80 to 150.

    Model with 150 height

    The height value you set for the building now overrides the rule parameter. All other shapes still use the height value defined in the rule.

    Open the  mapcontrolTutorial_02.cej scene to see an example of your scene.

Add a map to control the height

In this section, you'll add a color map to control the height parameter of the buildings.

  1. Open the mapcontrolTutorial_02.cej scene if it's not already open.
  2. Select some shapes around the building and click the Generate button Generate (Ctrl+G).

    Buildings generated

    All the buildings have a height of 80 meters. You can improve the appearance of the buildings by adding a skyline. However, rather than setting the CGA shape attributes manually as you did in the first section, you'll use the red skyline map below to control the height of the buildings.

    Red height map
    Red channel map for height
    Topo map
    Topography map

    The red channel of the skyline map represents the height of the buildings in this area. When you compare the skyline map to the topography map, you'll see that a skyline forms around the corner of the lake. There is also a second center in the city at the upper left.

  3. Create a map layer by clicking Layer > New Map Layer in the main menu.

    You can also right-click the Scene Editor and click New > New Map Layer.

  4. Select Mapping and click Next.
  5. Click Browse and select the skylineMap.png file in the /maps/ folder.
  6. Change the Dimensions boxes to 3000 X 3000 and ensure the Location boxes are set to 0.
  7. Deselect the Keep ratio button Keep ratio and ensure that the alignment button Alignment location is set to the center.

    Mapping settings

  8. Right-click the Mappings section and click Add Row.

    Mapping dialog box

  9. Click the Attribute box and name the attribute skylineValue.
  10. Set Channel to the red channel from the drop-down list.
  11. Set Minimum to 20 and Maximum to 200.

    This means building heights should vary between 20 (0 percent red) and 200 (100 percent red) meters.

    Mapping dialog box

  12. Click Finish to create the map layer.
  13. Name the new map layer Skyline Map in the Inspector.

    You can now control the rule height parameter with your skyline map.

Connect the skyline height to the map

Next, you'll connect the skylineValue attribute to the buildings.

  1. Select all shapes in the Streetnetwork layer.
  2. Next to the height attribute in the Inspector, click the drop-down menu and select Connect Attribute.

    Connect Attribute

    The Attribute Connection Editor dialog box appears.

  3. Click Layer attribute, and choose the new Skyline Map layer and the skylineValue(Layer attribute) attribute.

    Attribute Connection Editor dialog box

    See Map attributes with Connection Editor for more information.

  4. Click OK.
  5. Select a single lot and review its attributes.

    The  height attribute value is now connected to Skyline Map.

    Height value connected

  6. Select some shapes around the bay and generate the buildings.

    Buildings surrounding the bay

    The skyline is looking better, but you can improve it by modifying the CGA rule.

  7. Open the simpleBuildingShells_02.cga rule file and locate the following function:

    // calc height with variation
    getHeight(area) = 
    	case area > 600 : rand(0,40)+height
    	case area > 200 : rand(0,40)+height/2
    	else: rand(15,30)

    Rather than mapping the height value from the skyline map directly to the building height, this function creates tall buildings only on large area lots and adds randomness to the buildings. See the Basic shape grammar tutorial for more information on CGA.

  8. Select the Streetnetwork layer in the Scene Editor.
  9. Drag the simpleBuildingShells_02.cga rule onto the selected shapes.


    When you drag rule files onto the shapes, the models are automatically generated.

    Resulting scene

Control the map with land-use types

You'll now learn how to use a color map to control the land-use type of each building. The map you'll use classifies the land-use type by color: red is industrial, blue is commercial, and green is residential.

Land-use map
Land-use map
Topo map
Topography map of lake

  1. Open the mapcontrolTutorial_03.cej scene.
  2. Turn off the Skyline Map layer in the Scene Editor.
  3. Open the  simpleBuildingShells_03.cga rule file.

    Before creating the next map layer, locate the attributes listed in the rule. You'll use the same names when creating layer attributes in the map layer.

    // land use types
    attr t_industrial = 0
    attr t_commercial = 0
    attr t_residential = 0

  4. Create a map layer by clicking Layer > New Map Layer.
  5. Select Mapping and click Next.
  6. Click Browse and select areatypes.png.
  7. Change the Dimensions boxes to 3000 x 3000 and ensure the Location boxes are set to 0.
  8. Deselect the Keep ratio button Keep ratio and ensure the alignment button Alignment location is set to the center.
  9. Under Attributes, add the mapping attributes with the same naming as in the rule, with the Channel boxes set to red, blue, and green.

    Mapping attributes

    Keep the default minimum and maximum values of 0 and 1.

  10. Click Finish to create the map layer.
  11. Name the layer LandUse Map in the Inspector.
  12. Select the new map layer, and click Layer Attributes in the Inspector.

    Inspector window showing layer attributes

  13. Select the Streetnetwork layer.
  14. Assign the simpleBuildingShells_03.cga rule file.

    The rule automatically connects the layer attributes to LandUse Map:

    Inspector window showing land-use parameters

  15. Before you generate the buildings, review the simpleBuildingShells_03.cga rule file. Locate the color declarations and landuseTypeColor function:

    Color type for land use:

    // color declarations
    red = "#ffaaaa"
    green = "#aaffaa"
    blue = "#aaaaff"
    white = "#ffffff"

    Land-use function:

    // Functions
    landuseTypeColor = 
    	case t_industrial > t_commercial && t_industrial > t_residential : red
    	case t_commercial > t_industrial && t_commercial > t_residential : blue
    	case t_residential > t_industrial && t_residential > t_commercial : green
    	else : white

    The function analyzes the values coming from the land-use map and returns a color accordingly. If the color channel value coming from the map is greater than the value of the other channels, the corresponding land-use color is returned. The Lot rule uses the color(landuseTypeColor) operation:

    Lot -->
    	// prepare building ground size and pivot orientation
    	case geometry.isConcave : color(landuseTypeColor)LotSub(getHeight(geometry.area))	
    	else : color(landuseTypeColor) s('.8,'1,'.8) center(xz) LotSub(getHeight(geometry.area))

    The color(landuseTypeColor) operation calls the land-use color function and the color is applied to the generated buildings.

  16. Generate all buildings in the scene.

    Final generated building scene

    The mapcontrolTutorial_04.cej scene shows the final scene.

In this tutorial, you've explored applying CGA rules to shapes, using a map to control height, and controlling coloring buildings by land-use type with a three-color map.

To continue your learning with CityEngine, see the complete CityEngine tutorial catalog.