ISAT User Guide Table of Contents

Who should use this document?

Anyone learning to use the NADS Interactive Scenario Authoring Tool (ISAT) to create scenarios for simulation, or who is interested in learning more about ISAT, ISAT elements or creating scenarios.

This user guide contains an introduction to the ISAT interface and how to use ISAT for various tasks during the creation of scenario files (also known as scenario authoring).

Example scenarios are provided to help illustrate concepts and tasks.

Conventions Used in this Document

This section contains abbreviations and conventions used as a shortened description to make spelling out every step using text unnecessary.

• BLI roadmap of the road network constructed using the Tile Mosaic Tool (TMT)
• CTRL or Ctrl Press the Control (Ctrl) key
• LMB Left mouse button
• DblClk Double click LMB
• MMB Middle mouse button (or scroll wheel as button)
• RMB Right mouse button

Words or phrases separated by >> indicate the word or phrase after >> is a child of the word or phrase preceding these characters. For example, to describe inserting a Traffic Source in ISAT from the Insert menu:

LMB Insert >> Coordinators >> Source >> LMB

NOTE: LMB is assumed for all menu items and may not be explicitly included

For commands entered into a DOS command line interface (CLI) window, characters within <> are intended as generic and should be replaced in your CLI with the actual file name, without the <> characters

<Enter> or (Enter) means to press the Enter key

Demonstration Scenarios

Demonstration scenario files have been provided to assist with learning how to use ISAT or the mechanics of specific actions or sequences of actions as examples and are not intended to be examples of completed scenarios unless identified as such.

These demo scenarios should not be considered actual scenarios, because they often lack supporting event logging (logstreams) as well as lacking any general context in terms of an overall scenario. The demo scenarios are intentionally simplistic and intended only to provide working examples of specific topics or actions.

Using Demo Scenarios

You may use the demo scenarios in ISAT for rehearsal or import and drive them on miniSim. Feel free to copy isat elements from the demo scenario files for use in your own scenarios as needed.

ISAT Overview & Interface Basics

This section contains interface documentation.

What is ISAT?

ISAT is the NADS Interactive Scenario Authoring Tool. ISAT is used to create simulation scenarios:

• 2D roadmap viewer
• Native file format: SCN (scenario.scn)

Requires a roadmap (BLI)

ISAT is NOT:

ISAT is not an object editor for creating or modifying 3D model objects, signs or roads.

miniSim Scenario Components Overview*

The following diagram illustrates the context of scenario authoring to provide an overview of related components.

• See the NADS miniSim user guide for miniSim simulator architecture details

TBC hyperlink to miniSim user guide & page ref

What is a Scenario?

A scenario defines everything that happens to the driver during a simulation.

Uses Actions and events to control the scenario; i.e., familiarization or restart drive, hazard detection & recognition or obstacle avoidance.

• Coupled to a roadmap (BLI)
• Scenario behaviors (responsible for executing scenarios) run at 30Hz

Anatomy of a Scenario

Scenarios typically have an initialization period followed by one or more events. A final event is the last event to occur before simulation is terminated.

Scenario events may contain one or more actions.

Scenario files are text files

• Can be edited by a text editor
• Portions of a scenario file can be generated programmatically:
  • ISAT ISC
  • Python
  • Shell script

This diagram shows the same scenario in ISAT, Emacs and Notepad++ text editors

Scenario Text File

Typically you can borrow elements from other scenario files by copying elements from one scenario and pasting them into another using a text editor or isat.

• If editing text,always check your edits in ISAT!
• Copy/Paste - delete paths from elements when the BLI is different between your source & destination BLI files:

ADO, roadpad, time to arrival, etc.

NOTE: A Traffic Source is not a portable element

Re-create it in ISAT or integrate it via text file

Text files are easy to examine in a command (shell) window.

Example search for time trigger in all scenario files: >grep TimeTrigger *.scn | grep ISAT | grep Name <Enter>

ISAT-Samples-Avoid.scn: Name "TimeTrigger1"

ISAT-Samples-Avoid.scn: Name "TimeTrigger2"

ISAT-Samples-Avoid.scn: Name "TimeTrigger3"

ISAT-Samples-Avoid.scn: Name "TimeTrigger1"

How to know what to look for in the scenario text file?

If you know what to look for in a scenario GREP can help you locate files containing that element or text quickly. However, what if you don't know what to look for? How would you find something when you don't have any idea what to look for?

• Create a new scenario
• Create the scenario element you need or are looking for:

ADO, Trigger/Coordinator

Give the element a unique name that you can search for in the text file

• Save the file, then edit the file in a text editor

Find the element name to see element syntax and parameters

TBC: Insert demonstration to find an expression trigger that relates to the speed of the ownship

What is a Scenario Event?

A scenario event is made from one or more actions created to present situational information to the external driver (research participant, trainee or simulation viewer) in some logical sequence;

force a vehicle to change speed

force a vehicle to brake, change lanes or turn

create or destroy scenario elements

Or:

change scenario elements:

initialize variables

change traffic signal state

etc.

Typical Scenario Events

• When the external driver approaches a specified location, cause oncoming traffic to veer into the drivers' lane to force a driver response
• As the external driver approaches a specified location, control ambient traffic to expose a vehicle stopped in the drivers' lane
• When the Time to Arrival (to a specified location) is 4 seconds, change the traffic signal to yellow and activate traffic stopped at the intersection (aka red light runner)

What is an Action?

Actions are specific commands that happen intentionally during a simulation:

• Time, situational, calculation or location based
• Caused by the external driver or some other action, hardware configuration or calculation

can create or delete objects, including other scenario elements

Typically actions are linked with other actions to create a scenario event as shown in the figure above.

Typical Actions

• Activate a scenario element
• Calculate something:

-Time to arrival (TTA)

-Time to collision (TTC)

-headway

• Check state of simulator or driver
• Create something (any scenario element)
• Destroy a scenario element
• End simulation (terminates the current drive)
• Play a sound
• Set a variable
• Set ADO vehicle speed (not the external driver)

ISAT Modes of Operation

• Edit
• Rehearsal
• DAQ playback
• Monitor Currently not available

Edit & Rehearsal Modes

• Edit

Creation of scenario

Link to or import portions of other scenario elements

• Rehearsal

Debug & test scenario

Simulates scenario using Behaviors and Vehicle Dynamics

Displays error messages from behaviors

NOTE: Rehearsal mode simulates the external driver; your simulation may not respond as expected:

i.e., if the driver was instructed to 'remain on the right lane', the simulated ownship may not stay in the desired lane

Some control of the simulated ownship is possible in ISAT using the Rehearsal Mode >> Advanced Options panel

speed, lane changes

Playback Mode

• Playback mode will play back a DAQ file from a miniSim drive
• Can search for specific conditions; i.e. CFS_Brake_Pedal_Force > 0.1
• Display data streams
• Graph collected data (limited to single cells)
• Record a video file of the playback

miniSim Scenario Components

ISAT Workspace

ISAT uses standard Windows[TM] graphical user interface conventions such as floating windows/panels/dialogs and dockable widgets.

The primary region where the road network and placed scenario elements are shown is known as the workspace. In the default layout, menus are located across the top of the interface. A region of icons is located beneath the menu region. Additional ISAT widgets may be positioned along the right or left edges of the interface.

In cases where ISAT needs to place an element, notice the cursor changes to an insert element cursor when you select from menus or icons.

The menu and icon widgets require a LMB to access and place into the workspace. For the ISAT elements widget, LMB and drag the element into the workspace.

ISAT Workspace Status Bar

The status bar contains useful information to the scenario author:

• position (continuously reports location of the cursor)

When configured, the status bar can also report:

• Name of scenario elements
• Roadway information:

road name

default speed limit

surface material code for location under the cursor

Status Bar Settings

The status bar settings can be accessed by choosing Edit >> Preferences >>Status Bar Settings. Use the existing codes to configure the status bar to display the desired information.

Measuring Distance in ISAT

To measure between two locations in ISAT:

• measurement is a linear measurement

Press & hold Ctrl and Shift keys, RMB on roadmap/BLI Position cursor over any other location

The measurement will update dynamically to reflect the distance from the cursor to the original 'pinned' location.

TBC link to video example

Scenario Authoring & miniSim Architecture Overview

This section contains scenario authoring documentation.

ISAT Elements

ISAT objects consist of two main types: the objects that can be inserted using ISAT, and the objects already present in a roadmap/BLI.

1. Objects placed in ISAT

These are objects defined in the Scenario Object Library (SOL2) and can be placed onto a roadmap by the scenario author:

• ADO
• DDO
• DDDO
• Static Object
• Virtual Object*
• Trigger/Coordinator

NOTE: Virtual objects are defined in the scenario, not in the SOL2.

2. Scenario world objects

These are objects that exist in the roadmap and have not been added by the scenario author. These objects may be either authorable (can be changed by the scenario author) or not (the object cannot be selected or changed in ISAT).

• Traffic Lights

Traffic lights are embedded into intersections for traffic control purposes.

The SOL2 contains a traffic light object that can be placed in ISAT; this is not a traffic light that controls traffic. It is a static object that only looks like a traffic light and can be controlled like any other static object.

There can be only one traffic light assigned to an intersection path. In some cases, i.e. on approach to a toll booth, multiple signals may be required visually.

• World objects vs. Scenario objects
• Coordinate systems
• Scenario initial conditions

ADO Scenario Object

• Vehicles that use vehicle dynamics and are AI controlled

Exceeding vehicle dynamics capability can cause issues

i.e., if ADO must exceed 10g's, the operation will likely fail

failure may cause ADO to disappear or be planted into the ground or fly into the air and freeze

• ADOs are 'aware' of other simulation entities

ADOs will attempt to change lanes to go around slow moving objects if this functionality is not disabled by the scenario author

ADOs may halt if they cannot move around a slow moving object or change lanes

• The scenario author sets default ADO behaviors; i.e.:

initial velocity

turn signals

headlights

lane changes, etc.

• RMB on ADO to specify path

TBC insert RMB ADO menu graphic

• Actions to modify ADO behavior

Set Dial

Set Button

instruct the ADO to maintain distance relative to the driver

maintain gap

cause the ADO to do something specific; i.e.:

enable brake light

accelerate or slow or stop

change lanes

DDO Scenario Object

• DDOs are 'dumb' objects

Do not obey traffic rules

DDOs follow a path blindly; also known as 'path follower'

Are not 'aware' of other entities within the simulation

No collision detection between the DDO and other scenario elements

• DDOs have two modes of operation:

1. Follow a path using kinematics
2. Free motion object

OpenDynamicsEngine library is used to model free motion objects dynamic behavior

bouncing/rolling ball

object falling off back of truck

DDDO Scenario Object

• Includes a target that affects DDO velocity/position along path
• DDDOs are 'dumb' objects

Do not obey traffic rules

DDDOs follow a path blindly; also known as 'path follower'

Are not 'aware' of other entities within the simulation

No collision detection between the DDO and other scenario elements

Free Motion Object

A free motion object is a non-vehicle DDO that:

• need to have realistic motion
• needs to interact with the environment

simple collision detection

objects that fall off vehicles

• static objects on road that start moving

rolling ball (i.e., on a hill or slope)

NOTE: vehicle dynamics do not apply to Free Motion Objects

Free motion objects have 3 modes:

1. coupled
2. relative trajectory
3. free motion

may require a mesh file to define a portion of the road surface to react against

Change object mode using Set Dial >> DDO >> Change Mode action TBC insert graphic

Static Object

• Model objects are defined within the SOL2

vehicles, animals, obstacles, signs

any model object defined in the SOL2 as a static object

• May contain multiple visual representations

options may be set as initial condition of the object, or changed during simulation using Set Dial action >> StaticObjManager

• Can use ADO models as static objects (as defined in the SOL2)
• Not intended to move (change position) during simulation

Traffic Signal

To control intersection traffic signals use Edit >> Traffic Light Manager

• To author traffic signal lights in sequence or on a route, the scenario author has to manage the signal states
• There is currently no way to automatically author a series of traffic light signals

Change A Traffic Light

Use the Set Dial >> Traffic Light action:

TBC insert traffic signal state table graphic

NOTE: The Traffic Light action does not change the signal directly. The action simply advances the traffic light state in the signal state table.

• If the specified target condition is not present in the signal state table, the traffic signal state does not change
• Static object traffic lights

These are objects, not true traffic signals and so they are not controlled with the Traffic Light manager.

Traffic Signal Types

The ISAT status bar reports Traffic Signal Type name. There are two signal types:

1. Standard signal - IDs may have no identifying information

Valid signal states: Red, Yellow, Green, Flashing Red, Flashing Yellow, OFF

1. Extended signal - The extended traffic signal type was developed to support dedicated traffic paths through intersections. These signals can be identified by the type code in their name:

NORM (normal)

uses standard signal states

LTRN (Left Turn)

signal states used should reflect signal type; i.e., Left Green, Left Yellow, etc.

RTRN (Right Turn)

signal states used should reflect signal type; i.e., Right Green, Right Yellow, etc.

STRT (Straight)

signal states used should reflect signal type; i.e., Straight Green, Straight Yellow, etc.

Traffic Signal Action

NOTE: Accessing the traffic signal action after it has been created can be problematic!

i.e., ISAT frequently crashes when accessing the traffic signal trigger actions

Solution: Isolate traffic signal action into some other trigger, i.e. in a Time Trigger that only contains the traffic signal action. If you have to make minor edits the scenario file can be edited as text in a text editor. Major edits may require re-creating the action from scratch, if ISAT cannot access the action.

Virtual Object

This object has a visual representation but does not exist as a 3D model in the simulated world

• 2D shape
• Overlay on screen of project into the scene
• supports animation (change of unique states)

A virtual object can be one of several predefined shapes or a custom image file

• Virtual objects will draw over scene elements during simulation
• Virtual objects do not render accurately during scenario rehearsal

Custom (icon) file virtual objects

Standard virtual object shape

Coordinators

Coordinators are used to control scenario elements:

• Intersection manager

Controls traffic within intersections

• Traffic Light Manager

Controls traffic light signal state (signal appearance)

• Triggers

Traffic Light trigger

Expression trigger

Roadpad trigger

Time to arrival trigger

Follow trigger

Triggers

All trigger types share the same Action types

• IF Then conditional
• Predicate: i.e., the activating agent

If predicate is TRUE, then do Action(s)

• Categorized by predicate type

Named element

Road (lane)

Nth vehicle on path only

Trigger Operation

One shot

Fire trigger once only

Debounce

Debounce is the interval between multiple trigger activations when predicate is TRUE and actions have completed execution

Controls the 'rate of fire' of the trigger

Debounce prevents unintentional repeat execution of the trigger actions

For example, a time trigger with a debounce of 0.96 seconds and actions that take 1 frame to complete will fire once per second.

Trigger General Settings

• Lifetime

How long the trigger is alive (active)

Default 0 means trigger lives unless the trigger is deleted

• Activation Delay

Time after the trigger is created when it becomes active

• Creation Radius

How close the external driver has to be to the trigger before it is created

Delete trigger when the external driver is no longer within the distance specified

• One shot

Fire the trigger only once

• Priority

Used with interdependent triggers to establish trigger priority:

i.e., a roadpad trigger sets a variable, and an expression trigger reacts to that variable. The roadpad trigger should have a 'high priority', the expression trigger should be set to 'Low priority'.

• Debounce

Time after firing the predicate remains inactive

Roadpad Trigger

A roadpad trigger (RPT) is defined on a segment of road or intersection by a path called a road pad (or pad).

The roadpad pad defines a geographic region where the trigger can be activated.

The trigger activates when the trigger predicate steps on the pad anywhere on the pad. It is not necessary for the trigger predicate to step on the pad at the beginning (start) of the pad.

• By Name Set

ISAT will prompt for existing scenario model object/s

• By Type Set

Type of object; i.e., External driver, ADO, etc.

• By Road

Filter trigger to a specific lane; i.e., predicate has to be on the roadpad and in target lane

Can be used to implement conditional trigger activation

An audio message to change lanes can be suppressed if the driver is already in the correct lane

TBC insert Road Trigger dialog graphic

Time to Arrival Trigger

The Time to Arrival Trigger (TTA) is similar to the Roadpad Trigger and adds a timer

Time to reach target point

Can use an expression to calculate time

Arrival time can take acceleration into account

Target point

The location used to measure vehicle distance

Time to Arrival Trigger example

A is the target point used in the trigger calculations

Follow Trigger

The Follow Trigger (FT) is another type of roadpad trigger

• Trigger activates when vehicle A is Distance X from vehicle B

Distance can be in feet or time

Both vehicles must be on roadpad;

very long roadpads are common with this trigger

Vehicles can include the External Driver

Expression takes priority over time field

TBC FT graphics

Additional Triggers

• Global Time (GTT)

Elapsed time from start of scenario

To use GTT as a timer, add an Activation Delay set to the desired elapsed time

• Expression Trigger (ET)

Execute actions if input expression evaluates to TRUE

• Traffic Light Trigger (TLT)

Execute actions when target traffic signal is set to target state;

when the traffic signal state matches the target state, execute actions

Scenario World Objects

TBC additional trigger graphics

Scenario Authoring Concepts

This section contains scenario authoring information.

Terminology & Documentation

This section contains terminology and references to related documentation. TBC vocabulary

Reporting ISAT & Scenario Issues

This section contains recommended procedures for reporting problems with ISAT or scenario authoring.

ISAT Reference Manual

The information provided in the user guide is intended to provide a jump start on the concepts and tools of scenario authoring using ISAT.

The reference manual for ISAT can be found here.