Build cities with Get Map Data

To access the tutorial projects in ArcGIS CityEngine, start 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.

This tutorial was created in collaboration with Devin Lavigne of Houseal Lavigne Associates.

Redevelopment along the river

A common request for urban planners and designers is to show or illustrate recommendations and ideas. For example, a planner working on a plan in downtown Berlin, Germany, may recommend an industrial site and large surface parking lot along the Spree River for redevelopment. The setting along the river and proximity to downtown make the site well suited for mixed-use development.

To help convey the message of the proposal, planners often collaborate with their communities to present visuals to articulate a vision for an area. Once a plan is adopted by a community, the property owner or prospective developer can bring in an architect to create a more detailed plan or proposal and help the community achieve its vision.

In both scenarios, the designer prepares a 3D concept plan, which includes the plan for the site along with the surrounding urban context. In this tutorial, you'll learn workflows that use CityEngine and GIS data available to the public to create these types of visualizations. You'll follow these key steps:


Get the data

Download data for building footprints and the street network from Open Street Map (OSM) data.


Generate and modify buildings

Generate 3D buildings from the OSM data.


Clean up the graph network and streets

Clean up and generate models for streets.


Work with the terrain

Remove a tunnel street and adjust the terrain height.


Create scenarios

Develop two alternative scenarios for a potential redevelopment site.

Get the data

In the first section, you'll open the scene and sign in to download the data from Get Map Data.

Open the scene

Begin by opening the GetMapData.cej scene, which is empty:

Open the GetMapData.cej scene

Sign in to ArcGIS Online

Your first step is to get the map data for the center of Berlin. To use the Get Map Data tool, you must be signed in to ArcGIS Online. Click the Not signed in drop-down menu.

Not signed in drop-down menu

Click Sign In to open the ArcGIS Sign In for CityEngine dialog box:

ArcGIS Sign In for CityEngine dialog box

Enter your ArcGIS Online username and password to sign in:

Signed in

Get Map Data

Next, click File > Get Map Data in the main menu.

Get Map Data in File menu

The Get Map Data dialog box appears; in the search box, type Berlin Cathedral, Berlin, DEU:

Get Map Data dialog box

The map zooms to the location.

Click Set Extent. A rectangular adjustable selection box appears, which determines the download area. Copy and paste the coordinates below for the exact results. This is important, because throughout this defined extent, you will be using bookmarks to move between different areas within Berlin.

  • Width—9177.662
  • Height—5692.849
  • X-Offset—1487196.025
  • Y-Offset—6892058.511

These values match the Web Mercator reference system. The reference system changes to UTM automatically after opening the scene. Disable the Fixed ratio button Fixed and under the Reference Point option Vertex location, ensure that the reference point of the rectangle is set to the lower left.

Under Esri World Elevation, change the Resolution setting from Medium (2k) to High (4K). Leave the other settings as they are. Click OK to start the download.

Get Map Data settings

  • To get elevation data with the map, you need an ArcGIS ArcGIS Online organizational account.
  • If you have issues with the download, you can find all the necessary data in the /maps/Terrain_Imagery_Final/ tutorial project folder. From there, drag the elevation.tif and map.osm files into the scene.

Import settings

Different settings result in different imports and different postprocessing routines, and as you get more familiar withCityEngine, you will gain a deeper understanding of what each of the settings do. For example, if you expand the highway category, you control the subset of street types that are imported. For this tutorial, you can leave the defaults as they are and click Finish.

Import settings

Generate and modify buildings

In this next section, you will generate the buildings and learn how to modify them with different styles.

Generate buildings

Because the Generate models for downloaded shapes check box was checked on the Get Map Data dialog box, the Building_From_OpenStreetMap.cga rule file is applied to the building footprints.

Scene created with Get Map Data

The rule file is included in CityEngine and is located in the ESRI.lib folder.

There is a similar rule in the ESRI.lib folder named Building_From_Footprint.cga that works well with footprint shapes from other sources, including GIS data.

Schematic facades

Zoom in to the center of the scene. See 3D navigation essentials for an overview of navigation options.

When the Building_From_OpenStreetMap.cga rule is applied to buildings, by default, the buildings are white. Next, you will change the style of the buildings. In the Scene Editor window, right-click the Footprints layer and click Select Objects to select all the footprints.

Select building footprints

With building footprints selected, click the Representation drop-down arrow in the Inspector window to change the value to schematic facades. This instructs the CGA rule to create exterior windows onto the walls, and assigns different patterns and colors to each footprint.

Change buildings to schematic facades

Zoom in, and you can see the difference with the buildings that now have the schematic facades value applied.

Building with schematic facades

Realistic facades

Select the footprints again, and this time, change the Representation value to realistic with facade textures. With this value, the CGA randomly maps different images or textures of the facades to different buildings, giving the city a more realistic appearance.

Buildings with realistic facades

Because of this random texture assignment, the building typology doesn't always match. But when you zoom out, you get a nice realistic overview of the city.

Realistic overview of city

Make the buildings white

Finally, before moving to the next steps, return all the Representation values for the buildings back to the default white value. This is a common technique used for development visualization. You show a plan recommendation or development proposal in a full-color model as the main focus of the scene, and the existing buildings are displayed in white or subdued color to give context to the proposal, but not take away from the focus. The previous steps were intended to show you the options in the rule file that are available in the CityEngine default library (ESRI.lib).

Solid colors for key buildings

Under Bookmarks Bookmarks, click Bookmark 1 - Fernsehturm Berlin or press 0 to navigate to the Fernsehturm Berlin, a television tower in downtown Berlin. View some of the details in the surrounding buildings.

Bookmark 1 - Fernsehturm Berlin

The data in the shape’s Object Attributes are being read by the Building_From_OpenStreetMap.cga rule. And when there is detailed geometry information available, the rule can generate a more complex model (LOD2) for that shape instead of a simple extrusion (LOD1).

Select the television tower model and change its Representation attribute value to solid color. The top of the antenna becomes bright red.

Solid color for key building

Keep in mind that OSM data is a community effort and the quality of the data and amount of information can vary significantly. This means that sometimes there is color information present and other times the buildings are white, even with the representation attribute set to solid color.

Continue to Bookmark 2 – Berlin Cathedral (1). Here, is another example of how CityEngine can leverage LOD2 data stored within the OSM building footprints and automatically create architecturally rich 3D buildings.

As you did with the tower, select the cathedral and change the Representation value to solid color.

Cathedral with solid color

At this point, you can continue to change the colors of other key buildings in the scene like the Brandenburger Gate or the main train station. When finished, you should have a scene in which the majority of buildings are white, with some colored landmarks.

Next, you'll learn various street cleanup methods.

Clean up the graph network and streets

Often, after importing OSM data, you need to clean up the street networks. On import, CityEngine converts the OSM data into its own representation model, called a graph network, which consists of nodes and segments for which shapes are dynamically created. The most common errors exist at intersections, where nodes are placed too close together, or the centerline or street information is missing.


There are a few tools you can run to fix issues with the graph network and street shapes—the Cleanup Graph Cleanup Graph tool and the Simplify Graph tools are the most common tools to use for this workflow. These tools give you an automated way to repair most street issues. You can enable one of these tools upon import, but you can also trigger this process through the menus if you want to selectively apply it to some segments.

There is not a clear answer on which workflow works best because the outcome depends on the quality of the imported data. The automated cleanup may do a very good job in some cases, but in others it can make the situation worse. Usually, you end up applying a combination of different strategies, and in this tutorial, you will go through some of them.

Change the width of the streets and sidewalks

The width of the streets and the sidewalks are configured automatically on import of OSM data. For this tutorial, you will remove the sidewalks and narrow the streets to help minimize the amount of cleanup. To change the width of the streets, right-click the Street Network layer and click Select Objects to select the whole street network.

Select the street network

Make sure that the Segments tab is active in the Inspector window and change the Segment Parameters to the following:

  • Segment Width9
  • Lane Width4
  • Left Sidewalk Width0
  • Right Sidewalk Width0
Adjust street width

The dynamic shapes adjust accordingly to the new parameters. As you can see, when you compare the images above and below, you end up with much simpler streets.

Streets adjusted with new width

Change the rule file

Similarly to building footprints, streets are also assigned a rule on import. In this case, change the default Street_Modern_Standard.cga rule to the Street_Modern_Simple.cga rule, which is also part of ESRI.lib.

Select all the streets again if they are not selected and click Shapes > Assign Rule File in the main menu to open the Assign Rule File dialog box.

Assign Rule File in main menu

Now go two levels up so you see your full CityEngine workspace and browse to the /ESRI.lib/rules/Streets/ folder. Choose the Street_Modern_Simple.cga rule.

Choose the Street_Modern_Simple.cga rule file

Click Open to regenerate the street network with the new rule. One of the main differences you can immediately spot is that the street crossings are gone.

With all the street shapes still selected, change the following attributes for both Segments and Nodes in the Inspector window:

  • NbrOfRightLanes0
  • Centerlinewhite

Centerline parameter set to white

This change sets the centerline from a continuous yellow to a dashed white line and ensures that the streets have two lanes only.

Simple streets with dashed centerlines and two lanes

Prepare your scene for graph editing

To begin, ensure that only Graph Networks and Shapes are visible under Visibility settings Visibility settings. Click Map Layers (the basemap imagery) or press F9, and click Models (F12) to turn off their visibility. Also hide the Footprints layer in the Scene Editor window.

Turn off Models visibility

This isolates the graph network to better see any errors.

Street cleanup

Go to Bookmark 3 – Street Cleanup (2). You should see an image similar to the following, with red lines indicating the conflicting shapes and the visible gaps in the streets:

Scene with only shapes and street networks visible

To use the Cleanup Graph tool Cleanup Graph tool, click the Select button Select tool (Q), and click the Lasso Selection tool Lasso Selection in the Tool Options window Tool Options to select street segments in the center area.

Select streets with Lasso Selection tool

Click the Cleanup Graph tool Cleanup Graph tool on the toolbar, or click Graph > Cleanup Graph from the main menu to open the Cleanup Graph dialog box. You can specify a vertical and horizontal merge distance for the points (when points close together will merge) and check the Resolve Conflicting Shapes check box to resolve conflicting shapes indicated by the dashed red lines. Click Finish.

Cleanup Graph dialog box

The result should look like the following image:

Streets after using Cleanup Graph tool

The selected streets have the number of nodes reduced, and the red error markers are removed at the intersections. This means CityEngine created all the dynamic shapes. You can continue to clean up other parts of the scene before moving on to the next section.

Next, you will work with the terrain to create a more realistic scene.

Work with the terrain

Turn on the visibility of Map Layers and Models again by pressing F9 and F12, respectively. Then browse to Bookmark 4 – Terrain Editing.

Scene of terrain for editing

You may have noticed that there are a few locations where the terrain rises above the road and where one of the roads is actually a tunnel below the park.

Highlighted areas for tunnel

Remove the tunnel road

Terrains in CityEngine are based on heightmaps. And while this approach has its advantages, especially for performance for large areas, one of the disadvantages is that you can’t represent holes. This means there is no way to properly model the tunnel. Instead, you will remove the segments of the streets that are underground.

The tunnel starts after the intersection in the southern part of the park area and goes all the way to the main train station.

Use the Selection tool Rectangle selection to create a rectangular selection of a large area between the two intersections and press the Delete key to delete the selected segments.

Sequence of selecting areas, deleting segments, and resulting image

Continue along the tunnel, deleting parts of the streets. At intersections, carefully select the tunnel segments only. This works best using single clicks in combination with the Shift key or by changing the selection mode to Add Add to selection in the Selection Tool options window Tool options.

Delete additional segments

When you finish, it should look like the following image:

Final image with tunnels

Adjust the height of the terrain

Next, you'll adjust the terrain to the height of the street shapes so they don't overlap. Zoom in to the long street crossing the park and select some of the streets where the terrain overlaps.

Adjust terrain height

Click the Align Terrain to Shapes tool Align terrain to shapes tool on the toolbar. This opens a dialog box that works on the current selection, similar to the Cleanup Graph dialog box.

Align Terrain to Shapes dialog box

Leave the default values and click Apply. After closing the dialog box, the terrain is properly adjusted.

Terrain after aligning terrain to shapes

You can also use this tool to select all shapes in the scene and align the terrain to them, but this may lead to alignments in some areas where you may not be happy with the result. With the sequential approach in this tutorial, you have more control over the results.

Refine the terrain adjustments using the Terrain Edit brush

When you zoom in, you can still spot some minimal overlaps.

Terrain with some shapes overlaps

In CityEngine, you can modify the terrain using brushes, sculpting it to the height you need. Click the Terrain Edit Brush tool Terrain Edit Brush to change the Terrain Edit Brush tool options Tool options.

Turn on the Elevation Picker toggle button to get the precise elevation of the terrain. Move the pointer over the map and click to select the desired elevation. Since you want to lower the terrain beneath the road, select a lower point on the map; a height of 38 meters is appropriate for this part of the map.

Elevation Picker toggle button

Once you select the elevation, the Terrain Edit Brush tool Terrain Edit Brush becomes active. Click and drag for a paint effect on the terrain and to edit the elevation to the Height value. Do this over the top of the street until no parts of the street are below the ground.

Terrain Edit Brush activated

Continue editing the terrain for other places that overlap in the park area. When you finish, browse to Bookmark 4 – Terrain Editing again. It should look similar to the following image:

Final adjusted terrain with tunnel

Create scenarios

In this section, you'll create two scenarios for a potential redevelopment.

Scenarios allow you to create multiple designs in a scene and compare them. You can display scenarios side by side in different views for visual comparison. Scenarios can consist of layers, containing objects such as buildings, streets, or terrain, which only display when the scenario is active. You can make custom changes that affect only a specific scenario, or you can make global changes that can be applied across all scenarios. They provide a way to store multiple design alternatives in a single scene. Furthermore, having multiple scenarios is supported by Unreal Engine and 360 VR Experience.

Create an existing conditions scenario

Browse to Bookmark 5 – Spree River Redevelopment Site and turn back on the visibility of the Footprints layer in the Scene Editor window.

Spree River Redevelopment Site

To create an initial scenario, click the Add new scenario button Add new scenario in the Scene Editor window.

Add new scenario in Scene Editor

The New scenario dialog box appears. Name the scenario Existing Conditions. change ID to EC, and click OK. The new scenario automatically becomes the active scenario in the scene.

New scenario dialog box

Move existing buildings to existing conditions scenario

The scenario you are preparing explores a potential redevelopment of an underutilized riverfront site. Select the six footprints on the triangular site and press Ctrl+X or right-click and choose Cut to cut the footprints.

Selected footprints on triangular site

Now, press Ctrl+V or right-click and choose Paste in the Scene Editor window to paste the footprints. A new Footprints Paste layer is created. Rename it Redevelopment Footprints in the Inspector window. You can tell which scenario a layer belongs to by the color of the scenario next to Scenario.

To manage the layer type and scenario membership, click Edit to open the Edit Scenarios Membership dialog box, and check the Existing Conditions check box.


Move existing building to Existing Conditions Scenario

Create redevelopment Scenario A

Create another scenario, name it Scenario A, and change ID to A.

Add Scenario A

Because the new Scenario A is set as the active scenario, the buildings that you moved to the Existing Conditions scenario are now hidden, leaving an open empty area.

To fill this empty space, switch to the Polygonal Shape Creation tool Polygonal shape creation tool (S) and create a new parcel shape. Start next to the existing building on the left, and continue to work around it, follow the tracks of the elevated railway and go back to the street before the existing building on the right. Then follow the street and click the initial point to complete the shape.

Create a building footprint with the Polygonal Shape Creation tool

Because the terrain in the development area is not completely flat, the newly created parcel overlaps the terrain in some locations. Use the Align terrain to shapes tool Align terrain to shapes tool to adjust the terrain below the parcel.

Align the terrain to shapes

Rename the new layer Parcel in the Scene Editor window to keep things organized.

Next, expand the rules folder in the Navigator window and drag the UrbanBlocks.cga rule file onto the parcel.

Drag UrbanBlocks.cga rule file onto footprint

By default, two building blocks are created on the parcel.

Two building blocks created on the parcel

Adjust the various attributes in the Inspector window to create the design proposal. You can select up to six building blocks, and you can individually set the width, height, length, and gap between blocks. Under general, you can define additional settings, including the location where the first block should start (patternOffset), parcel setback (SetbackDepth), and color values (BlockColor).

Adjust the attributes in the Inspector window

After adjusting the attributes, your scene should look similar to the following image:

Once you’re happy with the results, continue by adding trees to the site. Luckily, there are many tree types available in ESRI.lib. In the Navigator window, browse to the /ESRI.lib/assets/Webstyles/Vegetation/Realistic/ folder, choose one of the trees, and drag it onto the scene.

A tree from ESRI.lib added to the scene

The tree is generated at the pointer location. To preview a tree, right-click the file name and choose File Preview to open a preview window.

Continue adding trees either by dragging new trees or copying existing trees. You can use the transform tools to create variation in size and orientation.

Transform the size or orientation of the trees

Create redevelopment Scenario B

To create the alternative proposal, you'll simply duplicate Scenario A. Right-click Scenario A in the Scene Editor window and choose Duplicate. On the Duplicate scenario dialog box, name it Scenario B and change its ID to B.

Scenario B

Same as when creating a new scenario, the duplicated scenario is automatically set as the active scenario. Select the parcel again and adjust the attributes in the Inspector window for this variant.

Scenario B attributes adjusted in Inspector window

Use the transform tools to rearrange the trees copied from Scenario A to fit your alternate proposal. You can also change the number of trees by deleting trees using the Delete key or by adding trees as described previously.

Trees arranged and scaled for Scenario B

And with that, you have created three different scenarios: Existing Conditions and two proposals, Scenario A and Scenario B. Well done!

Prepare the scene for visualization

Before you take a final look at the scene, ensure that the scenarios are highlighted properly. You may have noticed that, by default, CityEngine has a rather bright scene light set. This is great for editing, but for visualization purposes, a smoother lighting is preferred.

Click the Scene Light and Panorama tool Scene Light and Panorama tool on the toolbar to open the Scene Light and Panorama dialog box. You can either position the sun manually or choose a time and month together with a time zone. For this tutorial, leave Sun position source set to Direct Solar Angle Entry. Now, change the sun position to the following settings:

  • Solar elevation angle 35.0
  • Solar azimuth angle325.0

To make the light even smoother, you can also fine tune the Luminance level settings:

  • Solar intensity0.7
  • Ambient intensity0.25
  • Shadow attenuation0.3

Scene and panorama settings

Finally, turn off the visibility of the shapes by pressing F10. This hides not only all shapes under the generated models but also error markers on unfixed street crossings that may remain.

Switch between the scenarios

Now you are ready for exploration. You can switch between the three scenarios in the Scene Editor window by clicking the respective scenario or choose a scenario directly in the Viewport window under Scenarios Scenarios tool.

Switch to Scenario A in the Scene Editor and Viewport

Look at the site from different angles and zoom levels while switching between the scenarios.

Redevelopment River View 1

Redevelopment River View 2

Redevelopment River View 3

Redevelopment River View 4

Scenarios can also be exported to Unreal Engine for future visualization, as well as the 360 VR Experience for immersive viewing.

In this tutorial, you learned how to do the following:

  • Import data from a region using the Get Map Data tool.
  • Clean up the data and use it to create and visualize potential redevelopment scenarios.

Be sure to check out the other Essentials tutorials: CityEngine tour, Work with GIS data, and Rule-based modeling.

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