Build cities with Get Map Data

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.

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 perspective developer can bring in an architect to create a more detailed plan or proposal for the site 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 learn workflows that leverage CityEngine and GIS data available to the public, to create these types of visualizations. You'll follow these key steps:


Getting the data

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


Generating buildings

Generate 3D buildings from downloaded OSM data.


Clean up the graph network/streets

Clean up and generate models for streets.


Work with the terrain

Remove a tunnel street and adjust the terrain height.


Creating scenarios

Develop two alternative scenarios for an opportunity redevelopment site.

Getting the data

Open the scene

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

Open the GetMapData.cej scene

Sign into 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 into ArcGIS Online. Click the Not signed in drop-down menu.

Not signed in menu

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

sign in

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 which you can search for Berlin Cathedral, Berlin, DEU:

Get Map Data dialog box

The map zooms to the location.

Next, 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 Web Mercator reference system. The reference system changes after opening the scene to UTM automatically. Disable the Fixed ratio Fixed button and under the Reference Point Vertex location option, ensure the reference point of the rectangle is set to the bottom left.

Under Esri World Elevation change the terrain 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 your map you need to have 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, just drag and drop the eleavation.tif and the map.osm file into the scene.

Import settings

Different settings result in different imports and different post-processing routines, and as you get to know CityEngine, you will gain a deeper understanding of what each of the settings do. For this part, use primarily the default settings, with one exception – expand the highway category and ensure the tertiary highways are checked before clicking Finish.

Import settings

Generating and modifying buildings

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

Generating buildings

Because you checked the Generate models for downloaded shapes check box in 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 ESRI.lib.

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

Schematic facades

Zoom a bit closer to the center of the scene. Refer to 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 box 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.

Changing 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 are zoomed 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 only intended to show you the options within the rule file that are available to you 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 within 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 therefore the quality of the data and amount of information can vary quite a lot. This means, that sometimes there is color information present and other times the buildings are just 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 special colored landmarks.

Next, you'll learn various street cleanup methods.

Clean up the graph network/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 streets 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 it upon import, but you can also trigger this process through the menus in case 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 make the streets more narrow 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 Width: 9
  • Lane Width: 4
  • Left Sidewalk: 0
  • Right Sidewalk: 0
Adjusting street width

The dynamic shapes adjust accordingly to the new parameters. As you can see, when you compare the screenshots above and below, you already 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 the ESRI.lib.

Select all the streets again if they are unselected 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 that you see your full CityEngine workspace and browse to the /ESRI.lib/rules/Streets/ folder. Select the Street_Modern_Simple.cga rule.

Select Street_Modern_Simple.cga rule file

Click Open to regenerate the street network with the new rule. One of the main differences which 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:

  • NbrOfRightLanes: 0
  • Centerline: white

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, make sure only Graph Networks and Shapes are visible under the 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 possible errors.

Street cleanup

Using Bookmarks Bookmarks , go to Bookmark 3 – Street Cleanup (2). You should see something like the image below, 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 streets 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.

Selecting streets with Lasso Select tool

Then click the Cleanup Graph tool Cleanup streets 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 your points (when points close together will merge) and click 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 image below:

Streets after 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 was able to create all the dynamic shapes. You can continue to cleanup other parts of the scene before moving on to the next part.

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

Work with the terrain

In this part of the tutorial, turn on the visibility of the Map Layers and Models again by pressing F9 and F12. Then navigate 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 downsides is that you can’t represent holes. This means there is not a way to properly model the tunnel. Instead, you will remove the segments of the streets which are underground.

The tunnel starts a bit 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 big part between the two intersections and press the Delete key to delete the selected segments.

Sequence of selecting areas, deleting segments, and resulting image

Continue to work your way 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 Tool options window.

Deleting additional segments

After you are done, it should look like the image below:

Final image with tunnels

Adjust the height of the terrain

Next, you want to adjust the terrain to the height of the street shapes so they don't overlap anymore. Zoom in closer 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 up a dialog box which works on the current selection similar to the Cleanup Graph dialog box above.

Align Terrain to Shapes dialog box

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

Terrain after aligning terrain to shapes

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

Refine the terrain adjustments using the Terrain Edit brush

Zoom in and at close distance you can still spot some minimal overlaps.

Terrain with some shapes overlaps

CityEngine also gives you the ability to modify the terrain using brushes, sculpting it to the exact height you need. Click the the Terrain Edit Brush tool Terrain Edit Brush to change options in Terrain Edit Brush Tool options tool options.

Turn on the Elevation Picker toggle button to get the precise elevation of the terrain. Move the cursor over the map and click to select the elevation you would like. Since you want to lower the terrain beneath the road, select a lower point on the map; something around a height of 38 m should do the job for this part of the map.

Using Elevation Picker option

Once you select the elevation, the Terrain Edit Brush tool becomes active. Click and drag to "paint” on the terrain and edit the elevation to the height selected from the picker and displayed in Height. Do this over top of the street until no parts of the street are below the ground.

Terrain Edit Brush activated

Repeat editing the terrain for other places that overlap in the park area. When you’re done, navigate to Bookmark 4 – Terrain Editing again. It should look similar to the image below:

Final adjusted terrain with tunnel

Create an scenario

In the next part, you will create two scenarios for a potential redevelopment.

Scenarios allow you to create multiple designs within a single scene and then 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, and 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 Scene Editor window.

Add new scenario in Scene Editor

The New scenario dialog box appears. Name the scenario Existing Conditions and change its ID tag to EC. Click OK and 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 river front site. Select the six footprints on the triangular site and press Ctrl+X or right-click and select Cut to cut the footprints.

Selected footprints on triangular site

Now, press Ctrl+V or right-click and select Paste in the Scene Editor window to paste the footprints. A new Footprints Paste layer is created. Rename it to Redevelopment Footprints in the Inspector window. You can see 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 up the Edit Scenarios Membership dialog box.. Ensure to check the Existing Conditions check box.

scMove existing building to Existing Conditions Scenario

Create redevelopment Scenario A

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

Add Scenario A

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

Fill this empty space again. Switch to the Polygonal Shape Creation tool Polygonal shape creation tool (S) and create a new parcel shape. Start right 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.

Creating a building footprint with the Polygonal Shape Creation tool

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

Aligning the terrain to shapes

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

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

Drag UrbanBlocks.cga rule 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 your design proposal. You can choose 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, most notably the location of where the first block should start (patternOffset), parcel setback (SetbackDepth) and color values (BlockColor).

Adjust the attributes in the Inspector window

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

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

A tree from ESRI.lib added to the scene

The tree is generated at the pointer location. If you want to preview a tree beforehand, right-click the filename and select File Preview to open up a small preview window.

Keep on adding more trees either by the drag and drop method or copy and paste existing ones. You can use the transform tools to create some variation in size and orientation.

Transform the size and/or orientation of the trees

Create redevelopment Scenario B

To create the alternative proposal, you simply duplicate Scenario A by right clicking the scenario in the Scene Editor window and choose Duplicate. In 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 to the active scenario. Select the parcel again and adjust the attributes in the Inspector window as you like 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 new ones 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!

Make the scene ready for visualization

Before we take a final look at the scene, we want to make sure that the scenarios are highlighted properly. You may have noticed that, by default, CityEngine has 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 Scene Light and Panorama tool tool on the toolbar to open up the Scene Light and Panorama dialog box. You can either position the sun manually or choose a time/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 angle: 325.0

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

  • Solar intensity: 0.7
  • Ambient intensity: 0.25
  • Shadow attenuation: 0.3

Scene and panorama settings

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

Toggle through the scenarios

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

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

Scenario A Redeveleopment River View 1

Scenario A Redevelopment River View 2

Scenarios can also be exported into Unreal Engine for future visualization, as well as the 360 VR Experience for immersive viewing. For more information on that check out the help and our other essential tutorials such as the CityEngine Tour or the Work with GIS data.

In this tutorial, you learned how do the following:

  • Import data from a certain region by using the Get Map Data dialog.
  • 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 wtih GIS data and Rule-based modeling.

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