Tutorial 2: Terrain and dynamic city layouts

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.

Streets with models generated

Usually, you create the terrain first when you start a CityEngine scene. Terrains can be created from simple image files or from digital elevation models (DEMs), such as a GeoTIFF file in which the georeferencing information is supported.

In this tutorial, you'll learn about creating and aligning terrains; growing streets and cleaning up streets, and the fundamentals of dynamic city layouts.

Create a terrain

To create a terrain, do the following:

  1. Expand the Tutorial_02_Terrain_and_Dynamic_City_Layouts tutorial folder in the Navigator window.
  2. Open the Part_1_Start.cej scene in the scenes folder.
  3. Open the maps folder, and drag the elevation.jpg image into the Viewport window to open the Import dialog box.

    Terrain import dialog box

  4. Select Terrain Import and click Next.
  5. Under Texture File, click Browse to select the topo.png texture file in the maps folder.
  6. Click Open.
  7. Leave the Channel property set to brightness..
  8. Set the Maximum Height value to 150.
  9. Under Bounds, edit the Dimensions and Location values to look like the following image:

    Terrain dialog box


    If you load an image without georeference information, its pixel resolution is set as the terrain dimensions.

  10. Select the Keep ratio button Keep ratio toggle and ensure the alignment button alignment location is set to the center.
  11. Click Finish.

    Terrain elevation in Viewport

    The Terrain elevation layer is created and added to the Scene Editor window.

    Terrain elevation in Scene Editor

  12. Click the layer in the Scene Editor window to explore the attributes in the Inspector window.

    Inspector of terrain attributes

    For more information on terrain layer attributes, see Terrain layer.

    Open the Part_1_End.cej scene to see the finished example located in the scenes folder.


Currently, CityEngine only supports image-based terrains (gray scale height maps); it does not support 3D meshes. If you only have a 3D mesh, or any other data type, you need to convert it to a heightmap.

Grow streets

In Tutorial 1: Essential skills, you learned how to grow streets on a flat grid without elevation present. Now, you'll use the Grow Streets tool and algorithm to directly adapt the streets to the actual terrain elevation.

Grow streets with a heightmap

To grow streets with a heightmap, do the following

  1. Click the Part_2_Start.cej file to open the scene.
  2. Click Graph > Grow Streets... in the main menu to open the Grow Streets dialog box.

    Grow streets dialog

  3. Expand the Environment Settings section.
  4. Next to Heightmap, click the drop-down menu and select Terrain elevation.

    Grow Streets and Terrain elevation

  5. Click Apply.

    The Streetnetwork layer is added to the Scene Editor window.

    Streetnetwork Scene Editor

    The streets automatically align to the terrain.

  6. Click Close to view the streets in the Viewport window.

    Grow streets with heightmap

Grow streets with obstacle maps

You may have noticed that the Grow Streets tool grows streets randomly. This includes areas in which you may not want streets. You can create an obstacle map to allow you to leave those areas empty and minimize the manual cleanup process. An obstacle map is a black and white image in which the brightness defines the areas that streets can grow.

To add an obstacle map, do the following:

  1. Right-click in the Scene Editor window and select New > New Map Layer  to open the New Map Layer dialog box.
  2. Click Obstacle.

    New Map Layer dialog box

  3. Click Next.
  4. Click Browse and select the obstacles.png file in the maps folder.
  5. Keep the Channel property set to brightness.
  6. Set the Obstacle Threshold value to 0.5.

    The Obstacle Threshold defines the image brightness that distinguishes between obstacles and non-obstacles.

  7. Under Bounds, set the values to your terrain’s extent.

    Obstacle dialog settings

  8. Click Finish.

    The New Obstacle map layer is created in the Scene Editor window.

    New Obstacle layer added to Scene Editor

  9. Expand the Layer Attributes section in the Inspector window:

    attr obstacle = brightness < 0.5

    The code determines the attribute mapping, in this case as a Boolean value (true/false).

  10. To apply the obstacle map when growing streets, first turn off the visibility box of the New Obstacle layer in the Scene Editor window.
  11. Click in the Viewport window to deselect the New Obstacle layer in the Scene Editor window.
  12. Click Graph > Grow Streets... in the main menu again.
  13. Expand the Environment Settings section.
  14. Next to Obstaclemap, click the drop-down menu and select New Obstacle to assign the obstacle map.

    Obstaclemap applied

  15. Click Apply.

    Streets adjusted by obstacle map

    The Grow Streets tool creates streets in the white areas of the obstacle map and doesn't in the black areas.

    Your scene should look something like the Part_2_End.cej scene.


The Grow Streets tool also allows you to automatically create street patterns using the parameters. See Street pattern examples for more information.

Clean up streets

Sometimes the street networks have conflicting graph segments that need to be cleaned up. These errors are highlighted in red when proper shapes can't be created. Use the Cleanup Graph tool Cleanup streets tool to clean up street network issues.

  1. Open the Part_3_Start.cej scene.
  2. Zoom to a conflicting graph segment marked in red.

    Viewport displays conflicting segments

  3. Select the area around the conflicting segment with the Select tool Select tool.
  4. Click the Cleanup Graph tool Cleanup streets tool (C) on the toolbar or select Graph > Cleanup Graph... in the main menu to open the Cleanup Graph dialog box.

    Cleanup Graph dialog box

  5. Keep the default settings.

    See Cleanup streets for more information.

  6. Click Finish.

    Viewport Perspective View of cleaned up network

    Compare your scene to the Part_3_End.cej scene.

Align terrain

Streets that are created usually follow the surface of the terrain or the location of buildings. Often, created objects in a scene aren't aligned properly to the terrain, such as when importing 2D GIS data.

The following table lists the tools that can align streets and shapes with the terrain:

Align Graph to Terrain

Projects street segments onto the terrain.

Align Shapes to Terrain

Projects static shapes onto the terrain*.

Align Terrain to Shapes

Aligns the terrain to static and/or dynamic shapes.


*Shapes that are manually drawn or imported are called static shapes. Regarding alignment, the dynamic city layout tools create dynamic shapes that cannot be aligned with the alignment tools. Since dynamic shapes are created as the children of (dynamic) blocks, (the same is true for streets), the Block Subdivision parameters contain a specific parameter for the alignment. See Block parameters for more information.

Align the graph to the terrain

First, you will align the graphs to the terrain.

  1. Open the Part_4_Start.cej scene.

    Align streets to terrain

  2. Select some shapes in the scene.

    Streets selected to align

  3. Click the Align Graph to Terrain tool Align streets to terrain tool on the toolbar or select Graph > Align Graph to Terrain... in the main menu.
  4. Next to Heightmap, click the drop-down menu and select Terrain elevation.

    Align Graph to Terrain dialog

    See Align streets to terrain for more information.

  5. Set the Offset value to 0.2.
  6. Click Finish.

    Streets after align to terrain


    The change isn't very noticeable. For a stronger effect, change the Maximum Height value.

Align the terrain to shapes

Next, you will align the terrain to the dynamic shapes in your scene.

  1. Select some shapes in the scene again.
  2. Click the Align terrain to shapes tool Align terrain to shapes tool on the toolbar or select Terrains > Align Terrain to Shapes... in the main menu to open the Align Terrain to Shapes dialog box.

    Align Terrain to Shapes dialog

    See Align terrain to shapes for more information.
  3. Keep the default settings and click Apply.

    Streets after terrain aligned to shapes


    There is a very slight change since your streets were aligned to the terrain already.

  4. Click Close.
  5. Click the Terrain elevation layer in the Scene Editor window.
  6. Under the  Elevation section in the Inspector window, alternate disabling and enabling the Apply Alignments setting with the drop-down menu.

    Elevation in Inspector

    The terrain switches back and forth between the unaligned and aligned state. This means that the alignment data, or the elevationDelta property, is stored as a file.

  7. Expand the Layer Attributes section to view how the elevationDelta property helps define the elevation attribute.

    attr elevation = map_01(brightness, minHeight, maxHeight) + elevationDelta + elevationOffset

  8. Save your scene.
  9. Click File > Refresh Workspace to refresh the tutorial project workspace.

    The data folder now contains the elevation delta file in the Part_4_Start.cej folder.

    Data folder where the elevation_delta image is located

    Ensure that you save the scene after aligning the terrain the first time.

  10. To view the elevation file from the top view, create a new viewport by clicking Window > New Viewport > Top View in the main menu.
  11. Drag the elevation_delta file into the Top View viewport.

    Gray scale delta map result

    The 16-bit delta map stores the elevation changes (gray = no change; black = lower; white = higher). See Elevation delta maps for more information.

    Open the Part_4_End.cej scene to see the finished scene.

Dynamic city layouts

Dynamic city layouts is a set of tools and functionalities that allow you to quickly create city layouts. The result is a series of shapes, ready for use with CGA rules to create 3D models. The main elements are streets and blocks. Blocks are created if the street center lines physically enclose an area (and the network is cleanly connected). Blocks are represented with a dashed line, which you can select.

Both street segments and blocks have individual parameters that drive the creation of their children, the dynamic shapes.

Object types

When you explore the streets that you've grown, you'll find that there are three selectable object types whose parameters drive and influence the shape creation: segments, nodes, blocks.

Segment Parameters

Selected street segment
Inspector Segment parameters

Node Parameters

Selected node
Inspector Node parameters

Block Parameters

Selected block
Inspector Block dialog box with parameters

The Create Shape parameter is common to all three object types and enables or disables the shape geometry creation. For example, you may want to create shapes for the street, but not subdivisions in the blocks.

Feel free to play around with the parameters of the different object types, such as adjusting the width of streets and sidewalks; creating some roundabouts and editing their radii; or creating some cul-de-sacs.

Block subdivision types

You'll next work with block subdivisions. Select a block in the scene and change the Subdivision Type parameter. Each subdivision algorithm has its own parameters and creates a specific pattern.

Recursive Subdivision

Recursive subdivision

Skeleton Subdivision

Skeleton subdivision

Offset Subdivision

Offset subdivision

No Subdivision

No subdivision

Now you have a better understanding of the dynamic shape creation process. In the next sections, you'll explore street drawing, editing streets and curves, and generating street models.

Working with streets

In the previous sections, you used the dynamic city layout tools to create a street network, practiced cleaning up streets, and worked with aligning terrain. Now, you'll learn some common workflows working with streets.

Draw streets manually

First, you'll explore drawing streets using both the Polygonal Street Creation Polygonal Street Creation tool and Freehand Street Creation Freehand street creation tool tools.

  1. To add streets to the existing network, click the Polygonal Street Creation tool Polygonal Street Creation tool(G) on the toolbar.
    1. Snap and click to place the first node of the new street.

      Drawing with polygonal street tool

    2. Double-click to finish the street.

      Finished polygonal street

      You can set the segment lengths and other properties in the Polygonal Street Creation tool options window Tool options . See Draw a polygonal street for more information.

  2. To draw streets by freehand, click the Freehand Street Creation tool Freehand street creation tool(Shift+G) on the toolbar.
    1. Snap and click and drag to start drawing a new street.

      Drawing streets with freehand tool

    2. Release the mouse button to finish the street.

      Finished freehand street

      You can set the street widths and other properties in the Freehand Street Creation tool options window Tool options. See Draw a street freehand for more information.

Curved segments

Next, you'll practice changing street segments from straight to curved and vice versa.

  1. Select some streets.
  2. Play around with the Graph > Set Curves Straight and Graph > Set Curves Smooth tools in the main menu.

    The streets can be switched between straight and curved with these tools. The following image, is a good example of the differences between the Set Curves Straight and the Set Curves Smooth tools.

    Set Curve Straight and Set Curve Smooth tools

    You can adjust the curvature of the streets with the handles. See Straight vs smooth for more information.

    Keep in mind that curved streets produce many polygons so it's recommended that you keep them at a minimum.

  3. Edit the precision of the number of segments for the curved street you created.
    1. Select the street and click the Precision parameter in the Inspector window.

      The Precision parameter value is set to .5

      Curved street with .5 precision
      .5 precision parameter

    2. Change the value to .25.

      Curved street with .25 precision
      .25 precision parameter

Edit streets

Continuing, you'll edit streets and curves using the Edit Streets/Curves tool Edit street/curves tool.

  1. Click the Edit Streets/Curves tool Edit street/curves tool (C) on the toolbar.

    See Edit street and curves for more information.

  2. Using the handles, edit the widths of the streets and sidewalks.
  3. Edit the tangent handles.

    Depending on the viewing angle, the horizontal or vertical tangent handles display to be edited.

    Viewport Perspective View of tangent edits

Generate street models

Finally, you'll finish by generating street models with the Street Construction Simple.cga rule.

  1. Expand the Streetnetwork layer and right-click the Network sublayer.
  2. Right-click Select Objects.

    This selects only the streets and not the blocks.

  3. Drag the Street Construction Simple.cga rule onto the selected shapes.

    Street models and 3D objects are generated by the rule.

    Streets with models generated


    You can edit the streets, including the lengths, widths, and curves, and regenerate models on the fly.

  4. Select a street shape and click the Start Rule link in the Inspector window.

    This allows you to explore the rule in the CGA Editor.

    Street segment with start rule in CGA Editor

    The diagrams below demonstrate the StartRules and the corresponding street shapes by color.

    Street shapes 1
    Streets shapes 2


    You can explore the color shapes more by applying the color_streetshapes.cga rule to the streets.

    Open the Part_5_End.cej scene to see the finished scene.

To learn about importing streets, see Tutorial 4: Import streets.

In this tutorial, you've explored creating terrain, growing streets automatically, cleaning up streets, aligning terrain, and creating dynamic city layouts. You then learned about drawing streets, editing them, and generating street models.

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