Tutorial 5: Import initial shapes

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.

Sphere city models

Importing data is an essential part of working with CityEngine. Many formats are supported including shapefiles, geodatabases, OBJ, FBX, USD, glTF, DWG, and IFC. See Import by dialog for more information.

Most of the file types can be imported as shapes or static models with the following descriptions:

  • Shapes serve as a base for CGA generation. A typical example is footprint data.
  • Static models can be scaled, rotated, and translated after import but cannot be processed further with CGA. Typical examples are landmark buildings.

This tutorial shows you how to import data formats and provides workflows to process them further.

Import shapefiles

To import shapefiles, do the following:

  1. Click File > New > CityEngine > CityEngine scene in the main menu to create a scene.
  2. Drag the footprints.shp file from the \data\shp_footprints\ folder into Viewport.
  3. Select Raw data in meters under No Projection as the scene coordinate system.

    Raw data in meters scene coordinate system

    The data in the shapefile is in meters and not georeferenced, so the scene coordinate system is set to Raw data in meters.

  4. Click OK.

    Imported shapefile data

  5. Select a single footprint to see the object attributes imported with the shapefile.

    The object attributes are displayed under  Object Attributes in the Inspector window.

    Shapefile attributes

Assign a rule and generate models

You'll now generate simple extrusions with CGA rules on the imported footprints. The extrude.cga rule extrudes the footprint to the height defined in the height object attribute.

  1. Double-click the extrude.cga rule file in the \rules\ folder to open it in the CGA Editor window.

    attr height = 10
    Lot --> extrude(height)

  2. Select all the footprints in Viewport.
  3. Drag the extrude.cga rule onto the selected shapes to assign the rule.

    Extruded models from shapefile

    Open the footprints_from_shp.cej scene to see the generated models.

Import geodatabase data

The workflow for importing geodatabase data is similar to the shapefile import.

  1. Create a scene.
  2. Drag the \footprints.gdb\ folder from the \data\ folder into Viewport window.


    The footprints.gdb file is displayed as a folder in Navigator window.

    The FileGeodatabase dialog box appears, allowing you to choose the layers to import from the geodatabase.

    FileGeodatabase dialog box


    You can click Next for additional import options such as Generate Bridges, Simplify Graph, and Cleanup Graph.

  3. Click Finish.

    You are prompted to choose a scene coordinate system. The coordinate system suggested in the dialog box is taken from the data in the geodatabase.

    Scene coordinate system

    Since the data in the geodatabase is identical to the shapefile above, you can apply the same steps to generate the building models from the footprints.

Import PolylineZ shapes

Do the following to import shapes with Z values:

  1. Create a scene.
  2. Drag the sphereCity.shp file from the \data\sphereCity_shp\ folder into Viewport window.

    The Select a shapefile data coordinate system dialog box appears.

  3. Select Raw data in meters since the shapefile data is in meters and is not georeferenced.
  4. Click OK.

    The sphereCity.shp file doesn't have a .prj file that defines the scene coordinate system, so the Select Scene Coordinate System dialog box appears.

  5. Choose Raw data in meters as the scene coordinate system.

    By using the same coordinate system for the data and scene, no reprojection is applied to the data on import.

    Sphere city shapes

The new sphereCity shape layer is added to the Scene Editor window, and since the footprint shapes have z-values, they display as 3D polygons in Viewport.


Two attributes are defined in this dataset: ruleFile and startRule.


Use this specific syntax in your GIS application to define which rules and start rules are assigned directly after import. This saves time by not having to manually assign them.

The attribute table in your GIS application will look similar to the following:

Attribute table

  1. Select a single shape (one face of the sphere).

    In the Inspector window, the object attributes are displayed under Object Attributes and the rules that are automatically assigned are under Rules.

    spherecity rules and attributes

  2. Select all the shapes of the sphereCity layer in the Scene Editor window.
  3. Click Generate Generate (Ctrl+G) to generate the buildings.

    Sphere city models

    The spherecity_from_shp.cej scene shows the sphere city with models.

Change the start rule

Change the start rule for individual shapes to change the generated model.

  1. Select a single model in the scene.
  2. Click Select next to Start Rule.

    Select Start Rule

    The Set Start Rule dialog box appears.

    Set Start Rule

    Start rules (rules with the @StartRule tag in CGA code) are displayed in bold.

  3. Select  Commercial as the new start rule.
  4. Click OK.

    Model with start rule set to Commercial

Import shapes from OBJ

To import OBJ files as shapes, do the following:

  1. Create a scene.
  2. Right-click the pompeii_footprints.obj file in the \data\obj\ folder and select Import.

    The OBJ import dialog box appears.

    OBJ dialog box

  3. Uncheck  Import as static model.
  4. Click Finish.

    OBJ shapes in the Viewport window

    You'll now generate simple extrusions from the footprints.

  5. Select all the footprints.
  6. Drag the extrude.cga rule file onto the selected footprints.

    When you drag the rule over the shapes, they are highlighted:

    Assigning extrude rule to shapes

    The extrude.cga rule file extrudes the footprint shapes to a height of 10 meters defined by the height attribute in the rule.

    OBJ shapes with 10 meter extrusion

    Open the footprints_from_obj.cej scene to see the final extruded models.

Import an OBJ file as a building model

You can model volumes in an external application instead of describing them with the CGA grammar. This section describes how to import a building volume modeled in Autodesk Maya into CityEngine, and refine the facades using CGA rules.

Building volume model

This building volume was modeled with conventional methods in Maya and exported as an .obj file.


See Import by dialog for a list of the file formats supported by CityEngine.

To import the OBJ, do the following:

  1. Create a scene.
  2. Right-click the Building_1.obj file in the \data\obj\ folder and select Import.

    The OBJ dialog box appears.

  3. Uncheck Import as static model.
  4. Click Finish.

    The new Building_1 shape layer appears in the Scene Editor window and the building model displays in the Viewport window.

    OBJ building model

Apply a building rule

The Building_1 shape includes the Building start rule. You must align the coordinate system of the model to the CityEngine yUp system.

The Building rule uses the alignScopeToAxes() and comp(f) CGA operations to split the model into different faces. The top selector is for the roof faces and the side selector is for the facades:

Building -->
	comp(f){top : color("#ff0000") Roof. | side : Facade. }

This colors the roof shape so that the faces are identified correctly.

To apply the Building rule to the building model, do the following:

  1. Select the building model.
  2. Drag the importedVolume_01_markFaces.cga rule file onto the selected building.

    Building model with faces

    The building model now has the colored faces—red for the top faces (roof) and gray for the side faces (facades).

    Because the faces are modeled outside CityEngine, their orientation is not necessarily compatible with your rule operations. To correct this, the importedVolume_02_facades.cga rule adds the Facade rule to the alignScopeToGeometry(zUp, any, world.lowest) CGA operation:

    Facade -->  
    alignScopeToGeometry(zUp, any, world.lowest)
    split(y){3.5 : Groundfloor | {~3 : Floor}* }

    The Facade rule aligns the scope of the facade shape to its lowest edge, with z facing outward. This ensures that you operate with identically oriented scopes on all facade faces.

  3. Ensure that the building model is selected.
  4. Drag the  importedVolume_02_facades.cga rule file onto the selected building.

    Building with facade detail

    The volume_from_obj.cej scene shows the finished model.

  5. See Tutorial 6: Basic shape grammar for more information about CGA rules.

Import assets as textured shapes or static models

You can import premodeled textured assets, such as landmark buildings, as shapes or static models.

  1. Create a scene.
  2. Drag the building_0.dae file from the \data\dae\ folder into the Viewport window.

    Imported DAE model

    The new building_0 shape layer appears in the Scene Editor window.

Convert static models to shapes

To apply CGA rules to static models, you must first convert them to shapes.

  1. Select the imported static model.

    Static model

  2. Click Shapes > Convert Models to Shapes in the main menu.

    Shape model after conversion

    The models are now ready to apply CGA rules.

Apply a CGA rule

To apply a landmark rule to the model, do the following:

  1. Select the building model.
  2. Drag the landmark.cga rule file onto the selected building.


  3. Explore the rule options by changing the values of the mode parameter in the Inspector window.

    Mode options

  4. Click the landmark drop-down menu to switch between the styles or click Preview & select styles to open the Style Manager window.

    Style menu

    The Style Manager window displays the style options.

    Style Manager window

    To view the finished scene with the generated models, open the landmark_as_shape.cej scene.

In this tutorial, you learned how to import several file formats as shapes or as static models into CityEngine and apply rules to them.

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