CityEngine/SUMO Scene Construction Manual i

CityEngine/SUMO Scene Construction Manual CityEngine/SUMO Scene Construction Manual ii

Contents

1 Overview of the Manual 1 1.1 Tools...... 1 1.1.1 CityEngine [CE] ...... 2 1.1.2 SUMO ...... 2 1.1.3 OpenStreetMap [OSM] ...... 3 1.1.4 JOSM ...... 3 1.1.5 USGS National Map Viewer ...... 4 1.1.6 TERRA ...... 4 1.1.7 simpleDemViewer ...... 5 1.1.8 GIMP ...... 5 1.1.9 Quantum GIS [QGIS] ...... 6 1.2 Terminology...... 6 1.2.1 graph elements (nodes and edges) [CE OSM SUMO] ...... 6 1.2.2 street/sidewalk shapes [CE] ...... 7 1.2.3 blocks [CE] ...... 8 1.2.4 lot shapes [CE] ...... 8 1.2.5 models [CE DIRSIG] ...... 9 1.2.6 attributes [CE OSM SUMO] ...... 9 1.2.7 attribute sources [CE] ...... 10 1.2.8 map layers [CE] ...... 10 1.2.9 scripts [CE] ...... 11 1.2.10 CGA/rules [CE] ...... 11 1.2.11 trips [SUMO] ...... 12 1.2.12 route [SUMO] ...... 12 1.2.13 traffic simulation [SUMO] ...... 13 1.2.14 dump file [SUMO DIRSIG] ...... 13 1.3 Workflow...... 13 CityEngine/SUMO Scene Construction Manual iii

2 Initialization of the CityEngine Scene 15 2.1 Workflow...... 15 2.2 Create a new Project in CityEngine...... 16 2.2.1 Visual guide...... 16 2.3 Organize the CityEngine scene and input directories...... 17 2.3.1 Visual guide...... 18 2.4 Create a new Scene in CityEngine...... 19 2.4.1 Visual guide...... 19 2.5 Prepare the OSM Graph Layer...... 21 2.5.1 For segments/edges (ways in OSM)...... 22 2.5.2 For nodes/intersections (nodes in OSM)...... 23 2.5.3 Visual guide...... 24 2.6 Overwrite CE OSM import rules...... 24 2.6.1 Visual guide...... 25 2.7 Setup configuration file...... 26 2.7.1 Initialization Variables...... 26 2.7.2 Class Mappings...... 27 2.7.3 Property Objects...... 28 2.7.4 Visual guide...... 29 2.8 Load the scripts into CityEngine...... 29 2.8.1 Visual guide...... 30 2.9 Clear existing scene and maps (script)...... 31 2.10 Import OSM street map (script)...... 31 2.11 Assign properties to edges and nodes (script)...... 32 2.11.1 Visual guide...... 32 2.12 Restart CityEngine...... 33 2.12.1 Visual guide...... 33

3 Exportation to SUMO 35 3.1 Workflow...... 35 3.2 Initialize the scene...... 35 3.3 Setup the output filenames...... 36 3.4 Select the area of the scene to export...... 36 3.5 Walk through all nodes and edges in the scene...... 37 CityEngine/SUMO Scene Construction Manual iv

4 Generating Vehicle Tracks with SUMO 39 4.1 Traffic Simulation with SUMO...... 39 4.1.1 Getting the SUMO Software...... 40 4.1.2 Importing the Road Network...... 40 4.1.3 Generating Routes...... 40 4.1.4 Populating the Road Network...... 40 4.1.5 Running the SUMO Simulation...... 41 4.1.6 SUMO Output Files...... 41 4.2 Exporting the SUMO Vehicle Tracks...... 41 4.2.1 The sumo2dirsig tool...... 42 4.2.2 Performing the Export...... 43 4.3 Importing Vehicle Tracks...... 43 4.3.1 Initial Vehicle Attributes...... 44 4.3.2 Randomizing Vehicle Attributes...... 45 4.3.3 Randomizing Vehicle Geometry...... 46 4.3.4 Dynamic Instance Import...... 47 4.3.5 Summary...... 47

5 Terrain importation and construction 48 5.1 Source Data...... 48 5.2 Importing Terrain Geometry to CityEngine...... 50 5.3 Using Terra to Facetize the Terrain...... 54 5.3.1 Building Terra...... 54 5.3.2 Preparing the Heightmap for Terra...... 54 5.3.3 Generating the Optimized OBJ with Terra...... 56

6 Constructing street geometry 59 6.1 Workflow...... 59 6.2 Initialize the scene...... 59 6.3 Import and align graph to terrain...... 60 6.4 Prepare the rule files...... 61 6.4.1 Rule tree...... 61 6.4.2 Sub-division and UV-mapping...... 62 6.4.3 Assets...... 64 6.4.4 Sidewalk rules...... 65 6.4.5 Variables and functions...... 65 6.5 Transfer graph attributes to shapes and set rule file...... 66 6.6 Generate models...... 67

7 Lot Geometry 68 CityEngine/SUMO Scene Construction Manual v

8 Exporting CityEngine geometry 69 8.1 Workflow...... 69 8.2 Export CityEngine models as OBJ files...... 69 8.3 Tranforming the OBJ files...... 71 8.4 Map OBJ materials to DIRSIG materials...... 71 8.5 Replace texture maps with DIRSIG material and texture maps...... 73 8.6 Write reports for clutter objects...... 74

A Generating vehicle track truth 75 A.1 Instance Report Generation...... 75 A.1.1 Requesting the Report...... 75 A.1.2 Report File Format...... 76 A.2 Raster Format Truth Collectors...... 76 A.2.1 Adding the "InstanceIndex" Collector...... 76 A.2.2 "InstanceIndex" Truth Map...... 77 A.3 Generating Per-Instance Tracks...... 78 A.3.1 Running the Extraction Tool...... 78 A.3.2 Track File Format...... 79 CityEngine/SUMO Scene Construction Manual vi

Authors: Adam Goodenough ([email protected]) Scott Brown ([email protected]) Rochester Institute of Technology ChesterF. Carlson Center for Imaging Science Digital Imaging and Remote Sensing Laboratory 54 Lomb Memorial Dr Rochester,NY 14623 CityEngine/SUMO Scene Construction Manual 1 / 82

Chapter 1

Overview of the Manual

This document describes the end-to-end process of generating a partially procedural, partially data-driven scene for use in DIRSIG (the Digital Imaging and Remote Sensing Image Generation model). CityEngine, a procedural scene generation tool, is used as the main driver for static scene geometry and SUMO (the Simulation of Urban MObility tool) is used to supply dynamic scene content (specifically vehicle movement in traffic). The framework of the scene is a data-driven description of the terrain and a street network. Both of these two inputs could be procedurally generated (as artificial terrain and/or a synthetically grown street network), but we take the approach here of using real world data. This gives us the benefit of physically realistic scenes without complex construction rules and a rich set of data that might otherwise be difficult to replicate with either model-based or statistical representations. Constructing the framework consists of obtaining these data sources and converting/importing that data into the workflow. The scene framework is coupled with user-driven descriptions of contextual information (e.g. population density) to create inputs to the procedural portion of the scene, which builds the specific road/building geometry and predicts the movements of vehicles. On the geometry side, a combination of scripting and rule based decision trees are used in CityEngine to transform simple shapes into complex, three-dimensional geometry entities with material information. For the dynamic content we assume that models of vehicles are already available and we use the description of the street network (including speed limits, intersection controls, etc..) to drive a traffic model and predict the locations of vehicles as a function of time. Care is taken to make sure that the predicted vehicle routes match up with the three-dimensional street geometry modeled in CityEngine. Fine control over the scripting and rules in CityEngine also allow for generating non-geometric information such as the positions of trees along roadsides or the locations of street parking spots. Information about scene elements such as driveways can also be extracted and then used to drive procedural elements not generatable in the two available tools (such as vehicles driving out of parking lots). One of the overarching goals of the process described here was to have as little user interaction in the details of scene building as possible. The user is still responsible for providing a large set of input parameters and data sources, but these are meant to be high level, describing the general characteristics of a particular scene area without providing the exact details about what each component of the end product should look like. That said, the constructed scene can be seen as a starting point for very specific scene element modeling that might be relevant to the desired simulation. For instance, a generic building lot that we generate for an industrial region of the scene might be removed in favor of a specific site model. The manual is presented as a series of mostly independent, modular chapters, each focused on a particular task. This overview chapter presents a centralized list of the tools and sources of data that are in use (and what they are used for), a list of the terms and concepts that will be encountered in the rest of the manual, and a brief descriptioon of the overall workflow of generating a scene.

1.1 Tools

Though the two primary tools used in this approach to scene construction are CityEngine and SUMO, there are a number of additional tools that facilitate the workflow. Below, we list and briefly describe each of the tools used in the development of this manual and identify their main contributions. Since many of the tools were chosen for convenience rather than exclusive functionality, possible alternatives are listed as well. CityEngine/SUMO Scene Construction Manual 2 / 82

1.1.1 CityEngine [CE]

• Source: http://www.esri.com/software/cityengine [2012.1] • License: commercial ($4,000) • Usage: main scene generation driver – importation of OSM street map information – script and rule based geometry creation – script based exportation of SUMO network inputs

1.1.2 SUMO

• Source: http://sumo.sourceforge.net/ [0.16.0] • License: GPL • Usage: vehicle motion prediction – demand based modeling of vehicle trips – traffic simulation on CityEngine street network – vehicle motion history for DIRSIG CityEngine/SUMO Scene Construction Manual 3 / 82

1.1.3 OpenStreetMap [OSM]

• Source: http://www.openstreetmap.org [online interface] • License: Open Data Commons Open Database License • Usage: street network information – starting point for street network graph – tagged metadata for streets and intersections • Alternatives: ESRI shapefiles with road network information, CityEngine based synthetic networks

1.1.4 JOSM

• Source: http://josm.openstreetmap.de/ [5759] • License: GPL • Usage: open street map viewer/editor – trimming raw street map data – viewing and editing tagged data • Alternatives: hand-editing OSM files, Potlatch 2 CityEngine/SUMO Scene Construction Manual 4 / 82

1.1.5 USGS National Map Viewer

• Source: http://viewer.nationalmap.gov/viewer/ [online interface] • License: public domain • Usage: digital elevation maps – moderate resolution elevation information for terrain construction • Alternatives: any other source of georeferenced elevation data

1.1.6 TERRA

• Source: http://mgarland.org/software/scape.html [0.7] • Usage: facetization of terrain elevation map • License: public domain

– transforming rasterized height data into 3D facets – optimizing the triangular mesh representation

• Alternatives: ArcGIS tools, any of many Delaunay triangulation/triangular irregular network tools CityEngine/SUMO Scene Construction Manual 5 / 82

1.1.7 simpleDemViewer

• Source: http://www.jizoh.jp/english.html [3.9.5] • License: public domain • Usage: converting DEM files for TERRA inputs • Alternatives: any convenient tool for viewing/converting georeferenced images

1.1.8 GIMP

• Source: http://www.gimp.org/ [2.8.2] • Usage: image editing • License: GPL

– synthetic property maps for driving scene attributes – layer-based editing of property maps/masks incorporating measured data

• Alternatives: Adobe Photoshop or other layer-based image editor CityEngine/SUMO Scene Construction Manual 6 / 82

1.1.9 Quantum GIS [QGIS]

• Source: http://www.qgis.org/ [1.8.0] • Usage: projecting raster data • License: GPL

– bringing raster data from different sources into the same geo-projection – property maps for scene construction

• Alternatives: ArcGIS or other GIS tool

1.2 Terminology

There are a number key terms that come into play over the course of transforming OpenStreetMap data into a final DIRSIG scene. We present those terms here to avoid giving their definitions each time they are encountered throughout the manual. The key tool(s) that use the term are given as well; one or more of: OpenStreetMap (OSM), CityEngine (CE), SUMO, and DIRSIG.

1.2.1 graph elements (nodes and edges) [CE OSM SUMO] CityEngine/SUMO Scene Construction Manual 7 / 82

The street networks in all three tools (OSM, CityEngine, and SUMO) are represented by a directed graph. The nodes of the graph correspond to intersections and dead ends in the street network and, in the case of OSM and CityEngine, waypoints along a road defining its shape (SUMO has an explicit shape definition). The edges of the graph are the roads in the network and are referred to as ways, segments, and edges in OSM, CE, and SUMO, respectively. Both OSM and CE use a single edge to define a twoway road, while SUMO uses two edges for this (one in each direction). All three tools define one or more lanes for a single edge. Nodes are defined by a horizontal point in a coordinate space (possibly georeferenced), though CityEngine allows for adding vertical component that is driven by the terrain height at that point. Edges are minimally defined by the two nodes that form their endpoints. Nodes and edges together are referred to as the network.

1.2.2 street/sidewalk shapes [CE]

Shapes are unique to CityEngine and convert the one-dimensional nodes and edges of the graph (geometric points and edges) into two-dimensional forms that will be used as the basis for three-dimensional models. A shape is simply a polygonal object defined by a set of two-dimensional vertices. A minimal amount of knowledge is necessary to accomplish thise, specifically CityEngine will need to know the width of the roads corresponding to each segment to generate street shapes. At nodes, where street shapes intersect, CityEngine will find a non-overlapping representation of the junction shape: CityEngine/SUMO Scene Construction Manual 8 / 82

Because sidewalks and other curb-related elements are highly correlated to the streets, it is useful to construct a parallel sidewalk shape (again, by providing the width of this area). Sidewalk shapes behave identically to street shapes, but are labeled differently and (by default) flank the street shapes.

1.2.3 blocks [CE]

When creating street shapes in CityEngine, a set of abstract blocks which explicitly define the areas corresponding to the inner- most edge of the street shapes (an area that is not surrounded on all sides by a road does not create a block). Blocks are not shapes themselves, but instead can create shapes (lots), much like the graph components.

1.2.4 lot shapes [CE]

Lot shapes are generated by blocks in CityEngine and are the two-dimensional objects on which buildings may be constructed. A block is subdivided into lots based one of a handful of simple algorithms (e.g. recursive subdivision) and is not generally driven by external data. By default, lots will be generated on all blocks (even skinny blocks that might have been medians). CityEngine/SUMO Scene Construction Manual 9 / 82

1.2.5 models [CE DIRSIG]

Models are the result of applying a rule to a shape within the scene. The rule starts with the two-dimensional shape and after manipulating that shape (usually by sub-dividing and extruding) ends up with one or more three-dimensional representations. In addition to geometry, the model can contain material properties associated with surface (e.g. a texture map defining a brick surface on the side of a building). In the case of street shapes, the output model is a facetized representation of a street (including the lines, should, gutter, etc..). Sidewalk shapes are used to generate curbs, verges, sidewalks, driveways, etc..). Lots usually have the most complex rules and the outputs are facetized buildings, lawns, garages, parking lots, etc. . . The final destination of all output models is to be used as material attributed geometry in DIRSIG to construct the scene.

1.2.6 attributes [CE OSM SUMO]

Graph/block elements and shapes are defined by their geometric properties, but they also have a set of attributes attached to them that can define any number of additional properties. Since attributes are available both in the scripts and rules in CityEngine and are tied to individual scene elements, they are the primary way by which control is exerted over the scene generation process. OSM and SUMO also allow for attaching tagged information to their representation of the road network. In OSM attributes are defined as arbitrary key/value pairs (as in CE) whereas SUMO has specific properties that can be defined of relevance to the traffic simulation. When imported into CE, OSM attributes can be mapped directly to CE attributes in the graph. CityEngine/SUMO Scene Construction Manual 10 / 82

1.2.7 attribute sources [CE]

In CityEngine, there a number of ways attribute are assigned: DEFAULT (RULE), USER,OBJECT and . DEFAULT attributes are those variables that have been defined in the rule file associated with the objects but have not been defined elsewhere (i.e. they take the default value the variable was initialized with). USER attrbutes are those that have been set directly by the user, either by interacting with the object in the GUI or setting the value from a script. OBJECT attributes are inherited from the parent object (e.g. a street shape can inherit attributes from its parent segment). Finally, a attribute is connected to a map (and potentially a function that translates the map value to the attribute value).

1.2.8 map layers [CE]

Maps are images loaded into CityEngine as scene layers that associate a horizontal position in the scene with a specific property. For example, the terrain/elevation map associates a vertical position (elevation) with any point within the scene that is then used to drive the vertical postion of graph elements. In this case each grayscale pixel value value in the image is used to compute the elevation in meters. Maps are also used to drive specific attributes associated with scene elements. This can be done in a binary fashion (treating the map like a mask that might drive something like the presence of street lights). Alternatively, the pixel value can be used to drive a lookup in a table of properties, such as a region class map that describes population density and land usage. CityEngine/SUMO Scene Construction Manual 11 / 82

1.2.9 scripts [CE]

CityEngine provides a Python console and the ability to run Python modules from within the GUI. In both cases, a scripting environment provides an API to a signficant portion CityEngine’s functionality. In contrast to rules, a script is a full programming language (Python) and may be used to asynchronously build or modify the scene. While there is some functionality in place to directly work with shapes and models, a script should not replace rules and should primarily be used to edit the basic objects and apply attributes.

1.2.10 CGA/rules [CE]

The rule files in CityEngine are user-written descriptions of how two-dimensional shapes should be converted into three- dimensional models. Rules are stored in CGA, or computer generated architecture, files and every shape in the scene (that will be used) should have an associated CGA file. CGA is not a programming language in the usual sense — it can be thought of as describing how a single shape is replaced by one or more shapes and/or models (the mapping of a single shape is a rule). For procedural construction of buildings/roads, this approach is very effective since branching from one rule to the next can be randomized and/or driven by the scene context. CityEngine/SUMO Scene Construction Manual 12 / 82

1.2.11 trips [SUMO]

In SUMO, a trip describes the desire for a particular vehicle to go from node A to node B in the network, starting at a particular moment in time. It does not describe the path it will take to the destination node nor is there any information about the time it will take. Trips are generated by one of many demand generation tools associated with SUMO, but not by SUMO itself.

1.2.12 route [SUMO]

A route is the specific path to be taken by a vehicle in the road network in order to complete a trip. Initial routing is usually done by considering a single criterion (such as shortest time), but may be updated after traffic simulation to take into account delays. Routes are created by an external tool called "duarouter," not by the main executable of SUMO itself. CityEngine/SUMO Scene Construction Manual 13 / 82

1.2.13 traffic simulation [SUMO]

The function of the SUMO executable (either command-line or GUI based) is to run the traffic simulation, which models what happens when all of the vehicles on the network attempt to complete their routes simultaneously. The traffic simulation is meant to be done iteratively in combination with re-generating the routes based on congestion information (i.e. the shortest route between two points may change when taking into account the amount of time spent in traffic)

1.2.14 dump file [SUMO DIRSIG]

The dump file captures the state of the street network in SUMO at a fixed sampling rate (such as every second) during the traffic simulation. This includes information about the location of every car active on the network and their speed at the time, information that is used by DIRSIG tools to produce a motion file for each vehicle in the simulation.

1.3 Workflow

The order of the modules in this manual roughly correlates to the workflow in which the scene is constructed. In general, we go from one-dimensional data (the nodes and edges of a graph network) to three-dimensional data (either vehicle movement within the scene or scene geometry). Conceptually, we can split the process into street modeling (three-dimensional representations of the streets and curbs as well as the vehicles on them) and lot modeling (construction of buildings and off-street geometry in general). CityEngine/SUMO Scene Construction Manual 14 / 82

About halfway through street modeling in CityEngine we branch off a parallel process in SUMO that uses the actual street graph/shapes in CityEngine to drive the SUMO network. Once the inputs to SUMO are created, the entire traffic modeling process is independent from the rest of the scene development until the final vehicle movement files are brought into the DIRSIG simulation.

Each module is described in more detail in the coming chapters. Each module has a specific set of inputs and outputs that we list here for convenience:

inputs module tools outputs OSM data file; Initialization of the CE CE network attributed initialization script; user CityEngine Scene with street parameters configuration script; region class map attributed street Exportation to SUMO CE SUMO node and edge network; export script; files user configuration script node and edge files Generating vehicle SUMO, DIRSIG vehicle motion tracks with SUMO DIRSIG files elevation map (DEM) Terrain importation CE, Terra DIRSIG terrain and construction geometry; CE terrain-aligned graph network terrain-aligned, Constructing road and CE CE street and sidewalk attributed graph sidewalk geometry models network; street/sidewalk rule file; maps terrain-aligned, Constructing lot CE CE lot models attributed graph geometry network; lot rule file; maps scene component Exporting CityEngine CE material-attributed models (street, sidewalk, geometry DIRSIG geometry lot) material-attributed Assembling the DIRSIG DIRSIG scene geometry; vehicle DIRSIG scene motion files; external geometry CityEngine/SUMO Scene Construction Manual 15 / 82

Chapter 2

Initialization of the CityEngine Scene

Initialization of the scene involves loading and applying attributes to the scene network that are either unavailable in the CityEngine importation process or are sourced from external data (e.g. using a class map to determine sidewalk widths). This process is fully automated using the python scripting interface to CityEngine and driven by a single configuration script shared with other parts of the scripting process. One important part of initialization is to link nodes to segments and segments to blocks (the basis of building lots) something that is not natively supported in CityEngine. This linking is essential for matching street specific properties (such as driveways that might act as nodes for SUMO) to the lot modeling that will be done in CityEngine.

Note Initialization of the CityEngine scene should only need to be run once to import and attribute nodes and edges from the input street map. The master script will only run the initialization module if no scene elements are selected from within CityEngine (any nodes/edges generated previously and any loaded maps will be removed prior to initialization).

Note The initialization script is wrapped with a @noUIupdate directive that indicates to the CE scripting engine should run these scripts without checking back in with the GUI (this is done to increase the speed at which the script runs). The presence of this directive means that the CityEngine interface will be non-responsive during the initialization process. To monitor what is happening as the script runs, make sure that the console window is visible in CityEngine before starting the initialization.

2.1 Workflow

• Create a new Project in CityEngine • Organize the CityEngine scene and input directories • Create a new Scene in CityEngine • Prepare the OSM graph layer • Overwrite CE OSM import rules • Create a class map • Setup configuration file • Load the scripts into CityEngine • Clear existing scene and maps (script) CityEngine/SUMO Scene Construction Manual 16 / 82

• Import OSM street map (script) • Assign properties to edges and nodes (script) • Restart CityEngine

2.2 Create a new Project in CityEngine

Action Item(s): Create a new project

A new project is started by simply selecting File > New... from the CityEngine Menu and choosing CityEngine pro ject from the list of wizards. You will have the opportunity to select a name for the new project and its location (the directory is arbitrary, but it is useful to place all of your CityEngine projects in the common CityEngine directory that was created during install).

2.2.1 Visual guide

Dialogs used in this section: CityEngine/SUMO Scene Construction Manual 17 / 82

2.3 Organize the CityEngine scene and input directories

Action Item(s): Add a sumo directory to the project tree

Each project created in CityEngine will be laid out in its own directory tree structure, to which we will add our input data. Since the SUMO output is tightly coupled to the CityEngine model, we’ll add a directory called "sumo" to the tree to hold our exported data. This directory will be referenced from the master script as: import os ... sumo_dir= top_dir+’sumo/’ if not os.path.exists(sumo_dir): os.makedirs(sumo_dir) where the top_dir variable contains the location of the project tree directory in the local file system and needs to be set by the user at the beginning of the master script.

Note While almost all user-driven parameters are provided in the configuration script, we need to modify the master script (the one loaded into CityEngine) to provide this top_dir so that the CE-based python engine knows where to look for the input scripts.

The project directory (after creating the sumo directory) is layed out as:

assets location for external data used to build the CityEngine scene (3D models that are not procedurally built, texture images, etc. . . ) data directory for arbitrary data of use in scene building — we will use it for storing the OSM street maps images standard output directory for screen snapshots CityEngine/SUMO Scene Construction Manual 18 / 82

maps storage for images that are imported as layers into CityEngine (the height map, road classification map, etc. . . ) models output directory where the street and building geometry files will be exported to rules files containing the CG language rules for building procedural scene elements scenes one or more project files containing scene states scripts Python scripts that are used from within CityEngine; we also use this directory to store modules to be imported sumo our created directory that will store the SUMO output generated from the CityEngine street network

CityEngine also creates a special directory, ce.lib, that we will modify (it should be located in the default project location, determined at install and parallel to the user-created project).

2.3.1 Visual guide

Adding a folder through the CityEngine interface. Adding a folder can be done using normal operating system tools as well. In that case File > Refresh Workspace should be selected from the menu to display the changes in the CE interface. CityEngine/SUMO Scene Construction Manual 19 / 82

2.4 Create a new Scene in CityEngine

Action Item(s): Create a new scene

A new scene is created within a project by selecting File > New... from the CityEngine Menu and selecting CityEngine scene from the list of wizards. You will have the opportunity to select a name for the new scene and its location (use the default +scenes* directory within the project that was created). It is possible to have many scenes for a single project and this is a useful way to share data between different versions of a particular location. You also have the option of setting the coordinate system for the scene at this point. Since the interface for doing this can be rather cumbersome, you can just leave this blank for now and we’ll just automatically set it when importing the OSM data later on (under most circumstances, you’ll want to use the OSM coordinate system for all elements of the scene anyways).

Important Unless you have a reason to manually set the coordinate system by hand, just leave the Coordinate Sytem entry blank for now

You should now see an empty scene in the viewport with a default grid.

2.4.1 Visual guide

Dialogs used in this section: CityEngine/SUMO Scene Construction Manual 20 / 82 CityEngine/SUMO Scene Construction Manual 21 / 82

2.5 Prepare the OSM Graph Layer

Action Item(s): Obtain and edit (optional) an OSM data set; Place OSM file into the data directory

The easiest way to build a fully attributed and logical road network is to import external data from real world locations. Open Street Map (OSM) hosts a free, worldwide map created by its users and is supported directly by CityEngine (SUMO supports importing OSM data as well, but due to differences in importation policies we import into CE and then manually export to a format that can be digested by SUMO with minimal changes). The website provides information about how to download the OSM data, but the general idea is to provide the geodetic locations of the corner points (either by a bounding box selection or by directly inputting the corners).

Note The type of data useful for scene construction (and necessary for input into CityEngine) is contained in the "OpenStreetMap XML Data" output option

The following figure shows part of an OSM file visualized in JOSM (a native OSM editor). CityEngine will use the road network (locations, number of lanes, etc. . . ) as the basis for synthesizing road geometry and generating the network that will be passed to SUMO for traffic modeling. CityEngine/SUMO Scene Construction Manual 22 / 82

Figure 2.1: OSM data visualized in JOSM

Aside from visualizing and inspecting the OSM data from JOSM, it can also be used to modify, add or remove tags from the map itself.

Important JOSM will ask you to upload any changes you make to the OSM file to the community of users before exitting. Please do not do this unless you are certain the changes are representative of the real world locations.

CityEngine can automatically convert all OSM tags to segment and node attributes, but only a small subset of tags are relevent to constructing the street network. These are:

2.5.1 For segments/edges (ways in OSM)

• highway tags (required - indicates the type of street)

– motorway – motorway_link – trunk – trunk_link – primary – primary_link – secondary – tertiary – tertiary_link – unclassified – residential – living_street – service – unsurfaced

• lanes (optional - full number or lanes in both directions or in one, if oneway) • oneway (optional - indicates that the street is oneway "yes"/"no") CityEngine/SUMO Scene Construction Manual 23 / 82

• maxspeed (optional - maximum speed in mph)

Note The concept of lanes is different between OSM and SUMO. In OSM the lanes tag indicates the total number of lanes along a road (in both directions), while in SUMO, lanes are given for a single direction only. Since we will be exporting the built street network to SUMO, we choose the SUMO convention (OSM lanes are automatically converted in the scripts as necessary). There is also a discrepancy between the speed in OSM and SUMO (mph vs m/s) and tags are automatically converted as needed.

In the OSM XML file these tags appear as k/v (key/value) pairs:

Note Each of the highway tags have their own default values for "lanes" and "maxspeed" (defined in the user configuration script below). The values in the OSM file will override the default values if provided.

2.5.2 For nodes/intersections (nodes in OSM)

• highway tags (indicates the type of intersection)

– traffic_signals (optional - indicates traffic lights at the intersection) – stop (optional - indicates stop signs at the intersection)

As with the non-highway tags above, the node tags can be used to override the default behavior of the road types.

Important The tags listed (with the exception of the way highway tag) are completely optional and should only be added (or kept) if the user desires to override the default characteristics of the road type.

Normally, importing the OSM data into CityEngine gives the user the option of selecting only those tags that they wish to map to CE attributes. However, the script engine version of the import does not support choosing specific tags (the OSM import options object has not been fully impolemented and the "interactive mode" alternative ignores any selections made by the user). Instead, the desired tags are listed in the configuration file and anything else is automatically deleted during initialization. Normal OSM maps usually have between ten and a hundred tags per way/node before we add our own so this cleanup is an important step. Once the OSM file is prepared it should be placed into the data subdirectory of the project tree. CityEngine/SUMO Scene Construction Manual 24 / 82

2.5.3 Visual guide

We’ll use a small section of a city grid as a running example for the Visual guide. It is shown below, visualized in JOSM (Potlatch2 style).

2.6 Overwrite CE OSM import rules

Action Item(s): Backup and edit ce.lib; Restart CityEngine

The special directory, ce.lib mentioned above, contains the rules used during the OSM importation process ("osm.ceattr"). Specif- ically, the rules are used to define a number of special attributes:

streetWidth the width used for the street segment being imported [m] sidewalkWidthLeft the width of the sidewalk (area starting with the curb) to the left of the street segment [m] sidewalkWidthRight same for the right of the street segment [m] precision a value in the range [0:1] defining the sampling precision of the bezier curve connecting street nodes minArcRadius controls the curvature around corners [m]

The CityEngine documentation can be consulted for more details. We choose to replace the default rules for OSM importation for two reasons. First, we want to drive the streetWidth parameter with a combination of class-based and mapped properties, neither of which are accessible during import. Second, minimizing the amount of curvature (Bezier curves) that CityEngine uses facilitates exportation to SUMO. CityEngine/SUMO Scene Construction Manual 25 / 82

Warning Before making any modifications to "osm.ceattr", make a backup copy of the original file

The replacement rules should be placed in the scripts subdirectory of ce.lib, replacing the file "osm.ceattr". The entire file should look like: #2012.1

//------// internal vars for the initial graph(set to preserve graph) attr streetWidth = 0.0 attr sidewalkWidthLeft=0 attr sidewalkWidthRight=0 attr precision=0 attr minArcRadius=0

Important The streetWidth is set to zero to force the vertexes of the blocks (the container shape of lots) generated by CityEngine to coincide with the nodes of the street network. This allows for finding neighboring blocks quickly and accurately regardless of orientation and attributing the streets with this information (CityEngine does not provide any way to relate roads and blocks/lots otherwise and this information is necessary for things like driveways). Without this step, an expensive distance calculation would need to be done for each check.

CityEngine will have to be restarted at this point in order for the changes to go into effect.

2.6.1 Visual guide

While not yet available, the "osm.ceattr" file in use can be visualized once the OSM data has been imported by selecting the network from the scene navigator and using the inspector. This is shown below, for the example OSM network that will be imported later: CityEngine/SUMO Scene Construction Manual 26 / 82

Important This view of the "osm.ceattr" is not yet available! Once the OSM file is imported the rules file can be verified.

2.7 Setup configuration file

Action Item(s): Place a copy of the configuration script in the scripts directory; Modify the user configuration script as needed

The configuraton script cesumo_config.py contains all of the user driven data necessary to run the initialization script as well as the other scene-building scripts in CityEngine. There are two basic types of information that are provided in this script. First, the user can set input filename information as well as some default values used to build the scene. Second, the user can modify a set of scene classification schemes that are used to modify the properties of the objects in the scene, either through their position (via a map lookup) or by their type (a tagged attribute). These two sets of information (those relevant to intialization) are described below.

2.7.1 Initialization Variables

ox, oy This is the origin of the local coordinate system along the x and z-axis in the scene coordinate system (usually UTM). All positions will be reported relative to this origin and maps are anchored relative to this point

Important CityEngine uses the X/Z axes for the horizontal coordinate system (+Y is up). The y used here references a strictly 2D coordinate system.

bbminx, bbminy, bbmaxx, bbmaxy These values define a bounding box surrounding the scene that the user desires to model. Any nodes or edges outside of CityEngine/SUMO Scene Construction Manual 27 / 82

this box will be removed from the scene. The coordinates are given in the scene coordinate system (e.g. UTM) but again the X/Y convention is used. elvation_map_filename This is a string holding the name of the image to be used as the elevation map. The filename should be given relative to the scene directory and, if the maps are stored in the "maps" subdirectory, should start with "maps/" class_map_filename Same as the elevation map filename, but this time the image should contain regional classification information osm_network_filename The OSM data to be imported (the XML file should have an ".osm" extension). The filename should also be prepended with the proper subdirectory ("data/") keep_tags This is a set of OSM tags that should not be removed from imported objects. Assuming that OSM is allowed to override road type properties, this should consist of ["highway","maxspeed","lanes","oneway"] and minimally of ["highway"] default_lane_width This is the base width (in meters) used for each lane in a road. It is suggested that the road classes (below) base their own widths off of this. 3.5 meters (about 12ft) is supplied as a default.

2.7.2 Class Mappings

The region class taxonomy describes different types of areas (areas with different lot sizes/content, different types of sidewalk- s/verges, etc..) to be found in the scene. The locations of these regions are communicated to the scripts by providing a grayscale class map (filename provided as a variable, see above). A fixed number of pixel values are associated with specific regions. The mapping from pixel value to region type is somewhat arbitrary, but follows the general scheme of white for densely populated areas and black for unpopulated areas. These associations are, by default:

pixel value region class description 250 urban_center center of a densely populated urban region (skyscrapers, financial buildings, highrises, etc. . . ) 225 urban_heavy densely packed mixed-use urban region with minimal greenspace or off-street parking areas (aside from full garages) 200 urban_light less densely packed mixed-use urban region allowing for some off-street parking and greenspace 175 industrial large industrial buildings (with stacks, converters, etc..) and large parking areas 150 commercial large box stores with large parking areas and strip malls 125 suburban_hi high income, exclusively residential areas with large lots as well as greenspace, larger verges and sidewalks 100 suburban_md small to mid-size house lots and larger lots with condomonium/apartments complexes and greenspace CityEngine/SUMO Scene Construction Manual 28 / 82

pixel value region class description 75 suburban_lo small house lots and apartments, patchy sidewalks/verges 50 rural large house lots bordering forested areas, lack of sidewalks/verges 25 agricultural very large lots, larger buildings (barns/silos), lack of sidewalks/verges 0 park very large lots, internal paths, no buildings or other features

Important The region classes are convenient definitions to allow the variations in the scene to be described easily. A user can modify the pixel value mapping and can provide additional classifications, but only if the appropriate property objects are defined (see the next section).

2.7.3 Property Objects

Property objects are abstract containers for related properties that can be used generically in the scripts yet be tailored to specific classes obtained from the current position in the map or the particular type of a scene element. For roads, two objects are defined. First is a RoadType type that is implemented as a simple Class in Python and sets up some basic properties by using the highway tag associated with edges (e.g. "residential", "tertiary", "motorway", etc..). The properties defined by the RoadType type object are given below:

property description priority a number representing the priority of this road type; at intersections of roads of different types with no signage or lights, a lower priority yields to a higher one maxspeed the maximum speed (of a typical driver, not the speed limit) given in m/s if not overriden by the OSM tag lanes the default number of lanes (in a single direction) if not overriden by the OSM tag primary_int the intersection type to use with roads of the same type ["allway_stop", "traffic_light", "priority_stop"] secondary_int the intersection type to use with intersecting roads of lesser priority has_sidewalks flag for the possibility of sidewalks/verges (also determined by region class) has_driveways flag for the possibility of driveways (also determined by region class)

The configuration script has road objects implemented for each available highway tag and stored in a dictionary called "roads" by the tag value so they can easily be looked up by the scripts. The second type of road object is called RoadClass and it describes the general properties used to build physical roads across road types. The RoadClass object is implemented as a Python namedtuple so that a default object can be setup and specific properties can be simply replaced by name when defining objects for specific regions without having to redefine the entire set of properties. These properties are: CityEngine/SUMO Scene Construction Manual 29 / 82

property description has_lines flag for painted lines [True/False] lane_width = width of lanes [m] shoulder_width = width of the shoulder in [m] gutter_width = width of the gutter in [m] curb_height = height of the curb in [m] curb_width = width of the curb in [m] verge_width = width of the verge in [m] verge_type = type of verge [asphalt, concrete, sidewalk_width = width of the sidewalk in [m] dirt, grass, trees] sidewalk_type = type of sidewalk parking_length = length of a spot [m] (zero [asphalt,concrete,dirt] indicates no parking) driveway_spacing = space between driveway_smallest_width = smallest width of driveways/entrances [m] (zero indicates no driveways/entrances [m] (actual width might break in curb) be randomly larger)

Note All width/heights can be set to zero (except lane_with) to eliminate modeling that part of the road.

2.7.4 Visual guide

While its possible to edit Python script files from within CityEngine, it can be easier to use an external text editor to do so.

2.8 Load the scripts into CityEngine CityEngine/SUMO Scene Construction Manual 30 / 82

Action Item(s): Copy the master and initialization scripts to the scripts directory; Set the top_dir in the master script; Load the master script into the CE interface and run it

The master script is used to drive both the initialization (which occurs if no scene elements are selected) and scene construction (covered elsewhere). It should be copied to the scripts directory and then modified to have the variable top_dir point the the project directory. Some additional scripts are required as well and should be copied to the same directory. The scripts needed for initialization are:

"build_osm_streets.py" master script (top_dir should be modified) "cesumo_config.py" user configuration script (filenames should be modified) "cesumo_initialize.py" core initialization script "cesumo_image_sampler.py" class maps sampler

The master script now needs to be loaded into the CE interface which can be done through Scripts > Add Script.... Once loaded, the master script can be run from this same menu or by using the shortcut provided.

Important The Console window in CityEngine will contain any output from the scripts describing what is being done during each step. This is also the location of any messages regarding errors when running the scripts (in addition to a debug dialog provided by CityEngine). To make sure that you can see this window while the scripts are running, make sure that its visible before starting the initialization scripts.

Make sure that no scene elements are selected and run the master script from the Scripts menu item, which will begin the scripted portion of the initialization process.

2.8.1 Visual guide

Once placed in the scripts directory, the master script is added directly to the CityEngine interface: CityEngine/SUMO Scene Construction Manual 31 / 82

2.9 Clear existing scene and maps (script)

Action Item(s): Actions occur as part of the script

Before importing the OSM file and creating the new network, it is desirable to clear any existing layers that were added previously by this script. To this end, layers loaded during initialization are labeled with the name "osm graph", the class map as "class map" and the elevation map as "elevation map". During the clear phase these labels are searched for in the scene and deleted.

2.10 Import OSM street map (script)

Action Item(s): Actions occur as part of the script

Due to scripting limitations the entire OSM file must be imported and all tags mapped to attributes in the network. After this process is complete, the network is "cleaned" by removing objects outside of the bounding box and tags not in the keep_tags CityEngine/SUMO Scene Construction Manual 32 / 82

user option

Warning The import setting classes have not yet been fully implemented in CityEngine (as of 2012.1). Therefore it is not possible to efficiently automate the process of importing an OSM street map without requiring specific formatting of the OSM file.

Warning CityEngine (2012.1) will ignore tag selections made during a (scripted) interactive importation process and will instead map all OSM tags.

Warning CityEngine (2012.1) occasionally re-maps tags upon import (e.g. certain highway::tertiary tags have been seen mapped to attribute highway="pedestrian"). It is unknown why this occurs or how it is triggered and there is no known workaround aside from editing the CE scene by hand.

2.11 Assign properties to edges and nodes (script)

Action Item(s): Actions occur as part of the script

The only connection between the three basic graph objects (nodes, edges, and blocks) in the CE scripting environment is the ability to obtain the two end nodes associated is an edge. Because we need to effectively walk through streets (for SUMO exportation and other scripting processes) we need to now go through and figure out which edges are connected to each node and store this information. We do a similar attribution for the block-edge connections, this time searching the blocks for vertexes that are coincident with the end nodes of segments. Additionally, during this process we label the types of intersection (from the properties defined above) and the widths of the streets and sidewalks. Finally, CityEngine’s Cleanup graph. . . routine is called to make sure that all nodes and edges are connected appropriately.

2.11.1 Visual guide

As the scripts progress you will see messages from the scripts describing what is happening in the Console window: CityEngine/SUMO Scene Construction Manual 33 / 82

2.12 Restart CityEngine

Action Item(s): Save the CityEngine scene; Restart CityEngine

Due to apparent limitations of the scripting engine, the scene must be saved and CityEngine must be restarted before any further work can be done.

Important After running the initialization script, it is necessary (version 2012.1) to save the scene, quit CityEngine, and restart CityEngine (the scene should be loaded automatically). This is due to the fact that the shapes will only be partially loaded after the script runs and be locked in whatever form they are in. After restarting (and re-loading the scene) the shapes will be fully generated. There is no known reason for this behavior.

We now have a network that has been cleaned of unnecessary information, has been updated with new attributes and fitted with shapes based on those attributes. We are now ready to generate a SUMO network and to build geometry on our shapes.

2.12.1 Visual guide

At the end of the initialization script you should see a network that looks unfinished (shapes are partially defined and the graph has a number of red lines in it). By saving and restarting CityEngine, this problem is fixed: CityEngine/SUMO Scene Construction Manual 34 / 82 CityEngine/SUMO Scene Construction Manual 35 / 82

Chapter 3

Exportation to SUMO

While both SUMO and CityEngine have the ability to convert OSM to their own network formats, these two processes end up being slightly different. CityEngine is focused on using the OSM data to build a 3D construction of streets, sidewalks and building lots that have a physical (if virtual) presence. SUMO, on the other hand, works very well in a 2D, vectorized world in which vehicle flows can be represented in isolation. These two different goals result in two different interpretations of the input data, making it difficult, if not impossible, to match the vehicle positions predicted by SUMO to the physical models of streets generated by CityEngine. Instead of trying to force these two independent processes to match, we take the approach of developing the network as much as possible in CityEngine and then gathering the information relevant to SUMO from the CityEngine network and exporting that information as directly as possible into SUMO. That direct link takes the form of translating the nodes and segments in CityEngine to a set of nodes and edges that we can translate into a SUMO network. Because CityEngine does not normally need a lot of the information that we require to write out the SUMO input files, it is necessary to generate additional connections between scene elements and provide additional attributes representing information that is useful to SUMO. Most of this information is generated in the initialization phase (accomplished in a separate module of this manual). Once that data is in place, exporting the SUMO network is a matter of walking through the scene (or part of it) and writing out nodes and edges as required.

3.1 Workflow

• Initialize the scene • Setup the output filenames • Select the area of the scene to export • Walk through all nodes and edges in the scene

3.2 Initialize the scene

During the initialization process, all the directories are setup, OSM data is imported and the scene elements are attributed based on the user configuration script. The initialization phase creates a sumo folder in the ’top_dir" defined in the master script. This is where the exported SUMO files will be written. All of the attributes that are relevant to the exportation process were assigned to the nodes and segments in CityEngine based on the input OSM data and the user-defined road types and region classes (see the initialization documentation for details). Primarily, we need to know how nodes and segments are connected and basic properties such as the number of lanes. The exact attributes we will use are: Node attributes CityEngine/SUMO Scene Construction Manual 36 / 82

attribute description edges a comma separated list of edges that are connected to this node (edges are identified by their name, which was assigned during initialization) type a simple description of what this node represents; nodes can be connects (a sample point along a single road), intersections (where multiple roads meet), merges (points at which oneway roads become two way roads) or ends (dead end markers)

Edge attributes

attribute description oneway flag indicating if the road is oneway only ["yes"/"no"] lanes the number of lanes (in one direction) for this road maxspeed the maximum speed along the road [m/s]

Warning While the initialization process defines the needed attributes for every node and segment, occasionally some of the objects will end up not having the needed attribute. These rare cases (especially for very large, complex scenes) means that it is important to check for the validity of retrieved attributes (testing whether or not they are equal to None)

3.3 Setup the output filenames

Very little of the exportation process relies directly on user inputs, but the root name of the output files is set in the configuration script (the same configuration script as was used for initialization). This variable is labeled sumo_root in the configuration and the output files will have names ".nod.xml" and ".edg.xml" for the nodes and edges, respectively. Additionally, the origin of the local coordinate system (discussed in the initialization document) is used to translate global coordinates in CityEngine to local coordinates in the exoported SUMO files.

3.4 Select the area of the scene to export

Before the actual script that does the exportation process is called, it is necessary to select the region of the scene to be exported. This can be done simply through the CityEngine interface, either by selecting the whole scene or a portion of it.

Important The bounding box selector in CityEngine has to modes of operation. If the box is drawn from upper left to lower right, then only scene elements fully within the bounding box are included in the selection. If the box is drawn from the lower right to upper left then any scene element that intersects the box is included in the selection.

Warning If selecting via a CityEngine viewport, make sure that the graph networks are visible (other scene element types can be selected as well, but they will be ignored)

The exportation process itself is the started by running the master script (when a selection is made, no initialization is done) CityEngine/SUMO Scene Construction Manual 37 / 82

3.5 Walk through all nodes and edges in the scene

The exportation process itself is a matter of walking through the (non-connect) nodes in the scene and then walking through each connected edge. Each path between non-connect nodes only needs to be walked once so we add a simple bookkeeping attribute to the nodes to keep track of what we have finished as we go through. The output data formats are very simple XML documents. The first contains the nodes in the network (the ".nod.xml" file) and is structured like:

...

Each non-connect node in CityEngine maps directly to a node entry in the output file. The XML attributes are as follows:

attribute description id this is the name of the node in CityEngine; the number at the end is the OSM ID from the original file (this is a useful value to use for cross-referencing OSM, CityEngine and SUMO data) x the position along the x-axis in the local coordinate system (measured in meters from the user supplied origin); this corresponds to the x-axis in CityEngine y the position along the x-axis in the local coordinate system (measured in meters from the user supplied origin); this corresponds to the z-axis in CityEngine type the type of intersection (from the node attribute of the same name)

Note Oneway merges (where two oneways become a twoway road and vice versa) are modeled as nodes but are given the unreg- ulated type to make sure that there is no stopping at the merge.

The final joinExclude entry is a list of nodes that should be excluded from junction joining by the SUMO tools (normally a very important step to simplify complex intersections). This is primarily used for marking dead end nodes to ensure they are not combined with the nearest intersection. The edges are written out similarly to the ".edg.xml" file. The format of that document looks like:

...

CityEngine/SUMO Scene Construction Manual 38 / 82

The XML attributes for edge entries are:

attribute description id this is the name of the edge in CityEngine, which we assigned to an index in the initialization process, plus an a or b; because twoway streets are represented in these SUMO inputs as separate edges, the a and b are used to differentiate those directions from the node at which the edge starts (corresponds to an id in the nodes file); note that directionality matters here — cars flow from the "from" node to the "to" node to the node at which the edge ends (corresponds to an id in the nodes file) numLanes the number of lanes in the direction of the edge speed the maximum speed along the edge [m/s] shape this is a list of 2D points that the road passes through; the shape list is only necessary when the road is not straight

Warning According to the SUMO manual shapes are only supposed to be internal points (i.e. the redundant endpoints are not supposed to be included). However, there appears to be a bug where shapes that are heavily sampled on one side but not the other end up removing one of the end nodes. To workaround this situation we always write out the end nodes whenever a shape is output.

Important The only way to consistently get directionality out of CityEngine is to look at the vertices of edges (the order corresponds to the original OSM order). This is very important for determining the direction of oneway streets. CityEngine/SUMO Scene Construction Manual 39 / 82

Chapter 4

Generating Vehicle Tracks with SUMO

The goal of this document is to explain how the Simulation of Urban Mobility (SUMO) software can be used to compute the location of vehicles as a function of time (e.g. a traffic pattern) for a DIRSIG simulation. In general, the process can be broken down into a series of steps:

• Create/Import the road network for SUMO • Populating the road network with a traffic pattern • Running the SUMO simulation • Exporting the SUMO generated 2D vehicle tracks to 3D DIRSIG dynamic instance descriptions • Associating those dynamic instances with geometric vehicles

Regarding the frequency which these tasks are performed, consider the following guidelines:

• A new road network is only created and imported into SUMO when a new scene is created for DIRSIG. If you are simulating a different traffic pattern with the same scene, you reuse the existing road network. • Populating the road network is performed any time you want to simulated a new traffic pattern. The road network can be reused, but the vehicles within the pattern may be different. • A new SUMO simulation is run whenever either the road network is updated (new or updated roads, new or updated traffic control devices, etc.) or when the traffic pattern is changed (different traffic routes, different numbers of vehicles, etc.). • The SUMO vehicle tracks are only exported when a new SUMO simulation is performed. If the same SUMO simulation is used in a DIRSIG simulation, then the vehicle track export step does not need to be performed again. • The association the vehicle geometry to imported vehicle tracks in DIRSIG only needs to be performed if a new SUMO simulation has been generated, or the associations of vehicle geometry to vehicle tracks are to be changed.

4.1 Traffic Simulation with SUMO

The SUMO model is traffic simulator that utilizes an agent-based modeling (ABM) approach, where each vehicle is an individual agent attempting to navigate a supplied road network. Each agent must obey traffic rules define in the road network (stop signs, traffic lights, etc.) and it must avoid other vehicle agents. If the roads are congested (for example due to intersection slow downs), then the traffic will slow as vehicles must wait for each other.

Note The goal of this section is not to replace the SUMO documentation. It is supposed to highlight techniques and approaches we have utilized. For a more complete explanation of how to use SUMO, please consult the SUMO documentation. CityEngine/SUMO Scene Construction Manual 40 / 82

The following is a list of important files utilized and/or created in the context of a SUMO simulation:

• The input "network" file describes the road network that the traffic will be modeled within. This network file contains descrip- tions of the roads, intersection, traffic control devices, etc. This XML file usually has a .net.xml file extension. • The input "route" file describes specific routes for vehicle within the road network. This XML file usually has a .rou.xml file extension.

• The input "configuration" file tells SUMO which road network file to use, which routes file to use, the output state dump file to create and the time window to simulate. This XML file usually has a .sumocfg file extension. • The output state "dump" file is produced by the SUMO simulation and contains the position of each vehicle as a function of time.

4.1.1 Getting the SUMO Software

The SUMO software is available on SourceForge . The software can be downloaded precompiled and packaged for common platforms or downloaded as source code and compiled. The software includes the core agent-based simulation tool, a graphical interface for visualizing a SUMO simulation and tools to help import road network data into the tool.

4.1.2 Importing the Road Network

The key input for the SUMO model is the road network that the traffic is navigating. This is a simple nodal network defined by "nodes" (waypoints along a road, intersections, etc.) and "edges" (connections between the nodes). Each "edge" can be attributed with properties including how many lanes are present, the speed limit, etc. The most common source of road network data we have used is OpenStreetMap (OSM). The SUMO software has many documented road network import methods and comes with tools to import road networks from common sources including Open Street Map (OSM). The following syntax shows how to use the netconvert tool to import a road network in OSM format (triggered by the --osm argument). netconvert--junctions.join\ --remove-edges.by-vclass rail_slow,rail_fast,cityrail,lightrail,bicycle,pedestrian\ --no-turnarounds--osm salt_lake_city.osm\ -o salt_lake_city.net.xml

Note The --remove-edges option can be used to ignore classes of edges in the OSM input data that are not roads. In this case, the list includes railroads, bike ways and pedestrian paths.

4.1.3 Generating Routes

SUMO can generate random routes for vehicles, but many times we will want to define specific routes. This section will attempt to outline that process.

4.1.4 Populating the Road Network

This section will discuss methods for populating the road network with traffic. This may include discussions of the following:

• Creating specific routes • Flood filling the network with random vehicles CityEngine/SUMO Scene Construction Manual 41 / 82

4.1.5 Running the SUMO Simulation

This section will explain the basics of running the SUMO simulation. Again, this is not supposed to replace the SUMO docs. The SUMO input "configuration" file is a simple XML file:

Note A list of route-files can be supplied using a semicolon (;) as the filename token separator. For example,

The simulation can be run from the command-line by supplying the SUMO program with the input configuration file: $ sumo salt_lake_city.sumocfg

4.1.6 SUMO Output Files

This section will briefly discuss which output files from SUMO we want and maybe a little bit about what they contain.

4.2 Exporting the SUMO Vehicle Tracks

The next major step is to convert the vehicle location data generated by SUMO into a format that can be ingested by DIRSIG. In addition to forming the vehicle track data into a format that DIRSIG already reads, this step accomplishes two additional and important tasks:

• The 2D vehicle location from SUMO is converted to a 3D location by determining the the Z height in the scene at the given 2D (XY) location. This allows the vehicles to follow the terrain in the DIRSIG scene.

• The 2D vehicle location from SUMO does not include a velocity vector to define the vehicle orientation. Therefore, the vehicle orientation must be determined by linearly interpolating between known locations. This allows the vehicles to always point in the direction they are traveling.

After the tool is run, the single output file generated by SUMO containing 2D vehicle locations will have been converted into N DIRSIG format .mov files that contain the 3D location and orientation for each individual vehicle in the SUMO simulation. CityEngine/SUMO Scene Construction Manual 42 / 82

4.2.1 The sumo2dirsig tool

This section will outline the sumo2dirsig tool which converts the SUMO output file into .mov files for each vehicle modeled. The following are required inputs:

SUMO Road Network File This is the XML file that defined the road network utilized in the SUMO simulation. This file is provided via the -- sumo_network option and usually has a .net.xml extension. SUMO Simulation Output File This is the XML "dump" file produced by the SUMO, which contains the vehicle locations as a function of time. This file is provided via the --sumo_netdump option and usually has a .dump extension. Scene GLIST File In order to convert the 2D SUMO coordinates to 3D DIRSIG locations the user must provide an input GLIST file that contains the basic geometry of the terrain and roads. This is the geometry which will be used to determine the correct Z altitude for each vehicle as a function of XY location. This file is provided via the --scene_glist option. Output GLIST File The output of the tool is a set of DIRSIG .mov files and a GLIST file with all of the dynamic instances for the exported vehicle tracks setup. This file is provided via the --output_glist option.

The following options are also available:

Scene Origin The output .mov files utilize the Scene ENU coordinate system and the SUMO road network is usually in the UTM coordinate system. This scene origin allows the user to incorporate the offset of the Scene ENU coordinate system within the UTM zone for the scene. This offset is provided by the --scene_origin option. MOV File Basename By default, the exported .mov files created by this tool are named sumo_ followed by the SUMO vehicle identifier. The --mov_basename option can be used to change the output file basename to something other than sumo_. MOV File Folder By default, the exported .mov files created by this tool are placed into the folder the program is run from. If the user wishes to change the output folder name (in order to export the .mov files directly into the desired location within the scene folder hierarchy), then the --mov_folder option can be specified. MOV File Path By default, the output .glist file will not manipulate the path to the .mov file specified in each entry. This can create a problem when the .mov files are not placed in the same folder as the .glist file. The -- mov_path option lets the user specify the path to the .mov files in the output .glist file. you

The tool has the following usage message: $ sumo2dirsig

DIRSIG4 Release: 4.6.0 (r12530) Build Date: Jun 12 2013 17:00:09 Copyright 2005-2013 Rochester Institute of Technology usage: sumo2dirsig[options] --sumo_network= --sumo_netdump= --scene_glist= --output_glist= where: The input SUMO road network file The input SUMO simulation status dump file The input GLIST file that contains the scene terrain The output GLIST file that will contain instances CityEngine/SUMO Scene Construction Manual 43 / 82

Options: --scene_origin= TheX,Y origin of the Scene ENU coordinate --mov_basename= An alternate base for the output mov files --mov_folder= An alternate folder for the output mov files --mov_path= The path to the MOV files used in the output GLIST

4.2.2 Performing the Export

Consider the following example syntax for exporting the vehicle tracks from the SUMO output "dump" file to a set of DIRSIG inputs. Note that the line continuation characters (\) have been introduced for clarity. The argument list can be supplied as a single line. $ sumo2dirsig--sumo_network=salt_lake_city.net.xml\ --sumo_netdump=salt_lake_city.dump\ --scene_origin=422469.1724,4516185.784 \ --scene_glist=roads.glist\ --output_glist=/home/dirsig/salt_lake_city/geometry/cars.glist\ --mov_folder=/home/dirsig/salt_lake_city/geometry/motion\ --mov_path=motion

The first two arguments (the SUMO road network and SUMO output dump file) should not require additional explanation. The --scene_origin supplied here is the same origin that is used throughout the scene construction process. For example, this same offset is used in CityEngine when the scene is exported from the UTM coordinate system inside CE to the Scene ENU coordinate system used in DIRSIG. The --scene_glist file points to a GLIST file that contains the terrain and the roadway geometry created by CityEngine. The --output_glist was given the absolute path the where we want the GLIST file to be placed, which is directly inside the scene folder hierarchy for this example. The --mov_folder option was used here to say that we want the output .mov files to be placed directly inside the scene folder hierarchy as well. The --mov_path option was used so that the GLIST file instances have the correct relative path to the .mov files.

Important The output GLIST file (cars.glist, in this example) only contains instance information at this time. The next step will be to describe what geometry is used with these instances.

This example shows one way of running the tool with regard to where the output GLIST and MOV files are placed. The user can choose to not include some of these options and output the files into the folder where the sumo2dirsig tool is run and relocate the files later.

4.3 Importing Vehicle Tracks

This section outlines the process for importing the vehicle tracks that were exported from SUMO and utilize a a pair of mech- anisms to simplify the assignment of various vehicle geometries and geometry attributions to those tracks. Specifically, this section will describe new mechanisms added to the GLIST file to facilitate rapid scene development based on (1) performing initial material attributions on base geometry objects without using Bulldozer or Blender, (2) introducing random variations in those initial material attributions on base geometry objects and (3) randomly selecting a base object (and material attribution set) for each instance in the scene. These mechanisms were introduced to significantly streamline the process of creating large populations of geometrically similar objects with defined sets of material variations. It should be noted that these mechanisms can be used separately or in combination.

Note These GLIST file features were added to DIRSIG in Release 4.6.

Note The GlistOptions1 demonstration focuses on these advanced GLIST file mechanisms. CityEngine/SUMO Scene Construction Manual 44 / 82

4.3.1 Initial Vehicle Attributes

In the past, the attribution of a geometry object (for example, a "car") in an Alias/Wavefront OBJ file required that the file be loaded into an interactive editor such as Bulldozer (distributed with DIRSIG) or Blender (an open-source geometry authoring tool). Although this workflow has worked for years, it required a man-in-the-loop to perform this key step in preparing geometry for use in DIRSIG. A new attribution mechanism has been added to DIRSIG that allows this process to be accomplished on-the-fly when the object is loaded into the simulation. The mechanism relies on making material assignments based on facet "groups" in an Alias/Wavefront OBJ file. A "group" is an optional mechanism in the OBJ file format to associate a group of facets (polygons). For example, the facets that compose the windshield of a car can be associated under a group named "windshield". Consider the following example from the vw_beetle.glist file:

The various elements associate the given material ID (specified via the id attribute) to a given group name. The first is important because it is applied to the special group name default, which means that any facets not associated with a group or any groups that are not specified later will be assigned this material ID (in this case, material ID #500). Each subsequent element specifies the material ID to be associated with facets in the specified group. Note that in this example, there are multiple groups (with slightly different names) that all get material ID #512 (the DIRSIG material describing a rubber tire).

How do you find the group names in an OBJ file? The groups in an OBJ file are defined by a block of facets preceded by a line starting with the "g" tag. For example, the following line: g wheel starts a group named "wheel" and all the facets following it will be associated with this group until a new group is defined.

Important The key benefit of this new material assignment mechanism is that it does not require graphical interaction with the model in a tool like Bulldozer or Blender. Furthermore, the material to group assignments could be automated at a later time if the OBJ group names are carefully managed by the object geometry author. CityEngine/SUMO Scene Construction Manual 45 / 82

4.3.2 Randomizing Vehicle Attributes

The last section described making initial material assignments to surfaces for a "base geometry" read in from an OBJ file. For a given "base geometry", it is many times desirable to have each instance reflect a different combination of material attributes for that "base geometry". The user must still provide a list of instances (either static or dynamic) but the model will choose which material attributes to apply to the "base geometry" for each instance based on a set of weightings. This mechanism can be used for a variety of applications, including:

• Quickly introduce material variations within a forest of trees of a given species. For example, the weightings for the materials could be setup so that some percentage of all the instances get assigned "sick tree" material properties. • Quickly populate a traffic pattern with material variants of the same "base geometry". For example, each "Honda Civic" could be randomly assigned a different paint color from a pool of allowable colors. The weightings of those materials combination can be manipulated to reflect observed distributions (for example, "white" is perhaps more common than "black").

The ability to randomly reassign material properties to each instance is performed via the element within an