STISIM Drive - Scenario Definition Language (SDL)

Before you can begin designing your scenarios you must decide what information you will be presenting to the driver as they negotiate through the simulation run. Additionally, you must also consider the data that you would like to collect from the driver as they encounter the various pitfalls that you have built into your scenario. All of this is controlled by individual events that will be linked to one another in your events file. Therefore, to efficiently create an events file, the following steps should be followed.

  1. Decide what exactly you will be trying to accomplish using the simulator. This may sound trivial but its not. More time is wasted putting events into a simulation scenario and later taking them out because they are not needed then most people would expect.
  2. Decide what type of data that you will be collecting, such as response times, or vehicle positions and speeds. This is not always easy because as you collect data and monitor simulation runs you begin to see that other data might be better. You should at least have an idea about what kind of data to collect before starting. To help decide what data to collect, you should review the BSAV and RMSB events as well as the STISIM DATA FILE section.
  3. Before actually defining individual events, layout the roadway that will be used. There are several choices straight-aways, horizontal curves, vertical curves, and intersections, so decide on how the road will look and then place the events on the road accordingly.
  4. Specify the type of units that the events file will be using by placing the word "Metric" or "English" (do not include the quotes) as the first line in the file.
  5. Use this section of help to determine what events will be used and place them at their respective positions on the previously designed roadway.
  6. Create the individual events by specifying the various parameters associated with each event
  7. Check the scenario that you created by running it. You can drive it yourself or use the built in autopilot by setting the autopilot parameter in the STISIM Drive configuration. At this point make any adjustments that are needed, and try again.

To help you understand what an events file is and how the parameters work, we have included several example event files with the simulator. You should review these sample files (found in the Projects directory under the STISIM Drive directory, usually C:\STISIM\Projects) and drive them. You can also use them or parts of them in your own scenarios, or as a start to a scenario that you are creating.

Because the program requires 2 different files (configuration and project) in order to create a simulation run, you must be careful not to mix different units. Trying to use a metric project file with an English configuration file will produce some interesting results. This is generally noticeable right away because the roadway will be the wrong dimensions, however to help prevent this from happening we recommend that in the first line of your project file you include a units descriptor. By simply placing the word "Metric" or "English" as the first line of your project file, STISIM Drive will check this with the units you have specified in your configuration and will warn you if the two don't match. If no units descriptor is in the file, STISIM Drive will assume the project is in English units.

The events file has a floating file format, this means that each line of the file does not have the same number of parameters in them. The general format for each line of the file is:

ON DISTANCE,EVENT SPECIFIER,PARAMETER 1,...,PARAMETER N,COMMENTS

The ON DISTANCE parameter is the longitudinal distance down the road (since the start of the simulation run) that the driver has driven when the event will initially appear on the screen. When checking simulation scenarios, you may at times want to delete an event from the display, but not from your events file. To do this simply make the ON DISTANCE parameter be a negative value. This way you can delete the event from the screen without removing the entire line from your events file. To put the line back in, make the ON DISTANCE parameter be a positive value again.

The total number of events for any simulation run is limited to a total of 10000 individual events.. If you try to use more than this amount, the program will report an error.

The event specifiers, and the remaining parameters will now be discussed individually. Some of the parameters have physical units associated with them, for instance the ON DISTANCE is a length so it is measured in feet or meters. In this document, all of the physical units are specified in English units. If you will be running the simulation using metric units, simply use the metric equivalent of the units specified.

The comments parameter allows you to place a line in the file that gives a description of what you are trying to accomplish. We recommend that if you use the comment parameter, you never use a numeral as the first character. Some of the STISIM Drive events use a numeric value in this field for doing internal testing. Therefore, if you set the first character in the comments field to a numeric value, the simulation may give you strange results.

In the discussion of each of the events that are supported by STISIM Drive, there is an example that demonstrates a typical use of the event being discussed. You should use these examples as a guide when defining events of your own. With each example comes a description of what the event is trying to accomplish and what each of the parameters is. Additionally, after the discussion parameters, the parameter values that appear in the event syntax will generally be included in parenthesis so that you can reference their use to their position in the events syntax.

One final note about event parameters. There are numerous events that require you to specify physical distances in order to use the event. When these parameters are discussed in the documentation, they will call for either a longitudinal, lateral or vertical distance in the real world driving scene. Therefore before continuing, you should acquaint your self with the STISIM Drive axis system.

The events that are currently supported are:

A - Vehicle ahead of driver, approaching in the other lane
AO - Analog output
B - Blank the roadway display screen for x.xx seconds
BARL - Construction zone barrels
BLCK - Display blocks or rectangles on the display screen
BLDG - Display a building
BRK Activate the brake pedal
BSAV - Begin saving dynamic data for the output file
C - Add curvature to the roadway display
CAO - Continuous analog output
CSET - Set crash parameters
CT - Cross traffic in an intersection
CV - Control vehicle automatically
D - Diamond sign
DA - Add a divided attention symbol to the display
DI - Digital input event
DO - Digital output event
ES - End simulation run
ESAV - End saving dynamic data for the output file
FOG - Add a patch of fog to scene
I - Display a roadway intersection
IA - Display an intersection ahead sign
JBAR - Jersey barrier
L - Left diamond sign
LS - Change the speed limit
PB - Police officer shows up
PDE - Previously defined event
PE - Police officer goes away
PED - Pedestrian
PI - Performance index simulation
POLY - 2 dimensional polygons
PR - Play recording
Q - Rectangle sign
R - Right diamond sign
RMSB - Begin taking RMS data
RMSE - End taking RMS data
ROAD - Display a specific roadway

RSA - Change the current road surface attributes
RT - Reaction Time

S - Stop sign
SA - Display the signal ahead sign
SIGN - Display a roadway sign
SL - Display a traffic signal light
SOBJ - Add a static object
SPCW - Speed control warning
STCW - Steer control warning
T - Yield sign
TDO - Triggered digital output
TREE - Display trees on the side of the road
V - Vehicle ahead of driver in driver's lane
VC - Vertical curvature
WG - Wind gusts

It should be noted that several events that were available with the DOS based version of STISIM are currently not available with STISIM Drive. These events are the MS, OVAL, PED, TEXT, and W events. At some point in the near future we hope to add these events back into the program, but as of this release they are not available. We have made an effort to keep the events and their parameters the same between STISIM and STISIM Drive, however, in some cases parameters have changed or new parameters have been added. Therefore we recommend that you review each event because even old events have new functionality that makes them even better than before.

Included with the STISIM Drive program (in the C:\STISIM\Projects folder) are some sample event files (SAMPLE.EVT, STEERING.EVT, TERRAIN.EVT, etc.) . These, plus others, have been included so that you can see how many of the SDL events work. If you use these to test drive the simulator and then go back and look at the events and their parameters, you will have a much better feel for how the program works. These sample files are all specified in English units as are all of the parameter definitions that follow. If you will be designing your scenarios using metric units, simply use meters anywhere a parameter is defined with feet, and use kilometers instead of miles.

One final general note. Many STISIM Drive events require a file that contains additional information. STISIM Drive automatically defaults to the Projects (usually C:\STISIM\Projects) directory. Therefore, you will either need to store the files in the projects directory, or include the full path name with the file name. Otherwise STISIM Drive will not be able to find the file, causing an error message to be generated and the event to be ignored.