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.

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.
   
2. Select a shape.

   When you explore the shape in the Inspector, you can see the shape doesn't have rule parameters 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 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.

   

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

   The height attribute is now assigned to the shapes.

   

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 (Ctrl+G) to generate the selected shape.
10. Change the height value from 80 to 150.

    

    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 (Ctrl+G).

   

   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 channel map for height

   

   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 and ensure that the alignment button is set to the center.

   

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

   

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.

    

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.

   

   The Attribute Connection Editor dialog box appears.

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

   

   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.

   

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

   

   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.

   Note:

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

   

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

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 and ensure the alignment button 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.

   

   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.

    

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

    The rule automatically connects the layer attributes to LandUse Map:

    

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.

    

    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.