Skip to content

ArcGIS__CityEngine__Unity: Workflow Tutorial

Marie Saldaña edited this page May 30, 2017 · 7 revisions

In this tutorial you will learn how to create a data in ArcGIS, import GIS data and build a scene in CityEngine, export a CityEngine Webscene, and bring a CityEngine scene into Unity.

This tutorial was written based on software versions as of May 2016.

Setup File Structure

Create a file structure for your project that follows this outline:

  • Main Project Folder
    • ArcGIS
    • CityEngine
      • Workspaces (if you switch between workstations that use a CityEngine license server)
      • CityEngine Project
    • Unity

Create Data in ArcGIS

File Setup

  • Open ArcGIS
  • Go to File > Map Document Properties > Default Geodatabase
    • If the project folder is not visible, click on the ‘Connect to Folder’ icon
    • Create a new geodatabase in Main Project Folder/ArcGIS
    • Check box next to “Store relative pathnames to data sources”
  • Go to View > Data Frame Properties > Coordinate System
    • Projected Coordinate Systems > UTM > WGS 1984 > Northern Hemisphere > Choose Zone
    • Click the star icon to “add to favorites”
  • Click on ‘Add Data’ icon (icon that looks like a yellow diamond with plus sign) > Add Basemap > Imagery With Labels
    • Navigate to the site, frame the general extent of the area in Viewport
  • Save the file as an ArcMap file (.mxd)

Georeferencing Basemaps

  • Copy the basemap file into your project folder
  • Go to ‘Add Data’ > browse to the map file
  • Find the Georeferencing toolbar. If not visible, right-click on the toolbar and select it from the menu.
  • Expand the ‘Georeferencing’ menu, select ‘Fit to Display’
  • In the Table of Contents panel at left, right-click the map layer, go to ‘Properties’ > Display > Transparency. Change to around 50%.
  • First, use the ‘Scale’, ‘Rotate, and ‘Pan’ tools to position the map as best as you can.
  • Next, add control points. Distribute these evenly over the map and only use 4-5 max.
    • Don’t control-z to undo during this process. If you need to delete a point, select it and delete it.
  • When done, go to Georeferencing > Update Georeferencing
  • Save your work often!!!

Create a Terrain Raster

Since the CityEngine 2016 release, there is a new feature called "Get Map Data" which allows you to "grab" terrain models and imagery from the web. However, the workflow below could still be useful if you need more detail, or are reconstructing terrain in archaeological contexts, for example.

  • You can use either elevation points or contour lines. Make sure the layer has an attribute field called ‘Elevation’ with units in meters.
  • Search for ‘Topo to Raster’. You may have to enable the 3D Analyst add-on.
  • Select the elevation data layer and select the primary type of input data (point or contour).
  • Set ‘Field’ to ‘Elevation’
    • For very large areas, it is best to break up the terrain into tiles, especially if you’re planning to use it in Unity. If you are making smaller map tiles, you can draw these as a polygon layer and use ‘Output Extent’ to make the terrain size match the polygon size.
  • Click OK, add to map as layer
  • After the raster generates, right-click on the layer and select ‘Properties’
  • Click on the ‘Symbology’ tab
  • At left, select ‘Stretched’
  • At bottom, select Stretch type: Custom
  • Click ‘OK’ to close;
  • Right-click on the raster layer again, select Data > Export Data
  • Export to the ‘maps’ folder in your CityEngine Project folder (you may need to do this step after creating the project folders…. See “Create a CityEngine Scene” below)
  • Optionally, export again as a PNG file for use as a texture. Click the box next to “Use Renderer”. Edit the PNG in Photoshop to achieve the desired appearance (e.g. adjust levels).

Adding Shape Layers

  • Open the Catalog window (icon that looks like a file cabinet)
    • Right click on your geodatabase
    • New > Feature Class
      • Give it a name (‘Houses’)
      • Select WGS 1984 UTM Zone (in Favorites if you saved it there)
      • Next > Next> Finish
  • Get the ‘Editor’ toolbar by right-clicking the toolbar and selecting it if it’s not visible
    • Go to Editor > Start Editing
  • Right-click on the layer in the Table of Contents > Open Attribute Table
  • To draw shapes, select the layer template in the ‘Create Features’ window at right.
    • Use the rectangle tool. Start at the front right corner of the house (as if you were facing the building), draw the right edge of the lot and drag to the left. This ensures that the front edge of the lot is correctly identified. The red vertex should be at the back right corner.

Draw Streets

  • Open Arc Catalog
    • Right click on your geodatabase > New > Feature Class
    • Name: Streets
    • Type of features stored in this feature class: Line Features
    • Next > choose coordinate system WGS 1984 UTM Zone
    • Next> Next> Next> Finish
  • Go to Editor toolbar dropdown menu > Start Editing
    • Choose ’Streets’ template in Create Features panel
    • Draw lines for streets. Double-click to end a line.
    • Editor toolbar > Save Edits.

Draw Trees

  • There are two ways to create trees and plants: either as individuals or as landscape areas.
    • For individual plants:
      • Make a new point feature class. Draw points for each individual plant.
    • For landscape areas:
      • This is better for lots of plants covering large areas. Make a polygon feature class and draw areas that you want to be populated with trees. Precision is not important, just make sure it doesn’t overlap with any buildings.

Merging Spreadsheet Data with Shape Layers

  • Instead of manually creating fields and entering data in ArcGIS, if you already have prepared data in a spreadsheet you can merge this with your geodatabase.
    • Cleaning Data
      • Add a column at the left of your spreadsheet called ‘ID’. Give each row a unique identifier starting with 1. Make sure the ID column for each entry matches the ‘OBJECTID’ for the corresponding shape in ArcGIS.
      • The field names should not have spaces or any characters except letters, numbers and underscore.
      • Make sure each column contains data of just one type.
      • Make sure any attributes to be used in CityEngine rules are spelled the same (case sensitive)
      • Save the file. * Merging Data
      • In ArcGIS, right click on the layer in the Table of Contents > Joins and Relates > Join
        • Choose the field in this layer that the join will be based on: OBJECTID
        • Choose the table to join to this layer: navigate to your spreadsheet
        • Choose the field in the table to base the join on: ID
      • After joining, you must export the data to make the join permanent
        • Right-click the layer in the Table of Contents. Data > Export Data
        • Give your exported feature class a name. Make sure it is saving to your geodatabase.
        • Click OK and add to the map as layer.
      • Delete/turn off any fields you don’t want to show in the final model.

Adding Data in ArcGIS

  • If you want to add data in ArcGIS instead of merging a spreadsheet:
    • Editing mode (Editor > Stop Editing)
    • Open the attribute table (control+T or right-click on layer)
    • Expand menu in upper left corner of attribute table > Add Field.
    • Make a field.
    • To add data to the fields, go to Editor > Start Editing.
    • Delete/turn off any fields you don’t want to show in the final model.

Create a CityEngine scene

Getting Started

  • In the CityEngine/workspaces folder, make a folder called ‘1’. (This step is necessary because when you move across different workstations you will need to choose a new workspace each time).
  • Open CityEngine. When asked to select a workspace, choose the folder ‘1’ you just made.
    • Follow this process again whenever switching workstations. If you always work on the same computer, you can simply open CityEngine next time.
    • When in doubt, create a new workspace folder and use Safe Mode to enter that workspace. Or go to File >Switch Workspace.
  • You will now have a blank workspace. Create a new project folder by going to File > New > CityEngine > CityEngine project.
  • Give it a name.
  • Uncheck ‘Use default location’. Browse to the ‘CityEngine Project’ folder you just made. Click ‘Finish’.
  • The software generated some folders in your ‘CityEngine’ folder.
  • Create a new scene. Go to File > New > CityEngine scene. Give it a name and the same coordinate system we used for ArcMap: Projected > UTM > WGS 1984 > Northern Hemisphere > _.
  • The window layout can be customized by going to Window > Layout.
  • You can also change the 3D navigation mode by going to Edit > Preferences > General > Navigation Devices > Mouse. You can set navigation to be the same as Sketch Up if you prefer.

Layers in CityEngine

  • There are three types of layers in CityEngine: Maps, Shapes, and Graphs. They each have a slightly different set of controls.
    • Maps correspond to raster layers in ArcGIS. These can be terrain maps, attribute maps, occlusion maps, etc.
    • Shapes correspond to polygon and point layers in ArcGIS. In our scene these will be houses (polygons) and trees (points)
    • Graphs correspond to line layers in ArcGIS. In our scene these will be street networks.

Make a Terrain Layer

  • Go to Layer > New Map Layer > Terrain.
  • For ‘Heightmap’ click browse and you should be in the ‘maps’ folder. You should see the TIF file you exported from ArcGIS. Select this.
  • Do the same for the Texture file, but select the PNG version you created earlier.
  • Right-click the terrain layer in the Scene panel at left, and click ‘Frame’.
  • You should now see the terrain layer.
  • Select the terrain in the Scene panel and you get the layer options in the Inspector panel at right.
  • You can change the color to be a bit more natural looking. ‘Add to Custom Colors’ so you can find it later.
  • Now click ‘Save’ to make sure you save the scene and workspace.

Import the Geodatabase

  • Go to File > Import > CityEngine Layers > File GDB Import
  • Click ‘browse’ and go to your geodatabase.
  • Uncheck the boxes next to any layers you don’t want to import.
  • If importing streets:
    • Uncheck ‘Simplify Graph Tool after Import’
    • Uncheck ‘Create Block/Lot Shapes from Graph’
  • Align each layer to the terrain individually, as follows:

Importing Shape Layers (buildings)

  • Your shapes are now under terrain. To align them, with the shapes selected (blue) go to Shapes > Align Shapes to Terrain.
    • Align function: Translate to Average
    • Heightmap: select the terrain layer you just made.
    • Finish.
  • Now align the terrain to match the shapes. Go to Layer > Align Terrain to Shapes > Apply.
  • With shapes selected, in the Inspector panel go to Rule File > _.cga.
  • Click ‘Generate’. You should now see the models.
  • The rule attributes are taken directly from the attribute assigned in ArcMap.

Importing Graph Layers (streets)

  • Before aligning, a few cleanup steps are usually necessary.
  • With streets selected, right-click and choose ‘Cleanup Graph’
  • Check box for ‘Snap nodes to segments’
  • Increase Vertical Snapping Distance to 10
  • Click ‘Finish’ – check result, if nodes still don’t meet try again increasing the tolerance
  • In Inspector panel at right, click ‘Nodes’ tab
  • Change ‘type’ from ‘Smart’ to ‘Crossing’
  • In the ‘Scene’ panel at left, turn off the ‘Blocks’ sublayer under the ‘Streets’ layer. You should now just see your somewhat normal- looking streets.
  • With streets selected, right-click and ‘Align Graph to Terrain’.
  • If the terrain is sloped and the streets don’t align well, you can add additional nodes by using the ‘Polygonal Street Creation’ tool (icon with arrow and plus sign), and double-clicking on a segment. Then use the Move tool (arrow and box icon) to move the node to sit on the terrain, or select the note and ‘Align Graph to Terrain’.
  • Once the graph is well aligned, select shapes. Go to Layer > Align Terrain to Shapes.
  • The ESRI.lib folder in the Navigator is automatically included in every workspace. You it contains some pre-made assets and rules such as streets and plants.
  • Right-click on the ‘Streets’ layer. All the streets should turn blue.
  • Click on the ‘Shapes’ tab in the Inspector panel.
  • Rule File > Assign > navigate up a couple of levels to ESRI.lib/rules/Streets/Street_Modern_Standard.cga.
  • Don’t worry about the yellow warning indicator next to ‘Start Rule.’ This just means that all the streets shapes have different built-in start rules.
  • Click ‘Generate’. You should now see street models.
  • To modify the rule attributes, select shapes. To modify street network attributes, select segments.

Plants (shapes or points)

  • Select the objects and ‘project all’ to align to terrain.
    • For point layers:
      • Keep points selected and in the Inspector panel assign the rule ESRI.lib/Plants/Plant_Loader.cga.
      • Plant type must be changed one by one
    • For landscape areas:
      • Assign the rule file ESRI.lib/Plants/Plant_Distributor.cga
  • There are many pre-made landscape combinations and density settings.
  • Tree models have a lot of polygons. To make your scene perform faster, in the Inspector panel go to Plant > Options > Representation > Fan.

Scene Tools

  • The Settings button at the top of the viewport (gear wheel icon) lets you turn on/off shadows and ambient occlusion. Turn these off if your computer is slow.
  • In the same menu, you can also turn off the ‘Wireframe on Shaded/Textured’ for a cleaner look

Create Alternative Layers

  • If you want to highlight a difference in two versions of a model:
  • In the Scene panel, copy-paste your layer to make a duplicate, and rename the copy to distinguish it.
  • Turn off the original layer.
  • In the new layer, select the shape and make the changes in the Object Attributes panel under the inspector. Add notes about your alternate version.
  • Turn the original layer back on.
  • Rename the 2 layers something that makes sense (i.e. houses_version_1, houses_version_2).

Make a Slide Show

  • Position the camera to show the view you want.
  • Above the viewport, click the star icon > Add Bookmark.
  • Give the bookmark a name. You can change the order in Edit Bookmarks.
  • Make sure to highlight views of your alternate models.

Export a CityEngine Webscene

  • Make sure all layers you want to include are visible, and shapes are on.
  • If shadows are on during the export process, they will be on by default in the webscene. Otherwise, they can be turned on in the webscene options.
  • Select all the shapes. Models do not have to be generated.
  • Go to File > Export Models > CityEngine WebScene
  • Choose the name and output path for your file. By default this will be the ‘models’ folder in your CityEngine project.
  • Choose “Export all visible terrain layers”. Click Next.
  • Give the two alternate layers a Group Name. This allows them to be compared using the slider.
  • Make sure there are no layers you don’t want to include. Click Finish.
  • When the export finishes, go to the models folder in the navigator panel and if you don’t see the model you just made, right-click and refresh.
  • Double click to open the webscene. Double check for errors.


  • If the webscene viewer doesn’t display, try setting the default browser to Chrome or Firefox.
  • If the terrain doesn’t appear in your model, close and reopen CityEngine, and export again. This usually works.

Export to Unity or other renderer

CityEngine scenes are in ‘geospace’, while Unity scenes are in Cartesian space. The following steps will help you set up your workflow so that you can move models from CityEngine to Unity with relative ease. This also is useful for any other renderer that is non-geolocated.

Setup File Structure

  • Open Unity and create a new project in the ‘Unity’ folder you made. This will create a series of new directories inside that folder.

Export the Terrain Map

  • Set the u and v resolution to the same value. Choose 257 for a low-res terrain, or 2049 for high. Lower is better for scene performance!
    • Re-align terrain to models if necessary.
  • In CityEngine, after aligning the terrain to models as desired, double-click to select the terrain in the Scene panel.
  • Go to File > Export > Export Selected Terrains as Image.
  • Click the box next to ’16 bit’.
  • Click ‘Finish’.

Convert Terrain File (Photoshop)

  • In Photoshop, open the .png file you just exported.
  • Flip image. Go to Image > Image Rotation > Flip Canvas Vertical
  • Save as a RAW file. Go to File > Save As > Format: Photoshop RAW (*.RAW)
  • Save the file in your Unity/assets folder. You may want to create a subfolder called ‘heightmaps’.

Get Terrain Dimensions

  • Upload the .png exported from CityEngine to an image metadata viewer such as
  • You will see ‘range_min’ and ‘range_max’.
  • The ‘range_min’ is the y-position of the terrain. - Subtract the ‘range_min’ from the ‘range_max’. This is the y-dimension of the terrain. Make a note of this number.
  • Find the x- and z-position of the terrain. Divide the x-size and z-size numbers from CityEngine by two (x size/2, z size/2). Make a note of these numbers for the next step.

Create Terrain in Unity

  • GameObject > 3D Object > Terrain
  • In the Inspector panel, go to Terrain settings (gear wheel icon).
  • Under Heightmap, ‘Import Raw’. Navigate and select the RAW file you created.
  • Change the byte order to Windows.
  • Enter the x,y,z size of the terrain. The x and z size can be found in the CityEngine inspector. The y-dimension was calculated in the step above. - Click ‘Import’.
  • If you need to modify the Terrain dimensions later, go to Terrain --> Set Resolution.
  • Position the terrain at the center of the scene. With the Terrain selected in the hierarchy, set the x- and z- position to the numbers you calculated earlier. Make these negative numbers (-x size/2), (-z size/2). The terrain is now centered.
  • Set the y-position. This is the same as the ‘range_min’ from the image metdata.
  • In the Inspector, click on the paintbrush icon for materials.
    • Terrain materials can be obtained by importing the Environment package
  • Save the scene in the Unity/Assets folder.
  • Your terrain is now finished. Next, add some models!

Export Models from CityEngine

  • Before export, it’s a good idea to set the viewport in CityEngine to ‘cull backfaces’ to check if you have any flipped normals! These will not render in Unity.
  • First, we need to set up a ‘global offset’.
    • Select the Terrain the Scene tab. This is the extent of your scene.
    • Go to File > Export Models of Selected Shapes > FBX.
    • Under ‘Misc Options’, select ‘Reset’ and ‘Center’.
    • Set Y-Offset to 0.
    • Save these export settings, and use the same preset for all subsequent exports.
    • You don’t actually need to export at this stage. Click cancel.
  • Now, select all the shapes you wish to export.
    • It is a good idea break up the export into chunks, according to how you want to deal with layers in Unity. Also, Unity can’t handle importing too many vertices at once. If you end up with missing geometry this could be the case.
    • Go to File > Export Models of Selected Shapes > FBX.
    • Make sure “do not export any terrain layers” is selected, or CE will crash!
    • Export Geometry: Models
    • Under ‘Preset’ choose ‘Previous Export Settings’. - Under ‘Location’, browse to find the ‘Assets’ folder of your Unity project. Make a subfolder called ‘Models’, and save all your exports here.

Import Models to Unity

  • Because you saved in the Unity ‘Assets’ folder, when you click on the Unity window it will refresh and the model will appear in the ‘Project’ tab. Select the model to view the Import Settings in the Inspector at right.
  • Set ‘Scale Factor’ to 100 (FBX model scale is 0.01).
  • Now drag the model to the Hierarchy tab at left. Model will import to the scene.
  • Select the model under the Hierarchy tab.
  • Set X Rotation to 180 and Z Rotation to 180.
  • Check the box next to ‘Static’ at the top.


  • If you get a hanging process called something like “5/11 Clustering” in Unity go to Window > Lighting and uncheck the box next to ‘Auto’.
You can’t perform that action at this time.