# Metropolis Documentation

### Starting Metropolis:

There are two ways to run Metropolis: from the source distribution, or from the Windows Executable distribution. For information on how to get started from the source distribution, please refer to the file INSTALL.txt in the transims-metro directory.

If you are using the Windows distribution, simply double-click on the 'metropolis' executible icon, which can be found in the distribution folder.

### Setting up a project

Metropolis will open up with a blank window, known as the Project window. To begin visualizing results, you will have to import some TRANSIMS network data files into Metropolis. Select "Project Settings..." from the "Project" menu, and you will be presented with a dialog like the one below:

In the top section, add files from the road network you are using. At the very least, you will need to include both Link and Node data files; Shape and Pocket Lane files are optional, but recommended. The data files may be in any valid TRANSIMS file format: ASCII text, binary, or SQLite format. Both TRANSIMS version 3 and 4 files are recognized, and attribute name variants (as described in this document) and optional columns are allowed. For text or binary file formats, the accompanying '.def' file must be in the same directory; this is unneccesary for SQL.

In some instances, the files you have included above might contain several different instances of one of the network tables; this might occur if you include a compound SQLite file which contains both full regional, and simulator subarea networks, or if you just added all of the files in a directory to the project. In this case, you can disambiguate beween the alternatives using the popup menus in the "Tables" section:

Note that the menu shows you both the table name (for SQLite files - otherwise it is 'Default') and the file containing the table. In many cases, if there are no alternatives, you will not need to make any changes to this section.

The last section describes parameters which affect the shape of the road network. For best results, these parameters should match the settings passed into the various Arc* TRANSIMS tools. In particular, look at the ArcSnapshot.ctl file for the values of CENTER_ONEWAY_LINKS, and LANE_WIDTH, and use those values in this section.

Once you have imported all the files, click "OK". You can always edit these settings later.

### Visualizing the road network

Once you have set up the project, the next step is to add a road layer (N.B. - in future versions, I intend to eliminate the requirement for this step...). To do this, go to the "Project" menu, and choose "Roads" from the "Add Layer" submenu. It may take several seconds for the network to appear. Once it appears, an entry called "Roads 1" (or similar) should appear in the "Layers" section.

### Navigating the map

To move around the map, you use a combination of the mouse and arrow keys. You can move the map around by holding down the left mouse button and dragging the map around. You can rotate the map left and right by using the left and right arrow keys, and you can rotate the map up or down using the up or down arrow keys.

To zoom into the map, point the mouse to the area you would like to zoom in to, and use the mouse wheel to zoom in and out. Alternately, you can hold down the Shift key, and zoom in and out with the arrow keys.

Finally, if you double click on a spot on the map, the map will move so that that spot is centered, and the view will zoom in as well.

### Working with Snapshot files

Currently, Metropolis can not read snapshot data directly from the microsimulator; it must be run through ArcSnapshot first. There are a few requirements, however. First, in the ArcSnapshot.ctl file, you must specify:

- NEW_SNAPSHOT_FILE
- NEW_SNAPSHOT_FORMAT SQLITE3
- TIME_OF_DAY_FORMAT SECONDS

Once the snapshot file has been generated, you must add an index to it. It is fairly simple (though you must install the free, public domain sqlite3 executable from www.sqlite.org). From a command line, type:

`sqlite3 'CREATE INDEX ix_time ON Snapshot (TIME);'`

(Note the final semicolon, as it is very important and easy to miss.

Once a snapshot file has been processed in this way, it can be opened from within Metropolis by choosing the menu "Project"->"Add Layer"->"Snapshot Layer...". From the dialog box that appears, select "Choose" to choose the files. In case multiple snapshots are availible in the same file, you can select between them using the drop-down menu.

Now that a snapshot layer is available, we can navigate in time using the time bar at the bottom of the window:

You can set the current time by dragging the small indicator triangle to the desired time, or by entering the time (as a 24-hour time) in the text box to the right of the time bar. You can step forward and back by one second by using the "<" and ">" buttons, or the "," and "." keys on your keyboard. To start animating, click "Play". You can speed up or slow down the rate of play using the "Playback Speed" drop down menu to the far right of the play button. Negative play speeds will cause the animation to play in reverse.

### Adding Layers

To add layers besides the Road Net layer, choose an entry from the "Add Layers" submenu of the "Project" menu. As of the time of this writing, the possible layers include:

1. Box Layer - a dummy layer type used to test out new layer feature - will be removed.
2. Roads - The layer which displays the (static) road network.
3. Snapshot Layer - A layer which displays TRANSIMS microsimulator snapshot output
4. Shapefile - A preliminary ESRI Shapefile importer

### Working with Layers

Layers are drawn one atop the other, with the topmost layer in the layer list (upper-left hand section of the Project window), being drawn on top of all others. If you wish to rearrange the order in which layers get drawn, you can change their order in the layer list simply by dragging and dropping them where you would like them to appear. In addition, you can temporarily hide a layer by unchecking the box next to the layer. Futhermode, you can permanently remove a layer by hilighting it in the Layer list, and choosing "Remove Layer" from the Project menu.

### Layer Options

Each layer type has its own set of options, such as which attribute to color a link by in the Road layer, or which vehicles to show in a Snapshot layer. To edit these options, hilight the desired layer in the Layer list by clicking on it, and edit the options in the pane below.

### Layer Selection

To select items from a layer, first hilight it in the Layer list, then click with your right mouse button (control-click on a single-button Macintosh) to select items near a point. If you click and drag with the right mouse button, you can select all items in a rectangle. Holding the shift key while making a selection will extend the current selection.

As a special case, when selecting from the Roads layer, if you double-right click on a link, all links which share that name will be selected; thus it is a simple way to select an entire (named) road.

### Viewing Raw Info

To look at the raw tables underlying either the road network or the snapshot files (and soon, the ESRI Shapefile), you can bring up the Info window by choosing "Show Info" from the Project menu. The Info window shows the tabular data from the selected items in the currently hilighted layer.

### Contacting the author

You may contact the author at mahall@ncsa.illinois.edu. However, bug reports and critical feature requests should be entered into the project tracking database. You can find the tracker here:

http://sourceforge.net/tracker/?func=add&group_id=271785&atid=1155590

If Metropolis crashes, please submit a bug report, and attach the metropolis.log file that can be found in your metropolis folder. Windows users, please also include the metropolis.exe.log file as well.