miniSim - User contributions [en]

File:ISAT Quick Start 2025.pdf

2025-02-21T17:27:12Z

Shawn Allen: Shawn Allen uploaded a new version of File:ISAT Quick Start 2025.pdf

File uploaded with MsUpload

File:ISAT Quick Start 2025.pdf

2025-02-21T15:23:40Z

Shawn Allen: File uploaded with MsUpload

File uploaded with MsUpload

ISAT Quick Start Guide

2025-02-21T15:22:18Z

Shawn Allen: /* updating file? */

This section contains the ISAT Quick Start Guide.

Note:
It is strongly recommended that users new to ISAT review this information and the ISAT User Guide to become familiar with the operation and use of ISAT and scenario development.

[[:File:ISAT_Quick_Start_2025.pdf]]

File:ISAT Quick Start 2023.pdf

2025-02-21T15:13:02Z

Shawn Allen: Shawn Allen uploaded a new version of File:ISAT Quick Start 2023.pdf

File uploaded with MsUpload

FAQ

2024-07-30T17:06:52Z

Shawn Allen: /* miniSim Documentation - add Scenario display text info from existing FAQ document by VJH*/

<div class="toccolours mw-collapsible mw-collapsed">
== miniSim Data Dictionary ==
The data dictionary is a compilation of the simulator data that is stored and available within the DAQ file after each drive.

[[:File:Cells-miniSim-20240715.pdf]]

Note:
miniSim users may extend the data dictionary by adding custom cells to the collect and schedule files:
* NadsMiniSim_x.x\data\NadsMiniSimCollect.general.txt
* NadsMiniSim_x.x\data\NadsMiniSim.cec

Typically new cells should be added into one of the SCNVIF sections. Use the same SCNVIF section for both files:

*cell 1 SCNVIF
*cell 7 SCNVIF
*cell 8 SCNVIF
*cell 9 SCNVIF

== miniSim Documentation ==
All miniSim simulators ship with a documentation folder located on the desktop. You can find miniSim and additional documentation within this folder.

===Editing scenario display text===

C:\NadsMiniSim_x.x\bin.x64\config\scenario_text.xml file.

A short segment of that file:

<?xml version="1.0" encoding="UTF-8" ?>
<NADS xmlns="http://www.nads-sc.uiowa.edu/XML/">
<MiniSim>
<Text>
<Location1>
<Font> arialbd.ttf </Font>
<FontSize> 45 </FontSize>
<AspectRatio> 1.0 </AspectRatio>
<RedIntensity> 0.95 </RedIntensity>
<GreenIntensity> 0.95 </GreenIntensity>
<BlueIntensity> 0.4 </BlueIntensity>
<AlphaIntensity> 0.95 </AlphaIntensity>
<BackgroundRedIntensity> 0.8 </BackgroundRedIntensity>
<BackgroundGreenIntensity> 0.8 </BackgroundGreenIntensity>
<BackgroundBlueIntensity> 0.8 </BackgroundBlueIntensity>
<BackgroundAlphaIntensity> 0.2 </BackgroundAlphaIntensity>
<HorizontalPosition> 0.0 </HorizontalPosition>
<VerticalPosition> 0.0 </VerticalPosition>
<Alignment> CENTER_CENTER </Alignment>
</Location1>
…

Anything between a pair of less-than and greater-than signs should not be changed, but the intervening text is editable; for example:
<DO_NOT_CHANGE> editable </DO_NOT_CHANGE>.

Editable content can be found between the <Location#> and </Location#> tags
(there will be a block for each of the 13 locations).

In particular, the HorizontalPosition and VerticalPosition settings will be of interest to you, probably the Alignment setting, as well.

Text positions are described in terms of coordinates which are normalized to fall between -0.5 and +0.5, regardless of device resolution, with (0, 0) being the center of the middle screen, positive x pointing right, and positive y pointing up.

For example, a HorizontalPosition of -0.25 and a VerticalPosition of +0.25 will put the text in the upper left quadrant of the screen.

The Alignment parameter sets the point within the block of text that snaps to the specified coordinate.
Valid choices are: LEFT_CENTER, CENTER_CENTER, RIGHT_CENTER, LEFT_TOP, CENTER_TOP, RIGHT_TOP, LEFT_BOTTOM, CENTER_BOTTOM, and RIGHT_BOTTOM.

For example, setting Alignment to LEFT_BOTTOM and then changing the HorizontalPosition of several locations to a common value and the VerticalPositions to an ascending series of values will give you a column layout.

== miniSim Hardware ==

=== Desktop and Viewport Settings ===
<div class="mw-collapsible-content">

Detailed information about the PC display layout and the miniSim viewport and channel configuration settings is available here:

[[:File:miniSim-Desktop_and_Viewport-Settings-v3_113022.pdf]]

[[#top|TOP]]
</div>
</div>

=== Q: My miniSim displays have changed. What happened, and how can I fix it? ===
<div class="mw-collapsible-content">

Windows has shown a tendency to re-enumerate the displays from time to time. The result is that the miniSim display layout/configuration becomes incorrect.

The relationship between the display layout and the viewport display settings in the miniSim Channel Configuration File (.ccf) no longer match.

To correct, check the following in this order:
# Displays are arranged from left to right: Matrox/Mosaic, Instrument Panel, Operator.(use mouse or arrow keys)
# The Matrox/Mosaic display must be designated as the ‘main’ or ‘primary’ in Windows. The task bar may move to this display when this is set, so drag the task bar and icons to the operator display
# Do not use the Matrox PowerDesk program to adjust the default locations for pop-up and application windows. This will cause many, many problems.
# The top edges of the display icons are aligned (use mouse or arrow keys)
# Reboot to make sure the configuration is stable.
# Check video and USB connections. If they are loose, it may cause windows to re number the displays, which can make things move around unpredictably.
# Open the correct Channel Configuration File (.ccf) in the \bin.x64 directory.

'''Note:''' there are several .ccf files in every system, and the ‘correct’ one is defined by the system settings in the ‘go.cmd’ file used to start miniSim.

See next section. The third number in the Channel header(s) should be equal to the number of the main display as reported by Windows in ‘Display Settings’ minus 1. Only 0, 1, 2 are generally valid for standard miniSim configurations (2 Channel, 3 displays).

:Channel 0 0 2 (Shear x2) (Twist x3) (Extends x4)
:0.000000 0.000000
:0.000000 0.000000 0.000000
:0.000000 0.000000 1.000000 1.000000
:6
:.
:.
:.
:Channel 1 0 2 (Shear x2) (Twist x3) (Extends x4)
:0.000000 0.000000
:0.000000 0.000000 0.000000
:1.000000 0.000000 2.000000 1.000000
:0 IP

[[#top|TOP]]
</div>

=== Q: What is the right Channel Configuration File for my miniSim? ===
<div class="mw-collapsible-content">

A. to determine the correct ccf file, examine the command file that launches miniSim.

The minisim is launched by running the correct go.cmd file in the '''NadsMiniSim_x.x.x\bin.x64''' folder.

Typically, there have been shortcuts created on the miniSim desktop that are used to run the appropriate ‘go’ scripts. There are often several go-scripts, this is usually to provide a way to launch the miniSim with or without various options (Video Capture, Advanced Automation, etc).

If you right-click on the shortcut icon and choose ‘edit’ you can edit the go.cmd script. A typical one looks like this:

:set MININADSCOMMMODE=PSEXEC
:set DYNA=car
:set NUMCHN='''2'''
:set INSTRUMENTS='''on'''
:set FORMAT='''wide'''
:set INSETVIEW=off
:set SIDEMIRRORS='''on'''
:set MININADSDAQ='''on'''

Based on these settings, the miniSim will read the following channel configuration file (.ccf) and use its contents for setting up the rendering channels and viewports. In this case, the miniSim will open this file:
'''\bin.x64\mininads_2ch.wide.sidemirrors.inst.ccf'''

This is the correct file to edit for this configuration. Remember to exit miniSim before making edits to the .ccf file.
'''If you make a change and see no effect, you may be editing the wrong file!'''

When the miniSim runs, it copies the .ccf file that pertains to the options selected in the go.cmd, and copies it to '''mininads_1ch.ccf''', which is the one that is loaded when miniSim is launched.

This means that the '''mininads_1ch.ccf''' has the same ‘Last Modified Date’ as the file you want to edit.

If you list the contents of the \bin.X64 folder by date, you will see something like this:

[[File:2022-11-30_15h03_56.png|400px]]

In this case, you will see that the '''mininads_2ch.wide.sidemirrors.inst.ccf''' is the file you want to edit, as it has the same last modified date as '''mininads_1ch.ccf'''.

For a desktop layout like this from Windows in ‘Display Settings’

[[File:2022-11-30_15h05_10.png|400px]]

This is a '''Two-Channel''' system, meaning that the front three displays on the Matrox/Mosaic are Channel 0, and the Instrument Panel display is Channel 1.

[[#top|TOP]]
</div>

=== Q: Where do I find data relating to the brake pedal force/position? ===
<div class="mw-collapsible-content">
A: The data you are seeking is represented by the '''CFS_Brake_Pedal_Force''' variable, which can be viewed either with ISAT or with Matlab during data reduction. The value ranges from 0 lbs. to 180 lbs., where 0 indicates no force (no pedal travel) and 180 indicates 180 pounds of force (full pedal travel).

If you see a variable named '''CFS_Brake_Pedal_Position''' you may ignore this as it is not currently being used.

[[#top|TOP]]
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: How can I adjust the brake pedal response? ===
<div class="mw-collapsible-content">

Information to adjust the brake pedal response is detailed in this document: [[:File:Adjust_Brake_Response_11302022.pdf]]

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: The tactile transducer, mounted under the cab, suddenly does not respond when the miniSim is running. ===
<div class="mw-collapsible-content">

Check the following:

1. Verify these connections first:
: a. The main stereo speakers should be plugged into the green audio port on the back of the PC using a ⅛" mini-jack.
: b. The Dayton D-30 amplifier should be plugged into the orange port on the back of the PC using a ⅛" mini-jack.
: c. The tactile transducer should be connected to the Dayton D-30 amplifier using the included speaker wire.

2. Note that the amplifier controls the volume of the tactile transducer and therefore must be plugged into a power source. If the amplifier is not plugged into power, this could be the reason the tactile transducer is not working.

3. Check the volume level of the amplifier. If it is set too low, the tactile transducer may '''appear''' to not be working. We suggest a minimum amplifier volume setting of 25% of full volume. A volume setting which is too high will be experienced as an unpleasant vibration and low-end rumble that does not resemble a real car.

4. Launch the Realtek audio manager from the Task Bar and select 5.1 audio. Then, disable the center and rear channels, leaving the front left and right speakers, and the subwoofer enabled.

5. Use the Realtek audio manager to test each of the speakers individually by clicking on each speaker icon. As you select a speaker, the speaker will sound.

Some motherboards have the sub/center channels switched. In this case, a ⅛" mini-jack to stereo RCA cable can be used.

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

== miniSim Operation ==
=== Q: Auto-start miniSim drive===
The miniSim simulator can be configured to start a drive automatically or not, depending on your project requirements.

This involves a '''''system level configuration change'''''. To run two projects simultaneously you will need to create a unique startup sequence for each project in order to use the correct configuration file.

Setting auto-start involves a setting in the hardware.xml file in use; note there are different configuration files present on all miniSim simulators within this folder:

miniSim_x.x\bin.x64\config

Please exit miniSim before editing any .xml file. You may want to backup these files prior to editing.

'''Enable auto-start'''

Change the string

<Sink device="SimulatorInterface" port="CIS_Auto_Ignition" ID="0" />

to

<Sink device="SimulatorInterface" port="CIS_Auto_Ignition" ID="1" />

To disable auto-start, set the value to 0.

=== Q: miniSim is not responding. ===
<div class="mw-collapsible-content">A: At times you may find that your miniSim PC or miniSim software has become unresponsive. We define appropriate steps for correcting unresponsive behavior on a miniSim PC under the following conditions:

* '''miniSim Software is Running but Will Not Load a Drive Scenario:'''
# Assuming the mouse is functioning, simply close and then restart the miniSim program.
# If the mouse is not functioning, use the keyboard to close and restart the miniSim program i.e. press Alt+Tab to select the minSim program and press Esc to close.
# This step will fix this unresponsive behavior most of the time.
* '''A miniSim Drive Has Been Selected but Will Not Start:'''
: Assuming the mouse is functioning, click on the Settings tab and verify all lines are green (ready mode). If one or more lines are red, simply wait for all to become green. If still not green after about 90 seconds, close and restart the miniSim software normally. This step will fix this unresponsive behavior most of the time.
* '''miniSim Software Stops Running:'''
# Assuming the mouse is functioning, simply close and then restart the miniSim program.
# If the mouse is not functioning, use the keyboard to close and restart miniSim program i.e. press Alt+Tab to select the minSim program and press Esc to close.
# If the miniSim software will not close, press Ctrl+Alt+Delete and open Task Manager. Within Task Manager, select the SimopServer program and close it. Restart miniSim.
# This process generally will recover miniSim from nearly any unresponsive state.
* '''miniSim PC Shuts Down Unexpectedly:'''
# Check for severe storms and possible power outages in your neighborhood.
# If you see smoke or smell something burning near the miniSim PC, carefully unplug the PC from the electrical outlet and fetch your fire extinguisher just in case. When immediate danger passes, consult a local hardware expert to examine your PC for possible electrical shorts, overheating or failure of critical systems such as motherboard, hard drive and etc. Contact NADS miniSim in the event hardware components need to be replaced. See contact information below.
* '''The miniSim PC Will Not Boot:'''
# On rare occasions your miniSim PC may not boot to Windows. It may halt the boot process just prior to launching Windows. If your miniSim PC has stopped the boot process before a Windows launch, it is okay to touch the reset button on the PC (the small button next to the power button). If your miniSim PC does not have a reset button, touch the power button lightly one time. There may be a slight delay but then your miniSim PC will restart the boot process. This is the safest way to handle an uncompleted boot sequence.
# In most cases if the system stops prematurely during the boot process, for example, while displaying the motherboard splash screen (typically AMI) or the blinking cursor just prior to the Windows logo, the PC is having trouble enumerating USB devices before loading windows.
# If the system hangs up during the second boot attempt, please check the USB connections. In particular, be sure the mouse and keyboard (typically connected through a USB hub) are in their designated USB ports i.e. nearest to the round PS2 style port (top for tower systems or far left for rackmount systems). These are typically USB 2.0 ports and are checked first during the USB enumeration process at boot. It is critical that the mouse/keyboard connections are made in this way.
# If the mouse/keyboard are connected to the correct USB ports, and your miniSim PC still does not boot, disconnect all USB devices (except mouse and keyboard) and systematically reconnect them one at a time in between reboots. This process will eventually and effectively isolate which USB device may be causing the boot problem. To resolve this conflict, simply plug the suspected USB device into a different USB port. Moving these devices to a different port typically resolves this problem permanently. It often (unfortunately) requires some experimentation (read trial and error) but once you find the right combination of USB devices and ports, this problem goes away.

Also, there are certain steps you should not take to try and resolve an unresponsive miniSim PC condition. Some tactics could actually make the problem worse e.g. damage hard drives, corrupt the operating system, scramble your data. Here are some activities you should not engage in to try and resolve a hanging miniSim PC:

'''Troubleshooting steps you should NOT try:'''
* Do not press and hold the power button on the PC while miniSim is running.
* Do not unplug the PC from electrical outlet while miniSim is running.
* Do not unplug mouse, monitors or keyboard while miniSim is running.

'''Acceptable methods for shutting down an unresponsive PC:'''
* Close all running programs, press the Windows key and select Shut Down.
* Or, press Ctrl+Alt+Delete and select Shut Down.
* Or, touch the reset button or lightly touch the power button one time.

====Making Changes to the BIOS====

If your miniSim PC is unresponsive in ways that are not covered above, you may need to make certain changes to the BIOS of your miniSim PC. Altering BIOS settings on a PC is delicate work and requires more than a passing knowledge of computers. Instructions for modifying the BIOS follows but if you would like the assistance of a NADS professional, don’t hesitate to ask.

The BIOS change involves enabling Fast Boot. Fast Boot will disable your USB devices at boot-up thus preventing USB port conflicts and effectively preventing endless USB enumeration and rebooting.

To enter BIOS setup, repeatedly press the Delete key while the computer is powering up. Ultimately you will see a screen that looks like the screen shot below. (This assumes your miniSim PC was built in 2015 or later.)

[[File:Initial BIOS Screen.jpg|400px|thumb|center|Initial BIOS Screen]]

Navigate to the '''Advanced tab''' using the arrow keys on your keyboard and select it.

[[File:Advanced.jpg|400px|thumb|center|Advanced Tab Selected]]

Scroll down and select '''USB Configuration.'''

[[File:USB Configuration.jpg|400px|thumb|center|USB Configuration Selected]]

Make sure your BIOS settings match the settings on the right half of the screen as shown below:

[[File:BIOS Settings.jpg|400px|thumb|center]]

Set '''Fast Boot''' to '''Fast.'''

[[File:Fast Boot Selected.jpg|400px|thumb|center|Fast Boot set to Fast]]

Select '''Save Changes and Exit'''

[[File:Save Changes and Exit.jpg|400px|thumb|center|Save Changes and Exit selected]]

'''NOTE: these settings will disable your USB devices during boot. This will eliminate the USB enumeration problem but will also prevent you from accessing BIOS settings again without a PS2 style keyboard. Feel free to contact NADS for additional information on this condition.'''

Bear in mind your BIOS screens may look different than the screenshots above but your objective remains the same, enable Fast Boot.

Please don’t hesitate to contact us if you wish help with these settings. '''Word of Caution:''' make these changes during normal business hours. If you get stuck in BIOS settings on a weekend or middle of the night, we may not be available to help you.

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

= miniSim Software =

=== Simulation data ===
Your data is the primary reason for simulation and is available from the miniSim in two ways:

# Default measures - these are pre-defined measures available for up to 20 events.
# Logstreams - the entire range of variables is available for as many events as required.

These two methods require setting up a scenario to create [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#What_is_a_Scenario_Event.3F '''events'''] that happen during simulation and are defined in a way to allow extracting them from the drive.

Default measures are available immediately after the drive in the form of a text document, located in the DAQ folder on miniSim.

Logstreams are flags embedded in the drive data and requires data reduction to make the information available after the drive.

More information on these methods is available [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#Data_Output_Methods here:]

= ISAT/Scenario =

=== New to ISAT? ===
A quick start overview is available [https://www.nads-sc.uiowa.edu/minisim/wiki/images/6/68/ISAT_Quick_Start.pdf '''here.''']

The ISAT User Guide is available [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents '''here.''']

A scenario/ISAT troubleshooting guide is available [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_Troubleshooting_Guide '''here.''']

=== Data Logging: miniSim Default Measures ===
There are a fixed number of measures available and a limit of 20 events.

More information including which measures are available and how to structure your scenario to support default measures is available [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#Default_miniSim_Scenario_Measures here.]

=== Q: How do we make an ADO or DDO go backward? ===
<div class="mw-collapsible-content">
A: Only DDOs can back up. To accomplish this, start by placing a DDO where desired.

Next, create a path for the DDO; right-click on it and select Extend Path from the pop-up menu.

Then, lay out a path (path nodes are a sequence of yellow dots) to indicate the desired route of travel.

Finally, right-click on each node and select Rotate to set the direction that you wish the DDO to face. The direction at each node can be set independently.

In order to make it appear as though the car is moving backwards, the arrows should point against the direction of travel. To avoid erratic movement, you should add sufficient nodes to create a smooth path. This will result in smoother and more realistic movement of the DDO, especially if you are changing direction rapidly.

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: How do I play a sound in my scenario? ===
<div class="mw-collapsible-content">

See [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#How_to_Use_Audio_in_your_Scenario Using Audio in a Scenario]

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: How do I add a trigger to my scenario? ===
<div class="mw-collapsible-content">

Triggers can be added to a scenario in ISAT through the menu '''Insert >> Coordinators'''
or, if the ISAT Elements panel is open, by left-click-drag any trigger off the panel and then releasing the left button where you want to place the trigger.

After a trigger has been placed in your scenario you can reposition it by clicking and dragging it to a new location.

'''Note:''' Trigger consist of multiple elements. To reposition a trigger you will have to click-drag the trigger handle, which is a small red dot. Clicking the larger trigger pane will move the pane, not the handle. Moving the handle will move the trigger.

[[File:2022-11-30_14h07_26.png|400px]]

Some triggers also require a roadpad (roadpad, follow, Time To Arrival triggers).
Right-click on the trigger and choose '''Place Road Pad.'''

'''Note: All triggers with road pads require a [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#Triggers '''predicate'''] to activate the trigger.'''

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: What is a “Write to Cell” action? ===
<div class="mw-collapsible-content">

Cells are reserved data containers that define various attributes and operating characteristics of the miniSim and are stored after each drive in a unique drive DAQ file.

A '''write to cell''' action allows you to send data to miniSim and simultaneously store this data in the DAQ file during simulation.

Most cells are managed by a subsystem (behaviors, dynamics, scenario control). For these cells, writing to a cell is possible but not practical because the managing subsystem will overwrite that cell within the next frame.

'''Examples''' (not a complete list!):
# Play a sound/audio file: Write to Cell SCC_Audio_Trigger
# Set event status or an event number for default miniSim data measures: Write to Cell SCC_Event_Status, SCC_Event_Number
# Saving data during a drive to the DAQ so it is available for analysis; i.e., timing of things, storing scenario variable data (variables are not persistent unless saved to a file or written to the DAQ): Write to Cell SCC_Custom1, or user defined
# Changing a simulator setting (Adaptive Cruise Control on/off, Automatic Lane Following): Write to Cell SCC_ALF_On, SCC_ACC_On

'''Note:''' Write to cell actions are expensive operations and there is currently a limit of 7 per frame. '''Exceeding this number will likely result in the excess cells not being written'''.

'''Note:''' Some cells are managed by the Cab Information/Hardware subsystem (CIS). Configuring miniSim to support operation by both scenario and CIS may require consulting with NADS to ensure correct operation.

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: How can I tell if the driver has left the road? ===
<div class="mw-collapsible-content">
One way to check if the driver has left the roadway is to use a lane deviation calculation: if the lane deviation is greater than <measured_total_lane_width> or less than -<measured_total_lane_width>, the driver is likely out of the lane.
[[#top|TOP]]
</div>
</div>

=== Q: How can I tell what surface the driver is driving over? ===
<div class="mw-collapsible-content">

A. Use the cell '''TPR_Surface_Type_Ind to detect the surface material code (SMC) under the driver.

The first four elements of the TPR_Surface_Type_Ind correspond to 4 wheels of the ownship/external driver vehicle.

[[File:2022-11-30_14h21_16.png|400px]]

[[File:2022-11-30_14h21_27.png|400px]]

MiniSim does not report surface material codes within intersections that do not have an elevation map associated with them.

[[File:2022-11-30_14h22_10.png|400px]]

You can find a complete list of available surface material codes (SMC) - (not all of these are used in the tile library, but this is the current version for SMC codes) under the TMT\ProjectData\Tiles\CommonLRIData\SurfaceMaterialSpecifications.xlsx.

'''Note:''' Intersection elevation maps were introduced in TMT '''1.8.5'''.

[[#top|TOP]]
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: What is the difference between SCC_Lane_Deviation and SCC_Lane_Spline_Deviation? ===

SCC_Lane_Spline_Deviation is computed from centerline data as a continuous spline and is recommended over SCC_Lane_Deviation.

[[File:scc_lane_spline_deviation_20230918.png|400px]]

<div class="mw-collapsible-content">

FAQ

2024-07-15T17:17:39Z

Shawn Allen: /* miniSim Data Dictionary update pdf file to new version containing SOP_Weather cells */

<div class="toccolours mw-collapsible mw-collapsed">
== miniSim Data Dictionary ==
The data dictionary is a compilation of the simulator data that is stored and available within the DAQ file after each drive.

[[:File:Cells-miniSim-20240715.pdf]]

Note:
miniSim users may extend the data dictionary by adding custom cells to the collect and schedule files:
* NadsMiniSim_x.x\data\NadsMiniSimCollect.general.txt
* NadsMiniSim_x.x\data\NadsMiniSim.cec

Typically new cells should be added into one of the SCNVIF sections. Use the same SCNVIF section for both files:

*cell 1 SCNVIF
*cell 7 SCNVIF
*cell 8 SCNVIF
*cell 9 SCNVIF

== miniSim Documentation ==
All miniSim simulators ship with a documentation folder located on the desktop. You can find miniSim and additional documentation within this folder.

== miniSim Hardware ==

=== Desktop and Viewport Settings ===
<div class="mw-collapsible-content">

Detailed information about the PC display layout and the miniSim viewport and channel configuration settings is available here:

[[:File:miniSim-Desktop_and_Viewport-Settings-v3_113022.pdf]]

[[#top|TOP]]
</div>
</div>

=== Q: My miniSim displays have changed. What happened, and how can I fix it? ===
<div class="mw-collapsible-content">

Windows has shown a tendency to re-enumerate the displays from time to time. The result is that the miniSim display layout/configuration becomes incorrect.

The relationship between the display layout and the viewport display settings in the miniSim Channel Configuration File (.ccf) no longer match.

To correct, check the following in this order:
# Displays are arranged from left to right: Matrox/Mosaic, Instrument Panel, Operator.(use mouse or arrow keys)
# The Matrox/Mosaic display must be designated as the ‘main’ or ‘primary’ in Windows. The task bar may move to this display when this is set, so drag the task bar and icons to the operator display
# Do not use the Matrox PowerDesk program to adjust the default locations for pop-up and application windows. This will cause many, many problems.
# The top edges of the display icons are aligned (use mouse or arrow keys)
# Reboot to make sure the configuration is stable.
# Check video and USB connections. If they are loose, it may cause windows to re number the displays, which can make things move around unpredictably.
# Open the correct Channel Configuration File (.ccf) in the \bin.x64 directory.

'''Note:''' there are several .ccf files in every system, and the ‘correct’ one is defined by the system settings in the ‘go.cmd’ file used to start miniSim.

See next section. The third number in the Channel header(s) should be equal to the number of the main display as reported by Windows in ‘Display Settings’ minus 1. Only 0, 1, 2 are generally valid for standard miniSim configurations (2 Channel, 3 displays).

:Channel 0 0 2 (Shear x2) (Twist x3) (Extends x4)
:0.000000 0.000000
:0.000000 0.000000 0.000000
:0.000000 0.000000 1.000000 1.000000
:6
:.
:.
:.
:Channel 1 0 2 (Shear x2) (Twist x3) (Extends x4)
:0.000000 0.000000
:0.000000 0.000000 0.000000
:1.000000 0.000000 2.000000 1.000000
:0 IP

[[#top|TOP]]
</div>

=== Q: What is the right Channel Configuration File for my miniSim? ===
<div class="mw-collapsible-content">

A. to determine the correct ccf file, examine the command file that launches miniSim.

The minisim is launched by running the correct go.cmd file in the '''NadsMiniSim_x.x.x\bin.x64''' folder.

Typically, there have been shortcuts created on the miniSim desktop that are used to run the appropriate ‘go’ scripts. There are often several go-scripts, this is usually to provide a way to launch the miniSim with or without various options (Video Capture, Advanced Automation, etc).

If you right-click on the shortcut icon and choose ‘edit’ you can edit the go.cmd script. A typical one looks like this:

:set MININADSCOMMMODE=PSEXEC
:set DYNA=car
:set NUMCHN='''2'''
:set INSTRUMENTS='''on'''
:set FORMAT='''wide'''
:set INSETVIEW=off
:set SIDEMIRRORS='''on'''
:set MININADSDAQ='''on'''

Based on these settings, the miniSim will read the following channel configuration file (.ccf) and use its contents for setting up the rendering channels and viewports. In this case, the miniSim will open this file:
'''\bin.x64\mininads_2ch.wide.sidemirrors.inst.ccf'''

This is the correct file to edit for this configuration. Remember to exit miniSim before making edits to the .ccf file.
'''If you make a change and see no effect, you may be editing the wrong file!'''

When the miniSim runs, it copies the .ccf file that pertains to the options selected in the go.cmd, and copies it to '''mininads_1ch.ccf''', which is the one that is loaded when miniSim is launched.

This means that the '''mininads_1ch.ccf''' has the same ‘Last Modified Date’ as the file you want to edit.

If you list the contents of the \bin.X64 folder by date, you will see something like this:

[[File:2022-11-30_15h03_56.png|400px]]

In this case, you will see that the '''mininads_2ch.wide.sidemirrors.inst.ccf''' is the file you want to edit, as it has the same last modified date as '''mininads_1ch.ccf'''.

For a desktop layout like this from Windows in ‘Display Settings’

[[File:2022-11-30_15h05_10.png|400px]]

This is a '''Two-Channel''' system, meaning that the front three displays on the Matrox/Mosaic are Channel 0, and the Instrument Panel display is Channel 1.

[[#top|TOP]]
</div>

=== Q: Where do I find data relating to the brake pedal force/position? ===
<div class="mw-collapsible-content">
A: The data you are seeking is represented by the '''CFS_Brake_Pedal_Force''' variable, which can be viewed either with ISAT or with Matlab during data reduction. The value ranges from 0 lbs. to 180 lbs., where 0 indicates no force (no pedal travel) and 180 indicates 180 pounds of force (full pedal travel).

If you see a variable named '''CFS_Brake_Pedal_Position''' you may ignore this as it is not currently being used.

[[#top|TOP]]
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: How can I adjust the brake pedal response? ===
<div class="mw-collapsible-content">

Information to adjust the brake pedal response is detailed in this document: [[:File:Adjust_Brake_Response_11302022.pdf]]

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: The tactile transducer, mounted under the cab, suddenly does not respond when the miniSim is running. ===
<div class="mw-collapsible-content">

Check the following:

1. Verify these connections first:
: a. The main stereo speakers should be plugged into the green audio port on the back of the PC using a ⅛" mini-jack.
: b. The Dayton D-30 amplifier should be plugged into the orange port on the back of the PC using a ⅛" mini-jack.
: c. The tactile transducer should be connected to the Dayton D-30 amplifier using the included speaker wire.

2. Note that the amplifier controls the volume of the tactile transducer and therefore must be plugged into a power source. If the amplifier is not plugged into power, this could be the reason the tactile transducer is not working.

3. Check the volume level of the amplifier. If it is set too low, the tactile transducer may '''appear''' to not be working. We suggest a minimum amplifier volume setting of 25% of full volume. A volume setting which is too high will be experienced as an unpleasant vibration and low-end rumble that does not resemble a real car.

4. Launch the Realtek audio manager from the Task Bar and select 5.1 audio. Then, disable the center and rear channels, leaving the front left and right speakers, and the subwoofer enabled.

5. Use the Realtek audio manager to test each of the speakers individually by clicking on each speaker icon. As you select a speaker, the speaker will sound.

Some motherboards have the sub/center channels switched. In this case, a ⅛" mini-jack to stereo RCA cable can be used.

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

== miniSim Operation ==
=== Q: Auto-start miniSim drive===
The miniSim simulator can be configured to start a drive automatically or not, depending on your project requirements.

This involves a '''''system level configuration change'''''. To run two projects simultaneously you will need to create a unique startup sequence for each project in order to use the correct configuration file.

Setting auto-start involves a setting in the hardware.xml file in use; note there are different configuration files present on all miniSim simulators within this folder:

miniSim_x.x\bin.x64\config

Please exit miniSim before editing any .xml file. You may want to backup these files prior to editing.

'''Enable auto-start'''

Change the string

<Sink device="SimulatorInterface" port="CIS_Auto_Ignition" ID="0" />

to

<Sink device="SimulatorInterface" port="CIS_Auto_Ignition" ID="1" />

To disable auto-start, set the value to 0.

=== Q: miniSim is not responding. ===
<div class="mw-collapsible-content">A: At times you may find that your miniSim PC or miniSim software has become unresponsive. We define appropriate steps for correcting unresponsive behavior on a miniSim PC under the following conditions:

* '''miniSim Software is Running but Will Not Load a Drive Scenario:'''
# Assuming the mouse is functioning, simply close and then restart the miniSim program.
# If the mouse is not functioning, use the keyboard to close and restart the miniSim program i.e. press Alt+Tab to select the minSim program and press Esc to close.
# This step will fix this unresponsive behavior most of the time.
* '''A miniSim Drive Has Been Selected but Will Not Start:'''
: Assuming the mouse is functioning, click on the Settings tab and verify all lines are green (ready mode). If one or more lines are red, simply wait for all to become green. If still not green after about 90 seconds, close and restart the miniSim software normally. This step will fix this unresponsive behavior most of the time.
* '''miniSim Software Stops Running:'''
# Assuming the mouse is functioning, simply close and then restart the miniSim program.
# If the mouse is not functioning, use the keyboard to close and restart miniSim program i.e. press Alt+Tab to select the minSim program and press Esc to close.
# If the miniSim software will not close, press Ctrl+Alt+Delete and open Task Manager. Within Task Manager, select the SimopServer program and close it. Restart miniSim.
# This process generally will recover miniSim from nearly any unresponsive state.
* '''miniSim PC Shuts Down Unexpectedly:'''
# Check for severe storms and possible power outages in your neighborhood.
# If you see smoke or smell something burning near the miniSim PC, carefully unplug the PC from the electrical outlet and fetch your fire extinguisher just in case. When immediate danger passes, consult a local hardware expert to examine your PC for possible electrical shorts, overheating or failure of critical systems such as motherboard, hard drive and etc. Contact NADS miniSim in the event hardware components need to be replaced. See contact information below.
* '''The miniSim PC Will Not Boot:'''
# On rare occasions your miniSim PC may not boot to Windows. It may halt the boot process just prior to launching Windows. If your miniSim PC has stopped the boot process before a Windows launch, it is okay to touch the reset button on the PC (the small button next to the power button). If your miniSim PC does not have a reset button, touch the power button lightly one time. There may be a slight delay but then your miniSim PC will restart the boot process. This is the safest way to handle an uncompleted boot sequence.
# In most cases if the system stops prematurely during the boot process, for example, while displaying the motherboard splash screen (typically AMI) or the blinking cursor just prior to the Windows logo, the PC is having trouble enumerating USB devices before loading windows.
# If the system hangs up during the second boot attempt, please check the USB connections. In particular, be sure the mouse and keyboard (typically connected through a USB hub) are in their designated USB ports i.e. nearest to the round PS2 style port (top for tower systems or far left for rackmount systems). These are typically USB 2.0 ports and are checked first during the USB enumeration process at boot. It is critical that the mouse/keyboard connections are made in this way.
# If the mouse/keyboard are connected to the correct USB ports, and your miniSim PC still does not boot, disconnect all USB devices (except mouse and keyboard) and systematically reconnect them one at a time in between reboots. This process will eventually and effectively isolate which USB device may be causing the boot problem. To resolve this conflict, simply plug the suspected USB device into a different USB port. Moving these devices to a different port typically resolves this problem permanently. It often (unfortunately) requires some experimentation (read trial and error) but once you find the right combination of USB devices and ports, this problem goes away.

Also, there are certain steps you should not take to try and resolve an unresponsive miniSim PC condition. Some tactics could actually make the problem worse e.g. damage hard drives, corrupt the operating system, scramble your data. Here are some activities you should not engage in to try and resolve a hanging miniSim PC:

'''Troubleshooting steps you should NOT try:'''
* Do not press and hold the power button on the PC while miniSim is running.
* Do not unplug the PC from electrical outlet while miniSim is running.
* Do not unplug mouse, monitors or keyboard while miniSim is running.

'''Acceptable methods for shutting down an unresponsive PC:'''
* Close all running programs, press the Windows key and select Shut Down.
* Or, press Ctrl+Alt+Delete and select Shut Down.
* Or, touch the reset button or lightly touch the power button one time.

====Making Changes to the BIOS====

If your miniSim PC is unresponsive in ways that are not covered above, you may need to make certain changes to the BIOS of your miniSim PC. Altering BIOS settings on a PC is delicate work and requires more than a passing knowledge of computers. Instructions for modifying the BIOS follows but if you would like the assistance of a NADS professional, don’t hesitate to ask.

The BIOS change involves enabling Fast Boot. Fast Boot will disable your USB devices at boot-up thus preventing USB port conflicts and effectively preventing endless USB enumeration and rebooting.

To enter BIOS setup, repeatedly press the Delete key while the computer is powering up. Ultimately you will see a screen that looks like the screen shot below. (This assumes your miniSim PC was built in 2015 or later.)

[[File:Initial BIOS Screen.jpg|400px|thumb|center|Initial BIOS Screen]]

Navigate to the '''Advanced tab''' using the arrow keys on your keyboard and select it.

[[File:Advanced.jpg|400px|thumb|center|Advanced Tab Selected]]

Scroll down and select '''USB Configuration.'''

[[File:USB Configuration.jpg|400px|thumb|center|USB Configuration Selected]]

Make sure your BIOS settings match the settings on the right half of the screen as shown below:

[[File:BIOS Settings.jpg|400px|thumb|center]]

Set '''Fast Boot''' to '''Fast.'''

[[File:Fast Boot Selected.jpg|400px|thumb|center|Fast Boot set to Fast]]

Select '''Save Changes and Exit'''

[[File:Save Changes and Exit.jpg|400px|thumb|center|Save Changes and Exit selected]]

'''NOTE: these settings will disable your USB devices during boot. This will eliminate the USB enumeration problem but will also prevent you from accessing BIOS settings again without a PS2 style keyboard. Feel free to contact NADS for additional information on this condition.'''

Bear in mind your BIOS screens may look different than the screenshots above but your objective remains the same, enable Fast Boot.

Please don’t hesitate to contact us if you wish help with these settings. '''Word of Caution:''' make these changes during normal business hours. If you get stuck in BIOS settings on a weekend or middle of the night, we may not be available to help you.

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

= miniSim Software =

=== Simulation data ===
Your data is the primary reason for simulation and is available from the miniSim in two ways:

# Default measures - these are pre-defined measures available for up to 20 events.
# Logstreams - the entire range of variables is available for as many events as required.

These two methods require setting up a scenario to create [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#What_is_a_Scenario_Event.3F '''events'''] that happen during simulation and are defined in a way to allow extracting them from the drive.

Default measures are available immediately after the drive in the form of a text document, located in the DAQ folder on miniSim.

Logstreams are flags embedded in the drive data and requires data reduction to make the information available after the drive.

More information on these methods is available [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#Data_Output_Methods here:]

= ISAT/Scenario =

=== New to ISAT? ===
A quick start overview is available [https://www.nads-sc.uiowa.edu/minisim/wiki/images/6/68/ISAT_Quick_Start.pdf '''here.''']

The ISAT User Guide is available [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents '''here.''']

A scenario/ISAT troubleshooting guide is available [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_Troubleshooting_Guide '''here.''']

=== Data Logging: miniSim Default Measures ===
There are a fixed number of measures available and a limit of 20 events.

More information including which measures are available and how to structure your scenario to support default measures is available [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#Default_miniSim_Scenario_Measures here.]

=== Q: How do we make an ADO or DDO go backward? ===
<div class="mw-collapsible-content">
A: Only DDOs can back up. To accomplish this, start by placing a DDO where desired.

Next, create a path for the DDO; right-click on it and select Extend Path from the pop-up menu.

Then, lay out a path (path nodes are a sequence of yellow dots) to indicate the desired route of travel.

Finally, right-click on each node and select Rotate to set the direction that you wish the DDO to face. The direction at each node can be set independently.

In order to make it appear as though the car is moving backwards, the arrows should point against the direction of travel. To avoid erratic movement, you should add sufficient nodes to create a smooth path. This will result in smoother and more realistic movement of the DDO, especially if you are changing direction rapidly.

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: How do I play a sound in my scenario? ===
<div class="mw-collapsible-content">

See [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#How_to_Use_Audio_in_your_Scenario Using Audio in a Scenario]

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: How do I add a trigger to my scenario? ===
<div class="mw-collapsible-content">

Triggers can be added to a scenario in ISAT through the menu '''Insert >> Coordinators'''
or, if the ISAT Elements panel is open, by left-click-drag any trigger off the panel and then releasing the left button where you want to place the trigger.

After a trigger has been placed in your scenario you can reposition it by clicking and dragging it to a new location.

'''Note:''' Trigger consist of multiple elements. To reposition a trigger you will have to click-drag the trigger handle, which is a small red dot. Clicking the larger trigger pane will move the pane, not the handle. Moving the handle will move the trigger.

[[File:2022-11-30_14h07_26.png|400px]]

Some triggers also require a roadpad (roadpad, follow, Time To Arrival triggers).
Right-click on the trigger and choose '''Place Road Pad.'''

'''Note: All triggers with road pads require a [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#Triggers '''predicate'''] to activate the trigger.'''

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: What is a “Write to Cell” action? ===
<div class="mw-collapsible-content">

Cells are reserved data containers that define various attributes and operating characteristics of the miniSim and are stored after each drive in a unique drive DAQ file.

A '''write to cell''' action allows you to send data to miniSim and simultaneously store this data in the DAQ file during simulation.

Most cells are managed by a subsystem (behaviors, dynamics, scenario control). For these cells, writing to a cell is possible but not practical because the managing subsystem will overwrite that cell within the next frame.

'''Examples''' (not a complete list!):
# Play a sound/audio file: Write to Cell SCC_Audio_Trigger
# Set event status or an event number for default miniSim data measures: Write to Cell SCC_Event_Status, SCC_Event_Number
# Saving data during a drive to the DAQ so it is available for analysis; i.e., timing of things, storing scenario variable data (variables are not persistent unless saved to a file or written to the DAQ): Write to Cell SCC_Custom1, or user defined
# Changing a simulator setting (Adaptive Cruise Control on/off, Automatic Lane Following): Write to Cell SCC_ALF_On, SCC_ACC_On

'''Note:''' Write to cell actions are expensive operations and there is currently a limit of 7 per frame. '''Exceeding this number will likely result in the excess cells not being written'''.

'''Note:''' Some cells are managed by the Cab Information/Hardware subsystem (CIS). Configuring miniSim to support operation by both scenario and CIS may require consulting with NADS to ensure correct operation.

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: How can I tell if the driver has left the road? ===
<div class="mw-collapsible-content">
One way to check if the driver has left the roadway is to use a lane deviation calculation: if the lane deviation is greater than <measured_total_lane_width> or less than -<measured_total_lane_width>, the driver is likely out of the lane.
[[#top|TOP]]
</div>
</div>

=== Q: How can I tell what surface the driver is driving over? ===
<div class="mw-collapsible-content">

A. Use the cell '''TPR_Surface_Type_Ind to detect the surface material code (SMC) under the driver.

The first four elements of the TPR_Surface_Type_Ind correspond to 4 wheels of the ownship/external driver vehicle.

[[File:2022-11-30_14h21_16.png|400px]]

[[File:2022-11-30_14h21_27.png|400px]]

MiniSim does not report surface material codes within intersections that do not have an elevation map associated with them.

[[File:2022-11-30_14h22_10.png|400px]]

You can find a complete list of available surface material codes (SMC) - (not all of these are used in the tile library, but this is the current version for SMC codes) under the TMT\ProjectData\Tiles\CommonLRIData\SurfaceMaterialSpecifications.xlsx.

'''Note:''' Intersection elevation maps were introduced in TMT '''1.8.5'''.

[[#top|TOP]]
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: What is the difference between SCC_Lane_Deviation and SCC_Lane_Spline_Deviation? ===

SCC_Lane_Spline_Deviation is computed from centerline data as a continuous spline and is recommended over SCC_Lane_Deviation.

[[File:scc_lane_spline_deviation_20230918.png|400px]]

<div class="mw-collapsible-content">

File:Cells-miniSim-20240715.pdf

2024-07-15T17:16:47Z

Shawn Allen: File uploaded with MsUpload

File uploaded with MsUpload

TMT User Guide (versions 1.8 & greater)

2023-11-30T16:04:32Z

Shawn Allen: /* Summary of changes in this version surface materials verbag*/

<span style="color:red">This document is in beta 02.11.2020</span>

== Who should use this document ==
This document is for use with TMT version 1.8 or greater. Do '''NOT''' use this document if you are working with a TMT version less than 1.8.

== Summary of changes in this version==
This version of the Tile Mosaic Tool contains significant updates to the tile model library.

'''Elevation Maps'''
Elevation maps have been implemented on some tile model intersections. These are 3-D surfaces within an intersection. The primary characteristic of elevation maps is they support different surface materials within an intersection.

Elevation maps are one way to determine curb strikes within an intersection based on a surface material code (SMC).

<span style="color:red">'''NOTE:'''
Failure to use the correct rotation will produce a road network that ADOs cannot navigate because the elevation maps produce an offroad condition when the wrong rotation is used in the TMT.</span>

[[:File:elev_maps_20200211.jpg]]

'''NOTE:''' Elevation map intersections include a 'rotation key' in the tile name. Due to implementation requirements, it is '''required''' to rotate the tile model to the rotation specified.

'''Rotation Key'''

No code = 0 degrees
A = 90 degrees
B = 180 degrees
C = 270 degrees

'''NOTE:''' Tiles with intersection elevation maps that are not rotated (default rotation = zero degrees) are located in various tile categories. Only tiles containing intersections can contain intersection elevation maps.

'''Obsolete models'''
One significant change is that some tiles are now considered obsolete. Obsolete models are contained within the tile category 'Obsolete'.

It is '''strongly recommended''' that .MOS worlds using obsolete models be revised, as future versions of the Tile Mosaic Tool may not include those models.

<span style="color:red">'''If a world.mos file contains tile models that are missing from the library and it is saved, that .mos file will become corrupted.

There is currently no way to recover from this condition.'''</span>

The Obsolete tile category is included with this version to permit replacing obsolete models with compatible tiles. It is strongly recommended that obsolete tiles be converted to the correlated tile model.

A list of compatible models is included in the Appendix of this document.

''' Transition tile category'''

Transition tile models are now grouped into a new '''Transition''' tile category. If you require a transition between different roadway types, the Transition category is the place you will find it.

'''New tile models'''

Another change in this version is the addition of new tile models, listed below.

'''bike_lane'''
This is a new tile category. Tiles within the '''bike_lane''' category contain bicycle lanes, which are narrow lanes defined as Vehicle Restricted lanes. This definition is intended to prevent typical ADOs from using this lane.

However, scenario authors '''should be able''' to author pedestrian and bicycle models that will use the bike lane. In some cases it may be necessary to author scenarios using the standard road lane and apply a '''lane offset''' to shift the scenario object over into the target lane.

'''bike_lane tile models'''
#2ln_3Mi_01
#2ln_3Mi_02
#2ln_4way_3Mi_01
#2ln_4way_3Mi_02

'''NOTE:''' Bike lanes are not necessarily included as a separate network adjacent to the road network. At this time they are an attribute of the road.

'''city tile models'''
#4ln_city_1x1_02
#4ln_city_1x1_crv90_02
#6ln_4way_01
#6ln_4way_02
#6ln_city_straight_01
#6ln_city_straight_02

'''comm tile models'''
#2ln_4ln_3way_comm_02
#2ln_4ln_3way_comm_03
#4ln_4way_comm_01
#4ln_comm_straight
#4ln_comm_straight_04
#4ln_comm_straight_05
#4ln_res_3way_comm
#4ln_res_hill_curve01

'''filler tile models'''
#gen_common_3x5
#urban_01
#urban_02
#urban_03

'''fwy tile models'''
#fway_2ln_04
#fway_2ln_10k10kS_01
#fway_4ln_2ln_DTL01
#fway_4ln_straight_13x17

'''railroad tile models'''
#railway_1xgrade_rural_01
#railway_1xgrade_rural_02
#railway_1x_straight
#railway_3xgrade_city_01
#railway_3xgrade_rural_01
#railway_3xgrade_rural_02
#railway_3x_straight
#railway_4ln_city_01
#railway_90
#railway_straight

'''res tile models'''
#2ln_res_mult_school
#2ln_res_rural_trans
#2ln_straight_res
#2ln_straight_res_2
#res_2ln_3way
#res_2ln_3way_02
#res_3way
#res_3way_02
#res_90
#res_straight

'''rural tile models'''
#2ln_3way_rural_res01
#4ln_1mi_02

'''suburb tile models'''
#suburb_2mi_01
#suburb_90_01
#suburb_Scurve_01

'''transition tile models'''
#2ln_fwy_2ln_rural
#2ln_fwy_3ln_fwy
#2ln_fwy_3ln_fwy_02
#2ln_fwy_4ln_fwy
#2ln_fwy_4ln_urban
#2ln_rural_2ln_gravel
#2ln_rural_2ln_gravel_02
#2ln_rural_2ln_res
#2ln_rural_2ln_res_3way
#2ln_rural_2ln_rural_10f_lane
#2ln_rural_2ln_rural_no_shoulder
#2ln_rural_3M_rural
#2ln_rural_4ln_city
#2ln_rural_4ln_rural
#3ln_fwy_3ln_urban
#4ln_BLVD_4ln_urban_e20
#4ln_BL_urban_2ln_rural
#4ln_city_4ln_BL_city
#4ln_city_4ln_BL_city_ROT_C
#4ln_rural_2ln_fwy
#4ln_suburb_2ln_rural
#4ln_suburb_2ln_rural_night
#4ln_urban_6ln_urban_day
#4ln_urban_6ln_urban_night
#5ln_urban_4ln_urban

'''urban tile models'''
#4ln_urban_4x8_01
#urban_2ln_4ln_s1400A
#urban_4ln_arterial_02
#urban_4ln_straight_01

=='''Introduction'''==

The Tile Mosaic Tool (TMT™) was created to build visual and virtual correlated databases, a process generally known as world or database generation. The TMT is used to arrange tile models into a configuration (world). Tile models typically contain roads, terrain and feature objects. The construction of these elements and additional models and textures require the use of 3rd party software for the creation of textured 3D models. At the present time, only OpenFlight™ models and RGB format image files are supported by the TMT. Many commercially available (and many shareware or free) 3D programs can also be used for tile creation, but their output will need to be converted to OpenFlight™ format for use within the TMT. For a partial list of applications, please see Appendix B.

== '''Command line Syntax/Conventions''' ==

In this document the following conventions are used for command line interaction. #Information enclosed within bracket characters <like_this> is for user input.
#The phrase <ENTER> means that the user should press the Enter key, not to type in the word.
#Where the percent character is used to enclose a string, it indicates an environment variable or environment variable value.

== '''Getting Started''' ==

The TMT tile library contains of a number of related model files which reside on your computer. It is necessary that all tiles reside below a single parent directory (folder). Within this top-level directory, sub-directories are used to divide the tile library into different categories. Currently these categories consist of tiles with similar characteristics, but you are not limited to these. Additional tile categories may be created under the top-level directory. It is recommended that you do not change the basic tile category set, but you are able to add new tiles to existing categories, or create new categories for your tiles at any time.

'''NOTE:''' Each tile model must be unique – you should not have two tiles within the library with the same name, even if they are in different categories.

Start the TMT by double-clicking the icon. You may want to open existing database worlds, or create a new world (terrain database). To create a new world, choose New from the File menu (File >> New). If the TMT has not been used on this computer before, you’ll have to preprocess the tile library in order to proceed. Click Preprocess to load the tile library. This procedure will occur only when the TMT is first used on your system, or when a tile geometry file (.FLT) has been modified. The TMT loads the Tile Library automatically in normal use.

To open an existing terrain database/world file, choose File >>Open and navigate to the database location on your computer.

The TMT workspace window will appear. To place tiles into the terrain database, use the category tabs on the left to choose a tile category, and select a tile from the list by clicking with the left mouse button (LMB) on it. This will “attach” the tile to the cursor. Move the mouse to the right onto the terrain and position it, then LMB on any open grid to place the tile. The TMT will attempt to snap the placed tile onto the terrain grid. For more precise positioning, enable the terrain grid View >> Draw Attributes >> Grid and position the tile within the gridlines.

You can rotate a tile while it is attached to the cursor by pressing any key.

'''NOTE:''' When you are placing tiles onto a terrain that already contains tiles, the tiles will attempt to connect only where tile edges are the same. For example, the default tile edge is GEN (for General or Generic). A GEN edge will not match with any other edge unless it is forced. Although you can force tiles together, this is a procedure that has larger ramifications and can create visual and logical discontinuities and errors. Forcing tiles should be carefully considered.

When you are finished placing tiles, save the world file. Choose File >> Save and navigate to the directory location you wish to save the file set to. Because each world consists of multiple files, it is good practice to segregate them into their own unique directories. The Database directory installed with the TMT is a good location. For testing purposes, you may choose to use a single default “scratch” directory when doing rapid-cycle development or debugging and simply over-write the files repeatedly until a desired configuration is achieved.

'''NOTE:''' Avoid the use of spaces in the folder path to the TMT project files, as this can create problems for various TMT script utilities.

'''NOTE:''' To force/override the tile placement function, press and hold CTRL-SHIFT as you place the tile. This procedure will not allow you place a tile on top of another; it will however allow you to place two tiles together when their edges do not match.

'''NOTE: Each road map created in the TMT must be evaluated in ISAT to determine if the map is good and traffic can travel on all sections.'''
The simplest way to test for a valid road network is to use ISAT and an ADO lead vehicle that drives across all road sections you plan to use during your simulation.

The ADO path should look like the intended drive path for your external driver/XD.

You can set a set Dial >> ADO >> Force Velocity action on the lead vehicle to maintain a consistent headway gap relative to the XD. This will allow you to see if there is a problem in the road network.

Run the test scenario in ISAT rehearsal mode and see if the lead vehicle can navigate the entire road network. Following a successful rehearsal, drive the scenario in miniSim and see if the results match. If the lead vehicle disappears in either case, review the road network in ISAT following the above guidelines.

=== '''Creating Output''' ===

The process of building and driving a world on the miniSim is:

# Produce a terrain map by placing tiles on the workspace to create a road network using the TMT.
# Output the visual files using the TMT.
# Create a scenario control list (SCL) file using the command line.
# Create a logical road information (LRI) file using the TMT.
# Convert the LRI file to an optimized form (BLI) for ISAT and MiniSim using the command line.
# Convert the visual files to an optimized format using the command line.
# Install all required files on the miniSim using the install script.
# Create a scenario that uses the world and save it to disk. At a minimum you need to place an external driver on any roadway. You can also set the ownship cab type using ISAT.

'''NOTE: All steps must be completed in order to view the created world on the MiniSim simulator.'''

To generate files for use on the miniSim, you will use the TMT Output menu. Environment creation workflow consists of building the visual database first. The miniSim will render these output files after they are optimized and installed. You must also process these visual files to produce a scenario control list (SCL) file. After the SCL file has been created, you can choose Output >> Scenario LRI file from the TMT to create a Logical Road Information (LRI) correlated database file. It will be necessary to convert the LRI file into a Binary LRI file (BLI), since that is the format the miniSim uses during simulation. It can be useful to be able to read the text form of the LRI file when troubleshooting problems with the world output process.

Conversion of the output flt files to an optimized format for use on the miniSim happens with a two-step process. First a command list is created in the flt folder, and then that file is processed to generate the required files.
The database is ready for visualization on the miniSim when all the files have been installed.

== '''Tile Library Contents''' ==

The Tile Library has been designed as an open-ended, extendable library of re-usable components. Tile models are a different class of model from model objects such as signs, vehicles or virtual objects. Tile categories are intended to provide a coarse level of differentiation between tiles with different features (culture). Generally, tiles will contain roads, roadway markings, terrain and vegetation. More complex tiles will include signage or traffic control devices such as traffic signals, railroad crossing signals, and general signage. In most cases, signs and traffic control devices are designed to be operated during simulation, which means they may be authored in ISAT to change appearance either during simulator initialization (i.e., changing a stop sign to a yield sign), or change dynamically during simulation (i.e., traffic light state changes from red to green to yellow).

'''NOTE:''' Tile Library content may be added to at any time without affecting previously constructed terrain databases. However, it is important to understand that scenario events are closely coupled with geographic locations within the world. Changing a world after scenario authoring has begun or following authoring completion may result in unexpected results or even failure to load or run the scenario in ISAT.

Typically it is possible to change a portion of the road network if there are no scenario paths or elements on that portion. Extending a road network beyond an intersection will not affect the road network on the upstream side of the intersection.

[[File:tmt_adding_to_existing.jpg|400px]]

This example assumes there are no scenario authored objects, events or paths in the areas modified by the addition of tile models to the original design.

'''NOTE:''' Tile models require additional development for night rendering effects. Not all models in the library contain these effects.

Tile categories include:

# City
# Comm (commercial features)
# Elev_maps (models contain elevation maps)
# Filler (borders, panoramas and fillers)
# Fwy (freeway)
# Ind (Industrial features)
# Mtn (Mountain)
# Obsolete (these tiles should not be used)
# Railroad (includes a rail line)
# Res (Residential)
# Rural (Countryside)
# Rural_bike_lane (rural tiles with bike lanes)
# Special (Tiles which are non-standard in some way, or project-specific and not intended for general-purpose use)
# Suburb
# Transition (tiles that connect between different road types and lanes)
# Urban

Due to the nature of the visual and virtual correlated databases, special effects such as wet or snow environments have been constructed as specialized tiles, with the intended effect built into the tile model.

Time of day is a more general simulation effect, although for some complex tiles, a lighting effect has also been built into the tile. These special-function tiles are identified by keyword within the tile name (wet, day, night).

Although it is possible to use day tiles at night or vice-versa, the resulting database may appear odd and incongruous to the viewer.

Additional tile categories may be created by editing the alltiles.txt TMT configuration file located in the ProjectData\Tiles\ directory.

=== '''Tile Model Naming Conventions''' ===
As the tile library grows, it is useful to know how the tile model name is constructed.

Tile model names are intended to provide some clue as to the nature or content of the tile, without requiring the user to actually view the model. Viewing the model is, of course, a really great way to become familiar with the model.

Here are a few examples:

*2ln_city_01
**2 lane road, tile version 1
*2ln_city_1x1_crv90_01_20
**2 lane road, road bed is a 90 degree curve, tile version 1, 20f elevation
*2ln_city_4way_20
**2 lane road, 4 way intersection, 20f elevation
*4ln_2x2_Hill_02
** 4 lane, 2x2 tile (1320f x 1320f), tile version 2

'''NOTE:''' elevated tiles <span style="color:red"> '''WILL NOT''' </span>connect to standard tiles. You will require a hill tile to connect elevated and standard tile models. Forcing connections to these tiles is not advisable '''unless''' the connecting model has the same elevation.

'''NOTE:''' Tile versions are typically small variations from earlier version models. However, they may be completely different content on a similar road layout.

'''What happened to version <u>x</u>?'''
<ul>In cases where there is a missing version number, chances are that tile version is either not yet developed, or the missing version was left out of the TMT for some reason. There is no requirement that model versions be sequential, it just a mechanism to help classify a model.</ul>

== '''Compatible Tile List''' ==

This command provides a list of tiles which are compatible in terms of edge specifications for placement at an open grid location in the terrain database. You must select an open grid location adjacent to a placed tile to use this command.

#Select a grid location.
To select a grid location, double click (DBL) the grid location. That selected grid location will draw a yellow outline, indicating it has been selected.

[[File:TMT_selected_grid.jpg|400px]]

#RMB >>Compatible Tile List or Edit >> Compatible Tile List. A dialog will list all compatible tile choices for the selected grid location.

[[File:TMT_selected_grid_compatible.jpg|400px]]

Tiles are listed in terms of tile name, rotation, size and category. Select a compatible tile by LMB a Tile Name in the dialog. To place the compatible tile into the terrain, LMB the Apply button. The tile is placed at the selected grid location in the terrain. You can continue to choose other tiles from the dialog and apply them to the terrain until the desired tile has been placed. LMB OK to close the dialog or Cancel to cancel.

== '''Manual Tile Placement''' ==

The most common way to create terrain databases in the TMT is by placing the tiles manually. This provides the greatest control over creating the exact road network desired for simulation. After a tile has been placed in the database, you can edit the tiles to meet specific requirements* through the use of ISAT to change features that were created as configurable features.

'''Note:''' Editing the source tile model requires the use of a 3D editor. Tile editing and 3d modeling is outside the scope of this document.

To manually place tiles, choose a tile category from the left panel. Select a tile and LMB on the icon. Move the cursor to the right side, into the terrain layout. You can rotate a tile by pressing any key. Click on an open grid location to place the tile. To detach the tile from the cursor, move the cursor to the edge of the terrain database window.

The TMT will prevent placement if the following conditions occur:
1. You are attempting to place a tile onto another tile.
2. You are attempting to place a tile where the tile edge does not match. The TMT will turn the placed tile edge red when this happens, indicating an invalid edge match.

NOTE: You can override the edge match by pressing '''CTRL AND SHIFT''' when placing the tile. Be aware this can cause discontinuities and visual mismatch when you override edge matching.

After a tile is placed, you can modify the orientation by invoking commands from the Edit menu, RMB or Tool Bar.
1. Select a tile or group of tiles in the terrain database.
2. Choose a function from the Edit menu, RMB menu, or Tool Bar.

== '''Auto Tile Placement''' ==

You can fill in defined areas in the terrain database using automatic tile placement, which is used when no particular configuration is desired and a large region of coverage is desired. From the Auto Tile Placement dialog, you can choose tile categories and individual tiles within each category for placement. Tile placement is based upon a weighting factor which is controlled by this dialog.

Selecting a grid area by DBL at an open grid location. If properly selected you will see the terrain grid outlines in yellow. Move the cursor to another location, holding the SHIFT key, and LMB again at the new location. You will see a region of terrain grid now has a yellow border, indicating a valid selection. Choose Edit >> Auto Tile Placing or RMB >> Auto Tile Placing.

[[File:TMT_Auto_placement.jpg|400px]]

NOTE: if a grid area is not properly selected the command will not enable.

The Auto Tile Placement Control Dialog will appear. The dialog has two parts:
# Category selection and adjustments
# Library tile placement and adjustments

In the Category selection and adjustment area, choose the tile categories you wish to use for auto tile placing. You can select multiple categories, or LMB Select All. When you have chosen tile categories, LMB the Add button. Use CTRL to select discontinuous categories, or SHIFT to select a continuous list of categories. You can also remove single or multiple categories from the destination list.

In the Library Tile Selection and Adjustments section, you can choose the library tiles you wish to use in auto placement. Tiles within the selected Tile Categories appear in the source (left bottom) window. You can use Select All, Add, Remove and Clear buttons for both Tile Categories and Tiles. Adjust the weighting factors of each tile by using the slider bar. The Optimal Tiling button applies higher weights to tiles that have the most common edge specifications among the list of tiles chosen. Click OK to apply the settings to automatically place tiles within the terrain. Cancel will cancel the auto tile placement command.

== '''Controllability: Unique vs. Generic Functionality''' ==

The MiniSim™ uses scenario control software to control individual components within a tile (ie., changing a traffic light or sign). But what happens when there is more than one tile reference of the same tile within the terrain database? In order to control each model component, tiles must be flagged as a unique tile instance. This is achieved by enabling the Unique Control setting in the TMT™ (the traffic light icon) and then enabling Unique Control for a tile or selection of tiles.

'''NOTE:''' Unique control options in the menu are disabled until the Unique Control Mode is enabled in the TMT.

Select a tile by LMB or a group of tiles using fence select. RMB >> Enable/Disable Unique Control (Selected Tiles) or Edit >> Enable/Disable Unique Control (Selected Tiles). A uniquely controlled tile will display a small green X in the terrain layout view. Because this function is a toggle, to turn off unique control, you can disable all controls or for the selected tile using the same menu as enable.

=== '''When are Unique Controls necessary?''' ===

Unique controls are '''not''' necessary if there are no controls available within the tile!

However, if a tile contains SWITCHES, then the tile has been built to support changes to the simulation scene from scenario control. For example, some tiles contain street signs. It is often desirable to have a world contain unique street names. If the world is built with Unique Controls enabled, then a scenario author may adjust each street sign to a different name using the Interactive Scenario Authoring Tool (ISAT). This mechanism is used for all cases where a change in appearance is desired within the terrain tile.

'''NOTE:''' The TMT will output a file for each Unique Control tile.

'''NOTE: Turning a visual element off within a tile does not disable the CVED representation.''' Even if the object is not visible to the simulator driver, the object still exists.

This has implications if the miniSim is configured with collision effects enabled. In this case, '''driving into a visually disabled object will result in a collision.'''

Due to the nature of switch controls, it is possible to implement controllability for visual scene elements at any time. However, there is no corresponding capability for any applicable CVED representation.

For example, it is possible to create controllable road markings with different visual conditions (pristine, aged, off) but without additional programming CVED will not reflect this functionality. In this case, the CVED road marking representation will always be present, until the CVED code has been modified to support a variable condition road marking.

=== '''Load Management for Visual Databases''' ===

It is possible to create databases which will not perform optimally on the MiniSim™. To avoid this, adjust the visibility of terrain tiles by using the level of detail (LOD) node within each tile. More complex tiles may contain additional LOD nodes.

Right-click any tile and choose Tile LOD Settings… from the context menu. The LOD dialog will highlight each LOD in the configuration window as you select LODs from the list. You can change the Center, Switch Distance, Transition Range and Freeze flags for each LOD. Setting a small Switch Distance will cause the tile to display when the eyepoint approaches closer to the tile. Large values cause the tile to become visible over longer distances. Excessively long values, especially within complex environments, may contribute to performance problems.

It is most desirable to have terrain tiles visible only for the period they are needed. The LOD Center X, Y and Z values can be manipulated to shift the LOD so that the tile disappears behind curves. Thus, curve tiles are ideal for load management elements.

'''NOTE:''' Changing the LOD Center values will require the Freeze flag to be enabled. If the freeze flag is not enabled, the tile may not display as anticipated.

[[File:2021-12-03_10h56_40.png|400px]]

Notice how the curve tile LOD has been edited so the tile is not visible from the North-South road along the right side, and it is not displayed to the left of the large S-curve tile since it is unlikely the tile can be seen from that location anyway.

LODs can be adjusted significantly as needed, as shown below.
[[File:2021-12-03_11h35_39.png|400px]]

== '''Output for Visual Database''' ==

1. After a world has been developed and saved to disk, you can publish the visual database world to disk. From the TMT™ Output menu, choose Output Scenario/Visual Data. A dialog will appear. Disable the LRI flag, and use the default settings for OpenFlight Output.

'''NOTE:''' This will over-write the files located within the project flt directory; in the event you wish to retain these files, it is best to create a backup copy of the flt directory prior to generating output.

2. The next step is to generate a scenario control list for the terrain database/world that you've just generated. The SCL is a text file that lists all available switches, which can be authored using the ISAT. Without this file, although you can generate a world that will run on the MiniSim™, you will be unable to author objects within the environment such as street signs, traffic lights, etc.

Open a command window at the FLT directory. You can use the windows explorer to navigate to the Database directory under Favorites: Favorites >> ProjectData_Databases. Open the directory containing your database, then right-click on the FLT folder and choose “Open CMD here” from the context menu.

At the command window, enter:
'''buildscl''' <DB_NAME.flt><ENTER>

Remember that DB_NAME is the name of your .MOS world file (terrain database), and you do not type the ‘<’ or ‘>’ characters. <ENTER> means press the Enter key on your keyboard.

The program buildscl will create a scl file that is the same prefix as your terrain file (i.e., buildscl myTerrain.flt will generate the file myTerrain.scl).
4. Generate the optimized files for use on the Minisim simulator. Open a command line in the flt output folder. Type in the following command:
'''buildbatchlist''' <DB_NAME> <ENTER>

To automatically execute the optimization script, include the execute flag on the command line:

buildbatchlist <DB_NAME> -e <ENTER>

The script will create a command file (do.bat) that will process all the flight files in your output flt folder.

To manually execute the optimization command file on the command line:
'''do''' <ENTER>

The command line will process all the flight output files. When this is complete you will navigate up one folder level to prepare for processing the LRI file.
cd .. <ENTER>

*NOTE – this is two periods, which means “go up one level”.

**NOTE – if you forget to generate optimized files for the simulator the database installer script will not complete.

== '''Output for Correlated (Logical) Database''' ==

1. After you have generated the visual database and a .scl file and optimized the flight output, create the correlated virtual environment database. From the TMT™ Output menu, choose: Output Scenario/Visual Data and this time, disable all the OpenFlight™ Output options. Although you may enter a different output prefix, it is easiest to maintain projects if the default file name is used for both the terrain database.mos and the correlated virtual database.lri file.

A DOS window will display the status of the LRI build. Because this window is not persistent, if there are any error messages you wish to save you must collect them from the window using the quickedit mode: select the text you wish to save, and press <ENTER>. This places the text into a buffer, which you can now use to paste into a text log file for later use.

The most typical error will be a warning that a .summary or .scl file has not been found. In that case, you can proceed with the correlated virtual database build but no switches will be available to author. To correct this, simply follow step2 from Output for Visual Database located above, and then re-output the correlated virtual database file.

2. Navigate to the world/project folder. If you have a DOS window open to the FLT directory already, to move up one directory you can enter:
cd ..<ENTER>

3. From the DOS command window, enter the following:
'''mlri''' <database><ENTER>

This will cause a script to convert the ASCII correlated database .LRI file to an optimized binary form. This script will copy your database BLI file for use within ISAT to the ISAT directory. If you wish to see the script command commands necessary to convert the LRI file, simply enter:
'''mlri''' <ENTER>

and the script will echo the command and parameters in the DOS window.

== '''Test the New Database''' ==

Just because a database can be built, and the BLI can be read by ISAT, does not mean the road network is entirely valid and drivable. Testing can validate the database for simulated traffic and the External Driver (XD).

To test the database, place an ADO on the roadmap/BLI in ISAT and extend a path over the entire route that the XD is intended to drive. If ISAT cannot build a path over the entire route then there is some problem in the BLI to resolve. It is likely that the point where the path ends is where simulated traffic will die during simulation and disappear from the scene.

Reasons for this include:
# Forcing two tiles together in the TMT that do not share the same road characteristics (number of lanes, elevation).
# A problem in a tile on either side of the location where the path ends.'
# some other as yet unknown condition.

A successful path is only the first step. To be sure that you have a working database it is necessary to drive the desired route on the miniSim. Ideally you would start the driver just behind the test ADO, and use a Maintain Gap or Force Velocity action to keep that test ADO in sight throughout the drive.

Note: if the ADO is on a forced velocity and the XD speed exceeds the limit of what the ADO can support for cornering, it may disappear as a result.

When both the test ADO and XD arrive at the end of the drive, it is safe to say the database is valid and ready for scenario authoring.

Note: Authoring scenarios and then making changes to the BLI can invalidate the scenario, so testing should be the first thing to do when starting a new project with a new database world.

== '''Database Use Within ISAT''' ==

Following the successful creation of the visual and logical world, you will be able to open the world BLI from ISAT to create scenario events and conditions using your new database. The build process automatically copies the .BLI and .placeholder support file into the %MINISIM_ROOT%\Data/ directory. You can also access the primary files from the Projectdata\Databases/ directories. Care should be taken to maintain one pristine copy of files for development, and where necessary, backup copies should be made prior to major changes to your scenario (.SCN) files.

== '''File Transfer to MiniSim™''' ==

Database worlds that are created using the TMT™ must be copied into the MiniSim™ directory tree before they are available for use within the MiniSim™ simulator.

A script has been provided to copy files for user convenience, although it is advisable to be aware of the various file types and locations where these files are to be placed for proper configuration.

To install a database world, run the following script from the database directory:

'''dbinstall''' <DB_NAME><Minisim™ Version Number><ENTER>

This script expects the database files will be available from the location the script is activated, which means the default configuration as installed and described in this document. In the event of an error, the script will discontinue operation and inform the user it has encountered a problem.

'''NOTE:''' Non-standard file locations may cause the installation script to fail.
The following files are copied (version refers to the installed software version number):

DB_NAME.scl C:/MiniSim™_version/bin.x64/

<nowiki>*</nowiki>.FLT/*.IVE C:/MiniSim™_version/visuals/db_name/

DB_NAME.BLI C:/MiniSim™_version/data /

DB_NAME.FTR C:/MiniSim™_version/bin.x64/

'''TMT™ Reference'''
Help: There is currently no online help feature available for the TMT™.

== '''Associated file set''' ==

The Tile Library contains a number of related files, all of which are necessary to the use of the TMT™ and creation of Minisim™ environments:

# allTiles.txt – this text file contains a list of the tile library tiles and categories (configuration file for the TMT™).
# CD1 – A text file containing a list of the Tile Library Tiles used in the MOS.
# CD2 – A text file that defines the connective edges between tiles.
# DDS – these are compressed texture files for use on the MiniSim™.
# FLT – These are binary OpenFlight™ files that contain geometry and references to image texture files. These files are necessary for MiniSim™ simulator operation.
# FTR – This is a TMT™ support file that contains all the tile references necessary for a terrain configuration including XYZ offset, rotation, and tile category type. This file is necessary for MiniSim™ simulator operation.
# ICN – this is a binary file that is used for the TMT™ tile icon.
# Intersection.map – a text file that contains terrain data and specifications for unique elevation maps applied inside intersections.
# IVE – these are binary converted files optimized for MiniSim™ use.
# JPG – this is a binary snapshot view of the tile from an overhead view.
# LatProfileList.lat – this text file contains all the lateral specifications for every road type. It includes a cross-section profile and a material code index.
# MOS – this binary file is a TMT™ project file, also referred to as a world or project file.
# PATH/CORR – these are text data files that contain coordinate data describing either roads or intersection corridors.
# PET – this text file contains logical database tag information.
# RGB, RGBA, DDS –binary image texture files. The RGB and RGBA files may also have associated .attr files: these files are produced from the modeling environment tools and are not currently used by the TMT™ or MiniSim™. However, the RGB, RGBA and DDS files are necessary for MiniSim™ simulator operation. These files will already be present in the MiniSim™ configuration, but additional (new) files must be copied to the proper location.
# SUP – this binary file is used by the TMT™.
# SurfaceMaterialSpecifications.xlsx – an Excel™ document that contains surface material codes for road surfaces.
# tileSizes.txt – this text file contains a list of tile library tiles and their dimensions, given in Tile Units (increments of 660 ft; a 1 x 1 tile = 660ft x 660ft). Secondary configuration file for the TMT™.
# TXT – this text file contains TMT™ information. The TXT file will be updated when the binary FLT file changes, and should remain read/write. If you want to force the TMT™ to re-process the tile library or any particular tile, delete the TXT files and the TMT™ will re-create them.

== '''Included Databases''' ==

The following is a list of databases installed with the TMT™ with general descriptions:
# day_night_01: A long environment containing urban, residential, highway and rural environment. This database is designed for day or night use from the highway to rural area only. The urban environment is a night-only area.
# day_night_snow_01: The same environment as day_night_01 but with snow effects and roadways for the highway and rural roads.
# nadsdemo_dsc: A demonstration database containing dry, wet, and snow environments. This database includes a small urban area, a small rural area, and a small mountainous area.
# nadsdemo_geospecific: A small, geo-specific database built to match a real-world location in Iowa.
# nadsdemo_kiosk: A small, geo-typical database containing 3 separated environments. Contains rural and urban environments.
# simple_rural1: a basic, small rural environment
# simple_rural2: a basic, small rural environment with unique tiles enabled.
# rural_long: A simple rural environment intended for longer simulation drives. It begins with a long, straight roadway and contains varying curves and hills, with some intersections and one cross-road.
# test_all: A database that contains all the TMT tiles. Tiles are connected to each other for each category, and connections have been forced. This makes it possible to create a scenario for each tile category and to drive all the tiles, to become familiar with each tile and roadway type. The original tile orientation has been preserved where possible. Each tile category reads from top to bottom, left to right where possible.

<image_here>

== '''Database Creation Guidelines''' ==

Using the TMT™ it is possible to overload the visualization capacity of the MiniSim™. A few common sense rules will help to avoid that situation:

# Build only what you need. If your scenario requires 3 miles of highway driving, there is no point in building a ten mile stretch of terrain database. Keep the region of interest (ROI) or gaming area extent reduced to the smallest necessary footprint.
# Fewer larger tiles are more efficient than many smaller tiles. If you need 3 miles of highway, do not create a terrain that uses a small 1x1 tile to make the longer road.
# If you cannot see it from the road, don’t include it in the terrain. If something will never be visible, why include it in the terrain? There is one caveat: sometimes you will want to enclose the ROI such that it is not possible to see beyond the terrain edge. You will enclose the terrain using filler tiles, which are designed to block the view. These are secondary tiles with very little detail, small amounts of features and no drivable roads.
# Adjust the load for optimal performance. Even if you follow these guidelines, you may still bump into processing limitations. You can modify each tile within the TMT™ to display only when it is visible to the driver, and to turn off when it is not. This is accomplished by using level of detail (LOD). Each tile contains an LOD that is controlled from the TMT™ to permit the terrain database author to disable or enable tiles as needed to ensure consistent performance.
# Although the TMT™ itself does not enforce a rule, mixing coordinate units within the same terrain database is likely to cause problems. All tiles in the TMT™ Tile Library were constructed with units = feet, using the right-hand rule of coordinate systems: X increases to the right, Y increases forward, and Z increases upward.
# Forcing tile edge matches: although you can force a match in the TMT™, almost always you will not want to as it is likely to create problems within the visual terrain or logical database. A rural road that is forced to match an urban road will appear OK in the TMT™, but when you drive that database you will see how different the two road types are, and how the rural tile edge contains a different elevation profile than the urban edge. Use a transition tile to change from one road type to another instead of forcing these types of matches. There are only a few road types that can be forced that will still look and work due to their construction, profile and lane information.

'''Note: ''' After you have begun authoring scenarios, it is no longer trivial to change the terrain database. This is due to the internal data structure elements of the SCN and BLI files. The best approach is to finalize the road network configuration prior to scenario authoring activities.

== '''Script Utilities''' ==

A number of script utilities have been developed to assist with the terrain generation process. These files are located within the utils directory. In addition to the scripts mentioned within this document, the following scripts are included:

*lg.bat – This script will generate an LRI file from within the database project folder. In order to use this script the TMT™ must have already published the tile models, and the user should also have created the db_world.scl file from the TMT™ tile models located in the flt folder. This script is run from the same folder location as the db_world.mos file.

*mlri.bat – This script will generate a .BLI file from a .LRI file, and is run from the same folder as the db_world.mos file. The lri file can be published from the TMT™ or created using the lg.bat script.

*view.bat – This script allows the user to review an object or tile model without having to create a database and scenario and driving them on the MiniSim™. The viewer is only for reviewing models, it cannot be used to review a scenario. This command should be run from a command (DOS) window that is opened to the folder containing the models to be viewed. In the event this command does not work, the user should run nadsconfig_system.bat and then use the osg_viewer.exe application to view the model, and then communicate the script failure to NADS so the error may be corrected.

== '''Lessons Learned: Things that can go wrong''' ==

Although the terrain creation process is fairly streamlined, a number of issues may arise that could lead to problems. Mitigation strategies are provided to get you back into production:

# Test every road map. Just because the TMT produces a database does '''not''' guarantee the result is a completely drivable road network. [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=TMT_Troubleshooting_Guide_(all_versions)#ADOs_Can.27t_Travel_On_Sections_of_the_Road_Network Test to make sure that it is.]
# Every time you make a new build, generate both the visual and logical databases together. This is because there are no versioning schemas built into the TMT™, so it is necessary to re-generate all your files for a build in the same session. This has the highest chance for success. Often when a terrain control is not operating the way you think it should, the issue can be traced back to a mismatch between the visual and logical databases.
# Use a script for consistency. To repeat procedures over and over again with a consistent approach, use a script to ensure that you are using the commands and command line options the same way every time you perform a build.
# Do not copy/paste large areas using the TMT™. This can create corrupted terrain databases. Once a terrain file has been corrupted, there is no way to recover it. By saving a terrain database as another file, you can jump-start the construction process and provide yourself with a backup file at the same time. Copy/paste multiple tiles can be combined with rotation.
# To control objects in the environment (signs, traffic signals, etc) it is necessary to ensure the database world has been created using the “Unique Tiles” option, as described in the section Controllability: Unique vs. Generic Functionality (p10).

NOTE: You can have multiple TMT™ sessions open at once, using one database as a reference for LOD settings while building a second database.

== '''Unwanted collisions during simulation''' ==

If collisions are encountered with invisible objects during simulation - ie, there is no apparent source for the collisions, or if there are many collisions happening - the procedure involves:
1. Identify the tile containing the collisions. A coordinate is helpful for this, which can be determined from ISAT (reported on the status bar) or miniSim (has to be enabled).
2. Review the tile.pet file for Objects.
3. Each Object in the tile.pet will reference a sol2 object.
4. Locate the sol2 object from #3 then find the CollisionSoundID record.
5. Any positive number will enable collisions. To disable, replace the value with -1.

Note: If the object is not found in the sol2.txt file, then search all sol2_aux*.txt files.
Note: Remember to copy the modified file to ISAT\data if you are editing the file in NadsMiniSim_x.x\data (and vice-versa) to maintain consistency.
NOTE: You must exit miniSim and/or ISAT before making changes to system configuration files.

[[File:determine_and_disable_collision_objects_02052021.jpg|400px]]

=Appendix A=
==Obsolete and compatible tile models==

Do '''NOT''' use obsolete tile models - instead, locate the compatible tile model and use that instead. Obsolete models are included solely to avoid potentially corrupting existing world.mos files.

{|
|+ Obsolete and compatible Tile Models
|-
|Obsolete Tile|| use -> ||Compatible Tile
|-
|2ln_city_06
| is now:
|'''2ln_rural_4ln_city'''
|-
|2ln_4ln_trans_01
| is now:
|'''2ln_rural_4ln_rural'''
|-
|2ln_res_rural_trans
| is now:
|'''2ln_rural_2ln_res'''
|-
|urban_4ln_trans_01
| is now:
|'''5ln_urban_4ln_urban'''
|-
|fway_3LN_2ln_Trans_01
| is now:
|'''2ln_fwy_3ln_fwy'''
|-
|rural_2ln_gravel_trans_01
| is now:
|'''2ln_rural_2ln_gravel'''
|-
|suburb_trans_rural_01_night
| is now:
|'''4ln_suburb_2ln_rural_night'''
|-
|suburb_trans_rural_01
| is now:
|'''4ln_suburb_2ln_rural'''
|-
|4ln_city_1x1_BL_Trans01
| is now:
|'''4ln_city_4ln_BL_city'''
|-
|fway_trans_4ln_01
| is now:
|'''2ln_fwy_4ln_urban'''
|-
|fway_trans_rural_01
| is now:
|'''2ln_fwy_2ln_rural'''
|-
|fway_trans_4ln_2ln_01
| is now:
|'''2ln_fwy_4ln_fwy'''
|-
|fway_3LN_3LnUrban_trans01
| is now:
|'''3ln_fwy_3ln_urban'''
|-
|4ln_BL_rural_trans01
| is now:
|'''4ln_BL_urban_2ln_rural'''
|-
|4ln_rural_4ln_trans_01
| is now:
|'''4ln_rural_2ln_fwy'''
|-
|BLVD_4ln_trans_01_20
| is now:
|'''4ln_BLVD_4ln_urban_e20'''
|-
|fway_3ln_2ln_trans_03
| is now:
|'''2ln_fwy_3ln_fwy'''
|-
|rural_2ln_gravel_trans_02
| is now:
|'''2ln_rural_2ln_gravel_02'''
|-
|rural_trans03
| is now:
|'''2ln_rural_2ln_rural_no_shoulder'''
|-
|rural_trans01_3Mto12f
| is now:
|'''2ln_rural_3M_rural'''
|-
|rural_trans02_10fto12f
| is now:
|'''2ln_rural_2ln_rural_10f_lane'''
|-
|urban_6ln_4ln_transition
| is now:
|'''6ln_urban_4ln_urban_night'''
|-
|urban_6ln_4ln_transition_day
| is now:
|'''6ln_urban_4ln_urban_day'''
|-
|2ln_3way_rural_res01
| is now:
|'''2ln_rural_2ln_res_3way'''
|-
|4ln_city_1x1_BL_Trans01C
| is now:
|'''4ln_city_4ln_BL_city_ROT_C'''
|-

|}

=Appendix B=
The following is a partial list of applications used to support the creation of TMT™ compatible 3D models and textures. There are many programs available. The basic requirements necessary are the ability to create texture-mapped 3D geometry and the meta-data files containing simulator data. These files may be examined in the ProjectData\Tiles folders installed with the TMT™.

A. Graphics Programs
• Adobe Photoshop™ or CreativeSuite™
• GIMP™
• Painter™
• Any other raster editing graphics application

B. 3D Programs
• Presagis™ Creator
• Autodesk Maya™
• Autodesk 3D Studio™
• Google Sketchup™
• Any other 3D application capable of applying and saving textured 3D models
C. Conversion Programs
• Deep Exploration™
• Okino PolyTrans™
• Export from 3D Program

'''NOTE:''' Currently in order to use your models within the TMT™ to produce terrain databases, it will be necessary to utilize some form of conversion software to convert from the application native or export format into OpenFlight™.

TMT User Guide (versions 1.8 & greater)

2023-11-30T16:03:19Z

Shawn Allen: /* Summary of changes in this version emphasize elevation map orientation info*/

<span style="color:red">This document is in beta 02.11.2020</span>

== Who should use this document ==
This document is for use with TMT version 1.8 or greater. Do '''NOT''' use this document if you are working with a TMT version less than 1.8.

== Summary of changes in this version==
This version of the Tile Mosaic Tool contains significant updates to the tile model library.

'''Elevation Maps'''
Elevation maps have been implemented on some tile model intersections. These are 3-D surfaces within an intersection. The primary characteristic of elevation maps is they support different surfaces within an intersection.

Elevation maps are one way to determine curb strikes within an intersection based on a surface material code (SMC).

<span style="color:red">'''NOTE:'''
Failure to use the correct rotation will produce a road network that ADOs cannot navigate because the elevation maps produce an offroad condition when the wrong rotation is used in the TMT.</span>

[[:File:elev_maps_20200211.jpg]]

'''NOTE:''' Elevation map intersections include a 'rotation key' in the tile name. Due to implementation requirements, it is '''required''' to rotate the tile model to the rotation specified.

'''Rotation Key'''

No code = 0 degrees
A = 90 degrees
B = 180 degrees
C = 270 degrees

'''NOTE:''' Tiles with intersection elevation maps that are not rotated (default rotation = zero degrees) are located in various tile categories. Only tiles containing intersections can contain intersection elevation maps.

'''Obsolete models'''
One significant change is that some tiles are now considered obsolete. Obsolete models are contained within the tile category 'Obsolete'.

It is '''strongly recommended''' that .MOS worlds using obsolete models be revised, as future versions of the Tile Mosaic Tool may not include those models.

<span style="color:red">'''If a world.mos file contains tile models that are missing from the library and it is saved, that .mos file will become corrupted.

There is currently no way to recover from this condition.'''</span>

The Obsolete tile category is included with this version to permit replacing obsolete models with compatible tiles. It is strongly recommended that obsolete tiles be converted to the correlated tile model.

A list of compatible models is included in the Appendix of this document.

''' Transition tile category'''

Transition tile models are now grouped into a new '''Transition''' tile category. If you require a transition between different roadway types, the Transition category is the place you will find it.

'''New tile models'''

Another change in this version is the addition of new tile models, listed below.

'''bike_lane'''
This is a new tile category. Tiles within the '''bike_lane''' category contain bicycle lanes, which are narrow lanes defined as Vehicle Restricted lanes. This definition is intended to prevent typical ADOs from using this lane.

However, scenario authors '''should be able''' to author pedestrian and bicycle models that will use the bike lane. In some cases it may be necessary to author scenarios using the standard road lane and apply a '''lane offset''' to shift the scenario object over into the target lane.

'''bike_lane tile models'''
#2ln_3Mi_01
#2ln_3Mi_02
#2ln_4way_3Mi_01
#2ln_4way_3Mi_02

'''NOTE:''' Bike lanes are not necessarily included as a separate network adjacent to the road network. At this time they are an attribute of the road.

'''city tile models'''
#4ln_city_1x1_02
#4ln_city_1x1_crv90_02
#6ln_4way_01
#6ln_4way_02
#6ln_city_straight_01
#6ln_city_straight_02

'''comm tile models'''
#2ln_4ln_3way_comm_02
#2ln_4ln_3way_comm_03
#4ln_4way_comm_01
#4ln_comm_straight
#4ln_comm_straight_04
#4ln_comm_straight_05
#4ln_res_3way_comm
#4ln_res_hill_curve01

'''filler tile models'''
#gen_common_3x5
#urban_01
#urban_02
#urban_03

'''fwy tile models'''
#fway_2ln_04
#fway_2ln_10k10kS_01
#fway_4ln_2ln_DTL01
#fway_4ln_straight_13x17

'''railroad tile models'''
#railway_1xgrade_rural_01
#railway_1xgrade_rural_02
#railway_1x_straight
#railway_3xgrade_city_01
#railway_3xgrade_rural_01
#railway_3xgrade_rural_02
#railway_3x_straight
#railway_4ln_city_01
#railway_90
#railway_straight

'''res tile models'''
#2ln_res_mult_school
#2ln_res_rural_trans
#2ln_straight_res
#2ln_straight_res_2
#res_2ln_3way
#res_2ln_3way_02
#res_3way
#res_3way_02
#res_90
#res_straight

'''rural tile models'''
#2ln_3way_rural_res01
#4ln_1mi_02

'''suburb tile models'''
#suburb_2mi_01
#suburb_90_01
#suburb_Scurve_01

'''transition tile models'''
#2ln_fwy_2ln_rural
#2ln_fwy_3ln_fwy
#2ln_fwy_3ln_fwy_02
#2ln_fwy_4ln_fwy
#2ln_fwy_4ln_urban
#2ln_rural_2ln_gravel
#2ln_rural_2ln_gravel_02
#2ln_rural_2ln_res
#2ln_rural_2ln_res_3way
#2ln_rural_2ln_rural_10f_lane
#2ln_rural_2ln_rural_no_shoulder
#2ln_rural_3M_rural
#2ln_rural_4ln_city
#2ln_rural_4ln_rural
#3ln_fwy_3ln_urban
#4ln_BLVD_4ln_urban_e20
#4ln_BL_urban_2ln_rural
#4ln_city_4ln_BL_city
#4ln_city_4ln_BL_city_ROT_C
#4ln_rural_2ln_fwy
#4ln_suburb_2ln_rural
#4ln_suburb_2ln_rural_night
#4ln_urban_6ln_urban_day
#4ln_urban_6ln_urban_night
#5ln_urban_4ln_urban

'''urban tile models'''
#4ln_urban_4x8_01
#urban_2ln_4ln_s1400A
#urban_4ln_arterial_02
#urban_4ln_straight_01

=='''Introduction'''==

The Tile Mosaic Tool (TMT™) was created to build visual and virtual correlated databases, a process generally known as world or database generation. The TMT is used to arrange tile models into a configuration (world). Tile models typically contain roads, terrain and feature objects. The construction of these elements and additional models and textures require the use of 3rd party software for the creation of textured 3D models. At the present time, only OpenFlight™ models and RGB format image files are supported by the TMT. Many commercially available (and many shareware or free) 3D programs can also be used for tile creation, but their output will need to be converted to OpenFlight™ format for use within the TMT. For a partial list of applications, please see Appendix B.

== '''Command line Syntax/Conventions''' ==

In this document the following conventions are used for command line interaction. #Information enclosed within bracket characters <like_this> is for user input.
#The phrase <ENTER> means that the user should press the Enter key, not to type in the word.
#Where the percent character is used to enclose a string, it indicates an environment variable or environment variable value.

== '''Getting Started''' ==

The TMT tile library contains of a number of related model files which reside on your computer. It is necessary that all tiles reside below a single parent directory (folder). Within this top-level directory, sub-directories are used to divide the tile library into different categories. Currently these categories consist of tiles with similar characteristics, but you are not limited to these. Additional tile categories may be created under the top-level directory. It is recommended that you do not change the basic tile category set, but you are able to add new tiles to existing categories, or create new categories for your tiles at any time.

'''NOTE:''' Each tile model must be unique – you should not have two tiles within the library with the same name, even if they are in different categories.

Start the TMT by double-clicking the icon. You may want to open existing database worlds, or create a new world (terrain database). To create a new world, choose New from the File menu (File >> New). If the TMT has not been used on this computer before, you’ll have to preprocess the tile library in order to proceed. Click Preprocess to load the tile library. This procedure will occur only when the TMT is first used on your system, or when a tile geometry file (.FLT) has been modified. The TMT loads the Tile Library automatically in normal use.

To open an existing terrain database/world file, choose File >>Open and navigate to the database location on your computer.

The TMT workspace window will appear. To place tiles into the terrain database, use the category tabs on the left to choose a tile category, and select a tile from the list by clicking with the left mouse button (LMB) on it. This will “attach” the tile to the cursor. Move the mouse to the right onto the terrain and position it, then LMB on any open grid to place the tile. The TMT will attempt to snap the placed tile onto the terrain grid. For more precise positioning, enable the terrain grid View >> Draw Attributes >> Grid and position the tile within the gridlines.

You can rotate a tile while it is attached to the cursor by pressing any key.

'''NOTE:''' When you are placing tiles onto a terrain that already contains tiles, the tiles will attempt to connect only where tile edges are the same. For example, the default tile edge is GEN (for General or Generic). A GEN edge will not match with any other edge unless it is forced. Although you can force tiles together, this is a procedure that has larger ramifications and can create visual and logical discontinuities and errors. Forcing tiles should be carefully considered.

When you are finished placing tiles, save the world file. Choose File >> Save and navigate to the directory location you wish to save the file set to. Because each world consists of multiple files, it is good practice to segregate them into their own unique directories. The Database directory installed with the TMT is a good location. For testing purposes, you may choose to use a single default “scratch” directory when doing rapid-cycle development or debugging and simply over-write the files repeatedly until a desired configuration is achieved.

'''NOTE:''' Avoid the use of spaces in the folder path to the TMT project files, as this can create problems for various TMT script utilities.

'''NOTE:''' To force/override the tile placement function, press and hold CTRL-SHIFT as you place the tile. This procedure will not allow you place a tile on top of another; it will however allow you to place two tiles together when their edges do not match.

'''NOTE: Each road map created in the TMT must be evaluated in ISAT to determine if the map is good and traffic can travel on all sections.'''
The simplest way to test for a valid road network is to use ISAT and an ADO lead vehicle that drives across all road sections you plan to use during your simulation.

The ADO path should look like the intended drive path for your external driver/XD.

You can set a set Dial >> ADO >> Force Velocity action on the lead vehicle to maintain a consistent headway gap relative to the XD. This will allow you to see if there is a problem in the road network.

Run the test scenario in ISAT rehearsal mode and see if the lead vehicle can navigate the entire road network. Following a successful rehearsal, drive the scenario in miniSim and see if the results match. If the lead vehicle disappears in either case, review the road network in ISAT following the above guidelines.

=== '''Creating Output''' ===

The process of building and driving a world on the miniSim is:

# Produce a terrain map by placing tiles on the workspace to create a road network using the TMT.
# Output the visual files using the TMT.
# Create a scenario control list (SCL) file using the command line.
# Create a logical road information (LRI) file using the TMT.
# Convert the LRI file to an optimized form (BLI) for ISAT and MiniSim using the command line.
# Convert the visual files to an optimized format using the command line.
# Install all required files on the miniSim using the install script.
# Create a scenario that uses the world and save it to disk. At a minimum you need to place an external driver on any roadway. You can also set the ownship cab type using ISAT.

'''NOTE: All steps must be completed in order to view the created world on the MiniSim simulator.'''

To generate files for use on the miniSim, you will use the TMT Output menu. Environment creation workflow consists of building the visual database first. The miniSim will render these output files after they are optimized and installed. You must also process these visual files to produce a scenario control list (SCL) file. After the SCL file has been created, you can choose Output >> Scenario LRI file from the TMT to create a Logical Road Information (LRI) correlated database file. It will be necessary to convert the LRI file into a Binary LRI file (BLI), since that is the format the miniSim uses during simulation. It can be useful to be able to read the text form of the LRI file when troubleshooting problems with the world output process.

Conversion of the output flt files to an optimized format for use on the miniSim happens with a two-step process. First a command list is created in the flt folder, and then that file is processed to generate the required files.
The database is ready for visualization on the miniSim when all the files have been installed.

== '''Tile Library Contents''' ==

The Tile Library has been designed as an open-ended, extendable library of re-usable components. Tile models are a different class of model from model objects such as signs, vehicles or virtual objects. Tile categories are intended to provide a coarse level of differentiation between tiles with different features (culture). Generally, tiles will contain roads, roadway markings, terrain and vegetation. More complex tiles will include signage or traffic control devices such as traffic signals, railroad crossing signals, and general signage. In most cases, signs and traffic control devices are designed to be operated during simulation, which means they may be authored in ISAT to change appearance either during simulator initialization (i.e., changing a stop sign to a yield sign), or change dynamically during simulation (i.e., traffic light state changes from red to green to yellow).

'''NOTE:''' Tile Library content may be added to at any time without affecting previously constructed terrain databases. However, it is important to understand that scenario events are closely coupled with geographic locations within the world. Changing a world after scenario authoring has begun or following authoring completion may result in unexpected results or even failure to load or run the scenario in ISAT.

Typically it is possible to change a portion of the road network if there are no scenario paths or elements on that portion. Extending a road network beyond an intersection will not affect the road network on the upstream side of the intersection.

[[File:tmt_adding_to_existing.jpg|400px]]

This example assumes there are no scenario authored objects, events or paths in the areas modified by the addition of tile models to the original design.

'''NOTE:''' Tile models require additional development for night rendering effects. Not all models in the library contain these effects.

Tile categories include:

# City
# Comm (commercial features)
# Elev_maps (models contain elevation maps)
# Filler (borders, panoramas and fillers)
# Fwy (freeway)
# Ind (Industrial features)
# Mtn (Mountain)
# Obsolete (these tiles should not be used)
# Railroad (includes a rail line)
# Res (Residential)
# Rural (Countryside)
# Rural_bike_lane (rural tiles with bike lanes)
# Special (Tiles which are non-standard in some way, or project-specific and not intended for general-purpose use)
# Suburb
# Transition (tiles that connect between different road types and lanes)
# Urban

Due to the nature of the visual and virtual correlated databases, special effects such as wet or snow environments have been constructed as specialized tiles, with the intended effect built into the tile model.

Time of day is a more general simulation effect, although for some complex tiles, a lighting effect has also been built into the tile. These special-function tiles are identified by keyword within the tile name (wet, day, night).

Although it is possible to use day tiles at night or vice-versa, the resulting database may appear odd and incongruous to the viewer.

Additional tile categories may be created by editing the alltiles.txt TMT configuration file located in the ProjectData\Tiles\ directory.

=== '''Tile Model Naming Conventions''' ===
As the tile library grows, it is useful to know how the tile model name is constructed.

Tile model names are intended to provide some clue as to the nature or content of the tile, without requiring the user to actually view the model. Viewing the model is, of course, a really great way to become familiar with the model.

Here are a few examples:

*2ln_city_01
**2 lane road, tile version 1
*2ln_city_1x1_crv90_01_20
**2 lane road, road bed is a 90 degree curve, tile version 1, 20f elevation
*2ln_city_4way_20
**2 lane road, 4 way intersection, 20f elevation
*4ln_2x2_Hill_02
** 4 lane, 2x2 tile (1320f x 1320f), tile version 2

'''NOTE:''' elevated tiles <span style="color:red"> '''WILL NOT''' </span>connect to standard tiles. You will require a hill tile to connect elevated and standard tile models. Forcing connections to these tiles is not advisable '''unless''' the connecting model has the same elevation.

'''NOTE:''' Tile versions are typically small variations from earlier version models. However, they may be completely different content on a similar road layout.

'''What happened to version <u>x</u>?'''
<ul>In cases where there is a missing version number, chances are that tile version is either not yet developed, or the missing version was left out of the TMT for some reason. There is no requirement that model versions be sequential, it just a mechanism to help classify a model.</ul>

== '''Compatible Tile List''' ==

This command provides a list of tiles which are compatible in terms of edge specifications for placement at an open grid location in the terrain database. You must select an open grid location adjacent to a placed tile to use this command.

#Select a grid location.
To select a grid location, double click (DBL) the grid location. That selected grid location will draw a yellow outline, indicating it has been selected.

[[File:TMT_selected_grid.jpg|400px]]

#RMB >>Compatible Tile List or Edit >> Compatible Tile List. A dialog will list all compatible tile choices for the selected grid location.

[[File:TMT_selected_grid_compatible.jpg|400px]]

Tiles are listed in terms of tile name, rotation, size and category. Select a compatible tile by LMB a Tile Name in the dialog. To place the compatible tile into the terrain, LMB the Apply button. The tile is placed at the selected grid location in the terrain. You can continue to choose other tiles from the dialog and apply them to the terrain until the desired tile has been placed. LMB OK to close the dialog or Cancel to cancel.

== '''Manual Tile Placement''' ==

The most common way to create terrain databases in the TMT is by placing the tiles manually. This provides the greatest control over creating the exact road network desired for simulation. After a tile has been placed in the database, you can edit the tiles to meet specific requirements* through the use of ISAT to change features that were created as configurable features.

'''Note:''' Editing the source tile model requires the use of a 3D editor. Tile editing and 3d modeling is outside the scope of this document.

To manually place tiles, choose a tile category from the left panel. Select a tile and LMB on the icon. Move the cursor to the right side, into the terrain layout. You can rotate a tile by pressing any key. Click on an open grid location to place the tile. To detach the tile from the cursor, move the cursor to the edge of the terrain database window.

The TMT will prevent placement if the following conditions occur:
1. You are attempting to place a tile onto another tile.
2. You are attempting to place a tile where the tile edge does not match. The TMT will turn the placed tile edge red when this happens, indicating an invalid edge match.

NOTE: You can override the edge match by pressing '''CTRL AND SHIFT''' when placing the tile. Be aware this can cause discontinuities and visual mismatch when you override edge matching.

After a tile is placed, you can modify the orientation by invoking commands from the Edit menu, RMB or Tool Bar.
1. Select a tile or group of tiles in the terrain database.
2. Choose a function from the Edit menu, RMB menu, or Tool Bar.

== '''Auto Tile Placement''' ==

You can fill in defined areas in the terrain database using automatic tile placement, which is used when no particular configuration is desired and a large region of coverage is desired. From the Auto Tile Placement dialog, you can choose tile categories and individual tiles within each category for placement. Tile placement is based upon a weighting factor which is controlled by this dialog.

Selecting a grid area by DBL at an open grid location. If properly selected you will see the terrain grid outlines in yellow. Move the cursor to another location, holding the SHIFT key, and LMB again at the new location. You will see a region of terrain grid now has a yellow border, indicating a valid selection. Choose Edit >> Auto Tile Placing or RMB >> Auto Tile Placing.

[[File:TMT_Auto_placement.jpg|400px]]

NOTE: if a grid area is not properly selected the command will not enable.

The Auto Tile Placement Control Dialog will appear. The dialog has two parts:
# Category selection and adjustments
# Library tile placement and adjustments

In the Category selection and adjustment area, choose the tile categories you wish to use for auto tile placing. You can select multiple categories, or LMB Select All. When you have chosen tile categories, LMB the Add button. Use CTRL to select discontinuous categories, or SHIFT to select a continuous list of categories. You can also remove single or multiple categories from the destination list.

In the Library Tile Selection and Adjustments section, you can choose the library tiles you wish to use in auto placement. Tiles within the selected Tile Categories appear in the source (left bottom) window. You can use Select All, Add, Remove and Clear buttons for both Tile Categories and Tiles. Adjust the weighting factors of each tile by using the slider bar. The Optimal Tiling button applies higher weights to tiles that have the most common edge specifications among the list of tiles chosen. Click OK to apply the settings to automatically place tiles within the terrain. Cancel will cancel the auto tile placement command.

== '''Controllability: Unique vs. Generic Functionality''' ==

The MiniSim™ uses scenario control software to control individual components within a tile (ie., changing a traffic light or sign). But what happens when there is more than one tile reference of the same tile within the terrain database? In order to control each model component, tiles must be flagged as a unique tile instance. This is achieved by enabling the Unique Control setting in the TMT™ (the traffic light icon) and then enabling Unique Control for a tile or selection of tiles.

'''NOTE:''' Unique control options in the menu are disabled until the Unique Control Mode is enabled in the TMT.

Select a tile by LMB or a group of tiles using fence select. RMB >> Enable/Disable Unique Control (Selected Tiles) or Edit >> Enable/Disable Unique Control (Selected Tiles). A uniquely controlled tile will display a small green X in the terrain layout view. Because this function is a toggle, to turn off unique control, you can disable all controls or for the selected tile using the same menu as enable.

=== '''When are Unique Controls necessary?''' ===

Unique controls are '''not''' necessary if there are no controls available within the tile!

However, if a tile contains SWITCHES, then the tile has been built to support changes to the simulation scene from scenario control. For example, some tiles contain street signs. It is often desirable to have a world contain unique street names. If the world is built with Unique Controls enabled, then a scenario author may adjust each street sign to a different name using the Interactive Scenario Authoring Tool (ISAT). This mechanism is used for all cases where a change in appearance is desired within the terrain tile.

'''NOTE:''' The TMT will output a file for each Unique Control tile.

'''NOTE: Turning a visual element off within a tile does not disable the CVED representation.''' Even if the object is not visible to the simulator driver, the object still exists.

This has implications if the miniSim is configured with collision effects enabled. In this case, '''driving into a visually disabled object will result in a collision.'''

Due to the nature of switch controls, it is possible to implement controllability for visual scene elements at any time. However, there is no corresponding capability for any applicable CVED representation.

For example, it is possible to create controllable road markings with different visual conditions (pristine, aged, off) but without additional programming CVED will not reflect this functionality. In this case, the CVED road marking representation will always be present, until the CVED code has been modified to support a variable condition road marking.

=== '''Load Management for Visual Databases''' ===

It is possible to create databases which will not perform optimally on the MiniSim™. To avoid this, adjust the visibility of terrain tiles by using the level of detail (LOD) node within each tile. More complex tiles may contain additional LOD nodes.

Right-click any tile and choose Tile LOD Settings… from the context menu. The LOD dialog will highlight each LOD in the configuration window as you select LODs from the list. You can change the Center, Switch Distance, Transition Range and Freeze flags for each LOD. Setting a small Switch Distance will cause the tile to display when the eyepoint approaches closer to the tile. Large values cause the tile to become visible over longer distances. Excessively long values, especially within complex environments, may contribute to performance problems.

It is most desirable to have terrain tiles visible only for the period they are needed. The LOD Center X, Y and Z values can be manipulated to shift the LOD so that the tile disappears behind curves. Thus, curve tiles are ideal for load management elements.

'''NOTE:''' Changing the LOD Center values will require the Freeze flag to be enabled. If the freeze flag is not enabled, the tile may not display as anticipated.

[[File:2021-12-03_10h56_40.png|400px]]

Notice how the curve tile LOD has been edited so the tile is not visible from the North-South road along the right side, and it is not displayed to the left of the large S-curve tile since it is unlikely the tile can be seen from that location anyway.

LODs can be adjusted significantly as needed, as shown below.
[[File:2021-12-03_11h35_39.png|400px]]

== '''Output for Visual Database''' ==

1. After a world has been developed and saved to disk, you can publish the visual database world to disk. From the TMT™ Output menu, choose Output Scenario/Visual Data. A dialog will appear. Disable the LRI flag, and use the default settings for OpenFlight Output.

'''NOTE:''' This will over-write the files located within the project flt directory; in the event you wish to retain these files, it is best to create a backup copy of the flt directory prior to generating output.

2. The next step is to generate a scenario control list for the terrain database/world that you've just generated. The SCL is a text file that lists all available switches, which can be authored using the ISAT. Without this file, although you can generate a world that will run on the MiniSim™, you will be unable to author objects within the environment such as street signs, traffic lights, etc.

Open a command window at the FLT directory. You can use the windows explorer to navigate to the Database directory under Favorites: Favorites >> ProjectData_Databases. Open the directory containing your database, then right-click on the FLT folder and choose “Open CMD here” from the context menu.

At the command window, enter:
'''buildscl''' <DB_NAME.flt><ENTER>

Remember that DB_NAME is the name of your .MOS world file (terrain database), and you do not type the ‘<’ or ‘>’ characters. <ENTER> means press the Enter key on your keyboard.

The program buildscl will create a scl file that is the same prefix as your terrain file (i.e., buildscl myTerrain.flt will generate the file myTerrain.scl).
4. Generate the optimized files for use on the Minisim simulator. Open a command line in the flt output folder. Type in the following command:
'''buildbatchlist''' <DB_NAME> <ENTER>

To automatically execute the optimization script, include the execute flag on the command line:

buildbatchlist <DB_NAME> -e <ENTER>

The script will create a command file (do.bat) that will process all the flight files in your output flt folder.

To manually execute the optimization command file on the command line:
'''do''' <ENTER>

The command line will process all the flight output files. When this is complete you will navigate up one folder level to prepare for processing the LRI file.
cd .. <ENTER>

*NOTE – this is two periods, which means “go up one level”.

**NOTE – if you forget to generate optimized files for the simulator the database installer script will not complete.

== '''Output for Correlated (Logical) Database''' ==

1. After you have generated the visual database and a .scl file and optimized the flight output, create the correlated virtual environment database. From the TMT™ Output menu, choose: Output Scenario/Visual Data and this time, disable all the OpenFlight™ Output options. Although you may enter a different output prefix, it is easiest to maintain projects if the default file name is used for both the terrain database.mos and the correlated virtual database.lri file.

A DOS window will display the status of the LRI build. Because this window is not persistent, if there are any error messages you wish to save you must collect them from the window using the quickedit mode: select the text you wish to save, and press <ENTER>. This places the text into a buffer, which you can now use to paste into a text log file for later use.

The most typical error will be a warning that a .summary or .scl file has not been found. In that case, you can proceed with the correlated virtual database build but no switches will be available to author. To correct this, simply follow step2 from Output for Visual Database located above, and then re-output the correlated virtual database file.

2. Navigate to the world/project folder. If you have a DOS window open to the FLT directory already, to move up one directory you can enter:
cd ..<ENTER>

3. From the DOS command window, enter the following:
'''mlri''' <database><ENTER>

This will cause a script to convert the ASCII correlated database .LRI file to an optimized binary form. This script will copy your database BLI file for use within ISAT to the ISAT directory. If you wish to see the script command commands necessary to convert the LRI file, simply enter:
'''mlri''' <ENTER>

and the script will echo the command and parameters in the DOS window.

== '''Test the New Database''' ==

Just because a database can be built, and the BLI can be read by ISAT, does not mean the road network is entirely valid and drivable. Testing can validate the database for simulated traffic and the External Driver (XD).

To test the database, place an ADO on the roadmap/BLI in ISAT and extend a path over the entire route that the XD is intended to drive. If ISAT cannot build a path over the entire route then there is some problem in the BLI to resolve. It is likely that the point where the path ends is where simulated traffic will die during simulation and disappear from the scene.

Reasons for this include:
# Forcing two tiles together in the TMT that do not share the same road characteristics (number of lanes, elevation).
# A problem in a tile on either side of the location where the path ends.'
# some other as yet unknown condition.

A successful path is only the first step. To be sure that you have a working database it is necessary to drive the desired route on the miniSim. Ideally you would start the driver just behind the test ADO, and use a Maintain Gap or Force Velocity action to keep that test ADO in sight throughout the drive.

Note: if the ADO is on a forced velocity and the XD speed exceeds the limit of what the ADO can support for cornering, it may disappear as a result.

When both the test ADO and XD arrive at the end of the drive, it is safe to say the database is valid and ready for scenario authoring.

Note: Authoring scenarios and then making changes to the BLI can invalidate the scenario, so testing should be the first thing to do when starting a new project with a new database world.

== '''Database Use Within ISAT''' ==

Following the successful creation of the visual and logical world, you will be able to open the world BLI from ISAT to create scenario events and conditions using your new database. The build process automatically copies the .BLI and .placeholder support file into the %MINISIM_ROOT%\Data/ directory. You can also access the primary files from the Projectdata\Databases/ directories. Care should be taken to maintain one pristine copy of files for development, and where necessary, backup copies should be made prior to major changes to your scenario (.SCN) files.

== '''File Transfer to MiniSim™''' ==

Database worlds that are created using the TMT™ must be copied into the MiniSim™ directory tree before they are available for use within the MiniSim™ simulator.

A script has been provided to copy files for user convenience, although it is advisable to be aware of the various file types and locations where these files are to be placed for proper configuration.

To install a database world, run the following script from the database directory:

'''dbinstall''' <DB_NAME><Minisim™ Version Number><ENTER>

This script expects the database files will be available from the location the script is activated, which means the default configuration as installed and described in this document. In the event of an error, the script will discontinue operation and inform the user it has encountered a problem.

'''NOTE:''' Non-standard file locations may cause the installation script to fail.
The following files are copied (version refers to the installed software version number):

DB_NAME.scl C:/MiniSim™_version/bin.x64/

<nowiki>*</nowiki>.FLT/*.IVE C:/MiniSim™_version/visuals/db_name/

DB_NAME.BLI C:/MiniSim™_version/data /

DB_NAME.FTR C:/MiniSim™_version/bin.x64/

'''TMT™ Reference'''
Help: There is currently no online help feature available for the TMT™.

== '''Associated file set''' ==

The Tile Library contains a number of related files, all of which are necessary to the use of the TMT™ and creation of Minisim™ environments:

# allTiles.txt – this text file contains a list of the tile library tiles and categories (configuration file for the TMT™).
# CD1 – A text file containing a list of the Tile Library Tiles used in the MOS.
# CD2 – A text file that defines the connective edges between tiles.
# DDS – these are compressed texture files for use on the MiniSim™.
# FLT – These are binary OpenFlight™ files that contain geometry and references to image texture files. These files are necessary for MiniSim™ simulator operation.
# FTR – This is a TMT™ support file that contains all the tile references necessary for a terrain configuration including XYZ offset, rotation, and tile category type. This file is necessary for MiniSim™ simulator operation.
# ICN – this is a binary file that is used for the TMT™ tile icon.
# Intersection.map – a text file that contains terrain data and specifications for unique elevation maps applied inside intersections.
# IVE – these are binary converted files optimized for MiniSim™ use.
# JPG – this is a binary snapshot view of the tile from an overhead view.
# LatProfileList.lat – this text file contains all the lateral specifications for every road type. It includes a cross-section profile and a material code index.
# MOS – this binary file is a TMT™ project file, also referred to as a world or project file.
# PATH/CORR – these are text data files that contain coordinate data describing either roads or intersection corridors.
# PET – this text file contains logical database tag information.
# RGB, RGBA, DDS –binary image texture files. The RGB and RGBA files may also have associated .attr files: these files are produced from the modeling environment tools and are not currently used by the TMT™ or MiniSim™. However, the RGB, RGBA and DDS files are necessary for MiniSim™ simulator operation. These files will already be present in the MiniSim™ configuration, but additional (new) files must be copied to the proper location.
# SUP – this binary file is used by the TMT™.
# SurfaceMaterialSpecifications.xlsx – an Excel™ document that contains surface material codes for road surfaces.
# tileSizes.txt – this text file contains a list of tile library tiles and their dimensions, given in Tile Units (increments of 660 ft; a 1 x 1 tile = 660ft x 660ft). Secondary configuration file for the TMT™.
# TXT – this text file contains TMT™ information. The TXT file will be updated when the binary FLT file changes, and should remain read/write. If you want to force the TMT™ to re-process the tile library or any particular tile, delete the TXT files and the TMT™ will re-create them.

== '''Included Databases''' ==

The following is a list of databases installed with the TMT™ with general descriptions:
# day_night_01: A long environment containing urban, residential, highway and rural environment. This database is designed for day or night use from the highway to rural area only. The urban environment is a night-only area.
# day_night_snow_01: The same environment as day_night_01 but with snow effects and roadways for the highway and rural roads.
# nadsdemo_dsc: A demonstration database containing dry, wet, and snow environments. This database includes a small urban area, a small rural area, and a small mountainous area.
# nadsdemo_geospecific: A small, geo-specific database built to match a real-world location in Iowa.
# nadsdemo_kiosk: A small, geo-typical database containing 3 separated environments. Contains rural and urban environments.
# simple_rural1: a basic, small rural environment
# simple_rural2: a basic, small rural environment with unique tiles enabled.
# rural_long: A simple rural environment intended for longer simulation drives. It begins with a long, straight roadway and contains varying curves and hills, with some intersections and one cross-road.
# test_all: A database that contains all the TMT tiles. Tiles are connected to each other for each category, and connections have been forced. This makes it possible to create a scenario for each tile category and to drive all the tiles, to become familiar with each tile and roadway type. The original tile orientation has been preserved where possible. Each tile category reads from top to bottom, left to right where possible.

<image_here>

== '''Database Creation Guidelines''' ==

Using the TMT™ it is possible to overload the visualization capacity of the MiniSim™. A few common sense rules will help to avoid that situation:

# Build only what you need. If your scenario requires 3 miles of highway driving, there is no point in building a ten mile stretch of terrain database. Keep the region of interest (ROI) or gaming area extent reduced to the smallest necessary footprint.
# Fewer larger tiles are more efficient than many smaller tiles. If you need 3 miles of highway, do not create a terrain that uses a small 1x1 tile to make the longer road.
# If you cannot see it from the road, don’t include it in the terrain. If something will never be visible, why include it in the terrain? There is one caveat: sometimes you will want to enclose the ROI such that it is not possible to see beyond the terrain edge. You will enclose the terrain using filler tiles, which are designed to block the view. These are secondary tiles with very little detail, small amounts of features and no drivable roads.
# Adjust the load for optimal performance. Even if you follow these guidelines, you may still bump into processing limitations. You can modify each tile within the TMT™ to display only when it is visible to the driver, and to turn off when it is not. This is accomplished by using level of detail (LOD). Each tile contains an LOD that is controlled from the TMT™ to permit the terrain database author to disable or enable tiles as needed to ensure consistent performance.
# Although the TMT™ itself does not enforce a rule, mixing coordinate units within the same terrain database is likely to cause problems. All tiles in the TMT™ Tile Library were constructed with units = feet, using the right-hand rule of coordinate systems: X increases to the right, Y increases forward, and Z increases upward.
# Forcing tile edge matches: although you can force a match in the TMT™, almost always you will not want to as it is likely to create problems within the visual terrain or logical database. A rural road that is forced to match an urban road will appear OK in the TMT™, but when you drive that database you will see how different the two road types are, and how the rural tile edge contains a different elevation profile than the urban edge. Use a transition tile to change from one road type to another instead of forcing these types of matches. There are only a few road types that can be forced that will still look and work due to their construction, profile and lane information.

'''Note: ''' After you have begun authoring scenarios, it is no longer trivial to change the terrain database. This is due to the internal data structure elements of the SCN and BLI files. The best approach is to finalize the road network configuration prior to scenario authoring activities.

== '''Script Utilities''' ==

A number of script utilities have been developed to assist with the terrain generation process. These files are located within the utils directory. In addition to the scripts mentioned within this document, the following scripts are included:

*lg.bat – This script will generate an LRI file from within the database project folder. In order to use this script the TMT™ must have already published the tile models, and the user should also have created the db_world.scl file from the TMT™ tile models located in the flt folder. This script is run from the same folder location as the db_world.mos file.

*mlri.bat – This script will generate a .BLI file from a .LRI file, and is run from the same folder as the db_world.mos file. The lri file can be published from the TMT™ or created using the lg.bat script.

*view.bat – This script allows the user to review an object or tile model without having to create a database and scenario and driving them on the MiniSim™. The viewer is only for reviewing models, it cannot be used to review a scenario. This command should be run from a command (DOS) window that is opened to the folder containing the models to be viewed. In the event this command does not work, the user should run nadsconfig_system.bat and then use the osg_viewer.exe application to view the model, and then communicate the script failure to NADS so the error may be corrected.

== '''Lessons Learned: Things that can go wrong''' ==

Although the terrain creation process is fairly streamlined, a number of issues may arise that could lead to problems. Mitigation strategies are provided to get you back into production:

# Test every road map. Just because the TMT produces a database does '''not''' guarantee the result is a completely drivable road network. [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=TMT_Troubleshooting_Guide_(all_versions)#ADOs_Can.27t_Travel_On_Sections_of_the_Road_Network Test to make sure that it is.]
# Every time you make a new build, generate both the visual and logical databases together. This is because there are no versioning schemas built into the TMT™, so it is necessary to re-generate all your files for a build in the same session. This has the highest chance for success. Often when a terrain control is not operating the way you think it should, the issue can be traced back to a mismatch between the visual and logical databases.
# Use a script for consistency. To repeat procedures over and over again with a consistent approach, use a script to ensure that you are using the commands and command line options the same way every time you perform a build.
# Do not copy/paste large areas using the TMT™. This can create corrupted terrain databases. Once a terrain file has been corrupted, there is no way to recover it. By saving a terrain database as another file, you can jump-start the construction process and provide yourself with a backup file at the same time. Copy/paste multiple tiles can be combined with rotation.
# To control objects in the environment (signs, traffic signals, etc) it is necessary to ensure the database world has been created using the “Unique Tiles” option, as described in the section Controllability: Unique vs. Generic Functionality (p10).

NOTE: You can have multiple TMT™ sessions open at once, using one database as a reference for LOD settings while building a second database.

== '''Unwanted collisions during simulation''' ==

If collisions are encountered with invisible objects during simulation - ie, there is no apparent source for the collisions, or if there are many collisions happening - the procedure involves:
1. Identify the tile containing the collisions. A coordinate is helpful for this, which can be determined from ISAT (reported on the status bar) or miniSim (has to be enabled).
2. Review the tile.pet file for Objects.
3. Each Object in the tile.pet will reference a sol2 object.
4. Locate the sol2 object from #3 then find the CollisionSoundID record.
5. Any positive number will enable collisions. To disable, replace the value with -1.

Note: If the object is not found in the sol2.txt file, then search all sol2_aux*.txt files.
Note: Remember to copy the modified file to ISAT\data if you are editing the file in NadsMiniSim_x.x\data (and vice-versa) to maintain consistency.
NOTE: You must exit miniSim and/or ISAT before making changes to system configuration files.

[[File:determine_and_disable_collision_objects_02052021.jpg|400px]]

=Appendix A=
==Obsolete and compatible tile models==

Do '''NOT''' use obsolete tile models - instead, locate the compatible tile model and use that instead. Obsolete models are included solely to avoid potentially corrupting existing world.mos files.

{|
|+ Obsolete and compatible Tile Models
|-
|Obsolete Tile|| use -> ||Compatible Tile
|-
|2ln_city_06
| is now:
|'''2ln_rural_4ln_city'''
|-
|2ln_4ln_trans_01
| is now:
|'''2ln_rural_4ln_rural'''
|-
|2ln_res_rural_trans
| is now:
|'''2ln_rural_2ln_res'''
|-
|urban_4ln_trans_01
| is now:
|'''5ln_urban_4ln_urban'''
|-
|fway_3LN_2ln_Trans_01
| is now:
|'''2ln_fwy_3ln_fwy'''
|-
|rural_2ln_gravel_trans_01
| is now:
|'''2ln_rural_2ln_gravel'''
|-
|suburb_trans_rural_01_night
| is now:
|'''4ln_suburb_2ln_rural_night'''
|-
|suburb_trans_rural_01
| is now:
|'''4ln_suburb_2ln_rural'''
|-
|4ln_city_1x1_BL_Trans01
| is now:
|'''4ln_city_4ln_BL_city'''
|-
|fway_trans_4ln_01
| is now:
|'''2ln_fwy_4ln_urban'''
|-
|fway_trans_rural_01
| is now:
|'''2ln_fwy_2ln_rural'''
|-
|fway_trans_4ln_2ln_01
| is now:
|'''2ln_fwy_4ln_fwy'''
|-
|fway_3LN_3LnUrban_trans01
| is now:
|'''3ln_fwy_3ln_urban'''
|-
|4ln_BL_rural_trans01
| is now:
|'''4ln_BL_urban_2ln_rural'''
|-
|4ln_rural_4ln_trans_01
| is now:
|'''4ln_rural_2ln_fwy'''
|-
|BLVD_4ln_trans_01_20
| is now:
|'''4ln_BLVD_4ln_urban_e20'''
|-
|fway_3ln_2ln_trans_03
| is now:
|'''2ln_fwy_3ln_fwy'''
|-
|rural_2ln_gravel_trans_02
| is now:
|'''2ln_rural_2ln_gravel_02'''
|-
|rural_trans03
| is now:
|'''2ln_rural_2ln_rural_no_shoulder'''
|-
|rural_trans01_3Mto12f
| is now:
|'''2ln_rural_3M_rural'''
|-
|rural_trans02_10fto12f
| is now:
|'''2ln_rural_2ln_rural_10f_lane'''
|-
|urban_6ln_4ln_transition
| is now:
|'''6ln_urban_4ln_urban_night'''
|-
|urban_6ln_4ln_transition_day
| is now:
|'''6ln_urban_4ln_urban_day'''
|-
|2ln_3way_rural_res01
| is now:
|'''2ln_rural_2ln_res_3way'''
|-
|4ln_city_1x1_BL_Trans01C
| is now:
|'''4ln_city_4ln_BL_city_ROT_C'''
|-

|}

=Appendix B=
The following is a partial list of applications used to support the creation of TMT™ compatible 3D models and textures. There are many programs available. The basic requirements necessary are the ability to create texture-mapped 3D geometry and the meta-data files containing simulator data. These files may be examined in the ProjectData\Tiles folders installed with the TMT™.

A. Graphics Programs
• Adobe Photoshop™ or CreativeSuite™
• GIMP™
• Painter™
• Any other raster editing graphics application

B. 3D Programs
• Presagis™ Creator
• Autodesk Maya™
• Autodesk 3D Studio™
• Google Sketchup™
• Any other 3D application capable of applying and saving textured 3D models
C. Conversion Programs
• Deep Exploration™
• Okino PolyTrans™
• Export from 3D Program

'''NOTE:''' Currently in order to use your models within the TMT™ to produce terrain databases, it will be necessary to utilize some form of conversion software to convert from the application native or export format into OpenFlight™.

FAQ

2023-11-20T22:25:47Z

Shawn Allen: /* miniSim Data Dictionary add verbage to use SCNVIF sections for custom added cells*/

<div class="toccolours mw-collapsible mw-collapsed">
== miniSim Data Dictionary ==
The data dictionary is a compilation of the simulator data that is stored and available within the DAQ file after each drive.

[[:File:Cells_miniSim_20231120.pdf]]

Note:
miniSim users may extend the data dictionary by adding custom cells to the collect and schedule files:
* NadsMiniSim_x.x\data\NadsMiniSimCollect.general.txt
* NadsMiniSim_x.x\data\NadsMiniSim.cec

Typically new cells should be added into one of the SCNVIF sections. Use the same SCNVIF section for both files:

*cell 1 SCNVIF
*cell 7 SCNVIF
*cell 8 SCNVIF
*cell 9 SCNVIF

== miniSim Documentation ==
All miniSim simulators ship with a documentation folder located on the desktop. You can find miniSim and additional documentation within this folder.

== miniSim Hardware ==

=== Desktop and Viewport Settings ===
<div class="mw-collapsible-content">

Detailed information about the PC display layout and the miniSim viewport and channel configuration settings is available here:

[[:File:miniSim-Desktop_and_Viewport-Settings-v3_113022.pdf]]

[[#top|TOP]]
</div>
</div>

=== Q: My miniSim displays have changed. What happened, and how can I fix it? ===
<div class="mw-collapsible-content">

Windows has shown a tendency to re-enumerate the displays from time to time. The result is that the miniSim display layout/configuration becomes incorrect.

The relationship between the display layout and the viewport display settings in the miniSim Channel Configuration File (.ccf) no longer match.

To correct, check the following in this order:
# Displays are arranged from left to right: Matrox/Mosaic, Instrument Panel, Operator.(use mouse or arrow keys)
# The Matrox/Mosaic display must be designated as the ‘main’ or ‘primary’ in Windows. The task bar may move to this display when this is set, so drag the task bar and icons to the operator display
# Do not use the Matrox PowerDesk program to adjust the default locations for pop-up and application windows. This will cause many, many problems.
# The top edges of the display icons are aligned (use mouse or arrow keys)
# Reboot to make sure the configuration is stable.
# Check video and USB connections. If they are loose, it may cause windows to re number the displays, which can make things move around unpredictably.
# Open the correct Channel Configuration File (.ccf) in the \bin.x64 directory.

'''Note:''' there are several .ccf files in every system, and the ‘correct’ one is defined by the system settings in the ‘go.cmd’ file used to start miniSim.

See next section. The third number in the Channel header(s) should be equal to the number of the main display as reported by Windows in ‘Display Settings’ minus 1. Only 0, 1, 2 are generally valid for standard miniSim configurations (2 Channel, 3 displays).

:Channel 0 0 2 (Shear x2) (Twist x3) (Extends x4)
:0.000000 0.000000
:0.000000 0.000000 0.000000
:0.000000 0.000000 1.000000 1.000000
:6
:.
:.
:.
:Channel 1 0 2 (Shear x2) (Twist x3) (Extends x4)
:0.000000 0.000000
:0.000000 0.000000 0.000000
:1.000000 0.000000 2.000000 1.000000
:0 IP

[[#top|TOP]]
</div>

=== Q: What is the right Channel Configuration File for my miniSim? ===
<div class="mw-collapsible-content">

A. to determine the correct ccf file, examine the command file that launches miniSim.

The minisim is launched by running the correct go.cmd file in the '''NadsMiniSim_x.x.x\bin.x64''' folder.

Typically, there have been shortcuts created on the miniSim desktop that are used to run the appropriate ‘go’ scripts. There are often several go-scripts, this is usually to provide a way to launch the miniSim with or without various options (Video Capture, Advanced Automation, etc).

If you right-click on the shortcut icon and choose ‘edit’ you can edit the go.cmd script. A typical one looks like this:

:set MININADSCOMMMODE=PSEXEC
:set DYNA=car
:set NUMCHN='''2'''
:set INSTRUMENTS='''on'''
:set FORMAT='''wide'''
:set INSETVIEW=off
:set SIDEMIRRORS='''on'''
:set MININADSDAQ='''on'''

Based on these settings, the miniSim will read the following channel configuration file (.ccf) and use its contents for setting up the rendering channels and viewports. In this case, the miniSim will open this file:
'''\bin.x64\mininads_2ch.wide.sidemirrors.inst.ccf'''

This is the correct file to edit for this configuration. Remember to exit miniSim before making edits to the .ccf file.
'''If you make a change and see no effect, you may be editing the wrong file!'''

When the miniSim runs, it copies the .ccf file that pertains to the options selected in the go.cmd, and copies it to '''mininads_1ch.ccf''', which is the one that is loaded when miniSim is launched.

This means that the '''mininads_1ch.ccf''' has the same ‘Last Modified Date’ as the file you want to edit.

If you list the contents of the \bin.X64 folder by date, you will see something like this:

[[File:2022-11-30_15h03_56.png|400px]]

In this case, you will see that the '''mininads_2ch.wide.sidemirrors.inst.ccf''' is the file you want to edit, as it has the same last modified date as '''mininads_1ch.ccf'''.

For a desktop layout like this from Windows in ‘Display Settings’

[[File:2022-11-30_15h05_10.png|400px]]

This is a '''Two-Channel''' system, meaning that the front three displays on the Matrox/Mosaic are Channel 0, and the Instrument Panel display is Channel 1.

[[#top|TOP]]
</div>

=== Q: Where do I find data relating to the brake pedal force/position? ===
<div class="mw-collapsible-content">
A: The data you are seeking is represented by the '''CFS_Brake_Pedal_Force''' variable, which can be viewed either with ISAT or with Matlab during data reduction. The value ranges from 0 lbs. to 180 lbs., where 0 indicates no force (no pedal travel) and 180 indicates 180 pounds of force (full pedal travel).

If you see a variable named '''CFS_Brake_Pedal_Position''' you may ignore this as it is not currently being used.

[[#top|TOP]]
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: How can I adjust the brake pedal response? ===
<div class="mw-collapsible-content">

Information to adjust the brake pedal response is detailed in this document: [[:File:Adjust_Brake_Response_11302022.pdf]]

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: The tactile transducer, mounted under the cab, suddenly does not respond when the miniSim is running. ===
<div class="mw-collapsible-content">

Check the following:

1. Verify these connections first:
: a. The main stereo speakers should be plugged into the green audio port on the back of the PC using a ⅛" mini-jack.
: b. The Dayton D-30 amplifier should be plugged into the orange port on the back of the PC using a ⅛" mini-jack.
: c. The tactile transducer should be connected to the Dayton D-30 amplifier using the included speaker wire.

2. Note that the amplifier controls the volume of the tactile transducer and therefore must be plugged into a power source. If the amplifier is not plugged into power, this could be the reason the tactile transducer is not working.

3. Check the volume level of the amplifier. If it is set too low, the tactile transducer may '''appear''' to not be working. We suggest a minimum amplifier volume setting of 25% of full volume. A volume setting which is too high will be experienced as an unpleasant vibration and low-end rumble that does not resemble a real car.

4. Launch the Realtek audio manager from the Task Bar and select 5.1 audio. Then, disable the center and rear channels, leaving the front left and right speakers, and the subwoofer enabled.

5. Use the Realtek audio manager to test each of the speakers individually by clicking on each speaker icon. As you select a speaker, the speaker will sound.

Some motherboards have the sub/center channels switched. In this case, a ⅛" mini-jack to stereo RCA cable can be used.

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

== miniSim Operation ==
=== Q: Auto-start miniSim drive===
The miniSim simulator can be configured to start a drive automatically or not, depending on your project requirements.

This involves a '''''system level configuration change'''''. To run two projects simultaneously you will need to create a unique startup sequence for each project in order to use the correct configuration file.

Setting auto-start involves a setting in the hardware.xml file in use; note there are different configuration files present on all miniSim simulators within this folder:

miniSim_x.x\bin.x64\config

Please exit miniSim before editing any .xml file. You may want to backup these files prior to editing.

'''Enable auto-start'''

Change the string

<Sink device="SimulatorInterface" port="CIS_Auto_Ignition" ID="0" />

to

<Sink device="SimulatorInterface" port="CIS_Auto_Ignition" ID="1" />

To disable auto-start, set the value to 0.

=== Q: miniSim is not responding. ===
<div class="mw-collapsible-content">A: At times you may find that your miniSim PC or miniSim software has become unresponsive. We define appropriate steps for correcting unresponsive behavior on a miniSim PC under the following conditions:

* '''miniSim Software is Running but Will Not Load a Drive Scenario:'''
# Assuming the mouse is functioning, simply close and then restart the miniSim program.
# If the mouse is not functioning, use the keyboard to close and restart the miniSim program i.e. press Alt+Tab to select the minSim program and press Esc to close.
# This step will fix this unresponsive behavior most of the time.
* '''A miniSim Drive Has Been Selected but Will Not Start:'''
: Assuming the mouse is functioning, click on the Settings tab and verify all lines are green (ready mode). If one or more lines are red, simply wait for all to become green. If still not green after about 90 seconds, close and restart the miniSim software normally. This step will fix this unresponsive behavior most of the time.
* '''miniSim Software Stops Running:'''
# Assuming the mouse is functioning, simply close and then restart the miniSim program.
# If the mouse is not functioning, use the keyboard to close and restart miniSim program i.e. press Alt+Tab to select the minSim program and press Esc to close.
# If the miniSim software will not close, press Ctrl+Alt+Delete and open Task Manager. Within Task Manager, select the SimopServer program and close it. Restart miniSim.
# This process generally will recover miniSim from nearly any unresponsive state.
* '''miniSim PC Shuts Down Unexpectedly:'''
# Check for severe storms and possible power outages in your neighborhood.
# If you see smoke or smell something burning near the miniSim PC, carefully unplug the PC from the electrical outlet and fetch your fire extinguisher just in case. When immediate danger passes, consult a local hardware expert to examine your PC for possible electrical shorts, overheating or failure of critical systems such as motherboard, hard drive and etc. Contact NADS miniSim in the event hardware components need to be replaced. See contact information below.
* '''The miniSim PC Will Not Boot:'''
# On rare occasions your miniSim PC may not boot to Windows. It may halt the boot process just prior to launching Windows. If your miniSim PC has stopped the boot process before a Windows launch, it is okay to touch the reset button on the PC (the small button next to the power button). If your miniSim PC does not have a reset button, touch the power button lightly one time. There may be a slight delay but then your miniSim PC will restart the boot process. This is the safest way to handle an uncompleted boot sequence.
# In most cases if the system stops prematurely during the boot process, for example, while displaying the motherboard splash screen (typically AMI) or the blinking cursor just prior to the Windows logo, the PC is having trouble enumerating USB devices before loading windows.
# If the system hangs up during the second boot attempt, please check the USB connections. In particular, be sure the mouse and keyboard (typically connected through a USB hub) are in their designated USB ports i.e. nearest to the round PS2 style port (top for tower systems or far left for rackmount systems). These are typically USB 2.0 ports and are checked first during the USB enumeration process at boot. It is critical that the mouse/keyboard connections are made in this way.
# If the mouse/keyboard are connected to the correct USB ports, and your miniSim PC still does not boot, disconnect all USB devices (except mouse and keyboard) and systematically reconnect them one at a time in between reboots. This process will eventually and effectively isolate which USB device may be causing the boot problem. To resolve this conflict, simply plug the suspected USB device into a different USB port. Moving these devices to a different port typically resolves this problem permanently. It often (unfortunately) requires some experimentation (read trial and error) but once you find the right combination of USB devices and ports, this problem goes away.

Also, there are certain steps you should not take to try and resolve an unresponsive miniSim PC condition. Some tactics could actually make the problem worse e.g. damage hard drives, corrupt the operating system, scramble your data. Here are some activities you should not engage in to try and resolve a hanging miniSim PC:

'''Troubleshooting steps you should NOT try:'''
* Do not press and hold the power button on the PC while miniSim is running.
* Do not unplug the PC from electrical outlet while miniSim is running.
* Do not unplug mouse, monitors or keyboard while miniSim is running.

'''Acceptable methods for shutting down an unresponsive PC:'''
* Close all running programs, press the Windows key and select Shut Down.
* Or, press Ctrl+Alt+Delete and select Shut Down.
* Or, touch the reset button or lightly touch the power button one time.

====Making Changes to the BIOS====

If your miniSim PC is unresponsive in ways that are not covered above, you may need to make certain changes to the BIOS of your miniSim PC. Altering BIOS settings on a PC is delicate work and requires more than a passing knowledge of computers. Instructions for modifying the BIOS follows but if you would like the assistance of a NADS professional, don’t hesitate to ask.

The BIOS change involves enabling Fast Boot. Fast Boot will disable your USB devices at boot-up thus preventing USB port conflicts and effectively preventing endless USB enumeration and rebooting.

To enter BIOS setup, repeatedly press the Delete key while the computer is powering up. Ultimately you will see a screen that looks like the screen shot below. (This assumes your miniSim PC was built in 2015 or later.)

[[File:Initial BIOS Screen.jpg|400px|thumb|center|Initial BIOS Screen]]

Navigate to the '''Advanced tab''' using the arrow keys on your keyboard and select it.

[[File:Advanced.jpg|400px|thumb|center|Advanced Tab Selected]]

Scroll down and select '''USB Configuration.'''

[[File:USB Configuration.jpg|400px|thumb|center|USB Configuration Selected]]

Make sure your BIOS settings match the settings on the right half of the screen as shown below:

[[File:BIOS Settings.jpg|400px|thumb|center]]

Set '''Fast Boot''' to '''Fast.'''

[[File:Fast Boot Selected.jpg|400px|thumb|center|Fast Boot set to Fast]]

Select '''Save Changes and Exit'''

[[File:Save Changes and Exit.jpg|400px|thumb|center|Save Changes and Exit selected]]

'''NOTE: these settings will disable your USB devices during boot. This will eliminate the USB enumeration problem but will also prevent you from accessing BIOS settings again without a PS2 style keyboard. Feel free to contact NADS for additional information on this condition.'''

Bear in mind your BIOS screens may look different than the screenshots above but your objective remains the same, enable Fast Boot.

Please don’t hesitate to contact us if you wish help with these settings. '''Word of Caution:''' make these changes during normal business hours. If you get stuck in BIOS settings on a weekend or middle of the night, we may not be available to help you.

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

= miniSim Software =

=== Simulation data ===
Your data is the primary reason for simulation and is available from the miniSim in two ways:

# Default measures - these are pre-defined measures available for up to 20 events.
# Logstreams - the entire range of variables is available for as many events as required.

These two methods require setting up a scenario to create [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#What_is_a_Scenario_Event.3F '''events'''] that happen during simulation and are defined in a way to allow extracting them from the drive.

Default measures are available immediately after the drive in the form of a text document, located in the DAQ folder on miniSim.

Logstreams are flags embedded in the drive data and requires data reduction to make the information available after the drive.

More information on these methods is available [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#Data_Output_Methods here:]

= ISAT/Scenario =

=== New to ISAT? ===
A quick start overview is available [https://www.nads-sc.uiowa.edu/minisim/wiki/images/6/68/ISAT_Quick_Start.pdf '''here.''']

The ISAT User Guide is available [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents '''here.''']

A scenario/ISAT troubleshooting guide is available [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_Troubleshooting_Guide '''here.''']

=== Data Logging: miniSim Default Measures ===
There are a fixed number of measures available and a limit of 20 events.

More information including which measures are available and how to structure your scenario to support default measures is available [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#Default_miniSim_Scenario_Measures here.]

=== Q: How do we make an ADO or DDO go backward? ===
<div class="mw-collapsible-content">
A: Only DDOs can back up. To accomplish this, start by placing a DDO where desired.

Next, create a path for the DDO; right-click on it and select Extend Path from the pop-up menu.

Then, lay out a path (path nodes are a sequence of yellow dots) to indicate the desired route of travel.

Finally, right-click on each node and select Rotate to set the direction that you wish the DDO to face. The direction at each node can be set independently.

In order to make it appear as though the car is moving backwards, the arrows should point against the direction of travel. To avoid erratic movement, you should add sufficient nodes to create a smooth path. This will result in smoother and more realistic movement of the DDO, especially if you are changing direction rapidly.

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: How do I play a sound in my scenario? ===
<div class="mw-collapsible-content">

See [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#How_to_Use_Audio_in_your_Scenario Using Audio in a Scenario]

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: How do I add a trigger to my scenario? ===
<div class="mw-collapsible-content">

Triggers can be added to a scenario in ISAT through the menu '''Insert >> Coordinators'''
or, if the ISAT Elements panel is open, by left-click-drag any trigger off the panel and then releasing the left button where you want to place the trigger.

After a trigger has been placed in your scenario you can reposition it by clicking and dragging it to a new location.

'''Note:''' Trigger consist of multiple elements. To reposition a trigger you will have to click-drag the trigger handle, which is a small red dot. Clicking the larger trigger pane will move the pane, not the handle. Moving the handle will move the trigger.

[[File:2022-11-30_14h07_26.png|400px]]

Some triggers also require a roadpad (roadpad, follow, Time To Arrival triggers).
Right-click on the trigger and choose '''Place Road Pad.'''

'''Note: All triggers with road pads require a [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#Triggers '''predicate'''] to activate the trigger.'''

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: What is a “Write to Cell” action? ===
<div class="mw-collapsible-content">

Cells are reserved data containers that define various attributes and operating characteristics of the miniSim and are stored after each drive in a unique drive DAQ file.

A '''write to cell''' action allows you to send data to miniSim and simultaneously store this data in the DAQ file during simulation.

Most cells are managed by a subsystem (behaviors, dynamics, scenario control). For these cells, writing to a cell is possible but not practical because the managing subsystem will overwrite that cell within the next frame.

'''Examples''' (not a complete list!):
# Play a sound/audio file: Write to Cell SCC_Audio_Trigger
# Set event status or an event number for default miniSim data measures: Write to Cell SCC_Event_Status, SCC_Event_Number
# Saving data during a drive to the DAQ so it is available for analysis; i.e., timing of things, storing scenario variable data (variables are not persistent unless saved to a file or written to the DAQ): Write to Cell SCC_Custom1, or user defined
# Changing a simulator setting (Adaptive Cruise Control on/off, Automatic Lane Following): Write to Cell SCC_ALF_On, SCC_ACC_On

'''Note:''' Write to cell actions are expensive operations and there is currently a limit of 7 per frame. '''Exceeding this number will likely result in the excess cells not being written'''.

'''Note:''' Some cells are managed by the Cab Information/Hardware subsystem (CIS). Configuring miniSim to support operation by both scenario and CIS may require consulting with NADS to ensure correct operation.

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: How can I tell if the driver has left the road? ===
<div class="mw-collapsible-content">
One way to check if the driver has left the roadway is to use a lane deviation calculation: if the lane deviation is greater than <measured_total_lane_width> or less than -<measured_total_lane_width>, the driver is likely out of the lane.
[[#top|TOP]]
</div>
</div>

=== Q: How can I tell what surface the driver is driving over? ===
<div class="mw-collapsible-content">

A. Use the cell '''TPR_Surface_Type_Ind to detect the surface material code (SMC) under the driver.

The first four elements of the TPR_Surface_Type_Ind correspond to 4 wheels of the ownship/external driver vehicle.

[[File:2022-11-30_14h21_16.png|400px]]

[[File:2022-11-30_14h21_27.png|400px]]

MiniSim does not report surface material codes within intersections that do not have an elevation map associated with them.

[[File:2022-11-30_14h22_10.png|400px]]

You can find a complete list of available surface material codes (SMC) - (not all of these are used in the tile library, but this is the current version for SMC codes) under the TMT\ProjectData\Tiles\CommonLRIData\SurfaceMaterialSpecifications.xlsx.

'''Note:''' Intersection elevation maps were introduced in TMT '''1.8.5'''.

[[#top|TOP]]
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: What is the difference between SCC_Lane_Deviation and SCC_Lane_Spline_Deviation? ===

SCC_Lane_Spline_Deviation is computed from centerline data as a continuous spline and is recommended over SCC_Lane_Deviation.

[[File:scc_lane_spline_deviation_20230918.png|400px]]

<div class="mw-collapsible-content">

FAQ

2023-11-20T15:48:46Z

Shawn Allen: /* miniSim Documentation add data dictionary document*/

<div class="toccolours mw-collapsible mw-collapsed">
== miniSim Data Dictionary ==
The data dictionary is a compilation of the simulator data that is stored and available within the DAQ file after each drive.

[[:File:Cells_miniSim_20231120.pdf]]

Note:
miniSim users may extend the data dictionary by adding custom cells to the collect and schedule files:
* NadsMiniSim_x.x\data\NadsMiniSimCollect.general.txt
* NadsMiniSim_x.x\data\NadsMiniSim.cec

== miniSim Documentation ==
All miniSim simulators ship with a documentation folder located on the desktop. You can find miniSim and additional documentation within this folder.

== miniSim Hardware ==

=== Desktop and Viewport Settings ===
<div class="mw-collapsible-content">

Detailed information about the PC display layout and the miniSim viewport and channel configuration settings is available here:

[[:File:miniSim-Desktop_and_Viewport-Settings-v3_113022.pdf]]

[[#top|TOP]]
</div>
</div>

=== Q: My miniSim displays have changed. What happened, and how can I fix it? ===
<div class="mw-collapsible-content">

Windows has shown a tendency to re-enumerate the displays from time to time. The result is that the miniSim display layout/configuration becomes incorrect.

The relationship between the display layout and the viewport display settings in the miniSim Channel Configuration File (.ccf) no longer match.

To correct, check the following in this order:
# Displays are arranged from left to right: Matrox/Mosaic, Instrument Panel, Operator.(use mouse or arrow keys)
# The Matrox/Mosaic display must be designated as the ‘main’ or ‘primary’ in Windows. The task bar may move to this display when this is set, so drag the task bar and icons to the operator display
# Do not use the Matrox PowerDesk program to adjust the default locations for pop-up and application windows. This will cause many, many problems.
# The top edges of the display icons are aligned (use mouse or arrow keys)
# Reboot to make sure the configuration is stable.
# Check video and USB connections. If they are loose, it may cause windows to re number the displays, which can make things move around unpredictably.
# Open the correct Channel Configuration File (.ccf) in the \bin.x64 directory.

'''Note:''' there are several .ccf files in every system, and the ‘correct’ one is defined by the system settings in the ‘go.cmd’ file used to start miniSim.

See next section. The third number in the Channel header(s) should be equal to the number of the main display as reported by Windows in ‘Display Settings’ minus 1. Only 0, 1, 2 are generally valid for standard miniSim configurations (2 Channel, 3 displays).

:Channel 0 0 2 (Shear x2) (Twist x3) (Extends x4)
:0.000000 0.000000
:0.000000 0.000000 0.000000
:0.000000 0.000000 1.000000 1.000000
:6
:.
:.
:.
:Channel 1 0 2 (Shear x2) (Twist x3) (Extends x4)
:0.000000 0.000000
:0.000000 0.000000 0.000000
:1.000000 0.000000 2.000000 1.000000
:0 IP

[[#top|TOP]]
</div>

=== Q: What is the right Channel Configuration File for my miniSim? ===
<div class="mw-collapsible-content">

A. to determine the correct ccf file, examine the command file that launches miniSim.

The minisim is launched by running the correct go.cmd file in the '''NadsMiniSim_x.x.x\bin.x64''' folder.

Typically, there have been shortcuts created on the miniSim desktop that are used to run the appropriate ‘go’ scripts. There are often several go-scripts, this is usually to provide a way to launch the miniSim with or without various options (Video Capture, Advanced Automation, etc).

If you right-click on the shortcut icon and choose ‘edit’ you can edit the go.cmd script. A typical one looks like this:

:set MININADSCOMMMODE=PSEXEC
:set DYNA=car
:set NUMCHN='''2'''
:set INSTRUMENTS='''on'''
:set FORMAT='''wide'''
:set INSETVIEW=off
:set SIDEMIRRORS='''on'''
:set MININADSDAQ='''on'''

Based on these settings, the miniSim will read the following channel configuration file (.ccf) and use its contents for setting up the rendering channels and viewports. In this case, the miniSim will open this file:
'''\bin.x64\mininads_2ch.wide.sidemirrors.inst.ccf'''

This is the correct file to edit for this configuration. Remember to exit miniSim before making edits to the .ccf file.
'''If you make a change and see no effect, you may be editing the wrong file!'''

When the miniSim runs, it copies the .ccf file that pertains to the options selected in the go.cmd, and copies it to '''mininads_1ch.ccf''', which is the one that is loaded when miniSim is launched.

This means that the '''mininads_1ch.ccf''' has the same ‘Last Modified Date’ as the file you want to edit.

If you list the contents of the \bin.X64 folder by date, you will see something like this:

[[File:2022-11-30_15h03_56.png|400px]]

In this case, you will see that the '''mininads_2ch.wide.sidemirrors.inst.ccf''' is the file you want to edit, as it has the same last modified date as '''mininads_1ch.ccf'''.

For a desktop layout like this from Windows in ‘Display Settings’

[[File:2022-11-30_15h05_10.png|400px]]

This is a '''Two-Channel''' system, meaning that the front three displays on the Matrox/Mosaic are Channel 0, and the Instrument Panel display is Channel 1.

[[#top|TOP]]
</div>

=== Q: Where do I find data relating to the brake pedal force/position? ===
<div class="mw-collapsible-content">
A: The data you are seeking is represented by the '''CFS_Brake_Pedal_Force''' variable, which can be viewed either with ISAT or with Matlab during data reduction. The value ranges from 0 lbs. to 180 lbs., where 0 indicates no force (no pedal travel) and 180 indicates 180 pounds of force (full pedal travel).

If you see a variable named '''CFS_Brake_Pedal_Position''' you may ignore this as it is not currently being used.

[[#top|TOP]]
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: How can I adjust the brake pedal response? ===
<div class="mw-collapsible-content">

Information to adjust the brake pedal response is detailed in this document: [[:File:Adjust_Brake_Response_11302022.pdf]]

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: The tactile transducer, mounted under the cab, suddenly does not respond when the miniSim is running. ===
<div class="mw-collapsible-content">

Check the following:

1. Verify these connections first:
: a. The main stereo speakers should be plugged into the green audio port on the back of the PC using a ⅛" mini-jack.
: b. The Dayton D-30 amplifier should be plugged into the orange port on the back of the PC using a ⅛" mini-jack.
: c. The tactile transducer should be connected to the Dayton D-30 amplifier using the included speaker wire.

2. Note that the amplifier controls the volume of the tactile transducer and therefore must be plugged into a power source. If the amplifier is not plugged into power, this could be the reason the tactile transducer is not working.

3. Check the volume level of the amplifier. If it is set too low, the tactile transducer may '''appear''' to not be working. We suggest a minimum amplifier volume setting of 25% of full volume. A volume setting which is too high will be experienced as an unpleasant vibration and low-end rumble that does not resemble a real car.

4. Launch the Realtek audio manager from the Task Bar and select 5.1 audio. Then, disable the center and rear channels, leaving the front left and right speakers, and the subwoofer enabled.

5. Use the Realtek audio manager to test each of the speakers individually by clicking on each speaker icon. As you select a speaker, the speaker will sound.

Some motherboards have the sub/center channels switched. In this case, a ⅛" mini-jack to stereo RCA cable can be used.

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

== miniSim Operation ==
=== Q: Auto-start miniSim drive===
The miniSim simulator can be configured to start a drive automatically or not, depending on your project requirements.

This involves a '''''system level configuration change'''''. To run two projects simultaneously you will need to create a unique startup sequence for each project in order to use the correct configuration file.

Setting auto-start involves a setting in the hardware.xml file in use; note there are different configuration files present on all miniSim simulators within this folder:

miniSim_x.x\bin.x64\config

Please exit miniSim before editing any .xml file. You may want to backup these files prior to editing.

'''Enable auto-start'''

Change the string

<Sink device="SimulatorInterface" port="CIS_Auto_Ignition" ID="0" />

to

<Sink device="SimulatorInterface" port="CIS_Auto_Ignition" ID="1" />

To disable auto-start, set the value to 0.

=== Q: miniSim is not responding. ===
<div class="mw-collapsible-content">A: At times you may find that your miniSim PC or miniSim software has become unresponsive. We define appropriate steps for correcting unresponsive behavior on a miniSim PC under the following conditions:

* '''miniSim Software is Running but Will Not Load a Drive Scenario:'''
# Assuming the mouse is functioning, simply close and then restart the miniSim program.
# If the mouse is not functioning, use the keyboard to close and restart the miniSim program i.e. press Alt+Tab to select the minSim program and press Esc to close.
# This step will fix this unresponsive behavior most of the time.
* '''A miniSim Drive Has Been Selected but Will Not Start:'''
: Assuming the mouse is functioning, click on the Settings tab and verify all lines are green (ready mode). If one or more lines are red, simply wait for all to become green. If still not green after about 90 seconds, close and restart the miniSim software normally. This step will fix this unresponsive behavior most of the time.
* '''miniSim Software Stops Running:'''
# Assuming the mouse is functioning, simply close and then restart the miniSim program.
# If the mouse is not functioning, use the keyboard to close and restart miniSim program i.e. press Alt+Tab to select the minSim program and press Esc to close.
# If the miniSim software will not close, press Ctrl+Alt+Delete and open Task Manager. Within Task Manager, select the SimopServer program and close it. Restart miniSim.
# This process generally will recover miniSim from nearly any unresponsive state.
* '''miniSim PC Shuts Down Unexpectedly:'''
# Check for severe storms and possible power outages in your neighborhood.
# If you see smoke or smell something burning near the miniSim PC, carefully unplug the PC from the electrical outlet and fetch your fire extinguisher just in case. When immediate danger passes, consult a local hardware expert to examine your PC for possible electrical shorts, overheating or failure of critical systems such as motherboard, hard drive and etc. Contact NADS miniSim in the event hardware components need to be replaced. See contact information below.
* '''The miniSim PC Will Not Boot:'''
# On rare occasions your miniSim PC may not boot to Windows. It may halt the boot process just prior to launching Windows. If your miniSim PC has stopped the boot process before a Windows launch, it is okay to touch the reset button on the PC (the small button next to the power button). If your miniSim PC does not have a reset button, touch the power button lightly one time. There may be a slight delay but then your miniSim PC will restart the boot process. This is the safest way to handle an uncompleted boot sequence.
# In most cases if the system stops prematurely during the boot process, for example, while displaying the motherboard splash screen (typically AMI) or the blinking cursor just prior to the Windows logo, the PC is having trouble enumerating USB devices before loading windows.
# If the system hangs up during the second boot attempt, please check the USB connections. In particular, be sure the mouse and keyboard (typically connected through a USB hub) are in their designated USB ports i.e. nearest to the round PS2 style port (top for tower systems or far left for rackmount systems). These are typically USB 2.0 ports and are checked first during the USB enumeration process at boot. It is critical that the mouse/keyboard connections are made in this way.
# If the mouse/keyboard are connected to the correct USB ports, and your miniSim PC still does not boot, disconnect all USB devices (except mouse and keyboard) and systematically reconnect them one at a time in between reboots. This process will eventually and effectively isolate which USB device may be causing the boot problem. To resolve this conflict, simply plug the suspected USB device into a different USB port. Moving these devices to a different port typically resolves this problem permanently. It often (unfortunately) requires some experimentation (read trial and error) but once you find the right combination of USB devices and ports, this problem goes away.

Also, there are certain steps you should not take to try and resolve an unresponsive miniSim PC condition. Some tactics could actually make the problem worse e.g. damage hard drives, corrupt the operating system, scramble your data. Here are some activities you should not engage in to try and resolve a hanging miniSim PC:

'''Troubleshooting steps you should NOT try:'''
* Do not press and hold the power button on the PC while miniSim is running.
* Do not unplug the PC from electrical outlet while miniSim is running.
* Do not unplug mouse, monitors or keyboard while miniSim is running.

'''Acceptable methods for shutting down an unresponsive PC:'''
* Close all running programs, press the Windows key and select Shut Down.
* Or, press Ctrl+Alt+Delete and select Shut Down.
* Or, touch the reset button or lightly touch the power button one time.

====Making Changes to the BIOS====

If your miniSim PC is unresponsive in ways that are not covered above, you may need to make certain changes to the BIOS of your miniSim PC. Altering BIOS settings on a PC is delicate work and requires more than a passing knowledge of computers. Instructions for modifying the BIOS follows but if you would like the assistance of a NADS professional, don’t hesitate to ask.

The BIOS change involves enabling Fast Boot. Fast Boot will disable your USB devices at boot-up thus preventing USB port conflicts and effectively preventing endless USB enumeration and rebooting.

To enter BIOS setup, repeatedly press the Delete key while the computer is powering up. Ultimately you will see a screen that looks like the screen shot below. (This assumes your miniSim PC was built in 2015 or later.)

[[File:Initial BIOS Screen.jpg|400px|thumb|center|Initial BIOS Screen]]

Navigate to the '''Advanced tab''' using the arrow keys on your keyboard and select it.

[[File:Advanced.jpg|400px|thumb|center|Advanced Tab Selected]]

Scroll down and select '''USB Configuration.'''

[[File:USB Configuration.jpg|400px|thumb|center|USB Configuration Selected]]

Make sure your BIOS settings match the settings on the right half of the screen as shown below:

[[File:BIOS Settings.jpg|400px|thumb|center]]

Set '''Fast Boot''' to '''Fast.'''

[[File:Fast Boot Selected.jpg|400px|thumb|center|Fast Boot set to Fast]]

Select '''Save Changes and Exit'''

[[File:Save Changes and Exit.jpg|400px|thumb|center|Save Changes and Exit selected]]

'''NOTE: these settings will disable your USB devices during boot. This will eliminate the USB enumeration problem but will also prevent you from accessing BIOS settings again without a PS2 style keyboard. Feel free to contact NADS for additional information on this condition.'''

Bear in mind your BIOS screens may look different than the screenshots above but your objective remains the same, enable Fast Boot.

Please don’t hesitate to contact us if you wish help with these settings. '''Word of Caution:''' make these changes during normal business hours. If you get stuck in BIOS settings on a weekend or middle of the night, we may not be available to help you.

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

= miniSim Software =

=== Simulation data ===
Your data is the primary reason for simulation and is available from the miniSim in two ways:

# Default measures - these are pre-defined measures available for up to 20 events.
# Logstreams - the entire range of variables is available for as many events as required.

These two methods require setting up a scenario to create [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#What_is_a_Scenario_Event.3F '''events'''] that happen during simulation and are defined in a way to allow extracting them from the drive.

Default measures are available immediately after the drive in the form of a text document, located in the DAQ folder on miniSim.

Logstreams are flags embedded in the drive data and requires data reduction to make the information available after the drive.

More information on these methods is available [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#Data_Output_Methods here:]

= ISAT/Scenario =

=== New to ISAT? ===
A quick start overview is available [https://www.nads-sc.uiowa.edu/minisim/wiki/images/6/68/ISAT_Quick_Start.pdf '''here.''']

The ISAT User Guide is available [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents '''here.''']

A scenario/ISAT troubleshooting guide is available [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_Troubleshooting_Guide '''here.''']

=== Data Logging: miniSim Default Measures ===
There are a fixed number of measures available and a limit of 20 events.

More information including which measures are available and how to structure your scenario to support default measures is available [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#Default_miniSim_Scenario_Measures here.]

=== Q: How do we make an ADO or DDO go backward? ===
<div class="mw-collapsible-content">
A: Only DDOs can back up. To accomplish this, start by placing a DDO where desired.

Next, create a path for the DDO; right-click on it and select Extend Path from the pop-up menu.

Then, lay out a path (path nodes are a sequence of yellow dots) to indicate the desired route of travel.

Finally, right-click on each node and select Rotate to set the direction that you wish the DDO to face. The direction at each node can be set independently.

In order to make it appear as though the car is moving backwards, the arrows should point against the direction of travel. To avoid erratic movement, you should add sufficient nodes to create a smooth path. This will result in smoother and more realistic movement of the DDO, especially if you are changing direction rapidly.

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: How do I play a sound in my scenario? ===
<div class="mw-collapsible-content">

See [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#How_to_Use_Audio_in_your_Scenario Using Audio in a Scenario]

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: How do I add a trigger to my scenario? ===
<div class="mw-collapsible-content">

Triggers can be added to a scenario in ISAT through the menu '''Insert >> Coordinators'''
or, if the ISAT Elements panel is open, by left-click-drag any trigger off the panel and then releasing the left button where you want to place the trigger.

After a trigger has been placed in your scenario you can reposition it by clicking and dragging it to a new location.

'''Note:''' Trigger consist of multiple elements. To reposition a trigger you will have to click-drag the trigger handle, which is a small red dot. Clicking the larger trigger pane will move the pane, not the handle. Moving the handle will move the trigger.

[[File:2022-11-30_14h07_26.png|400px]]

Some triggers also require a roadpad (roadpad, follow, Time To Arrival triggers).
Right-click on the trigger and choose '''Place Road Pad.'''

'''Note: All triggers with road pads require a [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#Triggers '''predicate'''] to activate the trigger.'''

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: What is a “Write to Cell” action? ===
<div class="mw-collapsible-content">

Cells are reserved data containers that define various attributes and operating characteristics of the miniSim and are stored after each drive in a unique drive DAQ file.

A '''write to cell''' action allows you to send data to miniSim and simultaneously store this data in the DAQ file during simulation.

Most cells are managed by a subsystem (behaviors, dynamics, scenario control). For these cells, writing to a cell is possible but not practical because the managing subsystem will overwrite that cell within the next frame.

'''Examples''' (not a complete list!):
# Play a sound/audio file: Write to Cell SCC_Audio_Trigger
# Set event status or an event number for default miniSim data measures: Write to Cell SCC_Event_Status, SCC_Event_Number
# Saving data during a drive to the DAQ so it is available for analysis; i.e., timing of things, storing scenario variable data (variables are not persistent unless saved to a file or written to the DAQ): Write to Cell SCC_Custom1, or user defined
# Changing a simulator setting (Adaptive Cruise Control on/off, Automatic Lane Following): Write to Cell SCC_ALF_On, SCC_ACC_On

'''Note:''' Write to cell actions are expensive operations and there is currently a limit of 7 per frame. '''Exceeding this number will likely result in the excess cells not being written'''.

'''Note:''' Some cells are managed by the Cab Information/Hardware subsystem (CIS). Configuring miniSim to support operation by both scenario and CIS may require consulting with NADS to ensure correct operation.

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: How can I tell if the driver has left the road? ===
<div class="mw-collapsible-content">
One way to check if the driver has left the roadway is to use a lane deviation calculation: if the lane deviation is greater than <measured_total_lane_width> or less than -<measured_total_lane_width>, the driver is likely out of the lane.
[[#top|TOP]]
</div>
</div>

=== Q: How can I tell what surface the driver is driving over? ===
<div class="mw-collapsible-content">

A. Use the cell '''TPR_Surface_Type_Ind to detect the surface material code (SMC) under the driver.

The first four elements of the TPR_Surface_Type_Ind correspond to 4 wheels of the ownship/external driver vehicle.

[[File:2022-11-30_14h21_16.png|400px]]

[[File:2022-11-30_14h21_27.png|400px]]

MiniSim does not report surface material codes within intersections that do not have an elevation map associated with them.

[[File:2022-11-30_14h22_10.png|400px]]

You can find a complete list of available surface material codes (SMC) - (not all of these are used in the tile library, but this is the current version for SMC codes) under the TMT\ProjectData\Tiles\CommonLRIData\SurfaceMaterialSpecifications.xlsx.

'''Note:''' Intersection elevation maps were introduced in TMT '''1.8.5'''.

[[#top|TOP]]
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: What is the difference between SCC_Lane_Deviation and SCC_Lane_Spline_Deviation? ===

SCC_Lane_Spline_Deviation is computed from centerline data as a continuous spline and is recommended over SCC_Lane_Deviation.

[[File:scc_lane_spline_deviation_20230918.png|400px]]

<div class="mw-collapsible-content">

File:Cells miniSim 20231120.pdf

2023-11-20T15:48:02Z

Shawn Allen: File uploaded with MsUpload

File uploaded with MsUpload

ISAT User Guide Table of Contents

2023-10-02T18:38:12Z

Shawn Allen: /* Cell Operations: Best Practice Add write to a specific cell array element */

== Who should use this document? ==
Anyone learning to use the DSRI 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
*CTL-<some other key>: Press and hold the Ctrl and then press <some other key>. Most typically used for copy (CTRL-C) or paste (CTRL-V).
*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 and modify for use in your own scenarios as needed.

== <span style="color:#FF0000"> '''Known Issues'''</span>==

Added 2022.07.01 '''Relative Creation''' does not currently work for ADOs on miniSim.

'''Expression clarification'''

Increment and decrement operators (++, --) are not considered expressions by behaviors. They should not be flagged as expressions when used in the Value field of a Set Variable action.

Added 2019.11.07 '''File reset issue'''

ISAT has a long-standing bug which can reset your static object options when your scenario file is saved to disk.

'''It is strongly recommended that you use [[#External_Reference|external reference scenario files]] to avoid this. '''ISAT does not reset static object options in the xref file.

Added 2021.12.29 Expression Triggers and Values

'''Using Values in Expression Triggers'''

To ensure proper execution of expression triggers, it is recommended that the values used include the desired range by decreasing the lower threshold or increasing the upper threshold '''instead of using the exact value.'''

For example, to process values in a range (7031 - 7040):

[[File:2021-12-29_12h38_09.png|400px]]

'''Note: remember that negative values must be calculated since the expression parser does not parse negative values otherwise.'''

For example, to properly parse a specific transmission gear (Park):
'''ReadCell('CFS_Auto_Transmission_Mode', 1) = ( 0 - 2 )'''

<span style="color:#FF0000"> '''Rehearsal without specifying a start location</span>

In some cases ISAT will crash if the external driver (XD)/start location has not been specified or is missing due to a sol2 file configuration error.

=='''ISAT Overview & Interface Basics'''==
This section contains information about ISAT and the ISAT interface.

===What is ISAT?===
ISAT is the DSRI 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 uses resource files that are based on the model objects found in the miniSim. They are proxy objects for the real models used during simulation.

ISAT contains a rudimentary scripting language for automating some repetitive tasks. Scripting is an advanced topic. Because the scripting language is not well documented, it is recommended to copy existing scripts that perform similar functions and modify them.

Because ISAT scenarios are text, you can make some edits quickly and easily using any text editor.

'''However:

When editing a scenario as text, always work on a backup copy in case something goes wrong in the text editing process that invalidates the scenario file to the point where ISAT cannot read it!

===ISAT is NOT:===
ISAT is <span style="color:#FF0000">'''not an object editor'''</span> 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.
[[File:miniSim_scenario_compnents.png|center|640px]]

*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.

[[File:anatomy_of_a_scenario.png|center|400px]]

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

[[File:scenario_as_text.png|center|640px]]

This diagram shows the same scenario in (left to right) 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, <u>always</u> check your edits in ISAT!'''
*Copy/Paste - delete paths from elements when the BLI is different between your source & destination BLI files. The following scenario elements contain paths:
::ADO (with a path specified)
:: Any roadpad trigger (roadpad, Time to Arrival, Follow)

'''NOTE: A Traffic Source is not a portable element but it can be re-created in ISAT or integrated into a new scenario by copying the element from the source scenario then using a text editor to paste it into the destination scenario'''

'''How can I find information in multiple files easily?'''

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.

What if you don't know what to look for? How do 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
[[File:action_overview.png|400px||border|caption]]

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)

==='''Adding an action to a trigger'''===

The following example uses a Time Trigger; remember that '''all triggers share the same actions'''.

To add an action to a trigger you can double-click on the trigger, navigate to the '''Actions''' panel, and click on New to create a new action.

[[File:2022-11-30_12h47_23.png|400px]]

The possible actions are listed under the '''Action Type''' drop-down menu.

[[File:2022-11-30_12h47_44.png|400px]]

Actions are arranged in a 'stack' and are processed from top to bottom. If you use multiple actions you should enable the '''sequential flag''' to ensure each action is executed in sequence. Without the sequential flag, actions will be processed as fast as the simulator behaviors can execute.

[[File:2022-11-30_12h52_58.png|400px]]

Actions may be re-ordered in the stack using the '''arrows''' located near the action stack list.

=='''ISAT Modes of Operation'''==
[[File:ISAT_modes_of_operation.png|400px]]

*Edit
*Rehearsal
*DAQ playback
*Monitor '''Currently not available'''

==='''Edit & Rehearsal Modes'''===

*Edit - this is where scenario authors will spend the most time.
::Creation or modification of scenario
::Link to or import portions of other scenario elements

[[File:mode_edit.png|400px]]

*Rehearsal
::Debug & test scenario
::Simulates scenario using Behaviors and Vehicle Dynamics
::Displays error messages from behaviors

[[File:mode_rehearsal.png|400px]]

'''NOTE:''' Rehearsal mode <span style="color:#FF0000">simulates </span>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

[[File:mode_playback.png|400px]]

==='''miniSim Scenario Components'''===

The following diagram shows an overview of scenario related components of the NADS miniSim and how these components work together.

[[File:miniSim_scenario_components_wDAQ.png|400px]]

=='''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.

[[File:isat_workspace_general.png|400px]]

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)
[[File:isat_status_bar_overview.png|400px]]

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.

[[File:isat_user_prefs_status_bar_settings.png|400px]]

====ISAT Iconography====
ISAT provides graphic hints for triggers placed in scenario that can be useful when editing or maintaining scenarios.

The general format is a border enclosing miniature icons of the trigger and first action contained in that trigger. Additional information representing one or many actions is also shown.

[[File:hints1.png|400px]]

ISAT will list all trigger actions when a trigger is selected, but these hints provide a way to quickly identify what actions have been authored.

[[File:hint2.png|400px]]

*A Roadpad trigger, one action: '''Traffic Light Action'''
*B Roadpad trigger, multiple actions, first action is '''Remove Element'''
*C Roadpad trigger, multiple actions, first action is '''Set Dial'''
*D Roadpad trigger, constrained to road (lane), no actions - this is an empty trigger
*E Roadpad trigger, multiple actions, first action is '''Log Data'''
*F Global Time Trigger, single action: '''Set Dial'''

[[File:handle.png|400px]]

The element handle is the red dot visible in most of the triggers.
The handle can be dragged into position, and the trigger will follow the handle

Drag the trigger off the handle to offset it's location from the handle

==='''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.

[[File:object_types_isat.png|400px]]

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
::*Traffic Source

:'''NOTE:''' Virtual objects are defined in the scenario, not in the SOL2.
[[File:object_types_world.png|400px]]

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.
::NOTE: 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.

==='''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:
#Follow a path using kinematics
#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:
#coupled
#relative trajectory
#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'''===
Traffic signals are objects with special operation and function; they are coupled to intersections and routes of travel through intersections to control traffic flow similiar to their function in the real world. Traffic signals are part of the source tile model and may not be re-positioned or physically altered by scenario except for their visual signal state appearance; i.e., red, green or yellow signals.

To control intersection traffic signals use Edit >> Traffic Light ManagerTraffic signals use a Signal State Table (SST) to control which signal states are active and when. Each intersection with traffic signals will have an associated SST.

[[File:traffic_light_state_manager.png|400px]]

The above diagram shows an intersection in the workspace to the right, and the traffic signal state table for that intersection on the left. At this point additional states (for signal condition) can be added by clicking the '''Add state button'''.

[[File:traffic_signal_state_table2.png|400px]]

The above diagram shows two states defined for the intersection, represented by the two columns of state condition.

Continue adding states until the desired signal cycle has been defined. Generally this consists of red, green or yellow states.

NOTE: There is currently no way to automatically author a series of traffic light signals

To author traffic signal lights in sequence or on a route, the scenario author has to manage the signal states

[[File:traffic_signal_state_duration.png|400px]]

To edit the signal state duration RMB on the duration field header and choosing '''Edit state duration''' on the context menu. Enter the desired value then click OK.

====Traffic Signal Types====
The ISAT status bar reports Traffic Signal Type name. There are two signal types:
#Standard signal - IDs may have no identifying information
:Valid signal states: Red, Yellow, Green, Flashing Red, Flashing Yellow, OFF
#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

[[File:traffic_light_extended_type_name_normal.png|400px]]
: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.

[[File:traffic_light_extended_type_name.png|400px]]

===Changing Signal States in Scenario===
Traffic signals are controlled in scenario by using a Traffic Signal Action to change the SST.

'''NOTE:''' The Traffic Signal Action works by changing the SST, '''not by changing the traffic signal.''' This is a subtle but important difference.

Setting a signal to an undefined state effectively does nothing to the traffic signal.

[[File:traffic_light_state_table.png|400px]]

The above diagram shows a fully populated SST, with one signal row highlighted in red, and one state column highlighted in green. The associated intersection corridor is highlighted, showing the signal controls a dedicated left turn.

During simulation, the initial signal state is defined by the left column. As the simulation proceeds, the signal state changes according to the duration states defined across the state table, proceeding left to right and then wrapping around to the beginning after the last defined state. Each traffic signal appearance changes according to the configuration of the SST.

As a driver approaches this intersection, assume the signal state is in the column left of the highlighted column ('''R'''ed), and the desired action is to change the signal to green.

The action used to change a traffic signal state is the '''Traffic Light Action'''.
Using a traffic light action requires the specification of a signal state, the traffic signal to affect, and a duration.

[[File:traffic_signal_action1.png|400px]]

In the above diagram the scenario author has specified the desired state as '''Green''' as shown in the action dialog.

However, referring back to the previous state table diagram, there is no such state present in the SST. That means this particular action will fail, and the traffic signal will not change as the driver approaches the intersection - because the action does not create a new signal state, it works by advancing the state table condition (column) to the specified condition. If the condition is not present in the SST then nothing will appear to happen.

In this example, the action should be edited to use the correct signal state '''Left Turn Green''', which is present in the SST.

'''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

[[File:known_issue_traffic_light_action.png|400px]]

'''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.

[[File:known_issue_traffic_light_action_workaround.png|400px]]

====Change A Traffic Light Using Scenario Action====
To change a traffic signal, use the Set Dial >> Traffic Light action.
'''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

[[File:traffic_light_state_table.png|400px]]

This diagram shows a fully populated traffic signal state change for an intersection.

*Static object traffic lights
:These are objects, not true traffic signals and so they are not controlled with the Traffic Light manager.

==='''Traffic Source'''===
A traffic source is a coordinator used to create traffic at specific locations in the road map (unlike the Traffic Manager). This is useful for creating ambient traffic. Traffic Sources creates ADOs or DDOs at random or user-specified intervals.

Elements created using a Traffic Source will be created at the locations specified by the user. If traffic is specified at multiple locations the actual location for each creation will be determined randomly during simulation.

'''Note:''' Using the Relative Creation flag on ADOs created by the traffic source will not create traffic at the specified location on the map, but use the information in the Relative Creation fields to populate traffic in the scene during simulation.

This method allows for more flexibility but care must be taken not to create so many ADOs that miniSim is unable to make frame rate. Too many ADOs will cause the scene to jump and 'jitter' and it will feel slower than normal.

==='''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 ISAT scenario rehearsal

===Custom (icon) file virtual objects===

[[File:virtual_object_custom_icon_file.png|400px]]

'''Note:''' Some versions of MiniSim_2.3 do not support custom virtual objects. For those installs, if you require this type of functionality, a workaround exists in the form of a 2D model that can be customized (i.e, sprite).

Virtual objects may be customized using graphics files (texture images) to display any desired custom element. This typically requires the use of a bitmap graphic. Various file formats are supported: JPG, BMP, PNG. It is possible some types of these formats may not work - in those cases, try an alternate format.

If image transparency is required and the custom icon does not display during simulation, please email dsri-minisim@uiowa.edu with a description of the issue, your scenario and custom virtual object image file.

Custom icon files must be located within the Nads MiniSim path for resources - at NadsMiniSim_x.x\data\visuals\Models\ModelTx.

===Standard virtual object shapes===
The virtual object shapes include:
# Circle
# Triangle
# Octagon
# Star
# Diamond
# Icon <- this is for custom virtual object graphics
# Rectangle
# Hexagon

The virtual object fill and border color and transparency can be set in the virtual object properties dialog panel.

[[File:virtual_object_std_shape.png|400px]]

====Virtual Object Workaround====

There is a scenario authoring method that can be used to emulate virtual object functionality through the use of a DDO that is coupled to any dynamic scene element, including the External Driver. One model has been created to support this method called "sprite".

'''Note:''' The sprite model is a 2D object present in the scene, and can therefore be occluded by other scene elements during simulation.

[[File:trafsign_sprite.jpg|400px]]

The sprite model is designed as a flat plane that continuously faces the viewer. It contains different sized planes and can be customized through textures.

When authoring your scenario, configure the sprite object to Off unless it should be visible at scenario start. During the scenario you can control the sprite appearance with a setSwitch action.

[[File:sprite_setSwitch_action_021121.png|400px]]

The who to effect should use the name of the DDO placed in your scenario. The switch name will be s_sprite as shown above. Any valid option can be used. An invalid option (greater than 30) will disable the sprite the same as selecting the OFF option.

==='''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'''===
<span style="color:#FF0000">'''All trigger types share the same Action types'''</span>
*IF Then conditional
*Predicate: i.e., the activating agent
:If predicate is TRUE, then do Action(s)
*Road related triggers are categorized by predicate type
:Named element
:Road (lane)
:Nth vehicle on path only

'''What trigger is appropriate?'''
To determine which trigger is most appropriate, consider the task you are trying to accomplish. '''The differences between triggers is their activation methods.'''

'''Global Time Trigger'''
[[File:isat_time_trigger.png|150px]]

Use this trigger when something has to happen at some point in time.

Time triggers are also useful as "placeholder triggers"; used to apply persistent actions to multiple elements with unique settings for each element. Normally a persistent action is the last action possible in a trigger since the persistent action fires continuously. Putting persistent actions into a time trigger allows the scenario author to continue an action stack in the parent trigger if necessary.

Time triggers can be used as a 'stopwatch' - elapsed time, such as ending a drive after 3 minutes by setting the trigger to fire using an Activation Delay of 180s (GTT >> General).

Often used as a placeholder for actions such as initializing variables, displaying text messages to the screen using Set Visual Display Text actions, etc.

'''Note''': A time trigger can have global elapsed time and activation delay of 0, which causes the action stack in the time trigger to activate when that trigger is created.

'''Roadpad Trigger'''
[[File:isat_roadpad_trigger.png|150px]]

Use this trigger when something has to happen at some location in the drive that does not require event timing to be comparable for all participant drivers. For cases where event timing must be comparable among all participant drivers use the Time to Arrival trigger (TTA) instead of a roadpad trigger.

'''Time to Arrival Trigger'''
[[File:isat_time_to_arrival_trigger.png|150px]]

Use this trigger when something has to happen relative to some point in the drive, and also ensure all study drivers experience the same event timing irrespective of driver style (conservative, slow vs. aggressive, fast). Time to arrival (TTA) trigger uses a time calculation from the trigger pad activation to a target location specified in the trigger.

'''Traffic Light Trigger'''
[[File:isat_traffic_light_trigger.png|150px]]

This trigger activates actions when the specified traffic signal state is reached. For example, if the desired action is to create a DDO pedestrian to step into traffic when the traffic signal is yellow, then the Traffic Signal Manager must be used to author the appropriate signal states for the traffic signal.

Typically some other trigger is used to control the traffic signal (ie, to change the signal to Yellow on approach). It is therefore perfectly valid to put the actions within this other trigger rather than relying on the traffic light trigger.

'''Note''': Once a traffic light action has been authored, ISAT may be prone to crashing when accessing that trigger. This problem can be avoided by creating a time trigger and isolating the traffic light action there, allowing the parent trigger to be modified without crashing. Adjustments can be made to the traffic light action time trigger in a text editor, or recreated if it becomes necessary to make adjustments and ISAT continues to crash when trying to make edits.

'''Note:''' The traffic light action does not change the traffic signal state, and it requires a valid state sequence to exist in the signal timing table (Edit >> Traffic Light Manager). The traffic light action '''will not create a signal state''' that does not already exist in the signal timing table.

'''Expression Trigger'''
[[File:isat_expression_trigger.png|150px]]

Use this trigger when something must be monitored, evaluated or calculated such as checking a variable or cell value, velocity of the driver or the state of simulator hardware (steering wheel angle, brake or accelerator pedal position) or distance from the driver to some other object in the scenario.

Multiple expressions can be used within the same expression trigger. In those cases, all expressions must evaluate to True in order for the action stack to execute unless using an '''OR''' operator.

Use the '''OR''' operator - the pipe character "|" if you want to activate the action stack if '''any''' of the expressions evaluates to True.

In the following example, the trigger checks for TrialNumber = 1 and FirstButtonPress variables, and then checks if Aux Button 1 or 0 was pressed:

'''ReadVar('TrialNumber') = 1.0 & ReadVar('FirstButtonPress') = 1.0 & (ReadCell('Auxiliary_Buttons', 0) > 0 | ReadCell('Auxiliary_Buttons',1) > 0)'''

'''Note''': Expressions can also be embedded into some other triggers, most notably the Set Dial >> ADO >> Forced Velocity action often used in Roadpad triggers.

'''Follow Trigger'''
[[File:isat_follow_trigger.png|150px]]

Use this trigger when something has to happen based on one ADO position relative to another scenario element (including the XD). The follow trigger requires a leader and a follower to be specified; when this condition is met, the trigger action stack activates.

'''Note''': Both leader and follower must be positioned on the follow trigger roadpad to satisfy the follow parameters.

'''Geometric Position'''
[[File:isat_geometric_position_trigger.png|150px]]

This trigger is most useful to perform actions for off-road actors such as walkers. The trigger predicate is limited to Name or Type and requires a geometric position to be defined.

A more limited version of the geometric position trigger can be implemented with a Global Time Trigger that contains a Creation Radius. Placing the creation radius defines the area where the trigger may be activate.

===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

[[File:Screenshot (208).png|800px]]

'''Note:''' The highlighted lane shows which lane is the '''activating lane'''. Other lane/s will not activate the trigger action stack.

===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

[[File:TTA.png|400px]]

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===

[[File:other_triggers.png|400px]]

*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===

Execute actions if input expression evaluates to TRUE; the expression is specified on the trigger Predicate tab.

====Syntax====
Expression triggers support a simple language syntax with operators and functions.
The syntax is infix notation; i.e. a + b, not a b +.

Note: It is not generally possible to embed one function call inside another:
cos(sin(x)) is therefore an invalid expression. ISAT will report invalid expressions during rehearsal of a scenario. Invalid expressions are not supported and will not operate as written during simulation.

'''Exception:''' Currently it is possible to use the square root function with GetObjDistPow2 as in the following example:

sqrt(GetObjDistPow2('Target_Object_Name'))

Multiple expressions may be combined using the logical AND (&) or OR ("|" pipe character).

Exp1 '''&''' Exp2, Exp1 '''&''' Exp2 '''&''' Exp ''N''

All expressions must be true for the trigger to evaluate to TRUE and execute the action stack.

Exp1 '''|''' Exp2
One of the expressions must be true for the trigger to execute the action stack.

Negative values are not directly supported by the expression parser. To use a negative value, it must be a calculated value such as the following:

'''ReadCell('CFS_Steering_Wheel_Angle',0)<(0-5.0)'''

==== Operators ====
Operators are used to create expressions.

'''String'''
:Used within quotes as a string literal; i.e., 'some string'

Grouping
:Parentheses group elements together; i.e.,
:'''()'''; (a), (a + b)

Multiplication
:'''*'''; a * b

Division
:'''/'''; a / b

Addition
:'''+'''; a + b

Subtraction
:'''-'''; a - b

Note: negative values must be expressed with a subtraction operation:
(0 - 5), not -5 (invalid)

Greater than
:'''>'''; a > b

Less than
:'''<'''; a < b

Logical And
:'''&'''; a & b

Both a and b, otherwise returns 0 (FALSE)

Logical Or
:'''|'''; a | b

a or b returns 1 (TRUE)

====Expression Functions ====
Functions are used with operators to create expressions.

Function: '''sin'''
:sin -sine

Syntax
:sin(float x)

Description
:The sin() function returns the sine of x, where x is given in radians.

Return Value
:The sin() function returns a value between -1 and 1.

Function: '''cos'''
:cos –cosine

Syntax
:cos(float x)

Description
:The cos() function returns the cosine of x, where x is given in radians.

Return Value
:The cos() function returns a value between -1 and 1.

Function: '''ReadCell'''
:ReadCell()

Read a Cell value.

Syntax
:ReadCell(string Name, int Cell Array index)

Description
:ReadCell returns the value of a given cell (a cell is the current instance of a variable that will be maybe written to a daq file).

Index specifies a 0 based index into the array. Since most cells are single element arrays, a value 0 indicates the first element.

Cells valid for the ReadCell function are defined within the cell collect file NadsMiniSim.cec located in the miniSim_x.x\data folder.
The ReadCell function operates on shared memory during simulation, it does not read cell data from the DAQ file.

Cells that are defined may be written to the DAQ; the collect file specifies which cells are saved into the DAQ and what frequency to use for the write operation.
The NadsMiniSimCollect.general.txt file is located in the miniSim_x.x\data folder.

Available Cells:
Any cell that has been defined in the .cec file. For example:

:'''LogStreams''': Array of 5 floats. Logstreams are a set of values the scenario author can write to through “write to logstream” actions.
:'''AccelPedalPos''': Single Value. The current position of the accelerator pedal
:'''BrakePedalForce''': Single Value. The current force on the brake pedal in pounds
:'''SteeringWheelAngle''': Single Value. The current rotation of the steering wheel
:'''CruiseControl''': Single Value. The current cruise control position. (values are cab/platform specific)
:'''TurnSignal''': Single Value. The current position of the turn signal (values are cab/platform specific)
:'''OvVel''': Single Value. The participant’s current speed in miles per hour
:'''OvLaneDev''': Single Value. The participant’s lane deviation in feet.
:'''OvHeadwayToLeadVeh''': Single Value. The distance in feet to the first vehicle in front of the participant. -1 if no vehicle can be found.
:'''OvTtcToLeadVeh''': Single Value. The time to collision to the first vehicle ahead of the participant.
:'''Horn''': Single Value. The state of the horn (values are cab/platform specific)
:'''DynObj_Vel''': Array of 20 floats. The speed of a given dynamic object. Dynamic Objects are sorted in terms of distance to driver.
:'''OvVelLocal''': Single Value. The participant’s current speed in miles per hour, using the value local to scenario control

For a complete list of cells and array elements please see the miniSim data dictionary spreadsheet.

Return Value
:Returns the value of the specified cell.

Example
ReadCell(‘LogStreams’,5) > 3

Function: '''CellEquals'''
:Cell Equals, array element, value to compare

Syntax
:CellEquals(string name, int index, float value)

Description
:The Cell Equals function is similar to the ReadCell function, except it adds an additional value to compare against the cell value.

Like ReadCell, name specifies the name of the cell, index specifies the cell array index (use 0 for single value cells).

Available Cells:
:Any cell that is defined in the .cec file.

Return Value
:Units: 1 or 0
:1 if the cell value is equal to the passed in comparison value; otherwise 0

Function: '''GetObjDistPow2'''
:Get object distance squared

Syntax
:GetObjDistPow2(string name)

Description
:GetObjDistPow2 returns the distance squared between the external driver and the dynamic object specified by ‘name’.

Distance squared is used to avoid having to perform an expensive square root calculation every frame.

If the specified object cannot be found, a value larger than 100 million is returned.

Return Value
:Feet; Distance in feet measured from the eye position of the driver to the CG (centroid) of the dynamic object specified.

A very large number is returned if the specified object cannot be found (larger than 100 million)

Example
:GetObjDistPow2(‘OncomingCar1’) < 2500

'''Note:''' To get an actual distance, multiply by the square root (sqrt())
: sqrt(GetObjDistPow2('Target_Obj'))

Function: '''GetObjTtcToOv'''
:Get Object Time To Collision to Own Vehicle

Syntax
:GetObjTtcToOv(string object name)

Description
:GetObjTtcToOv gets the time to collision from the dynamic object specified by the name parameter, to the own vehicle.

Return Value
:Unit: Seconds
:Time (seconds) to collision from the own vehicle to the dynamic object specified by the name parameter.
:0 is returned if the object specified cannot be found.

Function: '''GetObjVel'''
:Get Object Velocity

Syntax
:GetObjVel(string object name)

Description
:GetObjVel gets the velocity in meters per second of the first dynamic object with the name specified by the ‘name’ argument.

Return Value
:Unit: Meters per second
:The speed of the specified dynamic object; 0 if no object is found

'''Note:''' Multiply by 2.23694 for miles per hour.

Example
:GetObjVel(‘PullOutVeh’) > 15.4

Function: '''Rand'''
:Random

Syntax
:Rand(int value)
:Rand(string name)
:Rand(string name, string type, double parameter, double parameter)
:Rand(string name, string type, int parameter, int parameter)

Description
:Rand returns a random value specified by the name of the generator, the type of distribution and its parameters.

If the user does not specify the name of the generator and only specifies a number as the only parameter, the Rand function will use a default random number generator to produce random numbers.

If the user only enters the name of a user created random number generator, the random number generator will produce a value between 0 and 1.
If a name of generator is supplied that has not been created, the Rand function will display an error message in the ISAT debug window and return 0 (during scenario rehearsal).

The rand function supports multiple types of distributions that can be used to generate a random number.

Types of Distributions:
:normal: Normal Distribution(mean, standard deviation). The normal distribution generates random numbers near the mean with a specific standard deviation.
:gamma: Gamma Distribution(alpha, beta). The gamma distribution generates a random value that models waiting times for the Poisson process.
:uniformInt: Uniform Integer Distribution(min, max). The uniform integer distribution generates a random integer number between the lower and upper bounds.
:uniform: Uniform Real Distribution(min, max). The uniform real distribution generates a random floating point number between the lower and upper bounds.

The values stated in the parenthesis above are the parameters for each distribution in order. If the incorrect number of parameters are entered or if they are entered incorrectly, the debug window in ISAT will display an error message and the rand function will return 0 (during scenario rehearsal).

If the distribution is entered incorrectly, the debug window will also display an error message.

Return Value
:A random value from 0 to 1 if the type of distribution is not specified.

If the type of distribution is specified, returns a random value determined from the type of distribution and the given parameters.

Example
:Rand(‘myRandGenerator’,’uniformInt’,1,10)
:This example returns a random integer value from 1 to 10.

Rand(5) or Rand(‘myRandGenerator’)
:These examples return a random value between 0 and 1.

Function: '''sqrt'''
Square root

Syntax:
:sqrt(parameter)

Return Value:
: return the square root of the specified parameter.
: parameter can be another function, such as GetObjDistPow2()

Function: '''ReadVar'''
:Read a variable

Syntax:
:ReadVar(string Name)

Return Value:
:Returns the string value of variable specified in <variable_name>

===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.

=='''Audio Components'''==
The components of the Audio sub-system includes configuration and data files installed into the NadsMiniSim_x.xx\data\sound\DefaultCabSound\Instructs folder.

[[File:audio_components.png|400px]]

The audio engine contains multiple channels and has a theoretical limit of 512 simultaneous sounds.

NOTE: Not all .wav files are compatible with the Audio Engine.

=Scenario World Objects=
Scenario world objects are defined in the tile model source. They are not added by the scenario author since they are objects already present in the roadmap/BLI.

[[File:object_types_world.png|400px]]

Typically, but not always, these objects can be authored in ISAT. However, some scenario world objects have no options - these cannot be selected in ISAT; therefore such objects cannot be authored.

Removal of world objects requires editing the source tile model using a 3D application. In some cases an alternate tile model is available identical to the original but without objects.

Contact NADS if removal of a world object is needed.

Other scenario world objects, such as Traffic Signals, are specialized function objects that can be authored. Traffic signals are authored using the Traffic Light Manager: Edit >> Traffic Light Manager.

=Troubleshooting Scenario Objects That Reset=

== Scenario World Objects ==
Scenario world objects are already present when you create a new scenario - they are not added by the scenario author. These objects may be visible in miniSim but not in ISAT, or they may be visible in ISAT and seem to be controllable, but the objects 'reset' to their defaults when viewed on miniSim.

[[File:2019-10-23_16h18_47.png|700px]]

The objects which 'reset' are a symptom of settings in the TMT that are not configured to allow scenario authoring of objects.

[[File:2019-10-23_16h18_52.png|700px]]

When objects appear to 'reset' or if you can edit an object in ISAT but don't see your changes in miniSim, correct the problem by resolving controllability in the TMT settings: https://www.screencast.com/t/ZH5Dh178.

=Scenario Coordinate Types=
There are two types of coordinates used in scenarios. The first is roadway coordinates. These coordinates are contextual (tied to a specific road or intersection and position) and are used for ADO objects and roadpad paths in general.

After a roadway coordinate has been generated, it is not updated unless the scenario author makes changes to the start, end or location of the entire path or pad.

Roadway coordinate are the reason it is not possible to change a roadmap using the TMT and expect a previously authored scenario to work on the altered roadmap. If the length or location of a road changes, the path/pad will update to the extent possible.

If the road has been eliminated and no longer exists in the roadmap/BLI, ISAT will report an error and not open the scenario file.

A. Field breakdown:
RoadPos keyword <name of road:lane:position on road:path length>

Name "Ado1"
RoadPos "r1_-6600_4620:0:5737.06:0.00"
Path "R:r1_-6600_4620:0[5736.06:5873.83]"

[[File:isat_coordinate_types.png|400px]]

B.
Name "VirtObj"
Option 2
Position -6.8375599E+002 5.6331237E+003 0.0000000E+000

The second type is world coordinates, which are Cartesian coordinates with X increasing to the right, Y increasing forward, and Z increasing up.

='''Scenario Authoring'''=
Scenario authoring is the creation, editing and testing of everything that happens during a simulation drive.

==Cell Operations: Best Practice==
Reading and writing to cells is a computationally expensive process. Best practice is to centralize all the reads/write to one place so that it’s only done once per cell.

Once a cell is read, the value is copied to a variable and only the variable is used throughout all the triggers that need it.

The same process applies to writing to cells. Use of variables can reduce the Cell Operations overhead greatly.

===How to write to a specific cell array element?===

To write to a specific cell array element, enclose the array element in square brackets as shown below:

[[File:Screenshot 2023-10-02 133413.png|400px]]

==Before You Begin==
Before beginning a scenario, it is necessary to understand the following requirements:

=== Drive Requirements===
How long is the drive?
What type of roadway?
Are there any specialized road elements (intersections, interchanges, freeway ramps)?
Are there any environmental requirements (should the simulation replicate a real world location, or is a generic environment acceptable)?
Is there a particular roadway configuration that is needed (long straight rural road vs. typical urban environment with intersections, signals, etc)?

=== Traffic Requirements ===
What types of traffic will be needed?
Will ambient traffic interact with the external driver?
What types of interaction will be required (traffic cloud, lead vehicle, follow vehicle)?

=== Events ===
The purpose of an event is to present a situation to the external driver. In order for the simulation to produce meaningful data, it is critical that events unfold for each driver in a comparable way. Therefore, each event must be designed with this repeatability in mind.

'''NOTE:''' one of the most variable scenario elements is the driving style of each external driver: how conservative or aggressive they drive, velocities throughout the scenario, how comfortable the driver is travelling with simulated vehicles, etc.

Repeatability often includes static elements (each driver encounters scenario elements in the same location) or in cases where the driver performance is taken into account, accommodation of the driver dynamic (velocity, lane position) through the use of time to arrival triggers (TTA) or follow triggers. A TTA trigger will fire based on time to a target location - thus a driver travelling at 45mph or a driver travelling at 55mph can both experience the same action relative to that target location, irrespective of the different driver velocities.

==Beginning A Scenario==
All scenarios designed to be driven require a start location - the place where the driver will be located when the simulated drive begins.

To insert a start location into a scenario:

:Insert >> External Driver >> LMB on road, intersection or terrain object

[[File:isat_initial_position.png|400px]]

'''NOTE:''' scenarios that only contain data and are not intended to be driven - for example, signs or traffic that are used as external reference files do not require a start location, since that will be defined within the parent scenario.

==Initial Conditions==
Initial conditions define how the simulated scene is configured: will the drive occur during daylight or night time conditions? Will the ownship (external driver vehicle) have headlights enabled? What type of vehicle will it be? Will there be objects or traffic visible to the driver?
These form the initial conditions of the simulation experience. Additional initial conditions would include initialization of variables or establishing networked communication as needed by the scenario.

[[File:isat_initial_conditions_miniSim.png|400px]]

By default ISAT sets the initial condition '''Time of Day''' to 12:00 noon. The time of day is controlled from the Initial Conditions dialog:

Edit >> Initial Conditions

[[File:isat_initial_conditions_scenario.png|400px]]

==Scenario Authoring: Actions==
Actions are the scenario elements that make things happen during simulation. Actions do specific things, like display a text message on screen for the driver, create a scenario element, change the velocity of simulated traffic, change a traffic signal, etc.

[[File:trigger_action_panels.png|400px]]

The diagram above shows the action panel for left to right: an expression trigger, a roadpad trigger and a global time trigger showing different panels based on the actions present in each trigger.

'''NOTE:'''Actions can be created, edited or removed from the '''Actions panel''' of '''any trigger'''.

'''NOTE:''' The Actions panel changes based on the action type created.
When multiple actions have been defined, control the sequence of actions by changing the action order in the list using the up or down arrows next to the list.

[[File:action_panel_overview.png|400px]]

If multiple actions need to happen in a specific order, set the order using the arrows and then flag the action list as '''sequential'''. This instructs behaviors to process the actions in the list order.

Using a delay for any action will pause processing of the '''following actions'''; the action happens first, then the delay is applied.

===Scenario Authoring: Action Types===
There are two types of actions:
# Instantaneous - the action takes up to one frame to complete, i.e.:
:set target velocity
:write to cell
# Persistent
<span style="color:red">'''*Persistent actions do not end'''</span>, or take multiple frames to complete:
:Forced lane offset
:Forced velocity
:Maintain Gap

==='''Actions'''===
*The "Who to Affect" field defines what is affected by the action
:Instigator set: who activated the trigger
:Name: one or more named elements
:Type: Apply changes to all objects matching the specified type
:Relative: Position relative to the trigger location

*Sequential
:Actions to execute sequentially, one after the other
:Specify delay between actions
:: Action executes, then delay

:Some actions are persistent and never "finish"

===Scenario example: display text & roadpad trigger to stop the drive===
This scenario is very simple and contains a global time trigger (GTT) that tells the driver what to do. After the driver travels along the roadway, a roadpad trigger (RPT) is used to tell the driver to stop driving. The same RPT also creates an expression trigger to terminate the drive.

TBC example scenario file

Because the external driver is not under control except by instructions, it's possible they might ignore the halt message and continue driving. A second failsafe RPT then terminates the drive.

==='''Actions: Button vs. Dial'''===
*Dial changes a setting
*Button: always runs in a single frame
:-"immediate" change. Typically buttons have less control than a '''Set Dial''' action

==='''ADO Actions'''===
[[File:ado_action_types_button_vs_dial.png|400px]]

==='''DDO Actions'''===
[[File:ddo_set_dial.png|400px]]

==='''External Driver Actions'''===
External driver behavior can be influenced by reinforcing scenario actions through audible speeding alerts, on-screen text instructions and messages or audio instructions.

Driving behavior can be influenced with situational elements
:Car in the drivers blind spot
:Lead vehicle
:Aggressive following vehicle
:Temporary lane closure
:lane specific instructions

Scenarios should '''not rely on specific driver actions to be successful'''
:to the extent possible; sometimes you do need the driver to respond/behave in a controlled manner.
:A work zone blocking one lane typically will require a roadpad placed upstream from the work zone to shift traffic into the correct lane

'''NOTE:''' Controlling driver actions should be an experimental design consideration.

==='''Special Actions'''===
These actions need special handling:
*Reset or "toggle":
:Audio
:Display Text

:'''Ado'''
::Audio State
::Forced Velocity
::Maintain Gap
::Visual State

*If using these persistent actions, place them at the '''end''' of an action sequence (because no action following these will execute):
:Forced Lane Offset
:Forced Velocity
:Maintain Gap
:Visual State

*Note: If the Visual State action contains a duration then it will be handled as a normal action, with subsequent actions firing after it. However, if there is no duration supplied with the Visual State action it behaves like a persistent action, and nothing following it in the Action stack will ever fire.

[[File:multiple_simultaneous_actions.png|400px]]

The diagram above shows how one parent trigger can be used to create multiple simultaneous triggers

*How to activate multiple unique force velocity (FV) or maintain gap (MG) actions:
#create the needed triggers from a general parent trigger, 1 per action
#put common actions into the parent trigger
::reset FV
::reset MG

==Scenario Authoring How To==
This section contains simple examples for various typical scenario situations.

===How do I specify an event?===
First, determine which method is best for you - the default measures (limited measures, 20 events max) or logstreams (all simulation data, no event maximum).

Regardless of method, you specify an event by identifying areas of significance in the drive and marking them so the data within the event region can be processed. Any trigger combination that can specify event start and event end may be used.

[[File:2022-07-01_11h21_52.png|400px]]

===How to know Which Coordinator or Trigger I need?===
The answer to this question lies in the type of information needed for an event:

*Time
:global time trigger
:or an expression trigger that calculates time
*Position or Location
:roadpad trigger
::or a time to arrival (TTA) trigger
::or an expression trigger that calculates distance
*Calculation
:Expression trigger

===How to Instruct the External Driver===

Instructions to the external driver can be accomplished by three main methods:
# Instruct the driver using experimental protocol (instructional or briefing presentation)
# Information messages displayed on screen: '''Action: ''set visual display text'' '''
# Information messages delivered as audio messages: '''Action: ''write to cell > SCC_Audio_Trigger ><audio ID>'' '''

===How to Add Traffic in the Scene ===

Generating traffic will happen in one of 5 ways:
# Created explicitly by inserting ADO, or copy/paste existing ADOs
# Created with a script
# Via a Create action inside a trigger, or placing scripted traffic inside a create action within a trigger
# From a '''Traffic Source'''*
# From the '''Traffic Manager'''**

Each of these methods has advantages and disadvantages.

==== Create Explicitly ====

The biggest advantage with this method of traffic creation is the high degree of control the scenario author has over:
# location of the created ADO
# Name of the created ADO
# Travel path of the created ADO
# Control when each ADO is created within the scene via Settings >> Creation Radius

The disadvantage is that creating a high volume of traffic will take some work with this method.

==== Created with a Script ====

This method combines the advantages of Creating Explicitly with volume. It is possible to create a large volume of traffic very easily with a script.

Disadvantages of using high volumes of traffic with a script: in the event it becomes necessary for a high degree of control over these ADOs, more is not better because ADOs will adapt to road conditions under their own power, unless the default ADO settings have been modified:
'''lane changes, including lane changes to accommodate freeway ramps'''
'''velocity adjustments'''

==== Via a Create action inside a trigger ====
Combines the advantages of the previous 2 methods with control over when to activate that traffic using a trigger action.

Disadvantages: Creating too many ADOs at one point in the drive can cause the miniSim to bog down for a few frames. If too many ADOs are present and active in the simulation at one time, this can cause the miniSim to drop frames and run sluggishly. This is highly noticeable and may increase the potential for the External Driver to experience '''simulator sickness.'''

==== From a '''Traffic Source''' ====

Traffic Sources rely on two methods to populate a scene with traffic:
# location specific, with each ADO created for a traffic source being a 'spawn location' for ADOs, or
# location agnostic if the ADO has '''relative creation''' enabled, thus being created relative to the object identified.

In addition to being created relative to a scenario element, ADOs are created relative to the specified scenario element:
# In front of (Longitudinal Distance > 0, where the number is feet offset from the object) , or
# Behind (Longitudinal Distance < 0, where the number is feet offset from the object).

Advantages: Can easily populate traffic into the simulation.

Disadvantages: It is easy to generate more traffic than the simulation can maintain at 60Hz frame rate, thus introducing frame lag with the resulting scene 'stutter' and the increased risk of simulator sickness.

Also, traffic created from a Traffic Source is generic traffic. It is not possible to reliably refer to specific ADOs generated from a traffic source except by using Who To Affect >> Relative (versus referring to a named ADO, i.e. Slow_Moving_Lead_Vehicle). Referring by name to Traffic Source generated ADOs will affect all similarly named ADOs at the same time.

==== From a '''Traffic Manager''' ====

The traffic manager interface is problematic in ISAT versions up to 1.8.5, especially when specifying the set of vehicles to be used for generating traffic.

Advantages: Create generic ambient traffic easily.

Disadvantages: Has the same disadvantages as traffic created via a Traffic Source. Also getting a traffic set working by specifying the vehicles to be used within the set. ISAT versions up to 1.8.5 exhibit instability when setting vehicles in ISAT.

Traffic Manager Set workaround: Borrow a working set from an existing scenario or group. Alternatively use a version of ISAT (1.8.6 +) to create the traffic set. This can be saved as a scenario or group file, which can then be used with ISAT 1.8.x as long as there is no attempt to adjust the vehicle weights within ISAT. The scenario or group file can be edited as text in a text editor, but care must be exercised to avoid introducing errors into the file. ISAT will not read invalid scenario or group files.

Traffic generated by the Traffic Manager is controlled through the use of Input Sets. An input set is a collection of vehicles and weights used to populate the scene during simulation. This is how the scenario author can control the vehicle population (type and number), density and creation/deletion distances - these attributes are unique to each set.

Since there is no 'discontinue traffic manager' function, one can be implemented by defining an input set with no traffic (an empty input set). An appropriate name can make the purpose of the set clear: PauseTraffic, Stop_TM, etc.

==== Sample Traffic Manager Set ====
This is a sample traffic manager set that can be pasted into a scenario file after the HCSM VehFail section. Be sure to paste '''after''' the HCSM VehFail end tag ('''&&&End&&&''') in your scenario file.

'''Note:''' A scenario file may contain only '''one''' Traffic Manager section.

There are two input sets in this example; note how they contain different vehicles and different settings from each other.

<span style="color:#2a4b8d">HCSM TrafficManager
GroupName "Traffic Manager"
HCSM InputSet
Name "ONE"
MinDensity 3.0000000E-002
MaxDensity 7.0000000E-002
MaxObjects 9
CreateDist 2.0000000E+003
DeleteDist 3.0000000E+003
AbsDeleteDist 3.4000000E+003
RunFreq 1.0000000E+000
SolWeights "cargill_semi_peterbilt_blu:2" "cargill_semi_freightliner_red:1" "cargill_semi_peterbilt_yel:3" "DumpTruck_org:3" "semi_peterbilt_yel_Walmart:2" "Cadillac_Escalade:10" "Ford_F150Xcab:15" "Saturn_Vue:10" "FordTaurus:15" "Escape:15" "DumpTruck:2"
&&&&End&&&&
HCSM InputSet
Name "TWO"
MinDensity 1.0000000E-002
MaxDensity 3.0000000E-002
MaxObjects 4
CreateDist 2.5000000E+003
DeleteDist 3.3000000E+003
AbsDeleteDist 3.5000000E+003
RunFreq 1.8000000E+000
SolWeights "Taurus2011:12" "Cadillac_Escalade:16" "Ford_F150Xcab:24" "Saturn_Vue:14" "Escape:6" "Deville:24" "Audi:4"
&&&&End&&&&
&&&&End&&&&
</span>

====='''Managing Traffic Manager Input Sets'''=====
During simulation, Input sets are controlled by the action '''Use Traffic Manager Set'''. A set name must be provided for this action to work.

===== Traffic Manager generated Traffic=====
ADOs will populate the road network around the XD based on the parameters of the Input Set. Typically traffic is removed from the scene shortly after passing the XD. This is visible in the rear view mirror. There is currently no way to adjust this delete distance.

====== Traffic Manager Traffic on 2 lane freeway======
Traffic will prefer to be in the XD lane, so ADOs created in any other lane will tend to veer into the XD lane. On a divided highway, traffic is generated moving with the XD.

====== Traffic Manager Traffic on 2 lane road======
Traffic is generated in the oncoming lane. In some cases traffic may be generated then immediately removed in front of the XD.

===How to Control Objects in the Scene during Simulation ===
"Set and forget" options on simulation entities only require the scenario author to "initialize" the element to a desired setting and then it is left alone during simulation.

Controlling objects dynamically during simulation requires the scenario "talk to" each object with a scenario action. This section describes how each scenario object type can be controlled during simulation within a scenario.

All models used in ISAT are listed within the Scenario Object Library (sol2).txt files. Terrain switch names are displayed in the ISAT workspace.

All model switches are listed within the NadsMiniSim_x.x\bin.x64\ModelList.txt file.

'''Note:''' The diligent reader will note discrepancies in model names between the sol2 and ModelList files. This is because the ModelList file contains actual file names, and the sol2 files define a "name label" for models that may, or may not, be the actual model name. Objects are linked between the sol2 and ModelList files through the ModelID/CigiID records. These values will match between sol2 and ModelList files, but IDs are not necessary at this time for scenario authoring purposes.

Complicated object names can be retrieved from the LRI file that was used to build any scenario file; each BLI is preceded by an LRI. The LRI contains all of the terrain models that will be present in ISAT. These are typically speed limit signs, traffic signals or other features that may be controllable.

'''Note:''' this file may not be present for the Springfield.bli file.

An alternative is to capture a screenshot of the ISAT workspace with the element name string showing. By default ISAT reports the name of any objects when the cursor passes over the object, as shown in this example:

[[File:2021-10-27_08h50_14.png|caption =Object Name Screenshot | 400px]]

{|class="wikitable"
|+ Controlling Scenario Elements During Simulation in Scenario
!Date
!Nads miniSim version
!Object Type
!Scenario Action
!Who To Affect
!Value
!Notes
|-
| Oct. 28, 2021
|2.3
|-
|
|
|Static Object (terrain)
| SetDial > StaticObjManager > Set Option1
| StaticObjManager
| switch name : switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
|Static Object, multiple options
| Set Switch
| Name of element
| switch option
|-
|
|
|Obstacle, multiple options
| Set Switch
| Name of element
| switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
| DDO, multiple options
| Set Switch
| Name of element
| switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
| ADO
| Set Dial > ADO > VisualState
| Name of element
| Limited to options present in ISAT
|-
|
|
| Traffic Signal
| Traffic Light
| Assign action to element
| Target state
| Target state must exist within the Traffic Light Manager intersection timing table for the specified signal

|}

===How to Control Simulated Vehicles===
The scenario author can control simulated vehicles by controlling the environment:
#change a traffic signal to cause an ADO to stop or start at intersections
#affect other ADOs to cause a target ADO to respond
# assign a path for the ADO to travel

Direct control:
*Lane related:
:Set button > ADO > ChangeLane, Turn, ProjectAndResetLane

*All other controls:
:Set Dial > ADO > AudioState, ForcedLaneOffset, ForcedVelocity, InhibitLaneChange, LaneChange, MaintainGap, TargetVelocity, VisualState, AudioState

====How to Change ADO Velocity====
ADO velocity can be changed using the SetDial action:
:SetDial > ADO >

:ForcedVelocity
:ForcedVelocity using an expression:
# match external driver speed
expr % OvVel(0) %
# multiply external driver speed
expr -1 9 %ReadCell('OvVelLocal',1)*1.75 %
:TargetVelocity

Indirect Control (dependent on other scenario element):
:MaintainGap

====How to Link ADO Velocity to Something Else====
ADOs velocity can be linked to other ADOs or the external driver using the MaintainGap (MG) action.

SetDial > ADO > MaintainGap

When using a traffic cloud containing multiple ADOs, each ADO in the cloud needs a unique MG. IF multiple ADOs have the same MG settings they will attempt to satisfy their parameters and likely oscillate position in a visually obnoxious way.

===How to Author Loop Scenarios===
A scenario created on a loop road network operates very much like any other scenario, with the exception that it is likely to require tracking the number of times through the loop, or to present scenario events to the external driver depending on each loop context.

[[File:loop_traffic_creation_01.png|400px]]

The simplest method of tracking loops is the use of a loop counter variable. This variable can be set by the driver "stepping onto" a roadpad trigger or it can be initialized through the use of a timer or expression, with increments managed by a roadpad trigger. Each time through the loop increases the loop count variable.

Thus it becomes possible to create events for each loop based on the loop counter variable, typically through an expression trigger.

Loop management triggers

[[File:loop_management_02.png|400px]]

Loop management trigger detail one

[[File:loop_management_vars_02b.png|400px]]

Loop management trigger detail two

[[File:loop_management_3.png|400px]]

====Creating Loop Specific Traffic====
Creating loop traffic is slightly more complicated due to the number of objects to be created and potentially the size of the actual loop. A small loop is installed with the Nads miniSim as simple_rural1 or simple_rural2. Each is a loop road network with two signed 3-way intersections.

Loop specific traffic can be created through the use of a variable (i.e., LoopCount) or within the roadpad trigger that is incrementing the loop count variable. Both methods will incorporate a '''Create Action''' that creates the required elements.

===How to Change Environment Settings===
The scenario author can define global or localized environment conditions.

1. Insert >> Environment Conditions >> <chosen condition>

2. Define a region where the environment condition is active:
:LMB to define polygon points
:RMB to exit point entry mode

[[File:env_condition1.png|400px]]

Choosing an environment condition

[[File:env_condition2.png|400px]]

Environment region defined and parameters panel shows available options

NOTE: The environment condition boundary is a discrete threshold. Condition A will be on one side of the threshold. Immediately after crossing the boundary, condition B will be displayed.

===How to Fade an Environment Condition===
To fade gradually between two conditions requires the use of an expression that continually monitors the desired condition and sets a few variables based on the results.

Examining the demo scenario is the best way to look 'under the hood' to see exact command syntax and values to be used.

[[File:env_fade.png|400px]]

Note: this approach has been used for fog and visibility. It is unknown how it might work with non-visibility conditions such as precipitation and wind.

*From the scenario demo_visibility_transition.scn

[[File:env_fade_schematic.png|400px]]

'''Note:''' although the example above uses an environment condition boundary, '''it is possible''' to omit the defined region, retaining all commands and the scenario will still function. However, without the environment region, it becomes more difficult to determine where conditions are different from the standard settings.

===How to Control a Cab Instrument Panel icon===
In order to control the instrument panel, there are 2 requirements:
The specific cab used for the scenario
The specific control (switch) to be manipulated
The action for addressing the instrument panel is '''ChangeCabSetting'''

Instrument panel models are located in NadsMiniSim_x.x\data\Visuals\Instruments
These files are in OpenFlight format. Any 3D editor capable of reading or importing OpenFlight can be used to review these files. NADS uses the Presagis product Creator[tm].

An alternative method to inventory switches is to use the the '''buildscl.exe''' tool. To run the tool, open a CMD window to the IP folder location above, then run the command:
buildscl <input_file.flt><Enter>.
<input_file.flt> is the name of the file to process, without the '<>' characters.
<Enter> means to press the Enter key,

The result will be in a new file ending with .scl. This is a text file, and can be opened in a text editor or you can use the shell utility '''more''' to view the file contents:

more <input_file.scl> | grep switch<Enter>

An example for the malibu cab is shown below. .

switch s_LowWasher 0
switch s_Cruise 1
switch s_LeftTurn 2
switch s_RightTurn 3
switch s_FwdCollisionWarn 4
switch s_BlindSpotWarn 5
switch s_LaneDeviationWarn 6
switch s_RearCollisionWarn 7
switch s_HighBeamHeadlights 8
switch s_SeatBelt 9
switch s_UpArrow 10
switch s_Airbag 11
switch s_CheckEngine 12
switch s_CheckGuages 13
switch s_ABS 14
switch s_Brake 15
switch s_LowFuel 16
switch s_Gear 17

These controls may be accessed directly in scenario using the ChangeCabSetting action.

'''NOTE:''' Some functions such as Cruise, Gear, High beam headlights, Blind spot, collision, lane deviation warnings are '''normally''' controlled not by direct access as described here but by hardware mechanisms/buttons.

'''NOTE:''' For altering cab instrument panel operation it will be necessary to modify the OpenFlight model to include the desired funationality; for example, instrument panel blanking is not build into the model but can be added by editing the cab instrument panel model file then installing the modified file into miniSim.

===Scenario Hints===
The total number of scenario elements active at any given time can affect simulator performance:

Total number of active elements
*vehicles (ADOs), triggers, animations, etc.

Object management
*Use paths to shift ADOs away from the driver route of travel as they turn off the route
*reduce the number of vehicles in traffic cloud surrounding external driver
*use creation radius to limit the number of active elements, and to remove elements after the driver has traveled beyond the creation radius

[[File:creation_radius_1.png|400px]]

Creation radius works by activating the scenario element only when the driver is within the radius. The scenario element is created when the driver enters the creation radius, and is deleted after the driver leaves the creation radius.

Exploit environment to reduce object load

*Use curves, hills, intersection corners to mask objects

Object deletion
*Remove objects when no longer needed

When creating dynamic elements, create them as close to where they are needed as possible.

====How to Determine When ADOs are Visible to the External Driver====

Some development/setup testing may be needed to determine precise location/distance/speed; i.e., locating ADOs for a freeway ramp merge event where the external driver is merging onto the freeway with other ambient traffic present.

Unless the purpose of the event is to study driver behavior at the merge, ideally the scenario will be authored to have ambient traffic on the freeway but not to present a conflict at the merge for the external driver.

A straightforward way to determine where the ADOs are first visible to the driver is to mock up a scenario placing colored ADOs along the freeway with a velocity of 0. This will ensure the ADOs remain stationary while the scenario author determines where they are first visible to the external driver.

Place the start position/external driver far enough up the ramp to be a reasonable test for the actual scenario.

As you drive the ramp, see which ADO is first visible to the driver. Place ADOs just out of view (upstream) of that location.

[[File:merge_hint.png|400px]]

'''NOTE:''' use test vehicles of the same type and character as the intended scenario vehicles. For example, do not use a sedan test ADO for a larger vehicle (SUV, bus, dump truck). Doing so will invalidate the visibility test, because a larger ADO will be visible over a longer distance than a small ADO.

[[File:ramp_vis_1.png|400px]]

At the scenario start location, ADOs in front of the Coke truck are visible. Note how the larger vehicles are more obvious at this distance.

[[File:ramp_vis_2.png|400px]]

The driver has traveled onto the ramp. At this point, the last ADO visible to the driver is still the Coke truck.

[[File:ramp_vis_3.png|400px]]

As the driver travels farther down the ramp a small ADO is visible behind the Coke truck.

The answer to the question '''When is an ADO visible?''' is thus:
#It depends on how large the ADO is
#Small ADOs can be placed at the location of the red ADO behind the Coke truck.
#Large ADOs may need to be placed farther back (behind the red ADO). This test is inconclusive, but based on the terrain it seems likely that large ADOs would need to be placed at least at the green ADO location (behind the Coke truck).

Creating small ADOs at the green ADO location when the external driver is located at the ramp position in 3 travelling at the same speed as the external driver should arrive at the merge slightly ahead of the driver (because the curved ramp is longer than the straight freeway).

'''NOTE:''' ADO size, ADO color, time of day and visibility settings affect ADO visibility.

====How to Position Objects Precisely using '''Place Object At..'''====

ISAT does not support true precision because it is not currently possible to 'dial in' a position as is typical in 3D modelling tools, but there is a way to approximate precision in cases where a consistent measurement is desired.

In the following example a number of roadpad triggers are placed relative to the location where a roadway enters an intersection. This is a discrete boundary within the simulation world as shown in ISAT.

There are two methods of placement possible:
# Measure the desired distance (CTRL+Shift+RMB, drag); take note of the coordinates updating in realtime and make a mental note of the desired location.
#Place an object (ADO or static object); use the Place Object At.. feature from the context menu when you RMB on a scenario object.
Using this method you can specify a distance - positive numbers move the object downstream/forward, negative numbers move the object upstream/backward.

'''Note:'''If the distance is significant and extends over an intersection, ISAT may produce unexpected and undesired results such as re-starting the measurement from the closest upstream intersection, thus placing the object where it was not intended.

In the following example, Place Object At.. is used to specify a point 50 feet upstream from the road/intersection border.

[[File:precision_placement_1.png|400px]]

A roadpad trigger has been positioned near the area of interest. Any existing roadpad is deleted from the trigger.

[[File:precision_placement_2.png|400px]]

An ADO is used as a marker object inserted temporarily into the scenario. Any convenient object may be used.

'''Note:''' large objects such as ADOs may be less precise than small objects such as the Traffic cone, but is generally easier to access in the ISAT interface unless you have created a script for cone objects.

[[File:precision_placement_3.png|400px]]

RMB on the ADO to access the Place Object At.. request dialog. Only numbers are valid entries.

[[File:precision_placement_4.png|400px]]

The desired distance is entered into the Place Object At.. request dialog. ISAT will then require you to select the object you wish to move using LMB.

[[File:precision_placement_5.png|400px]]

ISAT moves the selected object by the distance you specified.

[[File:precision_placement_6.png|400px]]

Use the ADO CG (model center) to place the start of the road pad.

[[File:precise_placement_7.png|400px]]

Remove the ADO marker and save your scenario.

==Scenario Testing and Debugging==
The primary way to test and debug scenarios is using ISAT rehearsal mode.

'''NOTE:''' the external driver during rehearsal is a simulation. You have limited control over the simulated ownship:
#change speed
#change lane

ISAT has two rehearsal dialogs:
#abbreviated (standard) dialog
#advanced (extended dialog)

===How to change to the advanced rehearsal dialog===
Often it is necessary to control the ownship during rehearsal. The ownship controls are located in the advanced (extended) rehearsal dialog.

ISAT will show the Advanced dialog the first time rehearsal mode is activated. All additional activations show the abbreviated dialog.

TBC abbreviated dialog

To use the Advanced dialog, LMB the Advanced button.

TBC Advanced dialog

===How to change ownship speed during rehearsal mode===
After entering rehearsal mode:
#click the Play icon (start the rehearsal)
#pause.
#adjust ownship speed
#toggle pause off (resume rehearsal)

===How to make ownship lane change during rehearsal mode===
After entering rehearsal mode:
#click the Play icon (start the rehearsal)
#click the desired Lane Change (left or right)

===How to Use Audio in your Scenario===
Scenarios play audio sounds and messages through a write to cell action: '''SCC_Audio_Trigger'''

Use of audio in a scenario typically requires both a write to cell and a 'clear action' that writes a zero (0) to SCC_Audio_Trigger in order to 'clear the channel'. The 'clear' action can happen before or after playing a sound; choose one method and be consistent in your scenario authoring.

Failure to 'clear the channel' or '''not''' writing a value of zero can result in no audio being played for subsequent write to cell SCC_Audio_Trigger actions.

The following shows how this looks in scenario when executed from a roadpad trigger (RPT):

[[File:audio_scn_A.png|400px]]

The above diagram is shown below in text format:

HCSM RoadPadTrigger
GroupName "WindGust_Audio"
ByTypeSet "ExternalDriver"
NthFromStart 0
NthFromEnd 0
VehicleAhead 0
VehicleBehind 0
LongComment "This is a wind gust event"
ShortComment " "
ActvDel 0.0000000E+00
CrRad 0.0000000E+00
Debounce 0.0000000E+00
FireDelFrames 0
Lifetime 0.0000000E+00
Name "RPT_WG_6"
OneShot 1
Priority 0
SeqAct 1
Position 6.7165800E+04 6.0419215E+03 0.0000000E+00
DrawPosition 6.7165800E+04 6.0419215E+03 1.1308095E-317
Path "R:r3_62700_7920:0[3033.04:3245.46]"
HCSM LogData
Comment "LS1=8"
Delay 0.0000000E+00
InstigatorSet 0
Stream 1
StreamVal 8.0000000E+00
&&&&End&&&&
HCSM WriteCell
Comment "Play_Audio"
Delay 2.0000000E+00
InstigatorSet 0
CellName "SCC_Audio_Trigger"
CellData "63000"
CellType 2
CellVar 0
&&&&End&&&&
HCSM WriteCell
Comment "clear_audio"
Delay 0.0000000E+00
InstigatorSet 0
CellName "SCC_Audio_Trigger"
CellData "0"
CellType 2
CellVar 0
&&&&End&&&&
&&&&End&&&&

===How to Add Custom Audio Instructions to miniSim===

''' Please note: Custom audio 'instructions' for a scenario should be added to the instructions.txt file.'''

These are sounds that are played in scenario, typically as directions for the minSim driver.

Adding custom audio files requires the following procedure:

1 Exit miniSim - changes to the miniSim configuration should happen only when miniSim is not running.

2 Copy the audio .wav file to:
:C:\NadsMiniSim_x.x\data\sound\DefaultCabSound\Instructs

:Edit the file instructions.txt in that same folder.

3 Add an entry to instructions.txt to register your audio file in accordance with the following layout using the existing entries as a template:

:Unique_ID Filename Normalized_Volume

:Unique_ID is whatever unique number you assign to your file.

:Filename is the name of your .WAV file.

:Normalized_Volume is the volume your audio file should play, where 0.00 is silence and 1.00 is maximum volume.

'''NOTE: Remove all spaces in your audio filename.''' If needed, use the underscore character instead of spaces.

===Troubleshooting Custom Audio Additions===
After installing new .wav files and adding them into the audio configuration file '''instructions.txt''', if the audio file does not play:
*Check the Audio Engine window while miniSim is still running. The Audio Engine will display file errors,.
*If Audio Engine does not display a message similar to: Audio Engine loaded normally, scroll through the window messages and look for any .wav or load error messages.

==Re-use of Scenario Elements==
Scenario authoring can be an intensive undertaking. It makes sense therefore to leverage your development efforts by re-using scenario elements where possible.

ISAT provides a number of ways to re-use scenario elements:
# copy/paste
# external references
<span style="color:#ac6600"># exporting elements as '''groups'''</span>
# isc scripts

Each of these methods have their strengths and weaknesses.

===copy/paste===
The simplest method to re-use scenario elements among different scenario files is copy/paste. This is possible for most scenario elements* even if the source and destination roadmap/BLIs are radically different.

[[File:copy_paste.png|400px]]

It is also possible to copy an ISAT element from one scenario to another as '''TEXT''' by selecting the element and using the windows copy shortcut CTRL-C, then open a text file and paste it using the windows paste shortcut CTRL-V.

'''NOTE:''' Traffic sources are '''not''' portable using copy/paste.

'''NOTE:''' Not all elements can be copy/pasted. Elements created from a Create Element action cannot be copied - it is necessary to select the parent element and copy that instead.

[[File:copy_paste2.png|400px]]

In the above diagram, elements at '''B''' and '''C''' cannot be copied/pasted because they have been created by element '''A'''. It is necessary to copy the element at '''A''' instead. If only the elements at B are needed, the best method will be to copy/paste as Text.

'''NOTE: ISAT will not copy elements containing road coordinates (elements with a path) to a scenario that does not share the same BLI as the source (copy from) scenario.'''

A partial solution to such cases is to remove the path first, copy the element, paste into the destination scenario, then re-create the path manually.

===External Reference===
An external reference scenario is intended to be re-used by multiple 'parent' scenarios. The effort of authoring objects is thus leverages across multiple files, without needing to re-create the same elements more than once.

[[File:re_use_xref_1.png|400px]]

Common uses of external references include traffic, traffic signal operation, traffic sign appearance or other environment features which have multiple appearances (billboards, some tile related scenery, etc).

NOTE: Multiple external references are possible; but because objects are categorized by group, it is not entirely necessary.

For example, one external reference file contains traffic, another contains signs. These two external reference scenarios could be combined into one file.

[[File:xref_overview2.png|400px]]

NOTE: Each group defined must be unique across all files: parent and external reference files.

In order to use an element in an external reference scenario, it is necessary to define and assign a group to all elements that you wish to control from the parent scenario.
At this time there is no visual hint in ISAT to indicate if a group has been assigned to an element or not - each element has to be confirmed independently.

However, a properly authored external reference element cannot be edited within the parent scenario (after you have done Add Ref. to use the external reference file).

An alternative is to insert groups using a text editor with macro capability, or to use a program or external script to make the necessary changes.

'''NOTE:''' If the external reference file is for object contained in the parent scenario (for example, an external reference file containing traffic signals with a group defined) it is still necessary for that group to be defined in the parent file.

With traffic signals, ISAT requires ONE explicit group reference, which will be contained in the HCSM TrafficLightManager block as shown below. If you require the use of traffic signals in an external reference, the recommended way to do this is through ISAT because then it manages the group assignment for you.

==== HCSM TrafficLightManager scenario block ====

HCSM TrafficLightManager
HCSM CLG
IntrsctnName "I1_40260_4620"
Duration 2.0000000E+01 3.0000000E+00 1.0000000E+00 2.0000000E+01 3.0000000E+00 1.0000000E+00
GroupName "TrafficSignals"
LightName "s_signal_r1_LTRN_40260_4620_270"
LightName "s_signal_r1_RTRN_40260_4620_270"
LightName "s_signal_r2_LTRN_40260_4620_270"
LightName "s_signal_r2_STRT_40260_4620_270"
LightName "s_signal_r3_STRT_40260_4620_270"
LightName "s_signal_r3_NORM_40260_4620_270"
Pattern "FLTY" "R" "R" "R" "R" "R" ""
Pattern "RTG" "R" "R" "R" "R" "R" ""
Pattern "LTR" "LTR" "LTR" "FLTY" "FLTY" "LTR" ""
Pattern "SR" "SR" "SR" "SG" "SY" "SR" ""
Pattern "SR" "SR" "SR" "SG" "SY" "SR" ""
Pattern "R" "R" "R" "G" "Y" "R" ""
&&&&End&&&&
&&&&End&&&&

'''NOTE:''' At this time there is a known issue using the write cell '''SCC_Audio_Trigger''' action in external references. Although the trigger containing this action can be assigned a group and used as an external reference, audio does not play.

<span style="color:#ac6600">'''Because ISAT updates static object positions (elevation) to the terrain (roadway) when the scenario file is saved, the best way to use a custom elevation is to put such objects into an external reference file in order to isolate those objects from normal scenario editing.''' </span>

====Define a Group====
<span style="color:#ac6600">'''NOTE:''' ISAT 1.8.5 and 1.8.6 currently do not work properly with group files. These versions will not import objects within a group file. There is a workaround which involves the following process, but instead of reading the saved group file into a scenario the workaround requires editing the scenario as text and inserting the objects within the group file into the scenario.</span>

RMB on the element and choose from the context menu: Group >> New Group (if this is a new group) or Group >> (choose an already defined group).

'''NOTE:''' The first time you create a group for an object, ISAT will automatically assign the group to that object.

After defining and assigning groups to the scenario elements needed, save the scenario file then close it.

Open or create the parent scenario file and use the Add Ref. button at the bottom of the ISAT window to select your external reference scenario. After you choose a file ISAT will present you with the groups found in that scenario. Choose the groups you with to include and click the 'Okay' button. Click the Add Ref. OK button to complete the process.

Currently import group file operations are not working, but it is possible to insert the group file content (all HCSM StaticObjects) into a scenario manually by using a text editor to copy text from the group file and paste that into a scenario file into the HCSM Static Object section of the scenario file.

[[File:group_text.jpg|400px]]

'''NOTE:''' ISAT does not enforce logic on your external reference authoring. If you add references to scenarios that do not share the same roadmap/BLI as the parent scenario, it is likely that elements will be placed at the origin (in cases where the external reference roadmap contains roadways not found in the parent) if it even loads.

===Exporting ISAT Elements as Groups===
Transferring ISAT elements among scenarios can be accomplished using groups. As with external reference scenarios, one or more groups must be defined and then assigned to one or more elements.

After defining and assigning groups select the group for export using the Group select drop-down located at the lower left corner of ISAT. Choose a group to export and then click the 'Save Group' button. Save the file.

TBC insert graphic sequence diagram here

'''NOTE:''' If you cannot locate the group file in the folder specified, check the ISAT install\data folder. This is typically:

C:\NADS\ISAT\data

===Group File Contents===
The group file is a text file and can be opened or edited in a text editor.

The following is a group file containing one ADO. Note the GroupName line near the bottom:

Header
LriFile "_dev.bli"
LongComment "this is a test group export"
ShortComment "this comment was left empty"
&&&&End&&&&
HCSM Ado
RunMode "eREMOTE_CONTROL"
RandomSol 0
Name "Ado1"
DynModel "Non Linear"
LogFile ""
LatOffsType 0
CreateRelLatInFeet 0
CreateRelOffsLonUsingExpr 0
CreateRelOffsLonExprStr ""
AutoControlBreakLights 0
AutoControlHeadLights 0
UseReaDel 1
StdToAccType 0
StdToDecType 0
StdToDecVal1 9.0000000E-001
StpToAccType 0
DecToAccType 0
FollowTimeMin 1.0000000E+000
FollowTimeMax 2.0000000E+000
EmergDecClip -1.1000000E+001
Accel2Catch 0
NormVel2Kp 7.0000000E-001
PathSearchDepth 2
LcvFall 1.5000000E+000 2.0000000E+000
LcvFreq 3.0000000E-002 5.0000000E-002
LcvRAmpl 1.0000000E-001 5.0000000E-001
VelCtrlInitMatchOvVel 0
VelCtrlFollowSpeedLimit 0
VelCtrlDistType 0
MaxLatOffset 9.0000000E+000
LongComment " "
ShortComment " "
SolName "Audi"
RoadPos "r1_1320_44220:2:32414.44:0.00"
GroupName "TEST_Group"
&&&&End&&&&
HCSM StaticObjManager
&&&&End&&&&
HCSM DriverMirror
&&&&End&&&&
HCSM IntersectionManager
&&&&End&&&&

===ISC Scripts===
Scripts are an efficient way to automate repetitive and/or complex tasks.

ISAT uses a custom language (ISC) to automate placement and manipulation of scenario objects. Combined with simple direction commands and the capability to navigate a road network, ISC scripts can ask the scenario author for input and prompt for selecting objects.

ISAT installs with some ISC script files. If your version of ISAT contains a data\isc
folder, then your version of ISAT is capable of running scripts. You can create
additional scripts as needed. All scripts located in the data\isc folder will load in ISAT
when ISAT is launched.

You can use these scripts for reference in creating your own custom scripts.

New scripts created during an existing ISAT session will not appear until ISAT is re-
launched.
Scripts that have been edited will not update until ISAT is re-launched.

Unless otherwise indicated, scripts are case-sensitive.

'''NOTE:''' Please do not edit the existing scripts!

Make a copy of any existing script before you make changes. In the event your modified script does not work, you can look at the original file for reference.

ISC scripts are located on the ISAT Elements widget. Custom isc scripts are located after the 'Events' separator.

Using an ISC script involves LMB + dragging the desired script onto the workspace. In some cases the script will ask for inputs.

ISC can be also used to create an entire event, thus ensuring that all events created will be entirely identical in terms of settings and locations for all created elements.

ISC scripts are text files located within the ISAT installation data folder. Only the custom ISC scripts are located in this folder. This is typically:

C:\Nads\Isat\data\isc

====Icon Files====
Script icon files are 8-bit windows icon files (file.ico). GIMP is capable of exporting valid ico files. To create an ico file, scale it to 32x32 pixels. Export the file as .ico to the isat\data\isc folder.

In order for a script to use an icon file, both files must exist in the isat\data\isc folder.

====ISC Script Examples====
This section contains example scripts with notes.

'''Rotate sign'''

.Name SetSignRotation
.Icon SignRot.ico
Static sign
Select(sign,"Please Select a Sign")
sign.SetAngle(Anchor)
.End

'''Place Multiple Static Objects (TrafCone)'''
The following script asks the scenario author for number of cones to generate, position and offset values and then generates the objects.

A breakdown of the script follows the code block below.

.Name Cones
.Icon cone.ico

Block coneBlock %%%
HCSM StaticObject
IsNewObj 1
Name "Cone_xxx"
SolName "TrafCone"
Option 0
Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
&&&&End&&&&
%%%
Static cone;

Value dist1
Value numberOfCones
Value distance
Value variablePart
Value randDistance
Value speed
Value Count
Value LatOffset

Block tempBlock
tempBlock = coneBlock
Count = 1
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

Ask(numberOfCones,"How many cones?" )
Ask(dist1,"Distance between cones?" )
Ask(LatOffset,"How much offset?" )

Position posRp
Position tempPos
posRp = Anchor
numberOfCones = numberOfCones

Repeat numberOfCones
posRp.GoForward(dist1)
# test comment
tempPos = posRp;
tempPos.SetOffset(LatOffset)
cone.RoadPos = tempPos
cone.Clone
Count = Count + 1
tempBlock = coneBlock
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

End
.End

====Script Breakdown cones.isc====

This section contains a description of the elements used in the script. The script segment is followed by a brief text description.

This script places a number of object copies (TrafCone) using information provided by a user.

.Name Cones
.Icon cone.ico

The first line contains a keyword '''.Name''' followed by the name of the script. This is the name that ISAT will use on the Isat Elements widget for the script. Note the script name does not have to be the same, but it is good computing practice.

The second line begins with the keyword '''.Icon''' followed by a file name. This file must exist in the ISAT\data\isc folder (accompanying the script file). This is the icon ISAT will use for the script.

Block coneBlock %%%
HCSM StaticObject
IsNewObj 1
Name "Cone_xxx"
SolName "TrafCone"
Option 0
Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
&&&&End&&&&
%%%

This is the data section of the script, which is defined using the keyword '''Block'''. A block name follows the keyword, and the data start is defined with '''%%%'''.

The HCSM StaticObject section has been copied from a scenario. In this case, a static object was placed into the workspace and then copied into a text file.

Name "Cone_xxx"
Note: the object name contains a marker that can be used to programmatically name instances of the object:

SolName "TrafCone"
This line begins with the keyword '''SolName''' followed by the name of the object as it is defined in the sol2.txt file.

Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
The Position of the static object will update when the script activates and instanced objects are placed in the workspace.

Static cone;
This line begins with the keyword '''Static''' followed by a variable name.

Value dist1
Value numberOfCones
Value distance
Value variablePart
Value randDistance
Value speed
Value Count
Value LatOffset

This section defines variables with the keyword '''Value''' followed by variable names. Using descriptive names is better than generic names. From the variable list it already seems clear what the programmer cares about: number of cones and distances.

Block tempBlock
tempBlock = coneBlock

This section defines a block using the keyword '''Block''' followed by the variable name.

The next statement replicates coneBlock into tempBlock.

Count = 1
Initialize the value of the variable Count to 1.

tempBlock.Replace('xxx',Count)
The built-in '''Replace''' function changes the string 'xxx' to the value of the variable Count.

cone.SetBlock(tempBlock)
This statement creates a block using the function '''SetBlock''' called cone, and copies the contents of tempBlock into it.

Ask(numberOfCones,"How many cones?" )
Ask(dist1,"Distance between cones?" )
Ask(LatOffset,"How much offset?" )

This section asks the user for input and puts that information into variables:
*Number of cones
*Distance between cones (dist1)
*Lateral offset (calculated from lane center)

Position posRp
Position tempPos
posRp = Anchor
numberOfCones = numberOfCones

This section contains position variables and assigns the value of numberOfCones.

Repeat numberOfCones
posRp.GoForward(dist1)
# test comment
tempPos = posRp;
tempPos.SetOffset(LatOffset)
cone.RoadPos = tempPos
cone.Clone
Count = Count + 1
tempBlock = coneBlock
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

This section is where the work happens. Reading from the top, this section is contained within a loop defined by the keyword '''Repeat'''. The number of times to repeat follows in a variable numberOfCones.

'''posRP.GoForward()''' is a built-in function to take the current position and shifts it forward by the amount specified in the dist1 variable.

#test comment
This is a comment defined by starting the line with the comment keyword '''#'''

tempPos = posRp;

Assign the value of the variable tempPos to the value currently in '''posRp'''

tempPos.SetOffset(LatOffset)

Another built-in function or attribute to the position element which defines a lateral offset (distance from the lane center). This statement places the value of a variable LatOffset into the offset element of the tempPos variable, using the operand '''SetOffset'''.

cone.RoadPos = tempPos

This statement sets the road position variable for cone to the value in the variable tempPos.

cone.Clone

Duplicate the block cone using the operand '''Clone'''

Count = Count + 1
Set the value of the variable Count to the value of Count plus one. This statement increments the value of Count for each loop processed.

tempBlock = coneBlock

Create a new block tempBlock by setting it to the content of coneBlock.

tempBlock.Replace('xxx',Count)

Use a built-in function to '''Replace''' the string 'xxx' with the value of the Count variable

cone.SetBlock(tempBlock)

Use the built-in function '''SetBlock''' to place the modified tempBlock (modified by the string replacement command earlier) into the cone block.

End
.End

The last two lines terminate the loop and the script, respectively.

====How to Create an ISC Script====
The simplest way to create an ISC script is to find an existing script that does something similar to your desired behavior and edit it.

=miniSim Simulation Data=
MiniSim runs on shared memory:
*miniSim is a collection of programs
*shared memory is a commonly accessed 'blackboard' list: a Cell and a Cell Value
:The DAQ file is a snapshot of this 'blackboard' memory for every frame.

*Scenario can write to cells added by the scenario author
:-i.e., for custom hardware or tasks/events

'''NOTE:''' Custom cells must be present in the collect file (NadsMiniSimCollect.cec) '''prior to''' simulation in order for the custom cells to be present in the DAQ.

NOTE: The cell type defined in the collect file must be followed, or garbage values will be used

Use of a DAQ file implies that at some point, data reduction will be needed.
Data reduction: the process of distilling measures from the DAQ file, i.e.
*Event definition
*SDLP
*Average headway

==What is the Difference? Cell vs. Variable==
*A Cell is a pre-created “slot” in shared memory
:-Specified in the .CEC collect file,
:-Saved in the DAQ file,
:-Can be sent to custom programs;
:-Can create & use custom cells;
*A Variable is a name value internal to the scenario
:-NOT saved to the DAQ file,
:-Can use to track items in the scenario
:i.e., how long the driver has been exceeding the speed limit
:-Initialize conditions in the scenario.

=== Variables Save ===
Variables can be saved to disk as a single value text file (ie, multiple values over time are not supported) through the use of a '''Store Variable''' action:

[[File:2021-08-23_13h28_49.png|400px]]

The file is stored in the miniSim_x.x\bin.x64 folder.

'''NOTE:''' The name of the file is defined within the Store Variable action. '''Care must be taken to save variables to unique file names''' in the case of multiple scenarios running on miniSim at the same time (if they share common variables), as would be the case if triggers are copied from one scenario to another.

=== Variables Restore/Read ===
Variables can be read into the simulation through the use of a '''Load Variable''' action:

[[File:2021-08-23_13h32_39.png|400px]]

==Cell Types==
This is a partial list of cell types.

*CFS = control feel subsystem (steering wheel, pedals)
*CIS = control information subsystem (gear, turn signal, buttons, etc)
*TPR = terrain profiler for terrain queries
*VDS = vehicle dynamics for accelerations, position, engine speed, speed, etc.
*ACC = adaptive cruise control
*RCM = configuration management for setting variables that affect subsystem configuration (ACC enabled or disabled, for instance)
*SCC = scenario
*SOP = for one time initializations at the start of the simulation.

=='''Data Output Actions'''==

*Write to Cell Actions
:-Write the value of a variable or cell to a cell
:-Write to a custom cell
:-Cannot overwrite another systems output
'''NOTE:''' Although it is possible to write to a different system cell, that value will be over-written on the next frame. Thus it is effectively not feasible nor desirable to do.

'''<span style="color:red">Also Note: the limit for maximum number of write to cell actions that can be performed in one frame is 8.</span>'''

*Set Variable Action
:-Sets the value of a variable
:-Does not have to be created first
:-Not saved in the DAQ unless written to a valid cell
*Logstream
:-Log data action

===Data Output Methods===
Your data is the primary reason for simulation.

1. Default miniSim scenario measures
:- Immediately available

2. Alternate scenario measures (DAQ file)
:- Processed through data reduction

====Default miniSim Scenario Measures====
*Saved to a drive report.txt file
*Saved to the same Location as DAQ files;
:Scenarioname_timedatestamp_report.txt
•Measures calculated overall, and up to 20 Events during drive:
:Collision Count Lane Departure Count
:Maximum Speed Lane Departure Percentage
:Minimum Speed Speeding Count
:Average Speed Speeding Percentage
:Standard Deviation of Speed Average Headway
:Standard Deviation of Lane Position

====Default miniSim Scenario Measures Require Scenario Event Definition====
In order to capture meaningful data into the default miniSim measures, a scenario must be configured properly to define events.

Use the Write to Cell action to activate the default measures.

[[File:2021-07-02_11h02_44.png|400px]]

*At the start of scenario, set:
::SCC_EventStatus =0
::SCC_EventNumber = 0
*At the start of the first event, set:
::SCC_EventStatus = 1
::SCC_EventNumber = 1
*At the end of the first event, set:
::SCC_EventStatus = 0
*At the start of the second event, set:
::SCC_EventStatus = 1
::SCC_EventNumber = 2
*At the end of the second event, set:
::SCC_EventStatus = 0

Continue this pattern; at end of final event, set:
::SCC_EventStatus = 0

====Default miniSim Scenario Measures Sample Report====
The following is an example report for 4 events. Note the remaining events present in the report are all zeroes or -1.00.

[[File:default_measures_report.png|400px]]

===="Alternate" Scenario Event Definition aka Using Logtreams====
'''NOTE: This method is the more typical/standard method for defining events.'''

Defining an event is key to partitioning simulator data into useful sections. Processing these sections is the essence of '''data reduction.'''

These useful sections are partitioned using logstreams and are generally called '''Events''':
*A logstream is a data marker present in the DAQ file
:there are 10 logstreams
:use logstreams to indicate when things happen '''in the data:'''
:at the start of an event; i.e.,
::grab all data where logstream 1 = 100 (example value)
:during a sub-section of an event
:at the end of an event (typically clears to 0)

Logstreams help separate/filter data;
*SDLP is not useful during emergency maneuver events

Logstreams can be useful to debug events;
:marking in the data when triggers fire
:ensuring event counters work; these are typically sequential, so any logstream deviation identifies a problem

*How to define a Scenario Event:

Set logstream values at scenario event start
:during and at scenario event end, set or clear logstream values:
For example:
::logstream 1 for event ID
::logstream 2 for sequencing the event (during/within event)
::logstream 3 for restart number, etc.

*Requires data reduction to fully process drive data
*Does '''not''' support default measures
:unless those measures are used in parallel with the logstream method

*The use of logstreams allows a scenario author to encode event and environment information into the scenario and as a result, into the simulator data stream.

====Example Alternate Scenario Event====
This section contains an example of a scenario that uses logstream 1 to define an event and environmental context.

In the following example, logstream 1 (LS1) is used to:
#define the scenario start, which is also in this example the event start. NOTE: This is not typical.
#when the driver is 805f from the intersection halt line, set a value into LS1
#when the driver is 500f from the intersection halt line, set a '''new value''' into LS1 NOTE: This could also use a different LS than the one used to define your event, i.e., 1
#when the driver activates a roadpad trigger to reset a force velocity (FV) on a lead vehicle

[[File:event_def_LS.png|400px]]

In the following event definition, an expression trigger is used to set a logstream value and execute two additional actions pertaining to the event.

[[File:event_ET_LS3.png|400px]]

====How to Export Data from A DAQ file using ISAT====
ISAT can display and export DAQ data. NOTE: This is 'raw data', not previously processed. This method can be used to test scenarios, confirm or identify data issues.

TBC: example export here

=Terminology & Documentation=
This section contains terminology and references to related documentation.

'''Action''' - the basic scenario element; the basis for creating scenarios. Actions may be executed on scenario elements (dynamic or static), create or remove elements, or the environment (time of day, visibility) or the simulated cab instrument panel.

'''ADO''' - Autonomous Dynamic Object; self-controlling to a degree.

'''Cell''' - Data elements that are recorded to during a drive; some cells may be used by the scenario author. Custom cells may be added to miniSim.

'''Event''' - anything significant that happens during a drive where the driver condition or response is desired to be identified in the drive data. Can be isolated from general driving through default measures or logstreams.

'''ISAT''' - Interactive Scenario Authoring Toolkit; used to create scenario files for use on the NADS facility or miniSim simulators.

'''ISC''' - ISAT script file.

'''Scenario''' - The simulation experience during a drive; also known as a scenario file, which contains all instructions to the elements within a simulator drive.

'''SDLP''' - Standard deviation lane position

'''SOL''' - Scenario Object Library; objects that are available to ISAT during scenario authoring must be present within the sol2.txt or an auxiliary sol2 (sol2_aux.xxx.txt) file.

'''Trigger''' - A scenario element that contains actions to execute during simulation. All triggers share the same actions, but execution depends on the trigger type.

'''TTA''' - Time to arrival.

'''TTC''' - Time to collision.

=Reporting ISAT & Scenario Issues=
*How to report ISAT & scenario issues:

When reporting issues with scenarios it is helpful to provide as much information as possible.

This often includes scenarios (including any external reference files) and the .LRI file used by the scenarios, screenshots or video that demonstrate the issue being reported and relevant DAQ files. It can be very helpful to include coordinate information with the screenshot or video.

The .BLI file is created from the .LRI and is much larger than the LRI so it may be more convenient to send the LRI file. NADS staff can re-create the BLI file from the LRI.

Some graphics anomalies may be issues with the tile model and not a scenario or miniSim problem. These include:
#white block shapes in the environment
#gaps or missing geometry; i.e., holes
#improper lighting (dark features present during the day)

If these issues happen on a custom roadmap/database world, please include the TMT .mos file as well so NADS can re-construct your environment.

==How to contact the NADS miniSim team:==

email [mailto:miniSim-Support@uiowa.edu minisim support]

[mailto:andrew-veit@uiowa.edu Andrew Veit]
Director of NADS miniSim

[mailto:joseph-meidlinger@uiowa.edu Joseph Meidlinger]
Program Coordinator NADS miniSim

[mailto:oscar-hernandezmurcia@uiowa.edu Oscar Hernandez Murcia]
MiniSim Application Programmer/Analyst

[mailto:chris-schwarz@uiowa.edu Chris Schwarz]
Data Reduction & Vehicle Dynamics

[mailto:shawn-allen@uiowa.edu Shawn Allen]
TMT, Modelling & Support

==How to check what BLI file is used by a scenario==

#You can edit the scenario in a text editor; near the top of the file will be a line starting with '''LriFile''' followed by the name of the BLI file in double quotes.
#You can use '''grep''' to inventory single or multiple scenarios:
:grep bli <scenario file/s>
:A partial listing is shown in the example below. NOTE: The files shown will likely be different on your PC:
C:\NADS\Isat\data\training.demo_scn>grep bli *.scn
Demo_Expression_Lead_Vehicle_Variables.scn: LriFile "simple_rural.bli"
Demo_Expression_Trigger_to_Lead_Vehicle.scn: LriFile "simple_rural.bli"
Demo_HUDD.scn: LriFile "simple_rural.bli"
ISAT-Samples-Avoid.scn: LriFile "esc_dry_05.bli"
ISAT-Samples-Right-Incursion.scn: LriFile "esc_dry_05.bli"
ISAT-Samples-TrafficLightTest.scn: LriFile "simple_city1.bli"
ISAT-Samples-TrafficLightTestB.scn: LriFile "simple_city1.bli"
ISAT-Samples-YellowLightDilemmaB.scn: LriFile "simple_city1.bli"
KBW_TEST.scn: LriFile "simple_rural.bli"
KBW_TESTB.scn: LriFile "simple_rural.bli"
demo.createADO_and_trigger.scn: LriFile "simple_city1.bli"
demo.creation_radius1.scn: LriFile "simple_city2.bli"
demo_FV_sum_of_Sines.scn: LriFile "simple_city2.bli"
demo_LV_Decelerate.scn: LriFile "simple_city2.bli"
demo_LV_cut_in.scn: LriFile "esc_dry_05.bli"
demo_MG.scn: LriFile "simple_city2.bli"
demo_TM1.scn: LriFile "simple_city2.bli"
demo_TT_null.scn: LriFile "simple_city2.bli"
demo_actions_text.scn: LriFile "simple_city2.bli"
demo_alt_data_measures.scn: LriFile "simple_city2.bli"
demo_audio_virtual_object.scn: LriFile "esc_dry_05.bli"
demo_audio_virtual_object_simple_rural.scn: LriFile "simple_rural.bli"
demo_auto_cloud1.scn: LriFile "simple_city2.bli"
demo_coneISC1.scn: LriFile "simple_city2.bli"
demo_dddo.scn: LriFile "simple_city1.bli"
demo_dddo_B.scn: LriFile "simple_city1.bli"
demo_forXRef_traffic.scn: LriFile "simple_city1.bli"
demo_force_vel_01.scn: LriFile "simple_city1.bli"
demo_groupImport.scn: LriFile "simple_city2.bli"

==How to configure miniSim for screenshots to include coordinates==
You can enable coordinate display on miniSim by changing the focus to the main display. #Move the cursor until it is positioned in the main display area, then LMB. When successful the main display will appear to "blink".

Press the keyboard n key twice. This will cause coordinate information to display in the lower left corner of the main display.

[[File:miniSim_show_coords.png|400px]]

The n key is a toggle; to disable coordinates, press it twice (2x) again. '''NOTE:''' the cursor focus must be in the main display in order for this to work.

=Additional Resources=
[[:File:ISAT_Quick_Start.pdf|ISAT Quick Start Guide]]

[[ISAT_Demonstration_Scenarios|Demonstration Scenarios]]

[[:File:Create_Use_Custom_Cells.pdf|Create and Use Custom Cells on MiniSim]]

[[:File:Function_ReadCell_20180824.pdf|ReadCell function]]

[[:File:TrafficManager_Ch12.NADS.Internal_ISAT_UsersGuide.pdf|Traffic Manager]]

=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 [[ISAT_Reference_Manual_Table_of_Contents#ISAT_Reference_Manual|reference manual for ISAT can be found here.]]

File:Screenshot 2023-10-02 133413.png

2023-10-02T18:37:42Z

Shawn Allen: File uploaded with MsUpload

File uploaded with MsUpload

FAQ

2023-09-18T18:06:49Z

Shawn Allen: /* Q: How can I tell what surface the driver is driving over? add graphic for comparing scc_lane_deviation and scc_lane_spline_deviation */

<div class="toccolours mw-collapsible mw-collapsed">
== miniSim Documentation ==
All miniSim simulators ship with a documentation folder located on the desktop. You can find miniSim and additional documentation within this folder.

== miniSim Hardware ==

=== Desktop and Viewport Settings ===
<div class="mw-collapsible-content">

Detailed information about the PC display layout and the miniSim viewport and channel configuration settings is available here:

[[:File:miniSim-Desktop_and_Viewport-Settings-v3_113022.pdf]]

[[#top|TOP]]
</div>
</div>

=== Q: My miniSim displays have changed. What happened, and how can I fix it? ===
<div class="mw-collapsible-content">

Windows has shown a tendency to re-enumerate the displays from time to time. The result is that the miniSim display layout/configuration becomes incorrect.

The relationship between the display layout and the viewport display settings in the miniSim Channel Configuration File (.ccf) no longer match.

To correct, check the following in this order:
# Displays are arranged from left to right: Matrox/Mosaic, Instrument Panel, Operator.(use mouse or arrow keys)
# The Matrox/Mosaic display must be designated as the ‘main’ or ‘primary’ in Windows. The task bar may move to this display when this is set, so drag the task bar and icons to the operator display
# Do not use the Matrox PowerDesk program to adjust the default locations for pop-up and application windows. This will cause many, many problems.
# The top edges of the display icons are aligned (use mouse or arrow keys)
# Reboot to make sure the configuration is stable.
# Check video and USB connections. If they are loose, it may cause windows to re number the displays, which can make things move around unpredictably.
# Open the correct Channel Configuration File (.ccf) in the \bin.x64 directory.

'''Note:''' there are several .ccf files in every system, and the ‘correct’ one is defined by the system settings in the ‘go.cmd’ file used to start miniSim.

See next section. The third number in the Channel header(s) should be equal to the number of the main display as reported by Windows in ‘Display Settings’ minus 1. Only 0, 1, 2 are generally valid for standard miniSim configurations (2 Channel, 3 displays).

:Channel 0 0 2 (Shear x2) (Twist x3) (Extends x4)
:0.000000 0.000000
:0.000000 0.000000 0.000000
:0.000000 0.000000 1.000000 1.000000
:6
:.
:.
:.
:Channel 1 0 2 (Shear x2) (Twist x3) (Extends x4)
:0.000000 0.000000
:0.000000 0.000000 0.000000
:1.000000 0.000000 2.000000 1.000000
:0 IP

[[#top|TOP]]
</div>

=== Q: What is the right Channel Configuration File for my miniSim? ===
<div class="mw-collapsible-content">

A. to determine the correct ccf file, examine the command file that launches miniSim.

The minisim is launched by running the correct go.cmd file in the '''NadsMiniSim_x.x.x\bin.x64''' folder.

Typically, there have been shortcuts created on the miniSim desktop that are used to run the appropriate ‘go’ scripts. There are often several go-scripts, this is usually to provide a way to launch the miniSim with or without various options (Video Capture, Advanced Automation, etc).

If you right-click on the shortcut icon and choose ‘edit’ you can edit the go.cmd script. A typical one looks like this:

:set MININADSCOMMMODE=PSEXEC
:set DYNA=car
:set NUMCHN='''2'''
:set INSTRUMENTS='''on'''
:set FORMAT='''wide'''
:set INSETVIEW=off
:set SIDEMIRRORS='''on'''
:set MININADSDAQ='''on'''

Based on these settings, the miniSim will read the following channel configuration file (.ccf) and use its contents for setting up the rendering channels and viewports. In this case, the miniSim will open this file:
'''\bin.x64\mininads_2ch.wide.sidemirrors.inst.ccf'''

This is the correct file to edit for this configuration. Remember to exit miniSim before making edits to the .ccf file.
'''If you make a change and see no effect, you may be editing the wrong file!'''

When the miniSim runs, it copies the .ccf file that pertains to the options selected in the go.cmd, and copies it to '''mininads_1ch.ccf''', which is the one that is loaded when miniSim is launched.

This means that the '''mininads_1ch.ccf''' has the same ‘Last Modified Date’ as the file you want to edit.

If you list the contents of the \bin.X64 folder by date, you will see something like this:

[[File:2022-11-30_15h03_56.png|400px]]

In this case, you will see that the '''mininads_2ch.wide.sidemirrors.inst.ccf''' is the file you want to edit, as it has the same last modified date as '''mininads_1ch.ccf'''.

For a desktop layout like this from Windows in ‘Display Settings’

[[File:2022-11-30_15h05_10.png|400px]]

This is a '''Two-Channel''' system, meaning that the front three displays on the Matrox/Mosaic are Channel 0, and the Instrument Panel display is Channel 1.

[[#top|TOP]]
</div>

=== Q: Where do I find data relating to the brake pedal force/position? ===
<div class="mw-collapsible-content">
A: The data you are seeking is represented by the '''CFS_Brake_Pedal_Force''' variable, which can be viewed either with ISAT or with Matlab during data reduction. The value ranges from 0 lbs. to 180 lbs., where 0 indicates no force (no pedal travel) and 180 indicates 180 pounds of force (full pedal travel).

If you see a variable named '''CFS_Brake_Pedal_Position''' you may ignore this as it is not currently being used.

[[#top|TOP]]
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: How can I adjust the brake pedal response? ===
<div class="mw-collapsible-content">

Information to adjust the brake pedal response is detailed in this document: [[:File:Adjust_Brake_Response_11302022.pdf]]

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: The tactile transducer, mounted under the cab, suddenly does not respond when the miniSim is running. ===
<div class="mw-collapsible-content">

Check the following:

1. Verify these connections first:
: a. The main stereo speakers should be plugged into the green audio port on the back of the PC using a ⅛" mini-jack.
: b. The Dayton D-30 amplifier should be plugged into the orange port on the back of the PC using a ⅛" mini-jack.
: c. The tactile transducer should be connected to the Dayton D-30 amplifier using the included speaker wire.

2. Note that the amplifier controls the volume of the tactile transducer and therefore must be plugged into a power source. If the amplifier is not plugged into power, this could be the reason the tactile transducer is not working.

3. Check the volume level of the amplifier. If it is set too low, the tactile transducer may '''appear''' to not be working. We suggest a minimum amplifier volume setting of 25% of full volume. A volume setting which is too high will be experienced as an unpleasant vibration and low-end rumble that does not resemble a real car.

4. Launch the Realtek audio manager from the Task Bar and select 5.1 audio. Then, disable the center and rear channels, leaving the front left and right speakers, and the subwoofer enabled.

5. Use the Realtek audio manager to test each of the speakers individually by clicking on each speaker icon. As you select a speaker, the speaker will sound.

Some motherboards have the sub/center channels switched. In this case, a ⅛" mini-jack to stereo RCA cable can be used.

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

== miniSim Operation ==
=== Q: Auto-start miniSim drive===
The miniSim simulator can be configured to start a drive automatically or not, depending on your project requirements.

This involves a '''''system level configuration change'''''. To run two projects simultaneously you will need to create a unique startup sequence for each project in order to use the correct configuration file.

Setting auto-start involves a setting in the hardware.xml file in use; note there are different configuration files present on all miniSim simulators within this folder:

miniSim_x.x\bin.x64\config

Please exit miniSim before editing any .xml file. You may want to backup these files prior to editing.

'''Enable auto-start'''

Change the string

<Sink device="SimulatorInterface" port="CIS_Auto_Ignition" ID="0" />

to

<Sink device="SimulatorInterface" port="CIS_Auto_Ignition" ID="1" />

To disable auto-start, set the value to 0.

=== Q: miniSim is not responding. ===
<div class="mw-collapsible-content">A: At times you may find that your miniSim PC or miniSim software has become unresponsive. We define appropriate steps for correcting unresponsive behavior on a miniSim PC under the following conditions:

* '''miniSim Software is Running but Will Not Load a Drive Scenario:'''
# Assuming the mouse is functioning, simply close and then restart the miniSim program.
# If the mouse is not functioning, use the keyboard to close and restart the miniSim program i.e. press Alt+Tab to select the minSim program and press Esc to close.
# This step will fix this unresponsive behavior most of the time.
* '''A miniSim Drive Has Been Selected but Will Not Start:'''
: Assuming the mouse is functioning, click on the Settings tab and verify all lines are green (ready mode). If one or more lines are red, simply wait for all to become green. If still not green after about 90 seconds, close and restart the miniSim software normally. This step will fix this unresponsive behavior most of the time.
* '''miniSim Software Stops Running:'''
# Assuming the mouse is functioning, simply close and then restart the miniSim program.
# If the mouse is not functioning, use the keyboard to close and restart miniSim program i.e. press Alt+Tab to select the minSim program and press Esc to close.
# If the miniSim software will not close, press Ctrl+Alt+Delete and open Task Manager. Within Task Manager, select the SimopServer program and close it. Restart miniSim.
# This process generally will recover miniSim from nearly any unresponsive state.
* '''miniSim PC Shuts Down Unexpectedly:'''
# Check for severe storms and possible power outages in your neighborhood.
# If you see smoke or smell something burning near the miniSim PC, carefully unplug the PC from the electrical outlet and fetch your fire extinguisher just in case. When immediate danger passes, consult a local hardware expert to examine your PC for possible electrical shorts, overheating or failure of critical systems such as motherboard, hard drive and etc. Contact NADS miniSim in the event hardware components need to be replaced. See contact information below.
* '''The miniSim PC Will Not Boot:'''
# On rare occasions your miniSim PC may not boot to Windows. It may halt the boot process just prior to launching Windows. If your miniSim PC has stopped the boot process before a Windows launch, it is okay to touch the reset button on the PC (the small button next to the power button). If your miniSim PC does not have a reset button, touch the power button lightly one time. There may be a slight delay but then your miniSim PC will restart the boot process. This is the safest way to handle an uncompleted boot sequence.
# In most cases if the system stops prematurely during the boot process, for example, while displaying the motherboard splash screen (typically AMI) or the blinking cursor just prior to the Windows logo, the PC is having trouble enumerating USB devices before loading windows.
# If the system hangs up during the second boot attempt, please check the USB connections. In particular, be sure the mouse and keyboard (typically connected through a USB hub) are in their designated USB ports i.e. nearest to the round PS2 style port (top for tower systems or far left for rackmount systems). These are typically USB 2.0 ports and are checked first during the USB enumeration process at boot. It is critical that the mouse/keyboard connections are made in this way.
# If the mouse/keyboard are connected to the correct USB ports, and your miniSim PC still does not boot, disconnect all USB devices (except mouse and keyboard) and systematically reconnect them one at a time in between reboots. This process will eventually and effectively isolate which USB device may be causing the boot problem. To resolve this conflict, simply plug the suspected USB device into a different USB port. Moving these devices to a different port typically resolves this problem permanently. It often (unfortunately) requires some experimentation (read trial and error) but once you find the right combination of USB devices and ports, this problem goes away.

Also, there are certain steps you should not take to try and resolve an unresponsive miniSim PC condition. Some tactics could actually make the problem worse e.g. damage hard drives, corrupt the operating system, scramble your data. Here are some activities you should not engage in to try and resolve a hanging miniSim PC:

'''Troubleshooting steps you should NOT try:'''
* Do not press and hold the power button on the PC while miniSim is running.
* Do not unplug the PC from electrical outlet while miniSim is running.
* Do not unplug mouse, monitors or keyboard while miniSim is running.

'''Acceptable methods for shutting down an unresponsive PC:'''
* Close all running programs, press the Windows key and select Shut Down.
* Or, press Ctrl+Alt+Delete and select Shut Down.
* Or, touch the reset button or lightly touch the power button one time.

====Making Changes to the BIOS====

If your miniSim PC is unresponsive in ways that are not covered above, you may need to make certain changes to the BIOS of your miniSim PC. Altering BIOS settings on a PC is delicate work and requires more than a passing knowledge of computers. Instructions for modifying the BIOS follows but if you would like the assistance of a NADS professional, don’t hesitate to ask.

The BIOS change involves enabling Fast Boot. Fast Boot will disable your USB devices at boot-up thus preventing USB port conflicts and effectively preventing endless USB enumeration and rebooting.

To enter BIOS setup, repeatedly press the Delete key while the computer is powering up. Ultimately you will see a screen that looks like the screen shot below. (This assumes your miniSim PC was built in 2015 or later.)

[[File:Initial BIOS Screen.jpg|400px|thumb|center|Initial BIOS Screen]]

Navigate to the '''Advanced tab''' using the arrow keys on your keyboard and select it.

[[File:Advanced.jpg|400px|thumb|center|Advanced Tab Selected]]

Scroll down and select '''USB Configuration.'''

[[File:USB Configuration.jpg|400px|thumb|center|USB Configuration Selected]]

Make sure your BIOS settings match the settings on the right half of the screen as shown below:

[[File:BIOS Settings.jpg|400px|thumb|center]]

Set '''Fast Boot''' to '''Fast.'''

[[File:Fast Boot Selected.jpg|400px|thumb|center|Fast Boot set to Fast]]

Select '''Save Changes and Exit'''

[[File:Save Changes and Exit.jpg|400px|thumb|center|Save Changes and Exit selected]]

'''NOTE: these settings will disable your USB devices during boot. This will eliminate the USB enumeration problem but will also prevent you from accessing BIOS settings again without a PS2 style keyboard. Feel free to contact NADS for additional information on this condition.'''

Bear in mind your BIOS screens may look different than the screenshots above but your objective remains the same, enable Fast Boot.

Please don’t hesitate to contact us if you wish help with these settings. '''Word of Caution:''' make these changes during normal business hours. If you get stuck in BIOS settings on a weekend or middle of the night, we may not be available to help you.

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

= miniSim Software =

=== Simulation data ===
Your data is the primary reason for simulation and is available from the miniSim in two ways:

# Default measures - these are pre-defined measures available for up to 20 events.
# Logstreams - the entire range of variables is available for as many events as required.

These two methods require setting up a scenario to create [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#What_is_a_Scenario_Event.3F '''events'''] that happen during simulation and are defined in a way to allow extracting them from the drive.

Default measures are available immediately after the drive in the form of a text document, located in the DAQ folder on miniSim.

Logstreams are flags embedded in the drive data and requires data reduction to make the information available after the drive.

More information on these methods is available [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#Data_Output_Methods here:]

= ISAT/Scenario =

=== New to ISAT? ===
A quick start overview is available [https://www.nads-sc.uiowa.edu/minisim/wiki/images/6/68/ISAT_Quick_Start.pdf '''here.''']

The ISAT User Guide is available [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents '''here.''']

A scenario/ISAT troubleshooting guide is available [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_Troubleshooting_Guide '''here.''']

=== Data Logging: miniSim Default Measures ===
There are a fixed number of measures available and a limit of 20 events.

More information including which measures are available and how to structure your scenario to support default measures is available [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#Default_miniSim_Scenario_Measures here.]

=== Q: How do we make an ADO or DDO go backward? ===
<div class="mw-collapsible-content">
A: Only DDOs can back up. To accomplish this, start by placing a DDO where desired.

Next, create a path for the DDO; right-click on it and select Extend Path from the pop-up menu.

Then, lay out a path (path nodes are a sequence of yellow dots) to indicate the desired route of travel.

Finally, right-click on each node and select Rotate to set the direction that you wish the DDO to face. The direction at each node can be set independently.

In order to make it appear as though the car is moving backwards, the arrows should point against the direction of travel. To avoid erratic movement, you should add sufficient nodes to create a smooth path. This will result in smoother and more realistic movement of the DDO, especially if you are changing direction rapidly.

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: How do I play a sound in my scenario? ===
<div class="mw-collapsible-content">

See [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#How_to_Use_Audio_in_your_Scenario Using Audio in a Scenario]

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: How do I add a trigger to my scenario? ===
<div class="mw-collapsible-content">

Triggers can be added to a scenario in ISAT through the menu '''Insert >> Coordinators'''
or, if the ISAT Elements panel is open, by left-click-drag any trigger off the panel and then releasing the left button where you want to place the trigger.

After a trigger has been placed in your scenario you can reposition it by clicking and dragging it to a new location.

'''Note:''' Trigger consist of multiple elements. To reposition a trigger you will have to click-drag the trigger handle, which is a small red dot. Clicking the larger trigger pane will move the pane, not the handle. Moving the handle will move the trigger.

[[File:2022-11-30_14h07_26.png|400px]]

Some triggers also require a roadpad (roadpad, follow, Time To Arrival triggers).
Right-click on the trigger and choose '''Place Road Pad.'''

'''Note: All triggers with road pads require a [https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#Triggers '''predicate'''] to activate the trigger.'''

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: What is a “Write to Cell” action? ===
<div class="mw-collapsible-content">

Cells are reserved data containers that define various attributes and operating characteristics of the miniSim and are stored after each drive in a unique drive DAQ file.

A '''write to cell''' action allows you to send data to miniSim and simultaneously store this data in the DAQ file during simulation.

Most cells are managed by a subsystem (behaviors, dynamics, scenario control). For these cells, writing to a cell is possible but not practical because the managing subsystem will overwrite that cell within the next frame.

'''Examples''' (not a complete list!):
# Play a sound/audio file: Write to Cell SCC_Audio_Trigger
# Set event status or an event number for default miniSim data measures: Write to Cell SCC_Event_Status, SCC_Event_Number
# Saving data during a drive to the DAQ so it is available for analysis; i.e., timing of things, storing scenario variable data (variables are not persistent unless saved to a file or written to the DAQ): Write to Cell SCC_Custom1, or user defined
# Changing a simulator setting (Adaptive Cruise Control on/off, Automatic Lane Following): Write to Cell SCC_ALF_On, SCC_ACC_On

'''Note:''' Write to cell actions are expensive operations and there is currently a limit of 7 per frame. '''Exceeding this number will likely result in the excess cells not being written'''.

'''Note:''' Some cells are managed by the Cab Information/Hardware subsystem (CIS). Configuring miniSim to support operation by both scenario and CIS may require consulting with NADS to ensure correct operation.

[[#top|TOP]]
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: How can I tell if the driver has left the road? ===
<div class="mw-collapsible-content">
One way to check if the driver has left the roadway is to use a lane deviation calculation: if the lane deviation is greater than <measured_total_lane_width> or less than -<measured_total_lane_width>, the driver is likely out of the lane.
[[#top|TOP]]
</div>
</div>

=== Q: How can I tell what surface the driver is driving over? ===
<div class="mw-collapsible-content">

A. Use the cell '''TPR_Surface_Type_Ind to detect the surface material code (SMC) under the driver.

The first four elements of the TPR_Surface_Type_Ind correspond to 4 wheels of the ownship/external driver vehicle.

[[File:2022-11-30_14h21_16.png|400px]]

[[File:2022-11-30_14h21_27.png|400px]]

MiniSim does not report surface material codes within intersections that do not have an elevation map associated with them.

[[File:2022-11-30_14h22_10.png|400px]]

You can find a complete list of available surface material codes (SMC) - (not all of these are used in the tile library, but this is the current version for SMC codes) under the TMT\ProjectData\Tiles\CommonLRIData\SurfaceMaterialSpecifications.xlsx.

'''Note:''' Intersection elevation maps were introduced in TMT '''1.8.5'''.

[[#top|TOP]]
</div>

<div class="toccolours mw-collapsible mw-collapsed">

=== Q: What is the difference between SCC_Lane_Deviation and SCC_Lane_Spline_Deviation? ===

SCC_Lane_Spline_Deviation is computed from centerline data as a continuous spline and is recommended over SCC_Lane_Deviation.

[[File:scc_lane_spline_deviation_20230918.png|400px]]

<div class="mw-collapsible-content">

File:Scc lane spline deviation 20230918.png

2023-09-18T18:05:50Z

Shawn Allen: File uploaded with MsUpload

File uploaded with MsUpload

ISAT Demonstration Scenarios

2023-09-15T15:48:38Z

Shawn Allen: /* Demo_ISAT_Show_Driver_Speed.scn */

== About the ISAT Demonstration Scenarios ==

Making something happen during a simulation in a repeatable and consistent fashion for different driving styles is the essence of scenario authoring. Every thing that happens must be coordinated to some degree with the External Driver (XD). For repeatability, it is also necessary to consider how different driving styles (aggressive vs. conservative) impact how the scenario unfolds for each.

These demonstration scenarios were created to facilitate learning how to use ISAT and do scenario actions. Each scenario demonstrates a key concept or element and may contain additional elements to support the main concept. For example, all scenarios contain an introduction to the scenario for the XD and a termination trigger that will stop the simulation.

'''These scenarios are not intended for use as completed data collection ready scenarios. They are provided to answer the question "how can I do X Y Z..?"

These scenario elements can be integrated into your scenarios using copy-paste except where elements have been created with a Create action. For those elements it will be necessary to copy the parent element instead.

TBC: Add a link to the library or directions how to get the files

== Demo_ISAT_ADO_Control.scn ==

This scenario demonstrates how to control an ADO:

• ADO set dial > forced velocity = 0 to keep ADO stationary.

• Release the forced velocity, assign a maintain gap.

• Release the maintain gap, assign a target velocity.

See also:
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn ==
This scenario demonstrates how to vary the velocity of an ADO using a Sum of Sines expression:

*Uses a forced velocity action;
*Try to maintain a constant speed at 30 mph;
*Notice how the speed of the ADO changes during the drive.

Note:
There is also a forced velocity Sin function available with 4 parameters

See Also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Oncoming_Incursion.scn ==
This scenario demonstrates the use of a forced lane offset to cause an oncoming ADO to veer into the driver’s lane:

*Additional ambient traffic is included to provide a normal driving environment;
*A following ADO will encourage slow drivers to travel the speed limit;
*Because we do not want to rely on the driver travelling at the right speed, we match the event ADO velocity to the driver to ensure the event happens as planned.

See Also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Passing_Maneuvers.scn ==
This scenario demonstrates how to implement an ADO passing maneuver on 4 lane and 2 lane roads:

*4 lane roads can use either Set Dial > ADO > Lane Change OR Set_Button > ADO > Lane Change;
*'''Lane change actions are not supported on 2 lane roads;
- Use a lane offset to produce something similar to a passing maneuver

See also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]

== Demo_ISAT_ADO_Random.scn ==

This scenario demonstrates how to use the Rand() function to assign a randomized gap to an ADO:

*Typical gap assignments are fixed/constant;
*Use of a randomized value introduces some inconsistency to the ADO position, which is organic and more realistic.
*Requires the use of variables and expressions.
*Saves the calculated randomizations to the DAQ for validation (review in ISAT).

See also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Relative_Create.scn ==

This scenario demonstrates how to use the Relative Create flag for ADOs.

'''Note:
'''Relative Create works only with negative values.

Used to create traffic behind the external driver independent of the location where the ADOs are initially placed.

See Also:

Demo_ISAT_ADO_Traffic_1.scn

== Demo_ISAT_ADO_Traffic_1.scn ==
This scenario demonstrates how to create traffic in a scenario:

*Create ADOs or copy/paste to locations within the drive;
*Create ADOs with a Creation Radius (they get created as the External Driver drives the route);
*Create ADOs with a trigger Create action;
*Generate traffic with a Traffic Source;
*Generate traffic with the Traffic Manager (or change TM sets).

Each method has advantages and disadvantages.

See Also:

: [[#Demo_ISAT_ADO_Relative_Create.scn|Demo_ISAT_ADO_Relative_Create.scn]]

== Demo_ISAT_ADO_TTA_LVPO.scn ==

This scenario demonstrates the use of Time to Arrival trigger to create a crashpossible event:

*The scenario contains some distracting elements;
*The event ADO behavior is highly dependent on the speed of the XD.
- If the driver is going too fast it may cause the event ADO to disappear
*A time trigger with creation radius acts as a proximity trigger to end the drive, in case the driver steers out of the crash area.

See Also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]

== Demo_ISAT_Alert_Slow_Moving_Object.scn ==

This scenario demonstrates how to implement a proximity alert to warn the driver of a slow moving vehicle ahead:

*Speed monitor to ensure the driver is travelling at a velocity where the event can happen
*Alarm triggers when proximity threshold is achieved

Because there is no good way to tell in advance where the event happens, the end of drive happens following the alert.

== Demo_ISAT_Avoid_Obstacle.scn ==

This demo scenario demonstrates a collision avoidance event using ambient traffic and a DDO obstacle:

*The event requires some setup to position the event vehicles
*The obstacle is a DDO (desk) contained within a van model that has operable rear doors which swing open
*The DDO transitions from a coupled object to a free motion object

== Demo_ISAT_Create_Elements.scn ==

This scenario demonstrates how to create scenario elements during a drive with the Create Element action.

*Remember all triggers share the same actions; thus, any trigger may contain a create action.
*Only 1 create action is permitted per trigger.

== Demo_ISAT_Data_Measures_Default_Measures.scn ==

This scenario demonstrates how to use the miniSim Default Measures in a scenario to produce a valid report for the drive:

*Must follow the write to cell procedure for events:
:#initialize event status and event number to zero at scenario start
:#change SCC_EventStatus from 0 to 1 for the event, and close to 0 after the event
:#change SCC_EventNumber throughout the drive (incremental count starting with 1, 2, 3, etc.)
*Produces a report.txt for each drive
*The drive report.txt for each drive is located in the DAQ folder location.

'''Note: if proper write to cell steps aren’t followed, all measures will be empty in the report.

== Demo_ISAT_Data_Measures_Logstreams.scn ==

This scenario demonstrates the use of Log Streams for documenting significant locations or events in your DAQ file.

*Best practice: initialize all Logstreams to some value at the start.
*Events may be numbered, or subdivided using the same logstream. This demo uses LogStream 1.

*The scenario author and data reduction scientist must agree on what measures are important to encode.

== Demo_ISAT_DDOs.scn ==

This scenario demonstrates different ways to use DDOs and DDDOs. Both types typically begin moving when the scenario starts, unless you assign a creation radius or control the DDO speed.

1. DDO: simple path follower.

2. DDDO (dependent path follower): includes a target path node and a target point. The
DDDO movement is constrained so when the specified object is at the target point, the DDDO will be at the target path node irrespective of the speed assigned to each node.
DDO and DDDOs can be pedestrians, animals or vehicles.

== Demo_ISAT_Display_Screen_Text.scn ==

This scenario demonstrates how to display text messages to the screen.

Text font, color and locations are specified at: NadsMiniSim_x.x\bin.x64\config\scenario_text.xml

'''*Be sure to maintain a backup if you edit this file!

See Also:
Demo_ISAT_Monitor_Driver_Speed.scn
Demo_ISAT_Show_Driver_Speed.scn

==Demo_ISAT_ENV_Dynamic_Fog.scn ==

This scenario demonstrates how to gradually apply fog and the difference between fog and visibility. The usual method of adding weather effects to a scenario is by defining a region of influence which means the effect is applied abruptly to the scene at the region boundaries (on/off).

*Fog and Visibility are Weather Effects
- Insert >> Environment Conditions
*Fog density is managed with 3 variables:
::#FogDistance
::#MaximumFog
::#FogDensity
*An example of reduced Visibility is included near the end of this drive to show how that setting is different from fog.

== Demo_ISAT_time_of_day.scn==

This scenario demonstrates how to change the time of day:

*Variables are used to track day-night cycles
*Time settings (Hour) were chosen arbitrarily
::'''Small time differences will not affect environment; ie. 07:10 – 07:30
*A parked F150 ADO in the scenario has auto-headlights enabled

'''NOTE: Headlight control from scenario requires changes to the miniSim hardware.xml configuration file – they do not automatically turn on at night

==Demo_ISAT_Exit_Simulation_on_Collision.scn ==

This scenario demonstrates how to terminate simulation if a collision happens during a drive. Collisions may occur with ADOs, DDOs, DDDOs and static objects that are present in the scene.

'''Note:
It is possible to configure miniSim or edit the scenario object list file (SOL2.txt) to disable collisions either globally or for specific objects. In that event this scenario will not terminate due to a collision.

==Demo_ISAT_Exit_Follow_Trigger_Create.scn ==

This scenario demonstrates use of the Follow Trigger:

*The follow trigger can activate between any two dynamic objects;
*Most commonly uses the XD for one of the two objects (leader or follower);
*Trigger instigator (predicate) can be either;
*The follow trigger action stack is processed when the trigger conditions have been met;
*When the actions are executed an oncoming Ambulance ADO is created.

== Demo_ISAT_Get_ObjTTC.scn==

This scenario demonstrates how to get a Time To Collision for dynamic and stationary objects (DDOs and ADOs):

*Any time delays in the action stack collecting data and reporting it will create a variance between what you measure in ISAT and what gets reported in the DAQ;
*Cells and variables are used to get the information for TTC and distance;
*Variables are written to SCC_Custom1 – 3 for distance, TTC and the raw distance value reported by GetObjDistPow2;
*3 events are shown to illustrate re-use of the same variables throughout for the target object:
::#DDO dynamic
::#DDO stationary
::#ADO stationary
*Logstreams are used for event numbering and distances to each object;
*If you re-use the same object name, you must remove the previous object – only 1 should be present in the simulation at any time.

'''NOTE:
Static objects cannot be created in realtime with the Create Element action, but they can be created as DDOs. They default to their first visual option; change with a set switch action.

==Demo_ISAT_Lane_Context_Actions.scn ==
This scenario demonstrates how to limit actions to a specific lane.

*Lane filter can only be used with roadpad triggers.
*Useful for situational cases: if the driver is in the correct lane, then they will not receive alert. If the driver is in the wrong lane, then they will.
*Also useful for ADO control at the lane level.

See also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]

==Demo_ISAT_Loop_Management_Traffic.scn ==

This scenario demonstrates how to configure a scenario where it is necessary to drive multiple loops:

*Increment a counter at the location the loop counts increase;
::Each time through the loop a unique action happens
::Increment and decrement operators are not expressions!
*Expression triggers fire on loops (one per loop);
*Can create more than ADOs.

==Demo_ISAT_Monitor_Driver_Speed.scn ==

This scenario demonstrates how to monitor driver velocity. Triggers are configured to monitor driving too slowly (under speed) and driving too fast. The threshold between under and over speed is intentionally difficult to maintain – the goal is to achieve a few alerts of either kind during the drive:

*Variable sets are used for under, over speed cases:
::a timer that increments a variable for each;
::an additional conditional (variable) so there is no alert at scenario start, while the driver is getting up to operating speed.

==Demo_ISAT_Play_Audio.scn ==

This scenario demonstrates how to play audio messages on miniSim using the write to cell >> SCC_Audio_Trigger action.
A short delay after the write to cell action is recommended.

'''Note:
'''Recommended practice requires a second write to cell action to ‘clear’ the previous audio message.

Playing two write to cell >> SCC_Audio_Trigger actions back to back with no delay, and no ‘clear’ likely results in a single audio message. For long messages, use the length of the message as a delay to avoid over-writing the message being played with any subsequent messages.

See also:

[https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#How_to_Use_Audio_in_your_Scenario How to Use Audio in your Scenario]

==Demo_ISAT_Right_Incursion.scn ==

This scenario demonstrates how to present a crash possible event using a right-side incursion:

• Ambient traffic and features are used during the drive; • The event is coupled with an oncoming vehicle distraction;
• The event is masked by features in the scene.

==Demo_ISAT_Set_Switch.scn ==

This scenario demonstrates how to change objects during a simulation with a Set Switch action (static object, DDO, ADO objects).

• The set switch action requires the model switch name;
• Switches for all models are listed in the file NadsMiniSim_x.x\bin.x64\ModelList.txt

==Demo_ISAT_Stop_Drive.scn ==

This scenario demonstrates how to terminate a simulation from the scenario:

• A roadpad trigger tells the driver it is time to stop and shift into park, and creates an Expression trigger to:
- monitor the transmission gear,
- terminate the simulation if the driver shifts into Park.
A Roadpad trigger acts as a backup that ends the drive if the XD doesn’t stop.

==Demo_ISAT_Show_Driver_Speed.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action.

* A time trigger is configured to monitor conditions; in this case, the external driver’s speed.
* The monitoring trigger is created by a roadpad trigger to ensure the driver is moving; therefore driver velocity is not zero.

* The monitoring trigger fires repeatedly during the drive.
* A variable is set to the value of a cell containing the driver velocity;
* That value is displayed on screen.

See Also:
: [[#Demo_ISAT_Display_Screen_Text.scn|Demo_ISAT_Display_Screen_Text.scn]]
: [[#Demo_ISAT_Monitor_Driver_Speed.scn|Demo_ISAT_Monitor_Driver_Speed.scn]]

==Demo_ISAT_Track_Button_Press.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action:

• A time trigger This demo scenario uses expression triggers to detect button presses (turn signal activation).
• Variables are used to track which signal was activated (left vs. right) and demo progress.

'''Note:
'''The values used in the scenario may be site-specific; if your miniSim does not produce the values used, this scenario may fail.

To determine the correct values for your miniSim, drive any scenario and press the left, then the right turn signals and review this drive DAQ in ISAT. The relevant cell is CIS_Turn_Signal.

==Demo_ISAT_Traffic_Light.scn ==

This scenario demonstrates the use of a Traffic Light Trigger:

*A traffic light trigger activates at a specified signal state;
*Relies on a traffic light action to set the signal to a specified state;
*That state must already exist in the traffic signal timing table configuration for the intersection
::dbl-click on the traffic signal to open the signal timing table

*A more robust method would use a time to arrival (TTA) trigger that can accommodate different XD velocities or driving styles (conservative vs. aggressive, slow vs. fast) instead of the roadpad and delays used in this demo.

==Demo_ISAT_Virtual_Objects.scn ==

This scenario demonstrates how to display and control virtual objects during a drive. Virtual objects render to screen space on top of everything on display; they do not typically occupy 3d space within the scene.

One possible application for virtual objects is to use them as a custom heads up display (HUD) or alert system within the scenario.

By default virtual objects initialize to state 0 (off/disabled) at scenario start.

'''Note:
'''Currently only Render Type = Overlay and Main Screen are supported.

==Demo_ISAT_Yellow_Light_Dilemma.scn ==

This scenario demonstrates how to create a Yellow Light dilemma at an intersection.

#There must be a working signal state table;
#The traffic signal is controlled by a time to arrival (TTA) trigger;
#If the XD decides to stop, a roadpad trigger created by (2) will reset the signal to green so the XD can continue the drive;
#A roadpad trigger terminates the drive after the intersection.

ISAT Demonstration Scenarios

2023-09-15T15:46:24Z

Shawn Allen: /* Demo_ISAT_Play_Audio.scn */

== About the ISAT Demonstration Scenarios ==

Making something happen during a simulation in a repeatable and consistent fashion for different driving styles is the essence of scenario authoring. Every thing that happens must be coordinated to some degree with the External Driver (XD). For repeatability, it is also necessary to consider how different driving styles (aggressive vs. conservative) impact how the scenario unfolds for each.

These demonstration scenarios were created to facilitate learning how to use ISAT and do scenario actions. Each scenario demonstrates a key concept or element and may contain additional elements to support the main concept. For example, all scenarios contain an introduction to the scenario for the XD and a termination trigger that will stop the simulation.

'''These scenarios are not intended for use as completed data collection ready scenarios. They are provided to answer the question "how can I do X Y Z..?"

These scenario elements can be integrated into your scenarios using copy-paste except where elements have been created with a Create action. For those elements it will be necessary to copy the parent element instead.

TBC: Add a link to the library or directions how to get the files

== Demo_ISAT_ADO_Control.scn ==

This scenario demonstrates how to control an ADO:

• ADO set dial > forced velocity = 0 to keep ADO stationary.

• Release the forced velocity, assign a maintain gap.

• Release the maintain gap, assign a target velocity.

See also:
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn ==
This scenario demonstrates how to vary the velocity of an ADO using a Sum of Sines expression:

*Uses a forced velocity action;
*Try to maintain a constant speed at 30 mph;
*Notice how the speed of the ADO changes during the drive.

Note:
There is also a forced velocity Sin function available with 4 parameters

See Also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Oncoming_Incursion.scn ==
This scenario demonstrates the use of a forced lane offset to cause an oncoming ADO to veer into the driver’s lane:

*Additional ambient traffic is included to provide a normal driving environment;
*A following ADO will encourage slow drivers to travel the speed limit;
*Because we do not want to rely on the driver travelling at the right speed, we match the event ADO velocity to the driver to ensure the event happens as planned.

See Also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Passing_Maneuvers.scn ==
This scenario demonstrates how to implement an ADO passing maneuver on 4 lane and 2 lane roads:

*4 lane roads can use either Set Dial > ADO > Lane Change OR Set_Button > ADO > Lane Change;
*'''Lane change actions are not supported on 2 lane roads;
- Use a lane offset to produce something similar to a passing maneuver

See also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]

== Demo_ISAT_ADO_Random.scn ==

This scenario demonstrates how to use the Rand() function to assign a randomized gap to an ADO:

*Typical gap assignments are fixed/constant;
*Use of a randomized value introduces some inconsistency to the ADO position, which is organic and more realistic.
*Requires the use of variables and expressions.
*Saves the calculated randomizations to the DAQ for validation (review in ISAT).

See also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Relative_Create.scn ==

This scenario demonstrates how to use the Relative Create flag for ADOs.

'''Note:
'''Relative Create works only with negative values.

Used to create traffic behind the external driver independent of the location where the ADOs are initially placed.

See Also:

Demo_ISAT_ADO_Traffic_1.scn

== Demo_ISAT_ADO_Traffic_1.scn ==
This scenario demonstrates how to create traffic in a scenario:

*Create ADOs or copy/paste to locations within the drive;
*Create ADOs with a Creation Radius (they get created as the External Driver drives the route);
*Create ADOs with a trigger Create action;
*Generate traffic with a Traffic Source;
*Generate traffic with the Traffic Manager (or change TM sets).

Each method has advantages and disadvantages.

See Also:

: [[#Demo_ISAT_ADO_Relative_Create.scn|Demo_ISAT_ADO_Relative_Create.scn]]

== Demo_ISAT_ADO_TTA_LVPO.scn ==

This scenario demonstrates the use of Time to Arrival trigger to create a crashpossible event:

*The scenario contains some distracting elements;
*The event ADO behavior is highly dependent on the speed of the XD.
- If the driver is going too fast it may cause the event ADO to disappear
*A time trigger with creation radius acts as a proximity trigger to end the drive, in case the driver steers out of the crash area.

See Also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]

== Demo_ISAT_Alert_Slow_Moving_Object.scn ==

This scenario demonstrates how to implement a proximity alert to warn the driver of a slow moving vehicle ahead:

*Speed monitor to ensure the driver is travelling at a velocity where the event can happen
*Alarm triggers when proximity threshold is achieved

Because there is no good way to tell in advance where the event happens, the end of drive happens following the alert.

== Demo_ISAT_Avoid_Obstacle.scn ==

This demo scenario demonstrates a collision avoidance event using ambient traffic and a DDO obstacle:

*The event requires some setup to position the event vehicles
*The obstacle is a DDO (desk) contained within a van model that has operable rear doors which swing open
*The DDO transitions from a coupled object to a free motion object

== Demo_ISAT_Create_Elements.scn ==

This scenario demonstrates how to create scenario elements during a drive with the Create Element action.

*Remember all triggers share the same actions; thus, any trigger may contain a create action.
*Only 1 create action is permitted per trigger.

== Demo_ISAT_Data_Measures_Default_Measures.scn ==

This scenario demonstrates how to use the miniSim Default Measures in a scenario to produce a valid report for the drive:

*Must follow the write to cell procedure for events:
:#initialize event status and event number to zero at scenario start
:#change SCC_EventStatus from 0 to 1 for the event, and close to 0 after the event
:#change SCC_EventNumber throughout the drive (incremental count starting with 1, 2, 3, etc.)
*Produces a report.txt for each drive
*The drive report.txt for each drive is located in the DAQ folder location.

'''Note: if proper write to cell steps aren’t followed, all measures will be empty in the report.

== Demo_ISAT_Data_Measures_Logstreams.scn ==

This scenario demonstrates the use of Log Streams for documenting significant locations or events in your DAQ file.

*Best practice: initialize all Logstreams to some value at the start.
*Events may be numbered, or subdivided using the same logstream. This demo uses LogStream 1.

*The scenario author and data reduction scientist must agree on what measures are important to encode.

== Demo_ISAT_DDOs.scn ==

This scenario demonstrates different ways to use DDOs and DDDOs. Both types typically begin moving when the scenario starts, unless you assign a creation radius or control the DDO speed.

1. DDO: simple path follower.

2. DDDO (dependent path follower): includes a target path node and a target point. The
DDDO movement is constrained so when the specified object is at the target point, the DDDO will be at the target path node irrespective of the speed assigned to each node.
DDO and DDDOs can be pedestrians, animals or vehicles.

== Demo_ISAT_Display_Screen_Text.scn ==

This scenario demonstrates how to display text messages to the screen.

Text font, color and locations are specified at: NadsMiniSim_x.x\bin.x64\config\scenario_text.xml

'''*Be sure to maintain a backup if you edit this file!

See Also:
Demo_ISAT_Monitor_Driver_Speed.scn
Demo_ISAT_Show_Driver_Speed.scn

==Demo_ISAT_ENV_Dynamic_Fog.scn ==

This scenario demonstrates how to gradually apply fog and the difference between fog and visibility. The usual method of adding weather effects to a scenario is by defining a region of influence which means the effect is applied abruptly to the scene at the region boundaries (on/off).

*Fog and Visibility are Weather Effects
- Insert >> Environment Conditions
*Fog density is managed with 3 variables:
::#FogDistance
::#MaximumFog
::#FogDensity
*An example of reduced Visibility is included near the end of this drive to show how that setting is different from fog.

== Demo_ISAT_time_of_day.scn==

This scenario demonstrates how to change the time of day:

*Variables are used to track day-night cycles
*Time settings (Hour) were chosen arbitrarily
::'''Small time differences will not affect environment; ie. 07:10 – 07:30
*A parked F150 ADO in the scenario has auto-headlights enabled

'''NOTE: Headlight control from scenario requires changes to the miniSim hardware.xml configuration file – they do not automatically turn on at night

==Demo_ISAT_Exit_Simulation_on_Collision.scn ==

This scenario demonstrates how to terminate simulation if a collision happens during a drive. Collisions may occur with ADOs, DDOs, DDDOs and static objects that are present in the scene.

'''Note:
It is possible to configure miniSim or edit the scenario object list file (SOL2.txt) to disable collisions either globally or for specific objects. In that event this scenario will not terminate due to a collision.

==Demo_ISAT_Exit_Follow_Trigger_Create.scn ==

This scenario demonstrates use of the Follow Trigger:

*The follow trigger can activate between any two dynamic objects;
*Most commonly uses the XD for one of the two objects (leader or follower);
*Trigger instigator (predicate) can be either;
*The follow trigger action stack is processed when the trigger conditions have been met;
*When the actions are executed an oncoming Ambulance ADO is created.

== Demo_ISAT_Get_ObjTTC.scn==

This scenario demonstrates how to get a Time To Collision for dynamic and stationary objects (DDOs and ADOs):

*Any time delays in the action stack collecting data and reporting it will create a variance between what you measure in ISAT and what gets reported in the DAQ;
*Cells and variables are used to get the information for TTC and distance;
*Variables are written to SCC_Custom1 – 3 for distance, TTC and the raw distance value reported by GetObjDistPow2;
*3 events are shown to illustrate re-use of the same variables throughout for the target object:
::#DDO dynamic
::#DDO stationary
::#ADO stationary
*Logstreams are used for event numbering and distances to each object;
*If you re-use the same object name, you must remove the previous object – only 1 should be present in the simulation at any time.

'''NOTE:
Static objects cannot be created in realtime with the Create Element action, but they can be created as DDOs. They default to their first visual option; change with a set switch action.

==Demo_ISAT_Lane_Context_Actions.scn ==
This scenario demonstrates how to limit actions to a specific lane.

*Lane filter can only be used with roadpad triggers.
*Useful for situational cases: if the driver is in the correct lane, then they will not receive alert. If the driver is in the wrong lane, then they will.
*Also useful for ADO control at the lane level.

See also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]

==Demo_ISAT_Loop_Management_Traffic.scn ==

This scenario demonstrates how to configure a scenario where it is necessary to drive multiple loops:

*Increment a counter at the location the loop counts increase;
::Each time through the loop a unique action happens
::Increment and decrement operators are not expressions!
*Expression triggers fire on loops (one per loop);
*Can create more than ADOs.

==Demo_ISAT_Monitor_Driver_Speed.scn ==

This scenario demonstrates how to monitor driver velocity. Triggers are configured to monitor driving too slowly (under speed) and driving too fast. The threshold between under and over speed is intentionally difficult to maintain – the goal is to achieve a few alerts of either kind during the drive:

*Variable sets are used for under, over speed cases:
::a timer that increments a variable for each;
::an additional conditional (variable) so there is no alert at scenario start, while the driver is getting up to operating speed.

==Demo_ISAT_Play_Audio.scn ==

This scenario demonstrates how to play audio messages on miniSim using the write to cell >> SCC_Audio_Trigger action.
A short delay after the write to cell action is recommended.

'''Note:
'''Recommended practice requires a second write to cell action to ‘clear’ the previous audio message.

Playing two write to cell >> SCC_Audio_Trigger actions back to back with no delay, and no ‘clear’ likely results in a single audio message. For long messages, use the length of the message as a delay to avoid over-writing the message being played with any subsequent messages.

See also:

[https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#How_to_Use_Audio_in_your_Scenario How to Use Audio in your Scenario]

==Demo_ISAT_Right_Incursion.scn ==

This scenario demonstrates how to present a crash possible event using a right-side incursion:

• Ambient traffic and features are used during the drive; • The event is coupled with an oncoming vehicle distraction;
• The event is masked by features in the scene.

==Demo_ISAT_Set_Switch.scn ==

This scenario demonstrates how to change objects during a simulation with a Set Switch action (static object, DDO, ADO objects).

• The set switch action requires the model switch name;
• Switches for all models are listed in the file NadsMiniSim_x.x\bin.x64\ModelList.txt

==Demo_ISAT_Stop_Drive.scn ==

This scenario demonstrates how to terminate a simulation from the scenario:

• A roadpad trigger tells the driver it is time to stop and shift into park, and creates an Expression trigger to:
- monitor the transmission gear,
- terminate the simulation if the driver shifts into Park.
A Roadpad trigger acts as a backup that ends the drive if the XD doesn’t stop.

==Demo_ISAT_Show_Driver_Speed.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action.

* A time trigger is configured to monitor conditions; in this case, the external driver’s speed.
* The monitoring trigger is created by a roadpad trigger to ensure the driver is moving; therefore driver velocity is not zero.

* The monitoring trigger fires repeatedly during the drive.
* A variable is set to the value of a cell containing the driver velocity;
* That value is displayed on screen.

See Also:
:Demo_ISAT_Display_Screen_Text.scn
:Demo_ISAT_Monitor_Driver_Speed.scn

==Demo_ISAT_Track_Button_Press.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action:

• A time trigger This demo scenario uses expression triggers to detect button presses (turn signal activation).
• Variables are used to track which signal was activated (left vs. right) and demo progress.

'''Note:
'''The values used in the scenario may be site-specific; if your miniSim does not produce the values used, this scenario may fail.

To determine the correct values for your miniSim, drive any scenario and press the left, then the right turn signals and review this drive DAQ in ISAT. The relevant cell is CIS_Turn_Signal.

==Demo_ISAT_Traffic_Light.scn ==

This scenario demonstrates the use of a Traffic Light Trigger:

*A traffic light trigger activates at a specified signal state;
*Relies on a traffic light action to set the signal to a specified state;
*That state must already exist in the traffic signal timing table configuration for the intersection
::dbl-click on the traffic signal to open the signal timing table

*A more robust method would use a time to arrival (TTA) trigger that can accommodate different XD velocities or driving styles (conservative vs. aggressive, slow vs. fast) instead of the roadpad and delays used in this demo.

==Demo_ISAT_Virtual_Objects.scn ==

This scenario demonstrates how to display and control virtual objects during a drive. Virtual objects render to screen space on top of everything on display; they do not typically occupy 3d space within the scene.

One possible application for virtual objects is to use them as a custom heads up display (HUD) or alert system within the scenario.

By default virtual objects initialize to state 0 (off/disabled) at scenario start.

'''Note:
'''Currently only Render Type = Overlay and Main Screen are supported.

==Demo_ISAT_Yellow_Light_Dilemma.scn ==

This scenario demonstrates how to create a Yellow Light dilemma at an intersection.

#There must be a working signal state table;
#The traffic signal is controlled by a time to arrival (TTA) trigger;
#If the XD decides to stop, a roadpad trigger created by (2) will reset the signal to green so the XD can continue the drive;
#A roadpad trigger terminates the drive after the intersection.

ISAT Demonstration Scenarios

2023-09-15T15:44:55Z

Shawn Allen: /* Demo_ISAT_Play_Audio.scn */

== About the ISAT Demonstration Scenarios ==

Making something happen during a simulation in a repeatable and consistent fashion for different driving styles is the essence of scenario authoring. Every thing that happens must be coordinated to some degree with the External Driver (XD). For repeatability, it is also necessary to consider how different driving styles (aggressive vs. conservative) impact how the scenario unfolds for each.

These demonstration scenarios were created to facilitate learning how to use ISAT and do scenario actions. Each scenario demonstrates a key concept or element and may contain additional elements to support the main concept. For example, all scenarios contain an introduction to the scenario for the XD and a termination trigger that will stop the simulation.

'''These scenarios are not intended for use as completed data collection ready scenarios. They are provided to answer the question "how can I do X Y Z..?"

These scenario elements can be integrated into your scenarios using copy-paste except where elements have been created with a Create action. For those elements it will be necessary to copy the parent element instead.

TBC: Add a link to the library or directions how to get the files

== Demo_ISAT_ADO_Control.scn ==

This scenario demonstrates how to control an ADO:

• ADO set dial > forced velocity = 0 to keep ADO stationary.

• Release the forced velocity, assign a maintain gap.

• Release the maintain gap, assign a target velocity.

See also:
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn ==
This scenario demonstrates how to vary the velocity of an ADO using a Sum of Sines expression:

*Uses a forced velocity action;
*Try to maintain a constant speed at 30 mph;
*Notice how the speed of the ADO changes during the drive.

Note:
There is also a forced velocity Sin function available with 4 parameters

See Also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Oncoming_Incursion.scn ==
This scenario demonstrates the use of a forced lane offset to cause an oncoming ADO to veer into the driver’s lane:

*Additional ambient traffic is included to provide a normal driving environment;
*A following ADO will encourage slow drivers to travel the speed limit;
*Because we do not want to rely on the driver travelling at the right speed, we match the event ADO velocity to the driver to ensure the event happens as planned.

See Also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Passing_Maneuvers.scn ==
This scenario demonstrates how to implement an ADO passing maneuver on 4 lane and 2 lane roads:

*4 lane roads can use either Set Dial > ADO > Lane Change OR Set_Button > ADO > Lane Change;
*'''Lane change actions are not supported on 2 lane roads;
- Use a lane offset to produce something similar to a passing maneuver

See also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]

== Demo_ISAT_ADO_Random.scn ==

This scenario demonstrates how to use the Rand() function to assign a randomized gap to an ADO:

*Typical gap assignments are fixed/constant;
*Use of a randomized value introduces some inconsistency to the ADO position, which is organic and more realistic.
*Requires the use of variables and expressions.
*Saves the calculated randomizations to the DAQ for validation (review in ISAT).

See also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Relative_Create.scn ==

This scenario demonstrates how to use the Relative Create flag for ADOs.

'''Note:
'''Relative Create works only with negative values.

Used to create traffic behind the external driver independent of the location where the ADOs are initially placed.

See Also:

Demo_ISAT_ADO_Traffic_1.scn

== Demo_ISAT_ADO_Traffic_1.scn ==
This scenario demonstrates how to create traffic in a scenario:

*Create ADOs or copy/paste to locations within the drive;
*Create ADOs with a Creation Radius (they get created as the External Driver drives the route);
*Create ADOs with a trigger Create action;
*Generate traffic with a Traffic Source;
*Generate traffic with the Traffic Manager (or change TM sets).

Each method has advantages and disadvantages.

See Also:

: [[#Demo_ISAT_ADO_Relative_Create.scn|Demo_ISAT_ADO_Relative_Create.scn]]

== Demo_ISAT_ADO_TTA_LVPO.scn ==

This scenario demonstrates the use of Time to Arrival trigger to create a crashpossible event:

*The scenario contains some distracting elements;
*The event ADO behavior is highly dependent on the speed of the XD.
- If the driver is going too fast it may cause the event ADO to disappear
*A time trigger with creation radius acts as a proximity trigger to end the drive, in case the driver steers out of the crash area.

See Also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]

== Demo_ISAT_Alert_Slow_Moving_Object.scn ==

This scenario demonstrates how to implement a proximity alert to warn the driver of a slow moving vehicle ahead:

*Speed monitor to ensure the driver is travelling at a velocity where the event can happen
*Alarm triggers when proximity threshold is achieved

Because there is no good way to tell in advance where the event happens, the end of drive happens following the alert.

== Demo_ISAT_Avoid_Obstacle.scn ==

This demo scenario demonstrates a collision avoidance event using ambient traffic and a DDO obstacle:

*The event requires some setup to position the event vehicles
*The obstacle is a DDO (desk) contained within a van model that has operable rear doors which swing open
*The DDO transitions from a coupled object to a free motion object

== Demo_ISAT_Create_Elements.scn ==

This scenario demonstrates how to create scenario elements during a drive with the Create Element action.

*Remember all triggers share the same actions; thus, any trigger may contain a create action.
*Only 1 create action is permitted per trigger.

== Demo_ISAT_Data_Measures_Default_Measures.scn ==

This scenario demonstrates how to use the miniSim Default Measures in a scenario to produce a valid report for the drive:

*Must follow the write to cell procedure for events:
:#initialize event status and event number to zero at scenario start
:#change SCC_EventStatus from 0 to 1 for the event, and close to 0 after the event
:#change SCC_EventNumber throughout the drive (incremental count starting with 1, 2, 3, etc.)
*Produces a report.txt for each drive
*The drive report.txt for each drive is located in the DAQ folder location.

'''Note: if proper write to cell steps aren’t followed, all measures will be empty in the report.

== Demo_ISAT_Data_Measures_Logstreams.scn ==

This scenario demonstrates the use of Log Streams for documenting significant locations or events in your DAQ file.

*Best practice: initialize all Logstreams to some value at the start.
*Events may be numbered, or subdivided using the same logstream. This demo uses LogStream 1.

*The scenario author and data reduction scientist must agree on what measures are important to encode.

== Demo_ISAT_DDOs.scn ==

This scenario demonstrates different ways to use DDOs and DDDOs. Both types typically begin moving when the scenario starts, unless you assign a creation radius or control the DDO speed.

1. DDO: simple path follower.

2. DDDO (dependent path follower): includes a target path node and a target point. The
DDDO movement is constrained so when the specified object is at the target point, the DDDO will be at the target path node irrespective of the speed assigned to each node.
DDO and DDDOs can be pedestrians, animals or vehicles.

== Demo_ISAT_Display_Screen_Text.scn ==

This scenario demonstrates how to display text messages to the screen.

Text font, color and locations are specified at: NadsMiniSim_x.x\bin.x64\config\scenario_text.xml

'''*Be sure to maintain a backup if you edit this file!

See Also:
Demo_ISAT_Monitor_Driver_Speed.scn
Demo_ISAT_Show_Driver_Speed.scn

==Demo_ISAT_ENV_Dynamic_Fog.scn ==

This scenario demonstrates how to gradually apply fog and the difference between fog and visibility. The usual method of adding weather effects to a scenario is by defining a region of influence which means the effect is applied abruptly to the scene at the region boundaries (on/off).

*Fog and Visibility are Weather Effects
- Insert >> Environment Conditions
*Fog density is managed with 3 variables:
::#FogDistance
::#MaximumFog
::#FogDensity
*An example of reduced Visibility is included near the end of this drive to show how that setting is different from fog.

== Demo_ISAT_time_of_day.scn==

This scenario demonstrates how to change the time of day:

*Variables are used to track day-night cycles
*Time settings (Hour) were chosen arbitrarily
::'''Small time differences will not affect environment; ie. 07:10 – 07:30
*A parked F150 ADO in the scenario has auto-headlights enabled

'''NOTE: Headlight control from scenario requires changes to the miniSim hardware.xml configuration file – they do not automatically turn on at night

==Demo_ISAT_Exit_Simulation_on_Collision.scn ==

This scenario demonstrates how to terminate simulation if a collision happens during a drive. Collisions may occur with ADOs, DDOs, DDDOs and static objects that are present in the scene.

'''Note:
It is possible to configure miniSim or edit the scenario object list file (SOL2.txt) to disable collisions either globally or for specific objects. In that event this scenario will not terminate due to a collision.

==Demo_ISAT_Exit_Follow_Trigger_Create.scn ==

This scenario demonstrates use of the Follow Trigger:

*The follow trigger can activate between any two dynamic objects;
*Most commonly uses the XD for one of the two objects (leader or follower);
*Trigger instigator (predicate) can be either;
*The follow trigger action stack is processed when the trigger conditions have been met;
*When the actions are executed an oncoming Ambulance ADO is created.

== Demo_ISAT_Get_ObjTTC.scn==

This scenario demonstrates how to get a Time To Collision for dynamic and stationary objects (DDOs and ADOs):

*Any time delays in the action stack collecting data and reporting it will create a variance between what you measure in ISAT and what gets reported in the DAQ;
*Cells and variables are used to get the information for TTC and distance;
*Variables are written to SCC_Custom1 – 3 for distance, TTC and the raw distance value reported by GetObjDistPow2;
*3 events are shown to illustrate re-use of the same variables throughout for the target object:
::#DDO dynamic
::#DDO stationary
::#ADO stationary
*Logstreams are used for event numbering and distances to each object;
*If you re-use the same object name, you must remove the previous object – only 1 should be present in the simulation at any time.

'''NOTE:
Static objects cannot be created in realtime with the Create Element action, but they can be created as DDOs. They default to their first visual option; change with a set switch action.

==Demo_ISAT_Lane_Context_Actions.scn ==
This scenario demonstrates how to limit actions to a specific lane.

*Lane filter can only be used with roadpad triggers.
*Useful for situational cases: if the driver is in the correct lane, then they will not receive alert. If the driver is in the wrong lane, then they will.
*Also useful for ADO control at the lane level.

See also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]

==Demo_ISAT_Loop_Management_Traffic.scn ==

This scenario demonstrates how to configure a scenario where it is necessary to drive multiple loops:

*Increment a counter at the location the loop counts increase;
::Each time through the loop a unique action happens
::Increment and decrement operators are not expressions!
*Expression triggers fire on loops (one per loop);
*Can create more than ADOs.

==Demo_ISAT_Monitor_Driver_Speed.scn ==

This scenario demonstrates how to monitor driver velocity. Triggers are configured to monitor driving too slowly (under speed) and driving too fast. The threshold between under and over speed is intentionally difficult to maintain – the goal is to achieve a few alerts of either kind during the drive:

*Variable sets are used for under, over speed cases:
::a timer that increments a variable for each;
::an additional conditional (variable) so there is no alert at scenario start, while the driver is getting up to operating speed.

==Demo_ISAT_Play_Audio.scn ==

This scenario demonstrates how to play audio messages on miniSim using the write to cell >> SCC_Audio_Trigger action.
A short delay after the write to cell action is recommended.

'''Note:
'''Recommended practice requires a second write to cell action to ‘clear’ the previous audio message.

Playing two write to cell >> SCC_Audio_Trigger actions back to back with no delay, and no ‘clear’ likely results in a single audio message. For long messages, use the length of the message as a delay to avoid over-writing the message being played with any subsequent messages.

See also:

[https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#How_to_Use_Audio_in_your_Scenario | How to Use Audio in your Scenario]

==Demo_ISAT_Right_Incursion.scn ==

This scenario demonstrates how to present a crash possible event using a right-side incursion:

• Ambient traffic and features are used during the drive; • The event is coupled with an oncoming vehicle distraction;
• The event is masked by features in the scene.

==Demo_ISAT_Set_Switch.scn ==

This scenario demonstrates how to change objects during a simulation with a Set Switch action (static object, DDO, ADO objects).

• The set switch action requires the model switch name;
• Switches for all models are listed in the file NadsMiniSim_x.x\bin.x64\ModelList.txt

==Demo_ISAT_Stop_Drive.scn ==

This scenario demonstrates how to terminate a simulation from the scenario:

• A roadpad trigger tells the driver it is time to stop and shift into park, and creates an Expression trigger to:
- monitor the transmission gear,
- terminate the simulation if the driver shifts into Park.
A Roadpad trigger acts as a backup that ends the drive if the XD doesn’t stop.

==Demo_ISAT_Show_Driver_Speed.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action.

* A time trigger is configured to monitor conditions; in this case, the external driver’s speed.
* The monitoring trigger is created by a roadpad trigger to ensure the driver is moving; therefore driver velocity is not zero.

* The monitoring trigger fires repeatedly during the drive.
* A variable is set to the value of a cell containing the driver velocity;
* That value is displayed on screen.

See Also:
:Demo_ISAT_Display_Screen_Text.scn
:Demo_ISAT_Monitor_Driver_Speed.scn

==Demo_ISAT_Track_Button_Press.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action:

• A time trigger This demo scenario uses expression triggers to detect button presses (turn signal activation).
• Variables are used to track which signal was activated (left vs. right) and demo progress.

'''Note:
'''The values used in the scenario may be site-specific; if your miniSim does not produce the values used, this scenario may fail.

To determine the correct values for your miniSim, drive any scenario and press the left, then the right turn signals and review this drive DAQ in ISAT. The relevant cell is CIS_Turn_Signal.

==Demo_ISAT_Traffic_Light.scn ==

This scenario demonstrates the use of a Traffic Light Trigger:

*A traffic light trigger activates at a specified signal state;
*Relies on a traffic light action to set the signal to a specified state;
*That state must already exist in the traffic signal timing table configuration for the intersection
::dbl-click on the traffic signal to open the signal timing table

*A more robust method would use a time to arrival (TTA) trigger that can accommodate different XD velocities or driving styles (conservative vs. aggressive, slow vs. fast) instead of the roadpad and delays used in this demo.

==Demo_ISAT_Virtual_Objects.scn ==

This scenario demonstrates how to display and control virtual objects during a drive. Virtual objects render to screen space on top of everything on display; they do not typically occupy 3d space within the scene.

One possible application for virtual objects is to use them as a custom heads up display (HUD) or alert system within the scenario.

By default virtual objects initialize to state 0 (off/disabled) at scenario start.

'''Note:
'''Currently only Render Type = Overlay and Main Screen are supported.

==Demo_ISAT_Yellow_Light_Dilemma.scn ==

This scenario demonstrates how to create a Yellow Light dilemma at an intersection.

#There must be a working signal state table;
#The traffic signal is controlled by a time to arrival (TTA) trigger;
#If the XD decides to stop, a roadpad trigger created by (2) will reset the signal to green so the XD can continue the drive;
#A roadpad trigger terminates the drive after the intersection.

ISAT Demonstration Scenarios

2023-09-15T15:38:54Z

Shawn Allen: /* Demo_ISAT_Play_Audio.scn add hyperlink to isat user guide section on audio*/

== About the ISAT Demonstration Scenarios ==

Making something happen during a simulation in a repeatable and consistent fashion for different driving styles is the essence of scenario authoring. Every thing that happens must be coordinated to some degree with the External Driver (XD). For repeatability, it is also necessary to consider how different driving styles (aggressive vs. conservative) impact how the scenario unfolds for each.

These demonstration scenarios were created to facilitate learning how to use ISAT and do scenario actions. Each scenario demonstrates a key concept or element and may contain additional elements to support the main concept. For example, all scenarios contain an introduction to the scenario for the XD and a termination trigger that will stop the simulation.

'''These scenarios are not intended for use as completed data collection ready scenarios. They are provided to answer the question "how can I do X Y Z..?"

These scenario elements can be integrated into your scenarios using copy-paste except where elements have been created with a Create action. For those elements it will be necessary to copy the parent element instead.

TBC: Add a link to the library or directions how to get the files

== Demo_ISAT_ADO_Control.scn ==

This scenario demonstrates how to control an ADO:

• ADO set dial > forced velocity = 0 to keep ADO stationary.

• Release the forced velocity, assign a maintain gap.

• Release the maintain gap, assign a target velocity.

See also:
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn ==
This scenario demonstrates how to vary the velocity of an ADO using a Sum of Sines expression:

*Uses a forced velocity action;
*Try to maintain a constant speed at 30 mph;
*Notice how the speed of the ADO changes during the drive.

Note:
There is also a forced velocity Sin function available with 4 parameters

See Also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Oncoming_Incursion.scn ==
This scenario demonstrates the use of a forced lane offset to cause an oncoming ADO to veer into the driver’s lane:

*Additional ambient traffic is included to provide a normal driving environment;
*A following ADO will encourage slow drivers to travel the speed limit;
*Because we do not want to rely on the driver travelling at the right speed, we match the event ADO velocity to the driver to ensure the event happens as planned.

See Also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Passing_Maneuvers.scn ==
This scenario demonstrates how to implement an ADO passing maneuver on 4 lane and 2 lane roads:

*4 lane roads can use either Set Dial > ADO > Lane Change OR Set_Button > ADO > Lane Change;
*'''Lane change actions are not supported on 2 lane roads;
- Use a lane offset to produce something similar to a passing maneuver

See also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]

== Demo_ISAT_ADO_Random.scn ==

This scenario demonstrates how to use the Rand() function to assign a randomized gap to an ADO:

*Typical gap assignments are fixed/constant;
*Use of a randomized value introduces some inconsistency to the ADO position, which is organic and more realistic.
*Requires the use of variables and expressions.
*Saves the calculated randomizations to the DAQ for validation (review in ISAT).

See also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Relative_Create.scn ==

This scenario demonstrates how to use the Relative Create flag for ADOs.

'''Note:
'''Relative Create works only with negative values.

Used to create traffic behind the external driver independent of the location where the ADOs are initially placed.

See Also:

Demo_ISAT_ADO_Traffic_1.scn

== Demo_ISAT_ADO_Traffic_1.scn ==
This scenario demonstrates how to create traffic in a scenario:

*Create ADOs or copy/paste to locations within the drive;
*Create ADOs with a Creation Radius (they get created as the External Driver drives the route);
*Create ADOs with a trigger Create action;
*Generate traffic with a Traffic Source;
*Generate traffic with the Traffic Manager (or change TM sets).

Each method has advantages and disadvantages.

See Also:

: [[#Demo_ISAT_ADO_Relative_Create.scn|Demo_ISAT_ADO_Relative_Create.scn]]

== Demo_ISAT_ADO_TTA_LVPO.scn ==

This scenario demonstrates the use of Time to Arrival trigger to create a crashpossible event:

*The scenario contains some distracting elements;
*The event ADO behavior is highly dependent on the speed of the XD.
- If the driver is going too fast it may cause the event ADO to disappear
*A time trigger with creation radius acts as a proximity trigger to end the drive, in case the driver steers out of the crash area.

See Also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]

== Demo_ISAT_Alert_Slow_Moving_Object.scn ==

This scenario demonstrates how to implement a proximity alert to warn the driver of a slow moving vehicle ahead:

*Speed monitor to ensure the driver is travelling at a velocity where the event can happen
*Alarm triggers when proximity threshold is achieved

Because there is no good way to tell in advance where the event happens, the end of drive happens following the alert.

== Demo_ISAT_Avoid_Obstacle.scn ==

This demo scenario demonstrates a collision avoidance event using ambient traffic and a DDO obstacle:

*The event requires some setup to position the event vehicles
*The obstacle is a DDO (desk) contained within a van model that has operable rear doors which swing open
*The DDO transitions from a coupled object to a free motion object

== Demo_ISAT_Create_Elements.scn ==

This scenario demonstrates how to create scenario elements during a drive with the Create Element action.

*Remember all triggers share the same actions; thus, any trigger may contain a create action.
*Only 1 create action is permitted per trigger.

== Demo_ISAT_Data_Measures_Default_Measures.scn ==

This scenario demonstrates how to use the miniSim Default Measures in a scenario to produce a valid report for the drive:

*Must follow the write to cell procedure for events:
:#initialize event status and event number to zero at scenario start
:#change SCC_EventStatus from 0 to 1 for the event, and close to 0 after the event
:#change SCC_EventNumber throughout the drive (incremental count starting with 1, 2, 3, etc.)
*Produces a report.txt for each drive
*The drive report.txt for each drive is located in the DAQ folder location.

'''Note: if proper write to cell steps aren’t followed, all measures will be empty in the report.

== Demo_ISAT_Data_Measures_Logstreams.scn ==

This scenario demonstrates the use of Log Streams for documenting significant locations or events in your DAQ file.

*Best practice: initialize all Logstreams to some value at the start.
*Events may be numbered, or subdivided using the same logstream. This demo uses LogStream 1.

*The scenario author and data reduction scientist must agree on what measures are important to encode.

== Demo_ISAT_DDOs.scn ==

This scenario demonstrates different ways to use DDOs and DDDOs. Both types typically begin moving when the scenario starts, unless you assign a creation radius or control the DDO speed.

1. DDO: simple path follower.

2. DDDO (dependent path follower): includes a target path node and a target point. The
DDDO movement is constrained so when the specified object is at the target point, the DDDO will be at the target path node irrespective of the speed assigned to each node.
DDO and DDDOs can be pedestrians, animals or vehicles.

== Demo_ISAT_Display_Screen_Text.scn ==

This scenario demonstrates how to display text messages to the screen.

Text font, color and locations are specified at: NadsMiniSim_x.x\bin.x64\config\scenario_text.xml

'''*Be sure to maintain a backup if you edit this file!

See Also:
Demo_ISAT_Monitor_Driver_Speed.scn
Demo_ISAT_Show_Driver_Speed.scn

==Demo_ISAT_ENV_Dynamic_Fog.scn ==

This scenario demonstrates how to gradually apply fog and the difference between fog and visibility. The usual method of adding weather effects to a scenario is by defining a region of influence which means the effect is applied abruptly to the scene at the region boundaries (on/off).

*Fog and Visibility are Weather Effects
- Insert >> Environment Conditions
*Fog density is managed with 3 variables:
::#FogDistance
::#MaximumFog
::#FogDensity
*An example of reduced Visibility is included near the end of this drive to show how that setting is different from fog.

== Demo_ISAT_time_of_day.scn==

This scenario demonstrates how to change the time of day:

*Variables are used to track day-night cycles
*Time settings (Hour) were chosen arbitrarily
::'''Small time differences will not affect environment; ie. 07:10 – 07:30
*A parked F150 ADO in the scenario has auto-headlights enabled

'''NOTE: Headlight control from scenario requires changes to the miniSim hardware.xml configuration file – they do not automatically turn on at night

==Demo_ISAT_Exit_Simulation_on_Collision.scn ==

This scenario demonstrates how to terminate simulation if a collision happens during a drive. Collisions may occur with ADOs, DDOs, DDDOs and static objects that are present in the scene.

'''Note:
It is possible to configure miniSim or edit the scenario object list file (SOL2.txt) to disable collisions either globally or for specific objects. In that event this scenario will not terminate due to a collision.

==Demo_ISAT_Exit_Follow_Trigger_Create.scn ==

This scenario demonstrates use of the Follow Trigger:

*The follow trigger can activate between any two dynamic objects;
*Most commonly uses the XD for one of the two objects (leader or follower);
*Trigger instigator (predicate) can be either;
*The follow trigger action stack is processed when the trigger conditions have been met;
*When the actions are executed an oncoming Ambulance ADO is created.

== Demo_ISAT_Get_ObjTTC.scn==

This scenario demonstrates how to get a Time To Collision for dynamic and stationary objects (DDOs and ADOs):

*Any time delays in the action stack collecting data and reporting it will create a variance between what you measure in ISAT and what gets reported in the DAQ;
*Cells and variables are used to get the information for TTC and distance;
*Variables are written to SCC_Custom1 – 3 for distance, TTC and the raw distance value reported by GetObjDistPow2;
*3 events are shown to illustrate re-use of the same variables throughout for the target object:
::#DDO dynamic
::#DDO stationary
::#ADO stationary
*Logstreams are used for event numbering and distances to each object;
*If you re-use the same object name, you must remove the previous object – only 1 should be present in the simulation at any time.

'''NOTE:
Static objects cannot be created in realtime with the Create Element action, but they can be created as DDOs. They default to their first visual option; change with a set switch action.

==Demo_ISAT_Lane_Context_Actions.scn ==
This scenario demonstrates how to limit actions to a specific lane.

*Lane filter can only be used with roadpad triggers.
*Useful for situational cases: if the driver is in the correct lane, then they will not receive alert. If the driver is in the wrong lane, then they will.
*Also useful for ADO control at the lane level.

See also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]

==Demo_ISAT_Loop_Management_Traffic.scn ==

This scenario demonstrates how to configure a scenario where it is necessary to drive multiple loops:

*Increment a counter at the location the loop counts increase;
::Each time through the loop a unique action happens
::Increment and decrement operators are not expressions!
*Expression triggers fire on loops (one per loop);
*Can create more than ADOs.

==Demo_ISAT_Monitor_Driver_Speed.scn ==

This scenario demonstrates how to monitor driver velocity. Triggers are configured to monitor driving too slowly (under speed) and driving too fast. The threshold between under and over speed is intentionally difficult to maintain – the goal is to achieve a few alerts of either kind during the drive:

*Variable sets are used for under, over speed cases:
::a timer that increments a variable for each;
::an additional conditional (variable) so there is no alert at scenario start, while the driver is getting up to operating speed.

==Demo_ISAT_Play_Audio.scn ==

This scenario demonstrates how to play audio messages on miniSim using the write to cell >> SCC_Audio_Trigger action.
A short delay after the write to cell action is recommended.

'''Note:
'''Recommended practice requires a second write to cell action to ‘clear’ the previous audio message.

Playing two write to cell >> SCC_Audio_Trigger actions back to back with no delay, and no ‘clear’ likely results in a single audio message. For long messages, use the length of the message as a delay to avoid over-writing the message being played with any subsequent messages.

See also:

[https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#How_to_Use_Audio_in_your_Scenario| How to Use Audio in your Scenario]

==Demo_ISAT_Right_Incursion.scn ==

This scenario demonstrates how to present a crash possible event using a right-side incursion:

• Ambient traffic and features are used during the drive; • The event is coupled with an oncoming vehicle distraction;
• The event is masked by features in the scene.

==Demo_ISAT_Set_Switch.scn ==

This scenario demonstrates how to change objects during a simulation with a Set Switch action (static object, DDO, ADO objects).

• The set switch action requires the model switch name;
• Switches for all models are listed in the file NadsMiniSim_x.x\bin.x64\ModelList.txt

==Demo_ISAT_Stop_Drive.scn ==

This scenario demonstrates how to terminate a simulation from the scenario:

• A roadpad trigger tells the driver it is time to stop and shift into park, and creates an Expression trigger to:
- monitor the transmission gear,
- terminate the simulation if the driver shifts into Park.
A Roadpad trigger acts as a backup that ends the drive if the XD doesn’t stop.

==Demo_ISAT_Show_Driver_Speed.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action.

* A time trigger is configured to monitor conditions; in this case, the external driver’s speed.
* The monitoring trigger is created by a roadpad trigger to ensure the driver is moving; therefore driver velocity is not zero.

* The monitoring trigger fires repeatedly during the drive.
* A variable is set to the value of a cell containing the driver velocity;
* That value is displayed on screen.

See Also:
:Demo_ISAT_Display_Screen_Text.scn
:Demo_ISAT_Monitor_Driver_Speed.scn

==Demo_ISAT_Track_Button_Press.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action:

• A time trigger This demo scenario uses expression triggers to detect button presses (turn signal activation).
• Variables are used to track which signal was activated (left vs. right) and demo progress.

'''Note:
'''The values used in the scenario may be site-specific; if your miniSim does not produce the values used, this scenario may fail.

To determine the correct values for your miniSim, drive any scenario and press the left, then the right turn signals and review this drive DAQ in ISAT. The relevant cell is CIS_Turn_Signal.

==Demo_ISAT_Traffic_Light.scn ==

This scenario demonstrates the use of a Traffic Light Trigger:

*A traffic light trigger activates at a specified signal state;
*Relies on a traffic light action to set the signal to a specified state;
*That state must already exist in the traffic signal timing table configuration for the intersection
::dbl-click on the traffic signal to open the signal timing table

*A more robust method would use a time to arrival (TTA) trigger that can accommodate different XD velocities or driving styles (conservative vs. aggressive, slow vs. fast) instead of the roadpad and delays used in this demo.

==Demo_ISAT_Virtual_Objects.scn ==

This scenario demonstrates how to display and control virtual objects during a drive. Virtual objects render to screen space on top of everything on display; they do not typically occupy 3d space within the scene.

One possible application for virtual objects is to use them as a custom heads up display (HUD) or alert system within the scenario.

By default virtual objects initialize to state 0 (off/disabled) at scenario start.

'''Note:
'''Currently only Render Type = Overlay and Main Screen are supported.

==Demo_ISAT_Yellow_Light_Dilemma.scn ==

This scenario demonstrates how to create a Yellow Light dilemma at an intersection.

#There must be a working signal state table;
#The traffic signal is controlled by a time to arrival (TTA) trigger;
#If the XD decides to stop, a roadpad trigger created by (2) will reset the signal to green so the XD can continue the drive;
#A roadpad trigger terminates the drive after the intersection.

ISAT Demonstration Scenarios

2023-09-15T15:32:00Z

Shawn Allen: /* Demo_ISAT_Play_Audio.scn add hyperlink*/

== About the ISAT Demonstration Scenarios ==

Making something happen during a simulation in a repeatable and consistent fashion for different driving styles is the essence of scenario authoring. Every thing that happens must be coordinated to some degree with the External Driver (XD). For repeatability, it is also necessary to consider how different driving styles (aggressive vs. conservative) impact how the scenario unfolds for each.

These demonstration scenarios were created to facilitate learning how to use ISAT and do scenario actions. Each scenario demonstrates a key concept or element and may contain additional elements to support the main concept. For example, all scenarios contain an introduction to the scenario for the XD and a termination trigger that will stop the simulation.

'''These scenarios are not intended for use as completed data collection ready scenarios. They are provided to answer the question "how can I do X Y Z..?"

These scenario elements can be integrated into your scenarios using copy-paste except where elements have been created with a Create action. For those elements it will be necessary to copy the parent element instead.

TBC: Add a link to the library or directions how to get the files

== Demo_ISAT_ADO_Control.scn ==

This scenario demonstrates how to control an ADO:

• ADO set dial > forced velocity = 0 to keep ADO stationary.

• Release the forced velocity, assign a maintain gap.

• Release the maintain gap, assign a target velocity.

See also:
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn ==
This scenario demonstrates how to vary the velocity of an ADO using a Sum of Sines expression:

*Uses a forced velocity action;
*Try to maintain a constant speed at 30 mph;
*Notice how the speed of the ADO changes during the drive.

Note:
There is also a forced velocity Sin function available with 4 parameters

See Also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Oncoming_Incursion.scn ==
This scenario demonstrates the use of a forced lane offset to cause an oncoming ADO to veer into the driver’s lane:

*Additional ambient traffic is included to provide a normal driving environment;
*A following ADO will encourage slow drivers to travel the speed limit;
*Because we do not want to rely on the driver travelling at the right speed, we match the event ADO velocity to the driver to ensure the event happens as planned.

See Also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Passing_Maneuvers.scn ==
This scenario demonstrates how to implement an ADO passing maneuver on 4 lane and 2 lane roads:

*4 lane roads can use either Set Dial > ADO > Lane Change OR Set_Button > ADO > Lane Change;
*'''Lane change actions are not supported on 2 lane roads;
- Use a lane offset to produce something similar to a passing maneuver

See also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]

== Demo_ISAT_ADO_Random.scn ==

This scenario demonstrates how to use the Rand() function to assign a randomized gap to an ADO:

*Typical gap assignments are fixed/constant;
*Use of a randomized value introduces some inconsistency to the ADO position, which is organic and more realistic.
*Requires the use of variables and expressions.
*Saves the calculated randomizations to the DAQ for validation (review in ISAT).

See also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Relative_Create.scn ==

This scenario demonstrates how to use the Relative Create flag for ADOs.

'''Note:
'''Relative Create works only with negative values.

Used to create traffic behind the external driver independent of the location where the ADOs are initially placed.

See Also:

Demo_ISAT_ADO_Traffic_1.scn

== Demo_ISAT_ADO_Traffic_1.scn ==
This scenario demonstrates how to create traffic in a scenario:

*Create ADOs or copy/paste to locations within the drive;
*Create ADOs with a Creation Radius (they get created as the External Driver drives the route);
*Create ADOs with a trigger Create action;
*Generate traffic with a Traffic Source;
*Generate traffic with the Traffic Manager (or change TM sets).

Each method has advantages and disadvantages.

See Also:

: [[#Demo_ISAT_ADO_Relative_Create.scn|Demo_ISAT_ADO_Relative_Create.scn]]

== Demo_ISAT_ADO_TTA_LVPO.scn ==

This scenario demonstrates the use of Time to Arrival trigger to create a crashpossible event:

*The scenario contains some distracting elements;
*The event ADO behavior is highly dependent on the speed of the XD.
- If the driver is going too fast it may cause the event ADO to disappear
*A time trigger with creation radius acts as a proximity trigger to end the drive, in case the driver steers out of the crash area.

See Also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]

== Demo_ISAT_Alert_Slow_Moving_Object.scn ==

This scenario demonstrates how to implement a proximity alert to warn the driver of a slow moving vehicle ahead:

*Speed monitor to ensure the driver is travelling at a velocity where the event can happen
*Alarm triggers when proximity threshold is achieved

Because there is no good way to tell in advance where the event happens, the end of drive happens following the alert.

== Demo_ISAT_Avoid_Obstacle.scn ==

This demo scenario demonstrates a collision avoidance event using ambient traffic and a DDO obstacle:

*The event requires some setup to position the event vehicles
*The obstacle is a DDO (desk) contained within a van model that has operable rear doors which swing open
*The DDO transitions from a coupled object to a free motion object

== Demo_ISAT_Create_Elements.scn ==

This scenario demonstrates how to create scenario elements during a drive with the Create Element action.

*Remember all triggers share the same actions; thus, any trigger may contain a create action.
*Only 1 create action is permitted per trigger.

== Demo_ISAT_Data_Measures_Default_Measures.scn ==

This scenario demonstrates how to use the miniSim Default Measures in a scenario to produce a valid report for the drive:

*Must follow the write to cell procedure for events:
:#initialize event status and event number to zero at scenario start
:#change SCC_EventStatus from 0 to 1 for the event, and close to 0 after the event
:#change SCC_EventNumber throughout the drive (incremental count starting with 1, 2, 3, etc.)
*Produces a report.txt for each drive
*The drive report.txt for each drive is located in the DAQ folder location.

'''Note: if proper write to cell steps aren’t followed, all measures will be empty in the report.

== Demo_ISAT_Data_Measures_Logstreams.scn ==

This scenario demonstrates the use of Log Streams for documenting significant locations or events in your DAQ file.

*Best practice: initialize all Logstreams to some value at the start.
*Events may be numbered, or subdivided using the same logstream. This demo uses LogStream 1.

*The scenario author and data reduction scientist must agree on what measures are important to encode.

== Demo_ISAT_DDOs.scn ==

This scenario demonstrates different ways to use DDOs and DDDOs. Both types typically begin moving when the scenario starts, unless you assign a creation radius or control the DDO speed.

1. DDO: simple path follower.

2. DDDO (dependent path follower): includes a target path node and a target point. The
DDDO movement is constrained so when the specified object is at the target point, the DDDO will be at the target path node irrespective of the speed assigned to each node.
DDO and DDDOs can be pedestrians, animals or vehicles.

== Demo_ISAT_Display_Screen_Text.scn ==

This scenario demonstrates how to display text messages to the screen.

Text font, color and locations are specified at: NadsMiniSim_x.x\bin.x64\config\scenario_text.xml

'''*Be sure to maintain a backup if you edit this file!

See Also:
Demo_ISAT_Monitor_Driver_Speed.scn
Demo_ISAT_Show_Driver_Speed.scn

==Demo_ISAT_ENV_Dynamic_Fog.scn ==

This scenario demonstrates how to gradually apply fog and the difference between fog and visibility. The usual method of adding weather effects to a scenario is by defining a region of influence which means the effect is applied abruptly to the scene at the region boundaries (on/off).

*Fog and Visibility are Weather Effects
- Insert >> Environment Conditions
*Fog density is managed with 3 variables:
::#FogDistance
::#MaximumFog
::#FogDensity
*An example of reduced Visibility is included near the end of this drive to show how that setting is different from fog.

== Demo_ISAT_time_of_day.scn==

This scenario demonstrates how to change the time of day:

*Variables are used to track day-night cycles
*Time settings (Hour) were chosen arbitrarily
::'''Small time differences will not affect environment; ie. 07:10 – 07:30
*A parked F150 ADO in the scenario has auto-headlights enabled

'''NOTE: Headlight control from scenario requires changes to the miniSim hardware.xml configuration file – they do not automatically turn on at night

==Demo_ISAT_Exit_Simulation_on_Collision.scn ==

This scenario demonstrates how to terminate simulation if a collision happens during a drive. Collisions may occur with ADOs, DDOs, DDDOs and static objects that are present in the scene.

'''Note:
It is possible to configure miniSim or edit the scenario object list file (SOL2.txt) to disable collisions either globally or for specific objects. In that event this scenario will not terminate due to a collision.

==Demo_ISAT_Exit_Follow_Trigger_Create.scn ==

This scenario demonstrates use of the Follow Trigger:

*The follow trigger can activate between any two dynamic objects;
*Most commonly uses the XD for one of the two objects (leader or follower);
*Trigger instigator (predicate) can be either;
*The follow trigger action stack is processed when the trigger conditions have been met;
*When the actions are executed an oncoming Ambulance ADO is created.

== Demo_ISAT_Get_ObjTTC.scn==

This scenario demonstrates how to get a Time To Collision for dynamic and stationary objects (DDOs and ADOs):

*Any time delays in the action stack collecting data and reporting it will create a variance between what you measure in ISAT and what gets reported in the DAQ;
*Cells and variables are used to get the information for TTC and distance;
*Variables are written to SCC_Custom1 – 3 for distance, TTC and the raw distance value reported by GetObjDistPow2;
*3 events are shown to illustrate re-use of the same variables throughout for the target object:
::#DDO dynamic
::#DDO stationary
::#ADO stationary
*Logstreams are used for event numbering and distances to each object;
*If you re-use the same object name, you must remove the previous object – only 1 should be present in the simulation at any time.

'''NOTE:
Static objects cannot be created in realtime with the Create Element action, but they can be created as DDOs. They default to their first visual option; change with a set switch action.

==Demo_ISAT_Lane_Context_Actions.scn ==
This scenario demonstrates how to limit actions to a specific lane.

*Lane filter can only be used with roadpad triggers.
*Useful for situational cases: if the driver is in the correct lane, then they will not receive alert. If the driver is in the wrong lane, then they will.
*Also useful for ADO control at the lane level.

See also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]

==Demo_ISAT_Loop_Management_Traffic.scn ==

This scenario demonstrates how to configure a scenario where it is necessary to drive multiple loops:

*Increment a counter at the location the loop counts increase;
::Each time through the loop a unique action happens
::Increment and decrement operators are not expressions!
*Expression triggers fire on loops (one per loop);
*Can create more than ADOs.

==Demo_ISAT_Monitor_Driver_Speed.scn ==

This scenario demonstrates how to monitor driver velocity. Triggers are configured to monitor driving too slowly (under speed) and driving too fast. The threshold between under and over speed is intentionally difficult to maintain – the goal is to achieve a few alerts of either kind during the drive:

*Variable sets are used for under, over speed cases:
::a timer that increments a variable for each;
::an additional conditional (variable) so there is no alert at scenario start, while the driver is getting up to operating speed.

==Demo_ISAT_Play_Audio.scn ==

This scenario demonstrates how to play audio messages on miniSim using the write to cell >> SCC_Audio_Trigger action.
A short delay after the write to cell action is recommended.

'''Note:
'''Recommended practice requires a second write to cell action to ‘clear’ the previous audio message.

Playing two write to cell >> SCC_Audio_Trigger actions back to back with no delay, and no ‘clear’ likely results in a single audio message. For long messages, use the length of the message as a delay to avoid over-writing the message being played with any subsequent messages.

See also:

[[https://www.nads-sc.uiowa.edu/minisim/wiki/index.php?title=ISAT_User_Guide_Table_of_Contents#How_to_Use_Audio_in_your_Scenario|How_to_Use_Audio_in_your_Scenario]]

==Demo_ISAT_Right_Incursion.scn ==

This scenario demonstrates how to present a crash possible event using a right-side incursion:

• Ambient traffic and features are used during the drive; • The event is coupled with an oncoming vehicle distraction;
• The event is masked by features in the scene.

==Demo_ISAT_Set_Switch.scn ==

This scenario demonstrates how to change objects during a simulation with a Set Switch action (static object, DDO, ADO objects).

• The set switch action requires the model switch name;
• Switches for all models are listed in the file NadsMiniSim_x.x\bin.x64\ModelList.txt

==Demo_ISAT_Stop_Drive.scn ==

This scenario demonstrates how to terminate a simulation from the scenario:

• A roadpad trigger tells the driver it is time to stop and shift into park, and creates an Expression trigger to:
- monitor the transmission gear,
- terminate the simulation if the driver shifts into Park.
A Roadpad trigger acts as a backup that ends the drive if the XD doesn’t stop.

==Demo_ISAT_Show_Driver_Speed.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action.

* A time trigger is configured to monitor conditions; in this case, the external driver’s speed.
* The monitoring trigger is created by a roadpad trigger to ensure the driver is moving; therefore driver velocity is not zero.

* The monitoring trigger fires repeatedly during the drive.
* A variable is set to the value of a cell containing the driver velocity;
* That value is displayed on screen.

See Also:
:Demo_ISAT_Display_Screen_Text.scn
:Demo_ISAT_Monitor_Driver_Speed.scn

==Demo_ISAT_Track_Button_Press.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action:

• A time trigger This demo scenario uses expression triggers to detect button presses (turn signal activation).
• Variables are used to track which signal was activated (left vs. right) and demo progress.

'''Note:
'''The values used in the scenario may be site-specific; if your miniSim does not produce the values used, this scenario may fail.

To determine the correct values for your miniSim, drive any scenario and press the left, then the right turn signals and review this drive DAQ in ISAT. The relevant cell is CIS_Turn_Signal.

==Demo_ISAT_Traffic_Light.scn ==

This scenario demonstrates the use of a Traffic Light Trigger:

*A traffic light trigger activates at a specified signal state;
*Relies on a traffic light action to set the signal to a specified state;
*That state must already exist in the traffic signal timing table configuration for the intersection
::dbl-click on the traffic signal to open the signal timing table

*A more robust method would use a time to arrival (TTA) trigger that can accommodate different XD velocities or driving styles (conservative vs. aggressive, slow vs. fast) instead of the roadpad and delays used in this demo.

==Demo_ISAT_Virtual_Objects.scn ==

This scenario demonstrates how to display and control virtual objects during a drive. Virtual objects render to screen space on top of everything on display; they do not typically occupy 3d space within the scene.

One possible application for virtual objects is to use them as a custom heads up display (HUD) or alert system within the scenario.

By default virtual objects initialize to state 0 (off/disabled) at scenario start.

'''Note:
'''Currently only Render Type = Overlay and Main Screen are supported.

==Demo_ISAT_Yellow_Light_Dilemma.scn ==

This scenario demonstrates how to create a Yellow Light dilemma at an intersection.

#There must be a working signal state table;
#The traffic signal is controlled by a time to arrival (TTA) trigger;
#If the XD decides to stop, a roadpad trigger created by (2) will reset the signal to green so the XD can continue the drive;
#A roadpad trigger terminates the drive after the intersection.

ISAT Demonstration Scenarios

2023-09-15T15:29:02Z

Shawn Allen: /* Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn */

== About the ISAT Demonstration Scenarios ==

Making something happen during a simulation in a repeatable and consistent fashion for different driving styles is the essence of scenario authoring. Every thing that happens must be coordinated to some degree with the External Driver (XD). For repeatability, it is also necessary to consider how different driving styles (aggressive vs. conservative) impact how the scenario unfolds for each.

These demonstration scenarios were created to facilitate learning how to use ISAT and do scenario actions. Each scenario demonstrates a key concept or element and may contain additional elements to support the main concept. For example, all scenarios contain an introduction to the scenario for the XD and a termination trigger that will stop the simulation.

'''These scenarios are not intended for use as completed data collection ready scenarios. They are provided to answer the question "how can I do X Y Z..?"

These scenario elements can be integrated into your scenarios using copy-paste except where elements have been created with a Create action. For those elements it will be necessary to copy the parent element instead.

TBC: Add a link to the library or directions how to get the files

== Demo_ISAT_ADO_Control.scn ==

This scenario demonstrates how to control an ADO:

• ADO set dial > forced velocity = 0 to keep ADO stationary.

• Release the forced velocity, assign a maintain gap.

• Release the maintain gap, assign a target velocity.

See also:
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn ==
This scenario demonstrates how to vary the velocity of an ADO using a Sum of Sines expression:

*Uses a forced velocity action;
*Try to maintain a constant speed at 30 mph;
*Notice how the speed of the ADO changes during the drive.

Note:
There is also a forced velocity Sin function available with 4 parameters

See Also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Oncoming_Incursion.scn ==
This scenario demonstrates the use of a forced lane offset to cause an oncoming ADO to veer into the driver’s lane:

*Additional ambient traffic is included to provide a normal driving environment;
*A following ADO will encourage slow drivers to travel the speed limit;
*Because we do not want to rely on the driver travelling at the right speed, we match the event ADO velocity to the driver to ensure the event happens as planned.

See Also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Passing_Maneuvers.scn ==
This scenario demonstrates how to implement an ADO passing maneuver on 4 lane and 2 lane roads:

*4 lane roads can use either Set Dial > ADO > Lane Change OR Set_Button > ADO > Lane Change;
*'''Lane change actions are not supported on 2 lane roads;
- Use a lane offset to produce something similar to a passing maneuver

See also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]

== Demo_ISAT_ADO_Random.scn ==

This scenario demonstrates how to use the Rand() function to assign a randomized gap to an ADO:

*Typical gap assignments are fixed/constant;
*Use of a randomized value introduces some inconsistency to the ADO position, which is organic and more realistic.
*Requires the use of variables and expressions.
*Saves the calculated randomizations to the DAQ for validation (review in ISAT).

See also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Relative_Create.scn ==

This scenario demonstrates how to use the Relative Create flag for ADOs.

'''Note:
'''Relative Create works only with negative values.

Used to create traffic behind the external driver independent of the location where the ADOs are initially placed.

See Also:

Demo_ISAT_ADO_Traffic_1.scn

== Demo_ISAT_ADO_Traffic_1.scn ==
This scenario demonstrates how to create traffic in a scenario:

*Create ADOs or copy/paste to locations within the drive;
*Create ADOs with a Creation Radius (they get created as the External Driver drives the route);
*Create ADOs with a trigger Create action;
*Generate traffic with a Traffic Source;
*Generate traffic with the Traffic Manager (or change TM sets).

Each method has advantages and disadvantages.

See Also:

: [[#Demo_ISAT_ADO_Relative_Create.scn|Demo_ISAT_ADO_Relative_Create.scn]]

== Demo_ISAT_ADO_TTA_LVPO.scn ==

This scenario demonstrates the use of Time to Arrival trigger to create a crashpossible event:

*The scenario contains some distracting elements;
*The event ADO behavior is highly dependent on the speed of the XD.
- If the driver is going too fast it may cause the event ADO to disappear
*A time trigger with creation radius acts as a proximity trigger to end the drive, in case the driver steers out of the crash area.

See Also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]

== Demo_ISAT_Alert_Slow_Moving_Object.scn ==

This scenario demonstrates how to implement a proximity alert to warn the driver of a slow moving vehicle ahead:

*Speed monitor to ensure the driver is travelling at a velocity where the event can happen
*Alarm triggers when proximity threshold is achieved

Because there is no good way to tell in advance where the event happens, the end of drive happens following the alert.

== Demo_ISAT_Avoid_Obstacle.scn ==

This demo scenario demonstrates a collision avoidance event using ambient traffic and a DDO obstacle:

*The event requires some setup to position the event vehicles
*The obstacle is a DDO (desk) contained within a van model that has operable rear doors which swing open
*The DDO transitions from a coupled object to a free motion object

== Demo_ISAT_Create_Elements.scn ==

This scenario demonstrates how to create scenario elements during a drive with the Create Element action.

*Remember all triggers share the same actions; thus, any trigger may contain a create action.
*Only 1 create action is permitted per trigger.

== Demo_ISAT_Data_Measures_Default_Measures.scn ==

This scenario demonstrates how to use the miniSim Default Measures in a scenario to produce a valid report for the drive:

*Must follow the write to cell procedure for events:
:#initialize event status and event number to zero at scenario start
:#change SCC_EventStatus from 0 to 1 for the event, and close to 0 after the event
:#change SCC_EventNumber throughout the drive (incremental count starting with 1, 2, 3, etc.)
*Produces a report.txt for each drive
*The drive report.txt for each drive is located in the DAQ folder location.

'''Note: if proper write to cell steps aren’t followed, all measures will be empty in the report.

== Demo_ISAT_Data_Measures_Logstreams.scn ==

This scenario demonstrates the use of Log Streams for documenting significant locations or events in your DAQ file.

*Best practice: initialize all Logstreams to some value at the start.
*Events may be numbered, or subdivided using the same logstream. This demo uses LogStream 1.

*The scenario author and data reduction scientist must agree on what measures are important to encode.

== Demo_ISAT_DDOs.scn ==

This scenario demonstrates different ways to use DDOs and DDDOs. Both types typically begin moving when the scenario starts, unless you assign a creation radius or control the DDO speed.

1. DDO: simple path follower.

2. DDDO (dependent path follower): includes a target path node and a target point. The
DDDO movement is constrained so when the specified object is at the target point, the DDDO will be at the target path node irrespective of the speed assigned to each node.
DDO and DDDOs can be pedestrians, animals or vehicles.

== Demo_ISAT_Display_Screen_Text.scn ==

This scenario demonstrates how to display text messages to the screen.

Text font, color and locations are specified at: NadsMiniSim_x.x\bin.x64\config\scenario_text.xml

'''*Be sure to maintain a backup if you edit this file!

See Also:
Demo_ISAT_Monitor_Driver_Speed.scn
Demo_ISAT_Show_Driver_Speed.scn

==Demo_ISAT_ENV_Dynamic_Fog.scn ==

This scenario demonstrates how to gradually apply fog and the difference between fog and visibility. The usual method of adding weather effects to a scenario is by defining a region of influence which means the effect is applied abruptly to the scene at the region boundaries (on/off).

*Fog and Visibility are Weather Effects
- Insert >> Environment Conditions
*Fog density is managed with 3 variables:
::#FogDistance
::#MaximumFog
::#FogDensity
*An example of reduced Visibility is included near the end of this drive to show how that setting is different from fog.

== Demo_ISAT_time_of_day.scn==

This scenario demonstrates how to change the time of day:

*Variables are used to track day-night cycles
*Time settings (Hour) were chosen arbitrarily
::'''Small time differences will not affect environment; ie. 07:10 – 07:30
*A parked F150 ADO in the scenario has auto-headlights enabled

'''NOTE: Headlight control from scenario requires changes to the miniSim hardware.xml configuration file – they do not automatically turn on at night

==Demo_ISAT_Exit_Simulation_on_Collision.scn ==

This scenario demonstrates how to terminate simulation if a collision happens during a drive. Collisions may occur with ADOs, DDOs, DDDOs and static objects that are present in the scene.

'''Note:
It is possible to configure miniSim or edit the scenario object list file (SOL2.txt) to disable collisions either globally or for specific objects. In that event this scenario will not terminate due to a collision.

==Demo_ISAT_Exit_Follow_Trigger_Create.scn ==

This scenario demonstrates use of the Follow Trigger:

*The follow trigger can activate between any two dynamic objects;
*Most commonly uses the XD for one of the two objects (leader or follower);
*Trigger instigator (predicate) can be either;
*The follow trigger action stack is processed when the trigger conditions have been met;
*When the actions are executed an oncoming Ambulance ADO is created.

== Demo_ISAT_Get_ObjTTC.scn==

This scenario demonstrates how to get a Time To Collision for dynamic and stationary objects (DDOs and ADOs):

*Any time delays in the action stack collecting data and reporting it will create a variance between what you measure in ISAT and what gets reported in the DAQ;
*Cells and variables are used to get the information for TTC and distance;
*Variables are written to SCC_Custom1 – 3 for distance, TTC and the raw distance value reported by GetObjDistPow2;
*3 events are shown to illustrate re-use of the same variables throughout for the target object:
::#DDO dynamic
::#DDO stationary
::#ADO stationary
*Logstreams are used for event numbering and distances to each object;
*If you re-use the same object name, you must remove the previous object – only 1 should be present in the simulation at any time.

'''NOTE:
Static objects cannot be created in realtime with the Create Element action, but they can be created as DDOs. They default to their first visual option; change with a set switch action.

==Demo_ISAT_Lane_Context_Actions.scn ==
This scenario demonstrates how to limit actions to a specific lane.

*Lane filter can only be used with roadpad triggers.
*Useful for situational cases: if the driver is in the correct lane, then they will not receive alert. If the driver is in the wrong lane, then they will.
*Also useful for ADO control at the lane level.

See also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]

==Demo_ISAT_Loop_Management_Traffic.scn ==

This scenario demonstrates how to configure a scenario where it is necessary to drive multiple loops:

*Increment a counter at the location the loop counts increase;
::Each time through the loop a unique action happens
::Increment and decrement operators are not expressions!
*Expression triggers fire on loops (one per loop);
*Can create more than ADOs.

==Demo_ISAT_Monitor_Driver_Speed.scn ==

This scenario demonstrates how to monitor driver velocity. Triggers are configured to monitor driving too slowly (under speed) and driving too fast. The threshold between under and over speed is intentionally difficult to maintain – the goal is to achieve a few alerts of either kind during the drive:

*Variable sets are used for under, over speed cases:
::a timer that increments a variable for each;
::an additional conditional (variable) so there is no alert at scenario start, while the driver is getting up to operating speed.

==Demo_ISAT_Play_Audio.scn ==

This scenario demonstrates how to play audio messages on miniSim using the write to cell >> SCC_Audio_Trigger action.
A short delay after the write to cell action is recommended.

'''Note:
'''Recommended practice requires a second write to cell action to ‘clear’ the previous audio message.

Playing two write to cell >> SCC_Audio_Trigger actions back to back with no delay, and no ‘clear’ likely results in a single audio message. For long messages, use the length of the message as a delay to avoid over-writing the message being played with any subsequent messages.

See also:

[[How to Use Audio in your Scenario|How_to_Use_Audio_in_your_Scenario]]

==Demo_ISAT_Right_Incursion.scn ==

This scenario demonstrates how to present a crash possible event using a right-side incursion:

• Ambient traffic and features are used during the drive; • The event is coupled with an oncoming vehicle distraction;
• The event is masked by features in the scene.

==Demo_ISAT_Set_Switch.scn ==

This scenario demonstrates how to change objects during a simulation with a Set Switch action (static object, DDO, ADO objects).

• The set switch action requires the model switch name;
• Switches for all models are listed in the file NadsMiniSim_x.x\bin.x64\ModelList.txt

==Demo_ISAT_Stop_Drive.scn ==

This scenario demonstrates how to terminate a simulation from the scenario:

• A roadpad trigger tells the driver it is time to stop and shift into park, and creates an Expression trigger to:
- monitor the transmission gear,
- terminate the simulation if the driver shifts into Park.
A Roadpad trigger acts as a backup that ends the drive if the XD doesn’t stop.

==Demo_ISAT_Show_Driver_Speed.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action.

* A time trigger is configured to monitor conditions; in this case, the external driver’s speed.
* The monitoring trigger is created by a roadpad trigger to ensure the driver is moving; therefore driver velocity is not zero.

* The monitoring trigger fires repeatedly during the drive.
* A variable is set to the value of a cell containing the driver velocity;
* That value is displayed on screen.

See Also:
:Demo_ISAT_Display_Screen_Text.scn
:Demo_ISAT_Monitor_Driver_Speed.scn

==Demo_ISAT_Track_Button_Press.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action:

• A time trigger This demo scenario uses expression triggers to detect button presses (turn signal activation).
• Variables are used to track which signal was activated (left vs. right) and demo progress.

'''Note:
'''The values used in the scenario may be site-specific; if your miniSim does not produce the values used, this scenario may fail.

To determine the correct values for your miniSim, drive any scenario and press the left, then the right turn signals and review this drive DAQ in ISAT. The relevant cell is CIS_Turn_Signal.

==Demo_ISAT_Traffic_Light.scn ==

This scenario demonstrates the use of a Traffic Light Trigger:

*A traffic light trigger activates at a specified signal state;
*Relies on a traffic light action to set the signal to a specified state;
*That state must already exist in the traffic signal timing table configuration for the intersection
::dbl-click on the traffic signal to open the signal timing table

*A more robust method would use a time to arrival (TTA) trigger that can accommodate different XD velocities or driving styles (conservative vs. aggressive, slow vs. fast) instead of the roadpad and delays used in this demo.

==Demo_ISAT_Virtual_Objects.scn ==

This scenario demonstrates how to display and control virtual objects during a drive. Virtual objects render to screen space on top of everything on display; they do not typically occupy 3d space within the scene.

One possible application for virtual objects is to use them as a custom heads up display (HUD) or alert system within the scenario.

By default virtual objects initialize to state 0 (off/disabled) at scenario start.

'''Note:
'''Currently only Render Type = Overlay and Main Screen are supported.

==Demo_ISAT_Yellow_Light_Dilemma.scn ==

This scenario demonstrates how to create a Yellow Light dilemma at an intersection.

#There must be a working signal state table;
#The traffic signal is controlled by a time to arrival (TTA) trigger;
#If the XD decides to stop, a roadpad trigger created by (2) will reset the signal to green so the XD can continue the drive;
#A roadpad trigger terminates the drive after the intersection.

ISAT Demonstration Scenarios

2023-09-15T15:28:20Z

Shawn Allen: /* Demo_ISAT_ADO_Control.scn */

== About the ISAT Demonstration Scenarios ==

Making something happen during a simulation in a repeatable and consistent fashion for different driving styles is the essence of scenario authoring. Every thing that happens must be coordinated to some degree with the External Driver (XD). For repeatability, it is also necessary to consider how different driving styles (aggressive vs. conservative) impact how the scenario unfolds for each.

These demonstration scenarios were created to facilitate learning how to use ISAT and do scenario actions. Each scenario demonstrates a key concept or element and may contain additional elements to support the main concept. For example, all scenarios contain an introduction to the scenario for the XD and a termination trigger that will stop the simulation.

'''These scenarios are not intended for use as completed data collection ready scenarios. They are provided to answer the question "how can I do X Y Z..?"

These scenario elements can be integrated into your scenarios using copy-paste except where elements have been created with a Create action. For those elements it will be necessary to copy the parent element instead.

TBC: Add a link to the library or directions how to get the files

== Demo_ISAT_ADO_Control.scn ==

This scenario demonstrates how to control an ADO:

• ADO set dial > forced velocity = 0 to keep ADO stationary.

• Release the forced velocity, assign a maintain gap.

• Release the maintain gap, assign a target velocity.

See also:
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn ==
This scenario demonstrates how to vary the velocity of an ADO using a Sum of Sines expression:

*Uses a forced velocity action;
*Try to maintain a constant speed at 30 mph;
*Notice how the speed of the ADO changes during the drive.

Note:
There is also a forced velocity Sin function available with 4 parameters

See Also:
:Demo_ISAT_ADO_Control.scn
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Oncoming_Incursion.scn ==
This scenario demonstrates the use of a forced lane offset to cause an oncoming ADO to veer into the driver’s lane:

*Additional ambient traffic is included to provide a normal driving environment;
*A following ADO will encourage slow drivers to travel the speed limit;
*Because we do not want to rely on the driver travelling at the right speed, we match the event ADO velocity to the driver to ensure the event happens as planned.

See Also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Passing_Maneuvers.scn ==
This scenario demonstrates how to implement an ADO passing maneuver on 4 lane and 2 lane roads:

*4 lane roads can use either Set Dial > ADO > Lane Change OR Set_Button > ADO > Lane Change;
*'''Lane change actions are not supported on 2 lane roads;
- Use a lane offset to produce something similar to a passing maneuver

See also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]

== Demo_ISAT_ADO_Random.scn ==

This scenario demonstrates how to use the Rand() function to assign a randomized gap to an ADO:

*Typical gap assignments are fixed/constant;
*Use of a randomized value introduces some inconsistency to the ADO position, which is organic and more realistic.
*Requires the use of variables and expressions.
*Saves the calculated randomizations to the DAQ for validation (review in ISAT).

See also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Relative_Create.scn ==

This scenario demonstrates how to use the Relative Create flag for ADOs.

'''Note:
'''Relative Create works only with negative values.

Used to create traffic behind the external driver independent of the location where the ADOs are initially placed.

See Also:

Demo_ISAT_ADO_Traffic_1.scn

== Demo_ISAT_ADO_Traffic_1.scn ==
This scenario demonstrates how to create traffic in a scenario:

*Create ADOs or copy/paste to locations within the drive;
*Create ADOs with a Creation Radius (they get created as the External Driver drives the route);
*Create ADOs with a trigger Create action;
*Generate traffic with a Traffic Source;
*Generate traffic with the Traffic Manager (or change TM sets).

Each method has advantages and disadvantages.

See Also:

: [[#Demo_ISAT_ADO_Relative_Create.scn|Demo_ISAT_ADO_Relative_Create.scn]]

== Demo_ISAT_ADO_TTA_LVPO.scn ==

This scenario demonstrates the use of Time to Arrival trigger to create a crashpossible event:

*The scenario contains some distracting elements;
*The event ADO behavior is highly dependent on the speed of the XD.
- If the driver is going too fast it may cause the event ADO to disappear
*A time trigger with creation radius acts as a proximity trigger to end the drive, in case the driver steers out of the crash area.

See Also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]

== Demo_ISAT_Alert_Slow_Moving_Object.scn ==

This scenario demonstrates how to implement a proximity alert to warn the driver of a slow moving vehicle ahead:

*Speed monitor to ensure the driver is travelling at a velocity where the event can happen
*Alarm triggers when proximity threshold is achieved

Because there is no good way to tell in advance where the event happens, the end of drive happens following the alert.

== Demo_ISAT_Avoid_Obstacle.scn ==

This demo scenario demonstrates a collision avoidance event using ambient traffic and a DDO obstacle:

*The event requires some setup to position the event vehicles
*The obstacle is a DDO (desk) contained within a van model that has operable rear doors which swing open
*The DDO transitions from a coupled object to a free motion object

== Demo_ISAT_Create_Elements.scn ==

This scenario demonstrates how to create scenario elements during a drive with the Create Element action.

*Remember all triggers share the same actions; thus, any trigger may contain a create action.
*Only 1 create action is permitted per trigger.

== Demo_ISAT_Data_Measures_Default_Measures.scn ==

This scenario demonstrates how to use the miniSim Default Measures in a scenario to produce a valid report for the drive:

*Must follow the write to cell procedure for events:
:#initialize event status and event number to zero at scenario start
:#change SCC_EventStatus from 0 to 1 for the event, and close to 0 after the event
:#change SCC_EventNumber throughout the drive (incremental count starting with 1, 2, 3, etc.)
*Produces a report.txt for each drive
*The drive report.txt for each drive is located in the DAQ folder location.

'''Note: if proper write to cell steps aren’t followed, all measures will be empty in the report.

== Demo_ISAT_Data_Measures_Logstreams.scn ==

This scenario demonstrates the use of Log Streams for documenting significant locations or events in your DAQ file.

*Best practice: initialize all Logstreams to some value at the start.
*Events may be numbered, or subdivided using the same logstream. This demo uses LogStream 1.

*The scenario author and data reduction scientist must agree on what measures are important to encode.

== Demo_ISAT_DDOs.scn ==

This scenario demonstrates different ways to use DDOs and DDDOs. Both types typically begin moving when the scenario starts, unless you assign a creation radius or control the DDO speed.

1. DDO: simple path follower.

2. DDDO (dependent path follower): includes a target path node and a target point. The
DDDO movement is constrained so when the specified object is at the target point, the DDDO will be at the target path node irrespective of the speed assigned to each node.
DDO and DDDOs can be pedestrians, animals or vehicles.

== Demo_ISAT_Display_Screen_Text.scn ==

This scenario demonstrates how to display text messages to the screen.

Text font, color and locations are specified at: NadsMiniSim_x.x\bin.x64\config\scenario_text.xml

'''*Be sure to maintain a backup if you edit this file!

See Also:
Demo_ISAT_Monitor_Driver_Speed.scn
Demo_ISAT_Show_Driver_Speed.scn

==Demo_ISAT_ENV_Dynamic_Fog.scn ==

This scenario demonstrates how to gradually apply fog and the difference between fog and visibility. The usual method of adding weather effects to a scenario is by defining a region of influence which means the effect is applied abruptly to the scene at the region boundaries (on/off).

*Fog and Visibility are Weather Effects
- Insert >> Environment Conditions
*Fog density is managed with 3 variables:
::#FogDistance
::#MaximumFog
::#FogDensity
*An example of reduced Visibility is included near the end of this drive to show how that setting is different from fog.

== Demo_ISAT_time_of_day.scn==

This scenario demonstrates how to change the time of day:

*Variables are used to track day-night cycles
*Time settings (Hour) were chosen arbitrarily
::'''Small time differences will not affect environment; ie. 07:10 – 07:30
*A parked F150 ADO in the scenario has auto-headlights enabled

'''NOTE: Headlight control from scenario requires changes to the miniSim hardware.xml configuration file – they do not automatically turn on at night

==Demo_ISAT_Exit_Simulation_on_Collision.scn ==

This scenario demonstrates how to terminate simulation if a collision happens during a drive. Collisions may occur with ADOs, DDOs, DDDOs and static objects that are present in the scene.

'''Note:
It is possible to configure miniSim or edit the scenario object list file (SOL2.txt) to disable collisions either globally or for specific objects. In that event this scenario will not terminate due to a collision.

==Demo_ISAT_Exit_Follow_Trigger_Create.scn ==

This scenario demonstrates use of the Follow Trigger:

*The follow trigger can activate between any two dynamic objects;
*Most commonly uses the XD for one of the two objects (leader or follower);
*Trigger instigator (predicate) can be either;
*The follow trigger action stack is processed when the trigger conditions have been met;
*When the actions are executed an oncoming Ambulance ADO is created.

== Demo_ISAT_Get_ObjTTC.scn==

This scenario demonstrates how to get a Time To Collision for dynamic and stationary objects (DDOs and ADOs):

*Any time delays in the action stack collecting data and reporting it will create a variance between what you measure in ISAT and what gets reported in the DAQ;
*Cells and variables are used to get the information for TTC and distance;
*Variables are written to SCC_Custom1 – 3 for distance, TTC and the raw distance value reported by GetObjDistPow2;
*3 events are shown to illustrate re-use of the same variables throughout for the target object:
::#DDO dynamic
::#DDO stationary
::#ADO stationary
*Logstreams are used for event numbering and distances to each object;
*If you re-use the same object name, you must remove the previous object – only 1 should be present in the simulation at any time.

'''NOTE:
Static objects cannot be created in realtime with the Create Element action, but they can be created as DDOs. They default to their first visual option; change with a set switch action.

==Demo_ISAT_Lane_Context_Actions.scn ==
This scenario demonstrates how to limit actions to a specific lane.

*Lane filter can only be used with roadpad triggers.
*Useful for situational cases: if the driver is in the correct lane, then they will not receive alert. If the driver is in the wrong lane, then they will.
*Also useful for ADO control at the lane level.

See also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]

==Demo_ISAT_Loop_Management_Traffic.scn ==

This scenario demonstrates how to configure a scenario where it is necessary to drive multiple loops:

*Increment a counter at the location the loop counts increase;
::Each time through the loop a unique action happens
::Increment and decrement operators are not expressions!
*Expression triggers fire on loops (one per loop);
*Can create more than ADOs.

==Demo_ISAT_Monitor_Driver_Speed.scn ==

This scenario demonstrates how to monitor driver velocity. Triggers are configured to monitor driving too slowly (under speed) and driving too fast. The threshold between under and over speed is intentionally difficult to maintain – the goal is to achieve a few alerts of either kind during the drive:

*Variable sets are used for under, over speed cases:
::a timer that increments a variable for each;
::an additional conditional (variable) so there is no alert at scenario start, while the driver is getting up to operating speed.

==Demo_ISAT_Play_Audio.scn ==

This scenario demonstrates how to play audio messages on miniSim using the write to cell >> SCC_Audio_Trigger action.
A short delay after the write to cell action is recommended.

'''Note:
'''Recommended practice requires a second write to cell action to ‘clear’ the previous audio message.

Playing two write to cell >> SCC_Audio_Trigger actions back to back with no delay, and no ‘clear’ likely results in a single audio message. For long messages, use the length of the message as a delay to avoid over-writing the message being played with any subsequent messages.

See also:

[[How to Use Audio in your Scenario|How_to_Use_Audio_in_your_Scenario]]

==Demo_ISAT_Right_Incursion.scn ==

This scenario demonstrates how to present a crash possible event using a right-side incursion:

• Ambient traffic and features are used during the drive; • The event is coupled with an oncoming vehicle distraction;
• The event is masked by features in the scene.

==Demo_ISAT_Set_Switch.scn ==

This scenario demonstrates how to change objects during a simulation with a Set Switch action (static object, DDO, ADO objects).

• The set switch action requires the model switch name;
• Switches for all models are listed in the file NadsMiniSim_x.x\bin.x64\ModelList.txt

==Demo_ISAT_Stop_Drive.scn ==

This scenario demonstrates how to terminate a simulation from the scenario:

• A roadpad trigger tells the driver it is time to stop and shift into park, and creates an Expression trigger to:
- monitor the transmission gear,
- terminate the simulation if the driver shifts into Park.
A Roadpad trigger acts as a backup that ends the drive if the XD doesn’t stop.

==Demo_ISAT_Show_Driver_Speed.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action.

* A time trigger is configured to monitor conditions; in this case, the external driver’s speed.
* The monitoring trigger is created by a roadpad trigger to ensure the driver is moving; therefore driver velocity is not zero.

* The monitoring trigger fires repeatedly during the drive.
* A variable is set to the value of a cell containing the driver velocity;
* That value is displayed on screen.

See Also:
:Demo_ISAT_Display_Screen_Text.scn
:Demo_ISAT_Monitor_Driver_Speed.scn

==Demo_ISAT_Track_Button_Press.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action:

• A time trigger This demo scenario uses expression triggers to detect button presses (turn signal activation).
• Variables are used to track which signal was activated (left vs. right) and demo progress.

'''Note:
'''The values used in the scenario may be site-specific; if your miniSim does not produce the values used, this scenario may fail.

To determine the correct values for your miniSim, drive any scenario and press the left, then the right turn signals and review this drive DAQ in ISAT. The relevant cell is CIS_Turn_Signal.

==Demo_ISAT_Traffic_Light.scn ==

This scenario demonstrates the use of a Traffic Light Trigger:

*A traffic light trigger activates at a specified signal state;
*Relies on a traffic light action to set the signal to a specified state;
*That state must already exist in the traffic signal timing table configuration for the intersection
::dbl-click on the traffic signal to open the signal timing table

*A more robust method would use a time to arrival (TTA) trigger that can accommodate different XD velocities or driving styles (conservative vs. aggressive, slow vs. fast) instead of the roadpad and delays used in this demo.

==Demo_ISAT_Virtual_Objects.scn ==

This scenario demonstrates how to display and control virtual objects during a drive. Virtual objects render to screen space on top of everything on display; they do not typically occupy 3d space within the scene.

One possible application for virtual objects is to use them as a custom heads up display (HUD) or alert system within the scenario.

By default virtual objects initialize to state 0 (off/disabled) at scenario start.

'''Note:
'''Currently only Render Type = Overlay and Main Screen are supported.

==Demo_ISAT_Yellow_Light_Dilemma.scn ==

This scenario demonstrates how to create a Yellow Light dilemma at an intersection.

#There must be a working signal state table;
#The traffic signal is controlled by a time to arrival (TTA) trigger;
#If the XD decides to stop, a roadpad trigger created by (2) will reset the signal to green so the XD can continue the drive;
#A roadpad trigger terminates the drive after the intersection.

ISAT Demonstration Scenarios

2023-09-15T15:27:25Z

Shawn Allen: /* Demo_ISAT_Lane_Context_Actions.scn */

== About the ISAT Demonstration Scenarios ==

Making something happen during a simulation in a repeatable and consistent fashion for different driving styles is the essence of scenario authoring. Every thing that happens must be coordinated to some degree with the External Driver (XD). For repeatability, it is also necessary to consider how different driving styles (aggressive vs. conservative) impact how the scenario unfolds for each.

These demonstration scenarios were created to facilitate learning how to use ISAT and do scenario actions. Each scenario demonstrates a key concept or element and may contain additional elements to support the main concept. For example, all scenarios contain an introduction to the scenario for the XD and a termination trigger that will stop the simulation.

'''These scenarios are not intended for use as completed data collection ready scenarios. They are provided to answer the question "how can I do X Y Z..?"

These scenario elements can be integrated into your scenarios using copy-paste except where elements have been created with a Create action. For those elements it will be necessary to copy the parent element instead.

TBC: Add a link to the library or directions how to get the files

== Demo_ISAT_ADO_Control.scn ==

This scenario demonstrates how to control an ADO:

• ADO set dial > forced velocity = 0 to keep ADO stationary.

• Release the forced velocity, assign a maintain gap.

• Release the maintain gap, assign a target velocity.

See also:
:Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn ==
This scenario demonstrates how to vary the velocity of an ADO using a Sum of Sines expression:

*Uses a forced velocity action;
*Try to maintain a constant speed at 30 mph;
*Notice how the speed of the ADO changes during the drive.

Note:
There is also a forced velocity Sin function available with 4 parameters

See Also:
:Demo_ISAT_ADO_Control.scn
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Oncoming_Incursion.scn ==
This scenario demonstrates the use of a forced lane offset to cause an oncoming ADO to veer into the driver’s lane:

*Additional ambient traffic is included to provide a normal driving environment;
*A following ADO will encourage slow drivers to travel the speed limit;
*Because we do not want to rely on the driver travelling at the right speed, we match the event ADO velocity to the driver to ensure the event happens as planned.

See Also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Passing_Maneuvers.scn ==
This scenario demonstrates how to implement an ADO passing maneuver on 4 lane and 2 lane roads:

*4 lane roads can use either Set Dial > ADO > Lane Change OR Set_Button > ADO > Lane Change;
*'''Lane change actions are not supported on 2 lane roads;
- Use a lane offset to produce something similar to a passing maneuver

See also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]

== Demo_ISAT_ADO_Random.scn ==

This scenario demonstrates how to use the Rand() function to assign a randomized gap to an ADO:

*Typical gap assignments are fixed/constant;
*Use of a randomized value introduces some inconsistency to the ADO position, which is organic and more realistic.
*Requires the use of variables and expressions.
*Saves the calculated randomizations to the DAQ for validation (review in ISAT).

See also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Relative_Create.scn ==

This scenario demonstrates how to use the Relative Create flag for ADOs.

'''Note:
'''Relative Create works only with negative values.

Used to create traffic behind the external driver independent of the location where the ADOs are initially placed.

See Also:

Demo_ISAT_ADO_Traffic_1.scn

== Demo_ISAT_ADO_Traffic_1.scn ==
This scenario demonstrates how to create traffic in a scenario:

*Create ADOs or copy/paste to locations within the drive;
*Create ADOs with a Creation Radius (they get created as the External Driver drives the route);
*Create ADOs with a trigger Create action;
*Generate traffic with a Traffic Source;
*Generate traffic with the Traffic Manager (or change TM sets).

Each method has advantages and disadvantages.

See Also:

: [[#Demo_ISAT_ADO_Relative_Create.scn|Demo_ISAT_ADO_Relative_Create.scn]]

== Demo_ISAT_ADO_TTA_LVPO.scn ==

This scenario demonstrates the use of Time to Arrival trigger to create a crashpossible event:

*The scenario contains some distracting elements;
*The event ADO behavior is highly dependent on the speed of the XD.
- If the driver is going too fast it may cause the event ADO to disappear
*A time trigger with creation radius acts as a proximity trigger to end the drive, in case the driver steers out of the crash area.

See Also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]

== Demo_ISAT_Alert_Slow_Moving_Object.scn ==

This scenario demonstrates how to implement a proximity alert to warn the driver of a slow moving vehicle ahead:

*Speed monitor to ensure the driver is travelling at a velocity where the event can happen
*Alarm triggers when proximity threshold is achieved

Because there is no good way to tell in advance where the event happens, the end of drive happens following the alert.

== Demo_ISAT_Avoid_Obstacle.scn ==

This demo scenario demonstrates a collision avoidance event using ambient traffic and a DDO obstacle:

*The event requires some setup to position the event vehicles
*The obstacle is a DDO (desk) contained within a van model that has operable rear doors which swing open
*The DDO transitions from a coupled object to a free motion object

== Demo_ISAT_Create_Elements.scn ==

This scenario demonstrates how to create scenario elements during a drive with the Create Element action.

*Remember all triggers share the same actions; thus, any trigger may contain a create action.
*Only 1 create action is permitted per trigger.

== Demo_ISAT_Data_Measures_Default_Measures.scn ==

This scenario demonstrates how to use the miniSim Default Measures in a scenario to produce a valid report for the drive:

*Must follow the write to cell procedure for events:
:#initialize event status and event number to zero at scenario start
:#change SCC_EventStatus from 0 to 1 for the event, and close to 0 after the event
:#change SCC_EventNumber throughout the drive (incremental count starting with 1, 2, 3, etc.)
*Produces a report.txt for each drive
*The drive report.txt for each drive is located in the DAQ folder location.

'''Note: if proper write to cell steps aren’t followed, all measures will be empty in the report.

== Demo_ISAT_Data_Measures_Logstreams.scn ==

This scenario demonstrates the use of Log Streams for documenting significant locations or events in your DAQ file.

*Best practice: initialize all Logstreams to some value at the start.
*Events may be numbered, or subdivided using the same logstream. This demo uses LogStream 1.

*The scenario author and data reduction scientist must agree on what measures are important to encode.

== Demo_ISAT_DDOs.scn ==

This scenario demonstrates different ways to use DDOs and DDDOs. Both types typically begin moving when the scenario starts, unless you assign a creation radius or control the DDO speed.

1. DDO: simple path follower.

2. DDDO (dependent path follower): includes a target path node and a target point. The
DDDO movement is constrained so when the specified object is at the target point, the DDDO will be at the target path node irrespective of the speed assigned to each node.
DDO and DDDOs can be pedestrians, animals or vehicles.

== Demo_ISAT_Display_Screen_Text.scn ==

This scenario demonstrates how to display text messages to the screen.

Text font, color and locations are specified at: NadsMiniSim_x.x\bin.x64\config\scenario_text.xml

'''*Be sure to maintain a backup if you edit this file!

See Also:
Demo_ISAT_Monitor_Driver_Speed.scn
Demo_ISAT_Show_Driver_Speed.scn

==Demo_ISAT_ENV_Dynamic_Fog.scn ==

This scenario demonstrates how to gradually apply fog and the difference between fog and visibility. The usual method of adding weather effects to a scenario is by defining a region of influence which means the effect is applied abruptly to the scene at the region boundaries (on/off).

*Fog and Visibility are Weather Effects
- Insert >> Environment Conditions
*Fog density is managed with 3 variables:
::#FogDistance
::#MaximumFog
::#FogDensity
*An example of reduced Visibility is included near the end of this drive to show how that setting is different from fog.

== Demo_ISAT_time_of_day.scn==

This scenario demonstrates how to change the time of day:

*Variables are used to track day-night cycles
*Time settings (Hour) were chosen arbitrarily
::'''Small time differences will not affect environment; ie. 07:10 – 07:30
*A parked F150 ADO in the scenario has auto-headlights enabled

'''NOTE: Headlight control from scenario requires changes to the miniSim hardware.xml configuration file – they do not automatically turn on at night

==Demo_ISAT_Exit_Simulation_on_Collision.scn ==

This scenario demonstrates how to terminate simulation if a collision happens during a drive. Collisions may occur with ADOs, DDOs, DDDOs and static objects that are present in the scene.

'''Note:
It is possible to configure miniSim or edit the scenario object list file (SOL2.txt) to disable collisions either globally or for specific objects. In that event this scenario will not terminate due to a collision.

==Demo_ISAT_Exit_Follow_Trigger_Create.scn ==

This scenario demonstrates use of the Follow Trigger:

*The follow trigger can activate between any two dynamic objects;
*Most commonly uses the XD for one of the two objects (leader or follower);
*Trigger instigator (predicate) can be either;
*The follow trigger action stack is processed when the trigger conditions have been met;
*When the actions are executed an oncoming Ambulance ADO is created.

== Demo_ISAT_Get_ObjTTC.scn==

This scenario demonstrates how to get a Time To Collision for dynamic and stationary objects (DDOs and ADOs):

*Any time delays in the action stack collecting data and reporting it will create a variance between what you measure in ISAT and what gets reported in the DAQ;
*Cells and variables are used to get the information for TTC and distance;
*Variables are written to SCC_Custom1 – 3 for distance, TTC and the raw distance value reported by GetObjDistPow2;
*3 events are shown to illustrate re-use of the same variables throughout for the target object:
::#DDO dynamic
::#DDO stationary
::#ADO stationary
*Logstreams are used for event numbering and distances to each object;
*If you re-use the same object name, you must remove the previous object – only 1 should be present in the simulation at any time.

'''NOTE:
Static objects cannot be created in realtime with the Create Element action, but they can be created as DDOs. They default to their first visual option; change with a set switch action.

==Demo_ISAT_Lane_Context_Actions.scn ==
This scenario demonstrates how to limit actions to a specific lane.

*Lane filter can only be used with roadpad triggers.
*Useful for situational cases: if the driver is in the correct lane, then they will not receive alert. If the driver is in the wrong lane, then they will.
*Also useful for ADO control at the lane level.

See also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]

==Demo_ISAT_Loop_Management_Traffic.scn ==

This scenario demonstrates how to configure a scenario where it is necessary to drive multiple loops:

*Increment a counter at the location the loop counts increase;
::Each time through the loop a unique action happens
::Increment and decrement operators are not expressions!
*Expression triggers fire on loops (one per loop);
*Can create more than ADOs.

==Demo_ISAT_Monitor_Driver_Speed.scn ==

This scenario demonstrates how to monitor driver velocity. Triggers are configured to monitor driving too slowly (under speed) and driving too fast. The threshold between under and over speed is intentionally difficult to maintain – the goal is to achieve a few alerts of either kind during the drive:

*Variable sets are used for under, over speed cases:
::a timer that increments a variable for each;
::an additional conditional (variable) so there is no alert at scenario start, while the driver is getting up to operating speed.

==Demo_ISAT_Play_Audio.scn ==

This scenario demonstrates how to play audio messages on miniSim using the write to cell >> SCC_Audio_Trigger action.
A short delay after the write to cell action is recommended.

'''Note:
'''Recommended practice requires a second write to cell action to ‘clear’ the previous audio message.

Playing two write to cell >> SCC_Audio_Trigger actions back to back with no delay, and no ‘clear’ likely results in a single audio message. For long messages, use the length of the message as a delay to avoid over-writing the message being played with any subsequent messages.

See also:

[[How to Use Audio in your Scenario|How_to_Use_Audio_in_your_Scenario]]

==Demo_ISAT_Right_Incursion.scn ==

This scenario demonstrates how to present a crash possible event using a right-side incursion:

• Ambient traffic and features are used during the drive; • The event is coupled with an oncoming vehicle distraction;
• The event is masked by features in the scene.

==Demo_ISAT_Set_Switch.scn ==

This scenario demonstrates how to change objects during a simulation with a Set Switch action (static object, DDO, ADO objects).

• The set switch action requires the model switch name;
• Switches for all models are listed in the file NadsMiniSim_x.x\bin.x64\ModelList.txt

==Demo_ISAT_Stop_Drive.scn ==

This scenario demonstrates how to terminate a simulation from the scenario:

• A roadpad trigger tells the driver it is time to stop and shift into park, and creates an Expression trigger to:
- monitor the transmission gear,
- terminate the simulation if the driver shifts into Park.
A Roadpad trigger acts as a backup that ends the drive if the XD doesn’t stop.

==Demo_ISAT_Show_Driver_Speed.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action.

* A time trigger is configured to monitor conditions; in this case, the external driver’s speed.
* The monitoring trigger is created by a roadpad trigger to ensure the driver is moving; therefore driver velocity is not zero.

* The monitoring trigger fires repeatedly during the drive.
* A variable is set to the value of a cell containing the driver velocity;
* That value is displayed on screen.

See Also:
:Demo_ISAT_Display_Screen_Text.scn
:Demo_ISAT_Monitor_Driver_Speed.scn

==Demo_ISAT_Track_Button_Press.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action:

• A time trigger This demo scenario uses expression triggers to detect button presses (turn signal activation).
• Variables are used to track which signal was activated (left vs. right) and demo progress.

'''Note:
'''The values used in the scenario may be site-specific; if your miniSim does not produce the values used, this scenario may fail.

To determine the correct values for your miniSim, drive any scenario and press the left, then the right turn signals and review this drive DAQ in ISAT. The relevant cell is CIS_Turn_Signal.

==Demo_ISAT_Traffic_Light.scn ==

This scenario demonstrates the use of a Traffic Light Trigger:

*A traffic light trigger activates at a specified signal state;
*Relies on a traffic light action to set the signal to a specified state;
*That state must already exist in the traffic signal timing table configuration for the intersection
::dbl-click on the traffic signal to open the signal timing table

*A more robust method would use a time to arrival (TTA) trigger that can accommodate different XD velocities or driving styles (conservative vs. aggressive, slow vs. fast) instead of the roadpad and delays used in this demo.

==Demo_ISAT_Virtual_Objects.scn ==

This scenario demonstrates how to display and control virtual objects during a drive. Virtual objects render to screen space on top of everything on display; they do not typically occupy 3d space within the scene.

One possible application for virtual objects is to use them as a custom heads up display (HUD) or alert system within the scenario.

By default virtual objects initialize to state 0 (off/disabled) at scenario start.

'''Note:
'''Currently only Render Type = Overlay and Main Screen are supported.

==Demo_ISAT_Yellow_Light_Dilemma.scn ==

This scenario demonstrates how to create a Yellow Light dilemma at an intersection.

#There must be a working signal state table;
#The traffic signal is controlled by a time to arrival (TTA) trigger;
#If the XD decides to stop, a roadpad trigger created by (2) will reset the signal to green so the XD can continue the drive;
#A roadpad trigger terminates the drive after the intersection.

ISAT Demonstration Scenarios

2023-09-15T15:25:17Z

Shawn Allen: /* Demo_ISAT_ADO_TTA_LVPO.scn */

== About the ISAT Demonstration Scenarios ==

Making something happen during a simulation in a repeatable and consistent fashion for different driving styles is the essence of scenario authoring. Every thing that happens must be coordinated to some degree with the External Driver (XD). For repeatability, it is also necessary to consider how different driving styles (aggressive vs. conservative) impact how the scenario unfolds for each.

These demonstration scenarios were created to facilitate learning how to use ISAT and do scenario actions. Each scenario demonstrates a key concept or element and may contain additional elements to support the main concept. For example, all scenarios contain an introduction to the scenario for the XD and a termination trigger that will stop the simulation.

'''These scenarios are not intended for use as completed data collection ready scenarios. They are provided to answer the question "how can I do X Y Z..?"

These scenario elements can be integrated into your scenarios using copy-paste except where elements have been created with a Create action. For those elements it will be necessary to copy the parent element instead.

TBC: Add a link to the library or directions how to get the files

== Demo_ISAT_ADO_Control.scn ==

This scenario demonstrates how to control an ADO:

• ADO set dial > forced velocity = 0 to keep ADO stationary.

• Release the forced velocity, assign a maintain gap.

• Release the maintain gap, assign a target velocity.

See also:
:Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn ==
This scenario demonstrates how to vary the velocity of an ADO using a Sum of Sines expression:

*Uses a forced velocity action;
*Try to maintain a constant speed at 30 mph;
*Notice how the speed of the ADO changes during the drive.

Note:
There is also a forced velocity Sin function available with 4 parameters

See Also:
:Demo_ISAT_ADO_Control.scn
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Oncoming_Incursion.scn ==
This scenario demonstrates the use of a forced lane offset to cause an oncoming ADO to veer into the driver’s lane:

*Additional ambient traffic is included to provide a normal driving environment;
*A following ADO will encourage slow drivers to travel the speed limit;
*Because we do not want to rely on the driver travelling at the right speed, we match the event ADO velocity to the driver to ensure the event happens as planned.

See Also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Passing_Maneuvers.scn ==
This scenario demonstrates how to implement an ADO passing maneuver on 4 lane and 2 lane roads:

*4 lane roads can use either Set Dial > ADO > Lane Change OR Set_Button > ADO > Lane Change;
*'''Lane change actions are not supported on 2 lane roads;
- Use a lane offset to produce something similar to a passing maneuver

See also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]

== Demo_ISAT_ADO_Random.scn ==

This scenario demonstrates how to use the Rand() function to assign a randomized gap to an ADO:

*Typical gap assignments are fixed/constant;
*Use of a randomized value introduces some inconsistency to the ADO position, which is organic and more realistic.
*Requires the use of variables and expressions.
*Saves the calculated randomizations to the DAQ for validation (review in ISAT).

See also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Relative_Create.scn ==

This scenario demonstrates how to use the Relative Create flag for ADOs.

'''Note:
'''Relative Create works only with negative values.

Used to create traffic behind the external driver independent of the location where the ADOs are initially placed.

See Also:

Demo_ISAT_ADO_Traffic_1.scn

== Demo_ISAT_ADO_Traffic_1.scn ==
This scenario demonstrates how to create traffic in a scenario:

*Create ADOs or copy/paste to locations within the drive;
*Create ADOs with a Creation Radius (they get created as the External Driver drives the route);
*Create ADOs with a trigger Create action;
*Generate traffic with a Traffic Source;
*Generate traffic with the Traffic Manager (or change TM sets).

Each method has advantages and disadvantages.

See Also:

: [[#Demo_ISAT_ADO_Relative_Create.scn|Demo_ISAT_ADO_Relative_Create.scn]]

== Demo_ISAT_ADO_TTA_LVPO.scn ==

This scenario demonstrates the use of Time to Arrival trigger to create a crashpossible event:

*The scenario contains some distracting elements;
*The event ADO behavior is highly dependent on the speed of the XD.
- If the driver is going too fast it may cause the event ADO to disappear
*A time trigger with creation radius acts as a proximity trigger to end the drive, in case the driver steers out of the crash area.

See Also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]

== Demo_ISAT_Alert_Slow_Moving_Object.scn ==

This scenario demonstrates how to implement a proximity alert to warn the driver of a slow moving vehicle ahead:

*Speed monitor to ensure the driver is travelling at a velocity where the event can happen
*Alarm triggers when proximity threshold is achieved

Because there is no good way to tell in advance where the event happens, the end of drive happens following the alert.

== Demo_ISAT_Avoid_Obstacle.scn ==

This demo scenario demonstrates a collision avoidance event using ambient traffic and a DDO obstacle:

*The event requires some setup to position the event vehicles
*The obstacle is a DDO (desk) contained within a van model that has operable rear doors which swing open
*The DDO transitions from a coupled object to a free motion object

== Demo_ISAT_Create_Elements.scn ==

This scenario demonstrates how to create scenario elements during a drive with the Create Element action.

*Remember all triggers share the same actions; thus, any trigger may contain a create action.
*Only 1 create action is permitted per trigger.

== Demo_ISAT_Data_Measures_Default_Measures.scn ==

This scenario demonstrates how to use the miniSim Default Measures in a scenario to produce a valid report for the drive:

*Must follow the write to cell procedure for events:
:#initialize event status and event number to zero at scenario start
:#change SCC_EventStatus from 0 to 1 for the event, and close to 0 after the event
:#change SCC_EventNumber throughout the drive (incremental count starting with 1, 2, 3, etc.)
*Produces a report.txt for each drive
*The drive report.txt for each drive is located in the DAQ folder location.

'''Note: if proper write to cell steps aren’t followed, all measures will be empty in the report.

== Demo_ISAT_Data_Measures_Logstreams.scn ==

This scenario demonstrates the use of Log Streams for documenting significant locations or events in your DAQ file.

*Best practice: initialize all Logstreams to some value at the start.
*Events may be numbered, or subdivided using the same logstream. This demo uses LogStream 1.

*The scenario author and data reduction scientist must agree on what measures are important to encode.

== Demo_ISAT_DDOs.scn ==

This scenario demonstrates different ways to use DDOs and DDDOs. Both types typically begin moving when the scenario starts, unless you assign a creation radius or control the DDO speed.

1. DDO: simple path follower.

2. DDDO (dependent path follower): includes a target path node and a target point. The
DDDO movement is constrained so when the specified object is at the target point, the DDDO will be at the target path node irrespective of the speed assigned to each node.
DDO and DDDOs can be pedestrians, animals or vehicles.

== Demo_ISAT_Display_Screen_Text.scn ==

This scenario demonstrates how to display text messages to the screen.

Text font, color and locations are specified at: NadsMiniSim_x.x\bin.x64\config\scenario_text.xml

'''*Be sure to maintain a backup if you edit this file!

See Also:
Demo_ISAT_Monitor_Driver_Speed.scn
Demo_ISAT_Show_Driver_Speed.scn

==Demo_ISAT_ENV_Dynamic_Fog.scn ==

This scenario demonstrates how to gradually apply fog and the difference between fog and visibility. The usual method of adding weather effects to a scenario is by defining a region of influence which means the effect is applied abruptly to the scene at the region boundaries (on/off).

*Fog and Visibility are Weather Effects
- Insert >> Environment Conditions
*Fog density is managed with 3 variables:
::#FogDistance
::#MaximumFog
::#FogDensity
*An example of reduced Visibility is included near the end of this drive to show how that setting is different from fog.

== Demo_ISAT_time_of_day.scn==

This scenario demonstrates how to change the time of day:

*Variables are used to track day-night cycles
*Time settings (Hour) were chosen arbitrarily
::'''Small time differences will not affect environment; ie. 07:10 – 07:30
*A parked F150 ADO in the scenario has auto-headlights enabled

'''NOTE: Headlight control from scenario requires changes to the miniSim hardware.xml configuration file – they do not automatically turn on at night

==Demo_ISAT_Exit_Simulation_on_Collision.scn ==

This scenario demonstrates how to terminate simulation if a collision happens during a drive. Collisions may occur with ADOs, DDOs, DDDOs and static objects that are present in the scene.

'''Note:
It is possible to configure miniSim or edit the scenario object list file (SOL2.txt) to disable collisions either globally or for specific objects. In that event this scenario will not terminate due to a collision.

==Demo_ISAT_Exit_Follow_Trigger_Create.scn ==

This scenario demonstrates use of the Follow Trigger:

*The follow trigger can activate between any two dynamic objects;
*Most commonly uses the XD for one of the two objects (leader or follower);
*Trigger instigator (predicate) can be either;
*The follow trigger action stack is processed when the trigger conditions have been met;
*When the actions are executed an oncoming Ambulance ADO is created.

== Demo_ISAT_Get_ObjTTC.scn==

This scenario demonstrates how to get a Time To Collision for dynamic and stationary objects (DDOs and ADOs):

*Any time delays in the action stack collecting data and reporting it will create a variance between what you measure in ISAT and what gets reported in the DAQ;
*Cells and variables are used to get the information for TTC and distance;
*Variables are written to SCC_Custom1 – 3 for distance, TTC and the raw distance value reported by GetObjDistPow2;
*3 events are shown to illustrate re-use of the same variables throughout for the target object:
::#DDO dynamic
::#DDO stationary
::#ADO stationary
*Logstreams are used for event numbering and distances to each object;
*If you re-use the same object name, you must remove the previous object – only 1 should be present in the simulation at any time.

'''NOTE:
Static objects cannot be created in realtime with the Create Element action, but they can be created as DDOs. They default to their first visual option; change with a set switch action.

==Demo_ISAT_Lane_Context_Actions.scn ==
This scenario demonstrates how to limit actions to a specific lane.

*Lane filter can only be used with roadpad triggers.
*Useful for situational cases: if the driver is in the correct lane, then they will not receive alert. If the driver is in the wrong lane, then they will.
*Also useful for ADO control at the lane level.

See also:
Demo_ISAT_ADO_Control.scn

==Demo_ISAT_Loop_Management_Traffic.scn ==

This scenario demonstrates how to configure a scenario where it is necessary to drive multiple loops:

*Increment a counter at the location the loop counts increase;
::Each time through the loop a unique action happens
::Increment and decrement operators are not expressions!
*Expression triggers fire on loops (one per loop);
*Can create more than ADOs.

==Demo_ISAT_Monitor_Driver_Speed.scn ==

This scenario demonstrates how to monitor driver velocity. Triggers are configured to monitor driving too slowly (under speed) and driving too fast. The threshold between under and over speed is intentionally difficult to maintain – the goal is to achieve a few alerts of either kind during the drive:

*Variable sets are used for under, over speed cases:
::a timer that increments a variable for each;
::an additional conditional (variable) so there is no alert at scenario start, while the driver is getting up to operating speed.

==Demo_ISAT_Play_Audio.scn ==

This scenario demonstrates how to play audio messages on miniSim using the write to cell >> SCC_Audio_Trigger action.
A short delay after the write to cell action is recommended.

'''Note:
'''Recommended practice requires a second write to cell action to ‘clear’ the previous audio message.

Playing two write to cell >> SCC_Audio_Trigger actions back to back with no delay, and no ‘clear’ likely results in a single audio message. For long messages, use the length of the message as a delay to avoid over-writing the message being played with any subsequent messages.

See also:

[[How to Use Audio in your Scenario|How_to_Use_Audio_in_your_Scenario]]

==Demo_ISAT_Right_Incursion.scn ==

This scenario demonstrates how to present a crash possible event using a right-side incursion:

• Ambient traffic and features are used during the drive; • The event is coupled with an oncoming vehicle distraction;
• The event is masked by features in the scene.

==Demo_ISAT_Set_Switch.scn ==

This scenario demonstrates how to change objects during a simulation with a Set Switch action (static object, DDO, ADO objects).

• The set switch action requires the model switch name;
• Switches for all models are listed in the file NadsMiniSim_x.x\bin.x64\ModelList.txt

==Demo_ISAT_Stop_Drive.scn ==

This scenario demonstrates how to terminate a simulation from the scenario:

• A roadpad trigger tells the driver it is time to stop and shift into park, and creates an Expression trigger to:
- monitor the transmission gear,
- terminate the simulation if the driver shifts into Park.
A Roadpad trigger acts as a backup that ends the drive if the XD doesn’t stop.

==Demo_ISAT_Show_Driver_Speed.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action.

* A time trigger is configured to monitor conditions; in this case, the external driver’s speed.
* The monitoring trigger is created by a roadpad trigger to ensure the driver is moving; therefore driver velocity is not zero.

* The monitoring trigger fires repeatedly during the drive.
* A variable is set to the value of a cell containing the driver velocity;
* That value is displayed on screen.

See Also:
:Demo_ISAT_Display_Screen_Text.scn
:Demo_ISAT_Monitor_Driver_Speed.scn

==Demo_ISAT_Track_Button_Press.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action:

• A time trigger This demo scenario uses expression triggers to detect button presses (turn signal activation).
• Variables are used to track which signal was activated (left vs. right) and demo progress.

'''Note:
'''The values used in the scenario may be site-specific; if your miniSim does not produce the values used, this scenario may fail.

To determine the correct values for your miniSim, drive any scenario and press the left, then the right turn signals and review this drive DAQ in ISAT. The relevant cell is CIS_Turn_Signal.

==Demo_ISAT_Traffic_Light.scn ==

This scenario demonstrates the use of a Traffic Light Trigger:

*A traffic light trigger activates at a specified signal state;
*Relies on a traffic light action to set the signal to a specified state;
*That state must already exist in the traffic signal timing table configuration for the intersection
::dbl-click on the traffic signal to open the signal timing table

*A more robust method would use a time to arrival (TTA) trigger that can accommodate different XD velocities or driving styles (conservative vs. aggressive, slow vs. fast) instead of the roadpad and delays used in this demo.

==Demo_ISAT_Virtual_Objects.scn ==

This scenario demonstrates how to display and control virtual objects during a drive. Virtual objects render to screen space on top of everything on display; they do not typically occupy 3d space within the scene.

One possible application for virtual objects is to use them as a custom heads up display (HUD) or alert system within the scenario.

By default virtual objects initialize to state 0 (off/disabled) at scenario start.

'''Note:
'''Currently only Render Type = Overlay and Main Screen are supported.

==Demo_ISAT_Yellow_Light_Dilemma.scn ==

This scenario demonstrates how to create a Yellow Light dilemma at an intersection.

#There must be a working signal state table;
#The traffic signal is controlled by a time to arrival (TTA) trigger;
#If the XD decides to stop, a roadpad trigger created by (2) will reset the signal to green so the XD can continue the drive;
#A roadpad trigger terminates the drive after the intersection.

ISAT Demonstration Scenarios

2023-09-15T15:23:30Z

Shawn Allen: /* Demo_ISAT_ADO_Traffic_1.scn */

== About the ISAT Demonstration Scenarios ==

Making something happen during a simulation in a repeatable and consistent fashion for different driving styles is the essence of scenario authoring. Every thing that happens must be coordinated to some degree with the External Driver (XD). For repeatability, it is also necessary to consider how different driving styles (aggressive vs. conservative) impact how the scenario unfolds for each.

These demonstration scenarios were created to facilitate learning how to use ISAT and do scenario actions. Each scenario demonstrates a key concept or element and may contain additional elements to support the main concept. For example, all scenarios contain an introduction to the scenario for the XD and a termination trigger that will stop the simulation.

'''These scenarios are not intended for use as completed data collection ready scenarios. They are provided to answer the question "how can I do X Y Z..?"

These scenario elements can be integrated into your scenarios using copy-paste except where elements have been created with a Create action. For those elements it will be necessary to copy the parent element instead.

TBC: Add a link to the library or directions how to get the files

== Demo_ISAT_ADO_Control.scn ==

This scenario demonstrates how to control an ADO:

• ADO set dial > forced velocity = 0 to keep ADO stationary.

• Release the forced velocity, assign a maintain gap.

• Release the maintain gap, assign a target velocity.

See also:
:Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn ==
This scenario demonstrates how to vary the velocity of an ADO using a Sum of Sines expression:

*Uses a forced velocity action;
*Try to maintain a constant speed at 30 mph;
*Notice how the speed of the ADO changes during the drive.

Note:
There is also a forced velocity Sin function available with 4 parameters

See Also:
:Demo_ISAT_ADO_Control.scn
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Oncoming_Incursion.scn ==
This scenario demonstrates the use of a forced lane offset to cause an oncoming ADO to veer into the driver’s lane:

*Additional ambient traffic is included to provide a normal driving environment;
*A following ADO will encourage slow drivers to travel the speed limit;
*Because we do not want to rely on the driver travelling at the right speed, we match the event ADO velocity to the driver to ensure the event happens as planned.

See Also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Passing_Maneuvers.scn ==
This scenario demonstrates how to implement an ADO passing maneuver on 4 lane and 2 lane roads:

*4 lane roads can use either Set Dial > ADO > Lane Change OR Set_Button > ADO > Lane Change;
*'''Lane change actions are not supported on 2 lane roads;
- Use a lane offset to produce something similar to a passing maneuver

See also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]

== Demo_ISAT_ADO_Random.scn ==

This scenario demonstrates how to use the Rand() function to assign a randomized gap to an ADO:

*Typical gap assignments are fixed/constant;
*Use of a randomized value introduces some inconsistency to the ADO position, which is organic and more realistic.
*Requires the use of variables and expressions.
*Saves the calculated randomizations to the DAQ for validation (review in ISAT).

See also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Relative_Create.scn ==

This scenario demonstrates how to use the Relative Create flag for ADOs.

'''Note:
'''Relative Create works only with negative values.

Used to create traffic behind the external driver independent of the location where the ADOs are initially placed.

See Also:

Demo_ISAT_ADO_Traffic_1.scn

== Demo_ISAT_ADO_Traffic_1.scn ==
This scenario demonstrates how to create traffic in a scenario:

*Create ADOs or copy/paste to locations within the drive;
*Create ADOs with a Creation Radius (they get created as the External Driver drives the route);
*Create ADOs with a trigger Create action;
*Generate traffic with a Traffic Source;
*Generate traffic with the Traffic Manager (or change TM sets).

Each method has advantages and disadvantages.

See Also:

: [[#Demo_ISAT_ADO_Relative_Create.scn|Demo_ISAT_ADO_Relative_Create.scn]]

== Demo_ISAT_ADO_TTA_LVPO.scn ==

This scenario demonstrates the use of Time to Arrival trigger to create a crashpossible event:

*The scenario contains some distracting elements;
*The event ADO behavior is highly dependent on the speed of the XD.
- If the driver is going too fast it may cause the event ADO to disappear
*A time trigger with creation radius acts as a proximity trigger to end the drive, in case the driver steers out of the crash area.

See Also:

:Demo_ISAT_ADO_Control.scn
:Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn
:Demo_ISAT_ADO_Oncoming_Incursion.scn

== Demo_ISAT_Alert_Slow_Moving_Object.scn ==

This scenario demonstrates how to implement a proximity alert to warn the driver of a slow moving vehicle ahead:

*Speed monitor to ensure the driver is travelling at a velocity where the event can happen
*Alarm triggers when proximity threshold is achieved

Because there is no good way to tell in advance where the event happens, the end of drive happens following the alert.

== Demo_ISAT_Avoid_Obstacle.scn ==

This demo scenario demonstrates a collision avoidance event using ambient traffic and a DDO obstacle:

*The event requires some setup to position the event vehicles
*The obstacle is a DDO (desk) contained within a van model that has operable rear doors which swing open
*The DDO transitions from a coupled object to a free motion object

== Demo_ISAT_Create_Elements.scn ==

This scenario demonstrates how to create scenario elements during a drive with the Create Element action.

*Remember all triggers share the same actions; thus, any trigger may contain a create action.
*Only 1 create action is permitted per trigger.

== Demo_ISAT_Data_Measures_Default_Measures.scn ==

This scenario demonstrates how to use the miniSim Default Measures in a scenario to produce a valid report for the drive:

*Must follow the write to cell procedure for events:
:#initialize event status and event number to zero at scenario start
:#change SCC_EventStatus from 0 to 1 for the event, and close to 0 after the event
:#change SCC_EventNumber throughout the drive (incremental count starting with 1, 2, 3, etc.)
*Produces a report.txt for each drive
*The drive report.txt for each drive is located in the DAQ folder location.

'''Note: if proper write to cell steps aren’t followed, all measures will be empty in the report.

== Demo_ISAT_Data_Measures_Logstreams.scn ==

This scenario demonstrates the use of Log Streams for documenting significant locations or events in your DAQ file.

*Best practice: initialize all Logstreams to some value at the start.
*Events may be numbered, or subdivided using the same logstream. This demo uses LogStream 1.

*The scenario author and data reduction scientist must agree on what measures are important to encode.

== Demo_ISAT_DDOs.scn ==

This scenario demonstrates different ways to use DDOs and DDDOs. Both types typically begin moving when the scenario starts, unless you assign a creation radius or control the DDO speed.

1. DDO: simple path follower.

2. DDDO (dependent path follower): includes a target path node and a target point. The
DDDO movement is constrained so when the specified object is at the target point, the DDDO will be at the target path node irrespective of the speed assigned to each node.
DDO and DDDOs can be pedestrians, animals or vehicles.

== Demo_ISAT_Display_Screen_Text.scn ==

This scenario demonstrates how to display text messages to the screen.

Text font, color and locations are specified at: NadsMiniSim_x.x\bin.x64\config\scenario_text.xml

'''*Be sure to maintain a backup if you edit this file!

See Also:
Demo_ISAT_Monitor_Driver_Speed.scn
Demo_ISAT_Show_Driver_Speed.scn

==Demo_ISAT_ENV_Dynamic_Fog.scn ==

This scenario demonstrates how to gradually apply fog and the difference between fog and visibility. The usual method of adding weather effects to a scenario is by defining a region of influence which means the effect is applied abruptly to the scene at the region boundaries (on/off).

*Fog and Visibility are Weather Effects
- Insert >> Environment Conditions
*Fog density is managed with 3 variables:
::#FogDistance
::#MaximumFog
::#FogDensity
*An example of reduced Visibility is included near the end of this drive to show how that setting is different from fog.

== Demo_ISAT_time_of_day.scn==

This scenario demonstrates how to change the time of day:

*Variables are used to track day-night cycles
*Time settings (Hour) were chosen arbitrarily
::'''Small time differences will not affect environment; ie. 07:10 – 07:30
*A parked F150 ADO in the scenario has auto-headlights enabled

'''NOTE: Headlight control from scenario requires changes to the miniSim hardware.xml configuration file – they do not automatically turn on at night

==Demo_ISAT_Exit_Simulation_on_Collision.scn ==

This scenario demonstrates how to terminate simulation if a collision happens during a drive. Collisions may occur with ADOs, DDOs, DDDOs and static objects that are present in the scene.

'''Note:
It is possible to configure miniSim or edit the scenario object list file (SOL2.txt) to disable collisions either globally or for specific objects. In that event this scenario will not terminate due to a collision.

==Demo_ISAT_Exit_Follow_Trigger_Create.scn ==

This scenario demonstrates use of the Follow Trigger:

*The follow trigger can activate between any two dynamic objects;
*Most commonly uses the XD for one of the two objects (leader or follower);
*Trigger instigator (predicate) can be either;
*The follow trigger action stack is processed when the trigger conditions have been met;
*When the actions are executed an oncoming Ambulance ADO is created.

== Demo_ISAT_Get_ObjTTC.scn==

This scenario demonstrates how to get a Time To Collision for dynamic and stationary objects (DDOs and ADOs):

*Any time delays in the action stack collecting data and reporting it will create a variance between what you measure in ISAT and what gets reported in the DAQ;
*Cells and variables are used to get the information for TTC and distance;
*Variables are written to SCC_Custom1 – 3 for distance, TTC and the raw distance value reported by GetObjDistPow2;
*3 events are shown to illustrate re-use of the same variables throughout for the target object:
::#DDO dynamic
::#DDO stationary
::#ADO stationary
*Logstreams are used for event numbering and distances to each object;
*If you re-use the same object name, you must remove the previous object – only 1 should be present in the simulation at any time.

'''NOTE:
Static objects cannot be created in realtime with the Create Element action, but they can be created as DDOs. They default to their first visual option; change with a set switch action.

==Demo_ISAT_Lane_Context_Actions.scn ==
This scenario demonstrates how to limit actions to a specific lane.

*Lane filter can only be used with roadpad triggers.
*Useful for situational cases: if the driver is in the correct lane, then they will not receive alert. If the driver is in the wrong lane, then they will.
*Also useful for ADO control at the lane level.

See also:
Demo_ISAT_ADO_Control.scn

==Demo_ISAT_Loop_Management_Traffic.scn ==

This scenario demonstrates how to configure a scenario where it is necessary to drive multiple loops:

*Increment a counter at the location the loop counts increase;
::Each time through the loop a unique action happens
::Increment and decrement operators are not expressions!
*Expression triggers fire on loops (one per loop);
*Can create more than ADOs.

==Demo_ISAT_Monitor_Driver_Speed.scn ==

This scenario demonstrates how to monitor driver velocity. Triggers are configured to monitor driving too slowly (under speed) and driving too fast. The threshold between under and over speed is intentionally difficult to maintain – the goal is to achieve a few alerts of either kind during the drive:

*Variable sets are used for under, over speed cases:
::a timer that increments a variable for each;
::an additional conditional (variable) so there is no alert at scenario start, while the driver is getting up to operating speed.

==Demo_ISAT_Play_Audio.scn ==

This scenario demonstrates how to play audio messages on miniSim using the write to cell >> SCC_Audio_Trigger action.
A short delay after the write to cell action is recommended.

'''Note:
'''Recommended practice requires a second write to cell action to ‘clear’ the previous audio message.

Playing two write to cell >> SCC_Audio_Trigger actions back to back with no delay, and no ‘clear’ likely results in a single audio message. For long messages, use the length of the message as a delay to avoid over-writing the message being played with any subsequent messages.

See also:

[[How to Use Audio in your Scenario|How_to_Use_Audio_in_your_Scenario]]

==Demo_ISAT_Right_Incursion.scn ==

This scenario demonstrates how to present a crash possible event using a right-side incursion:

• Ambient traffic and features are used during the drive; • The event is coupled with an oncoming vehicle distraction;
• The event is masked by features in the scene.

==Demo_ISAT_Set_Switch.scn ==

This scenario demonstrates how to change objects during a simulation with a Set Switch action (static object, DDO, ADO objects).

• The set switch action requires the model switch name;
• Switches for all models are listed in the file NadsMiniSim_x.x\bin.x64\ModelList.txt

==Demo_ISAT_Stop_Drive.scn ==

This scenario demonstrates how to terminate a simulation from the scenario:

• A roadpad trigger tells the driver it is time to stop and shift into park, and creates an Expression trigger to:
- monitor the transmission gear,
- terminate the simulation if the driver shifts into Park.
A Roadpad trigger acts as a backup that ends the drive if the XD doesn’t stop.

==Demo_ISAT_Show_Driver_Speed.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action.

* A time trigger is configured to monitor conditions; in this case, the external driver’s speed.
* The monitoring trigger is created by a roadpad trigger to ensure the driver is moving; therefore driver velocity is not zero.

* The monitoring trigger fires repeatedly during the drive.
* A variable is set to the value of a cell containing the driver velocity;
* That value is displayed on screen.

See Also:
:Demo_ISAT_Display_Screen_Text.scn
:Demo_ISAT_Monitor_Driver_Speed.scn

==Demo_ISAT_Track_Button_Press.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action:

• A time trigger This demo scenario uses expression triggers to detect button presses (turn signal activation).
• Variables are used to track which signal was activated (left vs. right) and demo progress.

'''Note:
'''The values used in the scenario may be site-specific; if your miniSim does not produce the values used, this scenario may fail.

To determine the correct values for your miniSim, drive any scenario and press the left, then the right turn signals and review this drive DAQ in ISAT. The relevant cell is CIS_Turn_Signal.

==Demo_ISAT_Traffic_Light.scn ==

This scenario demonstrates the use of a Traffic Light Trigger:

*A traffic light trigger activates at a specified signal state;
*Relies on a traffic light action to set the signal to a specified state;
*That state must already exist in the traffic signal timing table configuration for the intersection
::dbl-click on the traffic signal to open the signal timing table

*A more robust method would use a time to arrival (TTA) trigger that can accommodate different XD velocities or driving styles (conservative vs. aggressive, slow vs. fast) instead of the roadpad and delays used in this demo.

==Demo_ISAT_Virtual_Objects.scn ==

This scenario demonstrates how to display and control virtual objects during a drive. Virtual objects render to screen space on top of everything on display; they do not typically occupy 3d space within the scene.

One possible application for virtual objects is to use them as a custom heads up display (HUD) or alert system within the scenario.

By default virtual objects initialize to state 0 (off/disabled) at scenario start.

'''Note:
'''Currently only Render Type = Overlay and Main Screen are supported.

==Demo_ISAT_Yellow_Light_Dilemma.scn ==

This scenario demonstrates how to create a Yellow Light dilemma at an intersection.

#There must be a working signal state table;
#The traffic signal is controlled by a time to arrival (TTA) trigger;
#If the XD decides to stop, a roadpad trigger created by (2) will reset the signal to green so the XD can continue the drive;
#A roadpad trigger terminates the drive after the intersection.

ISAT Demonstration Scenarios

2023-09-15T15:22:26Z

Shawn Allen: /* Demo_ISAT_ADO_Random.scn */

== About the ISAT Demonstration Scenarios ==

Making something happen during a simulation in a repeatable and consistent fashion for different driving styles is the essence of scenario authoring. Every thing that happens must be coordinated to some degree with the External Driver (XD). For repeatability, it is also necessary to consider how different driving styles (aggressive vs. conservative) impact how the scenario unfolds for each.

These demonstration scenarios were created to facilitate learning how to use ISAT and do scenario actions. Each scenario demonstrates a key concept or element and may contain additional elements to support the main concept. For example, all scenarios contain an introduction to the scenario for the XD and a termination trigger that will stop the simulation.

'''These scenarios are not intended for use as completed data collection ready scenarios. They are provided to answer the question "how can I do X Y Z..?"

These scenario elements can be integrated into your scenarios using copy-paste except where elements have been created with a Create action. For those elements it will be necessary to copy the parent element instead.

TBC: Add a link to the library or directions how to get the files

== Demo_ISAT_ADO_Control.scn ==

This scenario demonstrates how to control an ADO:

• ADO set dial > forced velocity = 0 to keep ADO stationary.

• Release the forced velocity, assign a maintain gap.

• Release the maintain gap, assign a target velocity.

See also:
:Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn ==
This scenario demonstrates how to vary the velocity of an ADO using a Sum of Sines expression:

*Uses a forced velocity action;
*Try to maintain a constant speed at 30 mph;
*Notice how the speed of the ADO changes during the drive.

Note:
There is also a forced velocity Sin function available with 4 parameters

See Also:
:Demo_ISAT_ADO_Control.scn
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Oncoming_Incursion.scn ==
This scenario demonstrates the use of a forced lane offset to cause an oncoming ADO to veer into the driver’s lane:

*Additional ambient traffic is included to provide a normal driving environment;
*A following ADO will encourage slow drivers to travel the speed limit;
*Because we do not want to rely on the driver travelling at the right speed, we match the event ADO velocity to the driver to ensure the event happens as planned.

See Also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Passing_Maneuvers.scn ==
This scenario demonstrates how to implement an ADO passing maneuver on 4 lane and 2 lane roads:

*4 lane roads can use either Set Dial > ADO > Lane Change OR Set_Button > ADO > Lane Change;
*'''Lane change actions are not supported on 2 lane roads;
- Use a lane offset to produce something similar to a passing maneuver

See also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]

== Demo_ISAT_ADO_Random.scn ==

This scenario demonstrates how to use the Rand() function to assign a randomized gap to an ADO:

*Typical gap assignments are fixed/constant;
*Use of a randomized value introduces some inconsistency to the ADO position, which is organic and more realistic.
*Requires the use of variables and expressions.
*Saves the calculated randomizations to the DAQ for validation (review in ISAT).

See also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Relative_Create.scn ==

This scenario demonstrates how to use the Relative Create flag for ADOs.

'''Note:
'''Relative Create works only with negative values.

Used to create traffic behind the external driver independent of the location where the ADOs are initially placed.

See Also:

Demo_ISAT_ADO_Traffic_1.scn

== Demo_ISAT_ADO_Traffic_1.scn ==
This scenario demonstrates how to create traffic in a scenario:

*Create ADOs or copy/paste to locations within the drive;
*Create ADOs with a Creation Radius (they get created as the External Driver drives the route);
*Create ADOs with a trigger Create action;
*Generate traffic with a Traffic Source;
*Generate traffic with the Traffic Manager (or change TM sets).

Each method has advantages and disadvantages.

See Also:

Demo_ISAT_ADO_Relative_Create.scn

== Demo_ISAT_ADO_TTA_LVPO.scn ==

This scenario demonstrates the use of Time to Arrival trigger to create a crashpossible event:

*The scenario contains some distracting elements;
*The event ADO behavior is highly dependent on the speed of the XD.
- If the driver is going too fast it may cause the event ADO to disappear
*A time trigger with creation radius acts as a proximity trigger to end the drive, in case the driver steers out of the crash area.

See Also:

:Demo_ISAT_ADO_Control.scn
:Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn
:Demo_ISAT_ADO_Oncoming_Incursion.scn

== Demo_ISAT_Alert_Slow_Moving_Object.scn ==

This scenario demonstrates how to implement a proximity alert to warn the driver of a slow moving vehicle ahead:

*Speed monitor to ensure the driver is travelling at a velocity where the event can happen
*Alarm triggers when proximity threshold is achieved

Because there is no good way to tell in advance where the event happens, the end of drive happens following the alert.

== Demo_ISAT_Avoid_Obstacle.scn ==

This demo scenario demonstrates a collision avoidance event using ambient traffic and a DDO obstacle:

*The event requires some setup to position the event vehicles
*The obstacle is a DDO (desk) contained within a van model that has operable rear doors which swing open
*The DDO transitions from a coupled object to a free motion object

== Demo_ISAT_Create_Elements.scn ==

This scenario demonstrates how to create scenario elements during a drive with the Create Element action.

*Remember all triggers share the same actions; thus, any trigger may contain a create action.
*Only 1 create action is permitted per trigger.

== Demo_ISAT_Data_Measures_Default_Measures.scn ==

This scenario demonstrates how to use the miniSim Default Measures in a scenario to produce a valid report for the drive:

*Must follow the write to cell procedure for events:
:#initialize event status and event number to zero at scenario start
:#change SCC_EventStatus from 0 to 1 for the event, and close to 0 after the event
:#change SCC_EventNumber throughout the drive (incremental count starting with 1, 2, 3, etc.)
*Produces a report.txt for each drive
*The drive report.txt for each drive is located in the DAQ folder location.

'''Note: if proper write to cell steps aren’t followed, all measures will be empty in the report.

== Demo_ISAT_Data_Measures_Logstreams.scn ==

This scenario demonstrates the use of Log Streams for documenting significant locations or events in your DAQ file.

*Best practice: initialize all Logstreams to some value at the start.
*Events may be numbered, or subdivided using the same logstream. This demo uses LogStream 1.

*The scenario author and data reduction scientist must agree on what measures are important to encode.

== Demo_ISAT_DDOs.scn ==

This scenario demonstrates different ways to use DDOs and DDDOs. Both types typically begin moving when the scenario starts, unless you assign a creation radius or control the DDO speed.

1. DDO: simple path follower.

2. DDDO (dependent path follower): includes a target path node and a target point. The
DDDO movement is constrained so when the specified object is at the target point, the DDDO will be at the target path node irrespective of the speed assigned to each node.
DDO and DDDOs can be pedestrians, animals or vehicles.

== Demo_ISAT_Display_Screen_Text.scn ==

This scenario demonstrates how to display text messages to the screen.

Text font, color and locations are specified at: NadsMiniSim_x.x\bin.x64\config\scenario_text.xml

'''*Be sure to maintain a backup if you edit this file!

See Also:
Demo_ISAT_Monitor_Driver_Speed.scn
Demo_ISAT_Show_Driver_Speed.scn

==Demo_ISAT_ENV_Dynamic_Fog.scn ==

This scenario demonstrates how to gradually apply fog and the difference between fog and visibility. The usual method of adding weather effects to a scenario is by defining a region of influence which means the effect is applied abruptly to the scene at the region boundaries (on/off).

*Fog and Visibility are Weather Effects
- Insert >> Environment Conditions
*Fog density is managed with 3 variables:
::#FogDistance
::#MaximumFog
::#FogDensity
*An example of reduced Visibility is included near the end of this drive to show how that setting is different from fog.

== Demo_ISAT_time_of_day.scn==

This scenario demonstrates how to change the time of day:

*Variables are used to track day-night cycles
*Time settings (Hour) were chosen arbitrarily
::'''Small time differences will not affect environment; ie. 07:10 – 07:30
*A parked F150 ADO in the scenario has auto-headlights enabled

'''NOTE: Headlight control from scenario requires changes to the miniSim hardware.xml configuration file – they do not automatically turn on at night

==Demo_ISAT_Exit_Simulation_on_Collision.scn ==

This scenario demonstrates how to terminate simulation if a collision happens during a drive. Collisions may occur with ADOs, DDOs, DDDOs and static objects that are present in the scene.

'''Note:
It is possible to configure miniSim or edit the scenario object list file (SOL2.txt) to disable collisions either globally or for specific objects. In that event this scenario will not terminate due to a collision.

==Demo_ISAT_Exit_Follow_Trigger_Create.scn ==

This scenario demonstrates use of the Follow Trigger:

*The follow trigger can activate between any two dynamic objects;
*Most commonly uses the XD for one of the two objects (leader or follower);
*Trigger instigator (predicate) can be either;
*The follow trigger action stack is processed when the trigger conditions have been met;
*When the actions are executed an oncoming Ambulance ADO is created.

== Demo_ISAT_Get_ObjTTC.scn==

This scenario demonstrates how to get a Time To Collision for dynamic and stationary objects (DDOs and ADOs):

*Any time delays in the action stack collecting data and reporting it will create a variance between what you measure in ISAT and what gets reported in the DAQ;
*Cells and variables are used to get the information for TTC and distance;
*Variables are written to SCC_Custom1 – 3 for distance, TTC and the raw distance value reported by GetObjDistPow2;
*3 events are shown to illustrate re-use of the same variables throughout for the target object:
::#DDO dynamic
::#DDO stationary
::#ADO stationary
*Logstreams are used for event numbering and distances to each object;
*If you re-use the same object name, you must remove the previous object – only 1 should be present in the simulation at any time.

'''NOTE:
Static objects cannot be created in realtime with the Create Element action, but they can be created as DDOs. They default to their first visual option; change with a set switch action.

==Demo_ISAT_Lane_Context_Actions.scn ==
This scenario demonstrates how to limit actions to a specific lane.

*Lane filter can only be used with roadpad triggers.
*Useful for situational cases: if the driver is in the correct lane, then they will not receive alert. If the driver is in the wrong lane, then they will.
*Also useful for ADO control at the lane level.

See also:
Demo_ISAT_ADO_Control.scn

==Demo_ISAT_Loop_Management_Traffic.scn ==

This scenario demonstrates how to configure a scenario where it is necessary to drive multiple loops:

*Increment a counter at the location the loop counts increase;
::Each time through the loop a unique action happens
::Increment and decrement operators are not expressions!
*Expression triggers fire on loops (one per loop);
*Can create more than ADOs.

==Demo_ISAT_Monitor_Driver_Speed.scn ==

This scenario demonstrates how to monitor driver velocity. Triggers are configured to monitor driving too slowly (under speed) and driving too fast. The threshold between under and over speed is intentionally difficult to maintain – the goal is to achieve a few alerts of either kind during the drive:

*Variable sets are used for under, over speed cases:
::a timer that increments a variable for each;
::an additional conditional (variable) so there is no alert at scenario start, while the driver is getting up to operating speed.

==Demo_ISAT_Play_Audio.scn ==

This scenario demonstrates how to play audio messages on miniSim using the write to cell >> SCC_Audio_Trigger action.
A short delay after the write to cell action is recommended.

'''Note:
'''Recommended practice requires a second write to cell action to ‘clear’ the previous audio message.

Playing two write to cell >> SCC_Audio_Trigger actions back to back with no delay, and no ‘clear’ likely results in a single audio message. For long messages, use the length of the message as a delay to avoid over-writing the message being played with any subsequent messages.

See also:

[[How to Use Audio in your Scenario|How_to_Use_Audio_in_your_Scenario]]

==Demo_ISAT_Right_Incursion.scn ==

This scenario demonstrates how to present a crash possible event using a right-side incursion:

• Ambient traffic and features are used during the drive; • The event is coupled with an oncoming vehicle distraction;
• The event is masked by features in the scene.

==Demo_ISAT_Set_Switch.scn ==

This scenario demonstrates how to change objects during a simulation with a Set Switch action (static object, DDO, ADO objects).

• The set switch action requires the model switch name;
• Switches for all models are listed in the file NadsMiniSim_x.x\bin.x64\ModelList.txt

==Demo_ISAT_Stop_Drive.scn ==

This scenario demonstrates how to terminate a simulation from the scenario:

• A roadpad trigger tells the driver it is time to stop and shift into park, and creates an Expression trigger to:
- monitor the transmission gear,
- terminate the simulation if the driver shifts into Park.
A Roadpad trigger acts as a backup that ends the drive if the XD doesn’t stop.

==Demo_ISAT_Show_Driver_Speed.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action.

* A time trigger is configured to monitor conditions; in this case, the external driver’s speed.
* The monitoring trigger is created by a roadpad trigger to ensure the driver is moving; therefore driver velocity is not zero.

* The monitoring trigger fires repeatedly during the drive.
* A variable is set to the value of a cell containing the driver velocity;
* That value is displayed on screen.

See Also:
:Demo_ISAT_Display_Screen_Text.scn
:Demo_ISAT_Monitor_Driver_Speed.scn

==Demo_ISAT_Track_Button_Press.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action:

• A time trigger This demo scenario uses expression triggers to detect button presses (turn signal activation).
• Variables are used to track which signal was activated (left vs. right) and demo progress.

'''Note:
'''The values used in the scenario may be site-specific; if your miniSim does not produce the values used, this scenario may fail.

To determine the correct values for your miniSim, drive any scenario and press the left, then the right turn signals and review this drive DAQ in ISAT. The relevant cell is CIS_Turn_Signal.

==Demo_ISAT_Traffic_Light.scn ==

This scenario demonstrates the use of a Traffic Light Trigger:

*A traffic light trigger activates at a specified signal state;
*Relies on a traffic light action to set the signal to a specified state;
*That state must already exist in the traffic signal timing table configuration for the intersection
::dbl-click on the traffic signal to open the signal timing table

*A more robust method would use a time to arrival (TTA) trigger that can accommodate different XD velocities or driving styles (conservative vs. aggressive, slow vs. fast) instead of the roadpad and delays used in this demo.

==Demo_ISAT_Virtual_Objects.scn ==

This scenario demonstrates how to display and control virtual objects during a drive. Virtual objects render to screen space on top of everything on display; they do not typically occupy 3d space within the scene.

One possible application for virtual objects is to use them as a custom heads up display (HUD) or alert system within the scenario.

By default virtual objects initialize to state 0 (off/disabled) at scenario start.

'''Note:
'''Currently only Render Type = Overlay and Main Screen are supported.

==Demo_ISAT_Yellow_Light_Dilemma.scn ==

This scenario demonstrates how to create a Yellow Light dilemma at an intersection.

#There must be a working signal state table;
#The traffic signal is controlled by a time to arrival (TTA) trigger;
#If the XD decides to stop, a roadpad trigger created by (2) will reset the signal to green so the XD can continue the drive;
#A roadpad trigger terminates the drive after the intersection.

ISAT Demonstration Scenarios

2023-09-15T15:22:04Z

Shawn Allen: /* Demo_ISAT_ADO_Passing_Maneuvers.scn */

== About the ISAT Demonstration Scenarios ==

Making something happen during a simulation in a repeatable and consistent fashion for different driving styles is the essence of scenario authoring. Every thing that happens must be coordinated to some degree with the External Driver (XD). For repeatability, it is also necessary to consider how different driving styles (aggressive vs. conservative) impact how the scenario unfolds for each.

These demonstration scenarios were created to facilitate learning how to use ISAT and do scenario actions. Each scenario demonstrates a key concept or element and may contain additional elements to support the main concept. For example, all scenarios contain an introduction to the scenario for the XD and a termination trigger that will stop the simulation.

'''These scenarios are not intended for use as completed data collection ready scenarios. They are provided to answer the question "how can I do X Y Z..?"

These scenario elements can be integrated into your scenarios using copy-paste except where elements have been created with a Create action. For those elements it will be necessary to copy the parent element instead.

TBC: Add a link to the library or directions how to get the files

== Demo_ISAT_ADO_Control.scn ==

This scenario demonstrates how to control an ADO:

• ADO set dial > forced velocity = 0 to keep ADO stationary.

• Release the forced velocity, assign a maintain gap.

• Release the maintain gap, assign a target velocity.

See also:
:Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn ==
This scenario demonstrates how to vary the velocity of an ADO using a Sum of Sines expression:

*Uses a forced velocity action;
*Try to maintain a constant speed at 30 mph;
*Notice how the speed of the ADO changes during the drive.

Note:
There is also a forced velocity Sin function available with 4 parameters

See Also:
:Demo_ISAT_ADO_Control.scn
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Oncoming_Incursion.scn ==
This scenario demonstrates the use of a forced lane offset to cause an oncoming ADO to veer into the driver’s lane:

*Additional ambient traffic is included to provide a normal driving environment;
*A following ADO will encourage slow drivers to travel the speed limit;
*Because we do not want to rely on the driver travelling at the right speed, we match the event ADO velocity to the driver to ensure the event happens as planned.

See Also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Passing_Maneuvers.scn ==
This scenario demonstrates how to implement an ADO passing maneuver on 4 lane and 2 lane roads:

*4 lane roads can use either Set Dial > ADO > Lane Change OR Set_Button > ADO > Lane Change;
*'''Lane change actions are not supported on 2 lane roads;
- Use a lane offset to produce something similar to a passing maneuver

See also:

: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]

== Demo_ISAT_ADO_Random.scn ==

This scenario demonstrates how to use the Rand() function to assign a randomized gap to an ADO:

*Typical gap assignments are fixed/constant;
*Use of a randomized value introduces some inconsistency to the ADO position, which is organic and more realistic.
*Requires the use of variables and expressions.
*Saves the calculated randomizations to the DAQ for validation (review in ISAT).

See also:

:Demo_ISAT_ADO_Control.scn
:Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn
:Demo_ISAT_ADO_TTA_LVPO.scn

== Demo_ISAT_ADO_Relative_Create.scn ==

This scenario demonstrates how to use the Relative Create flag for ADOs.

'''Note:
'''Relative Create works only with negative values.

Used to create traffic behind the external driver independent of the location where the ADOs are initially placed.

See Also:

Demo_ISAT_ADO_Traffic_1.scn

== Demo_ISAT_ADO_Traffic_1.scn ==
This scenario demonstrates how to create traffic in a scenario:

*Create ADOs or copy/paste to locations within the drive;
*Create ADOs with a Creation Radius (they get created as the External Driver drives the route);
*Create ADOs with a trigger Create action;
*Generate traffic with a Traffic Source;
*Generate traffic with the Traffic Manager (or change TM sets).

Each method has advantages and disadvantages.

See Also:

Demo_ISAT_ADO_Relative_Create.scn

== Demo_ISAT_ADO_TTA_LVPO.scn ==

This scenario demonstrates the use of Time to Arrival trigger to create a crashpossible event:

*The scenario contains some distracting elements;
*The event ADO behavior is highly dependent on the speed of the XD.
- If the driver is going too fast it may cause the event ADO to disappear
*A time trigger with creation radius acts as a proximity trigger to end the drive, in case the driver steers out of the crash area.

See Also:

:Demo_ISAT_ADO_Control.scn
:Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn
:Demo_ISAT_ADO_Oncoming_Incursion.scn

== Demo_ISAT_Alert_Slow_Moving_Object.scn ==

This scenario demonstrates how to implement a proximity alert to warn the driver of a slow moving vehicle ahead:

*Speed monitor to ensure the driver is travelling at a velocity where the event can happen
*Alarm triggers when proximity threshold is achieved

Because there is no good way to tell in advance where the event happens, the end of drive happens following the alert.

== Demo_ISAT_Avoid_Obstacle.scn ==

This demo scenario demonstrates a collision avoidance event using ambient traffic and a DDO obstacle:

*The event requires some setup to position the event vehicles
*The obstacle is a DDO (desk) contained within a van model that has operable rear doors which swing open
*The DDO transitions from a coupled object to a free motion object

== Demo_ISAT_Create_Elements.scn ==

This scenario demonstrates how to create scenario elements during a drive with the Create Element action.

*Remember all triggers share the same actions; thus, any trigger may contain a create action.
*Only 1 create action is permitted per trigger.

== Demo_ISAT_Data_Measures_Default_Measures.scn ==

This scenario demonstrates how to use the miniSim Default Measures in a scenario to produce a valid report for the drive:

*Must follow the write to cell procedure for events:
:#initialize event status and event number to zero at scenario start
:#change SCC_EventStatus from 0 to 1 for the event, and close to 0 after the event
:#change SCC_EventNumber throughout the drive (incremental count starting with 1, 2, 3, etc.)
*Produces a report.txt for each drive
*The drive report.txt for each drive is located in the DAQ folder location.

'''Note: if proper write to cell steps aren’t followed, all measures will be empty in the report.

== Demo_ISAT_Data_Measures_Logstreams.scn ==

This scenario demonstrates the use of Log Streams for documenting significant locations or events in your DAQ file.

*Best practice: initialize all Logstreams to some value at the start.
*Events may be numbered, or subdivided using the same logstream. This demo uses LogStream 1.

*The scenario author and data reduction scientist must agree on what measures are important to encode.

== Demo_ISAT_DDOs.scn ==

This scenario demonstrates different ways to use DDOs and DDDOs. Both types typically begin moving when the scenario starts, unless you assign a creation radius or control the DDO speed.

1. DDO: simple path follower.

2. DDDO (dependent path follower): includes a target path node and a target point. The
DDDO movement is constrained so when the specified object is at the target point, the DDDO will be at the target path node irrespective of the speed assigned to each node.
DDO and DDDOs can be pedestrians, animals or vehicles.

== Demo_ISAT_Display_Screen_Text.scn ==

This scenario demonstrates how to display text messages to the screen.

Text font, color and locations are specified at: NadsMiniSim_x.x\bin.x64\config\scenario_text.xml

'''*Be sure to maintain a backup if you edit this file!

See Also:
Demo_ISAT_Monitor_Driver_Speed.scn
Demo_ISAT_Show_Driver_Speed.scn

==Demo_ISAT_ENV_Dynamic_Fog.scn ==

This scenario demonstrates how to gradually apply fog and the difference between fog and visibility. The usual method of adding weather effects to a scenario is by defining a region of influence which means the effect is applied abruptly to the scene at the region boundaries (on/off).

*Fog and Visibility are Weather Effects
- Insert >> Environment Conditions
*Fog density is managed with 3 variables:
::#FogDistance
::#MaximumFog
::#FogDensity
*An example of reduced Visibility is included near the end of this drive to show how that setting is different from fog.

== Demo_ISAT_time_of_day.scn==

This scenario demonstrates how to change the time of day:

*Variables are used to track day-night cycles
*Time settings (Hour) were chosen arbitrarily
::'''Small time differences will not affect environment; ie. 07:10 – 07:30
*A parked F150 ADO in the scenario has auto-headlights enabled

'''NOTE: Headlight control from scenario requires changes to the miniSim hardware.xml configuration file – they do not automatically turn on at night

==Demo_ISAT_Exit_Simulation_on_Collision.scn ==

This scenario demonstrates how to terminate simulation if a collision happens during a drive. Collisions may occur with ADOs, DDOs, DDDOs and static objects that are present in the scene.

'''Note:
It is possible to configure miniSim or edit the scenario object list file (SOL2.txt) to disable collisions either globally or for specific objects. In that event this scenario will not terminate due to a collision.

==Demo_ISAT_Exit_Follow_Trigger_Create.scn ==

This scenario demonstrates use of the Follow Trigger:

*The follow trigger can activate between any two dynamic objects;
*Most commonly uses the XD for one of the two objects (leader or follower);
*Trigger instigator (predicate) can be either;
*The follow trigger action stack is processed when the trigger conditions have been met;
*When the actions are executed an oncoming Ambulance ADO is created.

== Demo_ISAT_Get_ObjTTC.scn==

This scenario demonstrates how to get a Time To Collision for dynamic and stationary objects (DDOs and ADOs):

*Any time delays in the action stack collecting data and reporting it will create a variance between what you measure in ISAT and what gets reported in the DAQ;
*Cells and variables are used to get the information for TTC and distance;
*Variables are written to SCC_Custom1 – 3 for distance, TTC and the raw distance value reported by GetObjDistPow2;
*3 events are shown to illustrate re-use of the same variables throughout for the target object:
::#DDO dynamic
::#DDO stationary
::#ADO stationary
*Logstreams are used for event numbering and distances to each object;
*If you re-use the same object name, you must remove the previous object – only 1 should be present in the simulation at any time.

'''NOTE:
Static objects cannot be created in realtime with the Create Element action, but they can be created as DDOs. They default to their first visual option; change with a set switch action.

==Demo_ISAT_Lane_Context_Actions.scn ==
This scenario demonstrates how to limit actions to a specific lane.

*Lane filter can only be used with roadpad triggers.
*Useful for situational cases: if the driver is in the correct lane, then they will not receive alert. If the driver is in the wrong lane, then they will.
*Also useful for ADO control at the lane level.

See also:
Demo_ISAT_ADO_Control.scn

==Demo_ISAT_Loop_Management_Traffic.scn ==

This scenario demonstrates how to configure a scenario where it is necessary to drive multiple loops:

*Increment a counter at the location the loop counts increase;
::Each time through the loop a unique action happens
::Increment and decrement operators are not expressions!
*Expression triggers fire on loops (one per loop);
*Can create more than ADOs.

==Demo_ISAT_Monitor_Driver_Speed.scn ==

This scenario demonstrates how to monitor driver velocity. Triggers are configured to monitor driving too slowly (under speed) and driving too fast. The threshold between under and over speed is intentionally difficult to maintain – the goal is to achieve a few alerts of either kind during the drive:

*Variable sets are used for under, over speed cases:
::a timer that increments a variable for each;
::an additional conditional (variable) so there is no alert at scenario start, while the driver is getting up to operating speed.

==Demo_ISAT_Play_Audio.scn ==

This scenario demonstrates how to play audio messages on miniSim using the write to cell >> SCC_Audio_Trigger action.
A short delay after the write to cell action is recommended.

'''Note:
'''Recommended practice requires a second write to cell action to ‘clear’ the previous audio message.

Playing two write to cell >> SCC_Audio_Trigger actions back to back with no delay, and no ‘clear’ likely results in a single audio message. For long messages, use the length of the message as a delay to avoid over-writing the message being played with any subsequent messages.

See also:

[[How to Use Audio in your Scenario|How_to_Use_Audio_in_your_Scenario]]

==Demo_ISAT_Right_Incursion.scn ==

This scenario demonstrates how to present a crash possible event using a right-side incursion:

• Ambient traffic and features are used during the drive; • The event is coupled with an oncoming vehicle distraction;
• The event is masked by features in the scene.

==Demo_ISAT_Set_Switch.scn ==

This scenario demonstrates how to change objects during a simulation with a Set Switch action (static object, DDO, ADO objects).

• The set switch action requires the model switch name;
• Switches for all models are listed in the file NadsMiniSim_x.x\bin.x64\ModelList.txt

==Demo_ISAT_Stop_Drive.scn ==

This scenario demonstrates how to terminate a simulation from the scenario:

• A roadpad trigger tells the driver it is time to stop and shift into park, and creates an Expression trigger to:
- monitor the transmission gear,
- terminate the simulation if the driver shifts into Park.
A Roadpad trigger acts as a backup that ends the drive if the XD doesn’t stop.

==Demo_ISAT_Show_Driver_Speed.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action.

* A time trigger is configured to monitor conditions; in this case, the external driver’s speed.
* The monitoring trigger is created by a roadpad trigger to ensure the driver is moving; therefore driver velocity is not zero.

* The monitoring trigger fires repeatedly during the drive.
* A variable is set to the value of a cell containing the driver velocity;
* That value is displayed on screen.

See Also:
:Demo_ISAT_Display_Screen_Text.scn
:Demo_ISAT_Monitor_Driver_Speed.scn

==Demo_ISAT_Track_Button_Press.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action:

• A time trigger This demo scenario uses expression triggers to detect button presses (turn signal activation).
• Variables are used to track which signal was activated (left vs. right) and demo progress.

'''Note:
'''The values used in the scenario may be site-specific; if your miniSim does not produce the values used, this scenario may fail.

To determine the correct values for your miniSim, drive any scenario and press the left, then the right turn signals and review this drive DAQ in ISAT. The relevant cell is CIS_Turn_Signal.

==Demo_ISAT_Traffic_Light.scn ==

This scenario demonstrates the use of a Traffic Light Trigger:

*A traffic light trigger activates at a specified signal state;
*Relies on a traffic light action to set the signal to a specified state;
*That state must already exist in the traffic signal timing table configuration for the intersection
::dbl-click on the traffic signal to open the signal timing table

*A more robust method would use a time to arrival (TTA) trigger that can accommodate different XD velocities or driving styles (conservative vs. aggressive, slow vs. fast) instead of the roadpad and delays used in this demo.

==Demo_ISAT_Virtual_Objects.scn ==

This scenario demonstrates how to display and control virtual objects during a drive. Virtual objects render to screen space on top of everything on display; they do not typically occupy 3d space within the scene.

One possible application for virtual objects is to use them as a custom heads up display (HUD) or alert system within the scenario.

By default virtual objects initialize to state 0 (off/disabled) at scenario start.

'''Note:
'''Currently only Render Type = Overlay and Main Screen are supported.

==Demo_ISAT_Yellow_Light_Dilemma.scn ==

This scenario demonstrates how to create a Yellow Light dilemma at an intersection.

#There must be a working signal state table;
#The traffic signal is controlled by a time to arrival (TTA) trigger;
#If the XD decides to stop, a roadpad trigger created by (2) will reset the signal to green so the XD can continue the drive;
#A roadpad trigger terminates the drive after the intersection.

ISAT Demonstration Scenarios

2023-09-15T15:21:37Z

Shawn Allen: /* Demo_ISAT_ADO_Oncoming_Incursion.scn add links to see also scn*/

== About the ISAT Demonstration Scenarios ==

Making something happen during a simulation in a repeatable and consistent fashion for different driving styles is the essence of scenario authoring. Every thing that happens must be coordinated to some degree with the External Driver (XD). For repeatability, it is also necessary to consider how different driving styles (aggressive vs. conservative) impact how the scenario unfolds for each.

These demonstration scenarios were created to facilitate learning how to use ISAT and do scenario actions. Each scenario demonstrates a key concept or element and may contain additional elements to support the main concept. For example, all scenarios contain an introduction to the scenario for the XD and a termination trigger that will stop the simulation.

'''These scenarios are not intended for use as completed data collection ready scenarios. They are provided to answer the question "how can I do X Y Z..?"

These scenario elements can be integrated into your scenarios using copy-paste except where elements have been created with a Create action. For those elements it will be necessary to copy the parent element instead.

TBC: Add a link to the library or directions how to get the files

== Demo_ISAT_ADO_Control.scn ==

This scenario demonstrates how to control an ADO:

• ADO set dial > forced velocity = 0 to keep ADO stationary.

• Release the forced velocity, assign a maintain gap.

• Release the maintain gap, assign a target velocity.

See also:
:Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn ==
This scenario demonstrates how to vary the velocity of an ADO using a Sum of Sines expression:

*Uses a forced velocity action;
*Try to maintain a constant speed at 30 mph;
*Notice how the speed of the ADO changes during the drive.

Note:
There is also a forced velocity Sin function available with 4 parameters

See Also:
:Demo_ISAT_ADO_Control.scn
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Oncoming_Incursion.scn ==
This scenario demonstrates the use of a forced lane offset to cause an oncoming ADO to veer into the driver’s lane:

*Additional ambient traffic is included to provide a normal driving environment;
*A following ADO will encourage slow drivers to travel the speed limit;
*Because we do not want to rely on the driver travelling at the right speed, we match the event ADO velocity to the driver to ensure the event happens as planned.

See Also:
: [[#Demo_ISAT_ADO_Control.scn|Demo_ISAT_ADO_Control.scn]]
: [[#Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn|Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Passing_Maneuvers.scn ==
This scenario demonstrates how to implement an ADO passing maneuver on 4 lane and 2 lane roads:

*4 lane roads can use either Set Dial > ADO > Lane Change OR Set_Button > ADO > Lane Change;
*'''Lane change actions are not supported on 2 lane roads;
- Use a lane offset to produce something similar to a passing maneuver

See also:

Demo_ISAT_ADO_Control.scn

== Demo_ISAT_ADO_Random.scn ==

This scenario demonstrates how to use the Rand() function to assign a randomized gap to an ADO:

*Typical gap assignments are fixed/constant;
*Use of a randomized value introduces some inconsistency to the ADO position, which is organic and more realistic.
*Requires the use of variables and expressions.
*Saves the calculated randomizations to the DAQ for validation (review in ISAT).

See also:

:Demo_ISAT_ADO_Control.scn
:Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn
:Demo_ISAT_ADO_TTA_LVPO.scn

== Demo_ISAT_ADO_Relative_Create.scn ==

This scenario demonstrates how to use the Relative Create flag for ADOs.

'''Note:
'''Relative Create works only with negative values.

Used to create traffic behind the external driver independent of the location where the ADOs are initially placed.

See Also:

Demo_ISAT_ADO_Traffic_1.scn

== Demo_ISAT_ADO_Traffic_1.scn ==
This scenario demonstrates how to create traffic in a scenario:

*Create ADOs or copy/paste to locations within the drive;
*Create ADOs with a Creation Radius (they get created as the External Driver drives the route);
*Create ADOs with a trigger Create action;
*Generate traffic with a Traffic Source;
*Generate traffic with the Traffic Manager (or change TM sets).

Each method has advantages and disadvantages.

See Also:

Demo_ISAT_ADO_Relative_Create.scn

== Demo_ISAT_ADO_TTA_LVPO.scn ==

This scenario demonstrates the use of Time to Arrival trigger to create a crashpossible event:

*The scenario contains some distracting elements;
*The event ADO behavior is highly dependent on the speed of the XD.
- If the driver is going too fast it may cause the event ADO to disappear
*A time trigger with creation radius acts as a proximity trigger to end the drive, in case the driver steers out of the crash area.

See Also:

:Demo_ISAT_ADO_Control.scn
:Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn
:Demo_ISAT_ADO_Oncoming_Incursion.scn

== Demo_ISAT_Alert_Slow_Moving_Object.scn ==

This scenario demonstrates how to implement a proximity alert to warn the driver of a slow moving vehicle ahead:

*Speed monitor to ensure the driver is travelling at a velocity where the event can happen
*Alarm triggers when proximity threshold is achieved

Because there is no good way to tell in advance where the event happens, the end of drive happens following the alert.

== Demo_ISAT_Avoid_Obstacle.scn ==

This demo scenario demonstrates a collision avoidance event using ambient traffic and a DDO obstacle:

*The event requires some setup to position the event vehicles
*The obstacle is a DDO (desk) contained within a van model that has operable rear doors which swing open
*The DDO transitions from a coupled object to a free motion object

== Demo_ISAT_Create_Elements.scn ==

This scenario demonstrates how to create scenario elements during a drive with the Create Element action.

*Remember all triggers share the same actions; thus, any trigger may contain a create action.
*Only 1 create action is permitted per trigger.

== Demo_ISAT_Data_Measures_Default_Measures.scn ==

This scenario demonstrates how to use the miniSim Default Measures in a scenario to produce a valid report for the drive:

*Must follow the write to cell procedure for events:
:#initialize event status and event number to zero at scenario start
:#change SCC_EventStatus from 0 to 1 for the event, and close to 0 after the event
:#change SCC_EventNumber throughout the drive (incremental count starting with 1, 2, 3, etc.)
*Produces a report.txt for each drive
*The drive report.txt for each drive is located in the DAQ folder location.

'''Note: if proper write to cell steps aren’t followed, all measures will be empty in the report.

== Demo_ISAT_Data_Measures_Logstreams.scn ==

This scenario demonstrates the use of Log Streams for documenting significant locations or events in your DAQ file.

*Best practice: initialize all Logstreams to some value at the start.
*Events may be numbered, or subdivided using the same logstream. This demo uses LogStream 1.

*The scenario author and data reduction scientist must agree on what measures are important to encode.

== Demo_ISAT_DDOs.scn ==

This scenario demonstrates different ways to use DDOs and DDDOs. Both types typically begin moving when the scenario starts, unless you assign a creation radius or control the DDO speed.

1. DDO: simple path follower.

2. DDDO (dependent path follower): includes a target path node and a target point. The
DDDO movement is constrained so when the specified object is at the target point, the DDDO will be at the target path node irrespective of the speed assigned to each node.
DDO and DDDOs can be pedestrians, animals or vehicles.

== Demo_ISAT_Display_Screen_Text.scn ==

This scenario demonstrates how to display text messages to the screen.

Text font, color and locations are specified at: NadsMiniSim_x.x\bin.x64\config\scenario_text.xml

'''*Be sure to maintain a backup if you edit this file!

See Also:
Demo_ISAT_Monitor_Driver_Speed.scn
Demo_ISAT_Show_Driver_Speed.scn

==Demo_ISAT_ENV_Dynamic_Fog.scn ==

This scenario demonstrates how to gradually apply fog and the difference between fog and visibility. The usual method of adding weather effects to a scenario is by defining a region of influence which means the effect is applied abruptly to the scene at the region boundaries (on/off).

*Fog and Visibility are Weather Effects
- Insert >> Environment Conditions
*Fog density is managed with 3 variables:
::#FogDistance
::#MaximumFog
::#FogDensity
*An example of reduced Visibility is included near the end of this drive to show how that setting is different from fog.

== Demo_ISAT_time_of_day.scn==

This scenario demonstrates how to change the time of day:

*Variables are used to track day-night cycles
*Time settings (Hour) were chosen arbitrarily
::'''Small time differences will not affect environment; ie. 07:10 – 07:30
*A parked F150 ADO in the scenario has auto-headlights enabled

'''NOTE: Headlight control from scenario requires changes to the miniSim hardware.xml configuration file – they do not automatically turn on at night

==Demo_ISAT_Exit_Simulation_on_Collision.scn ==

This scenario demonstrates how to terminate simulation if a collision happens during a drive. Collisions may occur with ADOs, DDOs, DDDOs and static objects that are present in the scene.

'''Note:
It is possible to configure miniSim or edit the scenario object list file (SOL2.txt) to disable collisions either globally or for specific objects. In that event this scenario will not terminate due to a collision.

==Demo_ISAT_Exit_Follow_Trigger_Create.scn ==

This scenario demonstrates use of the Follow Trigger:

*The follow trigger can activate between any two dynamic objects;
*Most commonly uses the XD for one of the two objects (leader or follower);
*Trigger instigator (predicate) can be either;
*The follow trigger action stack is processed when the trigger conditions have been met;
*When the actions are executed an oncoming Ambulance ADO is created.

== Demo_ISAT_Get_ObjTTC.scn==

This scenario demonstrates how to get a Time To Collision for dynamic and stationary objects (DDOs and ADOs):

*Any time delays in the action stack collecting data and reporting it will create a variance between what you measure in ISAT and what gets reported in the DAQ;
*Cells and variables are used to get the information for TTC and distance;
*Variables are written to SCC_Custom1 – 3 for distance, TTC and the raw distance value reported by GetObjDistPow2;
*3 events are shown to illustrate re-use of the same variables throughout for the target object:
::#DDO dynamic
::#DDO stationary
::#ADO stationary
*Logstreams are used for event numbering and distances to each object;
*If you re-use the same object name, you must remove the previous object – only 1 should be present in the simulation at any time.

'''NOTE:
Static objects cannot be created in realtime with the Create Element action, but they can be created as DDOs. They default to their first visual option; change with a set switch action.

==Demo_ISAT_Lane_Context_Actions.scn ==
This scenario demonstrates how to limit actions to a specific lane.

*Lane filter can only be used with roadpad triggers.
*Useful for situational cases: if the driver is in the correct lane, then they will not receive alert. If the driver is in the wrong lane, then they will.
*Also useful for ADO control at the lane level.

See also:
Demo_ISAT_ADO_Control.scn

==Demo_ISAT_Loop_Management_Traffic.scn ==

This scenario demonstrates how to configure a scenario where it is necessary to drive multiple loops:

*Increment a counter at the location the loop counts increase;
::Each time through the loop a unique action happens
::Increment and decrement operators are not expressions!
*Expression triggers fire on loops (one per loop);
*Can create more than ADOs.

==Demo_ISAT_Monitor_Driver_Speed.scn ==

This scenario demonstrates how to monitor driver velocity. Triggers are configured to monitor driving too slowly (under speed) and driving too fast. The threshold between under and over speed is intentionally difficult to maintain – the goal is to achieve a few alerts of either kind during the drive:

*Variable sets are used for under, over speed cases:
::a timer that increments a variable for each;
::an additional conditional (variable) so there is no alert at scenario start, while the driver is getting up to operating speed.

==Demo_ISAT_Play_Audio.scn ==

This scenario demonstrates how to play audio messages on miniSim using the write to cell >> SCC_Audio_Trigger action.
A short delay after the write to cell action is recommended.

'''Note:
'''Recommended practice requires a second write to cell action to ‘clear’ the previous audio message.

Playing two write to cell >> SCC_Audio_Trigger actions back to back with no delay, and no ‘clear’ likely results in a single audio message. For long messages, use the length of the message as a delay to avoid over-writing the message being played with any subsequent messages.

See also:

[[How to Use Audio in your Scenario|How_to_Use_Audio_in_your_Scenario]]

==Demo_ISAT_Right_Incursion.scn ==

This scenario demonstrates how to present a crash possible event using a right-side incursion:

• Ambient traffic and features are used during the drive; • The event is coupled with an oncoming vehicle distraction;
• The event is masked by features in the scene.

==Demo_ISAT_Set_Switch.scn ==

This scenario demonstrates how to change objects during a simulation with a Set Switch action (static object, DDO, ADO objects).

• The set switch action requires the model switch name;
• Switches for all models are listed in the file NadsMiniSim_x.x\bin.x64\ModelList.txt

==Demo_ISAT_Stop_Drive.scn ==

This scenario demonstrates how to terminate a simulation from the scenario:

• A roadpad trigger tells the driver it is time to stop and shift into park, and creates an Expression trigger to:
- monitor the transmission gear,
- terminate the simulation if the driver shifts into Park.
A Roadpad trigger acts as a backup that ends the drive if the XD doesn’t stop.

==Demo_ISAT_Show_Driver_Speed.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action.

* A time trigger is configured to monitor conditions; in this case, the external driver’s speed.
* The monitoring trigger is created by a roadpad trigger to ensure the driver is moving; therefore driver velocity is not zero.

* The monitoring trigger fires repeatedly during the drive.
* A variable is set to the value of a cell containing the driver velocity;
* That value is displayed on screen.

See Also:
:Demo_ISAT_Display_Screen_Text.scn
:Demo_ISAT_Monitor_Driver_Speed.scn

==Demo_ISAT_Track_Button_Press.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action:

• A time trigger This demo scenario uses expression triggers to detect button presses (turn signal activation).
• Variables are used to track which signal was activated (left vs. right) and demo progress.

'''Note:
'''The values used in the scenario may be site-specific; if your miniSim does not produce the values used, this scenario may fail.

To determine the correct values for your miniSim, drive any scenario and press the left, then the right turn signals and review this drive DAQ in ISAT. The relevant cell is CIS_Turn_Signal.

==Demo_ISAT_Traffic_Light.scn ==

This scenario demonstrates the use of a Traffic Light Trigger:

*A traffic light trigger activates at a specified signal state;
*Relies on a traffic light action to set the signal to a specified state;
*That state must already exist in the traffic signal timing table configuration for the intersection
::dbl-click on the traffic signal to open the signal timing table

*A more robust method would use a time to arrival (TTA) trigger that can accommodate different XD velocities or driving styles (conservative vs. aggressive, slow vs. fast) instead of the roadpad and delays used in this demo.

==Demo_ISAT_Virtual_Objects.scn ==

This scenario demonstrates how to display and control virtual objects during a drive. Virtual objects render to screen space on top of everything on display; they do not typically occupy 3d space within the scene.

One possible application for virtual objects is to use them as a custom heads up display (HUD) or alert system within the scenario.

By default virtual objects initialize to state 0 (off/disabled) at scenario start.

'''Note:
'''Currently only Render Type = Overlay and Main Screen are supported.

==Demo_ISAT_Yellow_Light_Dilemma.scn ==

This scenario demonstrates how to create a Yellow Light dilemma at an intersection.

#There must be a working signal state table;
#The traffic signal is controlled by a time to arrival (TTA) trigger;
#If the XD decides to stop, a roadpad trigger created by (2) will reset the signal to green so the XD can continue the drive;
#A roadpad trigger terminates the drive after the intersection.

ISAT Demonstration Scenarios

2023-09-15T15:18:24Z

Shawn Allen: /* Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn add links to see also scn*/

== About the ISAT Demonstration Scenarios ==

Making something happen during a simulation in a repeatable and consistent fashion for different driving styles is the essence of scenario authoring. Every thing that happens must be coordinated to some degree with the External Driver (XD). For repeatability, it is also necessary to consider how different driving styles (aggressive vs. conservative) impact how the scenario unfolds for each.

These demonstration scenarios were created to facilitate learning how to use ISAT and do scenario actions. Each scenario demonstrates a key concept or element and may contain additional elements to support the main concept. For example, all scenarios contain an introduction to the scenario for the XD and a termination trigger that will stop the simulation.

'''These scenarios are not intended for use as completed data collection ready scenarios. They are provided to answer the question "how can I do X Y Z..?"

These scenario elements can be integrated into your scenarios using copy-paste except where elements have been created with a Create action. For those elements it will be necessary to copy the parent element instead.

TBC: Add a link to the library or directions how to get the files

== Demo_ISAT_ADO_Control.scn ==

This scenario demonstrates how to control an ADO:

• ADO set dial > forced velocity = 0 to keep ADO stationary.

• Release the forced velocity, assign a maintain gap.

• Release the maintain gap, assign a target velocity.

See also:
:Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn ==
This scenario demonstrates how to vary the velocity of an ADO using a Sum of Sines expression:

*Uses a forced velocity action;
*Try to maintain a constant speed at 30 mph;
*Notice how the speed of the ADO changes during the drive.

Note:
There is also a forced velocity Sin function available with 4 parameters

See Also:
:Demo_ISAT_ADO_Control.scn
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Oncoming_Incursion.scn ==
This scenario demonstrates the use of a forced lane offset to cause an oncoming ADO to veer into the driver’s lane:

*Additional ambient traffic is included to provide a normal driving environment;
*A following ADO will encourage slow drivers to travel the speed limit;
*Because we do not want to rely on the driver travelling at the right speed, we match the event ADO velocity to the driver to ensure the event happens as planned.

See Also:
:Demo_ISAT_ADO_Control.scn
:Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn
:Demo_ISAT_ADO_TTA_LVPO.scn

== Demo_ISAT_ADO_Passing_Maneuvers.scn ==
This scenario demonstrates how to implement an ADO passing maneuver on 4 lane and 2 lane roads:

*4 lane roads can use either Set Dial > ADO > Lane Change OR Set_Button > ADO > Lane Change;
*'''Lane change actions are not supported on 2 lane roads;
- Use a lane offset to produce something similar to a passing maneuver

See also:

Demo_ISAT_ADO_Control.scn

== Demo_ISAT_ADO_Random.scn ==

This scenario demonstrates how to use the Rand() function to assign a randomized gap to an ADO:

*Typical gap assignments are fixed/constant;
*Use of a randomized value introduces some inconsistency to the ADO position, which is organic and more realistic.
*Requires the use of variables and expressions.
*Saves the calculated randomizations to the DAQ for validation (review in ISAT).

See also:

:Demo_ISAT_ADO_Control.scn
:Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn
:Demo_ISAT_ADO_TTA_LVPO.scn

== Demo_ISAT_ADO_Relative_Create.scn ==

This scenario demonstrates how to use the Relative Create flag for ADOs.

'''Note:
'''Relative Create works only with negative values.

Used to create traffic behind the external driver independent of the location where the ADOs are initially placed.

See Also:

Demo_ISAT_ADO_Traffic_1.scn

== Demo_ISAT_ADO_Traffic_1.scn ==
This scenario demonstrates how to create traffic in a scenario:

*Create ADOs or copy/paste to locations within the drive;
*Create ADOs with a Creation Radius (they get created as the External Driver drives the route);
*Create ADOs with a trigger Create action;
*Generate traffic with a Traffic Source;
*Generate traffic with the Traffic Manager (or change TM sets).

Each method has advantages and disadvantages.

See Also:

Demo_ISAT_ADO_Relative_Create.scn

== Demo_ISAT_ADO_TTA_LVPO.scn ==

This scenario demonstrates the use of Time to Arrival trigger to create a crashpossible event:

*The scenario contains some distracting elements;
*The event ADO behavior is highly dependent on the speed of the XD.
- If the driver is going too fast it may cause the event ADO to disappear
*A time trigger with creation radius acts as a proximity trigger to end the drive, in case the driver steers out of the crash area.

See Also:

:Demo_ISAT_ADO_Control.scn
:Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn
:Demo_ISAT_ADO_Oncoming_Incursion.scn

== Demo_ISAT_Alert_Slow_Moving_Object.scn ==

This scenario demonstrates how to implement a proximity alert to warn the driver of a slow moving vehicle ahead:

*Speed monitor to ensure the driver is travelling at a velocity where the event can happen
*Alarm triggers when proximity threshold is achieved

Because there is no good way to tell in advance where the event happens, the end of drive happens following the alert.

== Demo_ISAT_Avoid_Obstacle.scn ==

This demo scenario demonstrates a collision avoidance event using ambient traffic and a DDO obstacle:

*The event requires some setup to position the event vehicles
*The obstacle is a DDO (desk) contained within a van model that has operable rear doors which swing open
*The DDO transitions from a coupled object to a free motion object

== Demo_ISAT_Create_Elements.scn ==

This scenario demonstrates how to create scenario elements during a drive with the Create Element action.

*Remember all triggers share the same actions; thus, any trigger may contain a create action.
*Only 1 create action is permitted per trigger.

== Demo_ISAT_Data_Measures_Default_Measures.scn ==

This scenario demonstrates how to use the miniSim Default Measures in a scenario to produce a valid report for the drive:

*Must follow the write to cell procedure for events:
:#initialize event status and event number to zero at scenario start
:#change SCC_EventStatus from 0 to 1 for the event, and close to 0 after the event
:#change SCC_EventNumber throughout the drive (incremental count starting with 1, 2, 3, etc.)
*Produces a report.txt for each drive
*The drive report.txt for each drive is located in the DAQ folder location.

'''Note: if proper write to cell steps aren’t followed, all measures will be empty in the report.

== Demo_ISAT_Data_Measures_Logstreams.scn ==

This scenario demonstrates the use of Log Streams for documenting significant locations or events in your DAQ file.

*Best practice: initialize all Logstreams to some value at the start.
*Events may be numbered, or subdivided using the same logstream. This demo uses LogStream 1.

*The scenario author and data reduction scientist must agree on what measures are important to encode.

== Demo_ISAT_DDOs.scn ==

This scenario demonstrates different ways to use DDOs and DDDOs. Both types typically begin moving when the scenario starts, unless you assign a creation radius or control the DDO speed.

1. DDO: simple path follower.

2. DDDO (dependent path follower): includes a target path node and a target point. The
DDDO movement is constrained so when the specified object is at the target point, the DDDO will be at the target path node irrespective of the speed assigned to each node.
DDO and DDDOs can be pedestrians, animals or vehicles.

== Demo_ISAT_Display_Screen_Text.scn ==

This scenario demonstrates how to display text messages to the screen.

Text font, color and locations are specified at: NadsMiniSim_x.x\bin.x64\config\scenario_text.xml

'''*Be sure to maintain a backup if you edit this file!

See Also:
Demo_ISAT_Monitor_Driver_Speed.scn
Demo_ISAT_Show_Driver_Speed.scn

==Demo_ISAT_ENV_Dynamic_Fog.scn ==

This scenario demonstrates how to gradually apply fog and the difference between fog and visibility. The usual method of adding weather effects to a scenario is by defining a region of influence which means the effect is applied abruptly to the scene at the region boundaries (on/off).

*Fog and Visibility are Weather Effects
- Insert >> Environment Conditions
*Fog density is managed with 3 variables:
::#FogDistance
::#MaximumFog
::#FogDensity
*An example of reduced Visibility is included near the end of this drive to show how that setting is different from fog.

== Demo_ISAT_time_of_day.scn==

This scenario demonstrates how to change the time of day:

*Variables are used to track day-night cycles
*Time settings (Hour) were chosen arbitrarily
::'''Small time differences will not affect environment; ie. 07:10 – 07:30
*A parked F150 ADO in the scenario has auto-headlights enabled

'''NOTE: Headlight control from scenario requires changes to the miniSim hardware.xml configuration file – they do not automatically turn on at night

==Demo_ISAT_Exit_Simulation_on_Collision.scn ==

This scenario demonstrates how to terminate simulation if a collision happens during a drive. Collisions may occur with ADOs, DDOs, DDDOs and static objects that are present in the scene.

'''Note:
It is possible to configure miniSim or edit the scenario object list file (SOL2.txt) to disable collisions either globally or for specific objects. In that event this scenario will not terminate due to a collision.

==Demo_ISAT_Exit_Follow_Trigger_Create.scn ==

This scenario demonstrates use of the Follow Trigger:

*The follow trigger can activate between any two dynamic objects;
*Most commonly uses the XD for one of the two objects (leader or follower);
*Trigger instigator (predicate) can be either;
*The follow trigger action stack is processed when the trigger conditions have been met;
*When the actions are executed an oncoming Ambulance ADO is created.

== Demo_ISAT_Get_ObjTTC.scn==

This scenario demonstrates how to get a Time To Collision for dynamic and stationary objects (DDOs and ADOs):

*Any time delays in the action stack collecting data and reporting it will create a variance between what you measure in ISAT and what gets reported in the DAQ;
*Cells and variables are used to get the information for TTC and distance;
*Variables are written to SCC_Custom1 – 3 for distance, TTC and the raw distance value reported by GetObjDistPow2;
*3 events are shown to illustrate re-use of the same variables throughout for the target object:
::#DDO dynamic
::#DDO stationary
::#ADO stationary
*Logstreams are used for event numbering and distances to each object;
*If you re-use the same object name, you must remove the previous object – only 1 should be present in the simulation at any time.

'''NOTE:
Static objects cannot be created in realtime with the Create Element action, but they can be created as DDOs. They default to their first visual option; change with a set switch action.

==Demo_ISAT_Lane_Context_Actions.scn ==
This scenario demonstrates how to limit actions to a specific lane.

*Lane filter can only be used with roadpad triggers.
*Useful for situational cases: if the driver is in the correct lane, then they will not receive alert. If the driver is in the wrong lane, then they will.
*Also useful for ADO control at the lane level.

See also:
Demo_ISAT_ADO_Control.scn

==Demo_ISAT_Loop_Management_Traffic.scn ==

This scenario demonstrates how to configure a scenario where it is necessary to drive multiple loops:

*Increment a counter at the location the loop counts increase;
::Each time through the loop a unique action happens
::Increment and decrement operators are not expressions!
*Expression triggers fire on loops (one per loop);
*Can create more than ADOs.

==Demo_ISAT_Monitor_Driver_Speed.scn ==

This scenario demonstrates how to monitor driver velocity. Triggers are configured to monitor driving too slowly (under speed) and driving too fast. The threshold between under and over speed is intentionally difficult to maintain – the goal is to achieve a few alerts of either kind during the drive:

*Variable sets are used for under, over speed cases:
::a timer that increments a variable for each;
::an additional conditional (variable) so there is no alert at scenario start, while the driver is getting up to operating speed.

==Demo_ISAT_Play_Audio.scn ==

This scenario demonstrates how to play audio messages on miniSim using the write to cell >> SCC_Audio_Trigger action.
A short delay after the write to cell action is recommended.

'''Note:
'''Recommended practice requires a second write to cell action to ‘clear’ the previous audio message.

Playing two write to cell >> SCC_Audio_Trigger actions back to back with no delay, and no ‘clear’ likely results in a single audio message. For long messages, use the length of the message as a delay to avoid over-writing the message being played with any subsequent messages.

See also:

[[How to Use Audio in your Scenario|How_to_Use_Audio_in_your_Scenario]]

==Demo_ISAT_Right_Incursion.scn ==

This scenario demonstrates how to present a crash possible event using a right-side incursion:

• Ambient traffic and features are used during the drive; • The event is coupled with an oncoming vehicle distraction;
• The event is masked by features in the scene.

==Demo_ISAT_Set_Switch.scn ==

This scenario demonstrates how to change objects during a simulation with a Set Switch action (static object, DDO, ADO objects).

• The set switch action requires the model switch name;
• Switches for all models are listed in the file NadsMiniSim_x.x\bin.x64\ModelList.txt

==Demo_ISAT_Stop_Drive.scn ==

This scenario demonstrates how to terminate a simulation from the scenario:

• A roadpad trigger tells the driver it is time to stop and shift into park, and creates an Expression trigger to:
- monitor the transmission gear,
- terminate the simulation if the driver shifts into Park.
A Roadpad trigger acts as a backup that ends the drive if the XD doesn’t stop.

==Demo_ISAT_Show_Driver_Speed.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action.

* A time trigger is configured to monitor conditions; in this case, the external driver’s speed.
* The monitoring trigger is created by a roadpad trigger to ensure the driver is moving; therefore driver velocity is not zero.

* The monitoring trigger fires repeatedly during the drive.
* A variable is set to the value of a cell containing the driver velocity;
* That value is displayed on screen.

See Also:
:Demo_ISAT_Display_Screen_Text.scn
:Demo_ISAT_Monitor_Driver_Speed.scn

==Demo_ISAT_Track_Button_Press.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action:

• A time trigger This demo scenario uses expression triggers to detect button presses (turn signal activation).
• Variables are used to track which signal was activated (left vs. right) and demo progress.

'''Note:
'''The values used in the scenario may be site-specific; if your miniSim does not produce the values used, this scenario may fail.

To determine the correct values for your miniSim, drive any scenario and press the left, then the right turn signals and review this drive DAQ in ISAT. The relevant cell is CIS_Turn_Signal.

==Demo_ISAT_Traffic_Light.scn ==

This scenario demonstrates the use of a Traffic Light Trigger:

*A traffic light trigger activates at a specified signal state;
*Relies on a traffic light action to set the signal to a specified state;
*That state must already exist in the traffic signal timing table configuration for the intersection
::dbl-click on the traffic signal to open the signal timing table

*A more robust method would use a time to arrival (TTA) trigger that can accommodate different XD velocities or driving styles (conservative vs. aggressive, slow vs. fast) instead of the roadpad and delays used in this demo.

==Demo_ISAT_Virtual_Objects.scn ==

This scenario demonstrates how to display and control virtual objects during a drive. Virtual objects render to screen space on top of everything on display; they do not typically occupy 3d space within the scene.

One possible application for virtual objects is to use them as a custom heads up display (HUD) or alert system within the scenario.

By default virtual objects initialize to state 0 (off/disabled) at scenario start.

'''Note:
'''Currently only Render Type = Overlay and Main Screen are supported.

==Demo_ISAT_Yellow_Light_Dilemma.scn ==

This scenario demonstrates how to create a Yellow Light dilemma at an intersection.

#There must be a working signal state table;
#The traffic signal is controlled by a time to arrival (TTA) trigger;
#If the XD decides to stop, a roadpad trigger created by (2) will reset the signal to green so the XD can continue the drive;
#A roadpad trigger terminates the drive after the intersection.

ISAT Demonstration Scenarios

2023-09-15T15:16:59Z

Shawn Allen: /* Demo_ISAT_ADO_Control.scn add links to see also scenarios*/

== About the ISAT Demonstration Scenarios ==

Making something happen during a simulation in a repeatable and consistent fashion for different driving styles is the essence of scenario authoring. Every thing that happens must be coordinated to some degree with the External Driver (XD). For repeatability, it is also necessary to consider how different driving styles (aggressive vs. conservative) impact how the scenario unfolds for each.

These demonstration scenarios were created to facilitate learning how to use ISAT and do scenario actions. Each scenario demonstrates a key concept or element and may contain additional elements to support the main concept. For example, all scenarios contain an introduction to the scenario for the XD and a termination trigger that will stop the simulation.

'''These scenarios are not intended for use as completed data collection ready scenarios. They are provided to answer the question "how can I do X Y Z..?"

These scenario elements can be integrated into your scenarios using copy-paste except where elements have been created with a Create action. For those elements it will be necessary to copy the parent element instead.

TBC: Add a link to the library or directions how to get the files

== Demo_ISAT_ADO_Control.scn ==

This scenario demonstrates how to control an ADO:

• ADO set dial > forced velocity = 0 to keep ADO stationary.

• Release the forced velocity, assign a maintain gap.

• Release the maintain gap, assign a target velocity.

See also:
:Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn
: [[#Demo_ISAT_ADO_Oncoming_Incursion.scn|Demo_ISAT_ADO_Oncoming_Incursion.scn]]
: [[#Demo_ISAT_ADO_TTA_LVPO.scn|Demo_ISAT_ADO_TTA_LVPO.scn]]

== Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn ==
This scenario demonstrates how to vary the velocity of an ADO using a Sum of Sines expression:

*Uses a forced velocity action;
*Try to maintain a constant speed at 30 mph;
*Notice how the speed of the ADO changes during the drive.

Note:
There is also a forced velocity Sin function available with 4 parameters

See Also:
:Demo_ISAT_ADO_Control.scn
:Demo_ISAT_ADO_Oncoming_Incursion.scn
:Demo_ISAT_ADO_TTA_LVPO.scn

== Demo_ISAT_ADO_Oncoming_Incursion.scn ==
This scenario demonstrates the use of a forced lane offset to cause an oncoming ADO to veer into the driver’s lane:

*Additional ambient traffic is included to provide a normal driving environment;
*A following ADO will encourage slow drivers to travel the speed limit;
*Because we do not want to rely on the driver travelling at the right speed, we match the event ADO velocity to the driver to ensure the event happens as planned.

See Also:
:Demo_ISAT_ADO_Control.scn
:Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn
:Demo_ISAT_ADO_TTA_LVPO.scn

== Demo_ISAT_ADO_Passing_Maneuvers.scn ==
This scenario demonstrates how to implement an ADO passing maneuver on 4 lane and 2 lane roads:

*4 lane roads can use either Set Dial > ADO > Lane Change OR Set_Button > ADO > Lane Change;
*'''Lane change actions are not supported on 2 lane roads;
- Use a lane offset to produce something similar to a passing maneuver

See also:

Demo_ISAT_ADO_Control.scn

== Demo_ISAT_ADO_Random.scn ==

This scenario demonstrates how to use the Rand() function to assign a randomized gap to an ADO:

*Typical gap assignments are fixed/constant;
*Use of a randomized value introduces some inconsistency to the ADO position, which is organic and more realistic.
*Requires the use of variables and expressions.
*Saves the calculated randomizations to the DAQ for validation (review in ISAT).

See also:

:Demo_ISAT_ADO_Control.scn
:Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn
:Demo_ISAT_ADO_TTA_LVPO.scn

== Demo_ISAT_ADO_Relative_Create.scn ==

This scenario demonstrates how to use the Relative Create flag for ADOs.

'''Note:
'''Relative Create works only with negative values.

Used to create traffic behind the external driver independent of the location where the ADOs are initially placed.

See Also:

Demo_ISAT_ADO_Traffic_1.scn

== Demo_ISAT_ADO_Traffic_1.scn ==
This scenario demonstrates how to create traffic in a scenario:

*Create ADOs or copy/paste to locations within the drive;
*Create ADOs with a Creation Radius (they get created as the External Driver drives the route);
*Create ADOs with a trigger Create action;
*Generate traffic with a Traffic Source;
*Generate traffic with the Traffic Manager (or change TM sets).

Each method has advantages and disadvantages.

See Also:

Demo_ISAT_ADO_Relative_Create.scn

== Demo_ISAT_ADO_TTA_LVPO.scn ==

This scenario demonstrates the use of Time to Arrival trigger to create a crashpossible event:

*The scenario contains some distracting elements;
*The event ADO behavior is highly dependent on the speed of the XD.
- If the driver is going too fast it may cause the event ADO to disappear
*A time trigger with creation radius acts as a proximity trigger to end the drive, in case the driver steers out of the crash area.

See Also:

:Demo_ISAT_ADO_Control.scn
:Demo_ISAT_ADO_Forced_Velocity_Sum_of_Sines.scn
:Demo_ISAT_ADO_Oncoming_Incursion.scn

== Demo_ISAT_Alert_Slow_Moving_Object.scn ==

This scenario demonstrates how to implement a proximity alert to warn the driver of a slow moving vehicle ahead:

*Speed monitor to ensure the driver is travelling at a velocity where the event can happen
*Alarm triggers when proximity threshold is achieved

Because there is no good way to tell in advance where the event happens, the end of drive happens following the alert.

== Demo_ISAT_Avoid_Obstacle.scn ==

This demo scenario demonstrates a collision avoidance event using ambient traffic and a DDO obstacle:

*The event requires some setup to position the event vehicles
*The obstacle is a DDO (desk) contained within a van model that has operable rear doors which swing open
*The DDO transitions from a coupled object to a free motion object

== Demo_ISAT_Create_Elements.scn ==

This scenario demonstrates how to create scenario elements during a drive with the Create Element action.

*Remember all triggers share the same actions; thus, any trigger may contain a create action.
*Only 1 create action is permitted per trigger.

== Demo_ISAT_Data_Measures_Default_Measures.scn ==

This scenario demonstrates how to use the miniSim Default Measures in a scenario to produce a valid report for the drive:

*Must follow the write to cell procedure for events:
:#initialize event status and event number to zero at scenario start
:#change SCC_EventStatus from 0 to 1 for the event, and close to 0 after the event
:#change SCC_EventNumber throughout the drive (incremental count starting with 1, 2, 3, etc.)
*Produces a report.txt for each drive
*The drive report.txt for each drive is located in the DAQ folder location.

'''Note: if proper write to cell steps aren’t followed, all measures will be empty in the report.

== Demo_ISAT_Data_Measures_Logstreams.scn ==

This scenario demonstrates the use of Log Streams for documenting significant locations or events in your DAQ file.

*Best practice: initialize all Logstreams to some value at the start.
*Events may be numbered, or subdivided using the same logstream. This demo uses LogStream 1.

*The scenario author and data reduction scientist must agree on what measures are important to encode.

== Demo_ISAT_DDOs.scn ==

This scenario demonstrates different ways to use DDOs and DDDOs. Both types typically begin moving when the scenario starts, unless you assign a creation radius or control the DDO speed.

1. DDO: simple path follower.

2. DDDO (dependent path follower): includes a target path node and a target point. The
DDDO movement is constrained so when the specified object is at the target point, the DDDO will be at the target path node irrespective of the speed assigned to each node.
DDO and DDDOs can be pedestrians, animals or vehicles.

== Demo_ISAT_Display_Screen_Text.scn ==

This scenario demonstrates how to display text messages to the screen.

Text font, color and locations are specified at: NadsMiniSim_x.x\bin.x64\config\scenario_text.xml

'''*Be sure to maintain a backup if you edit this file!

See Also:
Demo_ISAT_Monitor_Driver_Speed.scn
Demo_ISAT_Show_Driver_Speed.scn

==Demo_ISAT_ENV_Dynamic_Fog.scn ==

This scenario demonstrates how to gradually apply fog and the difference between fog and visibility. The usual method of adding weather effects to a scenario is by defining a region of influence which means the effect is applied abruptly to the scene at the region boundaries (on/off).

*Fog and Visibility are Weather Effects
- Insert >> Environment Conditions
*Fog density is managed with 3 variables:
::#FogDistance
::#MaximumFog
::#FogDensity
*An example of reduced Visibility is included near the end of this drive to show how that setting is different from fog.

== Demo_ISAT_time_of_day.scn==

This scenario demonstrates how to change the time of day:

*Variables are used to track day-night cycles
*Time settings (Hour) were chosen arbitrarily
::'''Small time differences will not affect environment; ie. 07:10 – 07:30
*A parked F150 ADO in the scenario has auto-headlights enabled

'''NOTE: Headlight control from scenario requires changes to the miniSim hardware.xml configuration file – they do not automatically turn on at night

==Demo_ISAT_Exit_Simulation_on_Collision.scn ==

This scenario demonstrates how to terminate simulation if a collision happens during a drive. Collisions may occur with ADOs, DDOs, DDDOs and static objects that are present in the scene.

'''Note:
It is possible to configure miniSim or edit the scenario object list file (SOL2.txt) to disable collisions either globally or for specific objects. In that event this scenario will not terminate due to a collision.

==Demo_ISAT_Exit_Follow_Trigger_Create.scn ==

This scenario demonstrates use of the Follow Trigger:

*The follow trigger can activate between any two dynamic objects;
*Most commonly uses the XD for one of the two objects (leader or follower);
*Trigger instigator (predicate) can be either;
*The follow trigger action stack is processed when the trigger conditions have been met;
*When the actions are executed an oncoming Ambulance ADO is created.

== Demo_ISAT_Get_ObjTTC.scn==

This scenario demonstrates how to get a Time To Collision for dynamic and stationary objects (DDOs and ADOs):

*Any time delays in the action stack collecting data and reporting it will create a variance between what you measure in ISAT and what gets reported in the DAQ;
*Cells and variables are used to get the information for TTC and distance;
*Variables are written to SCC_Custom1 – 3 for distance, TTC and the raw distance value reported by GetObjDistPow2;
*3 events are shown to illustrate re-use of the same variables throughout for the target object:
::#DDO dynamic
::#DDO stationary
::#ADO stationary
*Logstreams are used for event numbering and distances to each object;
*If you re-use the same object name, you must remove the previous object – only 1 should be present in the simulation at any time.

'''NOTE:
Static objects cannot be created in realtime with the Create Element action, but they can be created as DDOs. They default to their first visual option; change with a set switch action.

==Demo_ISAT_Lane_Context_Actions.scn ==
This scenario demonstrates how to limit actions to a specific lane.

*Lane filter can only be used with roadpad triggers.
*Useful for situational cases: if the driver is in the correct lane, then they will not receive alert. If the driver is in the wrong lane, then they will.
*Also useful for ADO control at the lane level.

See also:
Demo_ISAT_ADO_Control.scn

==Demo_ISAT_Loop_Management_Traffic.scn ==

This scenario demonstrates how to configure a scenario where it is necessary to drive multiple loops:

*Increment a counter at the location the loop counts increase;
::Each time through the loop a unique action happens
::Increment and decrement operators are not expressions!
*Expression triggers fire on loops (one per loop);
*Can create more than ADOs.

==Demo_ISAT_Monitor_Driver_Speed.scn ==

This scenario demonstrates how to monitor driver velocity. Triggers are configured to monitor driving too slowly (under speed) and driving too fast. The threshold between under and over speed is intentionally difficult to maintain – the goal is to achieve a few alerts of either kind during the drive:

*Variable sets are used for under, over speed cases:
::a timer that increments a variable for each;
::an additional conditional (variable) so there is no alert at scenario start, while the driver is getting up to operating speed.

==Demo_ISAT_Play_Audio.scn ==

This scenario demonstrates how to play audio messages on miniSim using the write to cell >> SCC_Audio_Trigger action.
A short delay after the write to cell action is recommended.

'''Note:
'''Recommended practice requires a second write to cell action to ‘clear’ the previous audio message.

Playing two write to cell >> SCC_Audio_Trigger actions back to back with no delay, and no ‘clear’ likely results in a single audio message. For long messages, use the length of the message as a delay to avoid over-writing the message being played with any subsequent messages.

See also:

[[How to Use Audio in your Scenario|How_to_Use_Audio_in_your_Scenario]]

==Demo_ISAT_Right_Incursion.scn ==

This scenario demonstrates how to present a crash possible event using a right-side incursion:

• Ambient traffic and features are used during the drive; • The event is coupled with an oncoming vehicle distraction;
• The event is masked by features in the scene.

==Demo_ISAT_Set_Switch.scn ==

This scenario demonstrates how to change objects during a simulation with a Set Switch action (static object, DDO, ADO objects).

• The set switch action requires the model switch name;
• Switches for all models are listed in the file NadsMiniSim_x.x\bin.x64\ModelList.txt

==Demo_ISAT_Stop_Drive.scn ==

This scenario demonstrates how to terminate a simulation from the scenario:

• A roadpad trigger tells the driver it is time to stop and shift into park, and creates an Expression trigger to:
- monitor the transmission gear,
- terminate the simulation if the driver shifts into Park.
A Roadpad trigger acts as a backup that ends the drive if the XD doesn’t stop.

==Demo_ISAT_Show_Driver_Speed.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action.

* A time trigger is configured to monitor conditions; in this case, the external driver’s speed.
* The monitoring trigger is created by a roadpad trigger to ensure the driver is moving; therefore driver velocity is not zero.

* The monitoring trigger fires repeatedly during the drive.
* A variable is set to the value of a cell containing the driver velocity;
* That value is displayed on screen.

See Also:
:Demo_ISAT_Display_Screen_Text.scn
:Demo_ISAT_Monitor_Driver_Speed.scn

==Demo_ISAT_Track_Button_Press.scn ==

This scenario demonstrates how to display variables on screen using the Set Visual Display Text action:

• A time trigger This demo scenario uses expression triggers to detect button presses (turn signal activation).
• Variables are used to track which signal was activated (left vs. right) and demo progress.

'''Note:
'''The values used in the scenario may be site-specific; if your miniSim does not produce the values used, this scenario may fail.

To determine the correct values for your miniSim, drive any scenario and press the left, then the right turn signals and review this drive DAQ in ISAT. The relevant cell is CIS_Turn_Signal.

==Demo_ISAT_Traffic_Light.scn ==

This scenario demonstrates the use of a Traffic Light Trigger:

*A traffic light trigger activates at a specified signal state;
*Relies on a traffic light action to set the signal to a specified state;
*That state must already exist in the traffic signal timing table configuration for the intersection
::dbl-click on the traffic signal to open the signal timing table

*A more robust method would use a time to arrival (TTA) trigger that can accommodate different XD velocities or driving styles (conservative vs. aggressive, slow vs. fast) instead of the roadpad and delays used in this demo.

==Demo_ISAT_Virtual_Objects.scn ==

This scenario demonstrates how to display and control virtual objects during a drive. Virtual objects render to screen space on top of everything on display; they do not typically occupy 3d space within the scene.

One possible application for virtual objects is to use them as a custom heads up display (HUD) or alert system within the scenario.

By default virtual objects initialize to state 0 (off/disabled) at scenario start.

'''Note:
'''Currently only Render Type = Overlay and Main Screen are supported.

==Demo_ISAT_Yellow_Light_Dilemma.scn ==

This scenario demonstrates how to create a Yellow Light dilemma at an intersection.

#There must be a working signal state table;
#The traffic signal is controlled by a time to arrival (TTA) trigger;
#If the XD decides to stop, a roadpad trigger created by (2) will reset the signal to green so the XD can continue the drive;
#A roadpad trigger terminates the drive after the intersection.

APPENDIX B

2023-09-15T15:08:50Z

Shawn Allen: /* MiniSim Data Acquisition Cell Definitions add email link for more complete docs */

APPENDIX B

2023-09-15T15:05:14Z

Shawn Allen: /* MiniSim Data Acquisition Cell Definitions add a partial list verbage*/

ISAT User Guide Table of Contents

2023-09-15T15:02:18Z

Shawn Allen: /* What is ISAT? add more info about isat*/

== Who should use this document? ==
Anyone learning to use the DSRI 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
*CTL-<some other key>: Press and hold the Ctrl and then press <some other key>. Most typically used for copy (CTRL-C) or paste (CTRL-V).
*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 and modify for use in your own scenarios as needed.

== <span style="color:#FF0000"> '''Known Issues'''</span>==

Added 2022.07.01 '''Relative Creation''' does not currently work for ADOs on miniSim.

'''Expression clarification'''

Increment and decrement operators (++, --) are not considered expressions by behaviors. They should not be flagged as expressions when used in the Value field of a Set Variable action.

Added 2019.11.07 '''File reset issue'''

ISAT has a long-standing bug which can reset your static object options when your scenario file is saved to disk.

'''It is strongly recommended that you use [[#External_Reference|external reference scenario files]] to avoid this. '''ISAT does not reset static object options in the xref file.

Added 2021.12.29 Expression Triggers and Values

'''Using Values in Expression Triggers'''

To ensure proper execution of expression triggers, it is recommended that the values used include the desired range by decreasing the lower threshold or increasing the upper threshold '''instead of using the exact value.'''

For example, to process values in a range (7031 - 7040):

[[File:2021-12-29_12h38_09.png|400px]]

'''Note: remember that negative values must be calculated since the expression parser does not parse negative values otherwise.'''

For example, to properly parse a specific transmission gear (Park):
'''ReadCell('CFS_Auto_Transmission_Mode', 1) = ( 0 - 2 )'''

<span style="color:#FF0000"> '''Rehearsal without specifying a start location</span>

In some cases ISAT will crash if the external driver (XD)/start location has not been specified or is missing due to a sol2 file configuration error.

=='''ISAT Overview & Interface Basics'''==
This section contains information about ISAT and the ISAT interface.

===What is ISAT?===
ISAT is the DSRI 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 uses resource files that are based on the model objects found in the miniSim. They are proxy objects for the real models used during simulation.

ISAT contains a rudimentary scripting language for automating some repetitive tasks. Scripting is an advanced topic. Because the scripting language is not well documented, it is recommended to copy existing scripts that perform similar functions and modify them.

Because ISAT scenarios are text, you can make some edits quickly and easily using any text editor.

'''However:

When editing a scenario as text, always work on a backup copy in case something goes wrong in the text editing process that invalidates the scenario file to the point where ISAT cannot read it!

===ISAT is NOT:===
ISAT is <span style="color:#FF0000">'''not an object editor'''</span> 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.
[[File:miniSim_scenario_compnents.png|center|640px]]

*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.

[[File:anatomy_of_a_scenario.png|center|400px]]

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

[[File:scenario_as_text.png|center|640px]]

This diagram shows the same scenario in (left to right) 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, <u>always</u> check your edits in ISAT!'''
*Copy/Paste - delete paths from elements when the BLI is different between your source & destination BLI files. The following scenario elements contain paths:
::ADO (with a path specified)
:: Any roadpad trigger (roadpad, Time to Arrival, Follow)

'''NOTE: A Traffic Source is not a portable element but it can be re-created in ISAT or integrated into a new scenario by copying the element from the source scenario then using a text editor to paste it into the destination scenario'''

'''How can I find information in multiple files easily?'''

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.

What if you don't know what to look for? How do 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
[[File:action_overview.png|400px||border|caption]]

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)

==='''Adding an action to a trigger'''===

The following example uses a Time Trigger; remember that '''all triggers share the same actions'''.

To add an action to a trigger you can double-click on the trigger, navigate to the '''Actions''' panel, and click on New to create a new action.

[[File:2022-11-30_12h47_23.png|400px]]

The possible actions are listed under the '''Action Type''' drop-down menu.

[[File:2022-11-30_12h47_44.png|400px]]

Actions are arranged in a 'stack' and are processed from top to bottom. If you use multiple actions you should enable the '''sequential flag''' to ensure each action is executed in sequence. Without the sequential flag, actions will be processed as fast as the simulator behaviors can execute.

[[File:2022-11-30_12h52_58.png|400px]]

Actions may be re-ordered in the stack using the '''arrows''' located near the action stack list.

=='''ISAT Modes of Operation'''==
[[File:ISAT_modes_of_operation.png|400px]]

*Edit
*Rehearsal
*DAQ playback
*Monitor '''Currently not available'''

==='''Edit & Rehearsal Modes'''===

*Edit - this is where scenario authors will spend the most time.
::Creation or modification of scenario
::Link to or import portions of other scenario elements

[[File:mode_edit.png|400px]]

*Rehearsal
::Debug & test scenario
::Simulates scenario using Behaviors and Vehicle Dynamics
::Displays error messages from behaviors

[[File:mode_rehearsal.png|400px]]

'''NOTE:''' Rehearsal mode <span style="color:#FF0000">simulates </span>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

[[File:mode_playback.png|400px]]

==='''miniSim Scenario Components'''===

The following diagram shows an overview of scenario related components of the NADS miniSim and how these components work together.

[[File:miniSim_scenario_components_wDAQ.png|400px]]

=='''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.

[[File:isat_workspace_general.png|400px]]

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)
[[File:isat_status_bar_overview.png|400px]]

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.

[[File:isat_user_prefs_status_bar_settings.png|400px]]

====ISAT Iconography====
ISAT provides graphic hints for triggers placed in scenario that can be useful when editing or maintaining scenarios.

The general format is a border enclosing miniature icons of the trigger and first action contained in that trigger. Additional information representing one or many actions is also shown.

[[File:hints1.png|400px]]

ISAT will list all trigger actions when a trigger is selected, but these hints provide a way to quickly identify what actions have been authored.

[[File:hint2.png|400px]]

*A Roadpad trigger, one action: '''Traffic Light Action'''
*B Roadpad trigger, multiple actions, first action is '''Remove Element'''
*C Roadpad trigger, multiple actions, first action is '''Set Dial'''
*D Roadpad trigger, constrained to road (lane), no actions - this is an empty trigger
*E Roadpad trigger, multiple actions, first action is '''Log Data'''
*F Global Time Trigger, single action: '''Set Dial'''

[[File:handle.png|400px]]

The element handle is the red dot visible in most of the triggers.
The handle can be dragged into position, and the trigger will follow the handle

Drag the trigger off the handle to offset it's location from the handle

==='''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.

[[File:object_types_isat.png|400px]]

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
::*Traffic Source

:'''NOTE:''' Virtual objects are defined in the scenario, not in the SOL2.
[[File:object_types_world.png|400px]]

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.
::NOTE: 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.

==='''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:
#Follow a path using kinematics
#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:
#coupled
#relative trajectory
#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'''===
Traffic signals are objects with special operation and function; they are coupled to intersections and routes of travel through intersections to control traffic flow similiar to their function in the real world. Traffic signals are part of the source tile model and may not be re-positioned or physically altered by scenario except for their visual signal state appearance; i.e., red, green or yellow signals.

To control intersection traffic signals use Edit >> Traffic Light ManagerTraffic signals use a Signal State Table (SST) to control which signal states are active and when. Each intersection with traffic signals will have an associated SST.

[[File:traffic_light_state_manager.png|400px]]

The above diagram shows an intersection in the workspace to the right, and the traffic signal state table for that intersection on the left. At this point additional states (for signal condition) can be added by clicking the '''Add state button'''.

[[File:traffic_signal_state_table2.png|400px]]

The above diagram shows two states defined for the intersection, represented by the two columns of state condition.

Continue adding states until the desired signal cycle has been defined. Generally this consists of red, green or yellow states.

NOTE: There is currently no way to automatically author a series of traffic light signals

To author traffic signal lights in sequence or on a route, the scenario author has to manage the signal states

[[File:traffic_signal_state_duration.png|400px]]

To edit the signal state duration RMB on the duration field header and choosing '''Edit state duration''' on the context menu. Enter the desired value then click OK.

====Traffic Signal Types====
The ISAT status bar reports Traffic Signal Type name. There are two signal types:
#Standard signal - IDs may have no identifying information
:Valid signal states: Red, Yellow, Green, Flashing Red, Flashing Yellow, OFF
#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

[[File:traffic_light_extended_type_name_normal.png|400px]]
: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.

[[File:traffic_light_extended_type_name.png|400px]]

===Changing Signal States in Scenario===
Traffic signals are controlled in scenario by using a Traffic Signal Action to change the SST.

'''NOTE:''' The Traffic Signal Action works by changing the SST, '''not by changing the traffic signal.''' This is a subtle but important difference.

Setting a signal to an undefined state effectively does nothing to the traffic signal.

[[File:traffic_light_state_table.png|400px]]

The above diagram shows a fully populated SST, with one signal row highlighted in red, and one state column highlighted in green. The associated intersection corridor is highlighted, showing the signal controls a dedicated left turn.

During simulation, the initial signal state is defined by the left column. As the simulation proceeds, the signal state changes according to the duration states defined across the state table, proceeding left to right and then wrapping around to the beginning after the last defined state. Each traffic signal appearance changes according to the configuration of the SST.

As a driver approaches this intersection, assume the signal state is in the column left of the highlighted column ('''R'''ed), and the desired action is to change the signal to green.

The action used to change a traffic signal state is the '''Traffic Light Action'''.
Using a traffic light action requires the specification of a signal state, the traffic signal to affect, and a duration.

[[File:traffic_signal_action1.png|400px]]

In the above diagram the scenario author has specified the desired state as '''Green''' as shown in the action dialog.

However, referring back to the previous state table diagram, there is no such state present in the SST. That means this particular action will fail, and the traffic signal will not change as the driver approaches the intersection - because the action does not create a new signal state, it works by advancing the state table condition (column) to the specified condition. If the condition is not present in the SST then nothing will appear to happen.

In this example, the action should be edited to use the correct signal state '''Left Turn Green''', which is present in the SST.

'''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

[[File:known_issue_traffic_light_action.png|400px]]

'''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.

[[File:known_issue_traffic_light_action_workaround.png|400px]]

====Change A Traffic Light Using Scenario Action====
To change a traffic signal, use the Set Dial >> Traffic Light action.
'''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

[[File:traffic_light_state_table.png|400px]]

This diagram shows a fully populated traffic signal state change for an intersection.

*Static object traffic lights
:These are objects, not true traffic signals and so they are not controlled with the Traffic Light manager.

==='''Traffic Source'''===
A traffic source is a coordinator used to create traffic at specific locations in the road map (unlike the Traffic Manager). This is useful for creating ambient traffic. Traffic Sources creates ADOs or DDOs at random or user-specified intervals.

Elements created using a Traffic Source will be created at the locations specified by the user. If traffic is specified at multiple locations the actual location for each creation will be determined randomly during simulation.

'''Note:''' Using the Relative Creation flag on ADOs created by the traffic source will not create traffic at the specified location on the map, but use the information in the Relative Creation fields to populate traffic in the scene during simulation.

This method allows for more flexibility but care must be taken not to create so many ADOs that miniSim is unable to make frame rate. Too many ADOs will cause the scene to jump and 'jitter' and it will feel slower than normal.

==='''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 ISAT scenario rehearsal

===Custom (icon) file virtual objects===

[[File:virtual_object_custom_icon_file.png|400px]]

'''Note:''' Some versions of MiniSim_2.3 do not support custom virtual objects. For those installs, if you require this type of functionality, a workaround exists in the form of a 2D model that can be customized (i.e, sprite).

Virtual objects may be customized using graphics files (texture images) to display any desired custom element. This typically requires the use of a bitmap graphic. Various file formats are supported: JPG, BMP, PNG. It is possible some types of these formats may not work - in those cases, try an alternate format.

If image transparency is required and the custom icon does not display during simulation, please email dsri-minisim@uiowa.edu with a description of the issue, your scenario and custom virtual object image file.

Custom icon files must be located within the Nads MiniSim path for resources - at NadsMiniSim_x.x\data\visuals\Models\ModelTx.

===Standard virtual object shapes===
The virtual object shapes include:
# Circle
# Triangle
# Octagon
# Star
# Diamond
# Icon <- this is for custom virtual object graphics
# Rectangle
# Hexagon

The virtual object fill and border color and transparency can be set in the virtual object properties dialog panel.

[[File:virtual_object_std_shape.png|400px]]

====Virtual Object Workaround====

There is a scenario authoring method that can be used to emulate virtual object functionality through the use of a DDO that is coupled to any dynamic scene element, including the External Driver. One model has been created to support this method called "sprite".

'''Note:''' The sprite model is a 2D object present in the scene, and can therefore be occluded by other scene elements during simulation.

[[File:trafsign_sprite.jpg|400px]]

The sprite model is designed as a flat plane that continuously faces the viewer. It contains different sized planes and can be customized through textures.

When authoring your scenario, configure the sprite object to Off unless it should be visible at scenario start. During the scenario you can control the sprite appearance with a setSwitch action.

[[File:sprite_setSwitch_action_021121.png|400px]]

The who to effect should use the name of the DDO placed in your scenario. The switch name will be s_sprite as shown above. Any valid option can be used. An invalid option (greater than 30) will disable the sprite the same as selecting the OFF option.

==='''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'''===
<span style="color:#FF0000">'''All trigger types share the same Action types'''</span>
*IF Then conditional
*Predicate: i.e., the activating agent
:If predicate is TRUE, then do Action(s)
*Road related triggers are categorized by predicate type
:Named element
:Road (lane)
:Nth vehicle on path only

'''What trigger is appropriate?'''
To determine which trigger is most appropriate, consider the task you are trying to accomplish. '''The differences between triggers is their activation methods.'''

'''Global Time Trigger'''
[[File:isat_time_trigger.png|150px]]

Use this trigger when something has to happen at some point in time.

Time triggers are also useful as "placeholder triggers"; used to apply persistent actions to multiple elements with unique settings for each element. Normally a persistent action is the last action possible in a trigger since the persistent action fires continuously. Putting persistent actions into a time trigger allows the scenario author to continue an action stack in the parent trigger if necessary.

Time triggers can be used as a 'stopwatch' - elapsed time, such as ending a drive after 3 minutes by setting the trigger to fire using an Activation Delay of 180s (GTT >> General).

Often used as a placeholder for actions such as initializing variables, displaying text messages to the screen using Set Visual Display Text actions, etc.

'''Note''': A time trigger can have global elapsed time and activation delay of 0, which causes the action stack in the time trigger to activate when that trigger is created.

'''Roadpad Trigger'''
[[File:isat_roadpad_trigger.png|150px]]

Use this trigger when something has to happen at some location in the drive that does not require event timing to be comparable for all participant drivers. For cases where event timing must be comparable among all participant drivers use the Time to Arrival trigger (TTA) instead of a roadpad trigger.

'''Time to Arrival Trigger'''
[[File:isat_time_to_arrival_trigger.png|150px]]

Use this trigger when something has to happen relative to some point in the drive, and also ensure all study drivers experience the same event timing irrespective of driver style (conservative, slow vs. aggressive, fast). Time to arrival (TTA) trigger uses a time calculation from the trigger pad activation to a target location specified in the trigger.

'''Traffic Light Trigger'''
[[File:isat_traffic_light_trigger.png|150px]]

This trigger activates actions when the specified traffic signal state is reached. For example, if the desired action is to create a DDO pedestrian to step into traffic when the traffic signal is yellow, then the Traffic Signal Manager must be used to author the appropriate signal states for the traffic signal.

Typically some other trigger is used to control the traffic signal (ie, to change the signal to Yellow on approach). It is therefore perfectly valid to put the actions within this other trigger rather than relying on the traffic light trigger.

'''Note''': Once a traffic light action has been authored, ISAT may be prone to crashing when accessing that trigger. This problem can be avoided by creating a time trigger and isolating the traffic light action there, allowing the parent trigger to be modified without crashing. Adjustments can be made to the traffic light action time trigger in a text editor, or recreated if it becomes necessary to make adjustments and ISAT continues to crash when trying to make edits.

'''Note:''' The traffic light action does not change the traffic signal state, and it requires a valid state sequence to exist in the signal timing table (Edit >> Traffic Light Manager). The traffic light action '''will not create a signal state''' that does not already exist in the signal timing table.

'''Expression Trigger'''
[[File:isat_expression_trigger.png|150px]]

Use this trigger when something must be monitored, evaluated or calculated such as checking a variable or cell value, velocity of the driver or the state of simulator hardware (steering wheel angle, brake or accelerator pedal position) or distance from the driver to some other object in the scenario.

Multiple expressions can be used within the same expression trigger. In those cases, all expressions must evaluate to True in order for the action stack to execute unless using an '''OR''' operator.

Use the '''OR''' operator - the pipe character "|" if you want to activate the action stack if '''any''' of the expressions evaluates to True.

In the following example, the trigger checks for TrialNumber = 1 and FirstButtonPress variables, and then checks if Aux Button 1 or 0 was pressed:

'''ReadVar('TrialNumber') = 1.0 & ReadVar('FirstButtonPress') = 1.0 & (ReadCell('Auxiliary_Buttons', 0) > 0 | ReadCell('Auxiliary_Buttons',1) > 0)'''

'''Note''': Expressions can also be embedded into some other triggers, most notably the Set Dial >> ADO >> Forced Velocity action often used in Roadpad triggers.

'''Follow Trigger'''
[[File:isat_follow_trigger.png|150px]]

Use this trigger when something has to happen based on one ADO position relative to another scenario element (including the XD). The follow trigger requires a leader and a follower to be specified; when this condition is met, the trigger action stack activates.

'''Note''': Both leader and follower must be positioned on the follow trigger roadpad to satisfy the follow parameters.

'''Geometric Position'''
[[File:isat_geometric_position_trigger.png|150px]]

This trigger is most useful to perform actions for off-road actors such as walkers. The trigger predicate is limited to Name or Type and requires a geometric position to be defined.

A more limited version of the geometric position trigger can be implemented with a Global Time Trigger that contains a Creation Radius. Placing the creation radius defines the area where the trigger may be activate.

===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

[[File:Screenshot (208).png|800px]]

'''Note:''' The highlighted lane shows which lane is the '''activating lane'''. Other lane/s will not activate the trigger action stack.

===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

[[File:TTA.png|400px]]

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===

[[File:other_triggers.png|400px]]

*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===

Execute actions if input expression evaluates to TRUE; the expression is specified on the trigger Predicate tab.

====Syntax====
Expression triggers support a simple language syntax with operators and functions.
The syntax is infix notation; i.e. a + b, not a b +.

Note: It is not generally possible to embed one function call inside another:
cos(sin(x)) is therefore an invalid expression. ISAT will report invalid expressions during rehearsal of a scenario. Invalid expressions are not supported and will not operate as written during simulation.

'''Exception:''' Currently it is possible to use the square root function with GetObjDistPow2 as in the following example:

sqrt(GetObjDistPow2('Target_Object_Name'))

Multiple expressions may be combined using the logical AND (&) or OR ("|" pipe character).

Exp1 '''&''' Exp2, Exp1 '''&''' Exp2 '''&''' Exp ''N''

All expressions must be true for the trigger to evaluate to TRUE and execute the action stack.

Exp1 '''|''' Exp2
One of the expressions must be true for the trigger to execute the action stack.

Negative values are not directly supported by the expression parser. To use a negative value, it must be a calculated value such as the following:

'''ReadCell('CFS_Steering_Wheel_Angle',0)<(0-5.0)'''

==== Operators ====
Operators are used to create expressions.

'''String'''
:Used within quotes as a string literal; i.e., 'some string'

Grouping
:Parentheses group elements together; i.e.,
:'''()'''; (a), (a + b)

Multiplication
:'''*'''; a * b

Division
:'''/'''; a / b

Addition
:'''+'''; a + b

Subtraction
:'''-'''; a - b

Note: negative values must be expressed with a subtraction operation:
(0 - 5), not -5 (invalid)

Greater than
:'''>'''; a > b

Less than
:'''<'''; a < b

Logical And
:'''&'''; a & b

Both a and b, otherwise returns 0 (FALSE)

Logical Or
:'''|'''; a | b

a or b returns 1 (TRUE)

====Expression Functions ====
Functions are used with operators to create expressions.

Function: '''sin'''
:sin -sine

Syntax
:sin(float x)

Description
:The sin() function returns the sine of x, where x is given in radians.

Return Value
:The sin() function returns a value between -1 and 1.

Function: '''cos'''
:cos –cosine

Syntax
:cos(float x)

Description
:The cos() function returns the cosine of x, where x is given in radians.

Return Value
:The cos() function returns a value between -1 and 1.

Function: '''ReadCell'''
:ReadCell()

Read a Cell value.

Syntax
:ReadCell(string Name, int Cell Array index)

Description
:ReadCell returns the value of a given cell (a cell is the current instance of a variable that will be maybe written to a daq file).

Index specifies a 0 based index into the array. Since most cells are single element arrays, a value 0 indicates the first element.

Cells valid for the ReadCell function are defined within the cell collect file NadsMiniSim.cec located in the miniSim_x.x\data folder.
The ReadCell function operates on shared memory during simulation, it does not read cell data from the DAQ file.

Cells that are defined may be written to the DAQ; the collect file specifies which cells are saved into the DAQ and what frequency to use for the write operation.
The NadsMiniSimCollect.general.txt file is located in the miniSim_x.x\data folder.

Available Cells:
Any cell that has been defined in the .cec file. For example:

:'''LogStreams''': Array of 5 floats. Logstreams are a set of values the scenario author can write to through “write to logstream” actions.
:'''AccelPedalPos''': Single Value. The current position of the accelerator pedal
:'''BrakePedalForce''': Single Value. The current force on the brake pedal in pounds
:'''SteeringWheelAngle''': Single Value. The current rotation of the steering wheel
:'''CruiseControl''': Single Value. The current cruise control position. (values are cab/platform specific)
:'''TurnSignal''': Single Value. The current position of the turn signal (values are cab/platform specific)
:'''OvVel''': Single Value. The participant’s current speed in miles per hour
:'''OvLaneDev''': Single Value. The participant’s lane deviation in feet.
:'''OvHeadwayToLeadVeh''': Single Value. The distance in feet to the first vehicle in front of the participant. -1 if no vehicle can be found.
:'''OvTtcToLeadVeh''': Single Value. The time to collision to the first vehicle ahead of the participant.
:'''Horn''': Single Value. The state of the horn (values are cab/platform specific)
:'''DynObj_Vel''': Array of 20 floats. The speed of a given dynamic object. Dynamic Objects are sorted in terms of distance to driver.
:'''OvVelLocal''': Single Value. The participant’s current speed in miles per hour, using the value local to scenario control

For a complete list of cells and array elements please see the miniSim data dictionary spreadsheet.

Return Value
:Returns the value of the specified cell.

Example
ReadCell(‘LogStreams’,5) > 3

Function: '''CellEquals'''
:Cell Equals, array element, value to compare

Syntax
:CellEquals(string name, int index, float value)

Description
:The Cell Equals function is similar to the ReadCell function, except it adds an additional value to compare against the cell value.

Like ReadCell, name specifies the name of the cell, index specifies the cell array index (use 0 for single value cells).

Available Cells:
:Any cell that is defined in the .cec file.

Return Value
:Units: 1 or 0
:1 if the cell value is equal to the passed in comparison value; otherwise 0

Function: '''GetObjDistPow2'''
:Get object distance squared

Syntax
:GetObjDistPow2(string name)

Description
:GetObjDistPow2 returns the distance squared between the external driver and the dynamic object specified by ‘name’.

Distance squared is used to avoid having to perform an expensive square root calculation every frame.

If the specified object cannot be found, a value larger than 100 million is returned.

Return Value
:Feet; Distance in feet measured from the eye position of the driver to the CG (centroid) of the dynamic object specified.

A very large number is returned if the specified object cannot be found (larger than 100 million)

Example
:GetObjDistPow2(‘OncomingCar1’) < 2500

'''Note:''' To get an actual distance, multiply by the square root (sqrt())
: sqrt(GetObjDistPow2('Target_Obj'))

Function: '''GetObjTtcToOv'''
:Get Object Time To Collision to Own Vehicle

Syntax
:GetObjTtcToOv(string object name)

Description
:GetObjTtcToOv gets the time to collision from the dynamic object specified by the name parameter, to the own vehicle.

Return Value
:Unit: Seconds
:Time (seconds) to collision from the own vehicle to the dynamic object specified by the name parameter.
:0 is returned if the object specified cannot be found.

Function: '''GetObjVel'''
:Get Object Velocity

Syntax
:GetObjVel(string object name)

Description
:GetObjVel gets the velocity in meters per second of the first dynamic object with the name specified by the ‘name’ argument.

Return Value
:Unit: Meters per second
:The speed of the specified dynamic object; 0 if no object is found

'''Note:''' Multiply by 2.23694 for miles per hour.

Example
:GetObjVel(‘PullOutVeh’) > 15.4

Function: '''Rand'''
:Random

Syntax
:Rand(int value)
:Rand(string name)
:Rand(string name, string type, double parameter, double parameter)
:Rand(string name, string type, int parameter, int parameter)

Description
:Rand returns a random value specified by the name of the generator, the type of distribution and its parameters.

If the user does not specify the name of the generator and only specifies a number as the only parameter, the Rand function will use a default random number generator to produce random numbers.

If the user only enters the name of a user created random number generator, the random number generator will produce a value between 0 and 1.
If a name of generator is supplied that has not been created, the Rand function will display an error message in the ISAT debug window and return 0 (during scenario rehearsal).

The rand function supports multiple types of distributions that can be used to generate a random number.

Types of Distributions:
:normal: Normal Distribution(mean, standard deviation). The normal distribution generates random numbers near the mean with a specific standard deviation.
:gamma: Gamma Distribution(alpha, beta). The gamma distribution generates a random value that models waiting times for the Poisson process.
:uniformInt: Uniform Integer Distribution(min, max). The uniform integer distribution generates a random integer number between the lower and upper bounds.
:uniform: Uniform Real Distribution(min, max). The uniform real distribution generates a random floating point number between the lower and upper bounds.

The values stated in the parenthesis above are the parameters for each distribution in order. If the incorrect number of parameters are entered or if they are entered incorrectly, the debug window in ISAT will display an error message and the rand function will return 0 (during scenario rehearsal).

If the distribution is entered incorrectly, the debug window will also display an error message.

Return Value
:A random value from 0 to 1 if the type of distribution is not specified.

If the type of distribution is specified, returns a random value determined from the type of distribution and the given parameters.

Example
:Rand(‘myRandGenerator’,’uniformInt’,1,10)
:This example returns a random integer value from 1 to 10.

Rand(5) or Rand(‘myRandGenerator’)
:These examples return a random value between 0 and 1.

Function: '''sqrt'''
Square root

Syntax:
:sqrt(parameter)

Return Value:
: return the square root of the specified parameter.
: parameter can be another function, such as GetObjDistPow2()

Function: '''ReadVar'''
:Read a variable

Syntax:
:ReadVar(string Name)

Return Value:
:Returns the string value of variable specified in <variable_name>

===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.

=='''Audio Components'''==
The components of the Audio sub-system includes configuration and data files installed into the NadsMiniSim_x.xx\data\sound\DefaultCabSound\Instructs folder.

[[File:audio_components.png|400px]]

The audio engine contains multiple channels and has a theoretical limit of 512 simultaneous sounds.

NOTE: Not all .wav files are compatible with the Audio Engine.

=Scenario World Objects=
Scenario world objects are defined in the tile model source. They are not added by the scenario author since they are objects already present in the roadmap/BLI.

[[File:object_types_world.png|400px]]

Typically, but not always, these objects can be authored in ISAT. However, some scenario world objects have no options - these cannot be selected in ISAT; therefore such objects cannot be authored.

Removal of world objects requires editing the source tile model using a 3D application. In some cases an alternate tile model is available identical to the original but without objects.

Contact NADS if removal of a world object is needed.

Other scenario world objects, such as Traffic Signals, are specialized function objects that can be authored. Traffic signals are authored using the Traffic Light Manager: Edit >> Traffic Light Manager.

=Troubleshooting Scenario Objects That Reset=

== Scenario World Objects ==
Scenario world objects are already present when you create a new scenario - they are not added by the scenario author. These objects may be visible in miniSim but not in ISAT, or they may be visible in ISAT and seem to be controllable, but the objects 'reset' to their defaults when viewed on miniSim.

[[File:2019-10-23_16h18_47.png|700px]]

The objects which 'reset' are a symptom of settings in the TMT that are not configured to allow scenario authoring of objects.

[[File:2019-10-23_16h18_52.png|700px]]

When objects appear to 'reset' or if you can edit an object in ISAT but don't see your changes in miniSim, correct the problem by resolving controllability in the TMT settings: https://www.screencast.com/t/ZH5Dh178.

=Scenario Coordinate Types=
There are two types of coordinates used in scenarios. The first is roadway coordinates. These coordinates are contextual (tied to a specific road or intersection and position) and are used for ADO objects and roadpad paths in general.

After a roadway coordinate has been generated, it is not updated unless the scenario author makes changes to the start, end or location of the entire path or pad.

Roadway coordinate are the reason it is not possible to change a roadmap using the TMT and expect a previously authored scenario to work on the altered roadmap. If the length or location of a road changes, the path/pad will update to the extent possible.

If the road has been eliminated and no longer exists in the roadmap/BLI, ISAT will report an error and not open the scenario file.

A. Field breakdown:
RoadPos keyword <name of road:lane:position on road:path length>

Name "Ado1"
RoadPos "r1_-6600_4620:0:5737.06:0.00"
Path "R:r1_-6600_4620:0[5736.06:5873.83]"

[[File:isat_coordinate_types.png|400px]]

B.
Name "VirtObj"
Option 2
Position -6.8375599E+002 5.6331237E+003 0.0000000E+000

The second type is world coordinates, which are Cartesian coordinates with X increasing to the right, Y increasing forward, and Z increasing up.

='''Scenario Authoring'''=
Scenario authoring is the creation, editing and testing of everything that happens during a simulation drive.

==Cell Operations: Best Practice==
Reading and writing to cells is a computationally expensive process. Best practice is to centralize all the reads/write to one place so that it’s only done once per cell.

Once a cell is read, the value is copied to a variable and only the variable is used throughout all the triggers that need it.

The same process applies to writing to cells. Use of variables can reduce the Cell Operations overhead greatly.

==Before You Begin==
Before beginning a scenario, it is necessary to understand the following requirements:

=== Drive Requirements===
How long is the drive?
What type of roadway?
Are there any specialized road elements (intersections, interchanges, freeway ramps)?
Are there any environmental requirements (should the simulation replicate a real world location, or is a generic environment acceptable)?
Is there a particular roadway configuration that is needed (long straight rural road vs. typical urban environment with intersections, signals, etc)?

=== Traffic Requirements ===
What types of traffic will be needed?
Will ambient traffic interact with the external driver?
What types of interaction will be required (traffic cloud, lead vehicle, follow vehicle)?

=== Events ===
The purpose of an event is to present a situation to the external driver. In order for the simulation to produce meaningful data, it is critical that events unfold for each driver in a comparable way. Therefore, each event must be designed with this repeatability in mind.

'''NOTE:''' one of the most variable scenario elements is the driving style of each external driver: how conservative or aggressive they drive, velocities throughout the scenario, how comfortable the driver is travelling with simulated vehicles, etc.

Repeatability often includes static elements (each driver encounters scenario elements in the same location) or in cases where the driver performance is taken into account, accommodation of the driver dynamic (velocity, lane position) through the use of time to arrival triggers (TTA) or follow triggers. A TTA trigger will fire based on time to a target location - thus a driver travelling at 45mph or a driver travelling at 55mph can both experience the same action relative to that target location, irrespective of the different driver velocities.

==Beginning A Scenario==
All scenarios designed to be driven require a start location - the place where the driver will be located when the simulated drive begins.

To insert a start location into a scenario:

:Insert >> External Driver >> LMB on road, intersection or terrain object

[[File:isat_initial_position.png|400px]]

'''NOTE:''' scenarios that only contain data and are not intended to be driven - for example, signs or traffic that are used as external reference files do not require a start location, since that will be defined within the parent scenario.

==Initial Conditions==
Initial conditions define how the simulated scene is configured: will the drive occur during daylight or night time conditions? Will the ownship (external driver vehicle) have headlights enabled? What type of vehicle will it be? Will there be objects or traffic visible to the driver?
These form the initial conditions of the simulation experience. Additional initial conditions would include initialization of variables or establishing networked communication as needed by the scenario.

[[File:isat_initial_conditions_miniSim.png|400px]]

By default ISAT sets the initial condition '''Time of Day''' to 12:00 noon. The time of day is controlled from the Initial Conditions dialog:

Edit >> Initial Conditions

[[File:isat_initial_conditions_scenario.png|400px]]

==Scenario Authoring: Actions==
Actions are the scenario elements that make things happen during simulation. Actions do specific things, like display a text message on screen for the driver, create a scenario element, change the velocity of simulated traffic, change a traffic signal, etc.

[[File:trigger_action_panels.png|400px]]

The diagram above shows the action panel for left to right: an expression trigger, a roadpad trigger and a global time trigger showing different panels based on the actions present in each trigger.

'''NOTE:'''Actions can be created, edited or removed from the '''Actions panel''' of '''any trigger'''.

'''NOTE:''' The Actions panel changes based on the action type created.
When multiple actions have been defined, control the sequence of actions by changing the action order in the list using the up or down arrows next to the list.

[[File:action_panel_overview.png|400px]]

If multiple actions need to happen in a specific order, set the order using the arrows and then flag the action list as '''sequential'''. This instructs behaviors to process the actions in the list order.

Using a delay for any action will pause processing of the '''following actions'''; the action happens first, then the delay is applied.

===Scenario Authoring: Action Types===
There are two types of actions:
# Instantaneous - the action takes up to one frame to complete, i.e.:
:set target velocity
:write to cell
# Persistent
<span style="color:red">'''*Persistent actions do not end'''</span>, or take multiple frames to complete:
:Forced lane offset
:Forced velocity
:Maintain Gap

==='''Actions'''===
*The "Who to Affect" field defines what is affected by the action
:Instigator set: who activated the trigger
:Name: one or more named elements
:Type: Apply changes to all objects matching the specified type
:Relative: Position relative to the trigger location

*Sequential
:Actions to execute sequentially, one after the other
:Specify delay between actions
:: Action executes, then delay

:Some actions are persistent and never "finish"

===Scenario example: display text & roadpad trigger to stop the drive===
This scenario is very simple and contains a global time trigger (GTT) that tells the driver what to do. After the driver travels along the roadway, a roadpad trigger (RPT) is used to tell the driver to stop driving. The same RPT also creates an expression trigger to terminate the drive.

TBC example scenario file

Because the external driver is not under control except by instructions, it's possible they might ignore the halt message and continue driving. A second failsafe RPT then terminates the drive.

==='''Actions: Button vs. Dial'''===
*Dial changes a setting
*Button: always runs in a single frame
:-"immediate" change. Typically buttons have less control than a '''Set Dial''' action

==='''ADO Actions'''===
[[File:ado_action_types_button_vs_dial.png|400px]]

==='''DDO Actions'''===
[[File:ddo_set_dial.png|400px]]

==='''External Driver Actions'''===
External driver behavior can be influenced by reinforcing scenario actions through audible speeding alerts, on-screen text instructions and messages or audio instructions.

Driving behavior can be influenced with situational elements
:Car in the drivers blind spot
:Lead vehicle
:Aggressive following vehicle
:Temporary lane closure
:lane specific instructions

Scenarios should '''not rely on specific driver actions to be successful'''
:to the extent possible; sometimes you do need the driver to respond/behave in a controlled manner.
:A work zone blocking one lane typically will require a roadpad placed upstream from the work zone to shift traffic into the correct lane

'''NOTE:''' Controlling driver actions should be an experimental design consideration.

==='''Special Actions'''===
These actions need special handling:
*Reset or "toggle":
:Audio
:Display Text

:'''Ado'''
::Audio State
::Forced Velocity
::Maintain Gap
::Visual State

*If using these persistent actions, place them at the '''end''' of an action sequence (because no action following these will execute):
:Forced Lane Offset
:Forced Velocity
:Maintain Gap
:Visual State

*Note: If the Visual State action contains a duration then it will be handled as a normal action, with subsequent actions firing after it. However, if there is no duration supplied with the Visual State action it behaves like a persistent action, and nothing following it in the Action stack will ever fire.

[[File:multiple_simultaneous_actions.png|400px]]

The diagram above shows how one parent trigger can be used to create multiple simultaneous triggers

*How to activate multiple unique force velocity (FV) or maintain gap (MG) actions:
#create the needed triggers from a general parent trigger, 1 per action
#put common actions into the parent trigger
::reset FV
::reset MG

==Scenario Authoring How To==
This section contains simple examples for various typical scenario situations.

===How do I specify an event?===
First, determine which method is best for you - the default measures (limited measures, 20 events max) or logstreams (all simulation data, no event maximum).

Regardless of method, you specify an event by identifying areas of significance in the drive and marking them so the data within the event region can be processed. Any trigger combination that can specify event start and event end may be used.

[[File:2022-07-01_11h21_52.png|400px]]

===How to know Which Coordinator or Trigger I need?===
The answer to this question lies in the type of information needed for an event:

*Time
:global time trigger
:or an expression trigger that calculates time
*Position or Location
:roadpad trigger
::or a time to arrival (TTA) trigger
::or an expression trigger that calculates distance
*Calculation
:Expression trigger

===How to Instruct the External Driver===

Instructions to the external driver can be accomplished by three main methods:
# Instruct the driver using experimental protocol (instructional or briefing presentation)
# Information messages displayed on screen: '''Action: ''set visual display text'' '''
# Information messages delivered as audio messages: '''Action: ''write to cell > SCC_Audio_Trigger ><audio ID>'' '''

===How to Add Traffic in the Scene ===

Generating traffic will happen in one of 5 ways:
# Created explicitly by inserting ADO, or copy/paste existing ADOs
# Created with a script
# Via a Create action inside a trigger, or placing scripted traffic inside a create action within a trigger
# From a '''Traffic Source'''*
# From the '''Traffic Manager'''**

Each of these methods has advantages and disadvantages.

==== Create Explicitly ====

The biggest advantage with this method of traffic creation is the high degree of control the scenario author has over:
# location of the created ADO
# Name of the created ADO
# Travel path of the created ADO
# Control when each ADO is created within the scene via Settings >> Creation Radius

The disadvantage is that creating a high volume of traffic will take some work with this method.

==== Created with a Script ====

This method combines the advantages of Creating Explicitly with volume. It is possible to create a large volume of traffic very easily with a script.

Disadvantages of using high volumes of traffic with a script: in the event it becomes necessary for a high degree of control over these ADOs, more is not better because ADOs will adapt to road conditions under their own power, unless the default ADO settings have been modified:
'''lane changes, including lane changes to accommodate freeway ramps'''
'''velocity adjustments'''

==== Via a Create action inside a trigger ====
Combines the advantages of the previous 2 methods with control over when to activate that traffic using a trigger action.

Disadvantages: Creating too many ADOs at one point in the drive can cause the miniSim to bog down for a few frames. If too many ADOs are present and active in the simulation at one time, this can cause the miniSim to drop frames and run sluggishly. This is highly noticeable and may increase the potential for the External Driver to experience '''simulator sickness.'''

==== From a '''Traffic Source''' ====

Traffic Sources rely on two methods to populate a scene with traffic:
# location specific, with each ADO created for a traffic source being a 'spawn location' for ADOs, or
# location agnostic if the ADO has '''relative creation''' enabled, thus being created relative to the object identified.

In addition to being created relative to a scenario element, ADOs are created relative to the specified scenario element:
# In front of (Longitudinal Distance > 0, where the number is feet offset from the object) , or
# Behind (Longitudinal Distance < 0, where the number is feet offset from the object).

Advantages: Can easily populate traffic into the simulation.

Disadvantages: It is easy to generate more traffic than the simulation can maintain at 60Hz frame rate, thus introducing frame lag with the resulting scene 'stutter' and the increased risk of simulator sickness.

Also, traffic created from a Traffic Source is generic traffic. It is not possible to reliably refer to specific ADOs generated from a traffic source except by using Who To Affect >> Relative (versus referring to a named ADO, i.e. Slow_Moving_Lead_Vehicle). Referring by name to Traffic Source generated ADOs will affect all similarly named ADOs at the same time.

==== From a '''Traffic Manager''' ====

The traffic manager interface is problematic in ISAT versions up to 1.8.5, especially when specifying the set of vehicles to be used for generating traffic.

Advantages: Create generic ambient traffic easily.

Disadvantages: Has the same disadvantages as traffic created via a Traffic Source. Also getting a traffic set working by specifying the vehicles to be used within the set. ISAT versions up to 1.8.5 exhibit instability when setting vehicles in ISAT.

Traffic Manager Set workaround: Borrow a working set from an existing scenario or group. Alternatively use a version of ISAT (1.8.6 +) to create the traffic set. This can be saved as a scenario or group file, which can then be used with ISAT 1.8.x as long as there is no attempt to adjust the vehicle weights within ISAT. The scenario or group file can be edited as text in a text editor, but care must be exercised to avoid introducing errors into the file. ISAT will not read invalid scenario or group files.

Traffic generated by the Traffic Manager is controlled through the use of Input Sets. An input set is a collection of vehicles and weights used to populate the scene during simulation. This is how the scenario author can control the vehicle population (type and number), density and creation/deletion distances - these attributes are unique to each set.

Since there is no 'discontinue traffic manager' function, one can be implemented by defining an input set with no traffic (an empty input set). An appropriate name can make the purpose of the set clear: PauseTraffic, Stop_TM, etc.

==== Sample Traffic Manager Set ====
This is a sample traffic manager set that can be pasted into a scenario file after the HCSM VehFail section. Be sure to paste '''after''' the HCSM VehFail end tag ('''&&&End&&&''') in your scenario file.

'''Note:''' A scenario file may contain only '''one''' Traffic Manager section.

There are two input sets in this example; note how they contain different vehicles and different settings from each other.

<span style="color:#2a4b8d">HCSM TrafficManager
GroupName "Traffic Manager"
HCSM InputSet
Name "ONE"
MinDensity 3.0000000E-002
MaxDensity 7.0000000E-002
MaxObjects 9
CreateDist 2.0000000E+003
DeleteDist 3.0000000E+003
AbsDeleteDist 3.4000000E+003
RunFreq 1.0000000E+000
SolWeights "cargill_semi_peterbilt_blu:2" "cargill_semi_freightliner_red:1" "cargill_semi_peterbilt_yel:3" "DumpTruck_org:3" "semi_peterbilt_yel_Walmart:2" "Cadillac_Escalade:10" "Ford_F150Xcab:15" "Saturn_Vue:10" "FordTaurus:15" "Escape:15" "DumpTruck:2"
&&&&End&&&&
HCSM InputSet
Name "TWO"
MinDensity 1.0000000E-002
MaxDensity 3.0000000E-002
MaxObjects 4
CreateDist 2.5000000E+003
DeleteDist 3.3000000E+003
AbsDeleteDist 3.5000000E+003
RunFreq 1.8000000E+000
SolWeights "Taurus2011:12" "Cadillac_Escalade:16" "Ford_F150Xcab:24" "Saturn_Vue:14" "Escape:6" "Deville:24" "Audi:4"
&&&&End&&&&
&&&&End&&&&
</span>

====='''Managing Traffic Manager Input Sets'''=====
During simulation, Input sets are controlled by the action '''Use Traffic Manager Set'''. A set name must be provided for this action to work.

===== Traffic Manager generated Traffic=====
ADOs will populate the road network around the XD based on the parameters of the Input Set. Typically traffic is removed from the scene shortly after passing the XD. This is visible in the rear view mirror. There is currently no way to adjust this delete distance.

====== Traffic Manager Traffic on 2 lane freeway======
Traffic will prefer to be in the XD lane, so ADOs created in any other lane will tend to veer into the XD lane. On a divided highway, traffic is generated moving with the XD.

====== Traffic Manager Traffic on 2 lane road======
Traffic is generated in the oncoming lane. In some cases traffic may be generated then immediately removed in front of the XD.

===How to Control Objects in the Scene during Simulation ===
"Set and forget" options on simulation entities only require the scenario author to "initialize" the element to a desired setting and then it is left alone during simulation.

Controlling objects dynamically during simulation requires the scenario "talk to" each object with a scenario action. This section describes how each scenario object type can be controlled during simulation within a scenario.

All models used in ISAT are listed within the Scenario Object Library (sol2).txt files. Terrain switch names are displayed in the ISAT workspace.

All model switches are listed within the NadsMiniSim_x.x\bin.x64\ModelList.txt file.

'''Note:''' The diligent reader will note discrepancies in model names between the sol2 and ModelList files. This is because the ModelList file contains actual file names, and the sol2 files define a "name label" for models that may, or may not, be the actual model name. Objects are linked between the sol2 and ModelList files through the ModelID/CigiID records. These values will match between sol2 and ModelList files, but IDs are not necessary at this time for scenario authoring purposes.

Complicated object names can be retrieved from the LRI file that was used to build any scenario file; each BLI is preceded by an LRI. The LRI contains all of the terrain models that will be present in ISAT. These are typically speed limit signs, traffic signals or other features that may be controllable.

'''Note:''' this file may not be present for the Springfield.bli file.

An alternative is to capture a screenshot of the ISAT workspace with the element name string showing. By default ISAT reports the name of any objects when the cursor passes over the object, as shown in this example:

[[File:2021-10-27_08h50_14.png|caption =Object Name Screenshot | 400px]]

{|class="wikitable"
|+ Controlling Scenario Elements During Simulation in Scenario
!Date
!Nads miniSim version
!Object Type
!Scenario Action
!Who To Affect
!Value
!Notes
|-
| Oct. 28, 2021
|2.3
|-
|
|
|Static Object (terrain)
| SetDial > StaticObjManager > Set Option1
| StaticObjManager
| switch name : switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
|Static Object, multiple options
| Set Switch
| Name of element
| switch option
|-
|
|
|Obstacle, multiple options
| Set Switch
| Name of element
| switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
| DDO, multiple options
| Set Switch
| Name of element
| switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
| ADO
| Set Dial > ADO > VisualState
| Name of element
| Limited to options present in ISAT
|-
|
|
| Traffic Signal
| Traffic Light
| Assign action to element
| Target state
| Target state must exist within the Traffic Light Manager intersection timing table for the specified signal

|}

===How to Control Simulated Vehicles===
The scenario author can control simulated vehicles by controlling the environment:
#change a traffic signal to cause an ADO to stop or start at intersections
#affect other ADOs to cause a target ADO to respond
# assign a path for the ADO to travel

Direct control:
*Lane related:
:Set button > ADO > ChangeLane, Turn, ProjectAndResetLane

*All other controls:
:Set Dial > ADO > AudioState, ForcedLaneOffset, ForcedVelocity, InhibitLaneChange, LaneChange, MaintainGap, TargetVelocity, VisualState, AudioState

====How to Change ADO Velocity====
ADO velocity can be changed using the SetDial action:
:SetDial > ADO >

:ForcedVelocity
:ForcedVelocity using an expression:
# match external driver speed
expr % OvVel(0) %
# multiply external driver speed
expr -1 9 %ReadCell('OvVelLocal',1)*1.75 %
:TargetVelocity

Indirect Control (dependent on other scenario element):
:MaintainGap

====How to Link ADO Velocity to Something Else====
ADOs velocity can be linked to other ADOs or the external driver using the MaintainGap (MG) action.

SetDial > ADO > MaintainGap

When using a traffic cloud containing multiple ADOs, each ADO in the cloud needs a unique MG. IF multiple ADOs have the same MG settings they will attempt to satisfy their parameters and likely oscillate position in a visually obnoxious way.

===How to Author Loop Scenarios===
A scenario created on a loop road network operates very much like any other scenario, with the exception that it is likely to require tracking the number of times through the loop, or to present scenario events to the external driver depending on each loop context.

[[File:loop_traffic_creation_01.png|400px]]

The simplest method of tracking loops is the use of a loop counter variable. This variable can be set by the driver "stepping onto" a roadpad trigger or it can be initialized through the use of a timer or expression, with increments managed by a roadpad trigger. Each time through the loop increases the loop count variable.

Thus it becomes possible to create events for each loop based on the loop counter variable, typically through an expression trigger.

Loop management triggers

[[File:loop_management_02.png|400px]]

Loop management trigger detail one

[[File:loop_management_vars_02b.png|400px]]

Loop management trigger detail two

[[File:loop_management_3.png|400px]]

====Creating Loop Specific Traffic====
Creating loop traffic is slightly more complicated due to the number of objects to be created and potentially the size of the actual loop. A small loop is installed with the Nads miniSim as simple_rural1 or simple_rural2. Each is a loop road network with two signed 3-way intersections.

Loop specific traffic can be created through the use of a variable (i.e., LoopCount) or within the roadpad trigger that is incrementing the loop count variable. Both methods will incorporate a '''Create Action''' that creates the required elements.

===How to Change Environment Settings===
The scenario author can define global or localized environment conditions.

1. Insert >> Environment Conditions >> <chosen condition>

2. Define a region where the environment condition is active:
:LMB to define polygon points
:RMB to exit point entry mode

[[File:env_condition1.png|400px]]

Choosing an environment condition

[[File:env_condition2.png|400px]]

Environment region defined and parameters panel shows available options

NOTE: The environment condition boundary is a discrete threshold. Condition A will be on one side of the threshold. Immediately after crossing the boundary, condition B will be displayed.

===How to Fade an Environment Condition===
To fade gradually between two conditions requires the use of an expression that continually monitors the desired condition and sets a few variables based on the results.

Examining the demo scenario is the best way to look 'under the hood' to see exact command syntax and values to be used.

[[File:env_fade.png|400px]]

Note: this approach has been used for fog and visibility. It is unknown how it might work with non-visibility conditions such as precipitation and wind.

*From the scenario demo_visibility_transition.scn

[[File:env_fade_schematic.png|400px]]

'''Note:''' although the example above uses an environment condition boundary, '''it is possible''' to omit the defined region, retaining all commands and the scenario will still function. However, without the environment region, it becomes more difficult to determine where conditions are different from the standard settings.

===How to Control a Cab Instrument Panel icon===
In order to control the instrument panel, there are 2 requirements:
The specific cab used for the scenario
The specific control (switch) to be manipulated
The action for addressing the instrument panel is '''ChangeCabSetting'''

Instrument panel models are located in NadsMiniSim_x.x\data\Visuals\Instruments
These files are in OpenFlight format. Any 3D editor capable of reading or importing OpenFlight can be used to review these files. NADS uses the Presagis product Creator[tm].

An alternative method to inventory switches is to use the the '''buildscl.exe''' tool. To run the tool, open a CMD window to the IP folder location above, then run the command:
buildscl <input_file.flt><Enter>.
<input_file.flt> is the name of the file to process, without the '<>' characters.
<Enter> means to press the Enter key,

The result will be in a new file ending with .scl. This is a text file, and can be opened in a text editor or you can use the shell utility '''more''' to view the file contents:

more <input_file.scl> | grep switch<Enter>

An example for the malibu cab is shown below. .

switch s_LowWasher 0
switch s_Cruise 1
switch s_LeftTurn 2
switch s_RightTurn 3
switch s_FwdCollisionWarn 4
switch s_BlindSpotWarn 5
switch s_LaneDeviationWarn 6
switch s_RearCollisionWarn 7
switch s_HighBeamHeadlights 8
switch s_SeatBelt 9
switch s_UpArrow 10
switch s_Airbag 11
switch s_CheckEngine 12
switch s_CheckGuages 13
switch s_ABS 14
switch s_Brake 15
switch s_LowFuel 16
switch s_Gear 17

These controls may be accessed directly in scenario using the ChangeCabSetting action.

'''NOTE:''' Some functions such as Cruise, Gear, High beam headlights, Blind spot, collision, lane deviation warnings are '''normally''' controlled not by direct access as described here but by hardware mechanisms/buttons.

'''NOTE:''' For altering cab instrument panel operation it will be necessary to modify the OpenFlight model to include the desired funationality; for example, instrument panel blanking is not build into the model but can be added by editing the cab instrument panel model file then installing the modified file into miniSim.

===Scenario Hints===
The total number of scenario elements active at any given time can affect simulator performance:

Total number of active elements
*vehicles (ADOs), triggers, animations, etc.

Object management
*Use paths to shift ADOs away from the driver route of travel as they turn off the route
*reduce the number of vehicles in traffic cloud surrounding external driver
*use creation radius to limit the number of active elements, and to remove elements after the driver has traveled beyond the creation radius

[[File:creation_radius_1.png|400px]]

Creation radius works by activating the scenario element only when the driver is within the radius. The scenario element is created when the driver enters the creation radius, and is deleted after the driver leaves the creation radius.

Exploit environment to reduce object load

*Use curves, hills, intersection corners to mask objects

Object deletion
*Remove objects when no longer needed

When creating dynamic elements, create them as close to where they are needed as possible.

====How to Determine When ADOs are Visible to the External Driver====

Some development/setup testing may be needed to determine precise location/distance/speed; i.e., locating ADOs for a freeway ramp merge event where the external driver is merging onto the freeway with other ambient traffic present.

Unless the purpose of the event is to study driver behavior at the merge, ideally the scenario will be authored to have ambient traffic on the freeway but not to present a conflict at the merge for the external driver.

A straightforward way to determine where the ADOs are first visible to the driver is to mock up a scenario placing colored ADOs along the freeway with a velocity of 0. This will ensure the ADOs remain stationary while the scenario author determines where they are first visible to the external driver.

Place the start position/external driver far enough up the ramp to be a reasonable test for the actual scenario.

As you drive the ramp, see which ADO is first visible to the driver. Place ADOs just out of view (upstream) of that location.

[[File:merge_hint.png|400px]]

'''NOTE:''' use test vehicles of the same type and character as the intended scenario vehicles. For example, do not use a sedan test ADO for a larger vehicle (SUV, bus, dump truck). Doing so will invalidate the visibility test, because a larger ADO will be visible over a longer distance than a small ADO.

[[File:ramp_vis_1.png|400px]]

At the scenario start location, ADOs in front of the Coke truck are visible. Note how the larger vehicles are more obvious at this distance.

[[File:ramp_vis_2.png|400px]]

The driver has traveled onto the ramp. At this point, the last ADO visible to the driver is still the Coke truck.

[[File:ramp_vis_3.png|400px]]

As the driver travels farther down the ramp a small ADO is visible behind the Coke truck.

The answer to the question '''When is an ADO visible?''' is thus:
#It depends on how large the ADO is
#Small ADOs can be placed at the location of the red ADO behind the Coke truck.
#Large ADOs may need to be placed farther back (behind the red ADO). This test is inconclusive, but based on the terrain it seems likely that large ADOs would need to be placed at least at the green ADO location (behind the Coke truck).

Creating small ADOs at the green ADO location when the external driver is located at the ramp position in 3 travelling at the same speed as the external driver should arrive at the merge slightly ahead of the driver (because the curved ramp is longer than the straight freeway).

'''NOTE:''' ADO size, ADO color, time of day and visibility settings affect ADO visibility.

====How to Position Objects Precisely using '''Place Object At..'''====

ISAT does not support true precision because it is not currently possible to 'dial in' a position as is typical in 3D modelling tools, but there is a way to approximate precision in cases where a consistent measurement is desired.

In the following example a number of roadpad triggers are placed relative to the location where a roadway enters an intersection. This is a discrete boundary within the simulation world as shown in ISAT.

There are two methods of placement possible:
# Measure the desired distance (CTRL+Shift+RMB, drag); take note of the coordinates updating in realtime and make a mental note of the desired location.
#Place an object (ADO or static object); use the Place Object At.. feature from the context menu when you RMB on a scenario object.
Using this method you can specify a distance - positive numbers move the object downstream/forward, negative numbers move the object upstream/backward.

'''Note:'''If the distance is significant and extends over an intersection, ISAT may produce unexpected and undesired results such as re-starting the measurement from the closest upstream intersection, thus placing the object where it was not intended.

In the following example, Place Object At.. is used to specify a point 50 feet upstream from the road/intersection border.

[[File:precision_placement_1.png|400px]]

A roadpad trigger has been positioned near the area of interest. Any existing roadpad is deleted from the trigger.

[[File:precision_placement_2.png|400px]]

An ADO is used as a marker object inserted temporarily into the scenario. Any convenient object may be used.

'''Note:''' large objects such as ADOs may be less precise than small objects such as the Traffic cone, but is generally easier to access in the ISAT interface unless you have created a script for cone objects.

[[File:precision_placement_3.png|400px]]

RMB on the ADO to access the Place Object At.. request dialog. Only numbers are valid entries.

[[File:precision_placement_4.png|400px]]

The desired distance is entered into the Place Object At.. request dialog. ISAT will then require you to select the object you wish to move using LMB.

[[File:precision_placement_5.png|400px]]

ISAT moves the selected object by the distance you specified.

[[File:precision_placement_6.png|400px]]

Use the ADO CG (model center) to place the start of the road pad.

[[File:precise_placement_7.png|400px]]

Remove the ADO marker and save your scenario.

==Scenario Testing and Debugging==
The primary way to test and debug scenarios is using ISAT rehearsal mode.

'''NOTE:''' the external driver during rehearsal is a simulation. You have limited control over the simulated ownship:
#change speed
#change lane

ISAT has two rehearsal dialogs:
#abbreviated (standard) dialog
#advanced (extended dialog)

===How to change to the advanced rehearsal dialog===
Often it is necessary to control the ownship during rehearsal. The ownship controls are located in the advanced (extended) rehearsal dialog.

ISAT will show the Advanced dialog the first time rehearsal mode is activated. All additional activations show the abbreviated dialog.

TBC abbreviated dialog

To use the Advanced dialog, LMB the Advanced button.

TBC Advanced dialog

===How to change ownship speed during rehearsal mode===
After entering rehearsal mode:
#click the Play icon (start the rehearsal)
#pause.
#adjust ownship speed
#toggle pause off (resume rehearsal)

===How to make ownship lane change during rehearsal mode===
After entering rehearsal mode:
#click the Play icon (start the rehearsal)
#click the desired Lane Change (left or right)

===How to Use Audio in your Scenario===
Scenarios play audio sounds and messages through a write to cell action: '''SCC_Audio_Trigger'''

Use of audio in a scenario typically requires both a write to cell and a 'clear action' that writes a zero (0) to SCC_Audio_Trigger in order to 'clear the channel'. The 'clear' action can happen before or after playing a sound; choose one method and be consistent in your scenario authoring.

Failure to 'clear the channel' or '''not''' writing a value of zero can result in no audio being played for subsequent write to cell SCC_Audio_Trigger actions.

The following shows how this looks in scenario when executed from a roadpad trigger (RPT):

[[File:audio_scn_A.png|400px]]

The above diagram is shown below in text format:

HCSM RoadPadTrigger
GroupName "WindGust_Audio"
ByTypeSet "ExternalDriver"
NthFromStart 0
NthFromEnd 0
VehicleAhead 0
VehicleBehind 0
LongComment "This is a wind gust event"
ShortComment " "
ActvDel 0.0000000E+00
CrRad 0.0000000E+00
Debounce 0.0000000E+00
FireDelFrames 0
Lifetime 0.0000000E+00
Name "RPT_WG_6"
OneShot 1
Priority 0
SeqAct 1
Position 6.7165800E+04 6.0419215E+03 0.0000000E+00
DrawPosition 6.7165800E+04 6.0419215E+03 1.1308095E-317
Path "R:r3_62700_7920:0[3033.04:3245.46]"
HCSM LogData
Comment "LS1=8"
Delay 0.0000000E+00
InstigatorSet 0
Stream 1
StreamVal 8.0000000E+00
&&&&End&&&&
HCSM WriteCell
Comment "Play_Audio"
Delay 2.0000000E+00
InstigatorSet 0
CellName "SCC_Audio_Trigger"
CellData "63000"
CellType 2
CellVar 0
&&&&End&&&&
HCSM WriteCell
Comment "clear_audio"
Delay 0.0000000E+00
InstigatorSet 0
CellName "SCC_Audio_Trigger"
CellData "0"
CellType 2
CellVar 0
&&&&End&&&&
&&&&End&&&&

===How to Add Custom Audio Instructions to miniSim===

''' Please note: Custom audio 'instructions' for a scenario should be added to the instructions.txt file.'''

These are sounds that are played in scenario, typically as directions for the minSim driver.

Adding custom audio files requires the following procedure:

1 Exit miniSim - changes to the miniSim configuration should happen only when miniSim is not running.

2 Copy the audio .wav file to:
:C:\NadsMiniSim_x.x\data\sound\DefaultCabSound\Instructs

:Edit the file instructions.txt in that same folder.

3 Add an entry to instructions.txt to register your audio file in accordance with the following layout using the existing entries as a template:

:Unique_ID Filename Normalized_Volume

:Unique_ID is whatever unique number you assign to your file.

:Filename is the name of your .WAV file.

:Normalized_Volume is the volume your audio file should play, where 0.00 is silence and 1.00 is maximum volume.

'''NOTE: Remove all spaces in your audio filename.''' If needed, use the underscore character instead of spaces.

===Troubleshooting Custom Audio Additions===
After installing new .wav files and adding them into the audio configuration file '''instructions.txt''', if the audio file does not play:
*Check the Audio Engine window while miniSim is still running. The Audio Engine will display file errors,.
*If Audio Engine does not display a message similar to: Audio Engine loaded normally, scroll through the window messages and look for any .wav or load error messages.

==Re-use of Scenario Elements==
Scenario authoring can be an intensive undertaking. It makes sense therefore to leverage your development efforts by re-using scenario elements where possible.

ISAT provides a number of ways to re-use scenario elements:
# copy/paste
# external references
<span style="color:#ac6600"># exporting elements as '''groups'''</span>
# isc scripts

Each of these methods have their strengths and weaknesses.

===copy/paste===
The simplest method to re-use scenario elements among different scenario files is copy/paste. This is possible for most scenario elements* even if the source and destination roadmap/BLIs are radically different.

[[File:copy_paste.png|400px]]

It is also possible to copy an ISAT element from one scenario to another as '''TEXT''' by selecting the element and using the windows copy shortcut CTRL-C, then open a text file and paste it using the windows paste shortcut CTRL-V.

'''NOTE:''' Traffic sources are '''not''' portable using copy/paste.

'''NOTE:''' Not all elements can be copy/pasted. Elements created from a Create Element action cannot be copied - it is necessary to select the parent element and copy that instead.

[[File:copy_paste2.png|400px]]

In the above diagram, elements at '''B''' and '''C''' cannot be copied/pasted because they have been created by element '''A'''. It is necessary to copy the element at '''A''' instead. If only the elements at B are needed, the best method will be to copy/paste as Text.

'''NOTE: ISAT will not copy elements containing road coordinates (elements with a path) to a scenario that does not share the same BLI as the source (copy from) scenario.'''

A partial solution to such cases is to remove the path first, copy the element, paste into the destination scenario, then re-create the path manually.

===External Reference===
An external reference scenario is intended to be re-used by multiple 'parent' scenarios. The effort of authoring objects is thus leverages across multiple files, without needing to re-create the same elements more than once.

[[File:re_use_xref_1.png|400px]]

Common uses of external references include traffic, traffic signal operation, traffic sign appearance or other environment features which have multiple appearances (billboards, some tile related scenery, etc).

NOTE: Multiple external references are possible; but because objects are categorized by group, it is not entirely necessary.

For example, one external reference file contains traffic, another contains signs. These two external reference scenarios could be combined into one file.

[[File:xref_overview2.png|400px]]

NOTE: Each group defined must be unique across all files: parent and external reference files.

In order to use an element in an external reference scenario, it is necessary to define and assign a group to all elements that you wish to control from the parent scenario.
At this time there is no visual hint in ISAT to indicate if a group has been assigned to an element or not - each element has to be confirmed independently.

However, a properly authored external reference element cannot be edited within the parent scenario (after you have done Add Ref. to use the external reference file).

An alternative is to insert groups using a text editor with macro capability, or to use a program or external script to make the necessary changes.

'''NOTE:''' If the external reference file is for object contained in the parent scenario (for example, an external reference file containing traffic signals with a group defined) it is still necessary for that group to be defined in the parent file.

With traffic signals, ISAT requires ONE explicit group reference, which will be contained in the HCSM TrafficLightManager block as shown below. If you require the use of traffic signals in an external reference, the recommended way to do this is through ISAT because then it manages the group assignment for you.

==== HCSM TrafficLightManager scenario block ====

HCSM TrafficLightManager
HCSM CLG
IntrsctnName "I1_40260_4620"
Duration 2.0000000E+01 3.0000000E+00 1.0000000E+00 2.0000000E+01 3.0000000E+00 1.0000000E+00
GroupName "TrafficSignals"
LightName "s_signal_r1_LTRN_40260_4620_270"
LightName "s_signal_r1_RTRN_40260_4620_270"
LightName "s_signal_r2_LTRN_40260_4620_270"
LightName "s_signal_r2_STRT_40260_4620_270"
LightName "s_signal_r3_STRT_40260_4620_270"
LightName "s_signal_r3_NORM_40260_4620_270"
Pattern "FLTY" "R" "R" "R" "R" "R" ""
Pattern "RTG" "R" "R" "R" "R" "R" ""
Pattern "LTR" "LTR" "LTR" "FLTY" "FLTY" "LTR" ""
Pattern "SR" "SR" "SR" "SG" "SY" "SR" ""
Pattern "SR" "SR" "SR" "SG" "SY" "SR" ""
Pattern "R" "R" "R" "G" "Y" "R" ""
&&&&End&&&&
&&&&End&&&&

'''NOTE:''' At this time there is a known issue using the write cell '''SCC_Audio_Trigger''' action in external references. Although the trigger containing this action can be assigned a group and used as an external reference, audio does not play.

<span style="color:#ac6600">'''Because ISAT updates static object positions (elevation) to the terrain (roadway) when the scenario file is saved, the best way to use a custom elevation is to put such objects into an external reference file in order to isolate those objects from normal scenario editing.''' </span>

====Define a Group====
<span style="color:#ac6600">'''NOTE:''' ISAT 1.8.5 and 1.8.6 currently do not work properly with group files. These versions will not import objects within a group file. There is a workaround which involves the following process, but instead of reading the saved group file into a scenario the workaround requires editing the scenario as text and inserting the objects within the group file into the scenario.</span>

RMB on the element and choose from the context menu: Group >> New Group (if this is a new group) or Group >> (choose an already defined group).

'''NOTE:''' The first time you create a group for an object, ISAT will automatically assign the group to that object.

After defining and assigning groups to the scenario elements needed, save the scenario file then close it.

Open or create the parent scenario file and use the Add Ref. button at the bottom of the ISAT window to select your external reference scenario. After you choose a file ISAT will present you with the groups found in that scenario. Choose the groups you with to include and click the 'Okay' button. Click the Add Ref. OK button to complete the process.

Currently import group file operations are not working, but it is possible to insert the group file content (all HCSM StaticObjects) into a scenario manually by using a text editor to copy text from the group file and paste that into a scenario file into the HCSM Static Object section of the scenario file.

[[File:group_text.jpg|400px]]

'''NOTE:''' ISAT does not enforce logic on your external reference authoring. If you add references to scenarios that do not share the same roadmap/BLI as the parent scenario, it is likely that elements will be placed at the origin (in cases where the external reference roadmap contains roadways not found in the parent) if it even loads.

===Exporting ISAT Elements as Groups===
Transferring ISAT elements among scenarios can be accomplished using groups. As with external reference scenarios, one or more groups must be defined and then assigned to one or more elements.

After defining and assigning groups select the group for export using the Group select drop-down located at the lower left corner of ISAT. Choose a group to export and then click the 'Save Group' button. Save the file.

TBC insert graphic sequence diagram here

'''NOTE:''' If you cannot locate the group file in the folder specified, check the ISAT install\data folder. This is typically:

C:\NADS\ISAT\data

===Group File Contents===
The group file is a text file and can be opened or edited in a text editor.

The following is a group file containing one ADO. Note the GroupName line near the bottom:

Header
LriFile "_dev.bli"
LongComment "this is a test group export"
ShortComment "this comment was left empty"
&&&&End&&&&
HCSM Ado
RunMode "eREMOTE_CONTROL"
RandomSol 0
Name "Ado1"
DynModel "Non Linear"
LogFile ""
LatOffsType 0
CreateRelLatInFeet 0
CreateRelOffsLonUsingExpr 0
CreateRelOffsLonExprStr ""
AutoControlBreakLights 0
AutoControlHeadLights 0
UseReaDel 1
StdToAccType 0
StdToDecType 0
StdToDecVal1 9.0000000E-001
StpToAccType 0
DecToAccType 0
FollowTimeMin 1.0000000E+000
FollowTimeMax 2.0000000E+000
EmergDecClip -1.1000000E+001
Accel2Catch 0
NormVel2Kp 7.0000000E-001
PathSearchDepth 2
LcvFall 1.5000000E+000 2.0000000E+000
LcvFreq 3.0000000E-002 5.0000000E-002
LcvRAmpl 1.0000000E-001 5.0000000E-001
VelCtrlInitMatchOvVel 0
VelCtrlFollowSpeedLimit 0
VelCtrlDistType 0
MaxLatOffset 9.0000000E+000
LongComment " "
ShortComment " "
SolName "Audi"
RoadPos "r1_1320_44220:2:32414.44:0.00"
GroupName "TEST_Group"
&&&&End&&&&
HCSM StaticObjManager
&&&&End&&&&
HCSM DriverMirror
&&&&End&&&&
HCSM IntersectionManager
&&&&End&&&&

===ISC Scripts===
Scripts are an efficient way to automate repetitive and/or complex tasks.

ISAT uses a custom language (ISC) to automate placement and manipulation of scenario objects. Combined with simple direction commands and the capability to navigate a road network, ISC scripts can ask the scenario author for input and prompt for selecting objects.

ISAT installs with some ISC script files. If your version of ISAT contains a data\isc
folder, then your version of ISAT is capable of running scripts. You can create
additional scripts as needed. All scripts located in the data\isc folder will load in ISAT
when ISAT is launched.

You can use these scripts for reference in creating your own custom scripts.

New scripts created during an existing ISAT session will not appear until ISAT is re-
launched.
Scripts that have been edited will not update until ISAT is re-launched.

Unless otherwise indicated, scripts are case-sensitive.

'''NOTE:''' Please do not edit the existing scripts!

Make a copy of any existing script before you make changes. In the event your modified script does not work, you can look at the original file for reference.

ISC scripts are located on the ISAT Elements widget. Custom isc scripts are located after the 'Events' separator.

Using an ISC script involves LMB + dragging the desired script onto the workspace. In some cases the script will ask for inputs.

ISC can be also used to create an entire event, thus ensuring that all events created will be entirely identical in terms of settings and locations for all created elements.

ISC scripts are text files located within the ISAT installation data folder. Only the custom ISC scripts are located in this folder. This is typically:

C:\Nads\Isat\data\isc

====Icon Files====
Script icon files are 8-bit windows icon files (file.ico). GIMP is capable of exporting valid ico files. To create an ico file, scale it to 32x32 pixels. Export the file as .ico to the isat\data\isc folder.

In order for a script to use an icon file, both files must exist in the isat\data\isc folder.

====ISC Script Examples====
This section contains example scripts with notes.

'''Rotate sign'''

.Name SetSignRotation
.Icon SignRot.ico
Static sign
Select(sign,"Please Select a Sign")
sign.SetAngle(Anchor)
.End

'''Place Multiple Static Objects (TrafCone)'''
The following script asks the scenario author for number of cones to generate, position and offset values and then generates the objects.

A breakdown of the script follows the code block below.

.Name Cones
.Icon cone.ico

Block coneBlock %%%
HCSM StaticObject
IsNewObj 1
Name "Cone_xxx"
SolName "TrafCone"
Option 0
Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
&&&&End&&&&
%%%
Static cone;

Value dist1
Value numberOfCones
Value distance
Value variablePart
Value randDistance
Value speed
Value Count
Value LatOffset

Block tempBlock
tempBlock = coneBlock
Count = 1
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

Ask(numberOfCones,"How many cones?" )
Ask(dist1,"Distance between cones?" )
Ask(LatOffset,"How much offset?" )

Position posRp
Position tempPos
posRp = Anchor
numberOfCones = numberOfCones

Repeat numberOfCones
posRp.GoForward(dist1)
# test comment
tempPos = posRp;
tempPos.SetOffset(LatOffset)
cone.RoadPos = tempPos
cone.Clone
Count = Count + 1
tempBlock = coneBlock
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

End
.End

====Script Breakdown cones.isc====

This section contains a description of the elements used in the script. The script segment is followed by a brief text description.

This script places a number of object copies (TrafCone) using information provided by a user.

.Name Cones
.Icon cone.ico

The first line contains a keyword '''.Name''' followed by the name of the script. This is the name that ISAT will use on the Isat Elements widget for the script. Note the script name does not have to be the same, but it is good computing practice.

The second line begins with the keyword '''.Icon''' followed by a file name. This file must exist in the ISAT\data\isc folder (accompanying the script file). This is the icon ISAT will use for the script.

Block coneBlock %%%
HCSM StaticObject
IsNewObj 1
Name "Cone_xxx"
SolName "TrafCone"
Option 0
Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
&&&&End&&&&
%%%

This is the data section of the script, which is defined using the keyword '''Block'''. A block name follows the keyword, and the data start is defined with '''%%%'''.

The HCSM StaticObject section has been copied from a scenario. In this case, a static object was placed into the workspace and then copied into a text file.

Name "Cone_xxx"
Note: the object name contains a marker that can be used to programmatically name instances of the object:

SolName "TrafCone"
This line begins with the keyword '''SolName''' followed by the name of the object as it is defined in the sol2.txt file.

Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
The Position of the static object will update when the script activates and instanced objects are placed in the workspace.

Static cone;
This line begins with the keyword '''Static''' followed by a variable name.

Value dist1
Value numberOfCones
Value distance
Value variablePart
Value randDistance
Value speed
Value Count
Value LatOffset

This section defines variables with the keyword '''Value''' followed by variable names. Using descriptive names is better than generic names. From the variable list it already seems clear what the programmer cares about: number of cones and distances.

Block tempBlock
tempBlock = coneBlock

This section defines a block using the keyword '''Block''' followed by the variable name.

The next statement replicates coneBlock into tempBlock.

Count = 1
Initialize the value of the variable Count to 1.

tempBlock.Replace('xxx',Count)
The built-in '''Replace''' function changes the string 'xxx' to the value of the variable Count.

cone.SetBlock(tempBlock)
This statement creates a block using the function '''SetBlock''' called cone, and copies the contents of tempBlock into it.

Ask(numberOfCones,"How many cones?" )
Ask(dist1,"Distance between cones?" )
Ask(LatOffset,"How much offset?" )

This section asks the user for input and puts that information into variables:
*Number of cones
*Distance between cones (dist1)
*Lateral offset (calculated from lane center)

Position posRp
Position tempPos
posRp = Anchor
numberOfCones = numberOfCones

This section contains position variables and assigns the value of numberOfCones.

Repeat numberOfCones
posRp.GoForward(dist1)
# test comment
tempPos = posRp;
tempPos.SetOffset(LatOffset)
cone.RoadPos = tempPos
cone.Clone
Count = Count + 1
tempBlock = coneBlock
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

This section is where the work happens. Reading from the top, this section is contained within a loop defined by the keyword '''Repeat'''. The number of times to repeat follows in a variable numberOfCones.

'''posRP.GoForward()''' is a built-in function to take the current position and shifts it forward by the amount specified in the dist1 variable.

#test comment
This is a comment defined by starting the line with the comment keyword '''#'''

tempPos = posRp;

Assign the value of the variable tempPos to the value currently in '''posRp'''

tempPos.SetOffset(LatOffset)

Another built-in function or attribute to the position element which defines a lateral offset (distance from the lane center). This statement places the value of a variable LatOffset into the offset element of the tempPos variable, using the operand '''SetOffset'''.

cone.RoadPos = tempPos

This statement sets the road position variable for cone to the value in the variable tempPos.

cone.Clone

Duplicate the block cone using the operand '''Clone'''

Count = Count + 1
Set the value of the variable Count to the value of Count plus one. This statement increments the value of Count for each loop processed.

tempBlock = coneBlock

Create a new block tempBlock by setting it to the content of coneBlock.

tempBlock.Replace('xxx',Count)

Use a built-in function to '''Replace''' the string 'xxx' with the value of the Count variable

cone.SetBlock(tempBlock)

Use the built-in function '''SetBlock''' to place the modified tempBlock (modified by the string replacement command earlier) into the cone block.

End
.End

The last two lines terminate the loop and the script, respectively.

====How to Create an ISC Script====
The simplest way to create an ISC script is to find an existing script that does something similar to your desired behavior and edit it.

=miniSim Simulation Data=
MiniSim runs on shared memory:
*miniSim is a collection of programs
*shared memory is a commonly accessed 'blackboard' list: a Cell and a Cell Value
:The DAQ file is a snapshot of this 'blackboard' memory for every frame.

*Scenario can write to cells added by the scenario author
:-i.e., for custom hardware or tasks/events

'''NOTE:''' Custom cells must be present in the collect file (NadsMiniSimCollect.cec) '''prior to''' simulation in order for the custom cells to be present in the DAQ.

NOTE: The cell type defined in the collect file must be followed, or garbage values will be used

Use of a DAQ file implies that at some point, data reduction will be needed.
Data reduction: the process of distilling measures from the DAQ file, i.e.
*Event definition
*SDLP
*Average headway

==What is the Difference? Cell vs. Variable==
*A Cell is a pre-created “slot” in shared memory
:-Specified in the .CEC collect file,
:-Saved in the DAQ file,
:-Can be sent to custom programs;
:-Can create & use custom cells;
*A Variable is a name value internal to the scenario
:-NOT saved to the DAQ file,
:-Can use to track items in the scenario
:i.e., how long the driver has been exceeding the speed limit
:-Initialize conditions in the scenario.

=== Variables Save ===
Variables can be saved to disk as a single value text file (ie, multiple values over time are not supported) through the use of a '''Store Variable''' action:

[[File:2021-08-23_13h28_49.png|400px]]

The file is stored in the miniSim_x.x\bin.x64 folder.

'''NOTE:''' The name of the file is defined within the Store Variable action. '''Care must be taken to save variables to unique file names''' in the case of multiple scenarios running on miniSim at the same time (if they share common variables), as would be the case if triggers are copied from one scenario to another.

=== Variables Restore/Read ===
Variables can be read into the simulation through the use of a '''Load Variable''' action:

[[File:2021-08-23_13h32_39.png|400px]]

==Cell Types==
This is a partial list of cell types.

*CFS = control feel subsystem (steering wheel, pedals)
*CIS = control information subsystem (gear, turn signal, buttons, etc)
*TPR = terrain profiler for terrain queries
*VDS = vehicle dynamics for accelerations, position, engine speed, speed, etc.
*ACC = adaptive cruise control
*RCM = configuration management for setting variables that affect subsystem configuration (ACC enabled or disabled, for instance)
*SCC = scenario
*SOP = for one time initializations at the start of the simulation.

=='''Data Output Actions'''==

*Write to Cell Actions
:-Write the value of a variable or cell to a cell
:-Write to a custom cell
:-Cannot overwrite another systems output
'''NOTE:''' Although it is possible to write to a different system cell, that value will be over-written on the next frame. Thus it is effectively not feasible nor desirable to do.

'''<span style="color:red">Also Note: the limit for maximum number of write to cell actions that can be performed in one frame is 8.</span>'''

*Set Variable Action
:-Sets the value of a variable
:-Does not have to be created first
:-Not saved in the DAQ unless written to a valid cell
*Logstream
:-Log data action

===Data Output Methods===
Your data is the primary reason for simulation.

1. Default miniSim scenario measures
:- Immediately available

2. Alternate scenario measures (DAQ file)
:- Processed through data reduction

====Default miniSim Scenario Measures====
*Saved to a drive report.txt file
*Saved to the same Location as DAQ files;
:Scenarioname_timedatestamp_report.txt
•Measures calculated overall, and up to 20 Events during drive:
:Collision Count Lane Departure Count
:Maximum Speed Lane Departure Percentage
:Minimum Speed Speeding Count
:Average Speed Speeding Percentage
:Standard Deviation of Speed Average Headway
:Standard Deviation of Lane Position

====Default miniSim Scenario Measures Require Scenario Event Definition====
In order to capture meaningful data into the default miniSim measures, a scenario must be configured properly to define events.

Use the Write to Cell action to activate the default measures.

[[File:2021-07-02_11h02_44.png|400px]]

*At the start of scenario, set:
::SCC_EventStatus =0
::SCC_EventNumber = 0
*At the start of the first event, set:
::SCC_EventStatus = 1
::SCC_EventNumber = 1
*At the end of the first event, set:
::SCC_EventStatus = 0
*At the start of the second event, set:
::SCC_EventStatus = 1
::SCC_EventNumber = 2
*At the end of the second event, set:
::SCC_EventStatus = 0

Continue this pattern; at end of final event, set:
::SCC_EventStatus = 0

====Default miniSim Scenario Measures Sample Report====
The following is an example report for 4 events. Note the remaining events present in the report are all zeroes or -1.00.

[[File:default_measures_report.png|400px]]

===="Alternate" Scenario Event Definition aka Using Logtreams====
'''NOTE: This method is the more typical/standard method for defining events.'''

Defining an event is key to partitioning simulator data into useful sections. Processing these sections is the essence of '''data reduction.'''

These useful sections are partitioned using logstreams and are generally called '''Events''':
*A logstream is a data marker present in the DAQ file
:there are 10 logstreams
:use logstreams to indicate when things happen '''in the data:'''
:at the start of an event; i.e.,
::grab all data where logstream 1 = 100 (example value)
:during a sub-section of an event
:at the end of an event (typically clears to 0)

Logstreams help separate/filter data;
*SDLP is not useful during emergency maneuver events

Logstreams can be useful to debug events;
:marking in the data when triggers fire
:ensuring event counters work; these are typically sequential, so any logstream deviation identifies a problem

*How to define a Scenario Event:

Set logstream values at scenario event start
:during and at scenario event end, set or clear logstream values:
For example:
::logstream 1 for event ID
::logstream 2 for sequencing the event (during/within event)
::logstream 3 for restart number, etc.

*Requires data reduction to fully process drive data
*Does '''not''' support default measures
:unless those measures are used in parallel with the logstream method

*The use of logstreams allows a scenario author to encode event and environment information into the scenario and as a result, into the simulator data stream.

====Example Alternate Scenario Event====
This section contains an example of a scenario that uses logstream 1 to define an event and environmental context.

In the following example, logstream 1 (LS1) is used to:
#define the scenario start, which is also in this example the event start. NOTE: This is not typical.
#when the driver is 805f from the intersection halt line, set a value into LS1
#when the driver is 500f from the intersection halt line, set a '''new value''' into LS1 NOTE: This could also use a different LS than the one used to define your event, i.e., 1
#when the driver activates a roadpad trigger to reset a force velocity (FV) on a lead vehicle

[[File:event_def_LS.png|400px]]

In the following event definition, an expression trigger is used to set a logstream value and execute two additional actions pertaining to the event.

[[File:event_ET_LS3.png|400px]]

====How to Export Data from A DAQ file using ISAT====
ISAT can display and export DAQ data. NOTE: This is 'raw data', not previously processed. This method can be used to test scenarios, confirm or identify data issues.

TBC: example export here

=Terminology & Documentation=
This section contains terminology and references to related documentation.

'''Action''' - the basic scenario element; the basis for creating scenarios. Actions may be executed on scenario elements (dynamic or static), create or remove elements, or the environment (time of day, visibility) or the simulated cab instrument panel.

'''ADO''' - Autonomous Dynamic Object; self-controlling to a degree.

'''Cell''' - Data elements that are recorded to during a drive; some cells may be used by the scenario author. Custom cells may be added to miniSim.

'''Event''' - anything significant that happens during a drive where the driver condition or response is desired to be identified in the drive data. Can be isolated from general driving through default measures or logstreams.

'''ISAT''' - Interactive Scenario Authoring Toolkit; used to create scenario files for use on the NADS facility or miniSim simulators.

'''ISC''' - ISAT script file.

'''Scenario''' - The simulation experience during a drive; also known as a scenario file, which contains all instructions to the elements within a simulator drive.

'''SDLP''' - Standard deviation lane position

'''SOL''' - Scenario Object Library; objects that are available to ISAT during scenario authoring must be present within the sol2.txt or an auxiliary sol2 (sol2_aux.xxx.txt) file.

'''Trigger''' - A scenario element that contains actions to execute during simulation. All triggers share the same actions, but execution depends on the trigger type.

'''TTA''' - Time to arrival.

'''TTC''' - Time to collision.

=Reporting ISAT & Scenario Issues=
*How to report ISAT & scenario issues:

When reporting issues with scenarios it is helpful to provide as much information as possible.

This often includes scenarios (including any external reference files) and the .LRI file used by the scenarios, screenshots or video that demonstrate the issue being reported and relevant DAQ files. It can be very helpful to include coordinate information with the screenshot or video.

The .BLI file is created from the .LRI and is much larger than the LRI so it may be more convenient to send the LRI file. NADS staff can re-create the BLI file from the LRI.

Some graphics anomalies may be issues with the tile model and not a scenario or miniSim problem. These include:
#white block shapes in the environment
#gaps or missing geometry; i.e., holes
#improper lighting (dark features present during the day)

If these issues happen on a custom roadmap/database world, please include the TMT .mos file as well so NADS can re-construct your environment.

==How to contact the NADS miniSim team:==

email [mailto:miniSim-Support@uiowa.edu minisim support]

[mailto:andrew-veit@uiowa.edu Andrew Veit]
Director of NADS miniSim

[mailto:joseph-meidlinger@uiowa.edu Joseph Meidlinger]
Program Coordinator NADS miniSim

[mailto:oscar-hernandezmurcia@uiowa.edu Oscar Hernandez Murcia]
MiniSim Application Programmer/Analyst

[mailto:chris-schwarz@uiowa.edu Chris Schwarz]
Data Reduction & Vehicle Dynamics

[mailto:shawn-allen@uiowa.edu Shawn Allen]
TMT, Modelling & Support

==How to check what BLI file is used by a scenario==

#You can edit the scenario in a text editor; near the top of the file will be a line starting with '''LriFile''' followed by the name of the BLI file in double quotes.
#You can use '''grep''' to inventory single or multiple scenarios:
:grep bli <scenario file/s>
:A partial listing is shown in the example below. NOTE: The files shown will likely be different on your PC:
C:\NADS\Isat\data\training.demo_scn>grep bli *.scn
Demo_Expression_Lead_Vehicle_Variables.scn: LriFile "simple_rural.bli"
Demo_Expression_Trigger_to_Lead_Vehicle.scn: LriFile "simple_rural.bli"
Demo_HUDD.scn: LriFile "simple_rural.bli"
ISAT-Samples-Avoid.scn: LriFile "esc_dry_05.bli"
ISAT-Samples-Right-Incursion.scn: LriFile "esc_dry_05.bli"
ISAT-Samples-TrafficLightTest.scn: LriFile "simple_city1.bli"
ISAT-Samples-TrafficLightTestB.scn: LriFile "simple_city1.bli"
ISAT-Samples-YellowLightDilemmaB.scn: LriFile "simple_city1.bli"
KBW_TEST.scn: LriFile "simple_rural.bli"
KBW_TESTB.scn: LriFile "simple_rural.bli"
demo.createADO_and_trigger.scn: LriFile "simple_city1.bli"
demo.creation_radius1.scn: LriFile "simple_city2.bli"
demo_FV_sum_of_Sines.scn: LriFile "simple_city2.bli"
demo_LV_Decelerate.scn: LriFile "simple_city2.bli"
demo_LV_cut_in.scn: LriFile "esc_dry_05.bli"
demo_MG.scn: LriFile "simple_city2.bli"
demo_TM1.scn: LriFile "simple_city2.bli"
demo_TT_null.scn: LriFile "simple_city2.bli"
demo_actions_text.scn: LriFile "simple_city2.bli"
demo_alt_data_measures.scn: LriFile "simple_city2.bli"
demo_audio_virtual_object.scn: LriFile "esc_dry_05.bli"
demo_audio_virtual_object_simple_rural.scn: LriFile "simple_rural.bli"
demo_auto_cloud1.scn: LriFile "simple_city2.bli"
demo_coneISC1.scn: LriFile "simple_city2.bli"
demo_dddo.scn: LriFile "simple_city1.bli"
demo_dddo_B.scn: LriFile "simple_city1.bli"
demo_forXRef_traffic.scn: LriFile "simple_city1.bli"
demo_force_vel_01.scn: LriFile "simple_city1.bli"
demo_groupImport.scn: LriFile "simple_city2.bli"

==How to configure miniSim for screenshots to include coordinates==
You can enable coordinate display on miniSim by changing the focus to the main display. #Move the cursor until it is positioned in the main display area, then LMB. When successful the main display will appear to "blink".

Press the keyboard n key twice. This will cause coordinate information to display in the lower left corner of the main display.

[[File:miniSim_show_coords.png|400px]]

The n key is a toggle; to disable coordinates, press it twice (2x) again. '''NOTE:''' the cursor focus must be in the main display in order for this to work.

=Additional Resources=
[[:File:ISAT_Quick_Start.pdf|ISAT Quick Start Guide]]

[[ISAT_Demonstration_Scenarios|Demonstration Scenarios]]

[[:File:Create_Use_Custom_Cells.pdf|Create and Use Custom Cells on MiniSim]]

[[:File:Function_ReadCell_20180824.pdf|ReadCell function]]

[[:File:TrafficManager_Ch12.NADS.Internal_ISAT_UsersGuide.pdf|Traffic Manager]]

=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 [[ISAT_Reference_Manual_Table_of_Contents#ISAT_Reference_Manual|reference manual for ISAT can be found here.]]

ISAT User Guide Table of Contents

2023-09-15T14:53:11Z

Shawn Allen: /* What is ISAT? change NADS to DSRI */

== Who should use this document? ==
Anyone learning to use the DSRI 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
*CTL-<some other key>: Press and hold the Ctrl and then press <some other key>. Most typically used for copy (CTRL-C) or paste (CTRL-V).
*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 and modify for use in your own scenarios as needed.

== <span style="color:#FF0000"> '''Known Issues'''</span>==

Added 2022.07.01 '''Relative Creation''' does not currently work for ADOs on miniSim.

'''Expression clarification'''

Increment and decrement operators (++, --) are not considered expressions by behaviors. They should not be flagged as expressions when used in the Value field of a Set Variable action.

Added 2019.11.07 '''File reset issue'''

ISAT has a long-standing bug which can reset your static object options when your scenario file is saved to disk.

'''It is strongly recommended that you use [[#External_Reference|external reference scenario files]] to avoid this. '''ISAT does not reset static object options in the xref file.

Added 2021.12.29 Expression Triggers and Values

'''Using Values in Expression Triggers'''

To ensure proper execution of expression triggers, it is recommended that the values used include the desired range by decreasing the lower threshold or increasing the upper threshold '''instead of using the exact value.'''

For example, to process values in a range (7031 - 7040):

[[File:2021-12-29_12h38_09.png|400px]]

'''Note: remember that negative values must be calculated since the expression parser does not parse negative values otherwise.'''

For example, to properly parse a specific transmission gear (Park):
'''ReadCell('CFS_Auto_Transmission_Mode', 1) = ( 0 - 2 )'''

<span style="color:#FF0000"> '''Rehearsal without specifying a start location</span>

In some cases ISAT will crash if the external driver (XD)/start location has not been specified or is missing due to a sol2 file configuration error.

=='''ISAT Overview & Interface Basics'''==
This section contains information about ISAT and the ISAT interface.

===What is ISAT?===
ISAT is the DSRI 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 <span style="color:#FF0000">'''not an object editor'''</span> 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.
[[File:miniSim_scenario_compnents.png|center|640px]]

*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.

[[File:anatomy_of_a_scenario.png|center|400px]]

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

[[File:scenario_as_text.png|center|640px]]

This diagram shows the same scenario in (left to right) 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, <u>always</u> check your edits in ISAT!'''
*Copy/Paste - delete paths from elements when the BLI is different between your source & destination BLI files. The following scenario elements contain paths:
::ADO (with a path specified)
:: Any roadpad trigger (roadpad, Time to Arrival, Follow)

'''NOTE: A Traffic Source is not a portable element but it can be re-created in ISAT or integrated into a new scenario by copying the element from the source scenario then using a text editor to paste it into the destination scenario'''

'''How can I find information in multiple files easily?'''

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.

What if you don't know what to look for? How do 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
[[File:action_overview.png|400px||border|caption]]

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)

==='''Adding an action to a trigger'''===

The following example uses a Time Trigger; remember that '''all triggers share the same actions'''.

To add an action to a trigger you can double-click on the trigger, navigate to the '''Actions''' panel, and click on New to create a new action.

[[File:2022-11-30_12h47_23.png|400px]]

The possible actions are listed under the '''Action Type''' drop-down menu.

[[File:2022-11-30_12h47_44.png|400px]]

Actions are arranged in a 'stack' and are processed from top to bottom. If you use multiple actions you should enable the '''sequential flag''' to ensure each action is executed in sequence. Without the sequential flag, actions will be processed as fast as the simulator behaviors can execute.

[[File:2022-11-30_12h52_58.png|400px]]

Actions may be re-ordered in the stack using the '''arrows''' located near the action stack list.

=='''ISAT Modes of Operation'''==
[[File:ISAT_modes_of_operation.png|400px]]

*Edit
*Rehearsal
*DAQ playback
*Monitor '''Currently not available'''

==='''Edit & Rehearsal Modes'''===

*Edit - this is where scenario authors will spend the most time.
::Creation or modification of scenario
::Link to or import portions of other scenario elements

[[File:mode_edit.png|400px]]

*Rehearsal
::Debug & test scenario
::Simulates scenario using Behaviors and Vehicle Dynamics
::Displays error messages from behaviors

[[File:mode_rehearsal.png|400px]]

'''NOTE:''' Rehearsal mode <span style="color:#FF0000">simulates </span>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

[[File:mode_playback.png|400px]]

==='''miniSim Scenario Components'''===

The following diagram shows an overview of scenario related components of the NADS miniSim and how these components work together.

[[File:miniSim_scenario_components_wDAQ.png|400px]]

=='''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.

[[File:isat_workspace_general.png|400px]]

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)
[[File:isat_status_bar_overview.png|400px]]

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.

[[File:isat_user_prefs_status_bar_settings.png|400px]]

====ISAT Iconography====
ISAT provides graphic hints for triggers placed in scenario that can be useful when editing or maintaining scenarios.

The general format is a border enclosing miniature icons of the trigger and first action contained in that trigger. Additional information representing one or many actions is also shown.

[[File:hints1.png|400px]]

ISAT will list all trigger actions when a trigger is selected, but these hints provide a way to quickly identify what actions have been authored.

[[File:hint2.png|400px]]

*A Roadpad trigger, one action: '''Traffic Light Action'''
*B Roadpad trigger, multiple actions, first action is '''Remove Element'''
*C Roadpad trigger, multiple actions, first action is '''Set Dial'''
*D Roadpad trigger, constrained to road (lane), no actions - this is an empty trigger
*E Roadpad trigger, multiple actions, first action is '''Log Data'''
*F Global Time Trigger, single action: '''Set Dial'''

[[File:handle.png|400px]]

The element handle is the red dot visible in most of the triggers.
The handle can be dragged into position, and the trigger will follow the handle

Drag the trigger off the handle to offset it's location from the handle

==='''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.

[[File:object_types_isat.png|400px]]

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
::*Traffic Source

:'''NOTE:''' Virtual objects are defined in the scenario, not in the SOL2.
[[File:object_types_world.png|400px]]

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.
::NOTE: 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.

==='''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:
#Follow a path using kinematics
#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:
#coupled
#relative trajectory
#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'''===
Traffic signals are objects with special operation and function; they are coupled to intersections and routes of travel through intersections to control traffic flow similiar to their function in the real world. Traffic signals are part of the source tile model and may not be re-positioned or physically altered by scenario except for their visual signal state appearance; i.e., red, green or yellow signals.

To control intersection traffic signals use Edit >> Traffic Light ManagerTraffic signals use a Signal State Table (SST) to control which signal states are active and when. Each intersection with traffic signals will have an associated SST.

[[File:traffic_light_state_manager.png|400px]]

The above diagram shows an intersection in the workspace to the right, and the traffic signal state table for that intersection on the left. At this point additional states (for signal condition) can be added by clicking the '''Add state button'''.

[[File:traffic_signal_state_table2.png|400px]]

The above diagram shows two states defined for the intersection, represented by the two columns of state condition.

Continue adding states until the desired signal cycle has been defined. Generally this consists of red, green or yellow states.

NOTE: There is currently no way to automatically author a series of traffic light signals

To author traffic signal lights in sequence or on a route, the scenario author has to manage the signal states

[[File:traffic_signal_state_duration.png|400px]]

To edit the signal state duration RMB on the duration field header and choosing '''Edit state duration''' on the context menu. Enter the desired value then click OK.

====Traffic Signal Types====
The ISAT status bar reports Traffic Signal Type name. There are two signal types:
#Standard signal - IDs may have no identifying information
:Valid signal states: Red, Yellow, Green, Flashing Red, Flashing Yellow, OFF
#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

[[File:traffic_light_extended_type_name_normal.png|400px]]
: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.

[[File:traffic_light_extended_type_name.png|400px]]

===Changing Signal States in Scenario===
Traffic signals are controlled in scenario by using a Traffic Signal Action to change the SST.

'''NOTE:''' The Traffic Signal Action works by changing the SST, '''not by changing the traffic signal.''' This is a subtle but important difference.

Setting a signal to an undefined state effectively does nothing to the traffic signal.

[[File:traffic_light_state_table.png|400px]]

The above diagram shows a fully populated SST, with one signal row highlighted in red, and one state column highlighted in green. The associated intersection corridor is highlighted, showing the signal controls a dedicated left turn.

During simulation, the initial signal state is defined by the left column. As the simulation proceeds, the signal state changes according to the duration states defined across the state table, proceeding left to right and then wrapping around to the beginning after the last defined state. Each traffic signal appearance changes according to the configuration of the SST.

As a driver approaches this intersection, assume the signal state is in the column left of the highlighted column ('''R'''ed), and the desired action is to change the signal to green.

The action used to change a traffic signal state is the '''Traffic Light Action'''.
Using a traffic light action requires the specification of a signal state, the traffic signal to affect, and a duration.

[[File:traffic_signal_action1.png|400px]]

In the above diagram the scenario author has specified the desired state as '''Green''' as shown in the action dialog.

However, referring back to the previous state table diagram, there is no such state present in the SST. That means this particular action will fail, and the traffic signal will not change as the driver approaches the intersection - because the action does not create a new signal state, it works by advancing the state table condition (column) to the specified condition. If the condition is not present in the SST then nothing will appear to happen.

In this example, the action should be edited to use the correct signal state '''Left Turn Green''', which is present in the SST.

'''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

[[File:known_issue_traffic_light_action.png|400px]]

'''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.

[[File:known_issue_traffic_light_action_workaround.png|400px]]

====Change A Traffic Light Using Scenario Action====
To change a traffic signal, use the Set Dial >> Traffic Light action.
'''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

[[File:traffic_light_state_table.png|400px]]

This diagram shows a fully populated traffic signal state change for an intersection.

*Static object traffic lights
:These are objects, not true traffic signals and so they are not controlled with the Traffic Light manager.

==='''Traffic Source'''===
A traffic source is a coordinator used to create traffic at specific locations in the road map (unlike the Traffic Manager). This is useful for creating ambient traffic. Traffic Sources creates ADOs or DDOs at random or user-specified intervals.

Elements created using a Traffic Source will be created at the locations specified by the user. If traffic is specified at multiple locations the actual location for each creation will be determined randomly during simulation.

'''Note:''' Using the Relative Creation flag on ADOs created by the traffic source will not create traffic at the specified location on the map, but use the information in the Relative Creation fields to populate traffic in the scene during simulation.

This method allows for more flexibility but care must be taken not to create so many ADOs that miniSim is unable to make frame rate. Too many ADOs will cause the scene to jump and 'jitter' and it will feel slower than normal.

==='''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 ISAT scenario rehearsal

===Custom (icon) file virtual objects===

[[File:virtual_object_custom_icon_file.png|400px]]

'''Note:''' Some versions of MiniSim_2.3 do not support custom virtual objects. For those installs, if you require this type of functionality, a workaround exists in the form of a 2D model that can be customized (i.e, sprite).

Virtual objects may be customized using graphics files (texture images) to display any desired custom element. This typically requires the use of a bitmap graphic. Various file formats are supported: JPG, BMP, PNG. It is possible some types of these formats may not work - in those cases, try an alternate format.

If image transparency is required and the custom icon does not display during simulation, please email dsri-minisim@uiowa.edu with a description of the issue, your scenario and custom virtual object image file.

Custom icon files must be located within the Nads MiniSim path for resources - at NadsMiniSim_x.x\data\visuals\Models\ModelTx.

===Standard virtual object shapes===
The virtual object shapes include:
# Circle
# Triangle
# Octagon
# Star
# Diamond
# Icon <- this is for custom virtual object graphics
# Rectangle
# Hexagon

The virtual object fill and border color and transparency can be set in the virtual object properties dialog panel.

[[File:virtual_object_std_shape.png|400px]]

====Virtual Object Workaround====

There is a scenario authoring method that can be used to emulate virtual object functionality through the use of a DDO that is coupled to any dynamic scene element, including the External Driver. One model has been created to support this method called "sprite".

'''Note:''' The sprite model is a 2D object present in the scene, and can therefore be occluded by other scene elements during simulation.

[[File:trafsign_sprite.jpg|400px]]

The sprite model is designed as a flat plane that continuously faces the viewer. It contains different sized planes and can be customized through textures.

When authoring your scenario, configure the sprite object to Off unless it should be visible at scenario start. During the scenario you can control the sprite appearance with a setSwitch action.

[[File:sprite_setSwitch_action_021121.png|400px]]

The who to effect should use the name of the DDO placed in your scenario. The switch name will be s_sprite as shown above. Any valid option can be used. An invalid option (greater than 30) will disable the sprite the same as selecting the OFF option.

==='''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'''===
<span style="color:#FF0000">'''All trigger types share the same Action types'''</span>
*IF Then conditional
*Predicate: i.e., the activating agent
:If predicate is TRUE, then do Action(s)
*Road related triggers are categorized by predicate type
:Named element
:Road (lane)
:Nth vehicle on path only

'''What trigger is appropriate?'''
To determine which trigger is most appropriate, consider the task you are trying to accomplish. '''The differences between triggers is their activation methods.'''

'''Global Time Trigger'''
[[File:isat_time_trigger.png|150px]]

Use this trigger when something has to happen at some point in time.

Time triggers are also useful as "placeholder triggers"; used to apply persistent actions to multiple elements with unique settings for each element. Normally a persistent action is the last action possible in a trigger since the persistent action fires continuously. Putting persistent actions into a time trigger allows the scenario author to continue an action stack in the parent trigger if necessary.

Time triggers can be used as a 'stopwatch' - elapsed time, such as ending a drive after 3 minutes by setting the trigger to fire using an Activation Delay of 180s (GTT >> General).

Often used as a placeholder for actions such as initializing variables, displaying text messages to the screen using Set Visual Display Text actions, etc.

'''Note''': A time trigger can have global elapsed time and activation delay of 0, which causes the action stack in the time trigger to activate when that trigger is created.

'''Roadpad Trigger'''
[[File:isat_roadpad_trigger.png|150px]]

Use this trigger when something has to happen at some location in the drive that does not require event timing to be comparable for all participant drivers. For cases where event timing must be comparable among all participant drivers use the Time to Arrival trigger (TTA) instead of a roadpad trigger.

'''Time to Arrival Trigger'''
[[File:isat_time_to_arrival_trigger.png|150px]]

Use this trigger when something has to happen relative to some point in the drive, and also ensure all study drivers experience the same event timing irrespective of driver style (conservative, slow vs. aggressive, fast). Time to arrival (TTA) trigger uses a time calculation from the trigger pad activation to a target location specified in the trigger.

'''Traffic Light Trigger'''
[[File:isat_traffic_light_trigger.png|150px]]

This trigger activates actions when the specified traffic signal state is reached. For example, if the desired action is to create a DDO pedestrian to step into traffic when the traffic signal is yellow, then the Traffic Signal Manager must be used to author the appropriate signal states for the traffic signal.

Typically some other trigger is used to control the traffic signal (ie, to change the signal to Yellow on approach). It is therefore perfectly valid to put the actions within this other trigger rather than relying on the traffic light trigger.

'''Note''': Once a traffic light action has been authored, ISAT may be prone to crashing when accessing that trigger. This problem can be avoided by creating a time trigger and isolating the traffic light action there, allowing the parent trigger to be modified without crashing. Adjustments can be made to the traffic light action time trigger in a text editor, or recreated if it becomes necessary to make adjustments and ISAT continues to crash when trying to make edits.

'''Note:''' The traffic light action does not change the traffic signal state, and it requires a valid state sequence to exist in the signal timing table (Edit >> Traffic Light Manager). The traffic light action '''will not create a signal state''' that does not already exist in the signal timing table.

'''Expression Trigger'''
[[File:isat_expression_trigger.png|150px]]

Use this trigger when something must be monitored, evaluated or calculated such as checking a variable or cell value, velocity of the driver or the state of simulator hardware (steering wheel angle, brake or accelerator pedal position) or distance from the driver to some other object in the scenario.

Multiple expressions can be used within the same expression trigger. In those cases, all expressions must evaluate to True in order for the action stack to execute unless using an '''OR''' operator.

Use the '''OR''' operator - the pipe character "|" if you want to activate the action stack if '''any''' of the expressions evaluates to True.

In the following example, the trigger checks for TrialNumber = 1 and FirstButtonPress variables, and then checks if Aux Button 1 or 0 was pressed:

'''ReadVar('TrialNumber') = 1.0 & ReadVar('FirstButtonPress') = 1.0 & (ReadCell('Auxiliary_Buttons', 0) > 0 | ReadCell('Auxiliary_Buttons',1) > 0)'''

'''Note''': Expressions can also be embedded into some other triggers, most notably the Set Dial >> ADO >> Forced Velocity action often used in Roadpad triggers.

'''Follow Trigger'''
[[File:isat_follow_trigger.png|150px]]

Use this trigger when something has to happen based on one ADO position relative to another scenario element (including the XD). The follow trigger requires a leader and a follower to be specified; when this condition is met, the trigger action stack activates.

'''Note''': Both leader and follower must be positioned on the follow trigger roadpad to satisfy the follow parameters.

'''Geometric Position'''
[[File:isat_geometric_position_trigger.png|150px]]

This trigger is most useful to perform actions for off-road actors such as walkers. The trigger predicate is limited to Name or Type and requires a geometric position to be defined.

A more limited version of the geometric position trigger can be implemented with a Global Time Trigger that contains a Creation Radius. Placing the creation radius defines the area where the trigger may be activate.

===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

[[File:Screenshot (208).png|800px]]

'''Note:''' The highlighted lane shows which lane is the '''activating lane'''. Other lane/s will not activate the trigger action stack.

===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

[[File:TTA.png|400px]]

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===

[[File:other_triggers.png|400px]]

*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===

Execute actions if input expression evaluates to TRUE; the expression is specified on the trigger Predicate tab.

====Syntax====
Expression triggers support a simple language syntax with operators and functions.
The syntax is infix notation; i.e. a + b, not a b +.

Note: It is not generally possible to embed one function call inside another:
cos(sin(x)) is therefore an invalid expression. ISAT will report invalid expressions during rehearsal of a scenario. Invalid expressions are not supported and will not operate as written during simulation.

'''Exception:''' Currently it is possible to use the square root function with GetObjDistPow2 as in the following example:

sqrt(GetObjDistPow2('Target_Object_Name'))

Multiple expressions may be combined using the logical AND (&) or OR ("|" pipe character).

Exp1 '''&''' Exp2, Exp1 '''&''' Exp2 '''&''' Exp ''N''

All expressions must be true for the trigger to evaluate to TRUE and execute the action stack.

Exp1 '''|''' Exp2
One of the expressions must be true for the trigger to execute the action stack.

Negative values are not directly supported by the expression parser. To use a negative value, it must be a calculated value such as the following:

'''ReadCell('CFS_Steering_Wheel_Angle',0)<(0-5.0)'''

==== Operators ====
Operators are used to create expressions.

'''String'''
:Used within quotes as a string literal; i.e., 'some string'

Grouping
:Parentheses group elements together; i.e.,
:'''()'''; (a), (a + b)

Multiplication
:'''*'''; a * b

Division
:'''/'''; a / b

Addition
:'''+'''; a + b

Subtraction
:'''-'''; a - b

Note: negative values must be expressed with a subtraction operation:
(0 - 5), not -5 (invalid)

Greater than
:'''>'''; a > b

Less than
:'''<'''; a < b

Logical And
:'''&'''; a & b

Both a and b, otherwise returns 0 (FALSE)

Logical Or
:'''|'''; a | b

a or b returns 1 (TRUE)

====Expression Functions ====
Functions are used with operators to create expressions.

Function: '''sin'''
:sin -sine

Syntax
:sin(float x)

Description
:The sin() function returns the sine of x, where x is given in radians.

Return Value
:The sin() function returns a value between -1 and 1.

Function: '''cos'''
:cos –cosine

Syntax
:cos(float x)

Description
:The cos() function returns the cosine of x, where x is given in radians.

Return Value
:The cos() function returns a value between -1 and 1.

Function: '''ReadCell'''
:ReadCell()

Read a Cell value.

Syntax
:ReadCell(string Name, int Cell Array index)

Description
:ReadCell returns the value of a given cell (a cell is the current instance of a variable that will be maybe written to a daq file).

Index specifies a 0 based index into the array. Since most cells are single element arrays, a value 0 indicates the first element.

Cells valid for the ReadCell function are defined within the cell collect file NadsMiniSim.cec located in the miniSim_x.x\data folder.
The ReadCell function operates on shared memory during simulation, it does not read cell data from the DAQ file.

Cells that are defined may be written to the DAQ; the collect file specifies which cells are saved into the DAQ and what frequency to use for the write operation.
The NadsMiniSimCollect.general.txt file is located in the miniSim_x.x\data folder.

Available Cells:
Any cell that has been defined in the .cec file. For example:

:'''LogStreams''': Array of 5 floats. Logstreams are a set of values the scenario author can write to through “write to logstream” actions.
:'''AccelPedalPos''': Single Value. The current position of the accelerator pedal
:'''BrakePedalForce''': Single Value. The current force on the brake pedal in pounds
:'''SteeringWheelAngle''': Single Value. The current rotation of the steering wheel
:'''CruiseControl''': Single Value. The current cruise control position. (values are cab/platform specific)
:'''TurnSignal''': Single Value. The current position of the turn signal (values are cab/platform specific)
:'''OvVel''': Single Value. The participant’s current speed in miles per hour
:'''OvLaneDev''': Single Value. The participant’s lane deviation in feet.
:'''OvHeadwayToLeadVeh''': Single Value. The distance in feet to the first vehicle in front of the participant. -1 if no vehicle can be found.
:'''OvTtcToLeadVeh''': Single Value. The time to collision to the first vehicle ahead of the participant.
:'''Horn''': Single Value. The state of the horn (values are cab/platform specific)
:'''DynObj_Vel''': Array of 20 floats. The speed of a given dynamic object. Dynamic Objects are sorted in terms of distance to driver.
:'''OvVelLocal''': Single Value. The participant’s current speed in miles per hour, using the value local to scenario control

For a complete list of cells and array elements please see the miniSim data dictionary spreadsheet.

Return Value
:Returns the value of the specified cell.

Example
ReadCell(‘LogStreams’,5) > 3

Function: '''CellEquals'''
:Cell Equals, array element, value to compare

Syntax
:CellEquals(string name, int index, float value)

Description
:The Cell Equals function is similar to the ReadCell function, except it adds an additional value to compare against the cell value.

Like ReadCell, name specifies the name of the cell, index specifies the cell array index (use 0 for single value cells).

Available Cells:
:Any cell that is defined in the .cec file.

Return Value
:Units: 1 or 0
:1 if the cell value is equal to the passed in comparison value; otherwise 0

Function: '''GetObjDistPow2'''
:Get object distance squared

Syntax
:GetObjDistPow2(string name)

Description
:GetObjDistPow2 returns the distance squared between the external driver and the dynamic object specified by ‘name’.

Distance squared is used to avoid having to perform an expensive square root calculation every frame.

If the specified object cannot be found, a value larger than 100 million is returned.

Return Value
:Feet; Distance in feet measured from the eye position of the driver to the CG (centroid) of the dynamic object specified.

A very large number is returned if the specified object cannot be found (larger than 100 million)

Example
:GetObjDistPow2(‘OncomingCar1’) < 2500

'''Note:''' To get an actual distance, multiply by the square root (sqrt())
: sqrt(GetObjDistPow2('Target_Obj'))

Function: '''GetObjTtcToOv'''
:Get Object Time To Collision to Own Vehicle

Syntax
:GetObjTtcToOv(string object name)

Description
:GetObjTtcToOv gets the time to collision from the dynamic object specified by the name parameter, to the own vehicle.

Return Value
:Unit: Seconds
:Time (seconds) to collision from the own vehicle to the dynamic object specified by the name parameter.
:0 is returned if the object specified cannot be found.

Function: '''GetObjVel'''
:Get Object Velocity

Syntax
:GetObjVel(string object name)

Description
:GetObjVel gets the velocity in meters per second of the first dynamic object with the name specified by the ‘name’ argument.

Return Value
:Unit: Meters per second
:The speed of the specified dynamic object; 0 if no object is found

'''Note:''' Multiply by 2.23694 for miles per hour.

Example
:GetObjVel(‘PullOutVeh’) > 15.4

Function: '''Rand'''
:Random

Syntax
:Rand(int value)
:Rand(string name)
:Rand(string name, string type, double parameter, double parameter)
:Rand(string name, string type, int parameter, int parameter)

Description
:Rand returns a random value specified by the name of the generator, the type of distribution and its parameters.

If the user does not specify the name of the generator and only specifies a number as the only parameter, the Rand function will use a default random number generator to produce random numbers.

If the user only enters the name of a user created random number generator, the random number generator will produce a value between 0 and 1.
If a name of generator is supplied that has not been created, the Rand function will display an error message in the ISAT debug window and return 0 (during scenario rehearsal).

The rand function supports multiple types of distributions that can be used to generate a random number.

Types of Distributions:
:normal: Normal Distribution(mean, standard deviation). The normal distribution generates random numbers near the mean with a specific standard deviation.
:gamma: Gamma Distribution(alpha, beta). The gamma distribution generates a random value that models waiting times for the Poisson process.
:uniformInt: Uniform Integer Distribution(min, max). The uniform integer distribution generates a random integer number between the lower and upper bounds.
:uniform: Uniform Real Distribution(min, max). The uniform real distribution generates a random floating point number between the lower and upper bounds.

The values stated in the parenthesis above are the parameters for each distribution in order. If the incorrect number of parameters are entered or if they are entered incorrectly, the debug window in ISAT will display an error message and the rand function will return 0 (during scenario rehearsal).

If the distribution is entered incorrectly, the debug window will also display an error message.

Return Value
:A random value from 0 to 1 if the type of distribution is not specified.

If the type of distribution is specified, returns a random value determined from the type of distribution and the given parameters.

Example
:Rand(‘myRandGenerator’,’uniformInt’,1,10)
:This example returns a random integer value from 1 to 10.

Rand(5) or Rand(‘myRandGenerator’)
:These examples return a random value between 0 and 1.

Function: '''sqrt'''
Square root

Syntax:
:sqrt(parameter)

Return Value:
: return the square root of the specified parameter.
: parameter can be another function, such as GetObjDistPow2()

Function: '''ReadVar'''
:Read a variable

Syntax:
:ReadVar(string Name)

Return Value:
:Returns the string value of variable specified in <variable_name>

===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.

=='''Audio Components'''==
The components of the Audio sub-system includes configuration and data files installed into the NadsMiniSim_x.xx\data\sound\DefaultCabSound\Instructs folder.

[[File:audio_components.png|400px]]

The audio engine contains multiple channels and has a theoretical limit of 512 simultaneous sounds.

NOTE: Not all .wav files are compatible with the Audio Engine.

=Scenario World Objects=
Scenario world objects are defined in the tile model source. They are not added by the scenario author since they are objects already present in the roadmap/BLI.

[[File:object_types_world.png|400px]]

Typically, but not always, these objects can be authored in ISAT. However, some scenario world objects have no options - these cannot be selected in ISAT; therefore such objects cannot be authored.

Removal of world objects requires editing the source tile model using a 3D application. In some cases an alternate tile model is available identical to the original but without objects.

Contact NADS if removal of a world object is needed.

Other scenario world objects, such as Traffic Signals, are specialized function objects that can be authored. Traffic signals are authored using the Traffic Light Manager: Edit >> Traffic Light Manager.

=Troubleshooting Scenario Objects That Reset=

== Scenario World Objects ==
Scenario world objects are already present when you create a new scenario - they are not added by the scenario author. These objects may be visible in miniSim but not in ISAT, or they may be visible in ISAT and seem to be controllable, but the objects 'reset' to their defaults when viewed on miniSim.

[[File:2019-10-23_16h18_47.png|700px]]

The objects which 'reset' are a symptom of settings in the TMT that are not configured to allow scenario authoring of objects.

[[File:2019-10-23_16h18_52.png|700px]]

When objects appear to 'reset' or if you can edit an object in ISAT but don't see your changes in miniSim, correct the problem by resolving controllability in the TMT settings: https://www.screencast.com/t/ZH5Dh178.

=Scenario Coordinate Types=
There are two types of coordinates used in scenarios. The first is roadway coordinates. These coordinates are contextual (tied to a specific road or intersection and position) and are used for ADO objects and roadpad paths in general.

After a roadway coordinate has been generated, it is not updated unless the scenario author makes changes to the start, end or location of the entire path or pad.

Roadway coordinate are the reason it is not possible to change a roadmap using the TMT and expect a previously authored scenario to work on the altered roadmap. If the length or location of a road changes, the path/pad will update to the extent possible.

If the road has been eliminated and no longer exists in the roadmap/BLI, ISAT will report an error and not open the scenario file.

A. Field breakdown:
RoadPos keyword <name of road:lane:position on road:path length>

Name "Ado1"
RoadPos "r1_-6600_4620:0:5737.06:0.00"
Path "R:r1_-6600_4620:0[5736.06:5873.83]"

[[File:isat_coordinate_types.png|400px]]

B.
Name "VirtObj"
Option 2
Position -6.8375599E+002 5.6331237E+003 0.0000000E+000

The second type is world coordinates, which are Cartesian coordinates with X increasing to the right, Y increasing forward, and Z increasing up.

='''Scenario Authoring'''=
Scenario authoring is the creation, editing and testing of everything that happens during a simulation drive.

==Cell Operations: Best Practice==
Reading and writing to cells is a computationally expensive process. Best practice is to centralize all the reads/write to one place so that it’s only done once per cell.

Once a cell is read, the value is copied to a variable and only the variable is used throughout all the triggers that need it.

The same process applies to writing to cells. Use of variables can reduce the Cell Operations overhead greatly.

==Before You Begin==
Before beginning a scenario, it is necessary to understand the following requirements:

=== Drive Requirements===
How long is the drive?
What type of roadway?
Are there any specialized road elements (intersections, interchanges, freeway ramps)?
Are there any environmental requirements (should the simulation replicate a real world location, or is a generic environment acceptable)?
Is there a particular roadway configuration that is needed (long straight rural road vs. typical urban environment with intersections, signals, etc)?

=== Traffic Requirements ===
What types of traffic will be needed?
Will ambient traffic interact with the external driver?
What types of interaction will be required (traffic cloud, lead vehicle, follow vehicle)?

=== Events ===
The purpose of an event is to present a situation to the external driver. In order for the simulation to produce meaningful data, it is critical that events unfold for each driver in a comparable way. Therefore, each event must be designed with this repeatability in mind.

'''NOTE:''' one of the most variable scenario elements is the driving style of each external driver: how conservative or aggressive they drive, velocities throughout the scenario, how comfortable the driver is travelling with simulated vehicles, etc.

Repeatability often includes static elements (each driver encounters scenario elements in the same location) or in cases where the driver performance is taken into account, accommodation of the driver dynamic (velocity, lane position) through the use of time to arrival triggers (TTA) or follow triggers. A TTA trigger will fire based on time to a target location - thus a driver travelling at 45mph or a driver travelling at 55mph can both experience the same action relative to that target location, irrespective of the different driver velocities.

==Beginning A Scenario==
All scenarios designed to be driven require a start location - the place where the driver will be located when the simulated drive begins.

To insert a start location into a scenario:

:Insert >> External Driver >> LMB on road, intersection or terrain object

[[File:isat_initial_position.png|400px]]

'''NOTE:''' scenarios that only contain data and are not intended to be driven - for example, signs or traffic that are used as external reference files do not require a start location, since that will be defined within the parent scenario.

==Initial Conditions==
Initial conditions define how the simulated scene is configured: will the drive occur during daylight or night time conditions? Will the ownship (external driver vehicle) have headlights enabled? What type of vehicle will it be? Will there be objects or traffic visible to the driver?
These form the initial conditions of the simulation experience. Additional initial conditions would include initialization of variables or establishing networked communication as needed by the scenario.

[[File:isat_initial_conditions_miniSim.png|400px]]

By default ISAT sets the initial condition '''Time of Day''' to 12:00 noon. The time of day is controlled from the Initial Conditions dialog:

Edit >> Initial Conditions

[[File:isat_initial_conditions_scenario.png|400px]]

==Scenario Authoring: Actions==
Actions are the scenario elements that make things happen during simulation. Actions do specific things, like display a text message on screen for the driver, create a scenario element, change the velocity of simulated traffic, change a traffic signal, etc.

[[File:trigger_action_panels.png|400px]]

The diagram above shows the action panel for left to right: an expression trigger, a roadpad trigger and a global time trigger showing different panels based on the actions present in each trigger.

'''NOTE:'''Actions can be created, edited or removed from the '''Actions panel''' of '''any trigger'''.

'''NOTE:''' The Actions panel changes based on the action type created.
When multiple actions have been defined, control the sequence of actions by changing the action order in the list using the up or down arrows next to the list.

[[File:action_panel_overview.png|400px]]

If multiple actions need to happen in a specific order, set the order using the arrows and then flag the action list as '''sequential'''. This instructs behaviors to process the actions in the list order.

Using a delay for any action will pause processing of the '''following actions'''; the action happens first, then the delay is applied.

===Scenario Authoring: Action Types===
There are two types of actions:
# Instantaneous - the action takes up to one frame to complete, i.e.:
:set target velocity
:write to cell
# Persistent
<span style="color:red">'''*Persistent actions do not end'''</span>, or take multiple frames to complete:
:Forced lane offset
:Forced velocity
:Maintain Gap

==='''Actions'''===
*The "Who to Affect" field defines what is affected by the action
:Instigator set: who activated the trigger
:Name: one or more named elements
:Type: Apply changes to all objects matching the specified type
:Relative: Position relative to the trigger location

*Sequential
:Actions to execute sequentially, one after the other
:Specify delay between actions
:: Action executes, then delay

:Some actions are persistent and never "finish"

===Scenario example: display text & roadpad trigger to stop the drive===
This scenario is very simple and contains a global time trigger (GTT) that tells the driver what to do. After the driver travels along the roadway, a roadpad trigger (RPT) is used to tell the driver to stop driving. The same RPT also creates an expression trigger to terminate the drive.

TBC example scenario file

Because the external driver is not under control except by instructions, it's possible they might ignore the halt message and continue driving. A second failsafe RPT then terminates the drive.

==='''Actions: Button vs. Dial'''===
*Dial changes a setting
*Button: always runs in a single frame
:-"immediate" change. Typically buttons have less control than a '''Set Dial''' action

==='''ADO Actions'''===
[[File:ado_action_types_button_vs_dial.png|400px]]

==='''DDO Actions'''===
[[File:ddo_set_dial.png|400px]]

==='''External Driver Actions'''===
External driver behavior can be influenced by reinforcing scenario actions through audible speeding alerts, on-screen text instructions and messages or audio instructions.

Driving behavior can be influenced with situational elements
:Car in the drivers blind spot
:Lead vehicle
:Aggressive following vehicle
:Temporary lane closure
:lane specific instructions

Scenarios should '''not rely on specific driver actions to be successful'''
:to the extent possible; sometimes you do need the driver to respond/behave in a controlled manner.
:A work zone blocking one lane typically will require a roadpad placed upstream from the work zone to shift traffic into the correct lane

'''NOTE:''' Controlling driver actions should be an experimental design consideration.

==='''Special Actions'''===
These actions need special handling:
*Reset or "toggle":
:Audio
:Display Text

:'''Ado'''
::Audio State
::Forced Velocity
::Maintain Gap
::Visual State

*If using these persistent actions, place them at the '''end''' of an action sequence (because no action following these will execute):
:Forced Lane Offset
:Forced Velocity
:Maintain Gap
:Visual State

*Note: If the Visual State action contains a duration then it will be handled as a normal action, with subsequent actions firing after it. However, if there is no duration supplied with the Visual State action it behaves like a persistent action, and nothing following it in the Action stack will ever fire.

[[File:multiple_simultaneous_actions.png|400px]]

The diagram above shows how one parent trigger can be used to create multiple simultaneous triggers

*How to activate multiple unique force velocity (FV) or maintain gap (MG) actions:
#create the needed triggers from a general parent trigger, 1 per action
#put common actions into the parent trigger
::reset FV
::reset MG

==Scenario Authoring How To==
This section contains simple examples for various typical scenario situations.

===How do I specify an event?===
First, determine which method is best for you - the default measures (limited measures, 20 events max) or logstreams (all simulation data, no event maximum).

Regardless of method, you specify an event by identifying areas of significance in the drive and marking them so the data within the event region can be processed. Any trigger combination that can specify event start and event end may be used.

[[File:2022-07-01_11h21_52.png|400px]]

===How to know Which Coordinator or Trigger I need?===
The answer to this question lies in the type of information needed for an event:

*Time
:global time trigger
:or an expression trigger that calculates time
*Position or Location
:roadpad trigger
::or a time to arrival (TTA) trigger
::or an expression trigger that calculates distance
*Calculation
:Expression trigger

===How to Instruct the External Driver===

Instructions to the external driver can be accomplished by three main methods:
# Instruct the driver using experimental protocol (instructional or briefing presentation)
# Information messages displayed on screen: '''Action: ''set visual display text'' '''
# Information messages delivered as audio messages: '''Action: ''write to cell > SCC_Audio_Trigger ><audio ID>'' '''

===How to Add Traffic in the Scene ===

Generating traffic will happen in one of 5 ways:
# Created explicitly by inserting ADO, or copy/paste existing ADOs
# Created with a script
# Via a Create action inside a trigger, or placing scripted traffic inside a create action within a trigger
# From a '''Traffic Source'''*
# From the '''Traffic Manager'''**

Each of these methods has advantages and disadvantages.

==== Create Explicitly ====

The biggest advantage with this method of traffic creation is the high degree of control the scenario author has over:
# location of the created ADO
# Name of the created ADO
# Travel path of the created ADO
# Control when each ADO is created within the scene via Settings >> Creation Radius

The disadvantage is that creating a high volume of traffic will take some work with this method.

==== Created with a Script ====

This method combines the advantages of Creating Explicitly with volume. It is possible to create a large volume of traffic very easily with a script.

Disadvantages of using high volumes of traffic with a script: in the event it becomes necessary for a high degree of control over these ADOs, more is not better because ADOs will adapt to road conditions under their own power, unless the default ADO settings have been modified:
'''lane changes, including lane changes to accommodate freeway ramps'''
'''velocity adjustments'''

==== Via a Create action inside a trigger ====
Combines the advantages of the previous 2 methods with control over when to activate that traffic using a trigger action.

Disadvantages: Creating too many ADOs at one point in the drive can cause the miniSim to bog down for a few frames. If too many ADOs are present and active in the simulation at one time, this can cause the miniSim to drop frames and run sluggishly. This is highly noticeable and may increase the potential for the External Driver to experience '''simulator sickness.'''

==== From a '''Traffic Source''' ====

Traffic Sources rely on two methods to populate a scene with traffic:
# location specific, with each ADO created for a traffic source being a 'spawn location' for ADOs, or
# location agnostic if the ADO has '''relative creation''' enabled, thus being created relative to the object identified.

In addition to being created relative to a scenario element, ADOs are created relative to the specified scenario element:
# In front of (Longitudinal Distance > 0, where the number is feet offset from the object) , or
# Behind (Longitudinal Distance < 0, where the number is feet offset from the object).

Advantages: Can easily populate traffic into the simulation.

Disadvantages: It is easy to generate more traffic than the simulation can maintain at 60Hz frame rate, thus introducing frame lag with the resulting scene 'stutter' and the increased risk of simulator sickness.

Also, traffic created from a Traffic Source is generic traffic. It is not possible to reliably refer to specific ADOs generated from a traffic source except by using Who To Affect >> Relative (versus referring to a named ADO, i.e. Slow_Moving_Lead_Vehicle). Referring by name to Traffic Source generated ADOs will affect all similarly named ADOs at the same time.

==== From a '''Traffic Manager''' ====

The traffic manager interface is problematic in ISAT versions up to 1.8.5, especially when specifying the set of vehicles to be used for generating traffic.

Advantages: Create generic ambient traffic easily.

Disadvantages: Has the same disadvantages as traffic created via a Traffic Source. Also getting a traffic set working by specifying the vehicles to be used within the set. ISAT versions up to 1.8.5 exhibit instability when setting vehicles in ISAT.

Traffic Manager Set workaround: Borrow a working set from an existing scenario or group. Alternatively use a version of ISAT (1.8.6 +) to create the traffic set. This can be saved as a scenario or group file, which can then be used with ISAT 1.8.x as long as there is no attempt to adjust the vehicle weights within ISAT. The scenario or group file can be edited as text in a text editor, but care must be exercised to avoid introducing errors into the file. ISAT will not read invalid scenario or group files.

Traffic generated by the Traffic Manager is controlled through the use of Input Sets. An input set is a collection of vehicles and weights used to populate the scene during simulation. This is how the scenario author can control the vehicle population (type and number), density and creation/deletion distances - these attributes are unique to each set.

Since there is no 'discontinue traffic manager' function, one can be implemented by defining an input set with no traffic (an empty input set). An appropriate name can make the purpose of the set clear: PauseTraffic, Stop_TM, etc.

==== Sample Traffic Manager Set ====
This is a sample traffic manager set that can be pasted into a scenario file after the HCSM VehFail section. Be sure to paste '''after''' the HCSM VehFail end tag ('''&&&End&&&''') in your scenario file.

'''Note:''' A scenario file may contain only '''one''' Traffic Manager section.

There are two input sets in this example; note how they contain different vehicles and different settings from each other.

<span style="color:#2a4b8d">HCSM TrafficManager
GroupName "Traffic Manager"
HCSM InputSet
Name "ONE"
MinDensity 3.0000000E-002
MaxDensity 7.0000000E-002
MaxObjects 9
CreateDist 2.0000000E+003
DeleteDist 3.0000000E+003
AbsDeleteDist 3.4000000E+003
RunFreq 1.0000000E+000
SolWeights "cargill_semi_peterbilt_blu:2" "cargill_semi_freightliner_red:1" "cargill_semi_peterbilt_yel:3" "DumpTruck_org:3" "semi_peterbilt_yel_Walmart:2" "Cadillac_Escalade:10" "Ford_F150Xcab:15" "Saturn_Vue:10" "FordTaurus:15" "Escape:15" "DumpTruck:2"
&&&&End&&&&
HCSM InputSet
Name "TWO"
MinDensity 1.0000000E-002
MaxDensity 3.0000000E-002
MaxObjects 4
CreateDist 2.5000000E+003
DeleteDist 3.3000000E+003
AbsDeleteDist 3.5000000E+003
RunFreq 1.8000000E+000
SolWeights "Taurus2011:12" "Cadillac_Escalade:16" "Ford_F150Xcab:24" "Saturn_Vue:14" "Escape:6" "Deville:24" "Audi:4"
&&&&End&&&&
&&&&End&&&&
</span>

====='''Managing Traffic Manager Input Sets'''=====
During simulation, Input sets are controlled by the action '''Use Traffic Manager Set'''. A set name must be provided for this action to work.

===== Traffic Manager generated Traffic=====
ADOs will populate the road network around the XD based on the parameters of the Input Set. Typically traffic is removed from the scene shortly after passing the XD. This is visible in the rear view mirror. There is currently no way to adjust this delete distance.

====== Traffic Manager Traffic on 2 lane freeway======
Traffic will prefer to be in the XD lane, so ADOs created in any other lane will tend to veer into the XD lane. On a divided highway, traffic is generated moving with the XD.

====== Traffic Manager Traffic on 2 lane road======
Traffic is generated in the oncoming lane. In some cases traffic may be generated then immediately removed in front of the XD.

===How to Control Objects in the Scene during Simulation ===
"Set and forget" options on simulation entities only require the scenario author to "initialize" the element to a desired setting and then it is left alone during simulation.

Controlling objects dynamically during simulation requires the scenario "talk to" each object with a scenario action. This section describes how each scenario object type can be controlled during simulation within a scenario.

All models used in ISAT are listed within the Scenario Object Library (sol2).txt files. Terrain switch names are displayed in the ISAT workspace.

All model switches are listed within the NadsMiniSim_x.x\bin.x64\ModelList.txt file.

'''Note:''' The diligent reader will note discrepancies in model names between the sol2 and ModelList files. This is because the ModelList file contains actual file names, and the sol2 files define a "name label" for models that may, or may not, be the actual model name. Objects are linked between the sol2 and ModelList files through the ModelID/CigiID records. These values will match between sol2 and ModelList files, but IDs are not necessary at this time for scenario authoring purposes.

Complicated object names can be retrieved from the LRI file that was used to build any scenario file; each BLI is preceded by an LRI. The LRI contains all of the terrain models that will be present in ISAT. These are typically speed limit signs, traffic signals or other features that may be controllable.

'''Note:''' this file may not be present for the Springfield.bli file.

An alternative is to capture a screenshot of the ISAT workspace with the element name string showing. By default ISAT reports the name of any objects when the cursor passes over the object, as shown in this example:

[[File:2021-10-27_08h50_14.png|caption =Object Name Screenshot | 400px]]

{|class="wikitable"
|+ Controlling Scenario Elements During Simulation in Scenario
!Date
!Nads miniSim version
!Object Type
!Scenario Action
!Who To Affect
!Value
!Notes
|-
| Oct. 28, 2021
|2.3
|-
|
|
|Static Object (terrain)
| SetDial > StaticObjManager > Set Option1
| StaticObjManager
| switch name : switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
|Static Object, multiple options
| Set Switch
| Name of element
| switch option
|-
|
|
|Obstacle, multiple options
| Set Switch
| Name of element
| switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
| DDO, multiple options
| Set Switch
| Name of element
| switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
| ADO
| Set Dial > ADO > VisualState
| Name of element
| Limited to options present in ISAT
|-
|
|
| Traffic Signal
| Traffic Light
| Assign action to element
| Target state
| Target state must exist within the Traffic Light Manager intersection timing table for the specified signal

|}

===How to Control Simulated Vehicles===
The scenario author can control simulated vehicles by controlling the environment:
#change a traffic signal to cause an ADO to stop or start at intersections
#affect other ADOs to cause a target ADO to respond
# assign a path for the ADO to travel

Direct control:
*Lane related:
:Set button > ADO > ChangeLane, Turn, ProjectAndResetLane

*All other controls:
:Set Dial > ADO > AudioState, ForcedLaneOffset, ForcedVelocity, InhibitLaneChange, LaneChange, MaintainGap, TargetVelocity, VisualState, AudioState

====How to Change ADO Velocity====
ADO velocity can be changed using the SetDial action:
:SetDial > ADO >

:ForcedVelocity
:ForcedVelocity using an expression:
# match external driver speed
expr % OvVel(0) %
# multiply external driver speed
expr -1 9 %ReadCell('OvVelLocal',1)*1.75 %
:TargetVelocity

Indirect Control (dependent on other scenario element):
:MaintainGap

====How to Link ADO Velocity to Something Else====
ADOs velocity can be linked to other ADOs or the external driver using the MaintainGap (MG) action.

SetDial > ADO > MaintainGap

When using a traffic cloud containing multiple ADOs, each ADO in the cloud needs a unique MG. IF multiple ADOs have the same MG settings they will attempt to satisfy their parameters and likely oscillate position in a visually obnoxious way.

===How to Author Loop Scenarios===
A scenario created on a loop road network operates very much like any other scenario, with the exception that it is likely to require tracking the number of times through the loop, or to present scenario events to the external driver depending on each loop context.

[[File:loop_traffic_creation_01.png|400px]]

The simplest method of tracking loops is the use of a loop counter variable. This variable can be set by the driver "stepping onto" a roadpad trigger or it can be initialized through the use of a timer or expression, with increments managed by a roadpad trigger. Each time through the loop increases the loop count variable.

Thus it becomes possible to create events for each loop based on the loop counter variable, typically through an expression trigger.

Loop management triggers

[[File:loop_management_02.png|400px]]

Loop management trigger detail one

[[File:loop_management_vars_02b.png|400px]]

Loop management trigger detail two

[[File:loop_management_3.png|400px]]

====Creating Loop Specific Traffic====
Creating loop traffic is slightly more complicated due to the number of objects to be created and potentially the size of the actual loop. A small loop is installed with the Nads miniSim as simple_rural1 or simple_rural2. Each is a loop road network with two signed 3-way intersections.

Loop specific traffic can be created through the use of a variable (i.e., LoopCount) or within the roadpad trigger that is incrementing the loop count variable. Both methods will incorporate a '''Create Action''' that creates the required elements.

===How to Change Environment Settings===
The scenario author can define global or localized environment conditions.

1. Insert >> Environment Conditions >> <chosen condition>

2. Define a region where the environment condition is active:
:LMB to define polygon points
:RMB to exit point entry mode

[[File:env_condition1.png|400px]]

Choosing an environment condition

[[File:env_condition2.png|400px]]

Environment region defined and parameters panel shows available options

NOTE: The environment condition boundary is a discrete threshold. Condition A will be on one side of the threshold. Immediately after crossing the boundary, condition B will be displayed.

===How to Fade an Environment Condition===
To fade gradually between two conditions requires the use of an expression that continually monitors the desired condition and sets a few variables based on the results.

Examining the demo scenario is the best way to look 'under the hood' to see exact command syntax and values to be used.

[[File:env_fade.png|400px]]

Note: this approach has been used for fog and visibility. It is unknown how it might work with non-visibility conditions such as precipitation and wind.

*From the scenario demo_visibility_transition.scn

[[File:env_fade_schematic.png|400px]]

'''Note:''' although the example above uses an environment condition boundary, '''it is possible''' to omit the defined region, retaining all commands and the scenario will still function. However, without the environment region, it becomes more difficult to determine where conditions are different from the standard settings.

===How to Control a Cab Instrument Panel icon===
In order to control the instrument panel, there are 2 requirements:
The specific cab used for the scenario
The specific control (switch) to be manipulated
The action for addressing the instrument panel is '''ChangeCabSetting'''

Instrument panel models are located in NadsMiniSim_x.x\data\Visuals\Instruments
These files are in OpenFlight format. Any 3D editor capable of reading or importing OpenFlight can be used to review these files. NADS uses the Presagis product Creator[tm].

An alternative method to inventory switches is to use the the '''buildscl.exe''' tool. To run the tool, open a CMD window to the IP folder location above, then run the command:
buildscl <input_file.flt><Enter>.
<input_file.flt> is the name of the file to process, without the '<>' characters.
<Enter> means to press the Enter key,

The result will be in a new file ending with .scl. This is a text file, and can be opened in a text editor or you can use the shell utility '''more''' to view the file contents:

more <input_file.scl> | grep switch<Enter>

An example for the malibu cab is shown below. .

switch s_LowWasher 0
switch s_Cruise 1
switch s_LeftTurn 2
switch s_RightTurn 3
switch s_FwdCollisionWarn 4
switch s_BlindSpotWarn 5
switch s_LaneDeviationWarn 6
switch s_RearCollisionWarn 7
switch s_HighBeamHeadlights 8
switch s_SeatBelt 9
switch s_UpArrow 10
switch s_Airbag 11
switch s_CheckEngine 12
switch s_CheckGuages 13
switch s_ABS 14
switch s_Brake 15
switch s_LowFuel 16
switch s_Gear 17

These controls may be accessed directly in scenario using the ChangeCabSetting action.

'''NOTE:''' Some functions such as Cruise, Gear, High beam headlights, Blind spot, collision, lane deviation warnings are '''normally''' controlled not by direct access as described here but by hardware mechanisms/buttons.

'''NOTE:''' For altering cab instrument panel operation it will be necessary to modify the OpenFlight model to include the desired funationality; for example, instrument panel blanking is not build into the model but can be added by editing the cab instrument panel model file then installing the modified file into miniSim.

===Scenario Hints===
The total number of scenario elements active at any given time can affect simulator performance:

Total number of active elements
*vehicles (ADOs), triggers, animations, etc.

Object management
*Use paths to shift ADOs away from the driver route of travel as they turn off the route
*reduce the number of vehicles in traffic cloud surrounding external driver
*use creation radius to limit the number of active elements, and to remove elements after the driver has traveled beyond the creation radius

[[File:creation_radius_1.png|400px]]

Creation radius works by activating the scenario element only when the driver is within the radius. The scenario element is created when the driver enters the creation radius, and is deleted after the driver leaves the creation radius.

Exploit environment to reduce object load

*Use curves, hills, intersection corners to mask objects

Object deletion
*Remove objects when no longer needed

When creating dynamic elements, create them as close to where they are needed as possible.

====How to Determine When ADOs are Visible to the External Driver====

Some development/setup testing may be needed to determine precise location/distance/speed; i.e., locating ADOs for a freeway ramp merge event where the external driver is merging onto the freeway with other ambient traffic present.

Unless the purpose of the event is to study driver behavior at the merge, ideally the scenario will be authored to have ambient traffic on the freeway but not to present a conflict at the merge for the external driver.

A straightforward way to determine where the ADOs are first visible to the driver is to mock up a scenario placing colored ADOs along the freeway with a velocity of 0. This will ensure the ADOs remain stationary while the scenario author determines where they are first visible to the external driver.

Place the start position/external driver far enough up the ramp to be a reasonable test for the actual scenario.

As you drive the ramp, see which ADO is first visible to the driver. Place ADOs just out of view (upstream) of that location.

[[File:merge_hint.png|400px]]

'''NOTE:''' use test vehicles of the same type and character as the intended scenario vehicles. For example, do not use a sedan test ADO for a larger vehicle (SUV, bus, dump truck). Doing so will invalidate the visibility test, because a larger ADO will be visible over a longer distance than a small ADO.

[[File:ramp_vis_1.png|400px]]

At the scenario start location, ADOs in front of the Coke truck are visible. Note how the larger vehicles are more obvious at this distance.

[[File:ramp_vis_2.png|400px]]

The driver has traveled onto the ramp. At this point, the last ADO visible to the driver is still the Coke truck.

[[File:ramp_vis_3.png|400px]]

As the driver travels farther down the ramp a small ADO is visible behind the Coke truck.

The answer to the question '''When is an ADO visible?''' is thus:
#It depends on how large the ADO is
#Small ADOs can be placed at the location of the red ADO behind the Coke truck.
#Large ADOs may need to be placed farther back (behind the red ADO). This test is inconclusive, but based on the terrain it seems likely that large ADOs would need to be placed at least at the green ADO location (behind the Coke truck).

Creating small ADOs at the green ADO location when the external driver is located at the ramp position in 3 travelling at the same speed as the external driver should arrive at the merge slightly ahead of the driver (because the curved ramp is longer than the straight freeway).

'''NOTE:''' ADO size, ADO color, time of day and visibility settings affect ADO visibility.

====How to Position Objects Precisely using '''Place Object At..'''====

ISAT does not support true precision because it is not currently possible to 'dial in' a position as is typical in 3D modelling tools, but there is a way to approximate precision in cases where a consistent measurement is desired.

In the following example a number of roadpad triggers are placed relative to the location where a roadway enters an intersection. This is a discrete boundary within the simulation world as shown in ISAT.

There are two methods of placement possible:
# Measure the desired distance (CTRL+Shift+RMB, drag); take note of the coordinates updating in realtime and make a mental note of the desired location.
#Place an object (ADO or static object); use the Place Object At.. feature from the context menu when you RMB on a scenario object.
Using this method you can specify a distance - positive numbers move the object downstream/forward, negative numbers move the object upstream/backward.

'''Note:'''If the distance is significant and extends over an intersection, ISAT may produce unexpected and undesired results such as re-starting the measurement from the closest upstream intersection, thus placing the object where it was not intended.

In the following example, Place Object At.. is used to specify a point 50 feet upstream from the road/intersection border.

[[File:precision_placement_1.png|400px]]

A roadpad trigger has been positioned near the area of interest. Any existing roadpad is deleted from the trigger.

[[File:precision_placement_2.png|400px]]

An ADO is used as a marker object inserted temporarily into the scenario. Any convenient object may be used.

'''Note:''' large objects such as ADOs may be less precise than small objects such as the Traffic cone, but is generally easier to access in the ISAT interface unless you have created a script for cone objects.

[[File:precision_placement_3.png|400px]]

RMB on the ADO to access the Place Object At.. request dialog. Only numbers are valid entries.

[[File:precision_placement_4.png|400px]]

The desired distance is entered into the Place Object At.. request dialog. ISAT will then require you to select the object you wish to move using LMB.

[[File:precision_placement_5.png|400px]]

ISAT moves the selected object by the distance you specified.

[[File:precision_placement_6.png|400px]]

Use the ADO CG (model center) to place the start of the road pad.

[[File:precise_placement_7.png|400px]]

Remove the ADO marker and save your scenario.

==Scenario Testing and Debugging==
The primary way to test and debug scenarios is using ISAT rehearsal mode.

'''NOTE:''' the external driver during rehearsal is a simulation. You have limited control over the simulated ownship:
#change speed
#change lane

ISAT has two rehearsal dialogs:
#abbreviated (standard) dialog
#advanced (extended dialog)

===How to change to the advanced rehearsal dialog===
Often it is necessary to control the ownship during rehearsal. The ownship controls are located in the advanced (extended) rehearsal dialog.

ISAT will show the Advanced dialog the first time rehearsal mode is activated. All additional activations show the abbreviated dialog.

TBC abbreviated dialog

To use the Advanced dialog, LMB the Advanced button.

TBC Advanced dialog

===How to change ownship speed during rehearsal mode===
After entering rehearsal mode:
#click the Play icon (start the rehearsal)
#pause.
#adjust ownship speed
#toggle pause off (resume rehearsal)

===How to make ownship lane change during rehearsal mode===
After entering rehearsal mode:
#click the Play icon (start the rehearsal)
#click the desired Lane Change (left or right)

===How to Use Audio in your Scenario===
Scenarios play audio sounds and messages through a write to cell action: '''SCC_Audio_Trigger'''

Use of audio in a scenario typically requires both a write to cell and a 'clear action' that writes a zero (0) to SCC_Audio_Trigger in order to 'clear the channel'. The 'clear' action can happen before or after playing a sound; choose one method and be consistent in your scenario authoring.

Failure to 'clear the channel' or '''not''' writing a value of zero can result in no audio being played for subsequent write to cell SCC_Audio_Trigger actions.

The following shows how this looks in scenario when executed from a roadpad trigger (RPT):

[[File:audio_scn_A.png|400px]]

The above diagram is shown below in text format:

HCSM RoadPadTrigger
GroupName "WindGust_Audio"
ByTypeSet "ExternalDriver"
NthFromStart 0
NthFromEnd 0
VehicleAhead 0
VehicleBehind 0
LongComment "This is a wind gust event"
ShortComment " "
ActvDel 0.0000000E+00
CrRad 0.0000000E+00
Debounce 0.0000000E+00
FireDelFrames 0
Lifetime 0.0000000E+00
Name "RPT_WG_6"
OneShot 1
Priority 0
SeqAct 1
Position 6.7165800E+04 6.0419215E+03 0.0000000E+00
DrawPosition 6.7165800E+04 6.0419215E+03 1.1308095E-317
Path "R:r3_62700_7920:0[3033.04:3245.46]"
HCSM LogData
Comment "LS1=8"
Delay 0.0000000E+00
InstigatorSet 0
Stream 1
StreamVal 8.0000000E+00
&&&&End&&&&
HCSM WriteCell
Comment "Play_Audio"
Delay 2.0000000E+00
InstigatorSet 0
CellName "SCC_Audio_Trigger"
CellData "63000"
CellType 2
CellVar 0
&&&&End&&&&
HCSM WriteCell
Comment "clear_audio"
Delay 0.0000000E+00
InstigatorSet 0
CellName "SCC_Audio_Trigger"
CellData "0"
CellType 2
CellVar 0
&&&&End&&&&
&&&&End&&&&

===How to Add Custom Audio Instructions to miniSim===

''' Please note: Custom audio 'instructions' for a scenario should be added to the instructions.txt file.'''

These are sounds that are played in scenario, typically as directions for the minSim driver.

Adding custom audio files requires the following procedure:

1 Exit miniSim - changes to the miniSim configuration should happen only when miniSim is not running.

2 Copy the audio .wav file to:
:C:\NadsMiniSim_x.x\data\sound\DefaultCabSound\Instructs

:Edit the file instructions.txt in that same folder.

3 Add an entry to instructions.txt to register your audio file in accordance with the following layout using the existing entries as a template:

:Unique_ID Filename Normalized_Volume

:Unique_ID is whatever unique number you assign to your file.

:Filename is the name of your .WAV file.

:Normalized_Volume is the volume your audio file should play, where 0.00 is silence and 1.00 is maximum volume.

'''NOTE: Remove all spaces in your audio filename.''' If needed, use the underscore character instead of spaces.

===Troubleshooting Custom Audio Additions===
After installing new .wav files and adding them into the audio configuration file '''instructions.txt''', if the audio file does not play:
*Check the Audio Engine window while miniSim is still running. The Audio Engine will display file errors,.
*If Audio Engine does not display a message similar to: Audio Engine loaded normally, scroll through the window messages and look for any .wav or load error messages.

==Re-use of Scenario Elements==
Scenario authoring can be an intensive undertaking. It makes sense therefore to leverage your development efforts by re-using scenario elements where possible.

ISAT provides a number of ways to re-use scenario elements:
# copy/paste
# external references
<span style="color:#ac6600"># exporting elements as '''groups'''</span>
# isc scripts

Each of these methods have their strengths and weaknesses.

===copy/paste===
The simplest method to re-use scenario elements among different scenario files is copy/paste. This is possible for most scenario elements* even if the source and destination roadmap/BLIs are radically different.

[[File:copy_paste.png|400px]]

It is also possible to copy an ISAT element from one scenario to another as '''TEXT''' by selecting the element and using the windows copy shortcut CTRL-C, then open a text file and paste it using the windows paste shortcut CTRL-V.

'''NOTE:''' Traffic sources are '''not''' portable using copy/paste.

'''NOTE:''' Not all elements can be copy/pasted. Elements created from a Create Element action cannot be copied - it is necessary to select the parent element and copy that instead.

[[File:copy_paste2.png|400px]]

In the above diagram, elements at '''B''' and '''C''' cannot be copied/pasted because they have been created by element '''A'''. It is necessary to copy the element at '''A''' instead. If only the elements at B are needed, the best method will be to copy/paste as Text.

'''NOTE: ISAT will not copy elements containing road coordinates (elements with a path) to a scenario that does not share the same BLI as the source (copy from) scenario.'''

A partial solution to such cases is to remove the path first, copy the element, paste into the destination scenario, then re-create the path manually.

===External Reference===
An external reference scenario is intended to be re-used by multiple 'parent' scenarios. The effort of authoring objects is thus leverages across multiple files, without needing to re-create the same elements more than once.

[[File:re_use_xref_1.png|400px]]

Common uses of external references include traffic, traffic signal operation, traffic sign appearance or other environment features which have multiple appearances (billboards, some tile related scenery, etc).

NOTE: Multiple external references are possible; but because objects are categorized by group, it is not entirely necessary.

For example, one external reference file contains traffic, another contains signs. These two external reference scenarios could be combined into one file.

[[File:xref_overview2.png|400px]]

NOTE: Each group defined must be unique across all files: parent and external reference files.

In order to use an element in an external reference scenario, it is necessary to define and assign a group to all elements that you wish to control from the parent scenario.
At this time there is no visual hint in ISAT to indicate if a group has been assigned to an element or not - each element has to be confirmed independently.

However, a properly authored external reference element cannot be edited within the parent scenario (after you have done Add Ref. to use the external reference file).

An alternative is to insert groups using a text editor with macro capability, or to use a program or external script to make the necessary changes.

'''NOTE:''' If the external reference file is for object contained in the parent scenario (for example, an external reference file containing traffic signals with a group defined) it is still necessary for that group to be defined in the parent file.

With traffic signals, ISAT requires ONE explicit group reference, which will be contained in the HCSM TrafficLightManager block as shown below. If you require the use of traffic signals in an external reference, the recommended way to do this is through ISAT because then it manages the group assignment for you.

==== HCSM TrafficLightManager scenario block ====

HCSM TrafficLightManager
HCSM CLG
IntrsctnName "I1_40260_4620"
Duration 2.0000000E+01 3.0000000E+00 1.0000000E+00 2.0000000E+01 3.0000000E+00 1.0000000E+00
GroupName "TrafficSignals"
LightName "s_signal_r1_LTRN_40260_4620_270"
LightName "s_signal_r1_RTRN_40260_4620_270"
LightName "s_signal_r2_LTRN_40260_4620_270"
LightName "s_signal_r2_STRT_40260_4620_270"
LightName "s_signal_r3_STRT_40260_4620_270"
LightName "s_signal_r3_NORM_40260_4620_270"
Pattern "FLTY" "R" "R" "R" "R" "R" ""
Pattern "RTG" "R" "R" "R" "R" "R" ""
Pattern "LTR" "LTR" "LTR" "FLTY" "FLTY" "LTR" ""
Pattern "SR" "SR" "SR" "SG" "SY" "SR" ""
Pattern "SR" "SR" "SR" "SG" "SY" "SR" ""
Pattern "R" "R" "R" "G" "Y" "R" ""
&&&&End&&&&
&&&&End&&&&

'''NOTE:''' At this time there is a known issue using the write cell '''SCC_Audio_Trigger''' action in external references. Although the trigger containing this action can be assigned a group and used as an external reference, audio does not play.

<span style="color:#ac6600">'''Because ISAT updates static object positions (elevation) to the terrain (roadway) when the scenario file is saved, the best way to use a custom elevation is to put such objects into an external reference file in order to isolate those objects from normal scenario editing.''' </span>

====Define a Group====
<span style="color:#ac6600">'''NOTE:''' ISAT 1.8.5 and 1.8.6 currently do not work properly with group files. These versions will not import objects within a group file. There is a workaround which involves the following process, but instead of reading the saved group file into a scenario the workaround requires editing the scenario as text and inserting the objects within the group file into the scenario.</span>

RMB on the element and choose from the context menu: Group >> New Group (if this is a new group) or Group >> (choose an already defined group).

'''NOTE:''' The first time you create a group for an object, ISAT will automatically assign the group to that object.

After defining and assigning groups to the scenario elements needed, save the scenario file then close it.

Open or create the parent scenario file and use the Add Ref. button at the bottom of the ISAT window to select your external reference scenario. After you choose a file ISAT will present you with the groups found in that scenario. Choose the groups you with to include and click the 'Okay' button. Click the Add Ref. OK button to complete the process.

Currently import group file operations are not working, but it is possible to insert the group file content (all HCSM StaticObjects) into a scenario manually by using a text editor to copy text from the group file and paste that into a scenario file into the HCSM Static Object section of the scenario file.

[[File:group_text.jpg|400px]]

'''NOTE:''' ISAT does not enforce logic on your external reference authoring. If you add references to scenarios that do not share the same roadmap/BLI as the parent scenario, it is likely that elements will be placed at the origin (in cases where the external reference roadmap contains roadways not found in the parent) if it even loads.

===Exporting ISAT Elements as Groups===
Transferring ISAT elements among scenarios can be accomplished using groups. As with external reference scenarios, one or more groups must be defined and then assigned to one or more elements.

After defining and assigning groups select the group for export using the Group select drop-down located at the lower left corner of ISAT. Choose a group to export and then click the 'Save Group' button. Save the file.

TBC insert graphic sequence diagram here

'''NOTE:''' If you cannot locate the group file in the folder specified, check the ISAT install\data folder. This is typically:

C:\NADS\ISAT\data

===Group File Contents===
The group file is a text file and can be opened or edited in a text editor.

The following is a group file containing one ADO. Note the GroupName line near the bottom:

Header
LriFile "_dev.bli"
LongComment "this is a test group export"
ShortComment "this comment was left empty"
&&&&End&&&&
HCSM Ado
RunMode "eREMOTE_CONTROL"
RandomSol 0
Name "Ado1"
DynModel "Non Linear"
LogFile ""
LatOffsType 0
CreateRelLatInFeet 0
CreateRelOffsLonUsingExpr 0
CreateRelOffsLonExprStr ""
AutoControlBreakLights 0
AutoControlHeadLights 0
UseReaDel 1
StdToAccType 0
StdToDecType 0
StdToDecVal1 9.0000000E-001
StpToAccType 0
DecToAccType 0
FollowTimeMin 1.0000000E+000
FollowTimeMax 2.0000000E+000
EmergDecClip -1.1000000E+001
Accel2Catch 0
NormVel2Kp 7.0000000E-001
PathSearchDepth 2
LcvFall 1.5000000E+000 2.0000000E+000
LcvFreq 3.0000000E-002 5.0000000E-002
LcvRAmpl 1.0000000E-001 5.0000000E-001
VelCtrlInitMatchOvVel 0
VelCtrlFollowSpeedLimit 0
VelCtrlDistType 0
MaxLatOffset 9.0000000E+000
LongComment " "
ShortComment " "
SolName "Audi"
RoadPos "r1_1320_44220:2:32414.44:0.00"
GroupName "TEST_Group"
&&&&End&&&&
HCSM StaticObjManager
&&&&End&&&&
HCSM DriverMirror
&&&&End&&&&
HCSM IntersectionManager
&&&&End&&&&

===ISC Scripts===
Scripts are an efficient way to automate repetitive and/or complex tasks.

ISAT uses a custom language (ISC) to automate placement and manipulation of scenario objects. Combined with simple direction commands and the capability to navigate a road network, ISC scripts can ask the scenario author for input and prompt for selecting objects.

ISAT installs with some ISC script files. If your version of ISAT contains a data\isc
folder, then your version of ISAT is capable of running scripts. You can create
additional scripts as needed. All scripts located in the data\isc folder will load in ISAT
when ISAT is launched.

You can use these scripts for reference in creating your own custom scripts.

New scripts created during an existing ISAT session will not appear until ISAT is re-
launched.
Scripts that have been edited will not update until ISAT is re-launched.

Unless otherwise indicated, scripts are case-sensitive.

'''NOTE:''' Please do not edit the existing scripts!

Make a copy of any existing script before you make changes. In the event your modified script does not work, you can look at the original file for reference.

ISC scripts are located on the ISAT Elements widget. Custom isc scripts are located after the 'Events' separator.

Using an ISC script involves LMB + dragging the desired script onto the workspace. In some cases the script will ask for inputs.

ISC can be also used to create an entire event, thus ensuring that all events created will be entirely identical in terms of settings and locations for all created elements.

ISC scripts are text files located within the ISAT installation data folder. Only the custom ISC scripts are located in this folder. This is typically:

C:\Nads\Isat\data\isc

====Icon Files====
Script icon files are 8-bit windows icon files (file.ico). GIMP is capable of exporting valid ico files. To create an ico file, scale it to 32x32 pixels. Export the file as .ico to the isat\data\isc folder.

In order for a script to use an icon file, both files must exist in the isat\data\isc folder.

====ISC Script Examples====
This section contains example scripts with notes.

'''Rotate sign'''

.Name SetSignRotation
.Icon SignRot.ico
Static sign
Select(sign,"Please Select a Sign")
sign.SetAngle(Anchor)
.End

'''Place Multiple Static Objects (TrafCone)'''
The following script asks the scenario author for number of cones to generate, position and offset values and then generates the objects.

A breakdown of the script follows the code block below.

.Name Cones
.Icon cone.ico

Block coneBlock %%%
HCSM StaticObject
IsNewObj 1
Name "Cone_xxx"
SolName "TrafCone"
Option 0
Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
&&&&End&&&&
%%%
Static cone;

Value dist1
Value numberOfCones
Value distance
Value variablePart
Value randDistance
Value speed
Value Count
Value LatOffset

Block tempBlock
tempBlock = coneBlock
Count = 1
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

Ask(numberOfCones,"How many cones?" )
Ask(dist1,"Distance between cones?" )
Ask(LatOffset,"How much offset?" )

Position posRp
Position tempPos
posRp = Anchor
numberOfCones = numberOfCones

Repeat numberOfCones
posRp.GoForward(dist1)
# test comment
tempPos = posRp;
tempPos.SetOffset(LatOffset)
cone.RoadPos = tempPos
cone.Clone
Count = Count + 1
tempBlock = coneBlock
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

End
.End

====Script Breakdown cones.isc====

This section contains a description of the elements used in the script. The script segment is followed by a brief text description.

This script places a number of object copies (TrafCone) using information provided by a user.

.Name Cones
.Icon cone.ico

The first line contains a keyword '''.Name''' followed by the name of the script. This is the name that ISAT will use on the Isat Elements widget for the script. Note the script name does not have to be the same, but it is good computing practice.

The second line begins with the keyword '''.Icon''' followed by a file name. This file must exist in the ISAT\data\isc folder (accompanying the script file). This is the icon ISAT will use for the script.

Block coneBlock %%%
HCSM StaticObject
IsNewObj 1
Name "Cone_xxx"
SolName "TrafCone"
Option 0
Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
&&&&End&&&&
%%%

This is the data section of the script, which is defined using the keyword '''Block'''. A block name follows the keyword, and the data start is defined with '''%%%'''.

The HCSM StaticObject section has been copied from a scenario. In this case, a static object was placed into the workspace and then copied into a text file.

Name "Cone_xxx"
Note: the object name contains a marker that can be used to programmatically name instances of the object:

SolName "TrafCone"
This line begins with the keyword '''SolName''' followed by the name of the object as it is defined in the sol2.txt file.

Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
The Position of the static object will update when the script activates and instanced objects are placed in the workspace.

Static cone;
This line begins with the keyword '''Static''' followed by a variable name.

Value dist1
Value numberOfCones
Value distance
Value variablePart
Value randDistance
Value speed
Value Count
Value LatOffset

This section defines variables with the keyword '''Value''' followed by variable names. Using descriptive names is better than generic names. From the variable list it already seems clear what the programmer cares about: number of cones and distances.

Block tempBlock
tempBlock = coneBlock

This section defines a block using the keyword '''Block''' followed by the variable name.

The next statement replicates coneBlock into tempBlock.

Count = 1
Initialize the value of the variable Count to 1.

tempBlock.Replace('xxx',Count)
The built-in '''Replace''' function changes the string 'xxx' to the value of the variable Count.

cone.SetBlock(tempBlock)
This statement creates a block using the function '''SetBlock''' called cone, and copies the contents of tempBlock into it.

Ask(numberOfCones,"How many cones?" )
Ask(dist1,"Distance between cones?" )
Ask(LatOffset,"How much offset?" )

This section asks the user for input and puts that information into variables:
*Number of cones
*Distance between cones (dist1)
*Lateral offset (calculated from lane center)

Position posRp
Position tempPos
posRp = Anchor
numberOfCones = numberOfCones

This section contains position variables and assigns the value of numberOfCones.

Repeat numberOfCones
posRp.GoForward(dist1)
# test comment
tempPos = posRp;
tempPos.SetOffset(LatOffset)
cone.RoadPos = tempPos
cone.Clone
Count = Count + 1
tempBlock = coneBlock
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

This section is where the work happens. Reading from the top, this section is contained within a loop defined by the keyword '''Repeat'''. The number of times to repeat follows in a variable numberOfCones.

'''posRP.GoForward()''' is a built-in function to take the current position and shifts it forward by the amount specified in the dist1 variable.

#test comment
This is a comment defined by starting the line with the comment keyword '''#'''

tempPos = posRp;

Assign the value of the variable tempPos to the value currently in '''posRp'''

tempPos.SetOffset(LatOffset)

Another built-in function or attribute to the position element which defines a lateral offset (distance from the lane center). This statement places the value of a variable LatOffset into the offset element of the tempPos variable, using the operand '''SetOffset'''.

cone.RoadPos = tempPos

This statement sets the road position variable for cone to the value in the variable tempPos.

cone.Clone

Duplicate the block cone using the operand '''Clone'''

Count = Count + 1
Set the value of the variable Count to the value of Count plus one. This statement increments the value of Count for each loop processed.

tempBlock = coneBlock

Create a new block tempBlock by setting it to the content of coneBlock.

tempBlock.Replace('xxx',Count)

Use a built-in function to '''Replace''' the string 'xxx' with the value of the Count variable

cone.SetBlock(tempBlock)

Use the built-in function '''SetBlock''' to place the modified tempBlock (modified by the string replacement command earlier) into the cone block.

End
.End

The last two lines terminate the loop and the script, respectively.

====How to Create an ISC Script====
The simplest way to create an ISC script is to find an existing script that does something similar to your desired behavior and edit it.

=miniSim Simulation Data=
MiniSim runs on shared memory:
*miniSim is a collection of programs
*shared memory is a commonly accessed 'blackboard' list: a Cell and a Cell Value
:The DAQ file is a snapshot of this 'blackboard' memory for every frame.

*Scenario can write to cells added by the scenario author
:-i.e., for custom hardware or tasks/events

'''NOTE:''' Custom cells must be present in the collect file (NadsMiniSimCollect.cec) '''prior to''' simulation in order for the custom cells to be present in the DAQ.

NOTE: The cell type defined in the collect file must be followed, or garbage values will be used

Use of a DAQ file implies that at some point, data reduction will be needed.
Data reduction: the process of distilling measures from the DAQ file, i.e.
*Event definition
*SDLP
*Average headway

==What is the Difference? Cell vs. Variable==
*A Cell is a pre-created “slot” in shared memory
:-Specified in the .CEC collect file,
:-Saved in the DAQ file,
:-Can be sent to custom programs;
:-Can create & use custom cells;
*A Variable is a name value internal to the scenario
:-NOT saved to the DAQ file,
:-Can use to track items in the scenario
:i.e., how long the driver has been exceeding the speed limit
:-Initialize conditions in the scenario.

=== Variables Save ===
Variables can be saved to disk as a single value text file (ie, multiple values over time are not supported) through the use of a '''Store Variable''' action:

[[File:2021-08-23_13h28_49.png|400px]]

The file is stored in the miniSim_x.x\bin.x64 folder.

'''NOTE:''' The name of the file is defined within the Store Variable action. '''Care must be taken to save variables to unique file names''' in the case of multiple scenarios running on miniSim at the same time (if they share common variables), as would be the case if triggers are copied from one scenario to another.

=== Variables Restore/Read ===
Variables can be read into the simulation through the use of a '''Load Variable''' action:

[[File:2021-08-23_13h32_39.png|400px]]

==Cell Types==
This is a partial list of cell types.

*CFS = control feel subsystem (steering wheel, pedals)
*CIS = control information subsystem (gear, turn signal, buttons, etc)
*TPR = terrain profiler for terrain queries
*VDS = vehicle dynamics for accelerations, position, engine speed, speed, etc.
*ACC = adaptive cruise control
*RCM = configuration management for setting variables that affect subsystem configuration (ACC enabled or disabled, for instance)
*SCC = scenario
*SOP = for one time initializations at the start of the simulation.

=='''Data Output Actions'''==

*Write to Cell Actions
:-Write the value of a variable or cell to a cell
:-Write to a custom cell
:-Cannot overwrite another systems output
'''NOTE:''' Although it is possible to write to a different system cell, that value will be over-written on the next frame. Thus it is effectively not feasible nor desirable to do.

'''<span style="color:red">Also Note: the limit for maximum number of write to cell actions that can be performed in one frame is 8.</span>'''

*Set Variable Action
:-Sets the value of a variable
:-Does not have to be created first
:-Not saved in the DAQ unless written to a valid cell
*Logstream
:-Log data action

===Data Output Methods===
Your data is the primary reason for simulation.

1. Default miniSim scenario measures
:- Immediately available

2. Alternate scenario measures (DAQ file)
:- Processed through data reduction

====Default miniSim Scenario Measures====
*Saved to a drive report.txt file
*Saved to the same Location as DAQ files;
:Scenarioname_timedatestamp_report.txt
•Measures calculated overall, and up to 20 Events during drive:
:Collision Count Lane Departure Count
:Maximum Speed Lane Departure Percentage
:Minimum Speed Speeding Count
:Average Speed Speeding Percentage
:Standard Deviation of Speed Average Headway
:Standard Deviation of Lane Position

====Default miniSim Scenario Measures Require Scenario Event Definition====
In order to capture meaningful data into the default miniSim measures, a scenario must be configured properly to define events.

Use the Write to Cell action to activate the default measures.

[[File:2021-07-02_11h02_44.png|400px]]

*At the start of scenario, set:
::SCC_EventStatus =0
::SCC_EventNumber = 0
*At the start of the first event, set:
::SCC_EventStatus = 1
::SCC_EventNumber = 1
*At the end of the first event, set:
::SCC_EventStatus = 0
*At the start of the second event, set:
::SCC_EventStatus = 1
::SCC_EventNumber = 2
*At the end of the second event, set:
::SCC_EventStatus = 0

Continue this pattern; at end of final event, set:
::SCC_EventStatus = 0

====Default miniSim Scenario Measures Sample Report====
The following is an example report for 4 events. Note the remaining events present in the report are all zeroes or -1.00.

[[File:default_measures_report.png|400px]]

===="Alternate" Scenario Event Definition aka Using Logtreams====
'''NOTE: This method is the more typical/standard method for defining events.'''

Defining an event is key to partitioning simulator data into useful sections. Processing these sections is the essence of '''data reduction.'''

These useful sections are partitioned using logstreams and are generally called '''Events''':
*A logstream is a data marker present in the DAQ file
:there are 10 logstreams
:use logstreams to indicate when things happen '''in the data:'''
:at the start of an event; i.e.,
::grab all data where logstream 1 = 100 (example value)
:during a sub-section of an event
:at the end of an event (typically clears to 0)

Logstreams help separate/filter data;
*SDLP is not useful during emergency maneuver events

Logstreams can be useful to debug events;
:marking in the data when triggers fire
:ensuring event counters work; these are typically sequential, so any logstream deviation identifies a problem

*How to define a Scenario Event:

Set logstream values at scenario event start
:during and at scenario event end, set or clear logstream values:
For example:
::logstream 1 for event ID
::logstream 2 for sequencing the event (during/within event)
::logstream 3 for restart number, etc.

*Requires data reduction to fully process drive data
*Does '''not''' support default measures
:unless those measures are used in parallel with the logstream method

*The use of logstreams allows a scenario author to encode event and environment information into the scenario and as a result, into the simulator data stream.

====Example Alternate Scenario Event====
This section contains an example of a scenario that uses logstream 1 to define an event and environmental context.

In the following example, logstream 1 (LS1) is used to:
#define the scenario start, which is also in this example the event start. NOTE: This is not typical.
#when the driver is 805f from the intersection halt line, set a value into LS1
#when the driver is 500f from the intersection halt line, set a '''new value''' into LS1 NOTE: This could also use a different LS than the one used to define your event, i.e., 1
#when the driver activates a roadpad trigger to reset a force velocity (FV) on a lead vehicle

[[File:event_def_LS.png|400px]]

In the following event definition, an expression trigger is used to set a logstream value and execute two additional actions pertaining to the event.

[[File:event_ET_LS3.png|400px]]

====How to Export Data from A DAQ file using ISAT====
ISAT can display and export DAQ data. NOTE: This is 'raw data', not previously processed. This method can be used to test scenarios, confirm or identify data issues.

TBC: example export here

=Terminology & Documentation=
This section contains terminology and references to related documentation.

'''Action''' - the basic scenario element; the basis for creating scenarios. Actions may be executed on scenario elements (dynamic or static), create or remove elements, or the environment (time of day, visibility) or the simulated cab instrument panel.

'''ADO''' - Autonomous Dynamic Object; self-controlling to a degree.

'''Cell''' - Data elements that are recorded to during a drive; some cells may be used by the scenario author. Custom cells may be added to miniSim.

'''Event''' - anything significant that happens during a drive where the driver condition or response is desired to be identified in the drive data. Can be isolated from general driving through default measures or logstreams.

'''ISAT''' - Interactive Scenario Authoring Toolkit; used to create scenario files for use on the NADS facility or miniSim simulators.

'''ISC''' - ISAT script file.

'''Scenario''' - The simulation experience during a drive; also known as a scenario file, which contains all instructions to the elements within a simulator drive.

'''SDLP''' - Standard deviation lane position

'''SOL''' - Scenario Object Library; objects that are available to ISAT during scenario authoring must be present within the sol2.txt or an auxiliary sol2 (sol2_aux.xxx.txt) file.

'''Trigger''' - A scenario element that contains actions to execute during simulation. All triggers share the same actions, but execution depends on the trigger type.

'''TTA''' - Time to arrival.

'''TTC''' - Time to collision.

=Reporting ISAT & Scenario Issues=
*How to report ISAT & scenario issues:

When reporting issues with scenarios it is helpful to provide as much information as possible.

This often includes scenarios (including any external reference files) and the .LRI file used by the scenarios, screenshots or video that demonstrate the issue being reported and relevant DAQ files. It can be very helpful to include coordinate information with the screenshot or video.

The .BLI file is created from the .LRI and is much larger than the LRI so it may be more convenient to send the LRI file. NADS staff can re-create the BLI file from the LRI.

Some graphics anomalies may be issues with the tile model and not a scenario or miniSim problem. These include:
#white block shapes in the environment
#gaps or missing geometry; i.e., holes
#improper lighting (dark features present during the day)

If these issues happen on a custom roadmap/database world, please include the TMT .mos file as well so NADS can re-construct your environment.

==How to contact the NADS miniSim team:==

email [mailto:miniSim-Support@uiowa.edu minisim support]

[mailto:andrew-veit@uiowa.edu Andrew Veit]
Director of NADS miniSim

[mailto:joseph-meidlinger@uiowa.edu Joseph Meidlinger]
Program Coordinator NADS miniSim

[mailto:oscar-hernandezmurcia@uiowa.edu Oscar Hernandez Murcia]
MiniSim Application Programmer/Analyst

[mailto:chris-schwarz@uiowa.edu Chris Schwarz]
Data Reduction & Vehicle Dynamics

[mailto:shawn-allen@uiowa.edu Shawn Allen]
TMT, Modelling & Support

==How to check what BLI file is used by a scenario==

#You can edit the scenario in a text editor; near the top of the file will be a line starting with '''LriFile''' followed by the name of the BLI file in double quotes.
#You can use '''grep''' to inventory single or multiple scenarios:
:grep bli <scenario file/s>
:A partial listing is shown in the example below. NOTE: The files shown will likely be different on your PC:
C:\NADS\Isat\data\training.demo_scn>grep bli *.scn
Demo_Expression_Lead_Vehicle_Variables.scn: LriFile "simple_rural.bli"
Demo_Expression_Trigger_to_Lead_Vehicle.scn: LriFile "simple_rural.bli"
Demo_HUDD.scn: LriFile "simple_rural.bli"
ISAT-Samples-Avoid.scn: LriFile "esc_dry_05.bli"
ISAT-Samples-Right-Incursion.scn: LriFile "esc_dry_05.bli"
ISAT-Samples-TrafficLightTest.scn: LriFile "simple_city1.bli"
ISAT-Samples-TrafficLightTestB.scn: LriFile "simple_city1.bli"
ISAT-Samples-YellowLightDilemmaB.scn: LriFile "simple_city1.bli"
KBW_TEST.scn: LriFile "simple_rural.bli"
KBW_TESTB.scn: LriFile "simple_rural.bli"
demo.createADO_and_trigger.scn: LriFile "simple_city1.bli"
demo.creation_radius1.scn: LriFile "simple_city2.bli"
demo_FV_sum_of_Sines.scn: LriFile "simple_city2.bli"
demo_LV_Decelerate.scn: LriFile "simple_city2.bli"
demo_LV_cut_in.scn: LriFile "esc_dry_05.bli"
demo_MG.scn: LriFile "simple_city2.bli"
demo_TM1.scn: LriFile "simple_city2.bli"
demo_TT_null.scn: LriFile "simple_city2.bli"
demo_actions_text.scn: LriFile "simple_city2.bli"
demo_alt_data_measures.scn: LriFile "simple_city2.bli"
demo_audio_virtual_object.scn: LriFile "esc_dry_05.bli"
demo_audio_virtual_object_simple_rural.scn: LriFile "simple_rural.bli"
demo_auto_cloud1.scn: LriFile "simple_city2.bli"
demo_coneISC1.scn: LriFile "simple_city2.bli"
demo_dddo.scn: LriFile "simple_city1.bli"
demo_dddo_B.scn: LriFile "simple_city1.bli"
demo_forXRef_traffic.scn: LriFile "simple_city1.bli"
demo_force_vel_01.scn: LriFile "simple_city1.bli"
demo_groupImport.scn: LriFile "simple_city2.bli"

==How to configure miniSim for screenshots to include coordinates==
You can enable coordinate display on miniSim by changing the focus to the main display. #Move the cursor until it is positioned in the main display area, then LMB. When successful the main display will appear to "blink".

Press the keyboard n key twice. This will cause coordinate information to display in the lower left corner of the main display.

[[File:miniSim_show_coords.png|400px]]

The n key is a toggle; to disable coordinates, press it twice (2x) again. '''NOTE:''' the cursor focus must be in the main display in order for this to work.

=Additional Resources=
[[:File:ISAT_Quick_Start.pdf|ISAT Quick Start Guide]]

[[ISAT_Demonstration_Scenarios|Demonstration Scenarios]]

[[:File:Create_Use_Custom_Cells.pdf|Create and Use Custom Cells on MiniSim]]

[[:File:Function_ReadCell_20180824.pdf|ReadCell function]]

[[:File:TrafficManager_Ch12.NADS.Internal_ISAT_UsersGuide.pdf|Traffic Manager]]

=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 [[ISAT_Reference_Manual_Table_of_Contents#ISAT_Reference_Manual|reference manual for ISAT can be found here.]]

ISAT User Guide Table of Contents

2023-09-15T14:52:28Z

Shawn Allen: /* Known Issues add blurb re: missing start or XD */

== Who should use this document? ==
Anyone learning to use the DSRI 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
*CTL-<some other key>: Press and hold the Ctrl and then press <some other key>. Most typically used for copy (CTRL-C) or paste (CTRL-V).
*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 and modify for use in your own scenarios as needed.

== <span style="color:#FF0000"> '''Known Issues'''</span>==

Added 2022.07.01 '''Relative Creation''' does not currently work for ADOs on miniSim.

'''Expression clarification'''

Increment and decrement operators (++, --) are not considered expressions by behaviors. They should not be flagged as expressions when used in the Value field of a Set Variable action.

Added 2019.11.07 '''File reset issue'''

ISAT has a long-standing bug which can reset your static object options when your scenario file is saved to disk.

'''It is strongly recommended that you use [[#External_Reference|external reference scenario files]] to avoid this. '''ISAT does not reset static object options in the xref file.

Added 2021.12.29 Expression Triggers and Values

'''Using Values in Expression Triggers'''

To ensure proper execution of expression triggers, it is recommended that the values used include the desired range by decreasing the lower threshold or increasing the upper threshold '''instead of using the exact value.'''

For example, to process values in a range (7031 - 7040):

[[File:2021-12-29_12h38_09.png|400px]]

'''Note: remember that negative values must be calculated since the expression parser does not parse negative values otherwise.'''

For example, to properly parse a specific transmission gear (Park):
'''ReadCell('CFS_Auto_Transmission_Mode', 1) = ( 0 - 2 )'''

<span style="color:#FF0000"> '''Rehearsal without specifying a start location</span>

In some cases ISAT will crash if the external driver (XD)/start location has not been specified or is missing due to a sol2 file configuration error.

=='''ISAT Overview & Interface Basics'''==
This section contains information about ISAT and the ISAT interface.

===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 <span style="color:#FF0000">'''not an object editor'''</span> 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.
[[File:miniSim_scenario_compnents.png|center|640px]]

*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.

[[File:anatomy_of_a_scenario.png|center|400px]]

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

[[File:scenario_as_text.png|center|640px]]

This diagram shows the same scenario in (left to right) 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, <u>always</u> check your edits in ISAT!'''
*Copy/Paste - delete paths from elements when the BLI is different between your source & destination BLI files. The following scenario elements contain paths:
::ADO (with a path specified)
:: Any roadpad trigger (roadpad, Time to Arrival, Follow)

'''NOTE: A Traffic Source is not a portable element but it can be re-created in ISAT or integrated into a new scenario by copying the element from the source scenario then using a text editor to paste it into the destination scenario'''

'''How can I find information in multiple files easily?'''

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.

What if you don't know what to look for? How do 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
[[File:action_overview.png|400px||border|caption]]

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)

==='''Adding an action to a trigger'''===

The following example uses a Time Trigger; remember that '''all triggers share the same actions'''.

To add an action to a trigger you can double-click on the trigger, navigate to the '''Actions''' panel, and click on New to create a new action.

[[File:2022-11-30_12h47_23.png|400px]]

The possible actions are listed under the '''Action Type''' drop-down menu.

[[File:2022-11-30_12h47_44.png|400px]]

Actions are arranged in a 'stack' and are processed from top to bottom. If you use multiple actions you should enable the '''sequential flag''' to ensure each action is executed in sequence. Without the sequential flag, actions will be processed as fast as the simulator behaviors can execute.

[[File:2022-11-30_12h52_58.png|400px]]

Actions may be re-ordered in the stack using the '''arrows''' located near the action stack list.

=='''ISAT Modes of Operation'''==
[[File:ISAT_modes_of_operation.png|400px]]

*Edit
*Rehearsal
*DAQ playback
*Monitor '''Currently not available'''

==='''Edit & Rehearsal Modes'''===

*Edit - this is where scenario authors will spend the most time.
::Creation or modification of scenario
::Link to or import portions of other scenario elements

[[File:mode_edit.png|400px]]

*Rehearsal
::Debug & test scenario
::Simulates scenario using Behaviors and Vehicle Dynamics
::Displays error messages from behaviors

[[File:mode_rehearsal.png|400px]]

'''NOTE:''' Rehearsal mode <span style="color:#FF0000">simulates </span>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

[[File:mode_playback.png|400px]]

==='''miniSim Scenario Components'''===

The following diagram shows an overview of scenario related components of the NADS miniSim and how these components work together.

[[File:miniSim_scenario_components_wDAQ.png|400px]]

=='''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.

[[File:isat_workspace_general.png|400px]]

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)
[[File:isat_status_bar_overview.png|400px]]

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.

[[File:isat_user_prefs_status_bar_settings.png|400px]]

====ISAT Iconography====
ISAT provides graphic hints for triggers placed in scenario that can be useful when editing or maintaining scenarios.

The general format is a border enclosing miniature icons of the trigger and first action contained in that trigger. Additional information representing one or many actions is also shown.

[[File:hints1.png|400px]]

ISAT will list all trigger actions when a trigger is selected, but these hints provide a way to quickly identify what actions have been authored.

[[File:hint2.png|400px]]

*A Roadpad trigger, one action: '''Traffic Light Action'''
*B Roadpad trigger, multiple actions, first action is '''Remove Element'''
*C Roadpad trigger, multiple actions, first action is '''Set Dial'''
*D Roadpad trigger, constrained to road (lane), no actions - this is an empty trigger
*E Roadpad trigger, multiple actions, first action is '''Log Data'''
*F Global Time Trigger, single action: '''Set Dial'''

[[File:handle.png|400px]]

The element handle is the red dot visible in most of the triggers.
The handle can be dragged into position, and the trigger will follow the handle

Drag the trigger off the handle to offset it's location from the handle

==='''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.

[[File:object_types_isat.png|400px]]

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
::*Traffic Source

:'''NOTE:''' Virtual objects are defined in the scenario, not in the SOL2.
[[File:object_types_world.png|400px]]

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.
::NOTE: 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.

==='''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:
#Follow a path using kinematics
#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:
#coupled
#relative trajectory
#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'''===
Traffic signals are objects with special operation and function; they are coupled to intersections and routes of travel through intersections to control traffic flow similiar to their function in the real world. Traffic signals are part of the source tile model and may not be re-positioned or physically altered by scenario except for their visual signal state appearance; i.e., red, green or yellow signals.

To control intersection traffic signals use Edit >> Traffic Light ManagerTraffic signals use a Signal State Table (SST) to control which signal states are active and when. Each intersection with traffic signals will have an associated SST.

[[File:traffic_light_state_manager.png|400px]]

The above diagram shows an intersection in the workspace to the right, and the traffic signal state table for that intersection on the left. At this point additional states (for signal condition) can be added by clicking the '''Add state button'''.

[[File:traffic_signal_state_table2.png|400px]]

The above diagram shows two states defined for the intersection, represented by the two columns of state condition.

Continue adding states until the desired signal cycle has been defined. Generally this consists of red, green or yellow states.

NOTE: There is currently no way to automatically author a series of traffic light signals

To author traffic signal lights in sequence or on a route, the scenario author has to manage the signal states

[[File:traffic_signal_state_duration.png|400px]]

To edit the signal state duration RMB on the duration field header and choosing '''Edit state duration''' on the context menu. Enter the desired value then click OK.

====Traffic Signal Types====
The ISAT status bar reports Traffic Signal Type name. There are two signal types:
#Standard signal - IDs may have no identifying information
:Valid signal states: Red, Yellow, Green, Flashing Red, Flashing Yellow, OFF
#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

[[File:traffic_light_extended_type_name_normal.png|400px]]
: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.

[[File:traffic_light_extended_type_name.png|400px]]

===Changing Signal States in Scenario===
Traffic signals are controlled in scenario by using a Traffic Signal Action to change the SST.

'''NOTE:''' The Traffic Signal Action works by changing the SST, '''not by changing the traffic signal.''' This is a subtle but important difference.

Setting a signal to an undefined state effectively does nothing to the traffic signal.

[[File:traffic_light_state_table.png|400px]]

The above diagram shows a fully populated SST, with one signal row highlighted in red, and one state column highlighted in green. The associated intersection corridor is highlighted, showing the signal controls a dedicated left turn.

During simulation, the initial signal state is defined by the left column. As the simulation proceeds, the signal state changes according to the duration states defined across the state table, proceeding left to right and then wrapping around to the beginning after the last defined state. Each traffic signal appearance changes according to the configuration of the SST.

As a driver approaches this intersection, assume the signal state is in the column left of the highlighted column ('''R'''ed), and the desired action is to change the signal to green.

The action used to change a traffic signal state is the '''Traffic Light Action'''.
Using a traffic light action requires the specification of a signal state, the traffic signal to affect, and a duration.

[[File:traffic_signal_action1.png|400px]]

In the above diagram the scenario author has specified the desired state as '''Green''' as shown in the action dialog.

However, referring back to the previous state table diagram, there is no such state present in the SST. That means this particular action will fail, and the traffic signal will not change as the driver approaches the intersection - because the action does not create a new signal state, it works by advancing the state table condition (column) to the specified condition. If the condition is not present in the SST then nothing will appear to happen.

In this example, the action should be edited to use the correct signal state '''Left Turn Green''', which is present in the SST.

'''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

[[File:known_issue_traffic_light_action.png|400px]]

'''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.

[[File:known_issue_traffic_light_action_workaround.png|400px]]

====Change A Traffic Light Using Scenario Action====
To change a traffic signal, use the Set Dial >> Traffic Light action.
'''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

[[File:traffic_light_state_table.png|400px]]

This diagram shows a fully populated traffic signal state change for an intersection.

*Static object traffic lights
:These are objects, not true traffic signals and so they are not controlled with the Traffic Light manager.

==='''Traffic Source'''===
A traffic source is a coordinator used to create traffic at specific locations in the road map (unlike the Traffic Manager). This is useful for creating ambient traffic. Traffic Sources creates ADOs or DDOs at random or user-specified intervals.

Elements created using a Traffic Source will be created at the locations specified by the user. If traffic is specified at multiple locations the actual location for each creation will be determined randomly during simulation.

'''Note:''' Using the Relative Creation flag on ADOs created by the traffic source will not create traffic at the specified location on the map, but use the information in the Relative Creation fields to populate traffic in the scene during simulation.

This method allows for more flexibility but care must be taken not to create so many ADOs that miniSim is unable to make frame rate. Too many ADOs will cause the scene to jump and 'jitter' and it will feel slower than normal.

==='''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 ISAT scenario rehearsal

===Custom (icon) file virtual objects===

[[File:virtual_object_custom_icon_file.png|400px]]

'''Note:''' Some versions of MiniSim_2.3 do not support custom virtual objects. For those installs, if you require this type of functionality, a workaround exists in the form of a 2D model that can be customized (i.e, sprite).

Virtual objects may be customized using graphics files (texture images) to display any desired custom element. This typically requires the use of a bitmap graphic. Various file formats are supported: JPG, BMP, PNG. It is possible some types of these formats may not work - in those cases, try an alternate format.

If image transparency is required and the custom icon does not display during simulation, please email dsri-minisim@uiowa.edu with a description of the issue, your scenario and custom virtual object image file.

Custom icon files must be located within the Nads MiniSim path for resources - at NadsMiniSim_x.x\data\visuals\Models\ModelTx.

===Standard virtual object shapes===
The virtual object shapes include:
# Circle
# Triangle
# Octagon
# Star
# Diamond
# Icon <- this is for custom virtual object graphics
# Rectangle
# Hexagon

The virtual object fill and border color and transparency can be set in the virtual object properties dialog panel.

[[File:virtual_object_std_shape.png|400px]]

====Virtual Object Workaround====

There is a scenario authoring method that can be used to emulate virtual object functionality through the use of a DDO that is coupled to any dynamic scene element, including the External Driver. One model has been created to support this method called "sprite".

'''Note:''' The sprite model is a 2D object present in the scene, and can therefore be occluded by other scene elements during simulation.

[[File:trafsign_sprite.jpg|400px]]

The sprite model is designed as a flat plane that continuously faces the viewer. It contains different sized planes and can be customized through textures.

When authoring your scenario, configure the sprite object to Off unless it should be visible at scenario start. During the scenario you can control the sprite appearance with a setSwitch action.

[[File:sprite_setSwitch_action_021121.png|400px]]

The who to effect should use the name of the DDO placed in your scenario. The switch name will be s_sprite as shown above. Any valid option can be used. An invalid option (greater than 30) will disable the sprite the same as selecting the OFF option.

==='''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'''===
<span style="color:#FF0000">'''All trigger types share the same Action types'''</span>
*IF Then conditional
*Predicate: i.e., the activating agent
:If predicate is TRUE, then do Action(s)
*Road related triggers are categorized by predicate type
:Named element
:Road (lane)
:Nth vehicle on path only

'''What trigger is appropriate?'''
To determine which trigger is most appropriate, consider the task you are trying to accomplish. '''The differences between triggers is their activation methods.'''

'''Global Time Trigger'''
[[File:isat_time_trigger.png|150px]]

Use this trigger when something has to happen at some point in time.

Time triggers are also useful as "placeholder triggers"; used to apply persistent actions to multiple elements with unique settings for each element. Normally a persistent action is the last action possible in a trigger since the persistent action fires continuously. Putting persistent actions into a time trigger allows the scenario author to continue an action stack in the parent trigger if necessary.

Time triggers can be used as a 'stopwatch' - elapsed time, such as ending a drive after 3 minutes by setting the trigger to fire using an Activation Delay of 180s (GTT >> General).

Often used as a placeholder for actions such as initializing variables, displaying text messages to the screen using Set Visual Display Text actions, etc.

'''Note''': A time trigger can have global elapsed time and activation delay of 0, which causes the action stack in the time trigger to activate when that trigger is created.

'''Roadpad Trigger'''
[[File:isat_roadpad_trigger.png|150px]]

Use this trigger when something has to happen at some location in the drive that does not require event timing to be comparable for all participant drivers. For cases where event timing must be comparable among all participant drivers use the Time to Arrival trigger (TTA) instead of a roadpad trigger.

'''Time to Arrival Trigger'''
[[File:isat_time_to_arrival_trigger.png|150px]]

Use this trigger when something has to happen relative to some point in the drive, and also ensure all study drivers experience the same event timing irrespective of driver style (conservative, slow vs. aggressive, fast). Time to arrival (TTA) trigger uses a time calculation from the trigger pad activation to a target location specified in the trigger.

'''Traffic Light Trigger'''
[[File:isat_traffic_light_trigger.png|150px]]

This trigger activates actions when the specified traffic signal state is reached. For example, if the desired action is to create a DDO pedestrian to step into traffic when the traffic signal is yellow, then the Traffic Signal Manager must be used to author the appropriate signal states for the traffic signal.

Typically some other trigger is used to control the traffic signal (ie, to change the signal to Yellow on approach). It is therefore perfectly valid to put the actions within this other trigger rather than relying on the traffic light trigger.

'''Note''': Once a traffic light action has been authored, ISAT may be prone to crashing when accessing that trigger. This problem can be avoided by creating a time trigger and isolating the traffic light action there, allowing the parent trigger to be modified without crashing. Adjustments can be made to the traffic light action time trigger in a text editor, or recreated if it becomes necessary to make adjustments and ISAT continues to crash when trying to make edits.

'''Note:''' The traffic light action does not change the traffic signal state, and it requires a valid state sequence to exist in the signal timing table (Edit >> Traffic Light Manager). The traffic light action '''will not create a signal state''' that does not already exist in the signal timing table.

'''Expression Trigger'''
[[File:isat_expression_trigger.png|150px]]

Use this trigger when something must be monitored, evaluated or calculated such as checking a variable or cell value, velocity of the driver or the state of simulator hardware (steering wheel angle, brake or accelerator pedal position) or distance from the driver to some other object in the scenario.

Multiple expressions can be used within the same expression trigger. In those cases, all expressions must evaluate to True in order for the action stack to execute unless using an '''OR''' operator.

Use the '''OR''' operator - the pipe character "|" if you want to activate the action stack if '''any''' of the expressions evaluates to True.

In the following example, the trigger checks for TrialNumber = 1 and FirstButtonPress variables, and then checks if Aux Button 1 or 0 was pressed:

'''ReadVar('TrialNumber') = 1.0 & ReadVar('FirstButtonPress') = 1.0 & (ReadCell('Auxiliary_Buttons', 0) > 0 | ReadCell('Auxiliary_Buttons',1) > 0)'''

'''Note''': Expressions can also be embedded into some other triggers, most notably the Set Dial >> ADO >> Forced Velocity action often used in Roadpad triggers.

'''Follow Trigger'''
[[File:isat_follow_trigger.png|150px]]

Use this trigger when something has to happen based on one ADO position relative to another scenario element (including the XD). The follow trigger requires a leader and a follower to be specified; when this condition is met, the trigger action stack activates.

'''Note''': Both leader and follower must be positioned on the follow trigger roadpad to satisfy the follow parameters.

'''Geometric Position'''
[[File:isat_geometric_position_trigger.png|150px]]

This trigger is most useful to perform actions for off-road actors such as walkers. The trigger predicate is limited to Name or Type and requires a geometric position to be defined.

A more limited version of the geometric position trigger can be implemented with a Global Time Trigger that contains a Creation Radius. Placing the creation radius defines the area where the trigger may be activate.

===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

[[File:Screenshot (208).png|800px]]

'''Note:''' The highlighted lane shows which lane is the '''activating lane'''. Other lane/s will not activate the trigger action stack.

===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

[[File:TTA.png|400px]]

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===

[[File:other_triggers.png|400px]]

*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===

Execute actions if input expression evaluates to TRUE; the expression is specified on the trigger Predicate tab.

====Syntax====
Expression triggers support a simple language syntax with operators and functions.
The syntax is infix notation; i.e. a + b, not a b +.

Note: It is not generally possible to embed one function call inside another:
cos(sin(x)) is therefore an invalid expression. ISAT will report invalid expressions during rehearsal of a scenario. Invalid expressions are not supported and will not operate as written during simulation.

'''Exception:''' Currently it is possible to use the square root function with GetObjDistPow2 as in the following example:

sqrt(GetObjDistPow2('Target_Object_Name'))

Multiple expressions may be combined using the logical AND (&) or OR ("|" pipe character).

Exp1 '''&''' Exp2, Exp1 '''&''' Exp2 '''&''' Exp ''N''

All expressions must be true for the trigger to evaluate to TRUE and execute the action stack.

Exp1 '''|''' Exp2
One of the expressions must be true for the trigger to execute the action stack.

Negative values are not directly supported by the expression parser. To use a negative value, it must be a calculated value such as the following:

'''ReadCell('CFS_Steering_Wheel_Angle',0)<(0-5.0)'''

==== Operators ====
Operators are used to create expressions.

'''String'''
:Used within quotes as a string literal; i.e., 'some string'

Grouping
:Parentheses group elements together; i.e.,
:'''()'''; (a), (a + b)

Multiplication
:'''*'''; a * b

Division
:'''/'''; a / b

Addition
:'''+'''; a + b

Subtraction
:'''-'''; a - b

Note: negative values must be expressed with a subtraction operation:
(0 - 5), not -5 (invalid)

Greater than
:'''>'''; a > b

Less than
:'''<'''; a < b

Logical And
:'''&'''; a & b

Both a and b, otherwise returns 0 (FALSE)

Logical Or
:'''|'''; a | b

a or b returns 1 (TRUE)

====Expression Functions ====
Functions are used with operators to create expressions.

Function: '''sin'''
:sin -sine

Syntax
:sin(float x)

Description
:The sin() function returns the sine of x, where x is given in radians.

Return Value
:The sin() function returns a value between -1 and 1.

Function: '''cos'''
:cos –cosine

Syntax
:cos(float x)

Description
:The cos() function returns the cosine of x, where x is given in radians.

Return Value
:The cos() function returns a value between -1 and 1.

Function: '''ReadCell'''
:ReadCell()

Read a Cell value.

Syntax
:ReadCell(string Name, int Cell Array index)

Description
:ReadCell returns the value of a given cell (a cell is the current instance of a variable that will be maybe written to a daq file).

Index specifies a 0 based index into the array. Since most cells are single element arrays, a value 0 indicates the first element.

Cells valid for the ReadCell function are defined within the cell collect file NadsMiniSim.cec located in the miniSim_x.x\data folder.
The ReadCell function operates on shared memory during simulation, it does not read cell data from the DAQ file.

Cells that are defined may be written to the DAQ; the collect file specifies which cells are saved into the DAQ and what frequency to use for the write operation.
The NadsMiniSimCollect.general.txt file is located in the miniSim_x.x\data folder.

Available Cells:
Any cell that has been defined in the .cec file. For example:

:'''LogStreams''': Array of 5 floats. Logstreams are a set of values the scenario author can write to through “write to logstream” actions.
:'''AccelPedalPos''': Single Value. The current position of the accelerator pedal
:'''BrakePedalForce''': Single Value. The current force on the brake pedal in pounds
:'''SteeringWheelAngle''': Single Value. The current rotation of the steering wheel
:'''CruiseControl''': Single Value. The current cruise control position. (values are cab/platform specific)
:'''TurnSignal''': Single Value. The current position of the turn signal (values are cab/platform specific)
:'''OvVel''': Single Value. The participant’s current speed in miles per hour
:'''OvLaneDev''': Single Value. The participant’s lane deviation in feet.
:'''OvHeadwayToLeadVeh''': Single Value. The distance in feet to the first vehicle in front of the participant. -1 if no vehicle can be found.
:'''OvTtcToLeadVeh''': Single Value. The time to collision to the first vehicle ahead of the participant.
:'''Horn''': Single Value. The state of the horn (values are cab/platform specific)
:'''DynObj_Vel''': Array of 20 floats. The speed of a given dynamic object. Dynamic Objects are sorted in terms of distance to driver.
:'''OvVelLocal''': Single Value. The participant’s current speed in miles per hour, using the value local to scenario control

For a complete list of cells and array elements please see the miniSim data dictionary spreadsheet.

Return Value
:Returns the value of the specified cell.

Example
ReadCell(‘LogStreams’,5) > 3

Function: '''CellEquals'''
:Cell Equals, array element, value to compare

Syntax
:CellEquals(string name, int index, float value)

Description
:The Cell Equals function is similar to the ReadCell function, except it adds an additional value to compare against the cell value.

Like ReadCell, name specifies the name of the cell, index specifies the cell array index (use 0 for single value cells).

Available Cells:
:Any cell that is defined in the .cec file.

Return Value
:Units: 1 or 0
:1 if the cell value is equal to the passed in comparison value; otherwise 0

Function: '''GetObjDistPow2'''
:Get object distance squared

Syntax
:GetObjDistPow2(string name)

Description
:GetObjDistPow2 returns the distance squared between the external driver and the dynamic object specified by ‘name’.

Distance squared is used to avoid having to perform an expensive square root calculation every frame.

If the specified object cannot be found, a value larger than 100 million is returned.

Return Value
:Feet; Distance in feet measured from the eye position of the driver to the CG (centroid) of the dynamic object specified.

A very large number is returned if the specified object cannot be found (larger than 100 million)

Example
:GetObjDistPow2(‘OncomingCar1’) < 2500

'''Note:''' To get an actual distance, multiply by the square root (sqrt())
: sqrt(GetObjDistPow2('Target_Obj'))

Function: '''GetObjTtcToOv'''
:Get Object Time To Collision to Own Vehicle

Syntax
:GetObjTtcToOv(string object name)

Description
:GetObjTtcToOv gets the time to collision from the dynamic object specified by the name parameter, to the own vehicle.

Return Value
:Unit: Seconds
:Time (seconds) to collision from the own vehicle to the dynamic object specified by the name parameter.
:0 is returned if the object specified cannot be found.

Function: '''GetObjVel'''
:Get Object Velocity

Syntax
:GetObjVel(string object name)

Description
:GetObjVel gets the velocity in meters per second of the first dynamic object with the name specified by the ‘name’ argument.

Return Value
:Unit: Meters per second
:The speed of the specified dynamic object; 0 if no object is found

'''Note:''' Multiply by 2.23694 for miles per hour.

Example
:GetObjVel(‘PullOutVeh’) > 15.4

Function: '''Rand'''
:Random

Syntax
:Rand(int value)
:Rand(string name)
:Rand(string name, string type, double parameter, double parameter)
:Rand(string name, string type, int parameter, int parameter)

Description
:Rand returns a random value specified by the name of the generator, the type of distribution and its parameters.

If the user does not specify the name of the generator and only specifies a number as the only parameter, the Rand function will use a default random number generator to produce random numbers.

If the user only enters the name of a user created random number generator, the random number generator will produce a value between 0 and 1.
If a name of generator is supplied that has not been created, the Rand function will display an error message in the ISAT debug window and return 0 (during scenario rehearsal).

The rand function supports multiple types of distributions that can be used to generate a random number.

Types of Distributions:
:normal: Normal Distribution(mean, standard deviation). The normal distribution generates random numbers near the mean with a specific standard deviation.
:gamma: Gamma Distribution(alpha, beta). The gamma distribution generates a random value that models waiting times for the Poisson process.
:uniformInt: Uniform Integer Distribution(min, max). The uniform integer distribution generates a random integer number between the lower and upper bounds.
:uniform: Uniform Real Distribution(min, max). The uniform real distribution generates a random floating point number between the lower and upper bounds.

The values stated in the parenthesis above are the parameters for each distribution in order. If the incorrect number of parameters are entered or if they are entered incorrectly, the debug window in ISAT will display an error message and the rand function will return 0 (during scenario rehearsal).

If the distribution is entered incorrectly, the debug window will also display an error message.

Return Value
:A random value from 0 to 1 if the type of distribution is not specified.

If the type of distribution is specified, returns a random value determined from the type of distribution and the given parameters.

Example
:Rand(‘myRandGenerator’,’uniformInt’,1,10)
:This example returns a random integer value from 1 to 10.

Rand(5) or Rand(‘myRandGenerator’)
:These examples return a random value between 0 and 1.

Function: '''sqrt'''
Square root

Syntax:
:sqrt(parameter)

Return Value:
: return the square root of the specified parameter.
: parameter can be another function, such as GetObjDistPow2()

Function: '''ReadVar'''
:Read a variable

Syntax:
:ReadVar(string Name)

Return Value:
:Returns the string value of variable specified in <variable_name>

===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.

=='''Audio Components'''==
The components of the Audio sub-system includes configuration and data files installed into the NadsMiniSim_x.xx\data\sound\DefaultCabSound\Instructs folder.

[[File:audio_components.png|400px]]

The audio engine contains multiple channels and has a theoretical limit of 512 simultaneous sounds.

NOTE: Not all .wav files are compatible with the Audio Engine.

=Scenario World Objects=
Scenario world objects are defined in the tile model source. They are not added by the scenario author since they are objects already present in the roadmap/BLI.

[[File:object_types_world.png|400px]]

Typically, but not always, these objects can be authored in ISAT. However, some scenario world objects have no options - these cannot be selected in ISAT; therefore such objects cannot be authored.

Removal of world objects requires editing the source tile model using a 3D application. In some cases an alternate tile model is available identical to the original but without objects.

Contact NADS if removal of a world object is needed.

Other scenario world objects, such as Traffic Signals, are specialized function objects that can be authored. Traffic signals are authored using the Traffic Light Manager: Edit >> Traffic Light Manager.

=Troubleshooting Scenario Objects That Reset=

== Scenario World Objects ==
Scenario world objects are already present when you create a new scenario - they are not added by the scenario author. These objects may be visible in miniSim but not in ISAT, or they may be visible in ISAT and seem to be controllable, but the objects 'reset' to their defaults when viewed on miniSim.

[[File:2019-10-23_16h18_47.png|700px]]

The objects which 'reset' are a symptom of settings in the TMT that are not configured to allow scenario authoring of objects.

[[File:2019-10-23_16h18_52.png|700px]]

When objects appear to 'reset' or if you can edit an object in ISAT but don't see your changes in miniSim, correct the problem by resolving controllability in the TMT settings: https://www.screencast.com/t/ZH5Dh178.

=Scenario Coordinate Types=
There are two types of coordinates used in scenarios. The first is roadway coordinates. These coordinates are contextual (tied to a specific road or intersection and position) and are used for ADO objects and roadpad paths in general.

After a roadway coordinate has been generated, it is not updated unless the scenario author makes changes to the start, end or location of the entire path or pad.

Roadway coordinate are the reason it is not possible to change a roadmap using the TMT and expect a previously authored scenario to work on the altered roadmap. If the length or location of a road changes, the path/pad will update to the extent possible.

If the road has been eliminated and no longer exists in the roadmap/BLI, ISAT will report an error and not open the scenario file.

A. Field breakdown:
RoadPos keyword <name of road:lane:position on road:path length>

Name "Ado1"
RoadPos "r1_-6600_4620:0:5737.06:0.00"
Path "R:r1_-6600_4620:0[5736.06:5873.83]"

[[File:isat_coordinate_types.png|400px]]

B.
Name "VirtObj"
Option 2
Position -6.8375599E+002 5.6331237E+003 0.0000000E+000

The second type is world coordinates, which are Cartesian coordinates with X increasing to the right, Y increasing forward, and Z increasing up.

='''Scenario Authoring'''=
Scenario authoring is the creation, editing and testing of everything that happens during a simulation drive.

==Cell Operations: Best Practice==
Reading and writing to cells is a computationally expensive process. Best practice is to centralize all the reads/write to one place so that it’s only done once per cell.

Once a cell is read, the value is copied to a variable and only the variable is used throughout all the triggers that need it.

The same process applies to writing to cells. Use of variables can reduce the Cell Operations overhead greatly.

==Before You Begin==
Before beginning a scenario, it is necessary to understand the following requirements:

=== Drive Requirements===
How long is the drive?
What type of roadway?
Are there any specialized road elements (intersections, interchanges, freeway ramps)?
Are there any environmental requirements (should the simulation replicate a real world location, or is a generic environment acceptable)?
Is there a particular roadway configuration that is needed (long straight rural road vs. typical urban environment with intersections, signals, etc)?

=== Traffic Requirements ===
What types of traffic will be needed?
Will ambient traffic interact with the external driver?
What types of interaction will be required (traffic cloud, lead vehicle, follow vehicle)?

=== Events ===
The purpose of an event is to present a situation to the external driver. In order for the simulation to produce meaningful data, it is critical that events unfold for each driver in a comparable way. Therefore, each event must be designed with this repeatability in mind.

'''NOTE:''' one of the most variable scenario elements is the driving style of each external driver: how conservative or aggressive they drive, velocities throughout the scenario, how comfortable the driver is travelling with simulated vehicles, etc.

Repeatability often includes static elements (each driver encounters scenario elements in the same location) or in cases where the driver performance is taken into account, accommodation of the driver dynamic (velocity, lane position) through the use of time to arrival triggers (TTA) or follow triggers. A TTA trigger will fire based on time to a target location - thus a driver travelling at 45mph or a driver travelling at 55mph can both experience the same action relative to that target location, irrespective of the different driver velocities.

==Beginning A Scenario==
All scenarios designed to be driven require a start location - the place where the driver will be located when the simulated drive begins.

To insert a start location into a scenario:

:Insert >> External Driver >> LMB on road, intersection or terrain object

[[File:isat_initial_position.png|400px]]

'''NOTE:''' scenarios that only contain data and are not intended to be driven - for example, signs or traffic that are used as external reference files do not require a start location, since that will be defined within the parent scenario.

==Initial Conditions==
Initial conditions define how the simulated scene is configured: will the drive occur during daylight or night time conditions? Will the ownship (external driver vehicle) have headlights enabled? What type of vehicle will it be? Will there be objects or traffic visible to the driver?
These form the initial conditions of the simulation experience. Additional initial conditions would include initialization of variables or establishing networked communication as needed by the scenario.

[[File:isat_initial_conditions_miniSim.png|400px]]

By default ISAT sets the initial condition '''Time of Day''' to 12:00 noon. The time of day is controlled from the Initial Conditions dialog:

Edit >> Initial Conditions

[[File:isat_initial_conditions_scenario.png|400px]]

==Scenario Authoring: Actions==
Actions are the scenario elements that make things happen during simulation. Actions do specific things, like display a text message on screen for the driver, create a scenario element, change the velocity of simulated traffic, change a traffic signal, etc.

[[File:trigger_action_panels.png|400px]]

The diagram above shows the action panel for left to right: an expression trigger, a roadpad trigger and a global time trigger showing different panels based on the actions present in each trigger.

'''NOTE:'''Actions can be created, edited or removed from the '''Actions panel''' of '''any trigger'''.

'''NOTE:''' The Actions panel changes based on the action type created.
When multiple actions have been defined, control the sequence of actions by changing the action order in the list using the up or down arrows next to the list.

[[File:action_panel_overview.png|400px]]

If multiple actions need to happen in a specific order, set the order using the arrows and then flag the action list as '''sequential'''. This instructs behaviors to process the actions in the list order.

Using a delay for any action will pause processing of the '''following actions'''; the action happens first, then the delay is applied.

===Scenario Authoring: Action Types===
There are two types of actions:
# Instantaneous - the action takes up to one frame to complete, i.e.:
:set target velocity
:write to cell
# Persistent
<span style="color:red">'''*Persistent actions do not end'''</span>, or take multiple frames to complete:
:Forced lane offset
:Forced velocity
:Maintain Gap

==='''Actions'''===
*The "Who to Affect" field defines what is affected by the action
:Instigator set: who activated the trigger
:Name: one or more named elements
:Type: Apply changes to all objects matching the specified type
:Relative: Position relative to the trigger location

*Sequential
:Actions to execute sequentially, one after the other
:Specify delay between actions
:: Action executes, then delay

:Some actions are persistent and never "finish"

===Scenario example: display text & roadpad trigger to stop the drive===
This scenario is very simple and contains a global time trigger (GTT) that tells the driver what to do. After the driver travels along the roadway, a roadpad trigger (RPT) is used to tell the driver to stop driving. The same RPT also creates an expression trigger to terminate the drive.

TBC example scenario file

Because the external driver is not under control except by instructions, it's possible they might ignore the halt message and continue driving. A second failsafe RPT then terminates the drive.

==='''Actions: Button vs. Dial'''===
*Dial changes a setting
*Button: always runs in a single frame
:-"immediate" change. Typically buttons have less control than a '''Set Dial''' action

==='''ADO Actions'''===
[[File:ado_action_types_button_vs_dial.png|400px]]

==='''DDO Actions'''===
[[File:ddo_set_dial.png|400px]]

==='''External Driver Actions'''===
External driver behavior can be influenced by reinforcing scenario actions through audible speeding alerts, on-screen text instructions and messages or audio instructions.

Driving behavior can be influenced with situational elements
:Car in the drivers blind spot
:Lead vehicle
:Aggressive following vehicle
:Temporary lane closure
:lane specific instructions

Scenarios should '''not rely on specific driver actions to be successful'''
:to the extent possible; sometimes you do need the driver to respond/behave in a controlled manner.
:A work zone blocking one lane typically will require a roadpad placed upstream from the work zone to shift traffic into the correct lane

'''NOTE:''' Controlling driver actions should be an experimental design consideration.

==='''Special Actions'''===
These actions need special handling:
*Reset or "toggle":
:Audio
:Display Text

:'''Ado'''
::Audio State
::Forced Velocity
::Maintain Gap
::Visual State

*If using these persistent actions, place them at the '''end''' of an action sequence (because no action following these will execute):
:Forced Lane Offset
:Forced Velocity
:Maintain Gap
:Visual State

*Note: If the Visual State action contains a duration then it will be handled as a normal action, with subsequent actions firing after it. However, if there is no duration supplied with the Visual State action it behaves like a persistent action, and nothing following it in the Action stack will ever fire.

[[File:multiple_simultaneous_actions.png|400px]]

The diagram above shows how one parent trigger can be used to create multiple simultaneous triggers

*How to activate multiple unique force velocity (FV) or maintain gap (MG) actions:
#create the needed triggers from a general parent trigger, 1 per action
#put common actions into the parent trigger
::reset FV
::reset MG

==Scenario Authoring How To==
This section contains simple examples for various typical scenario situations.

===How do I specify an event?===
First, determine which method is best for you - the default measures (limited measures, 20 events max) or logstreams (all simulation data, no event maximum).

Regardless of method, you specify an event by identifying areas of significance in the drive and marking them so the data within the event region can be processed. Any trigger combination that can specify event start and event end may be used.

[[File:2022-07-01_11h21_52.png|400px]]

===How to know Which Coordinator or Trigger I need?===
The answer to this question lies in the type of information needed for an event:

*Time
:global time trigger
:or an expression trigger that calculates time
*Position or Location
:roadpad trigger
::or a time to arrival (TTA) trigger
::or an expression trigger that calculates distance
*Calculation
:Expression trigger

===How to Instruct the External Driver===

Instructions to the external driver can be accomplished by three main methods:
# Instruct the driver using experimental protocol (instructional or briefing presentation)
# Information messages displayed on screen: '''Action: ''set visual display text'' '''
# Information messages delivered as audio messages: '''Action: ''write to cell > SCC_Audio_Trigger ><audio ID>'' '''

===How to Add Traffic in the Scene ===

Generating traffic will happen in one of 5 ways:
# Created explicitly by inserting ADO, or copy/paste existing ADOs
# Created with a script
# Via a Create action inside a trigger, or placing scripted traffic inside a create action within a trigger
# From a '''Traffic Source'''*
# From the '''Traffic Manager'''**

Each of these methods has advantages and disadvantages.

==== Create Explicitly ====

The biggest advantage with this method of traffic creation is the high degree of control the scenario author has over:
# location of the created ADO
# Name of the created ADO
# Travel path of the created ADO
# Control when each ADO is created within the scene via Settings >> Creation Radius

The disadvantage is that creating a high volume of traffic will take some work with this method.

==== Created with a Script ====

This method combines the advantages of Creating Explicitly with volume. It is possible to create a large volume of traffic very easily with a script.

Disadvantages of using high volumes of traffic with a script: in the event it becomes necessary for a high degree of control over these ADOs, more is not better because ADOs will adapt to road conditions under their own power, unless the default ADO settings have been modified:
'''lane changes, including lane changes to accommodate freeway ramps'''
'''velocity adjustments'''

==== Via a Create action inside a trigger ====
Combines the advantages of the previous 2 methods with control over when to activate that traffic using a trigger action.

Disadvantages: Creating too many ADOs at one point in the drive can cause the miniSim to bog down for a few frames. If too many ADOs are present and active in the simulation at one time, this can cause the miniSim to drop frames and run sluggishly. This is highly noticeable and may increase the potential for the External Driver to experience '''simulator sickness.'''

==== From a '''Traffic Source''' ====

Traffic Sources rely on two methods to populate a scene with traffic:
# location specific, with each ADO created for a traffic source being a 'spawn location' for ADOs, or
# location agnostic if the ADO has '''relative creation''' enabled, thus being created relative to the object identified.

In addition to being created relative to a scenario element, ADOs are created relative to the specified scenario element:
# In front of (Longitudinal Distance > 0, where the number is feet offset from the object) , or
# Behind (Longitudinal Distance < 0, where the number is feet offset from the object).

Advantages: Can easily populate traffic into the simulation.

Disadvantages: It is easy to generate more traffic than the simulation can maintain at 60Hz frame rate, thus introducing frame lag with the resulting scene 'stutter' and the increased risk of simulator sickness.

Also, traffic created from a Traffic Source is generic traffic. It is not possible to reliably refer to specific ADOs generated from a traffic source except by using Who To Affect >> Relative (versus referring to a named ADO, i.e. Slow_Moving_Lead_Vehicle). Referring by name to Traffic Source generated ADOs will affect all similarly named ADOs at the same time.

==== From a '''Traffic Manager''' ====

The traffic manager interface is problematic in ISAT versions up to 1.8.5, especially when specifying the set of vehicles to be used for generating traffic.

Advantages: Create generic ambient traffic easily.

Disadvantages: Has the same disadvantages as traffic created via a Traffic Source. Also getting a traffic set working by specifying the vehicles to be used within the set. ISAT versions up to 1.8.5 exhibit instability when setting vehicles in ISAT.

Traffic Manager Set workaround: Borrow a working set from an existing scenario or group. Alternatively use a version of ISAT (1.8.6 +) to create the traffic set. This can be saved as a scenario or group file, which can then be used with ISAT 1.8.x as long as there is no attempt to adjust the vehicle weights within ISAT. The scenario or group file can be edited as text in a text editor, but care must be exercised to avoid introducing errors into the file. ISAT will not read invalid scenario or group files.

Traffic generated by the Traffic Manager is controlled through the use of Input Sets. An input set is a collection of vehicles and weights used to populate the scene during simulation. This is how the scenario author can control the vehicle population (type and number), density and creation/deletion distances - these attributes are unique to each set.

Since there is no 'discontinue traffic manager' function, one can be implemented by defining an input set with no traffic (an empty input set). An appropriate name can make the purpose of the set clear: PauseTraffic, Stop_TM, etc.

==== Sample Traffic Manager Set ====
This is a sample traffic manager set that can be pasted into a scenario file after the HCSM VehFail section. Be sure to paste '''after''' the HCSM VehFail end tag ('''&&&End&&&''') in your scenario file.

'''Note:''' A scenario file may contain only '''one''' Traffic Manager section.

There are two input sets in this example; note how they contain different vehicles and different settings from each other.

<span style="color:#2a4b8d">HCSM TrafficManager
GroupName "Traffic Manager"
HCSM InputSet
Name "ONE"
MinDensity 3.0000000E-002
MaxDensity 7.0000000E-002
MaxObjects 9
CreateDist 2.0000000E+003
DeleteDist 3.0000000E+003
AbsDeleteDist 3.4000000E+003
RunFreq 1.0000000E+000
SolWeights "cargill_semi_peterbilt_blu:2" "cargill_semi_freightliner_red:1" "cargill_semi_peterbilt_yel:3" "DumpTruck_org:3" "semi_peterbilt_yel_Walmart:2" "Cadillac_Escalade:10" "Ford_F150Xcab:15" "Saturn_Vue:10" "FordTaurus:15" "Escape:15" "DumpTruck:2"
&&&&End&&&&
HCSM InputSet
Name "TWO"
MinDensity 1.0000000E-002
MaxDensity 3.0000000E-002
MaxObjects 4
CreateDist 2.5000000E+003
DeleteDist 3.3000000E+003
AbsDeleteDist 3.5000000E+003
RunFreq 1.8000000E+000
SolWeights "Taurus2011:12" "Cadillac_Escalade:16" "Ford_F150Xcab:24" "Saturn_Vue:14" "Escape:6" "Deville:24" "Audi:4"
&&&&End&&&&
&&&&End&&&&
</span>

====='''Managing Traffic Manager Input Sets'''=====
During simulation, Input sets are controlled by the action '''Use Traffic Manager Set'''. A set name must be provided for this action to work.

===== Traffic Manager generated Traffic=====
ADOs will populate the road network around the XD based on the parameters of the Input Set. Typically traffic is removed from the scene shortly after passing the XD. This is visible in the rear view mirror. There is currently no way to adjust this delete distance.

====== Traffic Manager Traffic on 2 lane freeway======
Traffic will prefer to be in the XD lane, so ADOs created in any other lane will tend to veer into the XD lane. On a divided highway, traffic is generated moving with the XD.

====== Traffic Manager Traffic on 2 lane road======
Traffic is generated in the oncoming lane. In some cases traffic may be generated then immediately removed in front of the XD.

===How to Control Objects in the Scene during Simulation ===
"Set and forget" options on simulation entities only require the scenario author to "initialize" the element to a desired setting and then it is left alone during simulation.

Controlling objects dynamically during simulation requires the scenario "talk to" each object with a scenario action. This section describes how each scenario object type can be controlled during simulation within a scenario.

All models used in ISAT are listed within the Scenario Object Library (sol2).txt files. Terrain switch names are displayed in the ISAT workspace.

All model switches are listed within the NadsMiniSim_x.x\bin.x64\ModelList.txt file.

'''Note:''' The diligent reader will note discrepancies in model names between the sol2 and ModelList files. This is because the ModelList file contains actual file names, and the sol2 files define a "name label" for models that may, or may not, be the actual model name. Objects are linked between the sol2 and ModelList files through the ModelID/CigiID records. These values will match between sol2 and ModelList files, but IDs are not necessary at this time for scenario authoring purposes.

Complicated object names can be retrieved from the LRI file that was used to build any scenario file; each BLI is preceded by an LRI. The LRI contains all of the terrain models that will be present in ISAT. These are typically speed limit signs, traffic signals or other features that may be controllable.

'''Note:''' this file may not be present for the Springfield.bli file.

An alternative is to capture a screenshot of the ISAT workspace with the element name string showing. By default ISAT reports the name of any objects when the cursor passes over the object, as shown in this example:

[[File:2021-10-27_08h50_14.png|caption =Object Name Screenshot | 400px]]

{|class="wikitable"
|+ Controlling Scenario Elements During Simulation in Scenario
!Date
!Nads miniSim version
!Object Type
!Scenario Action
!Who To Affect
!Value
!Notes
|-
| Oct. 28, 2021
|2.3
|-
|
|
|Static Object (terrain)
| SetDial > StaticObjManager > Set Option1
| StaticObjManager
| switch name : switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
|Static Object, multiple options
| Set Switch
| Name of element
| switch option
|-
|
|
|Obstacle, multiple options
| Set Switch
| Name of element
| switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
| DDO, multiple options
| Set Switch
| Name of element
| switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
| ADO
| Set Dial > ADO > VisualState
| Name of element
| Limited to options present in ISAT
|-
|
|
| Traffic Signal
| Traffic Light
| Assign action to element
| Target state
| Target state must exist within the Traffic Light Manager intersection timing table for the specified signal

|}

===How to Control Simulated Vehicles===
The scenario author can control simulated vehicles by controlling the environment:
#change a traffic signal to cause an ADO to stop or start at intersections
#affect other ADOs to cause a target ADO to respond
# assign a path for the ADO to travel

Direct control:
*Lane related:
:Set button > ADO > ChangeLane, Turn, ProjectAndResetLane

*All other controls:
:Set Dial > ADO > AudioState, ForcedLaneOffset, ForcedVelocity, InhibitLaneChange, LaneChange, MaintainGap, TargetVelocity, VisualState, AudioState

====How to Change ADO Velocity====
ADO velocity can be changed using the SetDial action:
:SetDial > ADO >

:ForcedVelocity
:ForcedVelocity using an expression:
# match external driver speed
expr % OvVel(0) %
# multiply external driver speed
expr -1 9 %ReadCell('OvVelLocal',1)*1.75 %
:TargetVelocity

Indirect Control (dependent on other scenario element):
:MaintainGap

====How to Link ADO Velocity to Something Else====
ADOs velocity can be linked to other ADOs or the external driver using the MaintainGap (MG) action.

SetDial > ADO > MaintainGap

When using a traffic cloud containing multiple ADOs, each ADO in the cloud needs a unique MG. IF multiple ADOs have the same MG settings they will attempt to satisfy their parameters and likely oscillate position in a visually obnoxious way.

===How to Author Loop Scenarios===
A scenario created on a loop road network operates very much like any other scenario, with the exception that it is likely to require tracking the number of times through the loop, or to present scenario events to the external driver depending on each loop context.

[[File:loop_traffic_creation_01.png|400px]]

The simplest method of tracking loops is the use of a loop counter variable. This variable can be set by the driver "stepping onto" a roadpad trigger or it can be initialized through the use of a timer or expression, with increments managed by a roadpad trigger. Each time through the loop increases the loop count variable.

Thus it becomes possible to create events for each loop based on the loop counter variable, typically through an expression trigger.

Loop management triggers

[[File:loop_management_02.png|400px]]

Loop management trigger detail one

[[File:loop_management_vars_02b.png|400px]]

Loop management trigger detail two

[[File:loop_management_3.png|400px]]

====Creating Loop Specific Traffic====
Creating loop traffic is slightly more complicated due to the number of objects to be created and potentially the size of the actual loop. A small loop is installed with the Nads miniSim as simple_rural1 or simple_rural2. Each is a loop road network with two signed 3-way intersections.

Loop specific traffic can be created through the use of a variable (i.e., LoopCount) or within the roadpad trigger that is incrementing the loop count variable. Both methods will incorporate a '''Create Action''' that creates the required elements.

===How to Change Environment Settings===
The scenario author can define global or localized environment conditions.

1. Insert >> Environment Conditions >> <chosen condition>

2. Define a region where the environment condition is active:
:LMB to define polygon points
:RMB to exit point entry mode

[[File:env_condition1.png|400px]]

Choosing an environment condition

[[File:env_condition2.png|400px]]

Environment region defined and parameters panel shows available options

NOTE: The environment condition boundary is a discrete threshold. Condition A will be on one side of the threshold. Immediately after crossing the boundary, condition B will be displayed.

===How to Fade an Environment Condition===
To fade gradually between two conditions requires the use of an expression that continually monitors the desired condition and sets a few variables based on the results.

Examining the demo scenario is the best way to look 'under the hood' to see exact command syntax and values to be used.

[[File:env_fade.png|400px]]

Note: this approach has been used for fog and visibility. It is unknown how it might work with non-visibility conditions such as precipitation and wind.

*From the scenario demo_visibility_transition.scn

[[File:env_fade_schematic.png|400px]]

'''Note:''' although the example above uses an environment condition boundary, '''it is possible''' to omit the defined region, retaining all commands and the scenario will still function. However, without the environment region, it becomes more difficult to determine where conditions are different from the standard settings.

===How to Control a Cab Instrument Panel icon===
In order to control the instrument panel, there are 2 requirements:
The specific cab used for the scenario
The specific control (switch) to be manipulated
The action for addressing the instrument panel is '''ChangeCabSetting'''

Instrument panel models are located in NadsMiniSim_x.x\data\Visuals\Instruments
These files are in OpenFlight format. Any 3D editor capable of reading or importing OpenFlight can be used to review these files. NADS uses the Presagis product Creator[tm].

An alternative method to inventory switches is to use the the '''buildscl.exe''' tool. To run the tool, open a CMD window to the IP folder location above, then run the command:
buildscl <input_file.flt><Enter>.
<input_file.flt> is the name of the file to process, without the '<>' characters.
<Enter> means to press the Enter key,

The result will be in a new file ending with .scl. This is a text file, and can be opened in a text editor or you can use the shell utility '''more''' to view the file contents:

more <input_file.scl> | grep switch<Enter>

An example for the malibu cab is shown below. .

switch s_LowWasher 0
switch s_Cruise 1
switch s_LeftTurn 2
switch s_RightTurn 3
switch s_FwdCollisionWarn 4
switch s_BlindSpotWarn 5
switch s_LaneDeviationWarn 6
switch s_RearCollisionWarn 7
switch s_HighBeamHeadlights 8
switch s_SeatBelt 9
switch s_UpArrow 10
switch s_Airbag 11
switch s_CheckEngine 12
switch s_CheckGuages 13
switch s_ABS 14
switch s_Brake 15
switch s_LowFuel 16
switch s_Gear 17

These controls may be accessed directly in scenario using the ChangeCabSetting action.

'''NOTE:''' Some functions such as Cruise, Gear, High beam headlights, Blind spot, collision, lane deviation warnings are '''normally''' controlled not by direct access as described here but by hardware mechanisms/buttons.

'''NOTE:''' For altering cab instrument panel operation it will be necessary to modify the OpenFlight model to include the desired funationality; for example, instrument panel blanking is not build into the model but can be added by editing the cab instrument panel model file then installing the modified file into miniSim.

===Scenario Hints===
The total number of scenario elements active at any given time can affect simulator performance:

Total number of active elements
*vehicles (ADOs), triggers, animations, etc.

Object management
*Use paths to shift ADOs away from the driver route of travel as they turn off the route
*reduce the number of vehicles in traffic cloud surrounding external driver
*use creation radius to limit the number of active elements, and to remove elements after the driver has traveled beyond the creation radius

[[File:creation_radius_1.png|400px]]

Creation radius works by activating the scenario element only when the driver is within the radius. The scenario element is created when the driver enters the creation radius, and is deleted after the driver leaves the creation radius.

Exploit environment to reduce object load

*Use curves, hills, intersection corners to mask objects

Object deletion
*Remove objects when no longer needed

When creating dynamic elements, create them as close to where they are needed as possible.

====How to Determine When ADOs are Visible to the External Driver====

Some development/setup testing may be needed to determine precise location/distance/speed; i.e., locating ADOs for a freeway ramp merge event where the external driver is merging onto the freeway with other ambient traffic present.

Unless the purpose of the event is to study driver behavior at the merge, ideally the scenario will be authored to have ambient traffic on the freeway but not to present a conflict at the merge for the external driver.

A straightforward way to determine where the ADOs are first visible to the driver is to mock up a scenario placing colored ADOs along the freeway with a velocity of 0. This will ensure the ADOs remain stationary while the scenario author determines where they are first visible to the external driver.

Place the start position/external driver far enough up the ramp to be a reasonable test for the actual scenario.

As you drive the ramp, see which ADO is first visible to the driver. Place ADOs just out of view (upstream) of that location.

[[File:merge_hint.png|400px]]

'''NOTE:''' use test vehicles of the same type and character as the intended scenario vehicles. For example, do not use a sedan test ADO for a larger vehicle (SUV, bus, dump truck). Doing so will invalidate the visibility test, because a larger ADO will be visible over a longer distance than a small ADO.

[[File:ramp_vis_1.png|400px]]

At the scenario start location, ADOs in front of the Coke truck are visible. Note how the larger vehicles are more obvious at this distance.

[[File:ramp_vis_2.png|400px]]

The driver has traveled onto the ramp. At this point, the last ADO visible to the driver is still the Coke truck.

[[File:ramp_vis_3.png|400px]]

As the driver travels farther down the ramp a small ADO is visible behind the Coke truck.

The answer to the question '''When is an ADO visible?''' is thus:
#It depends on how large the ADO is
#Small ADOs can be placed at the location of the red ADO behind the Coke truck.
#Large ADOs may need to be placed farther back (behind the red ADO). This test is inconclusive, but based on the terrain it seems likely that large ADOs would need to be placed at least at the green ADO location (behind the Coke truck).

Creating small ADOs at the green ADO location when the external driver is located at the ramp position in 3 travelling at the same speed as the external driver should arrive at the merge slightly ahead of the driver (because the curved ramp is longer than the straight freeway).

'''NOTE:''' ADO size, ADO color, time of day and visibility settings affect ADO visibility.

====How to Position Objects Precisely using '''Place Object At..'''====

ISAT does not support true precision because it is not currently possible to 'dial in' a position as is typical in 3D modelling tools, but there is a way to approximate precision in cases where a consistent measurement is desired.

In the following example a number of roadpad triggers are placed relative to the location where a roadway enters an intersection. This is a discrete boundary within the simulation world as shown in ISAT.

There are two methods of placement possible:
# Measure the desired distance (CTRL+Shift+RMB, drag); take note of the coordinates updating in realtime and make a mental note of the desired location.
#Place an object (ADO or static object); use the Place Object At.. feature from the context menu when you RMB on a scenario object.
Using this method you can specify a distance - positive numbers move the object downstream/forward, negative numbers move the object upstream/backward.

'''Note:'''If the distance is significant and extends over an intersection, ISAT may produce unexpected and undesired results such as re-starting the measurement from the closest upstream intersection, thus placing the object where it was not intended.

In the following example, Place Object At.. is used to specify a point 50 feet upstream from the road/intersection border.

[[File:precision_placement_1.png|400px]]

A roadpad trigger has been positioned near the area of interest. Any existing roadpad is deleted from the trigger.

[[File:precision_placement_2.png|400px]]

An ADO is used as a marker object inserted temporarily into the scenario. Any convenient object may be used.

'''Note:''' large objects such as ADOs may be less precise than small objects such as the Traffic cone, but is generally easier to access in the ISAT interface unless you have created a script for cone objects.

[[File:precision_placement_3.png|400px]]

RMB on the ADO to access the Place Object At.. request dialog. Only numbers are valid entries.

[[File:precision_placement_4.png|400px]]

The desired distance is entered into the Place Object At.. request dialog. ISAT will then require you to select the object you wish to move using LMB.

[[File:precision_placement_5.png|400px]]

ISAT moves the selected object by the distance you specified.

[[File:precision_placement_6.png|400px]]

Use the ADO CG (model center) to place the start of the road pad.

[[File:precise_placement_7.png|400px]]

Remove the ADO marker and save your scenario.

==Scenario Testing and Debugging==
The primary way to test and debug scenarios is using ISAT rehearsal mode.

'''NOTE:''' the external driver during rehearsal is a simulation. You have limited control over the simulated ownship:
#change speed
#change lane

ISAT has two rehearsal dialogs:
#abbreviated (standard) dialog
#advanced (extended dialog)

===How to change to the advanced rehearsal dialog===
Often it is necessary to control the ownship during rehearsal. The ownship controls are located in the advanced (extended) rehearsal dialog.

ISAT will show the Advanced dialog the first time rehearsal mode is activated. All additional activations show the abbreviated dialog.

TBC abbreviated dialog

To use the Advanced dialog, LMB the Advanced button.

TBC Advanced dialog

===How to change ownship speed during rehearsal mode===
After entering rehearsal mode:
#click the Play icon (start the rehearsal)
#pause.
#adjust ownship speed
#toggle pause off (resume rehearsal)

===How to make ownship lane change during rehearsal mode===
After entering rehearsal mode:
#click the Play icon (start the rehearsal)
#click the desired Lane Change (left or right)

===How to Use Audio in your Scenario===
Scenarios play audio sounds and messages through a write to cell action: '''SCC_Audio_Trigger'''

Use of audio in a scenario typically requires both a write to cell and a 'clear action' that writes a zero (0) to SCC_Audio_Trigger in order to 'clear the channel'. The 'clear' action can happen before or after playing a sound; choose one method and be consistent in your scenario authoring.

Failure to 'clear the channel' or '''not''' writing a value of zero can result in no audio being played for subsequent write to cell SCC_Audio_Trigger actions.

The following shows how this looks in scenario when executed from a roadpad trigger (RPT):

[[File:audio_scn_A.png|400px]]

The above diagram is shown below in text format:

HCSM RoadPadTrigger
GroupName "WindGust_Audio"
ByTypeSet "ExternalDriver"
NthFromStart 0
NthFromEnd 0
VehicleAhead 0
VehicleBehind 0
LongComment "This is a wind gust event"
ShortComment " "
ActvDel 0.0000000E+00
CrRad 0.0000000E+00
Debounce 0.0000000E+00
FireDelFrames 0
Lifetime 0.0000000E+00
Name "RPT_WG_6"
OneShot 1
Priority 0
SeqAct 1
Position 6.7165800E+04 6.0419215E+03 0.0000000E+00
DrawPosition 6.7165800E+04 6.0419215E+03 1.1308095E-317
Path "R:r3_62700_7920:0[3033.04:3245.46]"
HCSM LogData
Comment "LS1=8"
Delay 0.0000000E+00
InstigatorSet 0
Stream 1
StreamVal 8.0000000E+00
&&&&End&&&&
HCSM WriteCell
Comment "Play_Audio"
Delay 2.0000000E+00
InstigatorSet 0
CellName "SCC_Audio_Trigger"
CellData "63000"
CellType 2
CellVar 0
&&&&End&&&&
HCSM WriteCell
Comment "clear_audio"
Delay 0.0000000E+00
InstigatorSet 0
CellName "SCC_Audio_Trigger"
CellData "0"
CellType 2
CellVar 0
&&&&End&&&&
&&&&End&&&&

===How to Add Custom Audio Instructions to miniSim===

''' Please note: Custom audio 'instructions' for a scenario should be added to the instructions.txt file.'''

These are sounds that are played in scenario, typically as directions for the minSim driver.

Adding custom audio files requires the following procedure:

1 Exit miniSim - changes to the miniSim configuration should happen only when miniSim is not running.

2 Copy the audio .wav file to:
:C:\NadsMiniSim_x.x\data\sound\DefaultCabSound\Instructs

:Edit the file instructions.txt in that same folder.

3 Add an entry to instructions.txt to register your audio file in accordance with the following layout using the existing entries as a template:

:Unique_ID Filename Normalized_Volume

:Unique_ID is whatever unique number you assign to your file.

:Filename is the name of your .WAV file.

:Normalized_Volume is the volume your audio file should play, where 0.00 is silence and 1.00 is maximum volume.

'''NOTE: Remove all spaces in your audio filename.''' If needed, use the underscore character instead of spaces.

===Troubleshooting Custom Audio Additions===
After installing new .wav files and adding them into the audio configuration file '''instructions.txt''', if the audio file does not play:
*Check the Audio Engine window while miniSim is still running. The Audio Engine will display file errors,.
*If Audio Engine does not display a message similar to: Audio Engine loaded normally, scroll through the window messages and look for any .wav or load error messages.

==Re-use of Scenario Elements==
Scenario authoring can be an intensive undertaking. It makes sense therefore to leverage your development efforts by re-using scenario elements where possible.

ISAT provides a number of ways to re-use scenario elements:
# copy/paste
# external references
<span style="color:#ac6600"># exporting elements as '''groups'''</span>
# isc scripts

Each of these methods have their strengths and weaknesses.

===copy/paste===
The simplest method to re-use scenario elements among different scenario files is copy/paste. This is possible for most scenario elements* even if the source and destination roadmap/BLIs are radically different.

[[File:copy_paste.png|400px]]

It is also possible to copy an ISAT element from one scenario to another as '''TEXT''' by selecting the element and using the windows copy shortcut CTRL-C, then open a text file and paste it using the windows paste shortcut CTRL-V.

'''NOTE:''' Traffic sources are '''not''' portable using copy/paste.

'''NOTE:''' Not all elements can be copy/pasted. Elements created from a Create Element action cannot be copied - it is necessary to select the parent element and copy that instead.

[[File:copy_paste2.png|400px]]

In the above diagram, elements at '''B''' and '''C''' cannot be copied/pasted because they have been created by element '''A'''. It is necessary to copy the element at '''A''' instead. If only the elements at B are needed, the best method will be to copy/paste as Text.

'''NOTE: ISAT will not copy elements containing road coordinates (elements with a path) to a scenario that does not share the same BLI as the source (copy from) scenario.'''

A partial solution to such cases is to remove the path first, copy the element, paste into the destination scenario, then re-create the path manually.

===External Reference===
An external reference scenario is intended to be re-used by multiple 'parent' scenarios. The effort of authoring objects is thus leverages across multiple files, without needing to re-create the same elements more than once.

[[File:re_use_xref_1.png|400px]]

Common uses of external references include traffic, traffic signal operation, traffic sign appearance or other environment features which have multiple appearances (billboards, some tile related scenery, etc).

NOTE: Multiple external references are possible; but because objects are categorized by group, it is not entirely necessary.

For example, one external reference file contains traffic, another contains signs. These two external reference scenarios could be combined into one file.

[[File:xref_overview2.png|400px]]

NOTE: Each group defined must be unique across all files: parent and external reference files.

In order to use an element in an external reference scenario, it is necessary to define and assign a group to all elements that you wish to control from the parent scenario.
At this time there is no visual hint in ISAT to indicate if a group has been assigned to an element or not - each element has to be confirmed independently.

However, a properly authored external reference element cannot be edited within the parent scenario (after you have done Add Ref. to use the external reference file).

An alternative is to insert groups using a text editor with macro capability, or to use a program or external script to make the necessary changes.

'''NOTE:''' If the external reference file is for object contained in the parent scenario (for example, an external reference file containing traffic signals with a group defined) it is still necessary for that group to be defined in the parent file.

With traffic signals, ISAT requires ONE explicit group reference, which will be contained in the HCSM TrafficLightManager block as shown below. If you require the use of traffic signals in an external reference, the recommended way to do this is through ISAT because then it manages the group assignment for you.

==== HCSM TrafficLightManager scenario block ====

HCSM TrafficLightManager
HCSM CLG
IntrsctnName "I1_40260_4620"
Duration 2.0000000E+01 3.0000000E+00 1.0000000E+00 2.0000000E+01 3.0000000E+00 1.0000000E+00
GroupName "TrafficSignals"
LightName "s_signal_r1_LTRN_40260_4620_270"
LightName "s_signal_r1_RTRN_40260_4620_270"
LightName "s_signal_r2_LTRN_40260_4620_270"
LightName "s_signal_r2_STRT_40260_4620_270"
LightName "s_signal_r3_STRT_40260_4620_270"
LightName "s_signal_r3_NORM_40260_4620_270"
Pattern "FLTY" "R" "R" "R" "R" "R" ""
Pattern "RTG" "R" "R" "R" "R" "R" ""
Pattern "LTR" "LTR" "LTR" "FLTY" "FLTY" "LTR" ""
Pattern "SR" "SR" "SR" "SG" "SY" "SR" ""
Pattern "SR" "SR" "SR" "SG" "SY" "SR" ""
Pattern "R" "R" "R" "G" "Y" "R" ""
&&&&End&&&&
&&&&End&&&&

'''NOTE:''' At this time there is a known issue using the write cell '''SCC_Audio_Trigger''' action in external references. Although the trigger containing this action can be assigned a group and used as an external reference, audio does not play.

<span style="color:#ac6600">'''Because ISAT updates static object positions (elevation) to the terrain (roadway) when the scenario file is saved, the best way to use a custom elevation is to put such objects into an external reference file in order to isolate those objects from normal scenario editing.''' </span>

====Define a Group====
<span style="color:#ac6600">'''NOTE:''' ISAT 1.8.5 and 1.8.6 currently do not work properly with group files. These versions will not import objects within a group file. There is a workaround which involves the following process, but instead of reading the saved group file into a scenario the workaround requires editing the scenario as text and inserting the objects within the group file into the scenario.</span>

RMB on the element and choose from the context menu: Group >> New Group (if this is a new group) or Group >> (choose an already defined group).

'''NOTE:''' The first time you create a group for an object, ISAT will automatically assign the group to that object.

After defining and assigning groups to the scenario elements needed, save the scenario file then close it.

Open or create the parent scenario file and use the Add Ref. button at the bottom of the ISAT window to select your external reference scenario. After you choose a file ISAT will present you with the groups found in that scenario. Choose the groups you with to include and click the 'Okay' button. Click the Add Ref. OK button to complete the process.

Currently import group file operations are not working, but it is possible to insert the group file content (all HCSM StaticObjects) into a scenario manually by using a text editor to copy text from the group file and paste that into a scenario file into the HCSM Static Object section of the scenario file.

[[File:group_text.jpg|400px]]

'''NOTE:''' ISAT does not enforce logic on your external reference authoring. If you add references to scenarios that do not share the same roadmap/BLI as the parent scenario, it is likely that elements will be placed at the origin (in cases where the external reference roadmap contains roadways not found in the parent) if it even loads.

===Exporting ISAT Elements as Groups===
Transferring ISAT elements among scenarios can be accomplished using groups. As with external reference scenarios, one or more groups must be defined and then assigned to one or more elements.

After defining and assigning groups select the group for export using the Group select drop-down located at the lower left corner of ISAT. Choose a group to export and then click the 'Save Group' button. Save the file.

TBC insert graphic sequence diagram here

'''NOTE:''' If you cannot locate the group file in the folder specified, check the ISAT install\data folder. This is typically:

C:\NADS\ISAT\data

===Group File Contents===
The group file is a text file and can be opened or edited in a text editor.

The following is a group file containing one ADO. Note the GroupName line near the bottom:

Header
LriFile "_dev.bli"
LongComment "this is a test group export"
ShortComment "this comment was left empty"
&&&&End&&&&
HCSM Ado
RunMode "eREMOTE_CONTROL"
RandomSol 0
Name "Ado1"
DynModel "Non Linear"
LogFile ""
LatOffsType 0
CreateRelLatInFeet 0
CreateRelOffsLonUsingExpr 0
CreateRelOffsLonExprStr ""
AutoControlBreakLights 0
AutoControlHeadLights 0
UseReaDel 1
StdToAccType 0
StdToDecType 0
StdToDecVal1 9.0000000E-001
StpToAccType 0
DecToAccType 0
FollowTimeMin 1.0000000E+000
FollowTimeMax 2.0000000E+000
EmergDecClip -1.1000000E+001
Accel2Catch 0
NormVel2Kp 7.0000000E-001
PathSearchDepth 2
LcvFall 1.5000000E+000 2.0000000E+000
LcvFreq 3.0000000E-002 5.0000000E-002
LcvRAmpl 1.0000000E-001 5.0000000E-001
VelCtrlInitMatchOvVel 0
VelCtrlFollowSpeedLimit 0
VelCtrlDistType 0
MaxLatOffset 9.0000000E+000
LongComment " "
ShortComment " "
SolName "Audi"
RoadPos "r1_1320_44220:2:32414.44:0.00"
GroupName "TEST_Group"
&&&&End&&&&
HCSM StaticObjManager
&&&&End&&&&
HCSM DriverMirror
&&&&End&&&&
HCSM IntersectionManager
&&&&End&&&&

===ISC Scripts===
Scripts are an efficient way to automate repetitive and/or complex tasks.

ISAT uses a custom language (ISC) to automate placement and manipulation of scenario objects. Combined with simple direction commands and the capability to navigate a road network, ISC scripts can ask the scenario author for input and prompt for selecting objects.

ISAT installs with some ISC script files. If your version of ISAT contains a data\isc
folder, then your version of ISAT is capable of running scripts. You can create
additional scripts as needed. All scripts located in the data\isc folder will load in ISAT
when ISAT is launched.

You can use these scripts for reference in creating your own custom scripts.

New scripts created during an existing ISAT session will not appear until ISAT is re-
launched.
Scripts that have been edited will not update until ISAT is re-launched.

Unless otherwise indicated, scripts are case-sensitive.

'''NOTE:''' Please do not edit the existing scripts!

Make a copy of any existing script before you make changes. In the event your modified script does not work, you can look at the original file for reference.

ISC scripts are located on the ISAT Elements widget. Custom isc scripts are located after the 'Events' separator.

Using an ISC script involves LMB + dragging the desired script onto the workspace. In some cases the script will ask for inputs.

ISC can be also used to create an entire event, thus ensuring that all events created will be entirely identical in terms of settings and locations for all created elements.

ISC scripts are text files located within the ISAT installation data folder. Only the custom ISC scripts are located in this folder. This is typically:

C:\Nads\Isat\data\isc

====Icon Files====
Script icon files are 8-bit windows icon files (file.ico). GIMP is capable of exporting valid ico files. To create an ico file, scale it to 32x32 pixels. Export the file as .ico to the isat\data\isc folder.

In order for a script to use an icon file, both files must exist in the isat\data\isc folder.

====ISC Script Examples====
This section contains example scripts with notes.

'''Rotate sign'''

.Name SetSignRotation
.Icon SignRot.ico
Static sign
Select(sign,"Please Select a Sign")
sign.SetAngle(Anchor)
.End

'''Place Multiple Static Objects (TrafCone)'''
The following script asks the scenario author for number of cones to generate, position and offset values and then generates the objects.

A breakdown of the script follows the code block below.

.Name Cones
.Icon cone.ico

Block coneBlock %%%
HCSM StaticObject
IsNewObj 1
Name "Cone_xxx"
SolName "TrafCone"
Option 0
Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
&&&&End&&&&
%%%
Static cone;

Value dist1
Value numberOfCones
Value distance
Value variablePart
Value randDistance
Value speed
Value Count
Value LatOffset

Block tempBlock
tempBlock = coneBlock
Count = 1
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

Ask(numberOfCones,"How many cones?" )
Ask(dist1,"Distance between cones?" )
Ask(LatOffset,"How much offset?" )

Position posRp
Position tempPos
posRp = Anchor
numberOfCones = numberOfCones

Repeat numberOfCones
posRp.GoForward(dist1)
# test comment
tempPos = posRp;
tempPos.SetOffset(LatOffset)
cone.RoadPos = tempPos
cone.Clone
Count = Count + 1
tempBlock = coneBlock
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

End
.End

====Script Breakdown cones.isc====

This section contains a description of the elements used in the script. The script segment is followed by a brief text description.

This script places a number of object copies (TrafCone) using information provided by a user.

.Name Cones
.Icon cone.ico

The first line contains a keyword '''.Name''' followed by the name of the script. This is the name that ISAT will use on the Isat Elements widget for the script. Note the script name does not have to be the same, but it is good computing practice.

The second line begins with the keyword '''.Icon''' followed by a file name. This file must exist in the ISAT\data\isc folder (accompanying the script file). This is the icon ISAT will use for the script.

Block coneBlock %%%
HCSM StaticObject
IsNewObj 1
Name "Cone_xxx"
SolName "TrafCone"
Option 0
Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
&&&&End&&&&
%%%

This is the data section of the script, which is defined using the keyword '''Block'''. A block name follows the keyword, and the data start is defined with '''%%%'''.

The HCSM StaticObject section has been copied from a scenario. In this case, a static object was placed into the workspace and then copied into a text file.

Name "Cone_xxx"
Note: the object name contains a marker that can be used to programmatically name instances of the object:

SolName "TrafCone"
This line begins with the keyword '''SolName''' followed by the name of the object as it is defined in the sol2.txt file.

Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
The Position of the static object will update when the script activates and instanced objects are placed in the workspace.

Static cone;
This line begins with the keyword '''Static''' followed by a variable name.

Value dist1
Value numberOfCones
Value distance
Value variablePart
Value randDistance
Value speed
Value Count
Value LatOffset

This section defines variables with the keyword '''Value''' followed by variable names. Using descriptive names is better than generic names. From the variable list it already seems clear what the programmer cares about: number of cones and distances.

Block tempBlock
tempBlock = coneBlock

This section defines a block using the keyword '''Block''' followed by the variable name.

The next statement replicates coneBlock into tempBlock.

Count = 1
Initialize the value of the variable Count to 1.

tempBlock.Replace('xxx',Count)
The built-in '''Replace''' function changes the string 'xxx' to the value of the variable Count.

cone.SetBlock(tempBlock)
This statement creates a block using the function '''SetBlock''' called cone, and copies the contents of tempBlock into it.

Ask(numberOfCones,"How many cones?" )
Ask(dist1,"Distance between cones?" )
Ask(LatOffset,"How much offset?" )

This section asks the user for input and puts that information into variables:
*Number of cones
*Distance between cones (dist1)
*Lateral offset (calculated from lane center)

Position posRp
Position tempPos
posRp = Anchor
numberOfCones = numberOfCones

This section contains position variables and assigns the value of numberOfCones.

Repeat numberOfCones
posRp.GoForward(dist1)
# test comment
tempPos = posRp;
tempPos.SetOffset(LatOffset)
cone.RoadPos = tempPos
cone.Clone
Count = Count + 1
tempBlock = coneBlock
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

This section is where the work happens. Reading from the top, this section is contained within a loop defined by the keyword '''Repeat'''. The number of times to repeat follows in a variable numberOfCones.

'''posRP.GoForward()''' is a built-in function to take the current position and shifts it forward by the amount specified in the dist1 variable.

#test comment
This is a comment defined by starting the line with the comment keyword '''#'''

tempPos = posRp;

Assign the value of the variable tempPos to the value currently in '''posRp'''

tempPos.SetOffset(LatOffset)

Another built-in function or attribute to the position element which defines a lateral offset (distance from the lane center). This statement places the value of a variable LatOffset into the offset element of the tempPos variable, using the operand '''SetOffset'''.

cone.RoadPos = tempPos

This statement sets the road position variable for cone to the value in the variable tempPos.

cone.Clone

Duplicate the block cone using the operand '''Clone'''

Count = Count + 1
Set the value of the variable Count to the value of Count plus one. This statement increments the value of Count for each loop processed.

tempBlock = coneBlock

Create a new block tempBlock by setting it to the content of coneBlock.

tempBlock.Replace('xxx',Count)

Use a built-in function to '''Replace''' the string 'xxx' with the value of the Count variable

cone.SetBlock(tempBlock)

Use the built-in function '''SetBlock''' to place the modified tempBlock (modified by the string replacement command earlier) into the cone block.

End
.End

The last two lines terminate the loop and the script, respectively.

====How to Create an ISC Script====
The simplest way to create an ISC script is to find an existing script that does something similar to your desired behavior and edit it.

=miniSim Simulation Data=
MiniSim runs on shared memory:
*miniSim is a collection of programs
*shared memory is a commonly accessed 'blackboard' list: a Cell and a Cell Value
:The DAQ file is a snapshot of this 'blackboard' memory for every frame.

*Scenario can write to cells added by the scenario author
:-i.e., for custom hardware or tasks/events

'''NOTE:''' Custom cells must be present in the collect file (NadsMiniSimCollect.cec) '''prior to''' simulation in order for the custom cells to be present in the DAQ.

NOTE: The cell type defined in the collect file must be followed, or garbage values will be used

Use of a DAQ file implies that at some point, data reduction will be needed.
Data reduction: the process of distilling measures from the DAQ file, i.e.
*Event definition
*SDLP
*Average headway

==What is the Difference? Cell vs. Variable==
*A Cell is a pre-created “slot” in shared memory
:-Specified in the .CEC collect file,
:-Saved in the DAQ file,
:-Can be sent to custom programs;
:-Can create & use custom cells;
*A Variable is a name value internal to the scenario
:-NOT saved to the DAQ file,
:-Can use to track items in the scenario
:i.e., how long the driver has been exceeding the speed limit
:-Initialize conditions in the scenario.

=== Variables Save ===
Variables can be saved to disk as a single value text file (ie, multiple values over time are not supported) through the use of a '''Store Variable''' action:

[[File:2021-08-23_13h28_49.png|400px]]

The file is stored in the miniSim_x.x\bin.x64 folder.

'''NOTE:''' The name of the file is defined within the Store Variable action. '''Care must be taken to save variables to unique file names''' in the case of multiple scenarios running on miniSim at the same time (if they share common variables), as would be the case if triggers are copied from one scenario to another.

=== Variables Restore/Read ===
Variables can be read into the simulation through the use of a '''Load Variable''' action:

[[File:2021-08-23_13h32_39.png|400px]]

==Cell Types==
This is a partial list of cell types.

*CFS = control feel subsystem (steering wheel, pedals)
*CIS = control information subsystem (gear, turn signal, buttons, etc)
*TPR = terrain profiler for terrain queries
*VDS = vehicle dynamics for accelerations, position, engine speed, speed, etc.
*ACC = adaptive cruise control
*RCM = configuration management for setting variables that affect subsystem configuration (ACC enabled or disabled, for instance)
*SCC = scenario
*SOP = for one time initializations at the start of the simulation.

=='''Data Output Actions'''==

*Write to Cell Actions
:-Write the value of a variable or cell to a cell
:-Write to a custom cell
:-Cannot overwrite another systems output
'''NOTE:''' Although it is possible to write to a different system cell, that value will be over-written on the next frame. Thus it is effectively not feasible nor desirable to do.

'''<span style="color:red">Also Note: the limit for maximum number of write to cell actions that can be performed in one frame is 8.</span>'''

*Set Variable Action
:-Sets the value of a variable
:-Does not have to be created first
:-Not saved in the DAQ unless written to a valid cell
*Logstream
:-Log data action

===Data Output Methods===
Your data is the primary reason for simulation.

1. Default miniSim scenario measures
:- Immediately available

2. Alternate scenario measures (DAQ file)
:- Processed through data reduction

====Default miniSim Scenario Measures====
*Saved to a drive report.txt file
*Saved to the same Location as DAQ files;
:Scenarioname_timedatestamp_report.txt
•Measures calculated overall, and up to 20 Events during drive:
:Collision Count Lane Departure Count
:Maximum Speed Lane Departure Percentage
:Minimum Speed Speeding Count
:Average Speed Speeding Percentage
:Standard Deviation of Speed Average Headway
:Standard Deviation of Lane Position

====Default miniSim Scenario Measures Require Scenario Event Definition====
In order to capture meaningful data into the default miniSim measures, a scenario must be configured properly to define events.

Use the Write to Cell action to activate the default measures.

[[File:2021-07-02_11h02_44.png|400px]]

*At the start of scenario, set:
::SCC_EventStatus =0
::SCC_EventNumber = 0
*At the start of the first event, set:
::SCC_EventStatus = 1
::SCC_EventNumber = 1
*At the end of the first event, set:
::SCC_EventStatus = 0
*At the start of the second event, set:
::SCC_EventStatus = 1
::SCC_EventNumber = 2
*At the end of the second event, set:
::SCC_EventStatus = 0

Continue this pattern; at end of final event, set:
::SCC_EventStatus = 0

====Default miniSim Scenario Measures Sample Report====
The following is an example report for 4 events. Note the remaining events present in the report are all zeroes or -1.00.

[[File:default_measures_report.png|400px]]

===="Alternate" Scenario Event Definition aka Using Logtreams====
'''NOTE: This method is the more typical/standard method for defining events.'''

Defining an event is key to partitioning simulator data into useful sections. Processing these sections is the essence of '''data reduction.'''

These useful sections are partitioned using logstreams and are generally called '''Events''':
*A logstream is a data marker present in the DAQ file
:there are 10 logstreams
:use logstreams to indicate when things happen '''in the data:'''
:at the start of an event; i.e.,
::grab all data where logstream 1 = 100 (example value)
:during a sub-section of an event
:at the end of an event (typically clears to 0)

Logstreams help separate/filter data;
*SDLP is not useful during emergency maneuver events

Logstreams can be useful to debug events;
:marking in the data when triggers fire
:ensuring event counters work; these are typically sequential, so any logstream deviation identifies a problem

*How to define a Scenario Event:

Set logstream values at scenario event start
:during and at scenario event end, set or clear logstream values:
For example:
::logstream 1 for event ID
::logstream 2 for sequencing the event (during/within event)
::logstream 3 for restart number, etc.

*Requires data reduction to fully process drive data
*Does '''not''' support default measures
:unless those measures are used in parallel with the logstream method

*The use of logstreams allows a scenario author to encode event and environment information into the scenario and as a result, into the simulator data stream.

====Example Alternate Scenario Event====
This section contains an example of a scenario that uses logstream 1 to define an event and environmental context.

In the following example, logstream 1 (LS1) is used to:
#define the scenario start, which is also in this example the event start. NOTE: This is not typical.
#when the driver is 805f from the intersection halt line, set a value into LS1
#when the driver is 500f from the intersection halt line, set a '''new value''' into LS1 NOTE: This could also use a different LS than the one used to define your event, i.e., 1
#when the driver activates a roadpad trigger to reset a force velocity (FV) on a lead vehicle

[[File:event_def_LS.png|400px]]

In the following event definition, an expression trigger is used to set a logstream value and execute two additional actions pertaining to the event.

[[File:event_ET_LS3.png|400px]]

====How to Export Data from A DAQ file using ISAT====
ISAT can display and export DAQ data. NOTE: This is 'raw data', not previously processed. This method can be used to test scenarios, confirm or identify data issues.

TBC: example export here

=Terminology & Documentation=
This section contains terminology and references to related documentation.

'''Action''' - the basic scenario element; the basis for creating scenarios. Actions may be executed on scenario elements (dynamic or static), create or remove elements, or the environment (time of day, visibility) or the simulated cab instrument panel.

'''ADO''' - Autonomous Dynamic Object; self-controlling to a degree.

'''Cell''' - Data elements that are recorded to during a drive; some cells may be used by the scenario author. Custom cells may be added to miniSim.

'''Event''' - anything significant that happens during a drive where the driver condition or response is desired to be identified in the drive data. Can be isolated from general driving through default measures or logstreams.

'''ISAT''' - Interactive Scenario Authoring Toolkit; used to create scenario files for use on the NADS facility or miniSim simulators.

'''ISC''' - ISAT script file.

'''Scenario''' - The simulation experience during a drive; also known as a scenario file, which contains all instructions to the elements within a simulator drive.

'''SDLP''' - Standard deviation lane position

'''SOL''' - Scenario Object Library; objects that are available to ISAT during scenario authoring must be present within the sol2.txt or an auxiliary sol2 (sol2_aux.xxx.txt) file.

'''Trigger''' - A scenario element that contains actions to execute during simulation. All triggers share the same actions, but execution depends on the trigger type.

'''TTA''' - Time to arrival.

'''TTC''' - Time to collision.

=Reporting ISAT & Scenario Issues=
*How to report ISAT & scenario issues:

When reporting issues with scenarios it is helpful to provide as much information as possible.

This often includes scenarios (including any external reference files) and the .LRI file used by the scenarios, screenshots or video that demonstrate the issue being reported and relevant DAQ files. It can be very helpful to include coordinate information with the screenshot or video.

The .BLI file is created from the .LRI and is much larger than the LRI so it may be more convenient to send the LRI file. NADS staff can re-create the BLI file from the LRI.

Some graphics anomalies may be issues with the tile model and not a scenario or miniSim problem. These include:
#white block shapes in the environment
#gaps or missing geometry; i.e., holes
#improper lighting (dark features present during the day)

If these issues happen on a custom roadmap/database world, please include the TMT .mos file as well so NADS can re-construct your environment.

==How to contact the NADS miniSim team:==

email [mailto:miniSim-Support@uiowa.edu minisim support]

[mailto:andrew-veit@uiowa.edu Andrew Veit]
Director of NADS miniSim

[mailto:joseph-meidlinger@uiowa.edu Joseph Meidlinger]
Program Coordinator NADS miniSim

[mailto:oscar-hernandezmurcia@uiowa.edu Oscar Hernandez Murcia]
MiniSim Application Programmer/Analyst

[mailto:chris-schwarz@uiowa.edu Chris Schwarz]
Data Reduction & Vehicle Dynamics

[mailto:shawn-allen@uiowa.edu Shawn Allen]
TMT, Modelling & Support

==How to check what BLI file is used by a scenario==

#You can edit the scenario in a text editor; near the top of the file will be a line starting with '''LriFile''' followed by the name of the BLI file in double quotes.
#You can use '''grep''' to inventory single or multiple scenarios:
:grep bli <scenario file/s>
:A partial listing is shown in the example below. NOTE: The files shown will likely be different on your PC:
C:\NADS\Isat\data\training.demo_scn>grep bli *.scn
Demo_Expression_Lead_Vehicle_Variables.scn: LriFile "simple_rural.bli"
Demo_Expression_Trigger_to_Lead_Vehicle.scn: LriFile "simple_rural.bli"
Demo_HUDD.scn: LriFile "simple_rural.bli"
ISAT-Samples-Avoid.scn: LriFile "esc_dry_05.bli"
ISAT-Samples-Right-Incursion.scn: LriFile "esc_dry_05.bli"
ISAT-Samples-TrafficLightTest.scn: LriFile "simple_city1.bli"
ISAT-Samples-TrafficLightTestB.scn: LriFile "simple_city1.bli"
ISAT-Samples-YellowLightDilemmaB.scn: LriFile "simple_city1.bli"
KBW_TEST.scn: LriFile "simple_rural.bli"
KBW_TESTB.scn: LriFile "simple_rural.bli"
demo.createADO_and_trigger.scn: LriFile "simple_city1.bli"
demo.creation_radius1.scn: LriFile "simple_city2.bli"
demo_FV_sum_of_Sines.scn: LriFile "simple_city2.bli"
demo_LV_Decelerate.scn: LriFile "simple_city2.bli"
demo_LV_cut_in.scn: LriFile "esc_dry_05.bli"
demo_MG.scn: LriFile "simple_city2.bli"
demo_TM1.scn: LriFile "simple_city2.bli"
demo_TT_null.scn: LriFile "simple_city2.bli"
demo_actions_text.scn: LriFile "simple_city2.bli"
demo_alt_data_measures.scn: LriFile "simple_city2.bli"
demo_audio_virtual_object.scn: LriFile "esc_dry_05.bli"
demo_audio_virtual_object_simple_rural.scn: LriFile "simple_rural.bli"
demo_auto_cloud1.scn: LriFile "simple_city2.bli"
demo_coneISC1.scn: LriFile "simple_city2.bli"
demo_dddo.scn: LriFile "simple_city1.bli"
demo_dddo_B.scn: LriFile "simple_city1.bli"
demo_forXRef_traffic.scn: LriFile "simple_city1.bli"
demo_force_vel_01.scn: LriFile "simple_city1.bli"
demo_groupImport.scn: LriFile "simple_city2.bli"

==How to configure miniSim for screenshots to include coordinates==
You can enable coordinate display on miniSim by changing the focus to the main display. #Move the cursor until it is positioned in the main display area, then LMB. When successful the main display will appear to "blink".

Press the keyboard n key twice. This will cause coordinate information to display in the lower left corner of the main display.

[[File:miniSim_show_coords.png|400px]]

The n key is a toggle; to disable coordinates, press it twice (2x) again. '''NOTE:''' the cursor focus must be in the main display in order for this to work.

=Additional Resources=
[[:File:ISAT_Quick_Start.pdf|ISAT Quick Start Guide]]

[[ISAT_Demonstration_Scenarios|Demonstration Scenarios]]

[[:File:Create_Use_Custom_Cells.pdf|Create and Use Custom Cells on MiniSim]]

[[:File:Function_ReadCell_20180824.pdf|ReadCell function]]

[[:File:TrafficManager_Ch12.NADS.Internal_ISAT_UsersGuide.pdf|Traffic Manager]]

=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 [[ISAT_Reference_Manual_Table_of_Contents#ISAT_Reference_Manual|reference manual for ISAT can be found here.]]

ISAT User Guide Table of Contents

2023-09-15T14:48:04Z

Shawn Allen: /* Conventions Used in this Document formatting, add : to list elements for legibility */

== Who should use this document? ==
Anyone learning to use the DSRI 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
*CTL-<some other key>: Press and hold the Ctrl and then press <some other key>. Most typically used for copy (CTRL-C) or paste (CTRL-V).
*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 and modify for use in your own scenarios as needed.

== <span style="color:#FF0000"> '''Known Issues'''</span>==

Added 2022.07.01 '''Relative Creation''' does not currently work for ADOs on miniSim.

'''Expression clarification'''

Increment and decrement operators (++, --) are not considered expressions by behaviors. They should not be flagged as expressions when used in the Value field of a Set Variable action.

Added 2019.11.07 '''File reset issue'''

ISAT has a long-standing bug which can reset your static object options when your scenario file is saved to disk.

'''It is strongly recommended that you use [[#External_Reference|external reference scenario files]] to avoid this. '''ISAT does not reset static object options in the xref file.

Added 2021.12.29 Expression Triggers and Values

'''Using Values in Expression Triggers'''

To ensure proper execution of expression triggers, it is recommended that the values used include the desired range by decreasing the lower threshold or increasing the upper threshold '''instead of using the exact value.'''

For example, to process values in a range (7031 - 7040):

[[File:2021-12-29_12h38_09.png|400px]]

'''Note: remember that negative values must be calculated since the expression parser does not parse negative values otherwise.'''

For example, to properly parse a specific transmission gear (Park):
'''ReadCell('CFS_Auto_Transmission_Mode', 1) = ( 0 - 2 )'''

=='''ISAT Overview & Interface Basics'''==
This section contains information about ISAT and the ISAT interface.

===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 <span style="color:#FF0000">'''not an object editor'''</span> 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.
[[File:miniSim_scenario_compnents.png|center|640px]]

*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.

[[File:anatomy_of_a_scenario.png|center|400px]]

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

[[File:scenario_as_text.png|center|640px]]

This diagram shows the same scenario in (left to right) 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, <u>always</u> check your edits in ISAT!'''
*Copy/Paste - delete paths from elements when the BLI is different between your source & destination BLI files. The following scenario elements contain paths:
::ADO (with a path specified)
:: Any roadpad trigger (roadpad, Time to Arrival, Follow)

'''NOTE: A Traffic Source is not a portable element but it can be re-created in ISAT or integrated into a new scenario by copying the element from the source scenario then using a text editor to paste it into the destination scenario'''

'''How can I find information in multiple files easily?'''

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.

What if you don't know what to look for? How do 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
[[File:action_overview.png|400px||border|caption]]

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)

==='''Adding an action to a trigger'''===

The following example uses a Time Trigger; remember that '''all triggers share the same actions'''.

To add an action to a trigger you can double-click on the trigger, navigate to the '''Actions''' panel, and click on New to create a new action.

[[File:2022-11-30_12h47_23.png|400px]]

The possible actions are listed under the '''Action Type''' drop-down menu.

[[File:2022-11-30_12h47_44.png|400px]]

Actions are arranged in a 'stack' and are processed from top to bottom. If you use multiple actions you should enable the '''sequential flag''' to ensure each action is executed in sequence. Without the sequential flag, actions will be processed as fast as the simulator behaviors can execute.

[[File:2022-11-30_12h52_58.png|400px]]

Actions may be re-ordered in the stack using the '''arrows''' located near the action stack list.

=='''ISAT Modes of Operation'''==
[[File:ISAT_modes_of_operation.png|400px]]

*Edit
*Rehearsal
*DAQ playback
*Monitor '''Currently not available'''

==='''Edit & Rehearsal Modes'''===

*Edit - this is where scenario authors will spend the most time.
::Creation or modification of scenario
::Link to or import portions of other scenario elements

[[File:mode_edit.png|400px]]

*Rehearsal
::Debug & test scenario
::Simulates scenario using Behaviors and Vehicle Dynamics
::Displays error messages from behaviors

[[File:mode_rehearsal.png|400px]]

'''NOTE:''' Rehearsal mode <span style="color:#FF0000">simulates </span>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

[[File:mode_playback.png|400px]]

==='''miniSim Scenario Components'''===

The following diagram shows an overview of scenario related components of the NADS miniSim and how these components work together.

[[File:miniSim_scenario_components_wDAQ.png|400px]]

=='''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.

[[File:isat_workspace_general.png|400px]]

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)
[[File:isat_status_bar_overview.png|400px]]

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.

[[File:isat_user_prefs_status_bar_settings.png|400px]]

====ISAT Iconography====
ISAT provides graphic hints for triggers placed in scenario that can be useful when editing or maintaining scenarios.

The general format is a border enclosing miniature icons of the trigger and first action contained in that trigger. Additional information representing one or many actions is also shown.

[[File:hints1.png|400px]]

ISAT will list all trigger actions when a trigger is selected, but these hints provide a way to quickly identify what actions have been authored.

[[File:hint2.png|400px]]

*A Roadpad trigger, one action: '''Traffic Light Action'''
*B Roadpad trigger, multiple actions, first action is '''Remove Element'''
*C Roadpad trigger, multiple actions, first action is '''Set Dial'''
*D Roadpad trigger, constrained to road (lane), no actions - this is an empty trigger
*E Roadpad trigger, multiple actions, first action is '''Log Data'''
*F Global Time Trigger, single action: '''Set Dial'''

[[File:handle.png|400px]]

The element handle is the red dot visible in most of the triggers.
The handle can be dragged into position, and the trigger will follow the handle

Drag the trigger off the handle to offset it's location from the handle

==='''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.

[[File:object_types_isat.png|400px]]

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
::*Traffic Source

:'''NOTE:''' Virtual objects are defined in the scenario, not in the SOL2.
[[File:object_types_world.png|400px]]

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.
::NOTE: 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.

==='''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:
#Follow a path using kinematics
#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:
#coupled
#relative trajectory
#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'''===
Traffic signals are objects with special operation and function; they are coupled to intersections and routes of travel through intersections to control traffic flow similiar to their function in the real world. Traffic signals are part of the source tile model and may not be re-positioned or physically altered by scenario except for their visual signal state appearance; i.e., red, green or yellow signals.

To control intersection traffic signals use Edit >> Traffic Light ManagerTraffic signals use a Signal State Table (SST) to control which signal states are active and when. Each intersection with traffic signals will have an associated SST.

[[File:traffic_light_state_manager.png|400px]]

The above diagram shows an intersection in the workspace to the right, and the traffic signal state table for that intersection on the left. At this point additional states (for signal condition) can be added by clicking the '''Add state button'''.

[[File:traffic_signal_state_table2.png|400px]]

The above diagram shows two states defined for the intersection, represented by the two columns of state condition.

Continue adding states until the desired signal cycle has been defined. Generally this consists of red, green or yellow states.

NOTE: There is currently no way to automatically author a series of traffic light signals

To author traffic signal lights in sequence or on a route, the scenario author has to manage the signal states

[[File:traffic_signal_state_duration.png|400px]]

To edit the signal state duration RMB on the duration field header and choosing '''Edit state duration''' on the context menu. Enter the desired value then click OK.

====Traffic Signal Types====
The ISAT status bar reports Traffic Signal Type name. There are two signal types:
#Standard signal - IDs may have no identifying information
:Valid signal states: Red, Yellow, Green, Flashing Red, Flashing Yellow, OFF
#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

[[File:traffic_light_extended_type_name_normal.png|400px]]
: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.

[[File:traffic_light_extended_type_name.png|400px]]

===Changing Signal States in Scenario===
Traffic signals are controlled in scenario by using a Traffic Signal Action to change the SST.

'''NOTE:''' The Traffic Signal Action works by changing the SST, '''not by changing the traffic signal.''' This is a subtle but important difference.

Setting a signal to an undefined state effectively does nothing to the traffic signal.

[[File:traffic_light_state_table.png|400px]]

The above diagram shows a fully populated SST, with one signal row highlighted in red, and one state column highlighted in green. The associated intersection corridor is highlighted, showing the signal controls a dedicated left turn.

During simulation, the initial signal state is defined by the left column. As the simulation proceeds, the signal state changes according to the duration states defined across the state table, proceeding left to right and then wrapping around to the beginning after the last defined state. Each traffic signal appearance changes according to the configuration of the SST.

As a driver approaches this intersection, assume the signal state is in the column left of the highlighted column ('''R'''ed), and the desired action is to change the signal to green.

The action used to change a traffic signal state is the '''Traffic Light Action'''.
Using a traffic light action requires the specification of a signal state, the traffic signal to affect, and a duration.

[[File:traffic_signal_action1.png|400px]]

In the above diagram the scenario author has specified the desired state as '''Green''' as shown in the action dialog.

However, referring back to the previous state table diagram, there is no such state present in the SST. That means this particular action will fail, and the traffic signal will not change as the driver approaches the intersection - because the action does not create a new signal state, it works by advancing the state table condition (column) to the specified condition. If the condition is not present in the SST then nothing will appear to happen.

In this example, the action should be edited to use the correct signal state '''Left Turn Green''', which is present in the SST.

'''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

[[File:known_issue_traffic_light_action.png|400px]]

'''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.

[[File:known_issue_traffic_light_action_workaround.png|400px]]

====Change A Traffic Light Using Scenario Action====
To change a traffic signal, use the Set Dial >> Traffic Light action.
'''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

[[File:traffic_light_state_table.png|400px]]

This diagram shows a fully populated traffic signal state change for an intersection.

*Static object traffic lights
:These are objects, not true traffic signals and so they are not controlled with the Traffic Light manager.

==='''Traffic Source'''===
A traffic source is a coordinator used to create traffic at specific locations in the road map (unlike the Traffic Manager). This is useful for creating ambient traffic. Traffic Sources creates ADOs or DDOs at random or user-specified intervals.

Elements created using a Traffic Source will be created at the locations specified by the user. If traffic is specified at multiple locations the actual location for each creation will be determined randomly during simulation.

'''Note:''' Using the Relative Creation flag on ADOs created by the traffic source will not create traffic at the specified location on the map, but use the information in the Relative Creation fields to populate traffic in the scene during simulation.

This method allows for more flexibility but care must be taken not to create so many ADOs that miniSim is unable to make frame rate. Too many ADOs will cause the scene to jump and 'jitter' and it will feel slower than normal.

==='''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 ISAT scenario rehearsal

===Custom (icon) file virtual objects===

[[File:virtual_object_custom_icon_file.png|400px]]

'''Note:''' Some versions of MiniSim_2.3 do not support custom virtual objects. For those installs, if you require this type of functionality, a workaround exists in the form of a 2D model that can be customized (i.e, sprite).

Virtual objects may be customized using graphics files (texture images) to display any desired custom element. This typically requires the use of a bitmap graphic. Various file formats are supported: JPG, BMP, PNG. It is possible some types of these formats may not work - in those cases, try an alternate format.

If image transparency is required and the custom icon does not display during simulation, please email dsri-minisim@uiowa.edu with a description of the issue, your scenario and custom virtual object image file.

Custom icon files must be located within the Nads MiniSim path for resources - at NadsMiniSim_x.x\data\visuals\Models\ModelTx.

===Standard virtual object shapes===
The virtual object shapes include:
# Circle
# Triangle
# Octagon
# Star
# Diamond
# Icon <- this is for custom virtual object graphics
# Rectangle
# Hexagon

The virtual object fill and border color and transparency can be set in the virtual object properties dialog panel.

[[File:virtual_object_std_shape.png|400px]]

====Virtual Object Workaround====

There is a scenario authoring method that can be used to emulate virtual object functionality through the use of a DDO that is coupled to any dynamic scene element, including the External Driver. One model has been created to support this method called "sprite".

'''Note:''' The sprite model is a 2D object present in the scene, and can therefore be occluded by other scene elements during simulation.

[[File:trafsign_sprite.jpg|400px]]

The sprite model is designed as a flat plane that continuously faces the viewer. It contains different sized planes and can be customized through textures.

When authoring your scenario, configure the sprite object to Off unless it should be visible at scenario start. During the scenario you can control the sprite appearance with a setSwitch action.

[[File:sprite_setSwitch_action_021121.png|400px]]

The who to effect should use the name of the DDO placed in your scenario. The switch name will be s_sprite as shown above. Any valid option can be used. An invalid option (greater than 30) will disable the sprite the same as selecting the OFF option.

==='''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'''===
<span style="color:#FF0000">'''All trigger types share the same Action types'''</span>
*IF Then conditional
*Predicate: i.e., the activating agent
:If predicate is TRUE, then do Action(s)
*Road related triggers are categorized by predicate type
:Named element
:Road (lane)
:Nth vehicle on path only

'''What trigger is appropriate?'''
To determine which trigger is most appropriate, consider the task you are trying to accomplish. '''The differences between triggers is their activation methods.'''

'''Global Time Trigger'''
[[File:isat_time_trigger.png|150px]]

Use this trigger when something has to happen at some point in time.

Time triggers are also useful as "placeholder triggers"; used to apply persistent actions to multiple elements with unique settings for each element. Normally a persistent action is the last action possible in a trigger since the persistent action fires continuously. Putting persistent actions into a time trigger allows the scenario author to continue an action stack in the parent trigger if necessary.

Time triggers can be used as a 'stopwatch' - elapsed time, such as ending a drive after 3 minutes by setting the trigger to fire using an Activation Delay of 180s (GTT >> General).

Often used as a placeholder for actions such as initializing variables, displaying text messages to the screen using Set Visual Display Text actions, etc.

'''Note''': A time trigger can have global elapsed time and activation delay of 0, which causes the action stack in the time trigger to activate when that trigger is created.

'''Roadpad Trigger'''
[[File:isat_roadpad_trigger.png|150px]]

Use this trigger when something has to happen at some location in the drive that does not require event timing to be comparable for all participant drivers. For cases where event timing must be comparable among all participant drivers use the Time to Arrival trigger (TTA) instead of a roadpad trigger.

'''Time to Arrival Trigger'''
[[File:isat_time_to_arrival_trigger.png|150px]]

Use this trigger when something has to happen relative to some point in the drive, and also ensure all study drivers experience the same event timing irrespective of driver style (conservative, slow vs. aggressive, fast). Time to arrival (TTA) trigger uses a time calculation from the trigger pad activation to a target location specified in the trigger.

'''Traffic Light Trigger'''
[[File:isat_traffic_light_trigger.png|150px]]

This trigger activates actions when the specified traffic signal state is reached. For example, if the desired action is to create a DDO pedestrian to step into traffic when the traffic signal is yellow, then the Traffic Signal Manager must be used to author the appropriate signal states for the traffic signal.

Typically some other trigger is used to control the traffic signal (ie, to change the signal to Yellow on approach). It is therefore perfectly valid to put the actions within this other trigger rather than relying on the traffic light trigger.

'''Note''': Once a traffic light action has been authored, ISAT may be prone to crashing when accessing that trigger. This problem can be avoided by creating a time trigger and isolating the traffic light action there, allowing the parent trigger to be modified without crashing. Adjustments can be made to the traffic light action time trigger in a text editor, or recreated if it becomes necessary to make adjustments and ISAT continues to crash when trying to make edits.

'''Note:''' The traffic light action does not change the traffic signal state, and it requires a valid state sequence to exist in the signal timing table (Edit >> Traffic Light Manager). The traffic light action '''will not create a signal state''' that does not already exist in the signal timing table.

'''Expression Trigger'''
[[File:isat_expression_trigger.png|150px]]

Use this trigger when something must be monitored, evaluated or calculated such as checking a variable or cell value, velocity of the driver or the state of simulator hardware (steering wheel angle, brake or accelerator pedal position) or distance from the driver to some other object in the scenario.

Multiple expressions can be used within the same expression trigger. In those cases, all expressions must evaluate to True in order for the action stack to execute unless using an '''OR''' operator.

Use the '''OR''' operator - the pipe character "|" if you want to activate the action stack if '''any''' of the expressions evaluates to True.

In the following example, the trigger checks for TrialNumber = 1 and FirstButtonPress variables, and then checks if Aux Button 1 or 0 was pressed:

'''ReadVar('TrialNumber') = 1.0 & ReadVar('FirstButtonPress') = 1.0 & (ReadCell('Auxiliary_Buttons', 0) > 0 | ReadCell('Auxiliary_Buttons',1) > 0)'''

'''Note''': Expressions can also be embedded into some other triggers, most notably the Set Dial >> ADO >> Forced Velocity action often used in Roadpad triggers.

'''Follow Trigger'''
[[File:isat_follow_trigger.png|150px]]

Use this trigger when something has to happen based on one ADO position relative to another scenario element (including the XD). The follow trigger requires a leader and a follower to be specified; when this condition is met, the trigger action stack activates.

'''Note''': Both leader and follower must be positioned on the follow trigger roadpad to satisfy the follow parameters.

'''Geometric Position'''
[[File:isat_geometric_position_trigger.png|150px]]

This trigger is most useful to perform actions for off-road actors such as walkers. The trigger predicate is limited to Name or Type and requires a geometric position to be defined.

A more limited version of the geometric position trigger can be implemented with a Global Time Trigger that contains a Creation Radius. Placing the creation radius defines the area where the trigger may be activate.

===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

[[File:Screenshot (208).png|800px]]

'''Note:''' The highlighted lane shows which lane is the '''activating lane'''. Other lane/s will not activate the trigger action stack.

===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

[[File:TTA.png|400px]]

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===

[[File:other_triggers.png|400px]]

*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===

Execute actions if input expression evaluates to TRUE; the expression is specified on the trigger Predicate tab.

====Syntax====
Expression triggers support a simple language syntax with operators and functions.
The syntax is infix notation; i.e. a + b, not a b +.

Note: It is not generally possible to embed one function call inside another:
cos(sin(x)) is therefore an invalid expression. ISAT will report invalid expressions during rehearsal of a scenario. Invalid expressions are not supported and will not operate as written during simulation.

'''Exception:''' Currently it is possible to use the square root function with GetObjDistPow2 as in the following example:

sqrt(GetObjDistPow2('Target_Object_Name'))

Multiple expressions may be combined using the logical AND (&) or OR ("|" pipe character).

Exp1 '''&''' Exp2, Exp1 '''&''' Exp2 '''&''' Exp ''N''

All expressions must be true for the trigger to evaluate to TRUE and execute the action stack.

Exp1 '''|''' Exp2
One of the expressions must be true for the trigger to execute the action stack.

Negative values are not directly supported by the expression parser. To use a negative value, it must be a calculated value such as the following:

'''ReadCell('CFS_Steering_Wheel_Angle',0)<(0-5.0)'''

==== Operators ====
Operators are used to create expressions.

'''String'''
:Used within quotes as a string literal; i.e., 'some string'

Grouping
:Parentheses group elements together; i.e.,
:'''()'''; (a), (a + b)

Multiplication
:'''*'''; a * b

Division
:'''/'''; a / b

Addition
:'''+'''; a + b

Subtraction
:'''-'''; a - b

Note: negative values must be expressed with a subtraction operation:
(0 - 5), not -5 (invalid)

Greater than
:'''>'''; a > b

Less than
:'''<'''; a < b

Logical And
:'''&'''; a & b

Both a and b, otherwise returns 0 (FALSE)

Logical Or
:'''|'''; a | b

a or b returns 1 (TRUE)

====Expression Functions ====
Functions are used with operators to create expressions.

Function: '''sin'''
:sin -sine

Syntax
:sin(float x)

Description
:The sin() function returns the sine of x, where x is given in radians.

Return Value
:The sin() function returns a value between -1 and 1.

Function: '''cos'''
:cos –cosine

Syntax
:cos(float x)

Description
:The cos() function returns the cosine of x, where x is given in radians.

Return Value
:The cos() function returns a value between -1 and 1.

Function: '''ReadCell'''
:ReadCell()

Read a Cell value.

Syntax
:ReadCell(string Name, int Cell Array index)

Description
:ReadCell returns the value of a given cell (a cell is the current instance of a variable that will be maybe written to a daq file).

Index specifies a 0 based index into the array. Since most cells are single element arrays, a value 0 indicates the first element.

Cells valid for the ReadCell function are defined within the cell collect file NadsMiniSim.cec located in the miniSim_x.x\data folder.
The ReadCell function operates on shared memory during simulation, it does not read cell data from the DAQ file.

Cells that are defined may be written to the DAQ; the collect file specifies which cells are saved into the DAQ and what frequency to use for the write operation.
The NadsMiniSimCollect.general.txt file is located in the miniSim_x.x\data folder.

Available Cells:
Any cell that has been defined in the .cec file. For example:

:'''LogStreams''': Array of 5 floats. Logstreams are a set of values the scenario author can write to through “write to logstream” actions.
:'''AccelPedalPos''': Single Value. The current position of the accelerator pedal
:'''BrakePedalForce''': Single Value. The current force on the brake pedal in pounds
:'''SteeringWheelAngle''': Single Value. The current rotation of the steering wheel
:'''CruiseControl''': Single Value. The current cruise control position. (values are cab/platform specific)
:'''TurnSignal''': Single Value. The current position of the turn signal (values are cab/platform specific)
:'''OvVel''': Single Value. The participant’s current speed in miles per hour
:'''OvLaneDev''': Single Value. The participant’s lane deviation in feet.
:'''OvHeadwayToLeadVeh''': Single Value. The distance in feet to the first vehicle in front of the participant. -1 if no vehicle can be found.
:'''OvTtcToLeadVeh''': Single Value. The time to collision to the first vehicle ahead of the participant.
:'''Horn''': Single Value. The state of the horn (values are cab/platform specific)
:'''DynObj_Vel''': Array of 20 floats. The speed of a given dynamic object. Dynamic Objects are sorted in terms of distance to driver.
:'''OvVelLocal''': Single Value. The participant’s current speed in miles per hour, using the value local to scenario control

For a complete list of cells and array elements please see the miniSim data dictionary spreadsheet.

Return Value
:Returns the value of the specified cell.

Example
ReadCell(‘LogStreams’,5) > 3

Function: '''CellEquals'''
:Cell Equals, array element, value to compare

Syntax
:CellEquals(string name, int index, float value)

Description
:The Cell Equals function is similar to the ReadCell function, except it adds an additional value to compare against the cell value.

Like ReadCell, name specifies the name of the cell, index specifies the cell array index (use 0 for single value cells).

Available Cells:
:Any cell that is defined in the .cec file.

Return Value
:Units: 1 or 0
:1 if the cell value is equal to the passed in comparison value; otherwise 0

Function: '''GetObjDistPow2'''
:Get object distance squared

Syntax
:GetObjDistPow2(string name)

Description
:GetObjDistPow2 returns the distance squared between the external driver and the dynamic object specified by ‘name’.

Distance squared is used to avoid having to perform an expensive square root calculation every frame.

If the specified object cannot be found, a value larger than 100 million is returned.

Return Value
:Feet; Distance in feet measured from the eye position of the driver to the CG (centroid) of the dynamic object specified.

A very large number is returned if the specified object cannot be found (larger than 100 million)

Example
:GetObjDistPow2(‘OncomingCar1’) < 2500

'''Note:''' To get an actual distance, multiply by the square root (sqrt())
: sqrt(GetObjDistPow2('Target_Obj'))

Function: '''GetObjTtcToOv'''
:Get Object Time To Collision to Own Vehicle

Syntax
:GetObjTtcToOv(string object name)

Description
:GetObjTtcToOv gets the time to collision from the dynamic object specified by the name parameter, to the own vehicle.

Return Value
:Unit: Seconds
:Time (seconds) to collision from the own vehicle to the dynamic object specified by the name parameter.
:0 is returned if the object specified cannot be found.

Function: '''GetObjVel'''
:Get Object Velocity

Syntax
:GetObjVel(string object name)

Description
:GetObjVel gets the velocity in meters per second of the first dynamic object with the name specified by the ‘name’ argument.

Return Value
:Unit: Meters per second
:The speed of the specified dynamic object; 0 if no object is found

'''Note:''' Multiply by 2.23694 for miles per hour.

Example
:GetObjVel(‘PullOutVeh’) > 15.4

Function: '''Rand'''
:Random

Syntax
:Rand(int value)
:Rand(string name)
:Rand(string name, string type, double parameter, double parameter)
:Rand(string name, string type, int parameter, int parameter)

Description
:Rand returns a random value specified by the name of the generator, the type of distribution and its parameters.

If the user does not specify the name of the generator and only specifies a number as the only parameter, the Rand function will use a default random number generator to produce random numbers.

If the user only enters the name of a user created random number generator, the random number generator will produce a value between 0 and 1.
If a name of generator is supplied that has not been created, the Rand function will display an error message in the ISAT debug window and return 0 (during scenario rehearsal).

The rand function supports multiple types of distributions that can be used to generate a random number.

Types of Distributions:
:normal: Normal Distribution(mean, standard deviation). The normal distribution generates random numbers near the mean with a specific standard deviation.
:gamma: Gamma Distribution(alpha, beta). The gamma distribution generates a random value that models waiting times for the Poisson process.
:uniformInt: Uniform Integer Distribution(min, max). The uniform integer distribution generates a random integer number between the lower and upper bounds.
:uniform: Uniform Real Distribution(min, max). The uniform real distribution generates a random floating point number between the lower and upper bounds.

The values stated in the parenthesis above are the parameters for each distribution in order. If the incorrect number of parameters are entered or if they are entered incorrectly, the debug window in ISAT will display an error message and the rand function will return 0 (during scenario rehearsal).

If the distribution is entered incorrectly, the debug window will also display an error message.

Return Value
:A random value from 0 to 1 if the type of distribution is not specified.

If the type of distribution is specified, returns a random value determined from the type of distribution and the given parameters.

Example
:Rand(‘myRandGenerator’,’uniformInt’,1,10)
:This example returns a random integer value from 1 to 10.

Rand(5) or Rand(‘myRandGenerator’)
:These examples return a random value between 0 and 1.

Function: '''sqrt'''
Square root

Syntax:
:sqrt(parameter)

Return Value:
: return the square root of the specified parameter.
: parameter can be another function, such as GetObjDistPow2()

Function: '''ReadVar'''
:Read a variable

Syntax:
:ReadVar(string Name)

Return Value:
:Returns the string value of variable specified in <variable_name>

===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.

=='''Audio Components'''==
The components of the Audio sub-system includes configuration and data files installed into the NadsMiniSim_x.xx\data\sound\DefaultCabSound\Instructs folder.

[[File:audio_components.png|400px]]

The audio engine contains multiple channels and has a theoretical limit of 512 simultaneous sounds.

NOTE: Not all .wav files are compatible with the Audio Engine.

=Scenario World Objects=
Scenario world objects are defined in the tile model source. They are not added by the scenario author since they are objects already present in the roadmap/BLI.

[[File:object_types_world.png|400px]]

Typically, but not always, these objects can be authored in ISAT. However, some scenario world objects have no options - these cannot be selected in ISAT; therefore such objects cannot be authored.

Removal of world objects requires editing the source tile model using a 3D application. In some cases an alternate tile model is available identical to the original but without objects.

Contact NADS if removal of a world object is needed.

Other scenario world objects, such as Traffic Signals, are specialized function objects that can be authored. Traffic signals are authored using the Traffic Light Manager: Edit >> Traffic Light Manager.

=Troubleshooting Scenario Objects That Reset=

== Scenario World Objects ==
Scenario world objects are already present when you create a new scenario - they are not added by the scenario author. These objects may be visible in miniSim but not in ISAT, or they may be visible in ISAT and seem to be controllable, but the objects 'reset' to their defaults when viewed on miniSim.

[[File:2019-10-23_16h18_47.png|700px]]

The objects which 'reset' are a symptom of settings in the TMT that are not configured to allow scenario authoring of objects.

[[File:2019-10-23_16h18_52.png|700px]]

When objects appear to 'reset' or if you can edit an object in ISAT but don't see your changes in miniSim, correct the problem by resolving controllability in the TMT settings: https://www.screencast.com/t/ZH5Dh178.

=Scenario Coordinate Types=
There are two types of coordinates used in scenarios. The first is roadway coordinates. These coordinates are contextual (tied to a specific road or intersection and position) and are used for ADO objects and roadpad paths in general.

After a roadway coordinate has been generated, it is not updated unless the scenario author makes changes to the start, end or location of the entire path or pad.

Roadway coordinate are the reason it is not possible to change a roadmap using the TMT and expect a previously authored scenario to work on the altered roadmap. If the length or location of a road changes, the path/pad will update to the extent possible.

If the road has been eliminated and no longer exists in the roadmap/BLI, ISAT will report an error and not open the scenario file.

A. Field breakdown:
RoadPos keyword <name of road:lane:position on road:path length>

Name "Ado1"
RoadPos "r1_-6600_4620:0:5737.06:0.00"
Path "R:r1_-6600_4620:0[5736.06:5873.83]"

[[File:isat_coordinate_types.png|400px]]

B.
Name "VirtObj"
Option 2
Position -6.8375599E+002 5.6331237E+003 0.0000000E+000

The second type is world coordinates, which are Cartesian coordinates with X increasing to the right, Y increasing forward, and Z increasing up.

='''Scenario Authoring'''=
Scenario authoring is the creation, editing and testing of everything that happens during a simulation drive.

==Cell Operations: Best Practice==
Reading and writing to cells is a computationally expensive process. Best practice is to centralize all the reads/write to one place so that it’s only done once per cell.

Once a cell is read, the value is copied to a variable and only the variable is used throughout all the triggers that need it.

The same process applies to writing to cells. Use of variables can reduce the Cell Operations overhead greatly.

==Before You Begin==
Before beginning a scenario, it is necessary to understand the following requirements:

=== Drive Requirements===
How long is the drive?
What type of roadway?
Are there any specialized road elements (intersections, interchanges, freeway ramps)?
Are there any environmental requirements (should the simulation replicate a real world location, or is a generic environment acceptable)?
Is there a particular roadway configuration that is needed (long straight rural road vs. typical urban environment with intersections, signals, etc)?

=== Traffic Requirements ===
What types of traffic will be needed?
Will ambient traffic interact with the external driver?
What types of interaction will be required (traffic cloud, lead vehicle, follow vehicle)?

=== Events ===
The purpose of an event is to present a situation to the external driver. In order for the simulation to produce meaningful data, it is critical that events unfold for each driver in a comparable way. Therefore, each event must be designed with this repeatability in mind.

'''NOTE:''' one of the most variable scenario elements is the driving style of each external driver: how conservative or aggressive they drive, velocities throughout the scenario, how comfortable the driver is travelling with simulated vehicles, etc.

Repeatability often includes static elements (each driver encounters scenario elements in the same location) or in cases where the driver performance is taken into account, accommodation of the driver dynamic (velocity, lane position) through the use of time to arrival triggers (TTA) or follow triggers. A TTA trigger will fire based on time to a target location - thus a driver travelling at 45mph or a driver travelling at 55mph can both experience the same action relative to that target location, irrespective of the different driver velocities.

==Beginning A Scenario==
All scenarios designed to be driven require a start location - the place where the driver will be located when the simulated drive begins.

To insert a start location into a scenario:

:Insert >> External Driver >> LMB on road, intersection or terrain object

[[File:isat_initial_position.png|400px]]

'''NOTE:''' scenarios that only contain data and are not intended to be driven - for example, signs or traffic that are used as external reference files do not require a start location, since that will be defined within the parent scenario.

==Initial Conditions==
Initial conditions define how the simulated scene is configured: will the drive occur during daylight or night time conditions? Will the ownship (external driver vehicle) have headlights enabled? What type of vehicle will it be? Will there be objects or traffic visible to the driver?
These form the initial conditions of the simulation experience. Additional initial conditions would include initialization of variables or establishing networked communication as needed by the scenario.

[[File:isat_initial_conditions_miniSim.png|400px]]

By default ISAT sets the initial condition '''Time of Day''' to 12:00 noon. The time of day is controlled from the Initial Conditions dialog:

Edit >> Initial Conditions

[[File:isat_initial_conditions_scenario.png|400px]]

==Scenario Authoring: Actions==
Actions are the scenario elements that make things happen during simulation. Actions do specific things, like display a text message on screen for the driver, create a scenario element, change the velocity of simulated traffic, change a traffic signal, etc.

[[File:trigger_action_panels.png|400px]]

The diagram above shows the action panel for left to right: an expression trigger, a roadpad trigger and a global time trigger showing different panels based on the actions present in each trigger.

'''NOTE:'''Actions can be created, edited or removed from the '''Actions panel''' of '''any trigger'''.

'''NOTE:''' The Actions panel changes based on the action type created.
When multiple actions have been defined, control the sequence of actions by changing the action order in the list using the up or down arrows next to the list.

[[File:action_panel_overview.png|400px]]

If multiple actions need to happen in a specific order, set the order using the arrows and then flag the action list as '''sequential'''. This instructs behaviors to process the actions in the list order.

Using a delay for any action will pause processing of the '''following actions'''; the action happens first, then the delay is applied.

===Scenario Authoring: Action Types===
There are two types of actions:
# Instantaneous - the action takes up to one frame to complete, i.e.:
:set target velocity
:write to cell
# Persistent
<span style="color:red">'''*Persistent actions do not end'''</span>, or take multiple frames to complete:
:Forced lane offset
:Forced velocity
:Maintain Gap

==='''Actions'''===
*The "Who to Affect" field defines what is affected by the action
:Instigator set: who activated the trigger
:Name: one or more named elements
:Type: Apply changes to all objects matching the specified type
:Relative: Position relative to the trigger location

*Sequential
:Actions to execute sequentially, one after the other
:Specify delay between actions
:: Action executes, then delay

:Some actions are persistent and never "finish"

===Scenario example: display text & roadpad trigger to stop the drive===
This scenario is very simple and contains a global time trigger (GTT) that tells the driver what to do. After the driver travels along the roadway, a roadpad trigger (RPT) is used to tell the driver to stop driving. The same RPT also creates an expression trigger to terminate the drive.

TBC example scenario file

Because the external driver is not under control except by instructions, it's possible they might ignore the halt message and continue driving. A second failsafe RPT then terminates the drive.

==='''Actions: Button vs. Dial'''===
*Dial changes a setting
*Button: always runs in a single frame
:-"immediate" change. Typically buttons have less control than a '''Set Dial''' action

==='''ADO Actions'''===
[[File:ado_action_types_button_vs_dial.png|400px]]

==='''DDO Actions'''===
[[File:ddo_set_dial.png|400px]]

==='''External Driver Actions'''===
External driver behavior can be influenced by reinforcing scenario actions through audible speeding alerts, on-screen text instructions and messages or audio instructions.

Driving behavior can be influenced with situational elements
:Car in the drivers blind spot
:Lead vehicle
:Aggressive following vehicle
:Temporary lane closure
:lane specific instructions

Scenarios should '''not rely on specific driver actions to be successful'''
:to the extent possible; sometimes you do need the driver to respond/behave in a controlled manner.
:A work zone blocking one lane typically will require a roadpad placed upstream from the work zone to shift traffic into the correct lane

'''NOTE:''' Controlling driver actions should be an experimental design consideration.

==='''Special Actions'''===
These actions need special handling:
*Reset or "toggle":
:Audio
:Display Text

:'''Ado'''
::Audio State
::Forced Velocity
::Maintain Gap
::Visual State

*If using these persistent actions, place them at the '''end''' of an action sequence (because no action following these will execute):
:Forced Lane Offset
:Forced Velocity
:Maintain Gap
:Visual State

*Note: If the Visual State action contains a duration then it will be handled as a normal action, with subsequent actions firing after it. However, if there is no duration supplied with the Visual State action it behaves like a persistent action, and nothing following it in the Action stack will ever fire.

[[File:multiple_simultaneous_actions.png|400px]]

The diagram above shows how one parent trigger can be used to create multiple simultaneous triggers

*How to activate multiple unique force velocity (FV) or maintain gap (MG) actions:
#create the needed triggers from a general parent trigger, 1 per action
#put common actions into the parent trigger
::reset FV
::reset MG

==Scenario Authoring How To==
This section contains simple examples for various typical scenario situations.

===How do I specify an event?===
First, determine which method is best for you - the default measures (limited measures, 20 events max) or logstreams (all simulation data, no event maximum).

Regardless of method, you specify an event by identifying areas of significance in the drive and marking them so the data within the event region can be processed. Any trigger combination that can specify event start and event end may be used.

[[File:2022-07-01_11h21_52.png|400px]]

===How to know Which Coordinator or Trigger I need?===
The answer to this question lies in the type of information needed for an event:

*Time
:global time trigger
:or an expression trigger that calculates time
*Position or Location
:roadpad trigger
::or a time to arrival (TTA) trigger
::or an expression trigger that calculates distance
*Calculation
:Expression trigger

===How to Instruct the External Driver===

Instructions to the external driver can be accomplished by three main methods:
# Instruct the driver using experimental protocol (instructional or briefing presentation)
# Information messages displayed on screen: '''Action: ''set visual display text'' '''
# Information messages delivered as audio messages: '''Action: ''write to cell > SCC_Audio_Trigger ><audio ID>'' '''

===How to Add Traffic in the Scene ===

Generating traffic will happen in one of 5 ways:
# Created explicitly by inserting ADO, or copy/paste existing ADOs
# Created with a script
# Via a Create action inside a trigger, or placing scripted traffic inside a create action within a trigger
# From a '''Traffic Source'''*
# From the '''Traffic Manager'''**

Each of these methods has advantages and disadvantages.

==== Create Explicitly ====

The biggest advantage with this method of traffic creation is the high degree of control the scenario author has over:
# location of the created ADO
# Name of the created ADO
# Travel path of the created ADO
# Control when each ADO is created within the scene via Settings >> Creation Radius

The disadvantage is that creating a high volume of traffic will take some work with this method.

==== Created with a Script ====

This method combines the advantages of Creating Explicitly with volume. It is possible to create a large volume of traffic very easily with a script.

Disadvantages of using high volumes of traffic with a script: in the event it becomes necessary for a high degree of control over these ADOs, more is not better because ADOs will adapt to road conditions under their own power, unless the default ADO settings have been modified:
'''lane changes, including lane changes to accommodate freeway ramps'''
'''velocity adjustments'''

==== Via a Create action inside a trigger ====
Combines the advantages of the previous 2 methods with control over when to activate that traffic using a trigger action.

Disadvantages: Creating too many ADOs at one point in the drive can cause the miniSim to bog down for a few frames. If too many ADOs are present and active in the simulation at one time, this can cause the miniSim to drop frames and run sluggishly. This is highly noticeable and may increase the potential for the External Driver to experience '''simulator sickness.'''

==== From a '''Traffic Source''' ====

Traffic Sources rely on two methods to populate a scene with traffic:
# location specific, with each ADO created for a traffic source being a 'spawn location' for ADOs, or
# location agnostic if the ADO has '''relative creation''' enabled, thus being created relative to the object identified.

In addition to being created relative to a scenario element, ADOs are created relative to the specified scenario element:
# In front of (Longitudinal Distance > 0, where the number is feet offset from the object) , or
# Behind (Longitudinal Distance < 0, where the number is feet offset from the object).

Advantages: Can easily populate traffic into the simulation.

Disadvantages: It is easy to generate more traffic than the simulation can maintain at 60Hz frame rate, thus introducing frame lag with the resulting scene 'stutter' and the increased risk of simulator sickness.

Also, traffic created from a Traffic Source is generic traffic. It is not possible to reliably refer to specific ADOs generated from a traffic source except by using Who To Affect >> Relative (versus referring to a named ADO, i.e. Slow_Moving_Lead_Vehicle). Referring by name to Traffic Source generated ADOs will affect all similarly named ADOs at the same time.

==== From a '''Traffic Manager''' ====

The traffic manager interface is problematic in ISAT versions up to 1.8.5, especially when specifying the set of vehicles to be used for generating traffic.

Advantages: Create generic ambient traffic easily.

Disadvantages: Has the same disadvantages as traffic created via a Traffic Source. Also getting a traffic set working by specifying the vehicles to be used within the set. ISAT versions up to 1.8.5 exhibit instability when setting vehicles in ISAT.

Traffic Manager Set workaround: Borrow a working set from an existing scenario or group. Alternatively use a version of ISAT (1.8.6 +) to create the traffic set. This can be saved as a scenario or group file, which can then be used with ISAT 1.8.x as long as there is no attempt to adjust the vehicle weights within ISAT. The scenario or group file can be edited as text in a text editor, but care must be exercised to avoid introducing errors into the file. ISAT will not read invalid scenario or group files.

Traffic generated by the Traffic Manager is controlled through the use of Input Sets. An input set is a collection of vehicles and weights used to populate the scene during simulation. This is how the scenario author can control the vehicle population (type and number), density and creation/deletion distances - these attributes are unique to each set.

Since there is no 'discontinue traffic manager' function, one can be implemented by defining an input set with no traffic (an empty input set). An appropriate name can make the purpose of the set clear: PauseTraffic, Stop_TM, etc.

==== Sample Traffic Manager Set ====
This is a sample traffic manager set that can be pasted into a scenario file after the HCSM VehFail section. Be sure to paste '''after''' the HCSM VehFail end tag ('''&&&End&&&''') in your scenario file.

'''Note:''' A scenario file may contain only '''one''' Traffic Manager section.

There are two input sets in this example; note how they contain different vehicles and different settings from each other.

<span style="color:#2a4b8d">HCSM TrafficManager
GroupName "Traffic Manager"
HCSM InputSet
Name "ONE"
MinDensity 3.0000000E-002
MaxDensity 7.0000000E-002
MaxObjects 9
CreateDist 2.0000000E+003
DeleteDist 3.0000000E+003
AbsDeleteDist 3.4000000E+003
RunFreq 1.0000000E+000
SolWeights "cargill_semi_peterbilt_blu:2" "cargill_semi_freightliner_red:1" "cargill_semi_peterbilt_yel:3" "DumpTruck_org:3" "semi_peterbilt_yel_Walmart:2" "Cadillac_Escalade:10" "Ford_F150Xcab:15" "Saturn_Vue:10" "FordTaurus:15" "Escape:15" "DumpTruck:2"
&&&&End&&&&
HCSM InputSet
Name "TWO"
MinDensity 1.0000000E-002
MaxDensity 3.0000000E-002
MaxObjects 4
CreateDist 2.5000000E+003
DeleteDist 3.3000000E+003
AbsDeleteDist 3.5000000E+003
RunFreq 1.8000000E+000
SolWeights "Taurus2011:12" "Cadillac_Escalade:16" "Ford_F150Xcab:24" "Saturn_Vue:14" "Escape:6" "Deville:24" "Audi:4"
&&&&End&&&&
&&&&End&&&&
</span>

====='''Managing Traffic Manager Input Sets'''=====
During simulation, Input sets are controlled by the action '''Use Traffic Manager Set'''. A set name must be provided for this action to work.

===== Traffic Manager generated Traffic=====
ADOs will populate the road network around the XD based on the parameters of the Input Set. Typically traffic is removed from the scene shortly after passing the XD. This is visible in the rear view mirror. There is currently no way to adjust this delete distance.

====== Traffic Manager Traffic on 2 lane freeway======
Traffic will prefer to be in the XD lane, so ADOs created in any other lane will tend to veer into the XD lane. On a divided highway, traffic is generated moving with the XD.

====== Traffic Manager Traffic on 2 lane road======
Traffic is generated in the oncoming lane. In some cases traffic may be generated then immediately removed in front of the XD.

===How to Control Objects in the Scene during Simulation ===
"Set and forget" options on simulation entities only require the scenario author to "initialize" the element to a desired setting and then it is left alone during simulation.

Controlling objects dynamically during simulation requires the scenario "talk to" each object with a scenario action. This section describes how each scenario object type can be controlled during simulation within a scenario.

All models used in ISAT are listed within the Scenario Object Library (sol2).txt files. Terrain switch names are displayed in the ISAT workspace.

All model switches are listed within the NadsMiniSim_x.x\bin.x64\ModelList.txt file.

'''Note:''' The diligent reader will note discrepancies in model names between the sol2 and ModelList files. This is because the ModelList file contains actual file names, and the sol2 files define a "name label" for models that may, or may not, be the actual model name. Objects are linked between the sol2 and ModelList files through the ModelID/CigiID records. These values will match between sol2 and ModelList files, but IDs are not necessary at this time for scenario authoring purposes.

Complicated object names can be retrieved from the LRI file that was used to build any scenario file; each BLI is preceded by an LRI. The LRI contains all of the terrain models that will be present in ISAT. These are typically speed limit signs, traffic signals or other features that may be controllable.

'''Note:''' this file may not be present for the Springfield.bli file.

An alternative is to capture a screenshot of the ISAT workspace with the element name string showing. By default ISAT reports the name of any objects when the cursor passes over the object, as shown in this example:

[[File:2021-10-27_08h50_14.png|caption =Object Name Screenshot | 400px]]

{|class="wikitable"
|+ Controlling Scenario Elements During Simulation in Scenario
!Date
!Nads miniSim version
!Object Type
!Scenario Action
!Who To Affect
!Value
!Notes
|-
| Oct. 28, 2021
|2.3
|-
|
|
|Static Object (terrain)
| SetDial > StaticObjManager > Set Option1
| StaticObjManager
| switch name : switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
|Static Object, multiple options
| Set Switch
| Name of element
| switch option
|-
|
|
|Obstacle, multiple options
| Set Switch
| Name of element
| switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
| DDO, multiple options
| Set Switch
| Name of element
| switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
| ADO
| Set Dial > ADO > VisualState
| Name of element
| Limited to options present in ISAT
|-
|
|
| Traffic Signal
| Traffic Light
| Assign action to element
| Target state
| Target state must exist within the Traffic Light Manager intersection timing table for the specified signal

|}

===How to Control Simulated Vehicles===
The scenario author can control simulated vehicles by controlling the environment:
#change a traffic signal to cause an ADO to stop or start at intersections
#affect other ADOs to cause a target ADO to respond
# assign a path for the ADO to travel

Direct control:
*Lane related:
:Set button > ADO > ChangeLane, Turn, ProjectAndResetLane

*All other controls:
:Set Dial > ADO > AudioState, ForcedLaneOffset, ForcedVelocity, InhibitLaneChange, LaneChange, MaintainGap, TargetVelocity, VisualState, AudioState

====How to Change ADO Velocity====
ADO velocity can be changed using the SetDial action:
:SetDial > ADO >

:ForcedVelocity
:ForcedVelocity using an expression:
# match external driver speed
expr % OvVel(0) %
# multiply external driver speed
expr -1 9 %ReadCell('OvVelLocal',1)*1.75 %
:TargetVelocity

Indirect Control (dependent on other scenario element):
:MaintainGap

====How to Link ADO Velocity to Something Else====
ADOs velocity can be linked to other ADOs or the external driver using the MaintainGap (MG) action.

SetDial > ADO > MaintainGap

When using a traffic cloud containing multiple ADOs, each ADO in the cloud needs a unique MG. IF multiple ADOs have the same MG settings they will attempt to satisfy their parameters and likely oscillate position in a visually obnoxious way.

===How to Author Loop Scenarios===
A scenario created on a loop road network operates very much like any other scenario, with the exception that it is likely to require tracking the number of times through the loop, or to present scenario events to the external driver depending on each loop context.

[[File:loop_traffic_creation_01.png|400px]]

The simplest method of tracking loops is the use of a loop counter variable. This variable can be set by the driver "stepping onto" a roadpad trigger or it can be initialized through the use of a timer or expression, with increments managed by a roadpad trigger. Each time through the loop increases the loop count variable.

Thus it becomes possible to create events for each loop based on the loop counter variable, typically through an expression trigger.

Loop management triggers

[[File:loop_management_02.png|400px]]

Loop management trigger detail one

[[File:loop_management_vars_02b.png|400px]]

Loop management trigger detail two

[[File:loop_management_3.png|400px]]

====Creating Loop Specific Traffic====
Creating loop traffic is slightly more complicated due to the number of objects to be created and potentially the size of the actual loop. A small loop is installed with the Nads miniSim as simple_rural1 or simple_rural2. Each is a loop road network with two signed 3-way intersections.

Loop specific traffic can be created through the use of a variable (i.e., LoopCount) or within the roadpad trigger that is incrementing the loop count variable. Both methods will incorporate a '''Create Action''' that creates the required elements.

===How to Change Environment Settings===
The scenario author can define global or localized environment conditions.

1. Insert >> Environment Conditions >> <chosen condition>

2. Define a region where the environment condition is active:
:LMB to define polygon points
:RMB to exit point entry mode

[[File:env_condition1.png|400px]]

Choosing an environment condition

[[File:env_condition2.png|400px]]

Environment region defined and parameters panel shows available options

NOTE: The environment condition boundary is a discrete threshold. Condition A will be on one side of the threshold. Immediately after crossing the boundary, condition B will be displayed.

===How to Fade an Environment Condition===
To fade gradually between two conditions requires the use of an expression that continually monitors the desired condition and sets a few variables based on the results.

Examining the demo scenario is the best way to look 'under the hood' to see exact command syntax and values to be used.

[[File:env_fade.png|400px]]

Note: this approach has been used for fog and visibility. It is unknown how it might work with non-visibility conditions such as precipitation and wind.

*From the scenario demo_visibility_transition.scn

[[File:env_fade_schematic.png|400px]]

'''Note:''' although the example above uses an environment condition boundary, '''it is possible''' to omit the defined region, retaining all commands and the scenario will still function. However, without the environment region, it becomes more difficult to determine where conditions are different from the standard settings.

===How to Control a Cab Instrument Panel icon===
In order to control the instrument panel, there are 2 requirements:
The specific cab used for the scenario
The specific control (switch) to be manipulated
The action for addressing the instrument panel is '''ChangeCabSetting'''

Instrument panel models are located in NadsMiniSim_x.x\data\Visuals\Instruments
These files are in OpenFlight format. Any 3D editor capable of reading or importing OpenFlight can be used to review these files. NADS uses the Presagis product Creator[tm].

An alternative method to inventory switches is to use the the '''buildscl.exe''' tool. To run the tool, open a CMD window to the IP folder location above, then run the command:
buildscl <input_file.flt><Enter>.
<input_file.flt> is the name of the file to process, without the '<>' characters.
<Enter> means to press the Enter key,

The result will be in a new file ending with .scl. This is a text file, and can be opened in a text editor or you can use the shell utility '''more''' to view the file contents:

more <input_file.scl> | grep switch<Enter>

An example for the malibu cab is shown below. .

switch s_LowWasher 0
switch s_Cruise 1
switch s_LeftTurn 2
switch s_RightTurn 3
switch s_FwdCollisionWarn 4
switch s_BlindSpotWarn 5
switch s_LaneDeviationWarn 6
switch s_RearCollisionWarn 7
switch s_HighBeamHeadlights 8
switch s_SeatBelt 9
switch s_UpArrow 10
switch s_Airbag 11
switch s_CheckEngine 12
switch s_CheckGuages 13
switch s_ABS 14
switch s_Brake 15
switch s_LowFuel 16
switch s_Gear 17

These controls may be accessed directly in scenario using the ChangeCabSetting action.

'''NOTE:''' Some functions such as Cruise, Gear, High beam headlights, Blind spot, collision, lane deviation warnings are '''normally''' controlled not by direct access as described here but by hardware mechanisms/buttons.

'''NOTE:''' For altering cab instrument panel operation it will be necessary to modify the OpenFlight model to include the desired funationality; for example, instrument panel blanking is not build into the model but can be added by editing the cab instrument panel model file then installing the modified file into miniSim.

===Scenario Hints===
The total number of scenario elements active at any given time can affect simulator performance:

Total number of active elements
*vehicles (ADOs), triggers, animations, etc.

Object management
*Use paths to shift ADOs away from the driver route of travel as they turn off the route
*reduce the number of vehicles in traffic cloud surrounding external driver
*use creation radius to limit the number of active elements, and to remove elements after the driver has traveled beyond the creation radius

[[File:creation_radius_1.png|400px]]

Creation radius works by activating the scenario element only when the driver is within the radius. The scenario element is created when the driver enters the creation radius, and is deleted after the driver leaves the creation radius.

Exploit environment to reduce object load

*Use curves, hills, intersection corners to mask objects

Object deletion
*Remove objects when no longer needed

When creating dynamic elements, create them as close to where they are needed as possible.

====How to Determine When ADOs are Visible to the External Driver====

Some development/setup testing may be needed to determine precise location/distance/speed; i.e., locating ADOs for a freeway ramp merge event where the external driver is merging onto the freeway with other ambient traffic present.

Unless the purpose of the event is to study driver behavior at the merge, ideally the scenario will be authored to have ambient traffic on the freeway but not to present a conflict at the merge for the external driver.

A straightforward way to determine where the ADOs are first visible to the driver is to mock up a scenario placing colored ADOs along the freeway with a velocity of 0. This will ensure the ADOs remain stationary while the scenario author determines where they are first visible to the external driver.

Place the start position/external driver far enough up the ramp to be a reasonable test for the actual scenario.

As you drive the ramp, see which ADO is first visible to the driver. Place ADOs just out of view (upstream) of that location.

[[File:merge_hint.png|400px]]

'''NOTE:''' use test vehicles of the same type and character as the intended scenario vehicles. For example, do not use a sedan test ADO for a larger vehicle (SUV, bus, dump truck). Doing so will invalidate the visibility test, because a larger ADO will be visible over a longer distance than a small ADO.

[[File:ramp_vis_1.png|400px]]

At the scenario start location, ADOs in front of the Coke truck are visible. Note how the larger vehicles are more obvious at this distance.

[[File:ramp_vis_2.png|400px]]

The driver has traveled onto the ramp. At this point, the last ADO visible to the driver is still the Coke truck.

[[File:ramp_vis_3.png|400px]]

As the driver travels farther down the ramp a small ADO is visible behind the Coke truck.

The answer to the question '''When is an ADO visible?''' is thus:
#It depends on how large the ADO is
#Small ADOs can be placed at the location of the red ADO behind the Coke truck.
#Large ADOs may need to be placed farther back (behind the red ADO). This test is inconclusive, but based on the terrain it seems likely that large ADOs would need to be placed at least at the green ADO location (behind the Coke truck).

Creating small ADOs at the green ADO location when the external driver is located at the ramp position in 3 travelling at the same speed as the external driver should arrive at the merge slightly ahead of the driver (because the curved ramp is longer than the straight freeway).

'''NOTE:''' ADO size, ADO color, time of day and visibility settings affect ADO visibility.

====How to Position Objects Precisely using '''Place Object At..'''====

ISAT does not support true precision because it is not currently possible to 'dial in' a position as is typical in 3D modelling tools, but there is a way to approximate precision in cases where a consistent measurement is desired.

In the following example a number of roadpad triggers are placed relative to the location where a roadway enters an intersection. This is a discrete boundary within the simulation world as shown in ISAT.

There are two methods of placement possible:
# Measure the desired distance (CTRL+Shift+RMB, drag); take note of the coordinates updating in realtime and make a mental note of the desired location.
#Place an object (ADO or static object); use the Place Object At.. feature from the context menu when you RMB on a scenario object.
Using this method you can specify a distance - positive numbers move the object downstream/forward, negative numbers move the object upstream/backward.

'''Note:'''If the distance is significant and extends over an intersection, ISAT may produce unexpected and undesired results such as re-starting the measurement from the closest upstream intersection, thus placing the object where it was not intended.

In the following example, Place Object At.. is used to specify a point 50 feet upstream from the road/intersection border.

[[File:precision_placement_1.png|400px]]

A roadpad trigger has been positioned near the area of interest. Any existing roadpad is deleted from the trigger.

[[File:precision_placement_2.png|400px]]

An ADO is used as a marker object inserted temporarily into the scenario. Any convenient object may be used.

'''Note:''' large objects such as ADOs may be less precise than small objects such as the Traffic cone, but is generally easier to access in the ISAT interface unless you have created a script for cone objects.

[[File:precision_placement_3.png|400px]]

RMB on the ADO to access the Place Object At.. request dialog. Only numbers are valid entries.

[[File:precision_placement_4.png|400px]]

The desired distance is entered into the Place Object At.. request dialog. ISAT will then require you to select the object you wish to move using LMB.

[[File:precision_placement_5.png|400px]]

ISAT moves the selected object by the distance you specified.

[[File:precision_placement_6.png|400px]]

Use the ADO CG (model center) to place the start of the road pad.

[[File:precise_placement_7.png|400px]]

Remove the ADO marker and save your scenario.

==Scenario Testing and Debugging==
The primary way to test and debug scenarios is using ISAT rehearsal mode.

'''NOTE:''' the external driver during rehearsal is a simulation. You have limited control over the simulated ownship:
#change speed
#change lane

ISAT has two rehearsal dialogs:
#abbreviated (standard) dialog
#advanced (extended dialog)

===How to change to the advanced rehearsal dialog===
Often it is necessary to control the ownship during rehearsal. The ownship controls are located in the advanced (extended) rehearsal dialog.

ISAT will show the Advanced dialog the first time rehearsal mode is activated. All additional activations show the abbreviated dialog.

TBC abbreviated dialog

To use the Advanced dialog, LMB the Advanced button.

TBC Advanced dialog

===How to change ownship speed during rehearsal mode===
After entering rehearsal mode:
#click the Play icon (start the rehearsal)
#pause.
#adjust ownship speed
#toggle pause off (resume rehearsal)

===How to make ownship lane change during rehearsal mode===
After entering rehearsal mode:
#click the Play icon (start the rehearsal)
#click the desired Lane Change (left or right)

===How to Use Audio in your Scenario===
Scenarios play audio sounds and messages through a write to cell action: '''SCC_Audio_Trigger'''

Use of audio in a scenario typically requires both a write to cell and a 'clear action' that writes a zero (0) to SCC_Audio_Trigger in order to 'clear the channel'. The 'clear' action can happen before or after playing a sound; choose one method and be consistent in your scenario authoring.

Failure to 'clear the channel' or '''not''' writing a value of zero can result in no audio being played for subsequent write to cell SCC_Audio_Trigger actions.

The following shows how this looks in scenario when executed from a roadpad trigger (RPT):

[[File:audio_scn_A.png|400px]]

The above diagram is shown below in text format:

HCSM RoadPadTrigger
GroupName "WindGust_Audio"
ByTypeSet "ExternalDriver"
NthFromStart 0
NthFromEnd 0
VehicleAhead 0
VehicleBehind 0
LongComment "This is a wind gust event"
ShortComment " "
ActvDel 0.0000000E+00
CrRad 0.0000000E+00
Debounce 0.0000000E+00
FireDelFrames 0
Lifetime 0.0000000E+00
Name "RPT_WG_6"
OneShot 1
Priority 0
SeqAct 1
Position 6.7165800E+04 6.0419215E+03 0.0000000E+00
DrawPosition 6.7165800E+04 6.0419215E+03 1.1308095E-317
Path "R:r3_62700_7920:0[3033.04:3245.46]"
HCSM LogData
Comment "LS1=8"
Delay 0.0000000E+00
InstigatorSet 0
Stream 1
StreamVal 8.0000000E+00
&&&&End&&&&
HCSM WriteCell
Comment "Play_Audio"
Delay 2.0000000E+00
InstigatorSet 0
CellName "SCC_Audio_Trigger"
CellData "63000"
CellType 2
CellVar 0
&&&&End&&&&
HCSM WriteCell
Comment "clear_audio"
Delay 0.0000000E+00
InstigatorSet 0
CellName "SCC_Audio_Trigger"
CellData "0"
CellType 2
CellVar 0
&&&&End&&&&
&&&&End&&&&

===How to Add Custom Audio Instructions to miniSim===

''' Please note: Custom audio 'instructions' for a scenario should be added to the instructions.txt file.'''

These are sounds that are played in scenario, typically as directions for the minSim driver.

Adding custom audio files requires the following procedure:

1 Exit miniSim - changes to the miniSim configuration should happen only when miniSim is not running.

2 Copy the audio .wav file to:
:C:\NadsMiniSim_x.x\data\sound\DefaultCabSound\Instructs

:Edit the file instructions.txt in that same folder.

3 Add an entry to instructions.txt to register your audio file in accordance with the following layout using the existing entries as a template:

:Unique_ID Filename Normalized_Volume

:Unique_ID is whatever unique number you assign to your file.

:Filename is the name of your .WAV file.

:Normalized_Volume is the volume your audio file should play, where 0.00 is silence and 1.00 is maximum volume.

'''NOTE: Remove all spaces in your audio filename.''' If needed, use the underscore character instead of spaces.

===Troubleshooting Custom Audio Additions===
After installing new .wav files and adding them into the audio configuration file '''instructions.txt''', if the audio file does not play:
*Check the Audio Engine window while miniSim is still running. The Audio Engine will display file errors,.
*If Audio Engine does not display a message similar to: Audio Engine loaded normally, scroll through the window messages and look for any .wav or load error messages.

==Re-use of Scenario Elements==
Scenario authoring can be an intensive undertaking. It makes sense therefore to leverage your development efforts by re-using scenario elements where possible.

ISAT provides a number of ways to re-use scenario elements:
# copy/paste
# external references
<span style="color:#ac6600"># exporting elements as '''groups'''</span>
# isc scripts

Each of these methods have their strengths and weaknesses.

===copy/paste===
The simplest method to re-use scenario elements among different scenario files is copy/paste. This is possible for most scenario elements* even if the source and destination roadmap/BLIs are radically different.

[[File:copy_paste.png|400px]]

It is also possible to copy an ISAT element from one scenario to another as '''TEXT''' by selecting the element and using the windows copy shortcut CTRL-C, then open a text file and paste it using the windows paste shortcut CTRL-V.

'''NOTE:''' Traffic sources are '''not''' portable using copy/paste.

'''NOTE:''' Not all elements can be copy/pasted. Elements created from a Create Element action cannot be copied - it is necessary to select the parent element and copy that instead.

[[File:copy_paste2.png|400px]]

In the above diagram, elements at '''B''' and '''C''' cannot be copied/pasted because they have been created by element '''A'''. It is necessary to copy the element at '''A''' instead. If only the elements at B are needed, the best method will be to copy/paste as Text.

'''NOTE: ISAT will not copy elements containing road coordinates (elements with a path) to a scenario that does not share the same BLI as the source (copy from) scenario.'''

A partial solution to such cases is to remove the path first, copy the element, paste into the destination scenario, then re-create the path manually.

===External Reference===
An external reference scenario is intended to be re-used by multiple 'parent' scenarios. The effort of authoring objects is thus leverages across multiple files, without needing to re-create the same elements more than once.

[[File:re_use_xref_1.png|400px]]

Common uses of external references include traffic, traffic signal operation, traffic sign appearance or other environment features which have multiple appearances (billboards, some tile related scenery, etc).

NOTE: Multiple external references are possible; but because objects are categorized by group, it is not entirely necessary.

For example, one external reference file contains traffic, another contains signs. These two external reference scenarios could be combined into one file.

[[File:xref_overview2.png|400px]]

NOTE: Each group defined must be unique across all files: parent and external reference files.

In order to use an element in an external reference scenario, it is necessary to define and assign a group to all elements that you wish to control from the parent scenario.
At this time there is no visual hint in ISAT to indicate if a group has been assigned to an element or not - each element has to be confirmed independently.

However, a properly authored external reference element cannot be edited within the parent scenario (after you have done Add Ref. to use the external reference file).

An alternative is to insert groups using a text editor with macro capability, or to use a program or external script to make the necessary changes.

'''NOTE:''' If the external reference file is for object contained in the parent scenario (for example, an external reference file containing traffic signals with a group defined) it is still necessary for that group to be defined in the parent file.

With traffic signals, ISAT requires ONE explicit group reference, which will be contained in the HCSM TrafficLightManager block as shown below. If you require the use of traffic signals in an external reference, the recommended way to do this is through ISAT because then it manages the group assignment for you.

==== HCSM TrafficLightManager scenario block ====

HCSM TrafficLightManager
HCSM CLG
IntrsctnName "I1_40260_4620"
Duration 2.0000000E+01 3.0000000E+00 1.0000000E+00 2.0000000E+01 3.0000000E+00 1.0000000E+00
GroupName "TrafficSignals"
LightName "s_signal_r1_LTRN_40260_4620_270"
LightName "s_signal_r1_RTRN_40260_4620_270"
LightName "s_signal_r2_LTRN_40260_4620_270"
LightName "s_signal_r2_STRT_40260_4620_270"
LightName "s_signal_r3_STRT_40260_4620_270"
LightName "s_signal_r3_NORM_40260_4620_270"
Pattern "FLTY" "R" "R" "R" "R" "R" ""
Pattern "RTG" "R" "R" "R" "R" "R" ""
Pattern "LTR" "LTR" "LTR" "FLTY" "FLTY" "LTR" ""
Pattern "SR" "SR" "SR" "SG" "SY" "SR" ""
Pattern "SR" "SR" "SR" "SG" "SY" "SR" ""
Pattern "R" "R" "R" "G" "Y" "R" ""
&&&&End&&&&
&&&&End&&&&

'''NOTE:''' At this time there is a known issue using the write cell '''SCC_Audio_Trigger''' action in external references. Although the trigger containing this action can be assigned a group and used as an external reference, audio does not play.

<span style="color:#ac6600">'''Because ISAT updates static object positions (elevation) to the terrain (roadway) when the scenario file is saved, the best way to use a custom elevation is to put such objects into an external reference file in order to isolate those objects from normal scenario editing.''' </span>

====Define a Group====
<span style="color:#ac6600">'''NOTE:''' ISAT 1.8.5 and 1.8.6 currently do not work properly with group files. These versions will not import objects within a group file. There is a workaround which involves the following process, but instead of reading the saved group file into a scenario the workaround requires editing the scenario as text and inserting the objects within the group file into the scenario.</span>

RMB on the element and choose from the context menu: Group >> New Group (if this is a new group) or Group >> (choose an already defined group).

'''NOTE:''' The first time you create a group for an object, ISAT will automatically assign the group to that object.

After defining and assigning groups to the scenario elements needed, save the scenario file then close it.

Open or create the parent scenario file and use the Add Ref. button at the bottom of the ISAT window to select your external reference scenario. After you choose a file ISAT will present you with the groups found in that scenario. Choose the groups you with to include and click the 'Okay' button. Click the Add Ref. OK button to complete the process.

Currently import group file operations are not working, but it is possible to insert the group file content (all HCSM StaticObjects) into a scenario manually by using a text editor to copy text from the group file and paste that into a scenario file into the HCSM Static Object section of the scenario file.

[[File:group_text.jpg|400px]]

'''NOTE:''' ISAT does not enforce logic on your external reference authoring. If you add references to scenarios that do not share the same roadmap/BLI as the parent scenario, it is likely that elements will be placed at the origin (in cases where the external reference roadmap contains roadways not found in the parent) if it even loads.

===Exporting ISAT Elements as Groups===
Transferring ISAT elements among scenarios can be accomplished using groups. As with external reference scenarios, one or more groups must be defined and then assigned to one or more elements.

After defining and assigning groups select the group for export using the Group select drop-down located at the lower left corner of ISAT. Choose a group to export and then click the 'Save Group' button. Save the file.

TBC insert graphic sequence diagram here

'''NOTE:''' If you cannot locate the group file in the folder specified, check the ISAT install\data folder. This is typically:

C:\NADS\ISAT\data

===Group File Contents===
The group file is a text file and can be opened or edited in a text editor.

The following is a group file containing one ADO. Note the GroupName line near the bottom:

Header
LriFile "_dev.bli"
LongComment "this is a test group export"
ShortComment "this comment was left empty"
&&&&End&&&&
HCSM Ado
RunMode "eREMOTE_CONTROL"
RandomSol 0
Name "Ado1"
DynModel "Non Linear"
LogFile ""
LatOffsType 0
CreateRelLatInFeet 0
CreateRelOffsLonUsingExpr 0
CreateRelOffsLonExprStr ""
AutoControlBreakLights 0
AutoControlHeadLights 0
UseReaDel 1
StdToAccType 0
StdToDecType 0
StdToDecVal1 9.0000000E-001
StpToAccType 0
DecToAccType 0
FollowTimeMin 1.0000000E+000
FollowTimeMax 2.0000000E+000
EmergDecClip -1.1000000E+001
Accel2Catch 0
NormVel2Kp 7.0000000E-001
PathSearchDepth 2
LcvFall 1.5000000E+000 2.0000000E+000
LcvFreq 3.0000000E-002 5.0000000E-002
LcvRAmpl 1.0000000E-001 5.0000000E-001
VelCtrlInitMatchOvVel 0
VelCtrlFollowSpeedLimit 0
VelCtrlDistType 0
MaxLatOffset 9.0000000E+000
LongComment " "
ShortComment " "
SolName "Audi"
RoadPos "r1_1320_44220:2:32414.44:0.00"
GroupName "TEST_Group"
&&&&End&&&&
HCSM StaticObjManager
&&&&End&&&&
HCSM DriverMirror
&&&&End&&&&
HCSM IntersectionManager
&&&&End&&&&

===ISC Scripts===
Scripts are an efficient way to automate repetitive and/or complex tasks.

ISAT uses a custom language (ISC) to automate placement and manipulation of scenario objects. Combined with simple direction commands and the capability to navigate a road network, ISC scripts can ask the scenario author for input and prompt for selecting objects.

ISAT installs with some ISC script files. If your version of ISAT contains a data\isc
folder, then your version of ISAT is capable of running scripts. You can create
additional scripts as needed. All scripts located in the data\isc folder will load in ISAT
when ISAT is launched.

You can use these scripts for reference in creating your own custom scripts.

New scripts created during an existing ISAT session will not appear until ISAT is re-
launched.
Scripts that have been edited will not update until ISAT is re-launched.

Unless otherwise indicated, scripts are case-sensitive.

'''NOTE:''' Please do not edit the existing scripts!

Make a copy of any existing script before you make changes. In the event your modified script does not work, you can look at the original file for reference.

ISC scripts are located on the ISAT Elements widget. Custom isc scripts are located after the 'Events' separator.

Using an ISC script involves LMB + dragging the desired script onto the workspace. In some cases the script will ask for inputs.

ISC can be also used to create an entire event, thus ensuring that all events created will be entirely identical in terms of settings and locations for all created elements.

ISC scripts are text files located within the ISAT installation data folder. Only the custom ISC scripts are located in this folder. This is typically:

C:\Nads\Isat\data\isc

====Icon Files====
Script icon files are 8-bit windows icon files (file.ico). GIMP is capable of exporting valid ico files. To create an ico file, scale it to 32x32 pixels. Export the file as .ico to the isat\data\isc folder.

In order for a script to use an icon file, both files must exist in the isat\data\isc folder.

====ISC Script Examples====
This section contains example scripts with notes.

'''Rotate sign'''

.Name SetSignRotation
.Icon SignRot.ico
Static sign
Select(sign,"Please Select a Sign")
sign.SetAngle(Anchor)
.End

'''Place Multiple Static Objects (TrafCone)'''
The following script asks the scenario author for number of cones to generate, position and offset values and then generates the objects.

A breakdown of the script follows the code block below.

.Name Cones
.Icon cone.ico

Block coneBlock %%%
HCSM StaticObject
IsNewObj 1
Name "Cone_xxx"
SolName "TrafCone"
Option 0
Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
&&&&End&&&&
%%%
Static cone;

Value dist1
Value numberOfCones
Value distance
Value variablePart
Value randDistance
Value speed
Value Count
Value LatOffset

Block tempBlock
tempBlock = coneBlock
Count = 1
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

Ask(numberOfCones,"How many cones?" )
Ask(dist1,"Distance between cones?" )
Ask(LatOffset,"How much offset?" )

Position posRp
Position tempPos
posRp = Anchor
numberOfCones = numberOfCones

Repeat numberOfCones
posRp.GoForward(dist1)
# test comment
tempPos = posRp;
tempPos.SetOffset(LatOffset)
cone.RoadPos = tempPos
cone.Clone
Count = Count + 1
tempBlock = coneBlock
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

End
.End

====Script Breakdown cones.isc====

This section contains a description of the elements used in the script. The script segment is followed by a brief text description.

This script places a number of object copies (TrafCone) using information provided by a user.

.Name Cones
.Icon cone.ico

The first line contains a keyword '''.Name''' followed by the name of the script. This is the name that ISAT will use on the Isat Elements widget for the script. Note the script name does not have to be the same, but it is good computing practice.

The second line begins with the keyword '''.Icon''' followed by a file name. This file must exist in the ISAT\data\isc folder (accompanying the script file). This is the icon ISAT will use for the script.

Block coneBlock %%%
HCSM StaticObject
IsNewObj 1
Name "Cone_xxx"
SolName "TrafCone"
Option 0
Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
&&&&End&&&&
%%%

This is the data section of the script, which is defined using the keyword '''Block'''. A block name follows the keyword, and the data start is defined with '''%%%'''.

The HCSM StaticObject section has been copied from a scenario. In this case, a static object was placed into the workspace and then copied into a text file.

Name "Cone_xxx"
Note: the object name contains a marker that can be used to programmatically name instances of the object:

SolName "TrafCone"
This line begins with the keyword '''SolName''' followed by the name of the object as it is defined in the sol2.txt file.

Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
The Position of the static object will update when the script activates and instanced objects are placed in the workspace.

Static cone;
This line begins with the keyword '''Static''' followed by a variable name.

Value dist1
Value numberOfCones
Value distance
Value variablePart
Value randDistance
Value speed
Value Count
Value LatOffset

This section defines variables with the keyword '''Value''' followed by variable names. Using descriptive names is better than generic names. From the variable list it already seems clear what the programmer cares about: number of cones and distances.

Block tempBlock
tempBlock = coneBlock

This section defines a block using the keyword '''Block''' followed by the variable name.

The next statement replicates coneBlock into tempBlock.

Count = 1
Initialize the value of the variable Count to 1.

tempBlock.Replace('xxx',Count)
The built-in '''Replace''' function changes the string 'xxx' to the value of the variable Count.

cone.SetBlock(tempBlock)
This statement creates a block using the function '''SetBlock''' called cone, and copies the contents of tempBlock into it.

Ask(numberOfCones,"How many cones?" )
Ask(dist1,"Distance between cones?" )
Ask(LatOffset,"How much offset?" )

This section asks the user for input and puts that information into variables:
*Number of cones
*Distance between cones (dist1)
*Lateral offset (calculated from lane center)

Position posRp
Position tempPos
posRp = Anchor
numberOfCones = numberOfCones

This section contains position variables and assigns the value of numberOfCones.

Repeat numberOfCones
posRp.GoForward(dist1)
# test comment
tempPos = posRp;
tempPos.SetOffset(LatOffset)
cone.RoadPos = tempPos
cone.Clone
Count = Count + 1
tempBlock = coneBlock
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

This section is where the work happens. Reading from the top, this section is contained within a loop defined by the keyword '''Repeat'''. The number of times to repeat follows in a variable numberOfCones.

'''posRP.GoForward()''' is a built-in function to take the current position and shifts it forward by the amount specified in the dist1 variable.

#test comment
This is a comment defined by starting the line with the comment keyword '''#'''

tempPos = posRp;

Assign the value of the variable tempPos to the value currently in '''posRp'''

tempPos.SetOffset(LatOffset)

Another built-in function or attribute to the position element which defines a lateral offset (distance from the lane center). This statement places the value of a variable LatOffset into the offset element of the tempPos variable, using the operand '''SetOffset'''.

cone.RoadPos = tempPos

This statement sets the road position variable for cone to the value in the variable tempPos.

cone.Clone

Duplicate the block cone using the operand '''Clone'''

Count = Count + 1
Set the value of the variable Count to the value of Count plus one. This statement increments the value of Count for each loop processed.

tempBlock = coneBlock

Create a new block tempBlock by setting it to the content of coneBlock.

tempBlock.Replace('xxx',Count)

Use a built-in function to '''Replace''' the string 'xxx' with the value of the Count variable

cone.SetBlock(tempBlock)

Use the built-in function '''SetBlock''' to place the modified tempBlock (modified by the string replacement command earlier) into the cone block.

End
.End

The last two lines terminate the loop and the script, respectively.

====How to Create an ISC Script====
The simplest way to create an ISC script is to find an existing script that does something similar to your desired behavior and edit it.

=miniSim Simulation Data=
MiniSim runs on shared memory:
*miniSim is a collection of programs
*shared memory is a commonly accessed 'blackboard' list: a Cell and a Cell Value
:The DAQ file is a snapshot of this 'blackboard' memory for every frame.

*Scenario can write to cells added by the scenario author
:-i.e., for custom hardware or tasks/events

'''NOTE:''' Custom cells must be present in the collect file (NadsMiniSimCollect.cec) '''prior to''' simulation in order for the custom cells to be present in the DAQ.

NOTE: The cell type defined in the collect file must be followed, or garbage values will be used

Use of a DAQ file implies that at some point, data reduction will be needed.
Data reduction: the process of distilling measures from the DAQ file, i.e.
*Event definition
*SDLP
*Average headway

==What is the Difference? Cell vs. Variable==
*A Cell is a pre-created “slot” in shared memory
:-Specified in the .CEC collect file,
:-Saved in the DAQ file,
:-Can be sent to custom programs;
:-Can create & use custom cells;
*A Variable is a name value internal to the scenario
:-NOT saved to the DAQ file,
:-Can use to track items in the scenario
:i.e., how long the driver has been exceeding the speed limit
:-Initialize conditions in the scenario.

=== Variables Save ===
Variables can be saved to disk as a single value text file (ie, multiple values over time are not supported) through the use of a '''Store Variable''' action:

[[File:2021-08-23_13h28_49.png|400px]]

The file is stored in the miniSim_x.x\bin.x64 folder.

'''NOTE:''' The name of the file is defined within the Store Variable action. '''Care must be taken to save variables to unique file names''' in the case of multiple scenarios running on miniSim at the same time (if they share common variables), as would be the case if triggers are copied from one scenario to another.

=== Variables Restore/Read ===
Variables can be read into the simulation through the use of a '''Load Variable''' action:

[[File:2021-08-23_13h32_39.png|400px]]

==Cell Types==
This is a partial list of cell types.

*CFS = control feel subsystem (steering wheel, pedals)
*CIS = control information subsystem (gear, turn signal, buttons, etc)
*TPR = terrain profiler for terrain queries
*VDS = vehicle dynamics for accelerations, position, engine speed, speed, etc.
*ACC = adaptive cruise control
*RCM = configuration management for setting variables that affect subsystem configuration (ACC enabled or disabled, for instance)
*SCC = scenario
*SOP = for one time initializations at the start of the simulation.

=='''Data Output Actions'''==

*Write to Cell Actions
:-Write the value of a variable or cell to a cell
:-Write to a custom cell
:-Cannot overwrite another systems output
'''NOTE:''' Although it is possible to write to a different system cell, that value will be over-written on the next frame. Thus it is effectively not feasible nor desirable to do.

'''<span style="color:red">Also Note: the limit for maximum number of write to cell actions that can be performed in one frame is 8.</span>'''

*Set Variable Action
:-Sets the value of a variable
:-Does not have to be created first
:-Not saved in the DAQ unless written to a valid cell
*Logstream
:-Log data action

===Data Output Methods===
Your data is the primary reason for simulation.

1. Default miniSim scenario measures
:- Immediately available

2. Alternate scenario measures (DAQ file)
:- Processed through data reduction

====Default miniSim Scenario Measures====
*Saved to a drive report.txt file
*Saved to the same Location as DAQ files;
:Scenarioname_timedatestamp_report.txt
•Measures calculated overall, and up to 20 Events during drive:
:Collision Count Lane Departure Count
:Maximum Speed Lane Departure Percentage
:Minimum Speed Speeding Count
:Average Speed Speeding Percentage
:Standard Deviation of Speed Average Headway
:Standard Deviation of Lane Position

====Default miniSim Scenario Measures Require Scenario Event Definition====
In order to capture meaningful data into the default miniSim measures, a scenario must be configured properly to define events.

Use the Write to Cell action to activate the default measures.

[[File:2021-07-02_11h02_44.png|400px]]

*At the start of scenario, set:
::SCC_EventStatus =0
::SCC_EventNumber = 0
*At the start of the first event, set:
::SCC_EventStatus = 1
::SCC_EventNumber = 1
*At the end of the first event, set:
::SCC_EventStatus = 0
*At the start of the second event, set:
::SCC_EventStatus = 1
::SCC_EventNumber = 2
*At the end of the second event, set:
::SCC_EventStatus = 0

Continue this pattern; at end of final event, set:
::SCC_EventStatus = 0

====Default miniSim Scenario Measures Sample Report====
The following is an example report for 4 events. Note the remaining events present in the report are all zeroes or -1.00.

[[File:default_measures_report.png|400px]]

===="Alternate" Scenario Event Definition aka Using Logtreams====
'''NOTE: This method is the more typical/standard method for defining events.'''

Defining an event is key to partitioning simulator data into useful sections. Processing these sections is the essence of '''data reduction.'''

These useful sections are partitioned using logstreams and are generally called '''Events''':
*A logstream is a data marker present in the DAQ file
:there are 10 logstreams
:use logstreams to indicate when things happen '''in the data:'''
:at the start of an event; i.e.,
::grab all data where logstream 1 = 100 (example value)
:during a sub-section of an event
:at the end of an event (typically clears to 0)

Logstreams help separate/filter data;
*SDLP is not useful during emergency maneuver events

Logstreams can be useful to debug events;
:marking in the data when triggers fire
:ensuring event counters work; these are typically sequential, so any logstream deviation identifies a problem

*How to define a Scenario Event:

Set logstream values at scenario event start
:during and at scenario event end, set or clear logstream values:
For example:
::logstream 1 for event ID
::logstream 2 for sequencing the event (during/within event)
::logstream 3 for restart number, etc.

*Requires data reduction to fully process drive data
*Does '''not''' support default measures
:unless those measures are used in parallel with the logstream method

*The use of logstreams allows a scenario author to encode event and environment information into the scenario and as a result, into the simulator data stream.

====Example Alternate Scenario Event====
This section contains an example of a scenario that uses logstream 1 to define an event and environmental context.

In the following example, logstream 1 (LS1) is used to:
#define the scenario start, which is also in this example the event start. NOTE: This is not typical.
#when the driver is 805f from the intersection halt line, set a value into LS1
#when the driver is 500f from the intersection halt line, set a '''new value''' into LS1 NOTE: This could also use a different LS than the one used to define your event, i.e., 1
#when the driver activates a roadpad trigger to reset a force velocity (FV) on a lead vehicle

[[File:event_def_LS.png|400px]]

In the following event definition, an expression trigger is used to set a logstream value and execute two additional actions pertaining to the event.

[[File:event_ET_LS3.png|400px]]

====How to Export Data from A DAQ file using ISAT====
ISAT can display and export DAQ data. NOTE: This is 'raw data', not previously processed. This method can be used to test scenarios, confirm or identify data issues.

TBC: example export here

=Terminology & Documentation=
This section contains terminology and references to related documentation.

'''Action''' - the basic scenario element; the basis for creating scenarios. Actions may be executed on scenario elements (dynamic or static), create or remove elements, or the environment (time of day, visibility) or the simulated cab instrument panel.

'''ADO''' - Autonomous Dynamic Object; self-controlling to a degree.

'''Cell''' - Data elements that are recorded to during a drive; some cells may be used by the scenario author. Custom cells may be added to miniSim.

'''Event''' - anything significant that happens during a drive where the driver condition or response is desired to be identified in the drive data. Can be isolated from general driving through default measures or logstreams.

'''ISAT''' - Interactive Scenario Authoring Toolkit; used to create scenario files for use on the NADS facility or miniSim simulators.

'''ISC''' - ISAT script file.

'''Scenario''' - The simulation experience during a drive; also known as a scenario file, which contains all instructions to the elements within a simulator drive.

'''SDLP''' - Standard deviation lane position

'''SOL''' - Scenario Object Library; objects that are available to ISAT during scenario authoring must be present within the sol2.txt or an auxiliary sol2 (sol2_aux.xxx.txt) file.

'''Trigger''' - A scenario element that contains actions to execute during simulation. All triggers share the same actions, but execution depends on the trigger type.

'''TTA''' - Time to arrival.

'''TTC''' - Time to collision.

=Reporting ISAT & Scenario Issues=
*How to report ISAT & scenario issues:

When reporting issues with scenarios it is helpful to provide as much information as possible.

This often includes scenarios (including any external reference files) and the .LRI file used by the scenarios, screenshots or video that demonstrate the issue being reported and relevant DAQ files. It can be very helpful to include coordinate information with the screenshot or video.

The .BLI file is created from the .LRI and is much larger than the LRI so it may be more convenient to send the LRI file. NADS staff can re-create the BLI file from the LRI.

Some graphics anomalies may be issues with the tile model and not a scenario or miniSim problem. These include:
#white block shapes in the environment
#gaps or missing geometry; i.e., holes
#improper lighting (dark features present during the day)

If these issues happen on a custom roadmap/database world, please include the TMT .mos file as well so NADS can re-construct your environment.

==How to contact the NADS miniSim team:==

email [mailto:miniSim-Support@uiowa.edu minisim support]

[mailto:andrew-veit@uiowa.edu Andrew Veit]
Director of NADS miniSim

[mailto:joseph-meidlinger@uiowa.edu Joseph Meidlinger]
Program Coordinator NADS miniSim

[mailto:oscar-hernandezmurcia@uiowa.edu Oscar Hernandez Murcia]
MiniSim Application Programmer/Analyst

[mailto:chris-schwarz@uiowa.edu Chris Schwarz]
Data Reduction & Vehicle Dynamics

[mailto:shawn-allen@uiowa.edu Shawn Allen]
TMT, Modelling & Support

==How to check what BLI file is used by a scenario==

#You can edit the scenario in a text editor; near the top of the file will be a line starting with '''LriFile''' followed by the name of the BLI file in double quotes.
#You can use '''grep''' to inventory single or multiple scenarios:
:grep bli <scenario file/s>
:A partial listing is shown in the example below. NOTE: The files shown will likely be different on your PC:
C:\NADS\Isat\data\training.demo_scn>grep bli *.scn
Demo_Expression_Lead_Vehicle_Variables.scn: LriFile "simple_rural.bli"
Demo_Expression_Trigger_to_Lead_Vehicle.scn: LriFile "simple_rural.bli"
Demo_HUDD.scn: LriFile "simple_rural.bli"
ISAT-Samples-Avoid.scn: LriFile "esc_dry_05.bli"
ISAT-Samples-Right-Incursion.scn: LriFile "esc_dry_05.bli"
ISAT-Samples-TrafficLightTest.scn: LriFile "simple_city1.bli"
ISAT-Samples-TrafficLightTestB.scn: LriFile "simple_city1.bli"
ISAT-Samples-YellowLightDilemmaB.scn: LriFile "simple_city1.bli"
KBW_TEST.scn: LriFile "simple_rural.bli"
KBW_TESTB.scn: LriFile "simple_rural.bli"
demo.createADO_and_trigger.scn: LriFile "simple_city1.bli"
demo.creation_radius1.scn: LriFile "simple_city2.bli"
demo_FV_sum_of_Sines.scn: LriFile "simple_city2.bli"
demo_LV_Decelerate.scn: LriFile "simple_city2.bli"
demo_LV_cut_in.scn: LriFile "esc_dry_05.bli"
demo_MG.scn: LriFile "simple_city2.bli"
demo_TM1.scn: LriFile "simple_city2.bli"
demo_TT_null.scn: LriFile "simple_city2.bli"
demo_actions_text.scn: LriFile "simple_city2.bli"
demo_alt_data_measures.scn: LriFile "simple_city2.bli"
demo_audio_virtual_object.scn: LriFile "esc_dry_05.bli"
demo_audio_virtual_object_simple_rural.scn: LriFile "simple_rural.bli"
demo_auto_cloud1.scn: LriFile "simple_city2.bli"
demo_coneISC1.scn: LriFile "simple_city2.bli"
demo_dddo.scn: LriFile "simple_city1.bli"
demo_dddo_B.scn: LriFile "simple_city1.bli"
demo_forXRef_traffic.scn: LriFile "simple_city1.bli"
demo_force_vel_01.scn: LriFile "simple_city1.bli"
demo_groupImport.scn: LriFile "simple_city2.bli"

==How to configure miniSim for screenshots to include coordinates==
You can enable coordinate display on miniSim by changing the focus to the main display. #Move the cursor until it is positioned in the main display area, then LMB. When successful the main display will appear to "blink".

Press the keyboard n key twice. This will cause coordinate information to display in the lower left corner of the main display.

[[File:miniSim_show_coords.png|400px]]

The n key is a toggle; to disable coordinates, press it twice (2x) again. '''NOTE:''' the cursor focus must be in the main display in order for this to work.

=Additional Resources=
[[:File:ISAT_Quick_Start.pdf|ISAT Quick Start Guide]]

[[ISAT_Demonstration_Scenarios|Demonstration Scenarios]]

[[:File:Create_Use_Custom_Cells.pdf|Create and Use Custom Cells on MiniSim]]

[[:File:Function_ReadCell_20180824.pdf|ReadCell function]]

[[:File:TrafficManager_Ch12.NADS.Internal_ISAT_UsersGuide.pdf|Traffic Manager]]

=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 [[ISAT_Reference_Manual_Table_of_Contents#ISAT_Reference_Manual|reference manual for ISAT can be found here.]]

ISAT User Guide Table of Contents

2023-09-15T14:46:31Z

Shawn Allen: /* Who should use this document? Change NADS to DSRI*/

== Who should use this document? ==
Anyone learning to use the DSRI 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
*CTL-<some other key> Press and hold the Ctrl and then press <some other key>. Most typically used for copy (CTRL-C) or paste (CTRL-V).
*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 and modify for use in your own scenarios as needed.

== <span style="color:#FF0000"> '''Known Issues'''</span>==

Added 2022.07.01 '''Relative Creation''' does not currently work for ADOs on miniSim.

'''Expression clarification'''

Increment and decrement operators (++, --) are not considered expressions by behaviors. They should not be flagged as expressions when used in the Value field of a Set Variable action.

Added 2019.11.07 '''File reset issue'''

ISAT has a long-standing bug which can reset your static object options when your scenario file is saved to disk.

'''It is strongly recommended that you use [[#External_Reference|external reference scenario files]] to avoid this. '''ISAT does not reset static object options in the xref file.

Added 2021.12.29 Expression Triggers and Values

'''Using Values in Expression Triggers'''

To ensure proper execution of expression triggers, it is recommended that the values used include the desired range by decreasing the lower threshold or increasing the upper threshold '''instead of using the exact value.'''

For example, to process values in a range (7031 - 7040):

[[File:2021-12-29_12h38_09.png|400px]]

'''Note: remember that negative values must be calculated since the expression parser does not parse negative values otherwise.'''

For example, to properly parse a specific transmission gear (Park):
'''ReadCell('CFS_Auto_Transmission_Mode', 1) = ( 0 - 2 )'''

=='''ISAT Overview & Interface Basics'''==
This section contains information about ISAT and the ISAT interface.

===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 <span style="color:#FF0000">'''not an object editor'''</span> 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.
[[File:miniSim_scenario_compnents.png|center|640px]]

*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.

[[File:anatomy_of_a_scenario.png|center|400px]]

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

[[File:scenario_as_text.png|center|640px]]

This diagram shows the same scenario in (left to right) 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, <u>always</u> check your edits in ISAT!'''
*Copy/Paste - delete paths from elements when the BLI is different between your source & destination BLI files. The following scenario elements contain paths:
::ADO (with a path specified)
:: Any roadpad trigger (roadpad, Time to Arrival, Follow)

'''NOTE: A Traffic Source is not a portable element but it can be re-created in ISAT or integrated into a new scenario by copying the element from the source scenario then using a text editor to paste it into the destination scenario'''

'''How can I find information in multiple files easily?'''

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.

What if you don't know what to look for? How do 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
[[File:action_overview.png|400px||border|caption]]

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)

==='''Adding an action to a trigger'''===

The following example uses a Time Trigger; remember that '''all triggers share the same actions'''.

To add an action to a trigger you can double-click on the trigger, navigate to the '''Actions''' panel, and click on New to create a new action.

[[File:2022-11-30_12h47_23.png|400px]]

The possible actions are listed under the '''Action Type''' drop-down menu.

[[File:2022-11-30_12h47_44.png|400px]]

Actions are arranged in a 'stack' and are processed from top to bottom. If you use multiple actions you should enable the '''sequential flag''' to ensure each action is executed in sequence. Without the sequential flag, actions will be processed as fast as the simulator behaviors can execute.

[[File:2022-11-30_12h52_58.png|400px]]

Actions may be re-ordered in the stack using the '''arrows''' located near the action stack list.

=='''ISAT Modes of Operation'''==
[[File:ISAT_modes_of_operation.png|400px]]

*Edit
*Rehearsal
*DAQ playback
*Monitor '''Currently not available'''

==='''Edit & Rehearsal Modes'''===

*Edit - this is where scenario authors will spend the most time.
::Creation or modification of scenario
::Link to or import portions of other scenario elements

[[File:mode_edit.png|400px]]

*Rehearsal
::Debug & test scenario
::Simulates scenario using Behaviors and Vehicle Dynamics
::Displays error messages from behaviors

[[File:mode_rehearsal.png|400px]]

'''NOTE:''' Rehearsal mode <span style="color:#FF0000">simulates </span>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

[[File:mode_playback.png|400px]]

==='''miniSim Scenario Components'''===

The following diagram shows an overview of scenario related components of the NADS miniSim and how these components work together.

[[File:miniSim_scenario_components_wDAQ.png|400px]]

=='''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.

[[File:isat_workspace_general.png|400px]]

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)
[[File:isat_status_bar_overview.png|400px]]

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.

[[File:isat_user_prefs_status_bar_settings.png|400px]]

====ISAT Iconography====
ISAT provides graphic hints for triggers placed in scenario that can be useful when editing or maintaining scenarios.

The general format is a border enclosing miniature icons of the trigger and first action contained in that trigger. Additional information representing one or many actions is also shown.

[[File:hints1.png|400px]]

ISAT will list all trigger actions when a trigger is selected, but these hints provide a way to quickly identify what actions have been authored.

[[File:hint2.png|400px]]

*A Roadpad trigger, one action: '''Traffic Light Action'''
*B Roadpad trigger, multiple actions, first action is '''Remove Element'''
*C Roadpad trigger, multiple actions, first action is '''Set Dial'''
*D Roadpad trigger, constrained to road (lane), no actions - this is an empty trigger
*E Roadpad trigger, multiple actions, first action is '''Log Data'''
*F Global Time Trigger, single action: '''Set Dial'''

[[File:handle.png|400px]]

The element handle is the red dot visible in most of the triggers.
The handle can be dragged into position, and the trigger will follow the handle

Drag the trigger off the handle to offset it's location from the handle

==='''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.

[[File:object_types_isat.png|400px]]

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
::*Traffic Source

:'''NOTE:''' Virtual objects are defined in the scenario, not in the SOL2.
[[File:object_types_world.png|400px]]

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.
::NOTE: 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.

==='''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:
#Follow a path using kinematics
#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:
#coupled
#relative trajectory
#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'''===
Traffic signals are objects with special operation and function; they are coupled to intersections and routes of travel through intersections to control traffic flow similiar to their function in the real world. Traffic signals are part of the source tile model and may not be re-positioned or physically altered by scenario except for their visual signal state appearance; i.e., red, green or yellow signals.

To control intersection traffic signals use Edit >> Traffic Light ManagerTraffic signals use a Signal State Table (SST) to control which signal states are active and when. Each intersection with traffic signals will have an associated SST.

[[File:traffic_light_state_manager.png|400px]]

The above diagram shows an intersection in the workspace to the right, and the traffic signal state table for that intersection on the left. At this point additional states (for signal condition) can be added by clicking the '''Add state button'''.

[[File:traffic_signal_state_table2.png|400px]]

The above diagram shows two states defined for the intersection, represented by the two columns of state condition.

Continue adding states until the desired signal cycle has been defined. Generally this consists of red, green or yellow states.

NOTE: There is currently no way to automatically author a series of traffic light signals

To author traffic signal lights in sequence or on a route, the scenario author has to manage the signal states

[[File:traffic_signal_state_duration.png|400px]]

To edit the signal state duration RMB on the duration field header and choosing '''Edit state duration''' on the context menu. Enter the desired value then click OK.

====Traffic Signal Types====
The ISAT status bar reports Traffic Signal Type name. There are two signal types:
#Standard signal - IDs may have no identifying information
:Valid signal states: Red, Yellow, Green, Flashing Red, Flashing Yellow, OFF
#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

[[File:traffic_light_extended_type_name_normal.png|400px]]
: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.

[[File:traffic_light_extended_type_name.png|400px]]

===Changing Signal States in Scenario===
Traffic signals are controlled in scenario by using a Traffic Signal Action to change the SST.

'''NOTE:''' The Traffic Signal Action works by changing the SST, '''not by changing the traffic signal.''' This is a subtle but important difference.

Setting a signal to an undefined state effectively does nothing to the traffic signal.

[[File:traffic_light_state_table.png|400px]]

The above diagram shows a fully populated SST, with one signal row highlighted in red, and one state column highlighted in green. The associated intersection corridor is highlighted, showing the signal controls a dedicated left turn.

During simulation, the initial signal state is defined by the left column. As the simulation proceeds, the signal state changes according to the duration states defined across the state table, proceeding left to right and then wrapping around to the beginning after the last defined state. Each traffic signal appearance changes according to the configuration of the SST.

As a driver approaches this intersection, assume the signal state is in the column left of the highlighted column ('''R'''ed), and the desired action is to change the signal to green.

The action used to change a traffic signal state is the '''Traffic Light Action'''.
Using a traffic light action requires the specification of a signal state, the traffic signal to affect, and a duration.

[[File:traffic_signal_action1.png|400px]]

In the above diagram the scenario author has specified the desired state as '''Green''' as shown in the action dialog.

However, referring back to the previous state table diagram, there is no such state present in the SST. That means this particular action will fail, and the traffic signal will not change as the driver approaches the intersection - because the action does not create a new signal state, it works by advancing the state table condition (column) to the specified condition. If the condition is not present in the SST then nothing will appear to happen.

In this example, the action should be edited to use the correct signal state '''Left Turn Green''', which is present in the SST.

'''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

[[File:known_issue_traffic_light_action.png|400px]]

'''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.

[[File:known_issue_traffic_light_action_workaround.png|400px]]

====Change A Traffic Light Using Scenario Action====
To change a traffic signal, use the Set Dial >> Traffic Light action.
'''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

[[File:traffic_light_state_table.png|400px]]

This diagram shows a fully populated traffic signal state change for an intersection.

*Static object traffic lights
:These are objects, not true traffic signals and so they are not controlled with the Traffic Light manager.

==='''Traffic Source'''===
A traffic source is a coordinator used to create traffic at specific locations in the road map (unlike the Traffic Manager). This is useful for creating ambient traffic. Traffic Sources creates ADOs or DDOs at random or user-specified intervals.

Elements created using a Traffic Source will be created at the locations specified by the user. If traffic is specified at multiple locations the actual location for each creation will be determined randomly during simulation.

'''Note:''' Using the Relative Creation flag on ADOs created by the traffic source will not create traffic at the specified location on the map, but use the information in the Relative Creation fields to populate traffic in the scene during simulation.

This method allows for more flexibility but care must be taken not to create so many ADOs that miniSim is unable to make frame rate. Too many ADOs will cause the scene to jump and 'jitter' and it will feel slower than normal.

==='''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 ISAT scenario rehearsal

===Custom (icon) file virtual objects===

[[File:virtual_object_custom_icon_file.png|400px]]

'''Note:''' Some versions of MiniSim_2.3 do not support custom virtual objects. For those installs, if you require this type of functionality, a workaround exists in the form of a 2D model that can be customized (i.e, sprite).

Virtual objects may be customized using graphics files (texture images) to display any desired custom element. This typically requires the use of a bitmap graphic. Various file formats are supported: JPG, BMP, PNG. It is possible some types of these formats may not work - in those cases, try an alternate format.

If image transparency is required and the custom icon does not display during simulation, please email dsri-minisim@uiowa.edu with a description of the issue, your scenario and custom virtual object image file.

Custom icon files must be located within the Nads MiniSim path for resources - at NadsMiniSim_x.x\data\visuals\Models\ModelTx.

===Standard virtual object shapes===
The virtual object shapes include:
# Circle
# Triangle
# Octagon
# Star
# Diamond
# Icon <- this is for custom virtual object graphics
# Rectangle
# Hexagon

The virtual object fill and border color and transparency can be set in the virtual object properties dialog panel.

[[File:virtual_object_std_shape.png|400px]]

====Virtual Object Workaround====

There is a scenario authoring method that can be used to emulate virtual object functionality through the use of a DDO that is coupled to any dynamic scene element, including the External Driver. One model has been created to support this method called "sprite".

'''Note:''' The sprite model is a 2D object present in the scene, and can therefore be occluded by other scene elements during simulation.

[[File:trafsign_sprite.jpg|400px]]

The sprite model is designed as a flat plane that continuously faces the viewer. It contains different sized planes and can be customized through textures.

When authoring your scenario, configure the sprite object to Off unless it should be visible at scenario start. During the scenario you can control the sprite appearance with a setSwitch action.

[[File:sprite_setSwitch_action_021121.png|400px]]

The who to effect should use the name of the DDO placed in your scenario. The switch name will be s_sprite as shown above. Any valid option can be used. An invalid option (greater than 30) will disable the sprite the same as selecting the OFF option.

==='''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'''===
<span style="color:#FF0000">'''All trigger types share the same Action types'''</span>
*IF Then conditional
*Predicate: i.e., the activating agent
:If predicate is TRUE, then do Action(s)
*Road related triggers are categorized by predicate type
:Named element
:Road (lane)
:Nth vehicle on path only

'''What trigger is appropriate?'''
To determine which trigger is most appropriate, consider the task you are trying to accomplish. '''The differences between triggers is their activation methods.'''

'''Global Time Trigger'''
[[File:isat_time_trigger.png|150px]]

Use this trigger when something has to happen at some point in time.

Time triggers are also useful as "placeholder triggers"; used to apply persistent actions to multiple elements with unique settings for each element. Normally a persistent action is the last action possible in a trigger since the persistent action fires continuously. Putting persistent actions into a time trigger allows the scenario author to continue an action stack in the parent trigger if necessary.

Time triggers can be used as a 'stopwatch' - elapsed time, such as ending a drive after 3 minutes by setting the trigger to fire using an Activation Delay of 180s (GTT >> General).

Often used as a placeholder for actions such as initializing variables, displaying text messages to the screen using Set Visual Display Text actions, etc.

'''Note''': A time trigger can have global elapsed time and activation delay of 0, which causes the action stack in the time trigger to activate when that trigger is created.

'''Roadpad Trigger'''
[[File:isat_roadpad_trigger.png|150px]]

Use this trigger when something has to happen at some location in the drive that does not require event timing to be comparable for all participant drivers. For cases where event timing must be comparable among all participant drivers use the Time to Arrival trigger (TTA) instead of a roadpad trigger.

'''Time to Arrival Trigger'''
[[File:isat_time_to_arrival_trigger.png|150px]]

Use this trigger when something has to happen relative to some point in the drive, and also ensure all study drivers experience the same event timing irrespective of driver style (conservative, slow vs. aggressive, fast). Time to arrival (TTA) trigger uses a time calculation from the trigger pad activation to a target location specified in the trigger.

'''Traffic Light Trigger'''
[[File:isat_traffic_light_trigger.png|150px]]

This trigger activates actions when the specified traffic signal state is reached. For example, if the desired action is to create a DDO pedestrian to step into traffic when the traffic signal is yellow, then the Traffic Signal Manager must be used to author the appropriate signal states for the traffic signal.

Typically some other trigger is used to control the traffic signal (ie, to change the signal to Yellow on approach). It is therefore perfectly valid to put the actions within this other trigger rather than relying on the traffic light trigger.

'''Note''': Once a traffic light action has been authored, ISAT may be prone to crashing when accessing that trigger. This problem can be avoided by creating a time trigger and isolating the traffic light action there, allowing the parent trigger to be modified without crashing. Adjustments can be made to the traffic light action time trigger in a text editor, or recreated if it becomes necessary to make adjustments and ISAT continues to crash when trying to make edits.

'''Note:''' The traffic light action does not change the traffic signal state, and it requires a valid state sequence to exist in the signal timing table (Edit >> Traffic Light Manager). The traffic light action '''will not create a signal state''' that does not already exist in the signal timing table.

'''Expression Trigger'''
[[File:isat_expression_trigger.png|150px]]

Use this trigger when something must be monitored, evaluated or calculated such as checking a variable or cell value, velocity of the driver or the state of simulator hardware (steering wheel angle, brake or accelerator pedal position) or distance from the driver to some other object in the scenario.

Multiple expressions can be used within the same expression trigger. In those cases, all expressions must evaluate to True in order for the action stack to execute unless using an '''OR''' operator.

Use the '''OR''' operator - the pipe character "|" if you want to activate the action stack if '''any''' of the expressions evaluates to True.

In the following example, the trigger checks for TrialNumber = 1 and FirstButtonPress variables, and then checks if Aux Button 1 or 0 was pressed:

'''ReadVar('TrialNumber') = 1.0 & ReadVar('FirstButtonPress') = 1.0 & (ReadCell('Auxiliary_Buttons', 0) > 0 | ReadCell('Auxiliary_Buttons',1) > 0)'''

'''Note''': Expressions can also be embedded into some other triggers, most notably the Set Dial >> ADO >> Forced Velocity action often used in Roadpad triggers.

'''Follow Trigger'''
[[File:isat_follow_trigger.png|150px]]

Use this trigger when something has to happen based on one ADO position relative to another scenario element (including the XD). The follow trigger requires a leader and a follower to be specified; when this condition is met, the trigger action stack activates.

'''Note''': Both leader and follower must be positioned on the follow trigger roadpad to satisfy the follow parameters.

'''Geometric Position'''
[[File:isat_geometric_position_trigger.png|150px]]

This trigger is most useful to perform actions for off-road actors such as walkers. The trigger predicate is limited to Name or Type and requires a geometric position to be defined.

A more limited version of the geometric position trigger can be implemented with a Global Time Trigger that contains a Creation Radius. Placing the creation radius defines the area where the trigger may be activate.

===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

[[File:Screenshot (208).png|800px]]

'''Note:''' The highlighted lane shows which lane is the '''activating lane'''. Other lane/s will not activate the trigger action stack.

===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

[[File:TTA.png|400px]]

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===

[[File:other_triggers.png|400px]]

*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===

Execute actions if input expression evaluates to TRUE; the expression is specified on the trigger Predicate tab.

====Syntax====
Expression triggers support a simple language syntax with operators and functions.
The syntax is infix notation; i.e. a + b, not a b +.

Note: It is not generally possible to embed one function call inside another:
cos(sin(x)) is therefore an invalid expression. ISAT will report invalid expressions during rehearsal of a scenario. Invalid expressions are not supported and will not operate as written during simulation.

'''Exception:''' Currently it is possible to use the square root function with GetObjDistPow2 as in the following example:

sqrt(GetObjDistPow2('Target_Object_Name'))

Multiple expressions may be combined using the logical AND (&) or OR ("|" pipe character).

Exp1 '''&''' Exp2, Exp1 '''&''' Exp2 '''&''' Exp ''N''

All expressions must be true for the trigger to evaluate to TRUE and execute the action stack.

Exp1 '''|''' Exp2
One of the expressions must be true for the trigger to execute the action stack.

Negative values are not directly supported by the expression parser. To use a negative value, it must be a calculated value such as the following:

'''ReadCell('CFS_Steering_Wheel_Angle',0)<(0-5.0)'''

==== Operators ====
Operators are used to create expressions.

'''String'''
:Used within quotes as a string literal; i.e., 'some string'

Grouping
:Parentheses group elements together; i.e.,
:'''()'''; (a), (a + b)

Multiplication
:'''*'''; a * b

Division
:'''/'''; a / b

Addition
:'''+'''; a + b

Subtraction
:'''-'''; a - b

Note: negative values must be expressed with a subtraction operation:
(0 - 5), not -5 (invalid)

Greater than
:'''>'''; a > b

Less than
:'''<'''; a < b

Logical And
:'''&'''; a & b

Both a and b, otherwise returns 0 (FALSE)

Logical Or
:'''|'''; a | b

a or b returns 1 (TRUE)

====Expression Functions ====
Functions are used with operators to create expressions.

Function: '''sin'''
:sin -sine

Syntax
:sin(float x)

Description
:The sin() function returns the sine of x, where x is given in radians.

Return Value
:The sin() function returns a value between -1 and 1.

Function: '''cos'''
:cos –cosine

Syntax
:cos(float x)

Description
:The cos() function returns the cosine of x, where x is given in radians.

Return Value
:The cos() function returns a value between -1 and 1.

Function: '''ReadCell'''
:ReadCell()

Read a Cell value.

Syntax
:ReadCell(string Name, int Cell Array index)

Description
:ReadCell returns the value of a given cell (a cell is the current instance of a variable that will be maybe written to a daq file).

Index specifies a 0 based index into the array. Since most cells are single element arrays, a value 0 indicates the first element.

Cells valid for the ReadCell function are defined within the cell collect file NadsMiniSim.cec located in the miniSim_x.x\data folder.
The ReadCell function operates on shared memory during simulation, it does not read cell data from the DAQ file.

Cells that are defined may be written to the DAQ; the collect file specifies which cells are saved into the DAQ and what frequency to use for the write operation.
The NadsMiniSimCollect.general.txt file is located in the miniSim_x.x\data folder.

Available Cells:
Any cell that has been defined in the .cec file. For example:

:'''LogStreams''': Array of 5 floats. Logstreams are a set of values the scenario author can write to through “write to logstream” actions.
:'''AccelPedalPos''': Single Value. The current position of the accelerator pedal
:'''BrakePedalForce''': Single Value. The current force on the brake pedal in pounds
:'''SteeringWheelAngle''': Single Value. The current rotation of the steering wheel
:'''CruiseControl''': Single Value. The current cruise control position. (values are cab/platform specific)
:'''TurnSignal''': Single Value. The current position of the turn signal (values are cab/platform specific)
:'''OvVel''': Single Value. The participant’s current speed in miles per hour
:'''OvLaneDev''': Single Value. The participant’s lane deviation in feet.
:'''OvHeadwayToLeadVeh''': Single Value. The distance in feet to the first vehicle in front of the participant. -1 if no vehicle can be found.
:'''OvTtcToLeadVeh''': Single Value. The time to collision to the first vehicle ahead of the participant.
:'''Horn''': Single Value. The state of the horn (values are cab/platform specific)
:'''DynObj_Vel''': Array of 20 floats. The speed of a given dynamic object. Dynamic Objects are sorted in terms of distance to driver.
:'''OvVelLocal''': Single Value. The participant’s current speed in miles per hour, using the value local to scenario control

For a complete list of cells and array elements please see the miniSim data dictionary spreadsheet.

Return Value
:Returns the value of the specified cell.

Example
ReadCell(‘LogStreams’,5) > 3

Function: '''CellEquals'''
:Cell Equals, array element, value to compare

Syntax
:CellEquals(string name, int index, float value)

Description
:The Cell Equals function is similar to the ReadCell function, except it adds an additional value to compare against the cell value.

Like ReadCell, name specifies the name of the cell, index specifies the cell array index (use 0 for single value cells).

Available Cells:
:Any cell that is defined in the .cec file.

Return Value
:Units: 1 or 0
:1 if the cell value is equal to the passed in comparison value; otherwise 0

Function: '''GetObjDistPow2'''
:Get object distance squared

Syntax
:GetObjDistPow2(string name)

Description
:GetObjDistPow2 returns the distance squared between the external driver and the dynamic object specified by ‘name’.

Distance squared is used to avoid having to perform an expensive square root calculation every frame.

If the specified object cannot be found, a value larger than 100 million is returned.

Return Value
:Feet; Distance in feet measured from the eye position of the driver to the CG (centroid) of the dynamic object specified.

A very large number is returned if the specified object cannot be found (larger than 100 million)

Example
:GetObjDistPow2(‘OncomingCar1’) < 2500

'''Note:''' To get an actual distance, multiply by the square root (sqrt())
: sqrt(GetObjDistPow2('Target_Obj'))

Function: '''GetObjTtcToOv'''
:Get Object Time To Collision to Own Vehicle

Syntax
:GetObjTtcToOv(string object name)

Description
:GetObjTtcToOv gets the time to collision from the dynamic object specified by the name parameter, to the own vehicle.

Return Value
:Unit: Seconds
:Time (seconds) to collision from the own vehicle to the dynamic object specified by the name parameter.
:0 is returned if the object specified cannot be found.

Function: '''GetObjVel'''
:Get Object Velocity

Syntax
:GetObjVel(string object name)

Description
:GetObjVel gets the velocity in meters per second of the first dynamic object with the name specified by the ‘name’ argument.

Return Value
:Unit: Meters per second
:The speed of the specified dynamic object; 0 if no object is found

'''Note:''' Multiply by 2.23694 for miles per hour.

Example
:GetObjVel(‘PullOutVeh’) > 15.4

Function: '''Rand'''
:Random

Syntax
:Rand(int value)
:Rand(string name)
:Rand(string name, string type, double parameter, double parameter)
:Rand(string name, string type, int parameter, int parameter)

Description
:Rand returns a random value specified by the name of the generator, the type of distribution and its parameters.

If the user does not specify the name of the generator and only specifies a number as the only parameter, the Rand function will use a default random number generator to produce random numbers.

If the user only enters the name of a user created random number generator, the random number generator will produce a value between 0 and 1.
If a name of generator is supplied that has not been created, the Rand function will display an error message in the ISAT debug window and return 0 (during scenario rehearsal).

The rand function supports multiple types of distributions that can be used to generate a random number.

Types of Distributions:
:normal: Normal Distribution(mean, standard deviation). The normal distribution generates random numbers near the mean with a specific standard deviation.
:gamma: Gamma Distribution(alpha, beta). The gamma distribution generates a random value that models waiting times for the Poisson process.
:uniformInt: Uniform Integer Distribution(min, max). The uniform integer distribution generates a random integer number between the lower and upper bounds.
:uniform: Uniform Real Distribution(min, max). The uniform real distribution generates a random floating point number between the lower and upper bounds.

The values stated in the parenthesis above are the parameters for each distribution in order. If the incorrect number of parameters are entered or if they are entered incorrectly, the debug window in ISAT will display an error message and the rand function will return 0 (during scenario rehearsal).

If the distribution is entered incorrectly, the debug window will also display an error message.

Return Value
:A random value from 0 to 1 if the type of distribution is not specified.

If the type of distribution is specified, returns a random value determined from the type of distribution and the given parameters.

Example
:Rand(‘myRandGenerator’,’uniformInt’,1,10)
:This example returns a random integer value from 1 to 10.

Rand(5) or Rand(‘myRandGenerator’)
:These examples return a random value between 0 and 1.

Function: '''sqrt'''
Square root

Syntax:
:sqrt(parameter)

Return Value:
: return the square root of the specified parameter.
: parameter can be another function, such as GetObjDistPow2()

Function: '''ReadVar'''
:Read a variable

Syntax:
:ReadVar(string Name)

Return Value:
:Returns the string value of variable specified in <variable_name>

===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.

=='''Audio Components'''==
The components of the Audio sub-system includes configuration and data files installed into the NadsMiniSim_x.xx\data\sound\DefaultCabSound\Instructs folder.

[[File:audio_components.png|400px]]

The audio engine contains multiple channels and has a theoretical limit of 512 simultaneous sounds.

NOTE: Not all .wav files are compatible with the Audio Engine.

=Scenario World Objects=
Scenario world objects are defined in the tile model source. They are not added by the scenario author since they are objects already present in the roadmap/BLI.

[[File:object_types_world.png|400px]]

Typically, but not always, these objects can be authored in ISAT. However, some scenario world objects have no options - these cannot be selected in ISAT; therefore such objects cannot be authored.

Removal of world objects requires editing the source tile model using a 3D application. In some cases an alternate tile model is available identical to the original but without objects.

Contact NADS if removal of a world object is needed.

Other scenario world objects, such as Traffic Signals, are specialized function objects that can be authored. Traffic signals are authored using the Traffic Light Manager: Edit >> Traffic Light Manager.

=Troubleshooting Scenario Objects That Reset=

== Scenario World Objects ==
Scenario world objects are already present when you create a new scenario - they are not added by the scenario author. These objects may be visible in miniSim but not in ISAT, or they may be visible in ISAT and seem to be controllable, but the objects 'reset' to their defaults when viewed on miniSim.

[[File:2019-10-23_16h18_47.png|700px]]

The objects which 'reset' are a symptom of settings in the TMT that are not configured to allow scenario authoring of objects.

[[File:2019-10-23_16h18_52.png|700px]]

When objects appear to 'reset' or if you can edit an object in ISAT but don't see your changes in miniSim, correct the problem by resolving controllability in the TMT settings: https://www.screencast.com/t/ZH5Dh178.

=Scenario Coordinate Types=
There are two types of coordinates used in scenarios. The first is roadway coordinates. These coordinates are contextual (tied to a specific road or intersection and position) and are used for ADO objects and roadpad paths in general.

After a roadway coordinate has been generated, it is not updated unless the scenario author makes changes to the start, end or location of the entire path or pad.

Roadway coordinate are the reason it is not possible to change a roadmap using the TMT and expect a previously authored scenario to work on the altered roadmap. If the length or location of a road changes, the path/pad will update to the extent possible.

If the road has been eliminated and no longer exists in the roadmap/BLI, ISAT will report an error and not open the scenario file.

A. Field breakdown:
RoadPos keyword <name of road:lane:position on road:path length>

Name "Ado1"
RoadPos "r1_-6600_4620:0:5737.06:0.00"
Path "R:r1_-6600_4620:0[5736.06:5873.83]"

[[File:isat_coordinate_types.png|400px]]

B.
Name "VirtObj"
Option 2
Position -6.8375599E+002 5.6331237E+003 0.0000000E+000

The second type is world coordinates, which are Cartesian coordinates with X increasing to the right, Y increasing forward, and Z increasing up.

='''Scenario Authoring'''=
Scenario authoring is the creation, editing and testing of everything that happens during a simulation drive.

==Cell Operations: Best Practice==
Reading and writing to cells is a computationally expensive process. Best practice is to centralize all the reads/write to one place so that it’s only done once per cell.

Once a cell is read, the value is copied to a variable and only the variable is used throughout all the triggers that need it.

The same process applies to writing to cells. Use of variables can reduce the Cell Operations overhead greatly.

==Before You Begin==
Before beginning a scenario, it is necessary to understand the following requirements:

=== Drive Requirements===
How long is the drive?
What type of roadway?
Are there any specialized road elements (intersections, interchanges, freeway ramps)?
Are there any environmental requirements (should the simulation replicate a real world location, or is a generic environment acceptable)?
Is there a particular roadway configuration that is needed (long straight rural road vs. typical urban environment with intersections, signals, etc)?

=== Traffic Requirements ===
What types of traffic will be needed?
Will ambient traffic interact with the external driver?
What types of interaction will be required (traffic cloud, lead vehicle, follow vehicle)?

=== Events ===
The purpose of an event is to present a situation to the external driver. In order for the simulation to produce meaningful data, it is critical that events unfold for each driver in a comparable way. Therefore, each event must be designed with this repeatability in mind.

'''NOTE:''' one of the most variable scenario elements is the driving style of each external driver: how conservative or aggressive they drive, velocities throughout the scenario, how comfortable the driver is travelling with simulated vehicles, etc.

Repeatability often includes static elements (each driver encounters scenario elements in the same location) or in cases where the driver performance is taken into account, accommodation of the driver dynamic (velocity, lane position) through the use of time to arrival triggers (TTA) or follow triggers. A TTA trigger will fire based on time to a target location - thus a driver travelling at 45mph or a driver travelling at 55mph can both experience the same action relative to that target location, irrespective of the different driver velocities.

==Beginning A Scenario==
All scenarios designed to be driven require a start location - the place where the driver will be located when the simulated drive begins.

To insert a start location into a scenario:

:Insert >> External Driver >> LMB on road, intersection or terrain object

[[File:isat_initial_position.png|400px]]

'''NOTE:''' scenarios that only contain data and are not intended to be driven - for example, signs or traffic that are used as external reference files do not require a start location, since that will be defined within the parent scenario.

==Initial Conditions==
Initial conditions define how the simulated scene is configured: will the drive occur during daylight or night time conditions? Will the ownship (external driver vehicle) have headlights enabled? What type of vehicle will it be? Will there be objects or traffic visible to the driver?
These form the initial conditions of the simulation experience. Additional initial conditions would include initialization of variables or establishing networked communication as needed by the scenario.

[[File:isat_initial_conditions_miniSim.png|400px]]

By default ISAT sets the initial condition '''Time of Day''' to 12:00 noon. The time of day is controlled from the Initial Conditions dialog:

Edit >> Initial Conditions

[[File:isat_initial_conditions_scenario.png|400px]]

==Scenario Authoring: Actions==
Actions are the scenario elements that make things happen during simulation. Actions do specific things, like display a text message on screen for the driver, create a scenario element, change the velocity of simulated traffic, change a traffic signal, etc.

[[File:trigger_action_panels.png|400px]]

The diagram above shows the action panel for left to right: an expression trigger, a roadpad trigger and a global time trigger showing different panels based on the actions present in each trigger.

'''NOTE:'''Actions can be created, edited or removed from the '''Actions panel''' of '''any trigger'''.

'''NOTE:''' The Actions panel changes based on the action type created.
When multiple actions have been defined, control the sequence of actions by changing the action order in the list using the up or down arrows next to the list.

[[File:action_panel_overview.png|400px]]

If multiple actions need to happen in a specific order, set the order using the arrows and then flag the action list as '''sequential'''. This instructs behaviors to process the actions in the list order.

Using a delay for any action will pause processing of the '''following actions'''; the action happens first, then the delay is applied.

===Scenario Authoring: Action Types===
There are two types of actions:
# Instantaneous - the action takes up to one frame to complete, i.e.:
:set target velocity
:write to cell
# Persistent
<span style="color:red">'''*Persistent actions do not end'''</span>, or take multiple frames to complete:
:Forced lane offset
:Forced velocity
:Maintain Gap

==='''Actions'''===
*The "Who to Affect" field defines what is affected by the action
:Instigator set: who activated the trigger
:Name: one or more named elements
:Type: Apply changes to all objects matching the specified type
:Relative: Position relative to the trigger location

*Sequential
:Actions to execute sequentially, one after the other
:Specify delay between actions
:: Action executes, then delay

:Some actions are persistent and never "finish"

===Scenario example: display text & roadpad trigger to stop the drive===
This scenario is very simple and contains a global time trigger (GTT) that tells the driver what to do. After the driver travels along the roadway, a roadpad trigger (RPT) is used to tell the driver to stop driving. The same RPT also creates an expression trigger to terminate the drive.

TBC example scenario file

Because the external driver is not under control except by instructions, it's possible they might ignore the halt message and continue driving. A second failsafe RPT then terminates the drive.

==='''Actions: Button vs. Dial'''===
*Dial changes a setting
*Button: always runs in a single frame
:-"immediate" change. Typically buttons have less control than a '''Set Dial''' action

==='''ADO Actions'''===
[[File:ado_action_types_button_vs_dial.png|400px]]

==='''DDO Actions'''===
[[File:ddo_set_dial.png|400px]]

==='''External Driver Actions'''===
External driver behavior can be influenced by reinforcing scenario actions through audible speeding alerts, on-screen text instructions and messages or audio instructions.

Driving behavior can be influenced with situational elements
:Car in the drivers blind spot
:Lead vehicle
:Aggressive following vehicle
:Temporary lane closure
:lane specific instructions

Scenarios should '''not rely on specific driver actions to be successful'''
:to the extent possible; sometimes you do need the driver to respond/behave in a controlled manner.
:A work zone blocking one lane typically will require a roadpad placed upstream from the work zone to shift traffic into the correct lane

'''NOTE:''' Controlling driver actions should be an experimental design consideration.

==='''Special Actions'''===
These actions need special handling:
*Reset or "toggle":
:Audio
:Display Text

:'''Ado'''
::Audio State
::Forced Velocity
::Maintain Gap
::Visual State

*If using these persistent actions, place them at the '''end''' of an action sequence (because no action following these will execute):
:Forced Lane Offset
:Forced Velocity
:Maintain Gap
:Visual State

*Note: If the Visual State action contains a duration then it will be handled as a normal action, with subsequent actions firing after it. However, if there is no duration supplied with the Visual State action it behaves like a persistent action, and nothing following it in the Action stack will ever fire.

[[File:multiple_simultaneous_actions.png|400px]]

The diagram above shows how one parent trigger can be used to create multiple simultaneous triggers

*How to activate multiple unique force velocity (FV) or maintain gap (MG) actions:
#create the needed triggers from a general parent trigger, 1 per action
#put common actions into the parent trigger
::reset FV
::reset MG

==Scenario Authoring How To==
This section contains simple examples for various typical scenario situations.

===How do I specify an event?===
First, determine which method is best for you - the default measures (limited measures, 20 events max) or logstreams (all simulation data, no event maximum).

Regardless of method, you specify an event by identifying areas of significance in the drive and marking them so the data within the event region can be processed. Any trigger combination that can specify event start and event end may be used.

[[File:2022-07-01_11h21_52.png|400px]]

===How to know Which Coordinator or Trigger I need?===
The answer to this question lies in the type of information needed for an event:

*Time
:global time trigger
:or an expression trigger that calculates time
*Position or Location
:roadpad trigger
::or a time to arrival (TTA) trigger
::or an expression trigger that calculates distance
*Calculation
:Expression trigger

===How to Instruct the External Driver===

Instructions to the external driver can be accomplished by three main methods:
# Instruct the driver using experimental protocol (instructional or briefing presentation)
# Information messages displayed on screen: '''Action: ''set visual display text'' '''
# Information messages delivered as audio messages: '''Action: ''write to cell > SCC_Audio_Trigger ><audio ID>'' '''

===How to Add Traffic in the Scene ===

Generating traffic will happen in one of 5 ways:
# Created explicitly by inserting ADO, or copy/paste existing ADOs
# Created with a script
# Via a Create action inside a trigger, or placing scripted traffic inside a create action within a trigger
# From a '''Traffic Source'''*
# From the '''Traffic Manager'''**

Each of these methods has advantages and disadvantages.

==== Create Explicitly ====

The biggest advantage with this method of traffic creation is the high degree of control the scenario author has over:
# location of the created ADO
# Name of the created ADO
# Travel path of the created ADO
# Control when each ADO is created within the scene via Settings >> Creation Radius

The disadvantage is that creating a high volume of traffic will take some work with this method.

==== Created with a Script ====

This method combines the advantages of Creating Explicitly with volume. It is possible to create a large volume of traffic very easily with a script.

Disadvantages of using high volumes of traffic with a script: in the event it becomes necessary for a high degree of control over these ADOs, more is not better because ADOs will adapt to road conditions under their own power, unless the default ADO settings have been modified:
'''lane changes, including lane changes to accommodate freeway ramps'''
'''velocity adjustments'''

==== Via a Create action inside a trigger ====
Combines the advantages of the previous 2 methods with control over when to activate that traffic using a trigger action.

Disadvantages: Creating too many ADOs at one point in the drive can cause the miniSim to bog down for a few frames. If too many ADOs are present and active in the simulation at one time, this can cause the miniSim to drop frames and run sluggishly. This is highly noticeable and may increase the potential for the External Driver to experience '''simulator sickness.'''

==== From a '''Traffic Source''' ====

Traffic Sources rely on two methods to populate a scene with traffic:
# location specific, with each ADO created for a traffic source being a 'spawn location' for ADOs, or
# location agnostic if the ADO has '''relative creation''' enabled, thus being created relative to the object identified.

In addition to being created relative to a scenario element, ADOs are created relative to the specified scenario element:
# In front of (Longitudinal Distance > 0, where the number is feet offset from the object) , or
# Behind (Longitudinal Distance < 0, where the number is feet offset from the object).

Advantages: Can easily populate traffic into the simulation.

Disadvantages: It is easy to generate more traffic than the simulation can maintain at 60Hz frame rate, thus introducing frame lag with the resulting scene 'stutter' and the increased risk of simulator sickness.

Also, traffic created from a Traffic Source is generic traffic. It is not possible to reliably refer to specific ADOs generated from a traffic source except by using Who To Affect >> Relative (versus referring to a named ADO, i.e. Slow_Moving_Lead_Vehicle). Referring by name to Traffic Source generated ADOs will affect all similarly named ADOs at the same time.

==== From a '''Traffic Manager''' ====

The traffic manager interface is problematic in ISAT versions up to 1.8.5, especially when specifying the set of vehicles to be used for generating traffic.

Advantages: Create generic ambient traffic easily.

Disadvantages: Has the same disadvantages as traffic created via a Traffic Source. Also getting a traffic set working by specifying the vehicles to be used within the set. ISAT versions up to 1.8.5 exhibit instability when setting vehicles in ISAT.

Traffic Manager Set workaround: Borrow a working set from an existing scenario or group. Alternatively use a version of ISAT (1.8.6 +) to create the traffic set. This can be saved as a scenario or group file, which can then be used with ISAT 1.8.x as long as there is no attempt to adjust the vehicle weights within ISAT. The scenario or group file can be edited as text in a text editor, but care must be exercised to avoid introducing errors into the file. ISAT will not read invalid scenario or group files.

Traffic generated by the Traffic Manager is controlled through the use of Input Sets. An input set is a collection of vehicles and weights used to populate the scene during simulation. This is how the scenario author can control the vehicle population (type and number), density and creation/deletion distances - these attributes are unique to each set.

Since there is no 'discontinue traffic manager' function, one can be implemented by defining an input set with no traffic (an empty input set). An appropriate name can make the purpose of the set clear: PauseTraffic, Stop_TM, etc.

==== Sample Traffic Manager Set ====
This is a sample traffic manager set that can be pasted into a scenario file after the HCSM VehFail section. Be sure to paste '''after''' the HCSM VehFail end tag ('''&&&End&&&''') in your scenario file.

'''Note:''' A scenario file may contain only '''one''' Traffic Manager section.

There are two input sets in this example; note how they contain different vehicles and different settings from each other.

<span style="color:#2a4b8d">HCSM TrafficManager
GroupName "Traffic Manager"
HCSM InputSet
Name "ONE"
MinDensity 3.0000000E-002
MaxDensity 7.0000000E-002
MaxObjects 9
CreateDist 2.0000000E+003
DeleteDist 3.0000000E+003
AbsDeleteDist 3.4000000E+003
RunFreq 1.0000000E+000
SolWeights "cargill_semi_peterbilt_blu:2" "cargill_semi_freightliner_red:1" "cargill_semi_peterbilt_yel:3" "DumpTruck_org:3" "semi_peterbilt_yel_Walmart:2" "Cadillac_Escalade:10" "Ford_F150Xcab:15" "Saturn_Vue:10" "FordTaurus:15" "Escape:15" "DumpTruck:2"
&&&&End&&&&
HCSM InputSet
Name "TWO"
MinDensity 1.0000000E-002
MaxDensity 3.0000000E-002
MaxObjects 4
CreateDist 2.5000000E+003
DeleteDist 3.3000000E+003
AbsDeleteDist 3.5000000E+003
RunFreq 1.8000000E+000
SolWeights "Taurus2011:12" "Cadillac_Escalade:16" "Ford_F150Xcab:24" "Saturn_Vue:14" "Escape:6" "Deville:24" "Audi:4"
&&&&End&&&&
&&&&End&&&&
</span>

====='''Managing Traffic Manager Input Sets'''=====
During simulation, Input sets are controlled by the action '''Use Traffic Manager Set'''. A set name must be provided for this action to work.

===== Traffic Manager generated Traffic=====
ADOs will populate the road network around the XD based on the parameters of the Input Set. Typically traffic is removed from the scene shortly after passing the XD. This is visible in the rear view mirror. There is currently no way to adjust this delete distance.

====== Traffic Manager Traffic on 2 lane freeway======
Traffic will prefer to be in the XD lane, so ADOs created in any other lane will tend to veer into the XD lane. On a divided highway, traffic is generated moving with the XD.

====== Traffic Manager Traffic on 2 lane road======
Traffic is generated in the oncoming lane. In some cases traffic may be generated then immediately removed in front of the XD.

===How to Control Objects in the Scene during Simulation ===
"Set and forget" options on simulation entities only require the scenario author to "initialize" the element to a desired setting and then it is left alone during simulation.

Controlling objects dynamically during simulation requires the scenario "talk to" each object with a scenario action. This section describes how each scenario object type can be controlled during simulation within a scenario.

All models used in ISAT are listed within the Scenario Object Library (sol2).txt files. Terrain switch names are displayed in the ISAT workspace.

All model switches are listed within the NadsMiniSim_x.x\bin.x64\ModelList.txt file.

'''Note:''' The diligent reader will note discrepancies in model names between the sol2 and ModelList files. This is because the ModelList file contains actual file names, and the sol2 files define a "name label" for models that may, or may not, be the actual model name. Objects are linked between the sol2 and ModelList files through the ModelID/CigiID records. These values will match between sol2 and ModelList files, but IDs are not necessary at this time for scenario authoring purposes.

Complicated object names can be retrieved from the LRI file that was used to build any scenario file; each BLI is preceded by an LRI. The LRI contains all of the terrain models that will be present in ISAT. These are typically speed limit signs, traffic signals or other features that may be controllable.

'''Note:''' this file may not be present for the Springfield.bli file.

An alternative is to capture a screenshot of the ISAT workspace with the element name string showing. By default ISAT reports the name of any objects when the cursor passes over the object, as shown in this example:

[[File:2021-10-27_08h50_14.png|caption =Object Name Screenshot | 400px]]

{|class="wikitable"
|+ Controlling Scenario Elements During Simulation in Scenario
!Date
!Nads miniSim version
!Object Type
!Scenario Action
!Who To Affect
!Value
!Notes
|-
| Oct. 28, 2021
|2.3
|-
|
|
|Static Object (terrain)
| SetDial > StaticObjManager > Set Option1
| StaticObjManager
| switch name : switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
|Static Object, multiple options
| Set Switch
| Name of element
| switch option
|-
|
|
|Obstacle, multiple options
| Set Switch
| Name of element
| switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
| DDO, multiple options
| Set Switch
| Name of element
| switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
| ADO
| Set Dial > ADO > VisualState
| Name of element
| Limited to options present in ISAT
|-
|
|
| Traffic Signal
| Traffic Light
| Assign action to element
| Target state
| Target state must exist within the Traffic Light Manager intersection timing table for the specified signal

|}

===How to Control Simulated Vehicles===
The scenario author can control simulated vehicles by controlling the environment:
#change a traffic signal to cause an ADO to stop or start at intersections
#affect other ADOs to cause a target ADO to respond
# assign a path for the ADO to travel

Direct control:
*Lane related:
:Set button > ADO > ChangeLane, Turn, ProjectAndResetLane

*All other controls:
:Set Dial > ADO > AudioState, ForcedLaneOffset, ForcedVelocity, InhibitLaneChange, LaneChange, MaintainGap, TargetVelocity, VisualState, AudioState

====How to Change ADO Velocity====
ADO velocity can be changed using the SetDial action:
:SetDial > ADO >

:ForcedVelocity
:ForcedVelocity using an expression:
# match external driver speed
expr % OvVel(0) %
# multiply external driver speed
expr -1 9 %ReadCell('OvVelLocal',1)*1.75 %
:TargetVelocity

Indirect Control (dependent on other scenario element):
:MaintainGap

====How to Link ADO Velocity to Something Else====
ADOs velocity can be linked to other ADOs or the external driver using the MaintainGap (MG) action.

SetDial > ADO > MaintainGap

When using a traffic cloud containing multiple ADOs, each ADO in the cloud needs a unique MG. IF multiple ADOs have the same MG settings they will attempt to satisfy their parameters and likely oscillate position in a visually obnoxious way.

===How to Author Loop Scenarios===
A scenario created on a loop road network operates very much like any other scenario, with the exception that it is likely to require tracking the number of times through the loop, or to present scenario events to the external driver depending on each loop context.

[[File:loop_traffic_creation_01.png|400px]]

The simplest method of tracking loops is the use of a loop counter variable. This variable can be set by the driver "stepping onto" a roadpad trigger or it can be initialized through the use of a timer or expression, with increments managed by a roadpad trigger. Each time through the loop increases the loop count variable.

Thus it becomes possible to create events for each loop based on the loop counter variable, typically through an expression trigger.

Loop management triggers

[[File:loop_management_02.png|400px]]

Loop management trigger detail one

[[File:loop_management_vars_02b.png|400px]]

Loop management trigger detail two

[[File:loop_management_3.png|400px]]

====Creating Loop Specific Traffic====
Creating loop traffic is slightly more complicated due to the number of objects to be created and potentially the size of the actual loop. A small loop is installed with the Nads miniSim as simple_rural1 or simple_rural2. Each is a loop road network with two signed 3-way intersections.

Loop specific traffic can be created through the use of a variable (i.e., LoopCount) or within the roadpad trigger that is incrementing the loop count variable. Both methods will incorporate a '''Create Action''' that creates the required elements.

===How to Change Environment Settings===
The scenario author can define global or localized environment conditions.

1. Insert >> Environment Conditions >> <chosen condition>

2. Define a region where the environment condition is active:
:LMB to define polygon points
:RMB to exit point entry mode

[[File:env_condition1.png|400px]]

Choosing an environment condition

[[File:env_condition2.png|400px]]

Environment region defined and parameters panel shows available options

NOTE: The environment condition boundary is a discrete threshold. Condition A will be on one side of the threshold. Immediately after crossing the boundary, condition B will be displayed.

===How to Fade an Environment Condition===
To fade gradually between two conditions requires the use of an expression that continually monitors the desired condition and sets a few variables based on the results.

Examining the demo scenario is the best way to look 'under the hood' to see exact command syntax and values to be used.

[[File:env_fade.png|400px]]

Note: this approach has been used for fog and visibility. It is unknown how it might work with non-visibility conditions such as precipitation and wind.

*From the scenario demo_visibility_transition.scn

[[File:env_fade_schematic.png|400px]]

'''Note:''' although the example above uses an environment condition boundary, '''it is possible''' to omit the defined region, retaining all commands and the scenario will still function. However, without the environment region, it becomes more difficult to determine where conditions are different from the standard settings.

===How to Control a Cab Instrument Panel icon===
In order to control the instrument panel, there are 2 requirements:
The specific cab used for the scenario
The specific control (switch) to be manipulated
The action for addressing the instrument panel is '''ChangeCabSetting'''

Instrument panel models are located in NadsMiniSim_x.x\data\Visuals\Instruments
These files are in OpenFlight format. Any 3D editor capable of reading or importing OpenFlight can be used to review these files. NADS uses the Presagis product Creator[tm].

An alternative method to inventory switches is to use the the '''buildscl.exe''' tool. To run the tool, open a CMD window to the IP folder location above, then run the command:
buildscl <input_file.flt><Enter>.
<input_file.flt> is the name of the file to process, without the '<>' characters.
<Enter> means to press the Enter key,

The result will be in a new file ending with .scl. This is a text file, and can be opened in a text editor or you can use the shell utility '''more''' to view the file contents:

more <input_file.scl> | grep switch<Enter>

An example for the malibu cab is shown below. .

switch s_LowWasher 0
switch s_Cruise 1
switch s_LeftTurn 2
switch s_RightTurn 3
switch s_FwdCollisionWarn 4
switch s_BlindSpotWarn 5
switch s_LaneDeviationWarn 6
switch s_RearCollisionWarn 7
switch s_HighBeamHeadlights 8
switch s_SeatBelt 9
switch s_UpArrow 10
switch s_Airbag 11
switch s_CheckEngine 12
switch s_CheckGuages 13
switch s_ABS 14
switch s_Brake 15
switch s_LowFuel 16
switch s_Gear 17

These controls may be accessed directly in scenario using the ChangeCabSetting action.

'''NOTE:''' Some functions such as Cruise, Gear, High beam headlights, Blind spot, collision, lane deviation warnings are '''normally''' controlled not by direct access as described here but by hardware mechanisms/buttons.

'''NOTE:''' For altering cab instrument panel operation it will be necessary to modify the OpenFlight model to include the desired funationality; for example, instrument panel blanking is not build into the model but can be added by editing the cab instrument panel model file then installing the modified file into miniSim.

===Scenario Hints===
The total number of scenario elements active at any given time can affect simulator performance:

Total number of active elements
*vehicles (ADOs), triggers, animations, etc.

Object management
*Use paths to shift ADOs away from the driver route of travel as they turn off the route
*reduce the number of vehicles in traffic cloud surrounding external driver
*use creation radius to limit the number of active elements, and to remove elements after the driver has traveled beyond the creation radius

[[File:creation_radius_1.png|400px]]

Creation radius works by activating the scenario element only when the driver is within the radius. The scenario element is created when the driver enters the creation radius, and is deleted after the driver leaves the creation radius.

Exploit environment to reduce object load

*Use curves, hills, intersection corners to mask objects

Object deletion
*Remove objects when no longer needed

When creating dynamic elements, create them as close to where they are needed as possible.

====How to Determine When ADOs are Visible to the External Driver====

Some development/setup testing may be needed to determine precise location/distance/speed; i.e., locating ADOs for a freeway ramp merge event where the external driver is merging onto the freeway with other ambient traffic present.

Unless the purpose of the event is to study driver behavior at the merge, ideally the scenario will be authored to have ambient traffic on the freeway but not to present a conflict at the merge for the external driver.

A straightforward way to determine where the ADOs are first visible to the driver is to mock up a scenario placing colored ADOs along the freeway with a velocity of 0. This will ensure the ADOs remain stationary while the scenario author determines where they are first visible to the external driver.

Place the start position/external driver far enough up the ramp to be a reasonable test for the actual scenario.

As you drive the ramp, see which ADO is first visible to the driver. Place ADOs just out of view (upstream) of that location.

[[File:merge_hint.png|400px]]

'''NOTE:''' use test vehicles of the same type and character as the intended scenario vehicles. For example, do not use a sedan test ADO for a larger vehicle (SUV, bus, dump truck). Doing so will invalidate the visibility test, because a larger ADO will be visible over a longer distance than a small ADO.

[[File:ramp_vis_1.png|400px]]

At the scenario start location, ADOs in front of the Coke truck are visible. Note how the larger vehicles are more obvious at this distance.

[[File:ramp_vis_2.png|400px]]

The driver has traveled onto the ramp. At this point, the last ADO visible to the driver is still the Coke truck.

[[File:ramp_vis_3.png|400px]]

As the driver travels farther down the ramp a small ADO is visible behind the Coke truck.

The answer to the question '''When is an ADO visible?''' is thus:
#It depends on how large the ADO is
#Small ADOs can be placed at the location of the red ADO behind the Coke truck.
#Large ADOs may need to be placed farther back (behind the red ADO). This test is inconclusive, but based on the terrain it seems likely that large ADOs would need to be placed at least at the green ADO location (behind the Coke truck).

Creating small ADOs at the green ADO location when the external driver is located at the ramp position in 3 travelling at the same speed as the external driver should arrive at the merge slightly ahead of the driver (because the curved ramp is longer than the straight freeway).

'''NOTE:''' ADO size, ADO color, time of day and visibility settings affect ADO visibility.

====How to Position Objects Precisely using '''Place Object At..'''====

ISAT does not support true precision because it is not currently possible to 'dial in' a position as is typical in 3D modelling tools, but there is a way to approximate precision in cases where a consistent measurement is desired.

In the following example a number of roadpad triggers are placed relative to the location where a roadway enters an intersection. This is a discrete boundary within the simulation world as shown in ISAT.

There are two methods of placement possible:
# Measure the desired distance (CTRL+Shift+RMB, drag); take note of the coordinates updating in realtime and make a mental note of the desired location.
#Place an object (ADO or static object); use the Place Object At.. feature from the context menu when you RMB on a scenario object.
Using this method you can specify a distance - positive numbers move the object downstream/forward, negative numbers move the object upstream/backward.

'''Note:'''If the distance is significant and extends over an intersection, ISAT may produce unexpected and undesired results such as re-starting the measurement from the closest upstream intersection, thus placing the object where it was not intended.

In the following example, Place Object At.. is used to specify a point 50 feet upstream from the road/intersection border.

[[File:precision_placement_1.png|400px]]

A roadpad trigger has been positioned near the area of interest. Any existing roadpad is deleted from the trigger.

[[File:precision_placement_2.png|400px]]

An ADO is used as a marker object inserted temporarily into the scenario. Any convenient object may be used.

'''Note:''' large objects such as ADOs may be less precise than small objects such as the Traffic cone, but is generally easier to access in the ISAT interface unless you have created a script for cone objects.

[[File:precision_placement_3.png|400px]]

RMB on the ADO to access the Place Object At.. request dialog. Only numbers are valid entries.

[[File:precision_placement_4.png|400px]]

The desired distance is entered into the Place Object At.. request dialog. ISAT will then require you to select the object you wish to move using LMB.

[[File:precision_placement_5.png|400px]]

ISAT moves the selected object by the distance you specified.

[[File:precision_placement_6.png|400px]]

Use the ADO CG (model center) to place the start of the road pad.

[[File:precise_placement_7.png|400px]]

Remove the ADO marker and save your scenario.

==Scenario Testing and Debugging==
The primary way to test and debug scenarios is using ISAT rehearsal mode.

'''NOTE:''' the external driver during rehearsal is a simulation. You have limited control over the simulated ownship:
#change speed
#change lane

ISAT has two rehearsal dialogs:
#abbreviated (standard) dialog
#advanced (extended dialog)

===How to change to the advanced rehearsal dialog===
Often it is necessary to control the ownship during rehearsal. The ownship controls are located in the advanced (extended) rehearsal dialog.

ISAT will show the Advanced dialog the first time rehearsal mode is activated. All additional activations show the abbreviated dialog.

TBC abbreviated dialog

To use the Advanced dialog, LMB the Advanced button.

TBC Advanced dialog

===How to change ownship speed during rehearsal mode===
After entering rehearsal mode:
#click the Play icon (start the rehearsal)
#pause.
#adjust ownship speed
#toggle pause off (resume rehearsal)

===How to make ownship lane change during rehearsal mode===
After entering rehearsal mode:
#click the Play icon (start the rehearsal)
#click the desired Lane Change (left or right)

===How to Use Audio in your Scenario===
Scenarios play audio sounds and messages through a write to cell action: '''SCC_Audio_Trigger'''

Use of audio in a scenario typically requires both a write to cell and a 'clear action' that writes a zero (0) to SCC_Audio_Trigger in order to 'clear the channel'. The 'clear' action can happen before or after playing a sound; choose one method and be consistent in your scenario authoring.

Failure to 'clear the channel' or '''not''' writing a value of zero can result in no audio being played for subsequent write to cell SCC_Audio_Trigger actions.

The following shows how this looks in scenario when executed from a roadpad trigger (RPT):

[[File:audio_scn_A.png|400px]]

The above diagram is shown below in text format:

HCSM RoadPadTrigger
GroupName "WindGust_Audio"
ByTypeSet "ExternalDriver"
NthFromStart 0
NthFromEnd 0
VehicleAhead 0
VehicleBehind 0
LongComment "This is a wind gust event"
ShortComment " "
ActvDel 0.0000000E+00
CrRad 0.0000000E+00
Debounce 0.0000000E+00
FireDelFrames 0
Lifetime 0.0000000E+00
Name "RPT_WG_6"
OneShot 1
Priority 0
SeqAct 1
Position 6.7165800E+04 6.0419215E+03 0.0000000E+00
DrawPosition 6.7165800E+04 6.0419215E+03 1.1308095E-317
Path "R:r3_62700_7920:0[3033.04:3245.46]"
HCSM LogData
Comment "LS1=8"
Delay 0.0000000E+00
InstigatorSet 0
Stream 1
StreamVal 8.0000000E+00
&&&&End&&&&
HCSM WriteCell
Comment "Play_Audio"
Delay 2.0000000E+00
InstigatorSet 0
CellName "SCC_Audio_Trigger"
CellData "63000"
CellType 2
CellVar 0
&&&&End&&&&
HCSM WriteCell
Comment "clear_audio"
Delay 0.0000000E+00
InstigatorSet 0
CellName "SCC_Audio_Trigger"
CellData "0"
CellType 2
CellVar 0
&&&&End&&&&
&&&&End&&&&

===How to Add Custom Audio Instructions to miniSim===

''' Please note: Custom audio 'instructions' for a scenario should be added to the instructions.txt file.'''

These are sounds that are played in scenario, typically as directions for the minSim driver.

Adding custom audio files requires the following procedure:

1 Exit miniSim - changes to the miniSim configuration should happen only when miniSim is not running.

2 Copy the audio .wav file to:
:C:\NadsMiniSim_x.x\data\sound\DefaultCabSound\Instructs

:Edit the file instructions.txt in that same folder.

3 Add an entry to instructions.txt to register your audio file in accordance with the following layout using the existing entries as a template:

:Unique_ID Filename Normalized_Volume

:Unique_ID is whatever unique number you assign to your file.

:Filename is the name of your .WAV file.

:Normalized_Volume is the volume your audio file should play, where 0.00 is silence and 1.00 is maximum volume.

'''NOTE: Remove all spaces in your audio filename.''' If needed, use the underscore character instead of spaces.

===Troubleshooting Custom Audio Additions===
After installing new .wav files and adding them into the audio configuration file '''instructions.txt''', if the audio file does not play:
*Check the Audio Engine window while miniSim is still running. The Audio Engine will display file errors,.
*If Audio Engine does not display a message similar to: Audio Engine loaded normally, scroll through the window messages and look for any .wav or load error messages.

==Re-use of Scenario Elements==
Scenario authoring can be an intensive undertaking. It makes sense therefore to leverage your development efforts by re-using scenario elements where possible.

ISAT provides a number of ways to re-use scenario elements:
# copy/paste
# external references
<span style="color:#ac6600"># exporting elements as '''groups'''</span>
# isc scripts

Each of these methods have their strengths and weaknesses.

===copy/paste===
The simplest method to re-use scenario elements among different scenario files is copy/paste. This is possible for most scenario elements* even if the source and destination roadmap/BLIs are radically different.

[[File:copy_paste.png|400px]]

It is also possible to copy an ISAT element from one scenario to another as '''TEXT''' by selecting the element and using the windows copy shortcut CTRL-C, then open a text file and paste it using the windows paste shortcut CTRL-V.

'''NOTE:''' Traffic sources are '''not''' portable using copy/paste.

'''NOTE:''' Not all elements can be copy/pasted. Elements created from a Create Element action cannot be copied - it is necessary to select the parent element and copy that instead.

[[File:copy_paste2.png|400px]]

In the above diagram, elements at '''B''' and '''C''' cannot be copied/pasted because they have been created by element '''A'''. It is necessary to copy the element at '''A''' instead. If only the elements at B are needed, the best method will be to copy/paste as Text.

'''NOTE: ISAT will not copy elements containing road coordinates (elements with a path) to a scenario that does not share the same BLI as the source (copy from) scenario.'''

A partial solution to such cases is to remove the path first, copy the element, paste into the destination scenario, then re-create the path manually.

===External Reference===
An external reference scenario is intended to be re-used by multiple 'parent' scenarios. The effort of authoring objects is thus leverages across multiple files, without needing to re-create the same elements more than once.

[[File:re_use_xref_1.png|400px]]

Common uses of external references include traffic, traffic signal operation, traffic sign appearance or other environment features which have multiple appearances (billboards, some tile related scenery, etc).

NOTE: Multiple external references are possible; but because objects are categorized by group, it is not entirely necessary.

For example, one external reference file contains traffic, another contains signs. These two external reference scenarios could be combined into one file.

[[File:xref_overview2.png|400px]]

NOTE: Each group defined must be unique across all files: parent and external reference files.

In order to use an element in an external reference scenario, it is necessary to define and assign a group to all elements that you wish to control from the parent scenario.
At this time there is no visual hint in ISAT to indicate if a group has been assigned to an element or not - each element has to be confirmed independently.

However, a properly authored external reference element cannot be edited within the parent scenario (after you have done Add Ref. to use the external reference file).

An alternative is to insert groups using a text editor with macro capability, or to use a program or external script to make the necessary changes.

'''NOTE:''' If the external reference file is for object contained in the parent scenario (for example, an external reference file containing traffic signals with a group defined) it is still necessary for that group to be defined in the parent file.

With traffic signals, ISAT requires ONE explicit group reference, which will be contained in the HCSM TrafficLightManager block as shown below. If you require the use of traffic signals in an external reference, the recommended way to do this is through ISAT because then it manages the group assignment for you.

==== HCSM TrafficLightManager scenario block ====

HCSM TrafficLightManager
HCSM CLG
IntrsctnName "I1_40260_4620"
Duration 2.0000000E+01 3.0000000E+00 1.0000000E+00 2.0000000E+01 3.0000000E+00 1.0000000E+00
GroupName "TrafficSignals"
LightName "s_signal_r1_LTRN_40260_4620_270"
LightName "s_signal_r1_RTRN_40260_4620_270"
LightName "s_signal_r2_LTRN_40260_4620_270"
LightName "s_signal_r2_STRT_40260_4620_270"
LightName "s_signal_r3_STRT_40260_4620_270"
LightName "s_signal_r3_NORM_40260_4620_270"
Pattern "FLTY" "R" "R" "R" "R" "R" ""
Pattern "RTG" "R" "R" "R" "R" "R" ""
Pattern "LTR" "LTR" "LTR" "FLTY" "FLTY" "LTR" ""
Pattern "SR" "SR" "SR" "SG" "SY" "SR" ""
Pattern "SR" "SR" "SR" "SG" "SY" "SR" ""
Pattern "R" "R" "R" "G" "Y" "R" ""
&&&&End&&&&
&&&&End&&&&

'''NOTE:''' At this time there is a known issue using the write cell '''SCC_Audio_Trigger''' action in external references. Although the trigger containing this action can be assigned a group and used as an external reference, audio does not play.

<span style="color:#ac6600">'''Because ISAT updates static object positions (elevation) to the terrain (roadway) when the scenario file is saved, the best way to use a custom elevation is to put such objects into an external reference file in order to isolate those objects from normal scenario editing.''' </span>

====Define a Group====
<span style="color:#ac6600">'''NOTE:''' ISAT 1.8.5 and 1.8.6 currently do not work properly with group files. These versions will not import objects within a group file. There is a workaround which involves the following process, but instead of reading the saved group file into a scenario the workaround requires editing the scenario as text and inserting the objects within the group file into the scenario.</span>

RMB on the element and choose from the context menu: Group >> New Group (if this is a new group) or Group >> (choose an already defined group).

'''NOTE:''' The first time you create a group for an object, ISAT will automatically assign the group to that object.

After defining and assigning groups to the scenario elements needed, save the scenario file then close it.

Open or create the parent scenario file and use the Add Ref. button at the bottom of the ISAT window to select your external reference scenario. After you choose a file ISAT will present you with the groups found in that scenario. Choose the groups you with to include and click the 'Okay' button. Click the Add Ref. OK button to complete the process.

Currently import group file operations are not working, but it is possible to insert the group file content (all HCSM StaticObjects) into a scenario manually by using a text editor to copy text from the group file and paste that into a scenario file into the HCSM Static Object section of the scenario file.

[[File:group_text.jpg|400px]]

'''NOTE:''' ISAT does not enforce logic on your external reference authoring. If you add references to scenarios that do not share the same roadmap/BLI as the parent scenario, it is likely that elements will be placed at the origin (in cases where the external reference roadmap contains roadways not found in the parent) if it even loads.

===Exporting ISAT Elements as Groups===
Transferring ISAT elements among scenarios can be accomplished using groups. As with external reference scenarios, one or more groups must be defined and then assigned to one or more elements.

After defining and assigning groups select the group for export using the Group select drop-down located at the lower left corner of ISAT. Choose a group to export and then click the 'Save Group' button. Save the file.

TBC insert graphic sequence diagram here

'''NOTE:''' If you cannot locate the group file in the folder specified, check the ISAT install\data folder. This is typically:

C:\NADS\ISAT\data

===Group File Contents===
The group file is a text file and can be opened or edited in a text editor.

The following is a group file containing one ADO. Note the GroupName line near the bottom:

Header
LriFile "_dev.bli"
LongComment "this is a test group export"
ShortComment "this comment was left empty"
&&&&End&&&&
HCSM Ado
RunMode "eREMOTE_CONTROL"
RandomSol 0
Name "Ado1"
DynModel "Non Linear"
LogFile ""
LatOffsType 0
CreateRelLatInFeet 0
CreateRelOffsLonUsingExpr 0
CreateRelOffsLonExprStr ""
AutoControlBreakLights 0
AutoControlHeadLights 0
UseReaDel 1
StdToAccType 0
StdToDecType 0
StdToDecVal1 9.0000000E-001
StpToAccType 0
DecToAccType 0
FollowTimeMin 1.0000000E+000
FollowTimeMax 2.0000000E+000
EmergDecClip -1.1000000E+001
Accel2Catch 0
NormVel2Kp 7.0000000E-001
PathSearchDepth 2
LcvFall 1.5000000E+000 2.0000000E+000
LcvFreq 3.0000000E-002 5.0000000E-002
LcvRAmpl 1.0000000E-001 5.0000000E-001
VelCtrlInitMatchOvVel 0
VelCtrlFollowSpeedLimit 0
VelCtrlDistType 0
MaxLatOffset 9.0000000E+000
LongComment " "
ShortComment " "
SolName "Audi"
RoadPos "r1_1320_44220:2:32414.44:0.00"
GroupName "TEST_Group"
&&&&End&&&&
HCSM StaticObjManager
&&&&End&&&&
HCSM DriverMirror
&&&&End&&&&
HCSM IntersectionManager
&&&&End&&&&

===ISC Scripts===
Scripts are an efficient way to automate repetitive and/or complex tasks.

ISAT uses a custom language (ISC) to automate placement and manipulation of scenario objects. Combined with simple direction commands and the capability to navigate a road network, ISC scripts can ask the scenario author for input and prompt for selecting objects.

ISAT installs with some ISC script files. If your version of ISAT contains a data\isc
folder, then your version of ISAT is capable of running scripts. You can create
additional scripts as needed. All scripts located in the data\isc folder will load in ISAT
when ISAT is launched.

You can use these scripts for reference in creating your own custom scripts.

New scripts created during an existing ISAT session will not appear until ISAT is re-
launched.
Scripts that have been edited will not update until ISAT is re-launched.

Unless otherwise indicated, scripts are case-sensitive.

'''NOTE:''' Please do not edit the existing scripts!

Make a copy of any existing script before you make changes. In the event your modified script does not work, you can look at the original file for reference.

ISC scripts are located on the ISAT Elements widget. Custom isc scripts are located after the 'Events' separator.

Using an ISC script involves LMB + dragging the desired script onto the workspace. In some cases the script will ask for inputs.

ISC can be also used to create an entire event, thus ensuring that all events created will be entirely identical in terms of settings and locations for all created elements.

ISC scripts are text files located within the ISAT installation data folder. Only the custom ISC scripts are located in this folder. This is typically:

C:\Nads\Isat\data\isc

====Icon Files====
Script icon files are 8-bit windows icon files (file.ico). GIMP is capable of exporting valid ico files. To create an ico file, scale it to 32x32 pixels. Export the file as .ico to the isat\data\isc folder.

In order for a script to use an icon file, both files must exist in the isat\data\isc folder.

====ISC Script Examples====
This section contains example scripts with notes.

'''Rotate sign'''

.Name SetSignRotation
.Icon SignRot.ico
Static sign
Select(sign,"Please Select a Sign")
sign.SetAngle(Anchor)
.End

'''Place Multiple Static Objects (TrafCone)'''
The following script asks the scenario author for number of cones to generate, position and offset values and then generates the objects.

A breakdown of the script follows the code block below.

.Name Cones
.Icon cone.ico

Block coneBlock %%%
HCSM StaticObject
IsNewObj 1
Name "Cone_xxx"
SolName "TrafCone"
Option 0
Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
&&&&End&&&&
%%%
Static cone;

Value dist1
Value numberOfCones
Value distance
Value variablePart
Value randDistance
Value speed
Value Count
Value LatOffset

Block tempBlock
tempBlock = coneBlock
Count = 1
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

Ask(numberOfCones,"How many cones?" )
Ask(dist1,"Distance between cones?" )
Ask(LatOffset,"How much offset?" )

Position posRp
Position tempPos
posRp = Anchor
numberOfCones = numberOfCones

Repeat numberOfCones
posRp.GoForward(dist1)
# test comment
tempPos = posRp;
tempPos.SetOffset(LatOffset)
cone.RoadPos = tempPos
cone.Clone
Count = Count + 1
tempBlock = coneBlock
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

End
.End

====Script Breakdown cones.isc====

This section contains a description of the elements used in the script. The script segment is followed by a brief text description.

This script places a number of object copies (TrafCone) using information provided by a user.

.Name Cones
.Icon cone.ico

The first line contains a keyword '''.Name''' followed by the name of the script. This is the name that ISAT will use on the Isat Elements widget for the script. Note the script name does not have to be the same, but it is good computing practice.

The second line begins with the keyword '''.Icon''' followed by a file name. This file must exist in the ISAT\data\isc folder (accompanying the script file). This is the icon ISAT will use for the script.

Block coneBlock %%%
HCSM StaticObject
IsNewObj 1
Name "Cone_xxx"
SolName "TrafCone"
Option 0
Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
&&&&End&&&&
%%%

This is the data section of the script, which is defined using the keyword '''Block'''. A block name follows the keyword, and the data start is defined with '''%%%'''.

The HCSM StaticObject section has been copied from a scenario. In this case, a static object was placed into the workspace and then copied into a text file.

Name "Cone_xxx"
Note: the object name contains a marker that can be used to programmatically name instances of the object:

SolName "TrafCone"
This line begins with the keyword '''SolName''' followed by the name of the object as it is defined in the sol2.txt file.

Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
The Position of the static object will update when the script activates and instanced objects are placed in the workspace.

Static cone;
This line begins with the keyword '''Static''' followed by a variable name.

Value dist1
Value numberOfCones
Value distance
Value variablePart
Value randDistance
Value speed
Value Count
Value LatOffset

This section defines variables with the keyword '''Value''' followed by variable names. Using descriptive names is better than generic names. From the variable list it already seems clear what the programmer cares about: number of cones and distances.

Block tempBlock
tempBlock = coneBlock

This section defines a block using the keyword '''Block''' followed by the variable name.

The next statement replicates coneBlock into tempBlock.

Count = 1
Initialize the value of the variable Count to 1.

tempBlock.Replace('xxx',Count)
The built-in '''Replace''' function changes the string 'xxx' to the value of the variable Count.

cone.SetBlock(tempBlock)
This statement creates a block using the function '''SetBlock''' called cone, and copies the contents of tempBlock into it.

Ask(numberOfCones,"How many cones?" )
Ask(dist1,"Distance between cones?" )
Ask(LatOffset,"How much offset?" )

This section asks the user for input and puts that information into variables:
*Number of cones
*Distance between cones (dist1)
*Lateral offset (calculated from lane center)

Position posRp
Position tempPos
posRp = Anchor
numberOfCones = numberOfCones

This section contains position variables and assigns the value of numberOfCones.

Repeat numberOfCones
posRp.GoForward(dist1)
# test comment
tempPos = posRp;
tempPos.SetOffset(LatOffset)
cone.RoadPos = tempPos
cone.Clone
Count = Count + 1
tempBlock = coneBlock
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

This section is where the work happens. Reading from the top, this section is contained within a loop defined by the keyword '''Repeat'''. The number of times to repeat follows in a variable numberOfCones.

'''posRP.GoForward()''' is a built-in function to take the current position and shifts it forward by the amount specified in the dist1 variable.

#test comment
This is a comment defined by starting the line with the comment keyword '''#'''

tempPos = posRp;

Assign the value of the variable tempPos to the value currently in '''posRp'''

tempPos.SetOffset(LatOffset)

Another built-in function or attribute to the position element which defines a lateral offset (distance from the lane center). This statement places the value of a variable LatOffset into the offset element of the tempPos variable, using the operand '''SetOffset'''.

cone.RoadPos = tempPos

This statement sets the road position variable for cone to the value in the variable tempPos.

cone.Clone

Duplicate the block cone using the operand '''Clone'''

Count = Count + 1
Set the value of the variable Count to the value of Count plus one. This statement increments the value of Count for each loop processed.

tempBlock = coneBlock

Create a new block tempBlock by setting it to the content of coneBlock.

tempBlock.Replace('xxx',Count)

Use a built-in function to '''Replace''' the string 'xxx' with the value of the Count variable

cone.SetBlock(tempBlock)

Use the built-in function '''SetBlock''' to place the modified tempBlock (modified by the string replacement command earlier) into the cone block.

End
.End

The last two lines terminate the loop and the script, respectively.

====How to Create an ISC Script====
The simplest way to create an ISC script is to find an existing script that does something similar to your desired behavior and edit it.

=miniSim Simulation Data=
MiniSim runs on shared memory:
*miniSim is a collection of programs
*shared memory is a commonly accessed 'blackboard' list: a Cell and a Cell Value
:The DAQ file is a snapshot of this 'blackboard' memory for every frame.

*Scenario can write to cells added by the scenario author
:-i.e., for custom hardware or tasks/events

'''NOTE:''' Custom cells must be present in the collect file (NadsMiniSimCollect.cec) '''prior to''' simulation in order for the custom cells to be present in the DAQ.

NOTE: The cell type defined in the collect file must be followed, or garbage values will be used

Use of a DAQ file implies that at some point, data reduction will be needed.
Data reduction: the process of distilling measures from the DAQ file, i.e.
*Event definition
*SDLP
*Average headway

==What is the Difference? Cell vs. Variable==
*A Cell is a pre-created “slot” in shared memory
:-Specified in the .CEC collect file,
:-Saved in the DAQ file,
:-Can be sent to custom programs;
:-Can create & use custom cells;
*A Variable is a name value internal to the scenario
:-NOT saved to the DAQ file,
:-Can use to track items in the scenario
:i.e., how long the driver has been exceeding the speed limit
:-Initialize conditions in the scenario.

=== Variables Save ===
Variables can be saved to disk as a single value text file (ie, multiple values over time are not supported) through the use of a '''Store Variable''' action:

[[File:2021-08-23_13h28_49.png|400px]]

The file is stored in the miniSim_x.x\bin.x64 folder.

'''NOTE:''' The name of the file is defined within the Store Variable action. '''Care must be taken to save variables to unique file names''' in the case of multiple scenarios running on miniSim at the same time (if they share common variables), as would be the case if triggers are copied from one scenario to another.

=== Variables Restore/Read ===
Variables can be read into the simulation through the use of a '''Load Variable''' action:

[[File:2021-08-23_13h32_39.png|400px]]

==Cell Types==
This is a partial list of cell types.

*CFS = control feel subsystem (steering wheel, pedals)
*CIS = control information subsystem (gear, turn signal, buttons, etc)
*TPR = terrain profiler for terrain queries
*VDS = vehicle dynamics for accelerations, position, engine speed, speed, etc.
*ACC = adaptive cruise control
*RCM = configuration management for setting variables that affect subsystem configuration (ACC enabled or disabled, for instance)
*SCC = scenario
*SOP = for one time initializations at the start of the simulation.

=='''Data Output Actions'''==

*Write to Cell Actions
:-Write the value of a variable or cell to a cell
:-Write to a custom cell
:-Cannot overwrite another systems output
'''NOTE:''' Although it is possible to write to a different system cell, that value will be over-written on the next frame. Thus it is effectively not feasible nor desirable to do.

'''<span style="color:red">Also Note: the limit for maximum number of write to cell actions that can be performed in one frame is 8.</span>'''

*Set Variable Action
:-Sets the value of a variable
:-Does not have to be created first
:-Not saved in the DAQ unless written to a valid cell
*Logstream
:-Log data action

===Data Output Methods===
Your data is the primary reason for simulation.

1. Default miniSim scenario measures
:- Immediately available

2. Alternate scenario measures (DAQ file)
:- Processed through data reduction

====Default miniSim Scenario Measures====
*Saved to a drive report.txt file
*Saved to the same Location as DAQ files;
:Scenarioname_timedatestamp_report.txt
•Measures calculated overall, and up to 20 Events during drive:
:Collision Count Lane Departure Count
:Maximum Speed Lane Departure Percentage
:Minimum Speed Speeding Count
:Average Speed Speeding Percentage
:Standard Deviation of Speed Average Headway
:Standard Deviation of Lane Position

====Default miniSim Scenario Measures Require Scenario Event Definition====
In order to capture meaningful data into the default miniSim measures, a scenario must be configured properly to define events.

Use the Write to Cell action to activate the default measures.

[[File:2021-07-02_11h02_44.png|400px]]

*At the start of scenario, set:
::SCC_EventStatus =0
::SCC_EventNumber = 0
*At the start of the first event, set:
::SCC_EventStatus = 1
::SCC_EventNumber = 1
*At the end of the first event, set:
::SCC_EventStatus = 0
*At the start of the second event, set:
::SCC_EventStatus = 1
::SCC_EventNumber = 2
*At the end of the second event, set:
::SCC_EventStatus = 0

Continue this pattern; at end of final event, set:
::SCC_EventStatus = 0

====Default miniSim Scenario Measures Sample Report====
The following is an example report for 4 events. Note the remaining events present in the report are all zeroes or -1.00.

[[File:default_measures_report.png|400px]]

===="Alternate" Scenario Event Definition aka Using Logtreams====
'''NOTE: This method is the more typical/standard method for defining events.'''

Defining an event is key to partitioning simulator data into useful sections. Processing these sections is the essence of '''data reduction.'''

These useful sections are partitioned using logstreams and are generally called '''Events''':
*A logstream is a data marker present in the DAQ file
:there are 10 logstreams
:use logstreams to indicate when things happen '''in the data:'''
:at the start of an event; i.e.,
::grab all data where logstream 1 = 100 (example value)
:during a sub-section of an event
:at the end of an event (typically clears to 0)

Logstreams help separate/filter data;
*SDLP is not useful during emergency maneuver events

Logstreams can be useful to debug events;
:marking in the data when triggers fire
:ensuring event counters work; these are typically sequential, so any logstream deviation identifies a problem

*How to define a Scenario Event:

Set logstream values at scenario event start
:during and at scenario event end, set or clear logstream values:
For example:
::logstream 1 for event ID
::logstream 2 for sequencing the event (during/within event)
::logstream 3 for restart number, etc.

*Requires data reduction to fully process drive data
*Does '''not''' support default measures
:unless those measures are used in parallel with the logstream method

*The use of logstreams allows a scenario author to encode event and environment information into the scenario and as a result, into the simulator data stream.

====Example Alternate Scenario Event====
This section contains an example of a scenario that uses logstream 1 to define an event and environmental context.

In the following example, logstream 1 (LS1) is used to:
#define the scenario start, which is also in this example the event start. NOTE: This is not typical.
#when the driver is 805f from the intersection halt line, set a value into LS1
#when the driver is 500f from the intersection halt line, set a '''new value''' into LS1 NOTE: This could also use a different LS than the one used to define your event, i.e., 1
#when the driver activates a roadpad trigger to reset a force velocity (FV) on a lead vehicle

[[File:event_def_LS.png|400px]]

In the following event definition, an expression trigger is used to set a logstream value and execute two additional actions pertaining to the event.

[[File:event_ET_LS3.png|400px]]

====How to Export Data from A DAQ file using ISAT====
ISAT can display and export DAQ data. NOTE: This is 'raw data', not previously processed. This method can be used to test scenarios, confirm or identify data issues.

TBC: example export here

=Terminology & Documentation=
This section contains terminology and references to related documentation.

'''Action''' - the basic scenario element; the basis for creating scenarios. Actions may be executed on scenario elements (dynamic or static), create or remove elements, or the environment (time of day, visibility) or the simulated cab instrument panel.

'''ADO''' - Autonomous Dynamic Object; self-controlling to a degree.

'''Cell''' - Data elements that are recorded to during a drive; some cells may be used by the scenario author. Custom cells may be added to miniSim.

'''Event''' - anything significant that happens during a drive where the driver condition or response is desired to be identified in the drive data. Can be isolated from general driving through default measures or logstreams.

'''ISAT''' - Interactive Scenario Authoring Toolkit; used to create scenario files for use on the NADS facility or miniSim simulators.

'''ISC''' - ISAT script file.

'''Scenario''' - The simulation experience during a drive; also known as a scenario file, which contains all instructions to the elements within a simulator drive.

'''SDLP''' - Standard deviation lane position

'''SOL''' - Scenario Object Library; objects that are available to ISAT during scenario authoring must be present within the sol2.txt or an auxiliary sol2 (sol2_aux.xxx.txt) file.

'''Trigger''' - A scenario element that contains actions to execute during simulation. All triggers share the same actions, but execution depends on the trigger type.

'''TTA''' - Time to arrival.

'''TTC''' - Time to collision.

=Reporting ISAT & Scenario Issues=
*How to report ISAT & scenario issues:

When reporting issues with scenarios it is helpful to provide as much information as possible.

This often includes scenarios (including any external reference files) and the .LRI file used by the scenarios, screenshots or video that demonstrate the issue being reported and relevant DAQ files. It can be very helpful to include coordinate information with the screenshot or video.

The .BLI file is created from the .LRI and is much larger than the LRI so it may be more convenient to send the LRI file. NADS staff can re-create the BLI file from the LRI.

Some graphics anomalies may be issues with the tile model and not a scenario or miniSim problem. These include:
#white block shapes in the environment
#gaps or missing geometry; i.e., holes
#improper lighting (dark features present during the day)

If these issues happen on a custom roadmap/database world, please include the TMT .mos file as well so NADS can re-construct your environment.

==How to contact the NADS miniSim team:==

email [mailto:miniSim-Support@uiowa.edu minisim support]

[mailto:andrew-veit@uiowa.edu Andrew Veit]
Director of NADS miniSim

[mailto:joseph-meidlinger@uiowa.edu Joseph Meidlinger]
Program Coordinator NADS miniSim

[mailto:oscar-hernandezmurcia@uiowa.edu Oscar Hernandez Murcia]
MiniSim Application Programmer/Analyst

[mailto:chris-schwarz@uiowa.edu Chris Schwarz]
Data Reduction & Vehicle Dynamics

[mailto:shawn-allen@uiowa.edu Shawn Allen]
TMT, Modelling & Support

==How to check what BLI file is used by a scenario==

#You can edit the scenario in a text editor; near the top of the file will be a line starting with '''LriFile''' followed by the name of the BLI file in double quotes.
#You can use '''grep''' to inventory single or multiple scenarios:
:grep bli <scenario file/s>
:A partial listing is shown in the example below. NOTE: The files shown will likely be different on your PC:
C:\NADS\Isat\data\training.demo_scn>grep bli *.scn
Demo_Expression_Lead_Vehicle_Variables.scn: LriFile "simple_rural.bli"
Demo_Expression_Trigger_to_Lead_Vehicle.scn: LriFile "simple_rural.bli"
Demo_HUDD.scn: LriFile "simple_rural.bli"
ISAT-Samples-Avoid.scn: LriFile "esc_dry_05.bli"
ISAT-Samples-Right-Incursion.scn: LriFile "esc_dry_05.bli"
ISAT-Samples-TrafficLightTest.scn: LriFile "simple_city1.bli"
ISAT-Samples-TrafficLightTestB.scn: LriFile "simple_city1.bli"
ISAT-Samples-YellowLightDilemmaB.scn: LriFile "simple_city1.bli"
KBW_TEST.scn: LriFile "simple_rural.bli"
KBW_TESTB.scn: LriFile "simple_rural.bli"
demo.createADO_and_trigger.scn: LriFile "simple_city1.bli"
demo.creation_radius1.scn: LriFile "simple_city2.bli"
demo_FV_sum_of_Sines.scn: LriFile "simple_city2.bli"
demo_LV_Decelerate.scn: LriFile "simple_city2.bli"
demo_LV_cut_in.scn: LriFile "esc_dry_05.bli"
demo_MG.scn: LriFile "simple_city2.bli"
demo_TM1.scn: LriFile "simple_city2.bli"
demo_TT_null.scn: LriFile "simple_city2.bli"
demo_actions_text.scn: LriFile "simple_city2.bli"
demo_alt_data_measures.scn: LriFile "simple_city2.bli"
demo_audio_virtual_object.scn: LriFile "esc_dry_05.bli"
demo_audio_virtual_object_simple_rural.scn: LriFile "simple_rural.bli"
demo_auto_cloud1.scn: LriFile "simple_city2.bli"
demo_coneISC1.scn: LriFile "simple_city2.bli"
demo_dddo.scn: LriFile "simple_city1.bli"
demo_dddo_B.scn: LriFile "simple_city1.bli"
demo_forXRef_traffic.scn: LriFile "simple_city1.bli"
demo_force_vel_01.scn: LriFile "simple_city1.bli"
demo_groupImport.scn: LriFile "simple_city2.bli"

==How to configure miniSim for screenshots to include coordinates==
You can enable coordinate display on miniSim by changing the focus to the main display. #Move the cursor until it is positioned in the main display area, then LMB. When successful the main display will appear to "blink".

Press the keyboard n key twice. This will cause coordinate information to display in the lower left corner of the main display.

[[File:miniSim_show_coords.png|400px]]

The n key is a toggle; to disable coordinates, press it twice (2x) again. '''NOTE:''' the cursor focus must be in the main display in order for this to work.

=Additional Resources=
[[:File:ISAT_Quick_Start.pdf|ISAT Quick Start Guide]]

[[ISAT_Demonstration_Scenarios|Demonstration Scenarios]]

[[:File:Create_Use_Custom_Cells.pdf|Create and Use Custom Cells on MiniSim]]

[[:File:Function_ReadCell_20180824.pdf|ReadCell function]]

[[:File:TrafficManager_Ch12.NADS.Internal_ISAT_UsersGuide.pdf|Traffic Manager]]

=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 [[ISAT_Reference_Manual_Table_of_Contents#ISAT_Reference_Manual|reference manual for ISAT can be found here.]]

ISAT User Guide Table of Contents

2023-09-14T20:00:04Z

Shawn Allen: /* Known Issues add link to external ref section for Known Issues*/

== 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
*CTL-<some other key> Press and hold the Ctrl and then press <some other key>. Most typically used for copy (CTRL-C) or paste (CTRL-V).
*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 and modify for use in your own scenarios as needed.

== <span style="color:#FF0000"> '''Known Issues'''</span>==

Added 2022.07.01 '''Relative Creation''' does not currently work for ADOs on miniSim.

'''Expression clarification'''

Increment and decrement operators (++, --) are not considered expressions by behaviors. They should not be flagged as expressions when used in the Value field of a Set Variable action.

Added 2019.11.07 '''File reset issue'''

ISAT has a long-standing bug which can reset your static object options when your scenario file is saved to disk.

'''It is strongly recommended that you use [[#External_Reference|external reference scenario files]] to avoid this. '''ISAT does not reset static object options in the xref file.

Added 2021.12.29 Expression Triggers and Values

'''Using Values in Expression Triggers'''

To ensure proper execution of expression triggers, it is recommended that the values used include the desired range by decreasing the lower threshold or increasing the upper threshold '''instead of using the exact value.'''

For example, to process values in a range (7031 - 7040):

[[File:2021-12-29_12h38_09.png|400px]]

'''Note: remember that negative values must be calculated since the expression parser does not parse negative values otherwise.'''

For example, to properly parse a specific transmission gear (Park):
'''ReadCell('CFS_Auto_Transmission_Mode', 1) = ( 0 - 2 )'''

=='''ISAT Overview & Interface Basics'''==
This section contains information about ISAT and the ISAT interface.

===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 <span style="color:#FF0000">'''not an object editor'''</span> 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.
[[File:miniSim_scenario_compnents.png|center|640px]]

*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.

[[File:anatomy_of_a_scenario.png|center|400px]]

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

[[File:scenario_as_text.png|center|640px]]

This diagram shows the same scenario in (left to right) 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, <u>always</u> check your edits in ISAT!'''
*Copy/Paste - delete paths from elements when the BLI is different between your source & destination BLI files. The following scenario elements contain paths:
::ADO (with a path specified)
:: Any roadpad trigger (roadpad, Time to Arrival, Follow)

'''NOTE: A Traffic Source is not a portable element but it can be re-created in ISAT or integrated into a new scenario by copying the element from the source scenario then using a text editor to paste it into the destination scenario'''

'''How can I find information in multiple files easily?'''

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.

What if you don't know what to look for? How do 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
[[File:action_overview.png|400px||border|caption]]

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)

==='''Adding an action to a trigger'''===

The following example uses a Time Trigger; remember that '''all triggers share the same actions'''.

To add an action to a trigger you can double-click on the trigger, navigate to the '''Actions''' panel, and click on New to create a new action.

[[File:2022-11-30_12h47_23.png|400px]]

The possible actions are listed under the '''Action Type''' drop-down menu.

[[File:2022-11-30_12h47_44.png|400px]]

Actions are arranged in a 'stack' and are processed from top to bottom. If you use multiple actions you should enable the '''sequential flag''' to ensure each action is executed in sequence. Without the sequential flag, actions will be processed as fast as the simulator behaviors can execute.

[[File:2022-11-30_12h52_58.png|400px]]

Actions may be re-ordered in the stack using the '''arrows''' located near the action stack list.

=='''ISAT Modes of Operation'''==
[[File:ISAT_modes_of_operation.png|400px]]

*Edit
*Rehearsal
*DAQ playback
*Monitor '''Currently not available'''

==='''Edit & Rehearsal Modes'''===

*Edit - this is where scenario authors will spend the most time.
::Creation or modification of scenario
::Link to or import portions of other scenario elements

[[File:mode_edit.png|400px]]

*Rehearsal
::Debug & test scenario
::Simulates scenario using Behaviors and Vehicle Dynamics
::Displays error messages from behaviors

[[File:mode_rehearsal.png|400px]]

'''NOTE:''' Rehearsal mode <span style="color:#FF0000">simulates </span>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

[[File:mode_playback.png|400px]]

==='''miniSim Scenario Components'''===

The following diagram shows an overview of scenario related components of the NADS miniSim and how these components work together.

[[File:miniSim_scenario_components_wDAQ.png|400px]]

=='''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.

[[File:isat_workspace_general.png|400px]]

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)
[[File:isat_status_bar_overview.png|400px]]

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.

[[File:isat_user_prefs_status_bar_settings.png|400px]]

====ISAT Iconography====
ISAT provides graphic hints for triggers placed in scenario that can be useful when editing or maintaining scenarios.

The general format is a border enclosing miniature icons of the trigger and first action contained in that trigger. Additional information representing one or many actions is also shown.

[[File:hints1.png|400px]]

ISAT will list all trigger actions when a trigger is selected, but these hints provide a way to quickly identify what actions have been authored.

[[File:hint2.png|400px]]

*A Roadpad trigger, one action: '''Traffic Light Action'''
*B Roadpad trigger, multiple actions, first action is '''Remove Element'''
*C Roadpad trigger, multiple actions, first action is '''Set Dial'''
*D Roadpad trigger, constrained to road (lane), no actions - this is an empty trigger
*E Roadpad trigger, multiple actions, first action is '''Log Data'''
*F Global Time Trigger, single action: '''Set Dial'''

[[File:handle.png|400px]]

The element handle is the red dot visible in most of the triggers.
The handle can be dragged into position, and the trigger will follow the handle

Drag the trigger off the handle to offset it's location from the handle

==='''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.

[[File:object_types_isat.png|400px]]

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
::*Traffic Source

:'''NOTE:''' Virtual objects are defined in the scenario, not in the SOL2.
[[File:object_types_world.png|400px]]

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.
::NOTE: 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.

==='''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:
#Follow a path using kinematics
#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:
#coupled
#relative trajectory
#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'''===
Traffic signals are objects with special operation and function; they are coupled to intersections and routes of travel through intersections to control traffic flow similiar to their function in the real world. Traffic signals are part of the source tile model and may not be re-positioned or physically altered by scenario except for their visual signal state appearance; i.e., red, green or yellow signals.

To control intersection traffic signals use Edit >> Traffic Light ManagerTraffic signals use a Signal State Table (SST) to control which signal states are active and when. Each intersection with traffic signals will have an associated SST.

[[File:traffic_light_state_manager.png|400px]]

The above diagram shows an intersection in the workspace to the right, and the traffic signal state table for that intersection on the left. At this point additional states (for signal condition) can be added by clicking the '''Add state button'''.

[[File:traffic_signal_state_table2.png|400px]]

The above diagram shows two states defined for the intersection, represented by the two columns of state condition.

Continue adding states until the desired signal cycle has been defined. Generally this consists of red, green or yellow states.

NOTE: There is currently no way to automatically author a series of traffic light signals

To author traffic signal lights in sequence or on a route, the scenario author has to manage the signal states

[[File:traffic_signal_state_duration.png|400px]]

To edit the signal state duration RMB on the duration field header and choosing '''Edit state duration''' on the context menu. Enter the desired value then click OK.

====Traffic Signal Types====
The ISAT status bar reports Traffic Signal Type name. There are two signal types:
#Standard signal - IDs may have no identifying information
:Valid signal states: Red, Yellow, Green, Flashing Red, Flashing Yellow, OFF
#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

[[File:traffic_light_extended_type_name_normal.png|400px]]
: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.

[[File:traffic_light_extended_type_name.png|400px]]

===Changing Signal States in Scenario===
Traffic signals are controlled in scenario by using a Traffic Signal Action to change the SST.

'''NOTE:''' The Traffic Signal Action works by changing the SST, '''not by changing the traffic signal.''' This is a subtle but important difference.

Setting a signal to an undefined state effectively does nothing to the traffic signal.

[[File:traffic_light_state_table.png|400px]]

The above diagram shows a fully populated SST, with one signal row highlighted in red, and one state column highlighted in green. The associated intersection corridor is highlighted, showing the signal controls a dedicated left turn.

During simulation, the initial signal state is defined by the left column. As the simulation proceeds, the signal state changes according to the duration states defined across the state table, proceeding left to right and then wrapping around to the beginning after the last defined state. Each traffic signal appearance changes according to the configuration of the SST.

As a driver approaches this intersection, assume the signal state is in the column left of the highlighted column ('''R'''ed), and the desired action is to change the signal to green.

The action used to change a traffic signal state is the '''Traffic Light Action'''.
Using a traffic light action requires the specification of a signal state, the traffic signal to affect, and a duration.

[[File:traffic_signal_action1.png|400px]]

In the above diagram the scenario author has specified the desired state as '''Green''' as shown in the action dialog.

However, referring back to the previous state table diagram, there is no such state present in the SST. That means this particular action will fail, and the traffic signal will not change as the driver approaches the intersection - because the action does not create a new signal state, it works by advancing the state table condition (column) to the specified condition. If the condition is not present in the SST then nothing will appear to happen.

In this example, the action should be edited to use the correct signal state '''Left Turn Green''', which is present in the SST.

'''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

[[File:known_issue_traffic_light_action.png|400px]]

'''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.

[[File:known_issue_traffic_light_action_workaround.png|400px]]

====Change A Traffic Light Using Scenario Action====
To change a traffic signal, use the Set Dial >> Traffic Light action.
'''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

[[File:traffic_light_state_table.png|400px]]

This diagram shows a fully populated traffic signal state change for an intersection.

*Static object traffic lights
:These are objects, not true traffic signals and so they are not controlled with the Traffic Light manager.

==='''Traffic Source'''===
A traffic source is a coordinator used to create traffic at specific locations in the road map (unlike the Traffic Manager). This is useful for creating ambient traffic. Traffic Sources creates ADOs or DDOs at random or user-specified intervals.

Elements created using a Traffic Source will be created at the locations specified by the user. If traffic is specified at multiple locations the actual location for each creation will be determined randomly during simulation.

'''Note:''' Using the Relative Creation flag on ADOs created by the traffic source will not create traffic at the specified location on the map, but use the information in the Relative Creation fields to populate traffic in the scene during simulation.

This method allows for more flexibility but care must be taken not to create so many ADOs that miniSim is unable to make frame rate. Too many ADOs will cause the scene to jump and 'jitter' and it will feel slower than normal.

==='''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 ISAT scenario rehearsal

===Custom (icon) file virtual objects===

[[File:virtual_object_custom_icon_file.png|400px]]

'''Note:''' Some versions of MiniSim_2.3 do not support custom virtual objects. For those installs, if you require this type of functionality, a workaround exists in the form of a 2D model that can be customized (i.e, sprite).

Virtual objects may be customized using graphics files (texture images) to display any desired custom element. This typically requires the use of a bitmap graphic. Various file formats are supported: JPG, BMP, PNG. It is possible some types of these formats may not work - in those cases, try an alternate format.

If image transparency is required and the custom icon does not display during simulation, please email dsri-minisim@uiowa.edu with a description of the issue, your scenario and custom virtual object image file.

Custom icon files must be located within the Nads MiniSim path for resources - at NadsMiniSim_x.x\data\visuals\Models\ModelTx.

===Standard virtual object shapes===
The virtual object shapes include:
# Circle
# Triangle
# Octagon
# Star
# Diamond
# Icon <- this is for custom virtual object graphics
# Rectangle
# Hexagon

The virtual object fill and border color and transparency can be set in the virtual object properties dialog panel.

[[File:virtual_object_std_shape.png|400px]]

====Virtual Object Workaround====

There is a scenario authoring method that can be used to emulate virtual object functionality through the use of a DDO that is coupled to any dynamic scene element, including the External Driver. One model has been created to support this method called "sprite".

'''Note:''' The sprite model is a 2D object present in the scene, and can therefore be occluded by other scene elements during simulation.

[[File:trafsign_sprite.jpg|400px]]

The sprite model is designed as a flat plane that continuously faces the viewer. It contains different sized planes and can be customized through textures.

When authoring your scenario, configure the sprite object to Off unless it should be visible at scenario start. During the scenario you can control the sprite appearance with a setSwitch action.

[[File:sprite_setSwitch_action_021121.png|400px]]

The who to effect should use the name of the DDO placed in your scenario. The switch name will be s_sprite as shown above. Any valid option can be used. An invalid option (greater than 30) will disable the sprite the same as selecting the OFF option.

==='''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'''===
<span style="color:#FF0000">'''All trigger types share the same Action types'''</span>
*IF Then conditional
*Predicate: i.e., the activating agent
:If predicate is TRUE, then do Action(s)
*Road related triggers are categorized by predicate type
:Named element
:Road (lane)
:Nth vehicle on path only

'''What trigger is appropriate?'''
To determine which trigger is most appropriate, consider the task you are trying to accomplish. '''The differences between triggers is their activation methods.'''

'''Global Time Trigger'''
[[File:isat_time_trigger.png|150px]]

Use this trigger when something has to happen at some point in time.

Time triggers are also useful as "placeholder triggers"; used to apply persistent actions to multiple elements with unique settings for each element. Normally a persistent action is the last action possible in a trigger since the persistent action fires continuously. Putting persistent actions into a time trigger allows the scenario author to continue an action stack in the parent trigger if necessary.

Time triggers can be used as a 'stopwatch' - elapsed time, such as ending a drive after 3 minutes by setting the trigger to fire using an Activation Delay of 180s (GTT >> General).

Often used as a placeholder for actions such as initializing variables, displaying text messages to the screen using Set Visual Display Text actions, etc.

'''Note''': A time trigger can have global elapsed time and activation delay of 0, which causes the action stack in the time trigger to activate when that trigger is created.

'''Roadpad Trigger'''
[[File:isat_roadpad_trigger.png|150px]]

Use this trigger when something has to happen at some location in the drive that does not require event timing to be comparable for all participant drivers. For cases where event timing must be comparable among all participant drivers use the Time to Arrival trigger (TTA) instead of a roadpad trigger.

'''Time to Arrival Trigger'''
[[File:isat_time_to_arrival_trigger.png|150px]]

Use this trigger when something has to happen relative to some point in the drive, and also ensure all study drivers experience the same event timing irrespective of driver style (conservative, slow vs. aggressive, fast). Time to arrival (TTA) trigger uses a time calculation from the trigger pad activation to a target location specified in the trigger.

'''Traffic Light Trigger'''
[[File:isat_traffic_light_trigger.png|150px]]

This trigger activates actions when the specified traffic signal state is reached. For example, if the desired action is to create a DDO pedestrian to step into traffic when the traffic signal is yellow, then the Traffic Signal Manager must be used to author the appropriate signal states for the traffic signal.

Typically some other trigger is used to control the traffic signal (ie, to change the signal to Yellow on approach). It is therefore perfectly valid to put the actions within this other trigger rather than relying on the traffic light trigger.

'''Note''': Once a traffic light action has been authored, ISAT may be prone to crashing when accessing that trigger. This problem can be avoided by creating a time trigger and isolating the traffic light action there, allowing the parent trigger to be modified without crashing. Adjustments can be made to the traffic light action time trigger in a text editor, or recreated if it becomes necessary to make adjustments and ISAT continues to crash when trying to make edits.

'''Note:''' The traffic light action does not change the traffic signal state, and it requires a valid state sequence to exist in the signal timing table (Edit >> Traffic Light Manager). The traffic light action '''will not create a signal state''' that does not already exist in the signal timing table.

'''Expression Trigger'''
[[File:isat_expression_trigger.png|150px]]

Use this trigger when something must be monitored, evaluated or calculated such as checking a variable or cell value, velocity of the driver or the state of simulator hardware (steering wheel angle, brake or accelerator pedal position) or distance from the driver to some other object in the scenario.

Multiple expressions can be used within the same expression trigger. In those cases, all expressions must evaluate to True in order for the action stack to execute unless using an '''OR''' operator.

Use the '''OR''' operator - the pipe character "|" if you want to activate the action stack if '''any''' of the expressions evaluates to True.

In the following example, the trigger checks for TrialNumber = 1 and FirstButtonPress variables, and then checks if Aux Button 1 or 0 was pressed:

'''ReadVar('TrialNumber') = 1.0 & ReadVar('FirstButtonPress') = 1.0 & (ReadCell('Auxiliary_Buttons', 0) > 0 | ReadCell('Auxiliary_Buttons',1) > 0)'''

'''Note''': Expressions can also be embedded into some other triggers, most notably the Set Dial >> ADO >> Forced Velocity action often used in Roadpad triggers.

'''Follow Trigger'''
[[File:isat_follow_trigger.png|150px]]

Use this trigger when something has to happen based on one ADO position relative to another scenario element (including the XD). The follow trigger requires a leader and a follower to be specified; when this condition is met, the trigger action stack activates.

'''Note''': Both leader and follower must be positioned on the follow trigger roadpad to satisfy the follow parameters.

'''Geometric Position'''
[[File:isat_geometric_position_trigger.png|150px]]

This trigger is most useful to perform actions for off-road actors such as walkers. The trigger predicate is limited to Name or Type and requires a geometric position to be defined.

A more limited version of the geometric position trigger can be implemented with a Global Time Trigger that contains a Creation Radius. Placing the creation radius defines the area where the trigger may be activate.

===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

[[File:Screenshot (208).png|800px]]

'''Note:''' The highlighted lane shows which lane is the '''activating lane'''. Other lane/s will not activate the trigger action stack.

===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

[[File:TTA.png|400px]]

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===

[[File:other_triggers.png|400px]]

*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===

Execute actions if input expression evaluates to TRUE; the expression is specified on the trigger Predicate tab.

====Syntax====
Expression triggers support a simple language syntax with operators and functions.
The syntax is infix notation; i.e. a + b, not a b +.

Note: It is not generally possible to embed one function call inside another:
cos(sin(x)) is therefore an invalid expression. ISAT will report invalid expressions during rehearsal of a scenario. Invalid expressions are not supported and will not operate as written during simulation.

'''Exception:''' Currently it is possible to use the square root function with GetObjDistPow2 as in the following example:

sqrt(GetObjDistPow2('Target_Object_Name'))

Multiple expressions may be combined using the logical AND (&) or OR ("|" pipe character).

Exp1 '''&''' Exp2, Exp1 '''&''' Exp2 '''&''' Exp ''N''

All expressions must be true for the trigger to evaluate to TRUE and execute the action stack.

Exp1 '''|''' Exp2
One of the expressions must be true for the trigger to execute the action stack.

Negative values are not directly supported by the expression parser. To use a negative value, it must be a calculated value such as the following:

'''ReadCell('CFS_Steering_Wheel_Angle',0)<(0-5.0)'''

==== Operators ====
Operators are used to create expressions.

'''String'''
:Used within quotes as a string literal; i.e., 'some string'

Grouping
:Parentheses group elements together; i.e.,
:'''()'''; (a), (a + b)

Multiplication
:'''*'''; a * b

Division
:'''/'''; a / b

Addition
:'''+'''; a + b

Subtraction
:'''-'''; a - b

Note: negative values must be expressed with a subtraction operation:
(0 - 5), not -5 (invalid)

Greater than
:'''>'''; a > b

Less than
:'''<'''; a < b

Logical And
:'''&'''; a & b

Both a and b, otherwise returns 0 (FALSE)

Logical Or
:'''|'''; a | b

a or b returns 1 (TRUE)

====Expression Functions ====
Functions are used with operators to create expressions.

Function: '''sin'''
:sin -sine

Syntax
:sin(float x)

Description
:The sin() function returns the sine of x, where x is given in radians.

Return Value
:The sin() function returns a value between -1 and 1.

Function: '''cos'''
:cos –cosine

Syntax
:cos(float x)

Description
:The cos() function returns the cosine of x, where x is given in radians.

Return Value
:The cos() function returns a value between -1 and 1.

Function: '''ReadCell'''
:ReadCell()

Read a Cell value.

Syntax
:ReadCell(string Name, int Cell Array index)

Description
:ReadCell returns the value of a given cell (a cell is the current instance of a variable that will be maybe written to a daq file).

Index specifies a 0 based index into the array. Since most cells are single element arrays, a value 0 indicates the first element.

Cells valid for the ReadCell function are defined within the cell collect file NadsMiniSim.cec located in the miniSim_x.x\data folder.
The ReadCell function operates on shared memory during simulation, it does not read cell data from the DAQ file.

Cells that are defined may be written to the DAQ; the collect file specifies which cells are saved into the DAQ and what frequency to use for the write operation.
The NadsMiniSimCollect.general.txt file is located in the miniSim_x.x\data folder.

Available Cells:
Any cell that has been defined in the .cec file. For example:

:'''LogStreams''': Array of 5 floats. Logstreams are a set of values the scenario author can write to through “write to logstream” actions.
:'''AccelPedalPos''': Single Value. The current position of the accelerator pedal
:'''BrakePedalForce''': Single Value. The current force on the brake pedal in pounds
:'''SteeringWheelAngle''': Single Value. The current rotation of the steering wheel
:'''CruiseControl''': Single Value. The current cruise control position. (values are cab/platform specific)
:'''TurnSignal''': Single Value. The current position of the turn signal (values are cab/platform specific)
:'''OvVel''': Single Value. The participant’s current speed in miles per hour
:'''OvLaneDev''': Single Value. The participant’s lane deviation in feet.
:'''OvHeadwayToLeadVeh''': Single Value. The distance in feet to the first vehicle in front of the participant. -1 if no vehicle can be found.
:'''OvTtcToLeadVeh''': Single Value. The time to collision to the first vehicle ahead of the participant.
:'''Horn''': Single Value. The state of the horn (values are cab/platform specific)
:'''DynObj_Vel''': Array of 20 floats. The speed of a given dynamic object. Dynamic Objects are sorted in terms of distance to driver.
:'''OvVelLocal''': Single Value. The participant’s current speed in miles per hour, using the value local to scenario control

For a complete list of cells and array elements please see the miniSim data dictionary spreadsheet.

Return Value
:Returns the value of the specified cell.

Example
ReadCell(‘LogStreams’,5) > 3

Function: '''CellEquals'''
:Cell Equals, array element, value to compare

Syntax
:CellEquals(string name, int index, float value)

Description
:The Cell Equals function is similar to the ReadCell function, except it adds an additional value to compare against the cell value.

Like ReadCell, name specifies the name of the cell, index specifies the cell array index (use 0 for single value cells).

Available Cells:
:Any cell that is defined in the .cec file.

Return Value
:Units: 1 or 0
:1 if the cell value is equal to the passed in comparison value; otherwise 0

Function: '''GetObjDistPow2'''
:Get object distance squared

Syntax
:GetObjDistPow2(string name)

Description
:GetObjDistPow2 returns the distance squared between the external driver and the dynamic object specified by ‘name’.

Distance squared is used to avoid having to perform an expensive square root calculation every frame.

If the specified object cannot be found, a value larger than 100 million is returned.

Return Value
:Feet; Distance in feet measured from the eye position of the driver to the CG (centroid) of the dynamic object specified.

A very large number is returned if the specified object cannot be found (larger than 100 million)

Example
:GetObjDistPow2(‘OncomingCar1’) < 2500

'''Note:''' To get an actual distance, multiply by the square root (sqrt())
: sqrt(GetObjDistPow2('Target_Obj'))

Function: '''GetObjTtcToOv'''
:Get Object Time To Collision to Own Vehicle

Syntax
:GetObjTtcToOv(string object name)

Description
:GetObjTtcToOv gets the time to collision from the dynamic object specified by the name parameter, to the own vehicle.

Return Value
:Unit: Seconds
:Time (seconds) to collision from the own vehicle to the dynamic object specified by the name parameter.
:0 is returned if the object specified cannot be found.

Function: '''GetObjVel'''
:Get Object Velocity

Syntax
:GetObjVel(string object name)

Description
:GetObjVel gets the velocity in meters per second of the first dynamic object with the name specified by the ‘name’ argument.

Return Value
:Unit: Meters per second
:The speed of the specified dynamic object; 0 if no object is found

'''Note:''' Multiply by 2.23694 for miles per hour.

Example
:GetObjVel(‘PullOutVeh’) > 15.4

Function: '''Rand'''
:Random

Syntax
:Rand(int value)
:Rand(string name)
:Rand(string name, string type, double parameter, double parameter)
:Rand(string name, string type, int parameter, int parameter)

Description
:Rand returns a random value specified by the name of the generator, the type of distribution and its parameters.

If the user does not specify the name of the generator and only specifies a number as the only parameter, the Rand function will use a default random number generator to produce random numbers.

If the user only enters the name of a user created random number generator, the random number generator will produce a value between 0 and 1.
If a name of generator is supplied that has not been created, the Rand function will display an error message in the ISAT debug window and return 0 (during scenario rehearsal).

The rand function supports multiple types of distributions that can be used to generate a random number.

Types of Distributions:
:normal: Normal Distribution(mean, standard deviation). The normal distribution generates random numbers near the mean with a specific standard deviation.
:gamma: Gamma Distribution(alpha, beta). The gamma distribution generates a random value that models waiting times for the Poisson process.
:uniformInt: Uniform Integer Distribution(min, max). The uniform integer distribution generates a random integer number between the lower and upper bounds.
:uniform: Uniform Real Distribution(min, max). The uniform real distribution generates a random floating point number between the lower and upper bounds.

The values stated in the parenthesis above are the parameters for each distribution in order. If the incorrect number of parameters are entered or if they are entered incorrectly, the debug window in ISAT will display an error message and the rand function will return 0 (during scenario rehearsal).

If the distribution is entered incorrectly, the debug window will also display an error message.

Return Value
:A random value from 0 to 1 if the type of distribution is not specified.

If the type of distribution is specified, returns a random value determined from the type of distribution and the given parameters.

Example
:Rand(‘myRandGenerator’,’uniformInt’,1,10)
:This example returns a random integer value from 1 to 10.

Rand(5) or Rand(‘myRandGenerator’)
:These examples return a random value between 0 and 1.

Function: '''sqrt'''
Square root

Syntax:
:sqrt(parameter)

Return Value:
: return the square root of the specified parameter.
: parameter can be another function, such as GetObjDistPow2()

Function: '''ReadVar'''
:Read a variable

Syntax:
:ReadVar(string Name)

Return Value:
:Returns the string value of variable specified in <variable_name>

===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.

=='''Audio Components'''==
The components of the Audio sub-system includes configuration and data files installed into the NadsMiniSim_x.xx\data\sound\DefaultCabSound\Instructs folder.

[[File:audio_components.png|400px]]

The audio engine contains multiple channels and has a theoretical limit of 512 simultaneous sounds.

NOTE: Not all .wav files are compatible with the Audio Engine.

=Scenario World Objects=
Scenario world objects are defined in the tile model source. They are not added by the scenario author since they are objects already present in the roadmap/BLI.

[[File:object_types_world.png|400px]]

Typically, but not always, these objects can be authored in ISAT. However, some scenario world objects have no options - these cannot be selected in ISAT; therefore such objects cannot be authored.

Removal of world objects requires editing the source tile model using a 3D application. In some cases an alternate tile model is available identical to the original but without objects.

Contact NADS if removal of a world object is needed.

Other scenario world objects, such as Traffic Signals, are specialized function objects that can be authored. Traffic signals are authored using the Traffic Light Manager: Edit >> Traffic Light Manager.

=Troubleshooting Scenario Objects That Reset=

== Scenario World Objects ==
Scenario world objects are already present when you create a new scenario - they are not added by the scenario author. These objects may be visible in miniSim but not in ISAT, or they may be visible in ISAT and seem to be controllable, but the objects 'reset' to their defaults when viewed on miniSim.

[[File:2019-10-23_16h18_47.png|700px]]

The objects which 'reset' are a symptom of settings in the TMT that are not configured to allow scenario authoring of objects.

[[File:2019-10-23_16h18_52.png|700px]]

When objects appear to 'reset' or if you can edit an object in ISAT but don't see your changes in miniSim, correct the problem by resolving controllability in the TMT settings: https://www.screencast.com/t/ZH5Dh178.

=Scenario Coordinate Types=
There are two types of coordinates used in scenarios. The first is roadway coordinates. These coordinates are contextual (tied to a specific road or intersection and position) and are used for ADO objects and roadpad paths in general.

After a roadway coordinate has been generated, it is not updated unless the scenario author makes changes to the start, end or location of the entire path or pad.

Roadway coordinate are the reason it is not possible to change a roadmap using the TMT and expect a previously authored scenario to work on the altered roadmap. If the length or location of a road changes, the path/pad will update to the extent possible.

If the road has been eliminated and no longer exists in the roadmap/BLI, ISAT will report an error and not open the scenario file.

A. Field breakdown:
RoadPos keyword <name of road:lane:position on road:path length>

Name "Ado1"
RoadPos "r1_-6600_4620:0:5737.06:0.00"
Path "R:r1_-6600_4620:0[5736.06:5873.83]"

[[File:isat_coordinate_types.png|400px]]

B.
Name "VirtObj"
Option 2
Position -6.8375599E+002 5.6331237E+003 0.0000000E+000

The second type is world coordinates, which are Cartesian coordinates with X increasing to the right, Y increasing forward, and Z increasing up.

='''Scenario Authoring'''=
Scenario authoring is the creation, editing and testing of everything that happens during a simulation drive.

==Cell Operations: Best Practice==
Reading and writing to cells is a computationally expensive process. Best practice is to centralize all the reads/write to one place so that it’s only done once per cell.

Once a cell is read, the value is copied to a variable and only the variable is used throughout all the triggers that need it.

The same process applies to writing to cells. Use of variables can reduce the Cell Operations overhead greatly.

==Before You Begin==
Before beginning a scenario, it is necessary to understand the following requirements:

=== Drive Requirements===
How long is the drive?
What type of roadway?
Are there any specialized road elements (intersections, interchanges, freeway ramps)?
Are there any environmental requirements (should the simulation replicate a real world location, or is a generic environment acceptable)?
Is there a particular roadway configuration that is needed (long straight rural road vs. typical urban environment with intersections, signals, etc)?

=== Traffic Requirements ===
What types of traffic will be needed?
Will ambient traffic interact with the external driver?
What types of interaction will be required (traffic cloud, lead vehicle, follow vehicle)?

=== Events ===
The purpose of an event is to present a situation to the external driver. In order for the simulation to produce meaningful data, it is critical that events unfold for each driver in a comparable way. Therefore, each event must be designed with this repeatability in mind.

'''NOTE:''' one of the most variable scenario elements is the driving style of each external driver: how conservative or aggressive they drive, velocities throughout the scenario, how comfortable the driver is travelling with simulated vehicles, etc.

Repeatability often includes static elements (each driver encounters scenario elements in the same location) or in cases where the driver performance is taken into account, accommodation of the driver dynamic (velocity, lane position) through the use of time to arrival triggers (TTA) or follow triggers. A TTA trigger will fire based on time to a target location - thus a driver travelling at 45mph or a driver travelling at 55mph can both experience the same action relative to that target location, irrespective of the different driver velocities.

==Beginning A Scenario==
All scenarios designed to be driven require a start location - the place where the driver will be located when the simulated drive begins.

To insert a start location into a scenario:

:Insert >> External Driver >> LMB on road, intersection or terrain object

[[File:isat_initial_position.png|400px]]

'''NOTE:''' scenarios that only contain data and are not intended to be driven - for example, signs or traffic that are used as external reference files do not require a start location, since that will be defined within the parent scenario.

==Initial Conditions==
Initial conditions define how the simulated scene is configured: will the drive occur during daylight or night time conditions? Will the ownship (external driver vehicle) have headlights enabled? What type of vehicle will it be? Will there be objects or traffic visible to the driver?
These form the initial conditions of the simulation experience. Additional initial conditions would include initialization of variables or establishing networked communication as needed by the scenario.

[[File:isat_initial_conditions_miniSim.png|400px]]

By default ISAT sets the initial condition '''Time of Day''' to 12:00 noon. The time of day is controlled from the Initial Conditions dialog:

Edit >> Initial Conditions

[[File:isat_initial_conditions_scenario.png|400px]]

==Scenario Authoring: Actions==
Actions are the scenario elements that make things happen during simulation. Actions do specific things, like display a text message on screen for the driver, create a scenario element, change the velocity of simulated traffic, change a traffic signal, etc.

[[File:trigger_action_panels.png|400px]]

The diagram above shows the action panel for left to right: an expression trigger, a roadpad trigger and a global time trigger showing different panels based on the actions present in each trigger.

'''NOTE:'''Actions can be created, edited or removed from the '''Actions panel''' of '''any trigger'''.

'''NOTE:''' The Actions panel changes based on the action type created.
When multiple actions have been defined, control the sequence of actions by changing the action order in the list using the up or down arrows next to the list.

[[File:action_panel_overview.png|400px]]

If multiple actions need to happen in a specific order, set the order using the arrows and then flag the action list as '''sequential'''. This instructs behaviors to process the actions in the list order.

Using a delay for any action will pause processing of the '''following actions'''; the action happens first, then the delay is applied.

===Scenario Authoring: Action Types===
There are two types of actions:
# Instantaneous - the action takes up to one frame to complete, i.e.:
:set target velocity
:write to cell
# Persistent
<span style="color:red">'''*Persistent actions do not end'''</span>, or take multiple frames to complete:
:Forced lane offset
:Forced velocity
:Maintain Gap

==='''Actions'''===
*The "Who to Affect" field defines what is affected by the action
:Instigator set: who activated the trigger
:Name: one or more named elements
:Type: Apply changes to all objects matching the specified type
:Relative: Position relative to the trigger location

*Sequential
:Actions to execute sequentially, one after the other
:Specify delay between actions
:: Action executes, then delay

:Some actions are persistent and never "finish"

===Scenario example: display text & roadpad trigger to stop the drive===
This scenario is very simple and contains a global time trigger (GTT) that tells the driver what to do. After the driver travels along the roadway, a roadpad trigger (RPT) is used to tell the driver to stop driving. The same RPT also creates an expression trigger to terminate the drive.

TBC example scenario file

Because the external driver is not under control except by instructions, it's possible they might ignore the halt message and continue driving. A second failsafe RPT then terminates the drive.

==='''Actions: Button vs. Dial'''===
*Dial changes a setting
*Button: always runs in a single frame
:-"immediate" change. Typically buttons have less control than a '''Set Dial''' action

==='''ADO Actions'''===
[[File:ado_action_types_button_vs_dial.png|400px]]

==='''DDO Actions'''===
[[File:ddo_set_dial.png|400px]]

==='''External Driver Actions'''===
External driver behavior can be influenced by reinforcing scenario actions through audible speeding alerts, on-screen text instructions and messages or audio instructions.

Driving behavior can be influenced with situational elements
:Car in the drivers blind spot
:Lead vehicle
:Aggressive following vehicle
:Temporary lane closure
:lane specific instructions

Scenarios should '''not rely on specific driver actions to be successful'''
:to the extent possible; sometimes you do need the driver to respond/behave in a controlled manner.
:A work zone blocking one lane typically will require a roadpad placed upstream from the work zone to shift traffic into the correct lane

'''NOTE:''' Controlling driver actions should be an experimental design consideration.

==='''Special Actions'''===
These actions need special handling:
*Reset or "toggle":
:Audio
:Display Text

:'''Ado'''
::Audio State
::Forced Velocity
::Maintain Gap
::Visual State

*If using these persistent actions, place them at the '''end''' of an action sequence (because no action following these will execute):
:Forced Lane Offset
:Forced Velocity
:Maintain Gap
:Visual State

*Note: If the Visual State action contains a duration then it will be handled as a normal action, with subsequent actions firing after it. However, if there is no duration supplied with the Visual State action it behaves like a persistent action, and nothing following it in the Action stack will ever fire.

[[File:multiple_simultaneous_actions.png|400px]]

The diagram above shows how one parent trigger can be used to create multiple simultaneous triggers

*How to activate multiple unique force velocity (FV) or maintain gap (MG) actions:
#create the needed triggers from a general parent trigger, 1 per action
#put common actions into the parent trigger
::reset FV
::reset MG

==Scenario Authoring How To==
This section contains simple examples for various typical scenario situations.

===How do I specify an event?===
First, determine which method is best for you - the default measures (limited measures, 20 events max) or logstreams (all simulation data, no event maximum).

Regardless of method, you specify an event by identifying areas of significance in the drive and marking them so the data within the event region can be processed. Any trigger combination that can specify event start and event end may be used.

[[File:2022-07-01_11h21_52.png|400px]]

===How to know Which Coordinator or Trigger I need?===
The answer to this question lies in the type of information needed for an event:

*Time
:global time trigger
:or an expression trigger that calculates time
*Position or Location
:roadpad trigger
::or a time to arrival (TTA) trigger
::or an expression trigger that calculates distance
*Calculation
:Expression trigger

===How to Instruct the External Driver===

Instructions to the external driver can be accomplished by three main methods:
# Instruct the driver using experimental protocol (instructional or briefing presentation)
# Information messages displayed on screen: '''Action: ''set visual display text'' '''
# Information messages delivered as audio messages: '''Action: ''write to cell > SCC_Audio_Trigger ><audio ID>'' '''

===How to Add Traffic in the Scene ===

Generating traffic will happen in one of 5 ways:
# Created explicitly by inserting ADO, or copy/paste existing ADOs
# Created with a script
# Via a Create action inside a trigger, or placing scripted traffic inside a create action within a trigger
# From a '''Traffic Source'''*
# From the '''Traffic Manager'''**

Each of these methods has advantages and disadvantages.

==== Create Explicitly ====

The biggest advantage with this method of traffic creation is the high degree of control the scenario author has over:
# location of the created ADO
# Name of the created ADO
# Travel path of the created ADO
# Control when each ADO is created within the scene via Settings >> Creation Radius

The disadvantage is that creating a high volume of traffic will take some work with this method.

==== Created with a Script ====

This method combines the advantages of Creating Explicitly with volume. It is possible to create a large volume of traffic very easily with a script.

Disadvantages of using high volumes of traffic with a script: in the event it becomes necessary for a high degree of control over these ADOs, more is not better because ADOs will adapt to road conditions under their own power, unless the default ADO settings have been modified:
'''lane changes, including lane changes to accommodate freeway ramps'''
'''velocity adjustments'''

==== Via a Create action inside a trigger ====
Combines the advantages of the previous 2 methods with control over when to activate that traffic using a trigger action.

Disadvantages: Creating too many ADOs at one point in the drive can cause the miniSim to bog down for a few frames. If too many ADOs are present and active in the simulation at one time, this can cause the miniSim to drop frames and run sluggishly. This is highly noticeable and may increase the potential for the External Driver to experience '''simulator sickness.'''

==== From a '''Traffic Source''' ====

Traffic Sources rely on two methods to populate a scene with traffic:
# location specific, with each ADO created for a traffic source being a 'spawn location' for ADOs, or
# location agnostic if the ADO has '''relative creation''' enabled, thus being created relative to the object identified.

In addition to being created relative to a scenario element, ADOs are created relative to the specified scenario element:
# In front of (Longitudinal Distance > 0, where the number is feet offset from the object) , or
# Behind (Longitudinal Distance < 0, where the number is feet offset from the object).

Advantages: Can easily populate traffic into the simulation.

Disadvantages: It is easy to generate more traffic than the simulation can maintain at 60Hz frame rate, thus introducing frame lag with the resulting scene 'stutter' and the increased risk of simulator sickness.

Also, traffic created from a Traffic Source is generic traffic. It is not possible to reliably refer to specific ADOs generated from a traffic source except by using Who To Affect >> Relative (versus referring to a named ADO, i.e. Slow_Moving_Lead_Vehicle). Referring by name to Traffic Source generated ADOs will affect all similarly named ADOs at the same time.

==== From a '''Traffic Manager''' ====

The traffic manager interface is problematic in ISAT versions up to 1.8.5, especially when specifying the set of vehicles to be used for generating traffic.

Advantages: Create generic ambient traffic easily.

Disadvantages: Has the same disadvantages as traffic created via a Traffic Source. Also getting a traffic set working by specifying the vehicles to be used within the set. ISAT versions up to 1.8.5 exhibit instability when setting vehicles in ISAT.

Traffic Manager Set workaround: Borrow a working set from an existing scenario or group. Alternatively use a version of ISAT (1.8.6 +) to create the traffic set. This can be saved as a scenario or group file, which can then be used with ISAT 1.8.x as long as there is no attempt to adjust the vehicle weights within ISAT. The scenario or group file can be edited as text in a text editor, but care must be exercised to avoid introducing errors into the file. ISAT will not read invalid scenario or group files.

Traffic generated by the Traffic Manager is controlled through the use of Input Sets. An input set is a collection of vehicles and weights used to populate the scene during simulation. This is how the scenario author can control the vehicle population (type and number), density and creation/deletion distances - these attributes are unique to each set.

Since there is no 'discontinue traffic manager' function, one can be implemented by defining an input set with no traffic (an empty input set). An appropriate name can make the purpose of the set clear: PauseTraffic, Stop_TM, etc.

==== Sample Traffic Manager Set ====
This is a sample traffic manager set that can be pasted into a scenario file after the HCSM VehFail section. Be sure to paste '''after''' the HCSM VehFail end tag ('''&&&End&&&''') in your scenario file.

'''Note:''' A scenario file may contain only '''one''' Traffic Manager section.

There are two input sets in this example; note how they contain different vehicles and different settings from each other.

<span style="color:#2a4b8d">HCSM TrafficManager
GroupName "Traffic Manager"
HCSM InputSet
Name "ONE"
MinDensity 3.0000000E-002
MaxDensity 7.0000000E-002
MaxObjects 9
CreateDist 2.0000000E+003
DeleteDist 3.0000000E+003
AbsDeleteDist 3.4000000E+003
RunFreq 1.0000000E+000
SolWeights "cargill_semi_peterbilt_blu:2" "cargill_semi_freightliner_red:1" "cargill_semi_peterbilt_yel:3" "DumpTruck_org:3" "semi_peterbilt_yel_Walmart:2" "Cadillac_Escalade:10" "Ford_F150Xcab:15" "Saturn_Vue:10" "FordTaurus:15" "Escape:15" "DumpTruck:2"
&&&&End&&&&
HCSM InputSet
Name "TWO"
MinDensity 1.0000000E-002
MaxDensity 3.0000000E-002
MaxObjects 4
CreateDist 2.5000000E+003
DeleteDist 3.3000000E+003
AbsDeleteDist 3.5000000E+003
RunFreq 1.8000000E+000
SolWeights "Taurus2011:12" "Cadillac_Escalade:16" "Ford_F150Xcab:24" "Saturn_Vue:14" "Escape:6" "Deville:24" "Audi:4"
&&&&End&&&&
&&&&End&&&&
</span>

====='''Managing Traffic Manager Input Sets'''=====
During simulation, Input sets are controlled by the action '''Use Traffic Manager Set'''. A set name must be provided for this action to work.

===== Traffic Manager generated Traffic=====
ADOs will populate the road network around the XD based on the parameters of the Input Set. Typically traffic is removed from the scene shortly after passing the XD. This is visible in the rear view mirror. There is currently no way to adjust this delete distance.

====== Traffic Manager Traffic on 2 lane freeway======
Traffic will prefer to be in the XD lane, so ADOs created in any other lane will tend to veer into the XD lane. On a divided highway, traffic is generated moving with the XD.

====== Traffic Manager Traffic on 2 lane road======
Traffic is generated in the oncoming lane. In some cases traffic may be generated then immediately removed in front of the XD.

===How to Control Objects in the Scene during Simulation ===
"Set and forget" options on simulation entities only require the scenario author to "initialize" the element to a desired setting and then it is left alone during simulation.

Controlling objects dynamically during simulation requires the scenario "talk to" each object with a scenario action. This section describes how each scenario object type can be controlled during simulation within a scenario.

All models used in ISAT are listed within the Scenario Object Library (sol2).txt files. Terrain switch names are displayed in the ISAT workspace.

All model switches are listed within the NadsMiniSim_x.x\bin.x64\ModelList.txt file.

'''Note:''' The diligent reader will note discrepancies in model names between the sol2 and ModelList files. This is because the ModelList file contains actual file names, and the sol2 files define a "name label" for models that may, or may not, be the actual model name. Objects are linked between the sol2 and ModelList files through the ModelID/CigiID records. These values will match between sol2 and ModelList files, but IDs are not necessary at this time for scenario authoring purposes.

Complicated object names can be retrieved from the LRI file that was used to build any scenario file; each BLI is preceded by an LRI. The LRI contains all of the terrain models that will be present in ISAT. These are typically speed limit signs, traffic signals or other features that may be controllable.

'''Note:''' this file may not be present for the Springfield.bli file.

An alternative is to capture a screenshot of the ISAT workspace with the element name string showing. By default ISAT reports the name of any objects when the cursor passes over the object, as shown in this example:

[[File:2021-10-27_08h50_14.png|caption =Object Name Screenshot | 400px]]

{|class="wikitable"
|+ Controlling Scenario Elements During Simulation in Scenario
!Date
!Nads miniSim version
!Object Type
!Scenario Action
!Who To Affect
!Value
!Notes
|-
| Oct. 28, 2021
|2.3
|-
|
|
|Static Object (terrain)
| SetDial > StaticObjManager > Set Option1
| StaticObjManager
| switch name : switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
|Static Object, multiple options
| Set Switch
| Name of element
| switch option
|-
|
|
|Obstacle, multiple options
| Set Switch
| Name of element
| switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
| DDO, multiple options
| Set Switch
| Name of element
| switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
| ADO
| Set Dial > ADO > VisualState
| Name of element
| Limited to options present in ISAT
|-
|
|
| Traffic Signal
| Traffic Light
| Assign action to element
| Target state
| Target state must exist within the Traffic Light Manager intersection timing table for the specified signal

|}

===How to Control Simulated Vehicles===
The scenario author can control simulated vehicles by controlling the environment:
#change a traffic signal to cause an ADO to stop or start at intersections
#affect other ADOs to cause a target ADO to respond
# assign a path for the ADO to travel

Direct control:
*Lane related:
:Set button > ADO > ChangeLane, Turn, ProjectAndResetLane

*All other controls:
:Set Dial > ADO > AudioState, ForcedLaneOffset, ForcedVelocity, InhibitLaneChange, LaneChange, MaintainGap, TargetVelocity, VisualState, AudioState

====How to Change ADO Velocity====
ADO velocity can be changed using the SetDial action:
:SetDial > ADO >

:ForcedVelocity
:ForcedVelocity using an expression:
# match external driver speed
expr % OvVel(0) %
# multiply external driver speed
expr -1 9 %ReadCell('OvVelLocal',1)*1.75 %
:TargetVelocity

Indirect Control (dependent on other scenario element):
:MaintainGap

====How to Link ADO Velocity to Something Else====
ADOs velocity can be linked to other ADOs or the external driver using the MaintainGap (MG) action.

SetDial > ADO > MaintainGap

When using a traffic cloud containing multiple ADOs, each ADO in the cloud needs a unique MG. IF multiple ADOs have the same MG settings they will attempt to satisfy their parameters and likely oscillate position in a visually obnoxious way.

===How to Author Loop Scenarios===
A scenario created on a loop road network operates very much like any other scenario, with the exception that it is likely to require tracking the number of times through the loop, or to present scenario events to the external driver depending on each loop context.

[[File:loop_traffic_creation_01.png|400px]]

The simplest method of tracking loops is the use of a loop counter variable. This variable can be set by the driver "stepping onto" a roadpad trigger or it can be initialized through the use of a timer or expression, with increments managed by a roadpad trigger. Each time through the loop increases the loop count variable.

Thus it becomes possible to create events for each loop based on the loop counter variable, typically through an expression trigger.

Loop management triggers

[[File:loop_management_02.png|400px]]

Loop management trigger detail one

[[File:loop_management_vars_02b.png|400px]]

Loop management trigger detail two

[[File:loop_management_3.png|400px]]

====Creating Loop Specific Traffic====
Creating loop traffic is slightly more complicated due to the number of objects to be created and potentially the size of the actual loop. A small loop is installed with the Nads miniSim as simple_rural1 or simple_rural2. Each is a loop road network with two signed 3-way intersections.

Loop specific traffic can be created through the use of a variable (i.e., LoopCount) or within the roadpad trigger that is incrementing the loop count variable. Both methods will incorporate a '''Create Action''' that creates the required elements.

===How to Change Environment Settings===
The scenario author can define global or localized environment conditions.

1. Insert >> Environment Conditions >> <chosen condition>

2. Define a region where the environment condition is active:
:LMB to define polygon points
:RMB to exit point entry mode

[[File:env_condition1.png|400px]]

Choosing an environment condition

[[File:env_condition2.png|400px]]

Environment region defined and parameters panel shows available options

NOTE: The environment condition boundary is a discrete threshold. Condition A will be on one side of the threshold. Immediately after crossing the boundary, condition B will be displayed.

===How to Fade an Environment Condition===
To fade gradually between two conditions requires the use of an expression that continually monitors the desired condition and sets a few variables based on the results.

Examining the demo scenario is the best way to look 'under the hood' to see exact command syntax and values to be used.

[[File:env_fade.png|400px]]

Note: this approach has been used for fog and visibility. It is unknown how it might work with non-visibility conditions such as precipitation and wind.

*From the scenario demo_visibility_transition.scn

[[File:env_fade_schematic.png|400px]]

'''Note:''' although the example above uses an environment condition boundary, '''it is possible''' to omit the defined region, retaining all commands and the scenario will still function. However, without the environment region, it becomes more difficult to determine where conditions are different from the standard settings.

===How to Control a Cab Instrument Panel icon===
In order to control the instrument panel, there are 2 requirements:
The specific cab used for the scenario
The specific control (switch) to be manipulated
The action for addressing the instrument panel is '''ChangeCabSetting'''

Instrument panel models are located in NadsMiniSim_x.x\data\Visuals\Instruments
These files are in OpenFlight format. Any 3D editor capable of reading or importing OpenFlight can be used to review these files. NADS uses the Presagis product Creator[tm].

An alternative method to inventory switches is to use the the '''buildscl.exe''' tool. To run the tool, open a CMD window to the IP folder location above, then run the command:
buildscl <input_file.flt><Enter>.
<input_file.flt> is the name of the file to process, without the '<>' characters.
<Enter> means to press the Enter key,

The result will be in a new file ending with .scl. This is a text file, and can be opened in a text editor or you can use the shell utility '''more''' to view the file contents:

more <input_file.scl> | grep switch<Enter>

An example for the malibu cab is shown below. .

switch s_LowWasher 0
switch s_Cruise 1
switch s_LeftTurn 2
switch s_RightTurn 3
switch s_FwdCollisionWarn 4
switch s_BlindSpotWarn 5
switch s_LaneDeviationWarn 6
switch s_RearCollisionWarn 7
switch s_HighBeamHeadlights 8
switch s_SeatBelt 9
switch s_UpArrow 10
switch s_Airbag 11
switch s_CheckEngine 12
switch s_CheckGuages 13
switch s_ABS 14
switch s_Brake 15
switch s_LowFuel 16
switch s_Gear 17

These controls may be accessed directly in scenario using the ChangeCabSetting action.

'''NOTE:''' Some functions such as Cruise, Gear, High beam headlights, Blind spot, collision, lane deviation warnings are '''normally''' controlled not by direct access as described here but by hardware mechanisms/buttons.

'''NOTE:''' For altering cab instrument panel operation it will be necessary to modify the OpenFlight model to include the desired funationality; for example, instrument panel blanking is not build into the model but can be added by editing the cab instrument panel model file then installing the modified file into miniSim.

===Scenario Hints===
The total number of scenario elements active at any given time can affect simulator performance:

Total number of active elements
*vehicles (ADOs), triggers, animations, etc.

Object management
*Use paths to shift ADOs away from the driver route of travel as they turn off the route
*reduce the number of vehicles in traffic cloud surrounding external driver
*use creation radius to limit the number of active elements, and to remove elements after the driver has traveled beyond the creation radius

[[File:creation_radius_1.png|400px]]

Creation radius works by activating the scenario element only when the driver is within the radius. The scenario element is created when the driver enters the creation radius, and is deleted after the driver leaves the creation radius.

Exploit environment to reduce object load

*Use curves, hills, intersection corners to mask objects

Object deletion
*Remove objects when no longer needed

When creating dynamic elements, create them as close to where they are needed as possible.

====How to Determine When ADOs are Visible to the External Driver====

Some development/setup testing may be needed to determine precise location/distance/speed; i.e., locating ADOs for a freeway ramp merge event where the external driver is merging onto the freeway with other ambient traffic present.

Unless the purpose of the event is to study driver behavior at the merge, ideally the scenario will be authored to have ambient traffic on the freeway but not to present a conflict at the merge for the external driver.

A straightforward way to determine where the ADOs are first visible to the driver is to mock up a scenario placing colored ADOs along the freeway with a velocity of 0. This will ensure the ADOs remain stationary while the scenario author determines where they are first visible to the external driver.

Place the start position/external driver far enough up the ramp to be a reasonable test for the actual scenario.

As you drive the ramp, see which ADO is first visible to the driver. Place ADOs just out of view (upstream) of that location.

[[File:merge_hint.png|400px]]

'''NOTE:''' use test vehicles of the same type and character as the intended scenario vehicles. For example, do not use a sedan test ADO for a larger vehicle (SUV, bus, dump truck). Doing so will invalidate the visibility test, because a larger ADO will be visible over a longer distance than a small ADO.

[[File:ramp_vis_1.png|400px]]

At the scenario start location, ADOs in front of the Coke truck are visible. Note how the larger vehicles are more obvious at this distance.

[[File:ramp_vis_2.png|400px]]

The driver has traveled onto the ramp. At this point, the last ADO visible to the driver is still the Coke truck.

[[File:ramp_vis_3.png|400px]]

As the driver travels farther down the ramp a small ADO is visible behind the Coke truck.

The answer to the question '''When is an ADO visible?''' is thus:
#It depends on how large the ADO is
#Small ADOs can be placed at the location of the red ADO behind the Coke truck.
#Large ADOs may need to be placed farther back (behind the red ADO). This test is inconclusive, but based on the terrain it seems likely that large ADOs would need to be placed at least at the green ADO location (behind the Coke truck).

Creating small ADOs at the green ADO location when the external driver is located at the ramp position in 3 travelling at the same speed as the external driver should arrive at the merge slightly ahead of the driver (because the curved ramp is longer than the straight freeway).

'''NOTE:''' ADO size, ADO color, time of day and visibility settings affect ADO visibility.

====How to Position Objects Precisely using '''Place Object At..'''====

ISAT does not support true precision because it is not currently possible to 'dial in' a position as is typical in 3D modelling tools, but there is a way to approximate precision in cases where a consistent measurement is desired.

In the following example a number of roadpad triggers are placed relative to the location where a roadway enters an intersection. This is a discrete boundary within the simulation world as shown in ISAT.

There are two methods of placement possible:
# Measure the desired distance (CTRL+Shift+RMB, drag); take note of the coordinates updating in realtime and make a mental note of the desired location.
#Place an object (ADO or static object); use the Place Object At.. feature from the context menu when you RMB on a scenario object.
Using this method you can specify a distance - positive numbers move the object downstream/forward, negative numbers move the object upstream/backward.

'''Note:'''If the distance is significant and extends over an intersection, ISAT may produce unexpected and undesired results such as re-starting the measurement from the closest upstream intersection, thus placing the object where it was not intended.

In the following example, Place Object At.. is used to specify a point 50 feet upstream from the road/intersection border.

[[File:precision_placement_1.png|400px]]

A roadpad trigger has been positioned near the area of interest. Any existing roadpad is deleted from the trigger.

[[File:precision_placement_2.png|400px]]

An ADO is used as a marker object inserted temporarily into the scenario. Any convenient object may be used.

'''Note:''' large objects such as ADOs may be less precise than small objects such as the Traffic cone, but is generally easier to access in the ISAT interface unless you have created a script for cone objects.

[[File:precision_placement_3.png|400px]]

RMB on the ADO to access the Place Object At.. request dialog. Only numbers are valid entries.

[[File:precision_placement_4.png|400px]]

The desired distance is entered into the Place Object At.. request dialog. ISAT will then require you to select the object you wish to move using LMB.

[[File:precision_placement_5.png|400px]]

ISAT moves the selected object by the distance you specified.

[[File:precision_placement_6.png|400px]]

Use the ADO CG (model center) to place the start of the road pad.

[[File:precise_placement_7.png|400px]]

Remove the ADO marker and save your scenario.

==Scenario Testing and Debugging==
The primary way to test and debug scenarios is using ISAT rehearsal mode.

'''NOTE:''' the external driver during rehearsal is a simulation. You have limited control over the simulated ownship:
#change speed
#change lane

ISAT has two rehearsal dialogs:
#abbreviated (standard) dialog
#advanced (extended dialog)

===How to change to the advanced rehearsal dialog===
Often it is necessary to control the ownship during rehearsal. The ownship controls are located in the advanced (extended) rehearsal dialog.

ISAT will show the Advanced dialog the first time rehearsal mode is activated. All additional activations show the abbreviated dialog.

TBC abbreviated dialog

To use the Advanced dialog, LMB the Advanced button.

TBC Advanced dialog

===How to change ownship speed during rehearsal mode===
After entering rehearsal mode:
#click the Play icon (start the rehearsal)
#pause.
#adjust ownship speed
#toggle pause off (resume rehearsal)

===How to make ownship lane change during rehearsal mode===
After entering rehearsal mode:
#click the Play icon (start the rehearsal)
#click the desired Lane Change (left or right)

===How to Use Audio in your Scenario===
Scenarios play audio sounds and messages through a write to cell action: '''SCC_Audio_Trigger'''

Use of audio in a scenario typically requires both a write to cell and a 'clear action' that writes a zero (0) to SCC_Audio_Trigger in order to 'clear the channel'. The 'clear' action can happen before or after playing a sound; choose one method and be consistent in your scenario authoring.

Failure to 'clear the channel' or '''not''' writing a value of zero can result in no audio being played for subsequent write to cell SCC_Audio_Trigger actions.

The following shows how this looks in scenario when executed from a roadpad trigger (RPT):

[[File:audio_scn_A.png|400px]]

The above diagram is shown below in text format:

HCSM RoadPadTrigger
GroupName "WindGust_Audio"
ByTypeSet "ExternalDriver"
NthFromStart 0
NthFromEnd 0
VehicleAhead 0
VehicleBehind 0
LongComment "This is a wind gust event"
ShortComment " "
ActvDel 0.0000000E+00
CrRad 0.0000000E+00
Debounce 0.0000000E+00
FireDelFrames 0
Lifetime 0.0000000E+00
Name "RPT_WG_6"
OneShot 1
Priority 0
SeqAct 1
Position 6.7165800E+04 6.0419215E+03 0.0000000E+00
DrawPosition 6.7165800E+04 6.0419215E+03 1.1308095E-317
Path "R:r3_62700_7920:0[3033.04:3245.46]"
HCSM LogData
Comment "LS1=8"
Delay 0.0000000E+00
InstigatorSet 0
Stream 1
StreamVal 8.0000000E+00
&&&&End&&&&
HCSM WriteCell
Comment "Play_Audio"
Delay 2.0000000E+00
InstigatorSet 0
CellName "SCC_Audio_Trigger"
CellData "63000"
CellType 2
CellVar 0
&&&&End&&&&
HCSM WriteCell
Comment "clear_audio"
Delay 0.0000000E+00
InstigatorSet 0
CellName "SCC_Audio_Trigger"
CellData "0"
CellType 2
CellVar 0
&&&&End&&&&
&&&&End&&&&

===How to Add Custom Audio Instructions to miniSim===

''' Please note: Custom audio 'instructions' for a scenario should be added to the instructions.txt file.'''

These are sounds that are played in scenario, typically as directions for the minSim driver.

Adding custom audio files requires the following procedure:

1 Exit miniSim - changes to the miniSim configuration should happen only when miniSim is not running.

2 Copy the audio .wav file to:
:C:\NadsMiniSim_x.x\data\sound\DefaultCabSound\Instructs

:Edit the file instructions.txt in that same folder.

3 Add an entry to instructions.txt to register your audio file in accordance with the following layout using the existing entries as a template:

:Unique_ID Filename Normalized_Volume

:Unique_ID is whatever unique number you assign to your file.

:Filename is the name of your .WAV file.

:Normalized_Volume is the volume your audio file should play, where 0.00 is silence and 1.00 is maximum volume.

'''NOTE: Remove all spaces in your audio filename.''' If needed, use the underscore character instead of spaces.

===Troubleshooting Custom Audio Additions===
After installing new .wav files and adding them into the audio configuration file '''instructions.txt''', if the audio file does not play:
*Check the Audio Engine window while miniSim is still running. The Audio Engine will display file errors,.
*If Audio Engine does not display a message similar to: Audio Engine loaded normally, scroll through the window messages and look for any .wav or load error messages.

==Re-use of Scenario Elements==
Scenario authoring can be an intensive undertaking. It makes sense therefore to leverage your development efforts by re-using scenario elements where possible.

ISAT provides a number of ways to re-use scenario elements:
# copy/paste
# external references
<span style="color:#ac6600"># exporting elements as '''groups'''</span>
# isc scripts

Each of these methods have their strengths and weaknesses.

===copy/paste===
The simplest method to re-use scenario elements among different scenario files is copy/paste. This is possible for most scenario elements* even if the source and destination roadmap/BLIs are radically different.

[[File:copy_paste.png|400px]]

It is also possible to copy an ISAT element from one scenario to another as '''TEXT''' by selecting the element and using the windows copy shortcut CTRL-C, then open a text file and paste it using the windows paste shortcut CTRL-V.

'''NOTE:''' Traffic sources are '''not''' portable using copy/paste.

'''NOTE:''' Not all elements can be copy/pasted. Elements created from a Create Element action cannot be copied - it is necessary to select the parent element and copy that instead.

[[File:copy_paste2.png|400px]]

In the above diagram, elements at '''B''' and '''C''' cannot be copied/pasted because they have been created by element '''A'''. It is necessary to copy the element at '''A''' instead. If only the elements at B are needed, the best method will be to copy/paste as Text.

'''NOTE: ISAT will not copy elements containing road coordinates (elements with a path) to a scenario that does not share the same BLI as the source (copy from) scenario.'''

A partial solution to such cases is to remove the path first, copy the element, paste into the destination scenario, then re-create the path manually.

===External Reference===
An external reference scenario is intended to be re-used by multiple 'parent' scenarios. The effort of authoring objects is thus leverages across multiple files, without needing to re-create the same elements more than once.

[[File:re_use_xref_1.png|400px]]

Common uses of external references include traffic, traffic signal operation, traffic sign appearance or other environment features which have multiple appearances (billboards, some tile related scenery, etc).

NOTE: Multiple external references are possible; but because objects are categorized by group, it is not entirely necessary.

For example, one external reference file contains traffic, another contains signs. These two external reference scenarios could be combined into one file.

[[File:xref_overview2.png|400px]]

NOTE: Each group defined must be unique across all files: parent and external reference files.

In order to use an element in an external reference scenario, it is necessary to define and assign a group to all elements that you wish to control from the parent scenario.
At this time there is no visual hint in ISAT to indicate if a group has been assigned to an element or not - each element has to be confirmed independently.

However, a properly authored external reference element cannot be edited within the parent scenario (after you have done Add Ref. to use the external reference file).

An alternative is to insert groups using a text editor with macro capability, or to use a program or external script to make the necessary changes.

'''NOTE:''' If the external reference file is for object contained in the parent scenario (for example, an external reference file containing traffic signals with a group defined) it is still necessary for that group to be defined in the parent file.

With traffic signals, ISAT requires ONE explicit group reference, which will be contained in the HCSM TrafficLightManager block as shown below. If you require the use of traffic signals in an external reference, the recommended way to do this is through ISAT because then it manages the group assignment for you.

==== HCSM TrafficLightManager scenario block ====

HCSM TrafficLightManager
HCSM CLG
IntrsctnName "I1_40260_4620"
Duration 2.0000000E+01 3.0000000E+00 1.0000000E+00 2.0000000E+01 3.0000000E+00 1.0000000E+00
GroupName "TrafficSignals"
LightName "s_signal_r1_LTRN_40260_4620_270"
LightName "s_signal_r1_RTRN_40260_4620_270"
LightName "s_signal_r2_LTRN_40260_4620_270"
LightName "s_signal_r2_STRT_40260_4620_270"
LightName "s_signal_r3_STRT_40260_4620_270"
LightName "s_signal_r3_NORM_40260_4620_270"
Pattern "FLTY" "R" "R" "R" "R" "R" ""
Pattern "RTG" "R" "R" "R" "R" "R" ""
Pattern "LTR" "LTR" "LTR" "FLTY" "FLTY" "LTR" ""
Pattern "SR" "SR" "SR" "SG" "SY" "SR" ""
Pattern "SR" "SR" "SR" "SG" "SY" "SR" ""
Pattern "R" "R" "R" "G" "Y" "R" ""
&&&&End&&&&
&&&&End&&&&

'''NOTE:''' At this time there is a known issue using the write cell '''SCC_Audio_Trigger''' action in external references. Although the trigger containing this action can be assigned a group and used as an external reference, audio does not play.

<span style="color:#ac6600">'''Because ISAT updates static object positions (elevation) to the terrain (roadway) when the scenario file is saved, the best way to use a custom elevation is to put such objects into an external reference file in order to isolate those objects from normal scenario editing.''' </span>

====Define a Group====
<span style="color:#ac6600">'''NOTE:''' ISAT 1.8.5 and 1.8.6 currently do not work properly with group files. These versions will not import objects within a group file. There is a workaround which involves the following process, but instead of reading the saved group file into a scenario the workaround requires editing the scenario as text and inserting the objects within the group file into the scenario.</span>

RMB on the element and choose from the context menu: Group >> New Group (if this is a new group) or Group >> (choose an already defined group).

'''NOTE:''' The first time you create a group for an object, ISAT will automatically assign the group to that object.

After defining and assigning groups to the scenario elements needed, save the scenario file then close it.

Open or create the parent scenario file and use the Add Ref. button at the bottom of the ISAT window to select your external reference scenario. After you choose a file ISAT will present you with the groups found in that scenario. Choose the groups you with to include and click the 'Okay' button. Click the Add Ref. OK button to complete the process.

Currently import group file operations are not working, but it is possible to insert the group file content (all HCSM StaticObjects) into a scenario manually by using a text editor to copy text from the group file and paste that into a scenario file into the HCSM Static Object section of the scenario file.

[[File:group_text.jpg|400px]]

'''NOTE:''' ISAT does not enforce logic on your external reference authoring. If you add references to scenarios that do not share the same roadmap/BLI as the parent scenario, it is likely that elements will be placed at the origin (in cases where the external reference roadmap contains roadways not found in the parent) if it even loads.

===Exporting ISAT Elements as Groups===
Transferring ISAT elements among scenarios can be accomplished using groups. As with external reference scenarios, one or more groups must be defined and then assigned to one or more elements.

After defining and assigning groups select the group for export using the Group select drop-down located at the lower left corner of ISAT. Choose a group to export and then click the 'Save Group' button. Save the file.

TBC insert graphic sequence diagram here

'''NOTE:''' If you cannot locate the group file in the folder specified, check the ISAT install\data folder. This is typically:

C:\NADS\ISAT\data

===Group File Contents===
The group file is a text file and can be opened or edited in a text editor.

The following is a group file containing one ADO. Note the GroupName line near the bottom:

Header
LriFile "_dev.bli"
LongComment "this is a test group export"
ShortComment "this comment was left empty"
&&&&End&&&&
HCSM Ado
RunMode "eREMOTE_CONTROL"
RandomSol 0
Name "Ado1"
DynModel "Non Linear"
LogFile ""
LatOffsType 0
CreateRelLatInFeet 0
CreateRelOffsLonUsingExpr 0
CreateRelOffsLonExprStr ""
AutoControlBreakLights 0
AutoControlHeadLights 0
UseReaDel 1
StdToAccType 0
StdToDecType 0
StdToDecVal1 9.0000000E-001
StpToAccType 0
DecToAccType 0
FollowTimeMin 1.0000000E+000
FollowTimeMax 2.0000000E+000
EmergDecClip -1.1000000E+001
Accel2Catch 0
NormVel2Kp 7.0000000E-001
PathSearchDepth 2
LcvFall 1.5000000E+000 2.0000000E+000
LcvFreq 3.0000000E-002 5.0000000E-002
LcvRAmpl 1.0000000E-001 5.0000000E-001
VelCtrlInitMatchOvVel 0
VelCtrlFollowSpeedLimit 0
VelCtrlDistType 0
MaxLatOffset 9.0000000E+000
LongComment " "
ShortComment " "
SolName "Audi"
RoadPos "r1_1320_44220:2:32414.44:0.00"
GroupName "TEST_Group"
&&&&End&&&&
HCSM StaticObjManager
&&&&End&&&&
HCSM DriverMirror
&&&&End&&&&
HCSM IntersectionManager
&&&&End&&&&

===ISC Scripts===
Scripts are an efficient way to automate repetitive and/or complex tasks.

ISAT uses a custom language (ISC) to automate placement and manipulation of scenario objects. Combined with simple direction commands and the capability to navigate a road network, ISC scripts can ask the scenario author for input and prompt for selecting objects.

ISAT installs with some ISC script files. If your version of ISAT contains a data\isc
folder, then your version of ISAT is capable of running scripts. You can create
additional scripts as needed. All scripts located in the data\isc folder will load in ISAT
when ISAT is launched.

You can use these scripts for reference in creating your own custom scripts.

New scripts created during an existing ISAT session will not appear until ISAT is re-
launched.
Scripts that have been edited will not update until ISAT is re-launched.

Unless otherwise indicated, scripts are case-sensitive.

'''NOTE:''' Please do not edit the existing scripts!

Make a copy of any existing script before you make changes. In the event your modified script does not work, you can look at the original file for reference.

ISC scripts are located on the ISAT Elements widget. Custom isc scripts are located after the 'Events' separator.

Using an ISC script involves LMB + dragging the desired script onto the workspace. In some cases the script will ask for inputs.

ISC can be also used to create an entire event, thus ensuring that all events created will be entirely identical in terms of settings and locations for all created elements.

ISC scripts are text files located within the ISAT installation data folder. Only the custom ISC scripts are located in this folder. This is typically:

C:\Nads\Isat\data\isc

====Icon Files====
Script icon files are 8-bit windows icon files (file.ico). GIMP is capable of exporting valid ico files. To create an ico file, scale it to 32x32 pixels. Export the file as .ico to the isat\data\isc folder.

In order for a script to use an icon file, both files must exist in the isat\data\isc folder.

====ISC Script Examples====
This section contains example scripts with notes.

'''Rotate sign'''

.Name SetSignRotation
.Icon SignRot.ico
Static sign
Select(sign,"Please Select a Sign")
sign.SetAngle(Anchor)
.End

'''Place Multiple Static Objects (TrafCone)'''
The following script asks the scenario author for number of cones to generate, position and offset values and then generates the objects.

A breakdown of the script follows the code block below.

.Name Cones
.Icon cone.ico

Block coneBlock %%%
HCSM StaticObject
IsNewObj 1
Name "Cone_xxx"
SolName "TrafCone"
Option 0
Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
&&&&End&&&&
%%%
Static cone;

Value dist1
Value numberOfCones
Value distance
Value variablePart
Value randDistance
Value speed
Value Count
Value LatOffset

Block tempBlock
tempBlock = coneBlock
Count = 1
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

Ask(numberOfCones,"How many cones?" )
Ask(dist1,"Distance between cones?" )
Ask(LatOffset,"How much offset?" )

Position posRp
Position tempPos
posRp = Anchor
numberOfCones = numberOfCones

Repeat numberOfCones
posRp.GoForward(dist1)
# test comment
tempPos = posRp;
tempPos.SetOffset(LatOffset)
cone.RoadPos = tempPos
cone.Clone
Count = Count + 1
tempBlock = coneBlock
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

End
.End

====Script Breakdown cones.isc====

This section contains a description of the elements used in the script. The script segment is followed by a brief text description.

This script places a number of object copies (TrafCone) using information provided by a user.

.Name Cones
.Icon cone.ico

The first line contains a keyword '''.Name''' followed by the name of the script. This is the name that ISAT will use on the Isat Elements widget for the script. Note the script name does not have to be the same, but it is good computing practice.

The second line begins with the keyword '''.Icon''' followed by a file name. This file must exist in the ISAT\data\isc folder (accompanying the script file). This is the icon ISAT will use for the script.

Block coneBlock %%%
HCSM StaticObject
IsNewObj 1
Name "Cone_xxx"
SolName "TrafCone"
Option 0
Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
&&&&End&&&&
%%%

This is the data section of the script, which is defined using the keyword '''Block'''. A block name follows the keyword, and the data start is defined with '''%%%'''.

The HCSM StaticObject section has been copied from a scenario. In this case, a static object was placed into the workspace and then copied into a text file.

Name "Cone_xxx"
Note: the object name contains a marker that can be used to programmatically name instances of the object:

SolName "TrafCone"
This line begins with the keyword '''SolName''' followed by the name of the object as it is defined in the sol2.txt file.

Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
The Position of the static object will update when the script activates and instanced objects are placed in the workspace.

Static cone;
This line begins with the keyword '''Static''' followed by a variable name.

Value dist1
Value numberOfCones
Value distance
Value variablePart
Value randDistance
Value speed
Value Count
Value LatOffset

This section defines variables with the keyword '''Value''' followed by variable names. Using descriptive names is better than generic names. From the variable list it already seems clear what the programmer cares about: number of cones and distances.

Block tempBlock
tempBlock = coneBlock

This section defines a block using the keyword '''Block''' followed by the variable name.

The next statement replicates coneBlock into tempBlock.

Count = 1
Initialize the value of the variable Count to 1.

tempBlock.Replace('xxx',Count)
The built-in '''Replace''' function changes the string 'xxx' to the value of the variable Count.

cone.SetBlock(tempBlock)
This statement creates a block using the function '''SetBlock''' called cone, and copies the contents of tempBlock into it.

Ask(numberOfCones,"How many cones?" )
Ask(dist1,"Distance between cones?" )
Ask(LatOffset,"How much offset?" )

This section asks the user for input and puts that information into variables:
*Number of cones
*Distance between cones (dist1)
*Lateral offset (calculated from lane center)

Position posRp
Position tempPos
posRp = Anchor
numberOfCones = numberOfCones

This section contains position variables and assigns the value of numberOfCones.

Repeat numberOfCones
posRp.GoForward(dist1)
# test comment
tempPos = posRp;
tempPos.SetOffset(LatOffset)
cone.RoadPos = tempPos
cone.Clone
Count = Count + 1
tempBlock = coneBlock
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

This section is where the work happens. Reading from the top, this section is contained within a loop defined by the keyword '''Repeat'''. The number of times to repeat follows in a variable numberOfCones.

'''posRP.GoForward()''' is a built-in function to take the current position and shifts it forward by the amount specified in the dist1 variable.

#test comment
This is a comment defined by starting the line with the comment keyword '''#'''

tempPos = posRp;

Assign the value of the variable tempPos to the value currently in '''posRp'''

tempPos.SetOffset(LatOffset)

Another built-in function or attribute to the position element which defines a lateral offset (distance from the lane center). This statement places the value of a variable LatOffset into the offset element of the tempPos variable, using the operand '''SetOffset'''.

cone.RoadPos = tempPos

This statement sets the road position variable for cone to the value in the variable tempPos.

cone.Clone

Duplicate the block cone using the operand '''Clone'''

Count = Count + 1
Set the value of the variable Count to the value of Count plus one. This statement increments the value of Count for each loop processed.

tempBlock = coneBlock

Create a new block tempBlock by setting it to the content of coneBlock.

tempBlock.Replace('xxx',Count)

Use a built-in function to '''Replace''' the string 'xxx' with the value of the Count variable

cone.SetBlock(tempBlock)

Use the built-in function '''SetBlock''' to place the modified tempBlock (modified by the string replacement command earlier) into the cone block.

End
.End

The last two lines terminate the loop and the script, respectively.

====How to Create an ISC Script====
The simplest way to create an ISC script is to find an existing script that does something similar to your desired behavior and edit it.

=miniSim Simulation Data=
MiniSim runs on shared memory:
*miniSim is a collection of programs
*shared memory is a commonly accessed 'blackboard' list: a Cell and a Cell Value
:The DAQ file is a snapshot of this 'blackboard' memory for every frame.

*Scenario can write to cells added by the scenario author
:-i.e., for custom hardware or tasks/events

'''NOTE:''' Custom cells must be present in the collect file (NadsMiniSimCollect.cec) '''prior to''' simulation in order for the custom cells to be present in the DAQ.

NOTE: The cell type defined in the collect file must be followed, or garbage values will be used

Use of a DAQ file implies that at some point, data reduction will be needed.
Data reduction: the process of distilling measures from the DAQ file, i.e.
*Event definition
*SDLP
*Average headway

==What is the Difference? Cell vs. Variable==
*A Cell is a pre-created “slot” in shared memory
:-Specified in the .CEC collect file,
:-Saved in the DAQ file,
:-Can be sent to custom programs;
:-Can create & use custom cells;
*A Variable is a name value internal to the scenario
:-NOT saved to the DAQ file,
:-Can use to track items in the scenario
:i.e., how long the driver has been exceeding the speed limit
:-Initialize conditions in the scenario.

=== Variables Save ===
Variables can be saved to disk as a single value text file (ie, multiple values over time are not supported) through the use of a '''Store Variable''' action:

[[File:2021-08-23_13h28_49.png|400px]]

The file is stored in the miniSim_x.x\bin.x64 folder.

'''NOTE:''' The name of the file is defined within the Store Variable action. '''Care must be taken to save variables to unique file names''' in the case of multiple scenarios running on miniSim at the same time (if they share common variables), as would be the case if triggers are copied from one scenario to another.

=== Variables Restore/Read ===
Variables can be read into the simulation through the use of a '''Load Variable''' action:

[[File:2021-08-23_13h32_39.png|400px]]

==Cell Types==
This is a partial list of cell types.

*CFS = control feel subsystem (steering wheel, pedals)
*CIS = control information subsystem (gear, turn signal, buttons, etc)
*TPR = terrain profiler for terrain queries
*VDS = vehicle dynamics for accelerations, position, engine speed, speed, etc.
*ACC = adaptive cruise control
*RCM = configuration management for setting variables that affect subsystem configuration (ACC enabled or disabled, for instance)
*SCC = scenario
*SOP = for one time initializations at the start of the simulation.

=='''Data Output Actions'''==

*Write to Cell Actions
:-Write the value of a variable or cell to a cell
:-Write to a custom cell
:-Cannot overwrite another systems output
'''NOTE:''' Although it is possible to write to a different system cell, that value will be over-written on the next frame. Thus it is effectively not feasible nor desirable to do.

'''<span style="color:red">Also Note: the limit for maximum number of write to cell actions that can be performed in one frame is 8.</span>'''

*Set Variable Action
:-Sets the value of a variable
:-Does not have to be created first
:-Not saved in the DAQ unless written to a valid cell
*Logstream
:-Log data action

===Data Output Methods===
Your data is the primary reason for simulation.

1. Default miniSim scenario measures
:- Immediately available

2. Alternate scenario measures (DAQ file)
:- Processed through data reduction

====Default miniSim Scenario Measures====
*Saved to a drive report.txt file
*Saved to the same Location as DAQ files;
:Scenarioname_timedatestamp_report.txt
•Measures calculated overall, and up to 20 Events during drive:
:Collision Count Lane Departure Count
:Maximum Speed Lane Departure Percentage
:Minimum Speed Speeding Count
:Average Speed Speeding Percentage
:Standard Deviation of Speed Average Headway
:Standard Deviation of Lane Position

====Default miniSim Scenario Measures Require Scenario Event Definition====
In order to capture meaningful data into the default miniSim measures, a scenario must be configured properly to define events.

Use the Write to Cell action to activate the default measures.

[[File:2021-07-02_11h02_44.png|400px]]

*At the start of scenario, set:
::SCC_EventStatus =0
::SCC_EventNumber = 0
*At the start of the first event, set:
::SCC_EventStatus = 1
::SCC_EventNumber = 1
*At the end of the first event, set:
::SCC_EventStatus = 0
*At the start of the second event, set:
::SCC_EventStatus = 1
::SCC_EventNumber = 2
*At the end of the second event, set:
::SCC_EventStatus = 0

Continue this pattern; at end of final event, set:
::SCC_EventStatus = 0

====Default miniSim Scenario Measures Sample Report====
The following is an example report for 4 events. Note the remaining events present in the report are all zeroes or -1.00.

[[File:default_measures_report.png|400px]]

===="Alternate" Scenario Event Definition aka Using Logtreams====
'''NOTE: This method is the more typical/standard method for defining events.'''

Defining an event is key to partitioning simulator data into useful sections. Processing these sections is the essence of '''data reduction.'''

These useful sections are partitioned using logstreams and are generally called '''Events''':
*A logstream is a data marker present in the DAQ file
:there are 10 logstreams
:use logstreams to indicate when things happen '''in the data:'''
:at the start of an event; i.e.,
::grab all data where logstream 1 = 100 (example value)
:during a sub-section of an event
:at the end of an event (typically clears to 0)

Logstreams help separate/filter data;
*SDLP is not useful during emergency maneuver events

Logstreams can be useful to debug events;
:marking in the data when triggers fire
:ensuring event counters work; these are typically sequential, so any logstream deviation identifies a problem

*How to define a Scenario Event:

Set logstream values at scenario event start
:during and at scenario event end, set or clear logstream values:
For example:
::logstream 1 for event ID
::logstream 2 for sequencing the event (during/within event)
::logstream 3 for restart number, etc.

*Requires data reduction to fully process drive data
*Does '''not''' support default measures
:unless those measures are used in parallel with the logstream method

*The use of logstreams allows a scenario author to encode event and environment information into the scenario and as a result, into the simulator data stream.

====Example Alternate Scenario Event====
This section contains an example of a scenario that uses logstream 1 to define an event and environmental context.

In the following example, logstream 1 (LS1) is used to:
#define the scenario start, which is also in this example the event start. NOTE: This is not typical.
#when the driver is 805f from the intersection halt line, set a value into LS1
#when the driver is 500f from the intersection halt line, set a '''new value''' into LS1 NOTE: This could also use a different LS than the one used to define your event, i.e., 1
#when the driver activates a roadpad trigger to reset a force velocity (FV) on a lead vehicle

[[File:event_def_LS.png|400px]]

In the following event definition, an expression trigger is used to set a logstream value and execute two additional actions pertaining to the event.

[[File:event_ET_LS3.png|400px]]

====How to Export Data from A DAQ file using ISAT====
ISAT can display and export DAQ data. NOTE: This is 'raw data', not previously processed. This method can be used to test scenarios, confirm or identify data issues.

TBC: example export here

=Terminology & Documentation=
This section contains terminology and references to related documentation.

'''Action''' - the basic scenario element; the basis for creating scenarios. Actions may be executed on scenario elements (dynamic or static), create or remove elements, or the environment (time of day, visibility) or the simulated cab instrument panel.

'''ADO''' - Autonomous Dynamic Object; self-controlling to a degree.

'''Cell''' - Data elements that are recorded to during a drive; some cells may be used by the scenario author. Custom cells may be added to miniSim.

'''Event''' - anything significant that happens during a drive where the driver condition or response is desired to be identified in the drive data. Can be isolated from general driving through default measures or logstreams.

'''ISAT''' - Interactive Scenario Authoring Toolkit; used to create scenario files for use on the NADS facility or miniSim simulators.

'''ISC''' - ISAT script file.

'''Scenario''' - The simulation experience during a drive; also known as a scenario file, which contains all instructions to the elements within a simulator drive.

'''SDLP''' - Standard deviation lane position

'''SOL''' - Scenario Object Library; objects that are available to ISAT during scenario authoring must be present within the sol2.txt or an auxiliary sol2 (sol2_aux.xxx.txt) file.

'''Trigger''' - A scenario element that contains actions to execute during simulation. All triggers share the same actions, but execution depends on the trigger type.

'''TTA''' - Time to arrival.

'''TTC''' - Time to collision.

=Reporting ISAT & Scenario Issues=
*How to report ISAT & scenario issues:

When reporting issues with scenarios it is helpful to provide as much information as possible.

This often includes scenarios (including any external reference files) and the .LRI file used by the scenarios, screenshots or video that demonstrate the issue being reported and relevant DAQ files. It can be very helpful to include coordinate information with the screenshot or video.

The .BLI file is created from the .LRI and is much larger than the LRI so it may be more convenient to send the LRI file. NADS staff can re-create the BLI file from the LRI.

Some graphics anomalies may be issues with the tile model and not a scenario or miniSim problem. These include:
#white block shapes in the environment
#gaps or missing geometry; i.e., holes
#improper lighting (dark features present during the day)

If these issues happen on a custom roadmap/database world, please include the TMT .mos file as well so NADS can re-construct your environment.

==How to contact the NADS miniSim team:==

email [mailto:miniSim-Support@uiowa.edu minisim support]

[mailto:andrew-veit@uiowa.edu Andrew Veit]
Director of NADS miniSim

[mailto:joseph-meidlinger@uiowa.edu Joseph Meidlinger]
Program Coordinator NADS miniSim

[mailto:oscar-hernandezmurcia@uiowa.edu Oscar Hernandez Murcia]
MiniSim Application Programmer/Analyst

[mailto:chris-schwarz@uiowa.edu Chris Schwarz]
Data Reduction & Vehicle Dynamics

[mailto:shawn-allen@uiowa.edu Shawn Allen]
TMT, Modelling & Support

==How to check what BLI file is used by a scenario==

#You can edit the scenario in a text editor; near the top of the file will be a line starting with '''LriFile''' followed by the name of the BLI file in double quotes.
#You can use '''grep''' to inventory single or multiple scenarios:
:grep bli <scenario file/s>
:A partial listing is shown in the example below. NOTE: The files shown will likely be different on your PC:
C:\NADS\Isat\data\training.demo_scn>grep bli *.scn
Demo_Expression_Lead_Vehicle_Variables.scn: LriFile "simple_rural.bli"
Demo_Expression_Trigger_to_Lead_Vehicle.scn: LriFile "simple_rural.bli"
Demo_HUDD.scn: LriFile "simple_rural.bli"
ISAT-Samples-Avoid.scn: LriFile "esc_dry_05.bli"
ISAT-Samples-Right-Incursion.scn: LriFile "esc_dry_05.bli"
ISAT-Samples-TrafficLightTest.scn: LriFile "simple_city1.bli"
ISAT-Samples-TrafficLightTestB.scn: LriFile "simple_city1.bli"
ISAT-Samples-YellowLightDilemmaB.scn: LriFile "simple_city1.bli"
KBW_TEST.scn: LriFile "simple_rural.bli"
KBW_TESTB.scn: LriFile "simple_rural.bli"
demo.createADO_and_trigger.scn: LriFile "simple_city1.bli"
demo.creation_radius1.scn: LriFile "simple_city2.bli"
demo_FV_sum_of_Sines.scn: LriFile "simple_city2.bli"
demo_LV_Decelerate.scn: LriFile "simple_city2.bli"
demo_LV_cut_in.scn: LriFile "esc_dry_05.bli"
demo_MG.scn: LriFile "simple_city2.bli"
demo_TM1.scn: LriFile "simple_city2.bli"
demo_TT_null.scn: LriFile "simple_city2.bli"
demo_actions_text.scn: LriFile "simple_city2.bli"
demo_alt_data_measures.scn: LriFile "simple_city2.bli"
demo_audio_virtual_object.scn: LriFile "esc_dry_05.bli"
demo_audio_virtual_object_simple_rural.scn: LriFile "simple_rural.bli"
demo_auto_cloud1.scn: LriFile "simple_city2.bli"
demo_coneISC1.scn: LriFile "simple_city2.bli"
demo_dddo.scn: LriFile "simple_city1.bli"
demo_dddo_B.scn: LriFile "simple_city1.bli"
demo_forXRef_traffic.scn: LriFile "simple_city1.bli"
demo_force_vel_01.scn: LriFile "simple_city1.bli"
demo_groupImport.scn: LriFile "simple_city2.bli"

==How to configure miniSim for screenshots to include coordinates==
You can enable coordinate display on miniSim by changing the focus to the main display. #Move the cursor until it is positioned in the main display area, then LMB. When successful the main display will appear to "blink".

Press the keyboard n key twice. This will cause coordinate information to display in the lower left corner of the main display.

[[File:miniSim_show_coords.png|400px]]

The n key is a toggle; to disable coordinates, press it twice (2x) again. '''NOTE:''' the cursor focus must be in the main display in order for this to work.

=Additional Resources=
[[:File:ISAT_Quick_Start.pdf|ISAT Quick Start Guide]]

[[ISAT_Demonstration_Scenarios|Demonstration Scenarios]]

[[:File:Create_Use_Custom_Cells.pdf|Create and Use Custom Cells on MiniSim]]

[[:File:Function_ReadCell_20180824.pdf|ReadCell function]]

[[:File:TrafficManager_Ch12.NADS.Internal_ISAT_UsersGuide.pdf|Traffic Manager]]

=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 [[ISAT_Reference_Manual_Table_of_Contents#ISAT_Reference_Manual|reference manual for ISAT can be found here.]]

ISAT User Guide Table of Contents

2023-08-29T20:36:04Z

Shawn Allen: /* Triggers formatting*/

== 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
*CTL-<some other key> Press and hold the Ctrl and then press <some other key>. Most typically used for copy (CTRL-C) or paste (CTRL-V).
*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 and modify for use in your own scenarios as needed.

== <span style="color:#FF0000"> '''Known Issues'''</span>==

Added 2022.07.01 '''Relative Creation''' does not currently work for ADOs on miniSim.

'''Expression clarification'''

Increment and decrement operators (++, --) are not considered expressions by behaviors. They should not be flagged as expressions when used in the Value field of a Set Variable action.

Added 2019.11.07 '''File reset issue'''

ISAT has a long-standing bug which can reset your static object options when your scenario file is saved to disk.

'''It is strongly recommended that you use external reference scenario files to avoid this. '''ISAT does not reset static object options in the xref file.

Added 2021.12.29 Expression Triggers and Values

'''Using Values in Expression Triggers'''

To ensure proper execution of expression triggers, it is recommended that the values used include the desired range by decreasing the lower threshold or increasing the upper threshold '''instead of using the exact value.'''

For example, to process values in a range (7031 - 7040):

[[File:2021-12-29_12h38_09.png|400px]]

'''Note: remember that negative values must be calculated since the expression parser does not parse negative values otherwise.'''

For example, to properly parse a specific transmission gear (Park):
'''ReadCell('CFS_Auto_Transmission_Mode', 1) = ( 0 - 2 )'''

=='''ISAT Overview & Interface Basics'''==
This section contains information about ISAT and the ISAT interface.

===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 <span style="color:#FF0000">'''not an object editor'''</span> 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.
[[File:miniSim_scenario_compnents.png|center|640px]]

*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.

[[File:anatomy_of_a_scenario.png|center|400px]]

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

[[File:scenario_as_text.png|center|640px]]

This diagram shows the same scenario in (left to right) 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, <u>always</u> check your edits in ISAT!'''
*Copy/Paste - delete paths from elements when the BLI is different between your source & destination BLI files. The following scenario elements contain paths:
::ADO (with a path specified)
:: Any roadpad trigger (roadpad, Time to Arrival, Follow)

'''NOTE: A Traffic Source is not a portable element but it can be re-created in ISAT or integrated into a new scenario by copying the element from the source scenario then using a text editor to paste it into the destination scenario'''

'''How can I find information in multiple files easily?'''

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.

What if you don't know what to look for? How do 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
[[File:action_overview.png|400px||border|caption]]

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)

==='''Adding an action to a trigger'''===

The following example uses a Time Trigger; remember that '''all triggers share the same actions'''.

To add an action to a trigger you can double-click on the trigger, navigate to the '''Actions''' panel, and click on New to create a new action.

[[File:2022-11-30_12h47_23.png|400px]]

The possible actions are listed under the '''Action Type''' drop-down menu.

[[File:2022-11-30_12h47_44.png|400px]]

Actions are arranged in a 'stack' and are processed from top to bottom. If you use multiple actions you should enable the '''sequential flag''' to ensure each action is executed in sequence. Without the sequential flag, actions will be processed as fast as the simulator behaviors can execute.

[[File:2022-11-30_12h52_58.png|400px]]

Actions may be re-ordered in the stack using the '''arrows''' located near the action stack list.

=='''ISAT Modes of Operation'''==
[[File:ISAT_modes_of_operation.png|400px]]

*Edit
*Rehearsal
*DAQ playback
*Monitor '''Currently not available'''

==='''Edit & Rehearsal Modes'''===

*Edit - this is where scenario authors will spend the most time.
::Creation or modification of scenario
::Link to or import portions of other scenario elements

[[File:mode_edit.png|400px]]

*Rehearsal
::Debug & test scenario
::Simulates scenario using Behaviors and Vehicle Dynamics
::Displays error messages from behaviors

[[File:mode_rehearsal.png|400px]]

'''NOTE:''' Rehearsal mode <span style="color:#FF0000">simulates </span>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

[[File:mode_playback.png|400px]]

==='''miniSim Scenario Components'''===

The following diagram shows an overview of scenario related components of the NADS miniSim and how these components work together.

[[File:miniSim_scenario_components_wDAQ.png|400px]]

=='''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.

[[File:isat_workspace_general.png|400px]]

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)
[[File:isat_status_bar_overview.png|400px]]

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.

[[File:isat_user_prefs_status_bar_settings.png|400px]]

====ISAT Iconography====
ISAT provides graphic hints for triggers placed in scenario that can be useful when editing or maintaining scenarios.

The general format is a border enclosing miniature icons of the trigger and first action contained in that trigger. Additional information representing one or many actions is also shown.

[[File:hints1.png|400px]]

ISAT will list all trigger actions when a trigger is selected, but these hints provide a way to quickly identify what actions have been authored.

[[File:hint2.png|400px]]

*A Roadpad trigger, one action: '''Traffic Light Action'''
*B Roadpad trigger, multiple actions, first action is '''Remove Element'''
*C Roadpad trigger, multiple actions, first action is '''Set Dial'''
*D Roadpad trigger, constrained to road (lane), no actions - this is an empty trigger
*E Roadpad trigger, multiple actions, first action is '''Log Data'''
*F Global Time Trigger, single action: '''Set Dial'''

[[File:handle.png|400px]]

The element handle is the red dot visible in most of the triggers.
The handle can be dragged into position, and the trigger will follow the handle

Drag the trigger off the handle to offset it's location from the handle

==='''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.

[[File:object_types_isat.png|400px]]

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
::*Traffic Source

:'''NOTE:''' Virtual objects are defined in the scenario, not in the SOL2.
[[File:object_types_world.png|400px]]

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.
::NOTE: 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.

==='''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:
#Follow a path using kinematics
#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:
#coupled
#relative trajectory
#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'''===
Traffic signals are objects with special operation and function; they are coupled to intersections and routes of travel through intersections to control traffic flow similiar to their function in the real world. Traffic signals are part of the source tile model and may not be re-positioned or physically altered by scenario except for their visual signal state appearance; i.e., red, green or yellow signals.

To control intersection traffic signals use Edit >> Traffic Light ManagerTraffic signals use a Signal State Table (SST) to control which signal states are active and when. Each intersection with traffic signals will have an associated SST.

[[File:traffic_light_state_manager.png|400px]]

The above diagram shows an intersection in the workspace to the right, and the traffic signal state table for that intersection on the left. At this point additional states (for signal condition) can be added by clicking the '''Add state button'''.

[[File:traffic_signal_state_table2.png|400px]]

The above diagram shows two states defined for the intersection, represented by the two columns of state condition.

Continue adding states until the desired signal cycle has been defined. Generally this consists of red, green or yellow states.

NOTE: There is currently no way to automatically author a series of traffic light signals

To author traffic signal lights in sequence or on a route, the scenario author has to manage the signal states

[[File:traffic_signal_state_duration.png|400px]]

To edit the signal state duration RMB on the duration field header and choosing '''Edit state duration''' on the context menu. Enter the desired value then click OK.

====Traffic Signal Types====
The ISAT status bar reports Traffic Signal Type name. There are two signal types:
#Standard signal - IDs may have no identifying information
:Valid signal states: Red, Yellow, Green, Flashing Red, Flashing Yellow, OFF
#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

[[File:traffic_light_extended_type_name_normal.png|400px]]
: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.

[[File:traffic_light_extended_type_name.png|400px]]

===Changing Signal States in Scenario===
Traffic signals are controlled in scenario by using a Traffic Signal Action to change the SST.

'''NOTE:''' The Traffic Signal Action works by changing the SST, '''not by changing the traffic signal.''' This is a subtle but important difference.

Setting a signal to an undefined state effectively does nothing to the traffic signal.

[[File:traffic_light_state_table.png|400px]]

The above diagram shows a fully populated SST, with one signal row highlighted in red, and one state column highlighted in green. The associated intersection corridor is highlighted, showing the signal controls a dedicated left turn.

During simulation, the initial signal state is defined by the left column. As the simulation proceeds, the signal state changes according to the duration states defined across the state table, proceeding left to right and then wrapping around to the beginning after the last defined state. Each traffic signal appearance changes according to the configuration of the SST.

As a driver approaches this intersection, assume the signal state is in the column left of the highlighted column ('''R'''ed), and the desired action is to change the signal to green.

The action used to change a traffic signal state is the '''Traffic Light Action'''.
Using a traffic light action requires the specification of a signal state, the traffic signal to affect, and a duration.

[[File:traffic_signal_action1.png|400px]]

In the above diagram the scenario author has specified the desired state as '''Green''' as shown in the action dialog.

However, referring back to the previous state table diagram, there is no such state present in the SST. That means this particular action will fail, and the traffic signal will not change as the driver approaches the intersection - because the action does not create a new signal state, it works by advancing the state table condition (column) to the specified condition. If the condition is not present in the SST then nothing will appear to happen.

In this example, the action should be edited to use the correct signal state '''Left Turn Green''', which is present in the SST.

'''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

[[File:known_issue_traffic_light_action.png|400px]]

'''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.

[[File:known_issue_traffic_light_action_workaround.png|400px]]

====Change A Traffic Light Using Scenario Action====
To change a traffic signal, use the Set Dial >> Traffic Light action.
'''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

[[File:traffic_light_state_table.png|400px]]

This diagram shows a fully populated traffic signal state change for an intersection.

*Static object traffic lights
:These are objects, not true traffic signals and so they are not controlled with the Traffic Light manager.

==='''Traffic Source'''===
A traffic source is a coordinator used to create traffic at specific locations in the road map (unlike the Traffic Manager). This is useful for creating ambient traffic. Traffic Sources creates ADOs or DDOs at random or user-specified intervals.

Elements created using a Traffic Source will be created at the locations specified by the user. If traffic is specified at multiple locations the actual location for each creation will be determined randomly during simulation.

'''Note:''' Using the Relative Creation flag on ADOs created by the traffic source will not create traffic at the specified location on the map, but use the information in the Relative Creation fields to populate traffic in the scene during simulation.

This method allows for more flexibility but care must be taken not to create so many ADOs that miniSim is unable to make frame rate. Too many ADOs will cause the scene to jump and 'jitter' and it will feel slower than normal.

==='''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 ISAT scenario rehearsal

===Custom (icon) file virtual objects===

[[File:virtual_object_custom_icon_file.png|400px]]

'''Note:''' Some versions of MiniSim_2.3 do not support custom virtual objects. For those installs, if you require this type of functionality, a workaround exists in the form of a 2D model that can be customized (i.e, sprite).

Virtual objects may be customized using graphics files (texture images) to display any desired custom element. This typically requires the use of a bitmap graphic. Various file formats are supported: JPG, BMP, PNG. It is possible some types of these formats may not work - in those cases, try an alternate format.

If image transparency is required and the custom icon does not display during simulation, please email dsri-minisim@uiowa.edu with a description of the issue, your scenario and custom virtual object image file.

Custom icon files must be located within the Nads MiniSim path for resources - at NadsMiniSim_x.x\data\visuals\Models\ModelTx.

===Standard virtual object shapes===
The virtual object shapes include:
# Circle
# Triangle
# Octagon
# Star
# Diamond
# Icon <- this is for custom virtual object graphics
# Rectangle
# Hexagon

The virtual object fill and border color and transparency can be set in the virtual object properties dialog panel.

[[File:virtual_object_std_shape.png|400px]]

====Virtual Object Workaround====

There is a scenario authoring method that can be used to emulate virtual object functionality through the use of a DDO that is coupled to any dynamic scene element, including the External Driver. One model has been created to support this method called "sprite".

'''Note:''' The sprite model is a 2D object present in the scene, and can therefore be occluded by other scene elements during simulation.

[[File:trafsign_sprite.jpg|400px]]

The sprite model is designed as a flat plane that continuously faces the viewer. It contains different sized planes and can be customized through textures.

When authoring your scenario, configure the sprite object to Off unless it should be visible at scenario start. During the scenario you can control the sprite appearance with a setSwitch action.

[[File:sprite_setSwitch_action_021121.png|400px]]

The who to effect should use the name of the DDO placed in your scenario. The switch name will be s_sprite as shown above. Any valid option can be used. An invalid option (greater than 30) will disable the sprite the same as selecting the OFF option.

==='''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'''===
<span style="color:#FF0000">'''All trigger types share the same Action types'''</span>
*IF Then conditional
*Predicate: i.e., the activating agent
:If predicate is TRUE, then do Action(s)
*Road related triggers are categorized by predicate type
:Named element
:Road (lane)
:Nth vehicle on path only

'''What trigger is appropriate?'''
To determine which trigger is most appropriate, consider the task you are trying to accomplish. '''The differences between triggers is their activation methods.'''

'''Global Time Trigger'''
[[File:isat_time_trigger.png|150px]]

Use this trigger when something has to happen at some point in time.

Time triggers are also useful as "placeholder triggers"; used to apply persistent actions to multiple elements with unique settings for each element. Normally a persistent action is the last action possible in a trigger since the persistent action fires continuously. Putting persistent actions into a time trigger allows the scenario author to continue an action stack in the parent trigger if necessary.

Time triggers can be used as a 'stopwatch' - elapsed time, such as ending a drive after 3 minutes by setting the trigger to fire using an Activation Delay of 180s (GTT >> General).

Often used as a placeholder for actions such as initializing variables, displaying text messages to the screen using Set Visual Display Text actions, etc.

'''Note''': A time trigger can have global elapsed time and activation delay of 0, which causes the action stack in the time trigger to activate when that trigger is created.

'''Roadpad Trigger'''
[[File:isat_roadpad_trigger.png|150px]]

Use this trigger when something has to happen at some location in the drive that does not require event timing to be comparable for all participant drivers. For cases where event timing must be comparable among all participant drivers use the Time to Arrival trigger (TTA) instead of a roadpad trigger.

'''Time to Arrival Trigger'''
[[File:isat_time_to_arrival_trigger.png|150px]]

Use this trigger when something has to happen relative to some point in the drive, and also ensure all study drivers experience the same event timing irrespective of driver style (conservative, slow vs. aggressive, fast). Time to arrival (TTA) trigger uses a time calculation from the trigger pad activation to a target location specified in the trigger.

'''Traffic Light Trigger'''
[[File:isat_traffic_light_trigger.png|150px]]

This trigger activates actions when the specified traffic signal state is reached. For example, if the desired action is to create a DDO pedestrian to step into traffic when the traffic signal is yellow, then the Traffic Signal Manager must be used to author the appropriate signal states for the traffic signal.

Typically some other trigger is used to control the traffic signal (ie, to change the signal to Yellow on approach). It is therefore perfectly valid to put the actions within this other trigger rather than relying on the traffic light trigger.

'''Note''': Once a traffic light action has been authored, ISAT may be prone to crashing when accessing that trigger. This problem can be avoided by creating a time trigger and isolating the traffic light action there, allowing the parent trigger to be modified without crashing. Adjustments can be made to the traffic light action time trigger in a text editor, or recreated if it becomes necessary to make adjustments and ISAT continues to crash when trying to make edits.

'''Note:''' The traffic light action does not change the traffic signal state, and it requires a valid state sequence to exist in the signal timing table (Edit >> Traffic Light Manager). The traffic light action '''will not create a signal state''' that does not already exist in the signal timing table.

'''Expression Trigger'''
[[File:isat_expression_trigger.png|150px]]

Use this trigger when something must be monitored, evaluated or calculated such as checking a variable or cell value, velocity of the driver or the state of simulator hardware (steering wheel angle, brake or accelerator pedal position) or distance from the driver to some other object in the scenario.

Multiple expressions can be used within the same expression trigger. In those cases, all expressions must evaluate to True in order for the action stack to execute unless using an '''OR''' operator.

Use the '''OR''' operator - the pipe character "|" if you want to activate the action stack if '''any''' of the expressions evaluates to True.

In the following example, the trigger checks for TrialNumber = 1 and FirstButtonPress variables, and then checks if Aux Button 1 or 0 was pressed:

'''ReadVar('TrialNumber') = 1.0 & ReadVar('FirstButtonPress') = 1.0 & (ReadCell('Auxiliary_Buttons', 0) > 0 | ReadCell('Auxiliary_Buttons',1) > 0)'''

'''Note''': Expressions can also be embedded into some other triggers, most notably the Set Dial >> ADO >> Forced Velocity action often used in Roadpad triggers.

'''Follow Trigger'''
[[File:isat_follow_trigger.png|150px]]

Use this trigger when something has to happen based on one ADO position relative to another scenario element (including the XD). The follow trigger requires a leader and a follower to be specified; when this condition is met, the trigger action stack activates.

'''Note''': Both leader and follower must be positioned on the follow trigger roadpad to satisfy the follow parameters.

'''Geometric Position'''
[[File:isat_geometric_position_trigger.png|150px]]

This trigger is most useful to perform actions for off-road actors such as walkers. The trigger predicate is limited to Name or Type and requires a geometric position to be defined.

A more limited version of the geometric position trigger can be implemented with a Global Time Trigger that contains a Creation Radius. Placing the creation radius defines the area where the trigger may be activate.

===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

[[File:Screenshot (208).png|800px]]

'''Note:''' The highlighted lane shows which lane is the '''activating lane'''. Other lane/s will not activate the trigger action stack.

===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

[[File:TTA.png|400px]]

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===

[[File:other_triggers.png|400px]]

*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===

Execute actions if input expression evaluates to TRUE; the expression is specified on the trigger Predicate tab.

====Syntax====
Expression triggers support a simple language syntax with operators and functions.
The syntax is infix notation; i.e. a + b, not a b +.

Note: It is not generally possible to embed one function call inside another:
cos(sin(x)) is therefore an invalid expression. ISAT will report invalid expressions during rehearsal of a scenario. Invalid expressions are not supported and will not operate as written during simulation.

'''Exception:''' Currently it is possible to use the square root function with GetObjDistPow2 as in the following example:

sqrt(GetObjDistPow2('Target_Object_Name'))

Multiple expressions may be combined using the logical AND (&) or OR ("|" pipe character).

Exp1 '''&''' Exp2, Exp1 '''&''' Exp2 '''&''' Exp ''N''

All expressions must be true for the trigger to evaluate to TRUE and execute the action stack.

Exp1 '''|''' Exp2
One of the expressions must be true for the trigger to execute the action stack.

Negative values are not directly supported by the expression parser. To use a negative value, it must be a calculated value such as the following:

'''ReadCell('CFS_Steering_Wheel_Angle',0)<(0-5.0)'''

==== Operators ====
Operators are used to create expressions.

'''String'''
:Used within quotes as a string literal; i.e., 'some string'

Grouping
:Parentheses group elements together; i.e.,
:'''()'''; (a), (a + b)

Multiplication
:'''*'''; a * b

Division
:'''/'''; a / b

Addition
:'''+'''; a + b

Subtraction
:'''-'''; a - b

Note: negative values must be expressed with a subtraction operation:
(0 - 5), not -5 (invalid)

Greater than
:'''>'''; a > b

Less than
:'''<'''; a < b

Logical And
:'''&'''; a & b

Both a and b, otherwise returns 0 (FALSE)

Logical Or
:'''|'''; a | b

a or b returns 1 (TRUE)

====Expression Functions ====
Functions are used with operators to create expressions.

Function: '''sin'''
:sin -sine

Syntax
:sin(float x)

Description
:The sin() function returns the sine of x, where x is given in radians.

Return Value
:The sin() function returns a value between -1 and 1.

Function: '''cos'''
:cos –cosine

Syntax
:cos(float x)

Description
:The cos() function returns the cosine of x, where x is given in radians.

Return Value
:The cos() function returns a value between -1 and 1.

Function: '''ReadCell'''
:ReadCell()

Read a Cell value.

Syntax
:ReadCell(string Name, int Cell Array index)

Description
:ReadCell returns the value of a given cell (a cell is the current instance of a variable that will be maybe written to a daq file).

Index specifies a 0 based index into the array. Since most cells are single element arrays, a value 0 indicates the first element.

Cells valid for the ReadCell function are defined within the cell collect file NadsMiniSim.cec located in the miniSim_x.x\data folder.
The ReadCell function operates on shared memory during simulation, it does not read cell data from the DAQ file.

Cells that are defined may be written to the DAQ; the collect file specifies which cells are saved into the DAQ and what frequency to use for the write operation.
The NadsMiniSimCollect.general.txt file is located in the miniSim_x.x\data folder.

Available Cells:
Any cell that has been defined in the .cec file. For example:

:'''LogStreams''': Array of 5 floats. Logstreams are a set of values the scenario author can write to through “write to logstream” actions.
:'''AccelPedalPos''': Single Value. The current position of the accelerator pedal
:'''BrakePedalForce''': Single Value. The current force on the brake pedal in pounds
:'''SteeringWheelAngle''': Single Value. The current rotation of the steering wheel
:'''CruiseControl''': Single Value. The current cruise control position. (values are cab/platform specific)
:'''TurnSignal''': Single Value. The current position of the turn signal (values are cab/platform specific)
:'''OvVel''': Single Value. The participant’s current speed in miles per hour
:'''OvLaneDev''': Single Value. The participant’s lane deviation in feet.
:'''OvHeadwayToLeadVeh''': Single Value. The distance in feet to the first vehicle in front of the participant. -1 if no vehicle can be found.
:'''OvTtcToLeadVeh''': Single Value. The time to collision to the first vehicle ahead of the participant.
:'''Horn''': Single Value. The state of the horn (values are cab/platform specific)
:'''DynObj_Vel''': Array of 20 floats. The speed of a given dynamic object. Dynamic Objects are sorted in terms of distance to driver.
:'''OvVelLocal''': Single Value. The participant’s current speed in miles per hour, using the value local to scenario control

For a complete list of cells and array elements please see the miniSim data dictionary spreadsheet.

Return Value
:Returns the value of the specified cell.

Example
ReadCell(‘LogStreams’,5) > 3

Function: '''CellEquals'''
:Cell Equals, array element, value to compare

Syntax
:CellEquals(string name, int index, float value)

Description
:The Cell Equals function is similar to the ReadCell function, except it adds an additional value to compare against the cell value.

Like ReadCell, name specifies the name of the cell, index specifies the cell array index (use 0 for single value cells).

Available Cells:
:Any cell that is defined in the .cec file.

Return Value
:Units: 1 or 0
:1 if the cell value is equal to the passed in comparison value; otherwise 0

Function: '''GetObjDistPow2'''
:Get object distance squared

Syntax
:GetObjDistPow2(string name)

Description
:GetObjDistPow2 returns the distance squared between the external driver and the dynamic object specified by ‘name’.

Distance squared is used to avoid having to perform an expensive square root calculation every frame.

If the specified object cannot be found, a value larger than 100 million is returned.

Return Value
:Feet; Distance in feet measured from the eye position of the driver to the CG (centroid) of the dynamic object specified.

A very large number is returned if the specified object cannot be found (larger than 100 million)

Example
:GetObjDistPow2(‘OncomingCar1’) < 2500

'''Note:''' To get an actual distance, multiply by the square root (sqrt())
: sqrt(GetObjDistPow2('Target_Obj'))

Function: '''GetObjTtcToOv'''
:Get Object Time To Collision to Own Vehicle

Syntax
:GetObjTtcToOv(string object name)

Description
:GetObjTtcToOv gets the time to collision from the dynamic object specified by the name parameter, to the own vehicle.

Return Value
:Unit: Seconds
:Time (seconds) to collision from the own vehicle to the dynamic object specified by the name parameter.
:0 is returned if the object specified cannot be found.

Function: '''GetObjVel'''
:Get Object Velocity

Syntax
:GetObjVel(string object name)

Description
:GetObjVel gets the velocity in meters per second of the first dynamic object with the name specified by the ‘name’ argument.

Return Value
:Unit: Meters per second
:The speed of the specified dynamic object; 0 if no object is found

'''Note:''' Multiply by 2.23694 for miles per hour.

Example
:GetObjVel(‘PullOutVeh’) > 15.4

Function: '''Rand'''
:Random

Syntax
:Rand(int value)
:Rand(string name)
:Rand(string name, string type, double parameter, double parameter)
:Rand(string name, string type, int parameter, int parameter)

Description
:Rand returns a random value specified by the name of the generator, the type of distribution and its parameters.

If the user does not specify the name of the generator and only specifies a number as the only parameter, the Rand function will use a default random number generator to produce random numbers.

If the user only enters the name of a user created random number generator, the random number generator will produce a value between 0 and 1.
If a name of generator is supplied that has not been created, the Rand function will display an error message in the ISAT debug window and return 0 (during scenario rehearsal).

The rand function supports multiple types of distributions that can be used to generate a random number.

Types of Distributions:
:normal: Normal Distribution(mean, standard deviation). The normal distribution generates random numbers near the mean with a specific standard deviation.
:gamma: Gamma Distribution(alpha, beta). The gamma distribution generates a random value that models waiting times for the Poisson process.
:uniformInt: Uniform Integer Distribution(min, max). The uniform integer distribution generates a random integer number between the lower and upper bounds.
:uniform: Uniform Real Distribution(min, max). The uniform real distribution generates a random floating point number between the lower and upper bounds.

The values stated in the parenthesis above are the parameters for each distribution in order. If the incorrect number of parameters are entered or if they are entered incorrectly, the debug window in ISAT will display an error message and the rand function will return 0 (during scenario rehearsal).

If the distribution is entered incorrectly, the debug window will also display an error message.

Return Value
:A random value from 0 to 1 if the type of distribution is not specified.

If the type of distribution is specified, returns a random value determined from the type of distribution and the given parameters.

Example
:Rand(‘myRandGenerator’,’uniformInt’,1,10)
:This example returns a random integer value from 1 to 10.

Rand(5) or Rand(‘myRandGenerator’)
:These examples return a random value between 0 and 1.

Function: '''sqrt'''
Square root

Syntax:
:sqrt(parameter)

Return Value:
: return the square root of the specified parameter.
: parameter can be another function, such as GetObjDistPow2()

Function: '''ReadVar'''
:Read a variable

Syntax:
:ReadVar(string Name)

Return Value:
:Returns the string value of variable specified in <variable_name>

===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.

=='''Audio Components'''==
The components of the Audio sub-system includes configuration and data files installed into the NadsMiniSim_x.xx\data\sound\DefaultCabSound\Instructs folder.

[[File:audio_components.png|400px]]

The audio engine contains multiple channels and has a theoretical limit of 512 simultaneous sounds.

NOTE: Not all .wav files are compatible with the Audio Engine.

=Scenario World Objects=
Scenario world objects are defined in the tile model source. They are not added by the scenario author since they are objects already present in the roadmap/BLI.

[[File:object_types_world.png|400px]]

Typically, but not always, these objects can be authored in ISAT. However, some scenario world objects have no options - these cannot be selected in ISAT; therefore such objects cannot be authored.

Removal of world objects requires editing the source tile model using a 3D application. In some cases an alternate tile model is available identical to the original but without objects.

Contact NADS if removal of a world object is needed.

Other scenario world objects, such as Traffic Signals, are specialized function objects that can be authored. Traffic signals are authored using the Traffic Light Manager: Edit >> Traffic Light Manager.

=Troubleshooting Scenario Objects That Reset=

== Scenario World Objects ==
Scenario world objects are already present when you create a new scenario - they are not added by the scenario author. These objects may be visible in miniSim but not in ISAT, or they may be visible in ISAT and seem to be controllable, but the objects 'reset' to their defaults when viewed on miniSim.

[[File:2019-10-23_16h18_47.png|700px]]

The objects which 'reset' are a symptom of settings in the TMT that are not configured to allow scenario authoring of objects.

[[File:2019-10-23_16h18_52.png|700px]]

When objects appear to 'reset' or if you can edit an object in ISAT but don't see your changes in miniSim, correct the problem by resolving controllability in the TMT settings: https://www.screencast.com/t/ZH5Dh178.

=Scenario Coordinate Types=
There are two types of coordinates used in scenarios. The first is roadway coordinates. These coordinates are contextual (tied to a specific road or intersection and position) and are used for ADO objects and roadpad paths in general.

After a roadway coordinate has been generated, it is not updated unless the scenario author makes changes to the start, end or location of the entire path or pad.

Roadway coordinate are the reason it is not possible to change a roadmap using the TMT and expect a previously authored scenario to work on the altered roadmap. If the length or location of a road changes, the path/pad will update to the extent possible.

If the road has been eliminated and no longer exists in the roadmap/BLI, ISAT will report an error and not open the scenario file.

A. Field breakdown:
RoadPos keyword <name of road:lane:position on road:path length>

Name "Ado1"
RoadPos "r1_-6600_4620:0:5737.06:0.00"
Path "R:r1_-6600_4620:0[5736.06:5873.83]"

[[File:isat_coordinate_types.png|400px]]

B.
Name "VirtObj"
Option 2
Position -6.8375599E+002 5.6331237E+003 0.0000000E+000

The second type is world coordinates, which are Cartesian coordinates with X increasing to the right, Y increasing forward, and Z increasing up.

='''Scenario Authoring'''=
Scenario authoring is the creation, editing and testing of everything that happens during a simulation drive.

==Cell Operations: Best Practice==
Reading and writing to cells is a computationally expensive process. Best practice is to centralize all the reads/write to one place so that it’s only done once per cell.

Once a cell is read, the value is copied to a variable and only the variable is used throughout all the triggers that need it.

The same process applies to writing to cells. Use of variables can reduce the Cell Operations overhead greatly.

==Before You Begin==
Before beginning a scenario, it is necessary to understand the following requirements:

=== Drive Requirements===
How long is the drive?
What type of roadway?
Are there any specialized road elements (intersections, interchanges, freeway ramps)?
Are there any environmental requirements (should the simulation replicate a real world location, or is a generic environment acceptable)?
Is there a particular roadway configuration that is needed (long straight rural road vs. typical urban environment with intersections, signals, etc)?

=== Traffic Requirements ===
What types of traffic will be needed?
Will ambient traffic interact with the external driver?
What types of interaction will be required (traffic cloud, lead vehicle, follow vehicle)?

=== Events ===
The purpose of an event is to present a situation to the external driver. In order for the simulation to produce meaningful data, it is critical that events unfold for each driver in a comparable way. Therefore, each event must be designed with this repeatability in mind.

'''NOTE:''' one of the most variable scenario elements is the driving style of each external driver: how conservative or aggressive they drive, velocities throughout the scenario, how comfortable the driver is travelling with simulated vehicles, etc.

Repeatability often includes static elements (each driver encounters scenario elements in the same location) or in cases where the driver performance is taken into account, accommodation of the driver dynamic (velocity, lane position) through the use of time to arrival triggers (TTA) or follow triggers. A TTA trigger will fire based on time to a target location - thus a driver travelling at 45mph or a driver travelling at 55mph can both experience the same action relative to that target location, irrespective of the different driver velocities.

==Beginning A Scenario==
All scenarios designed to be driven require a start location - the place where the driver will be located when the simulated drive begins.

To insert a start location into a scenario:

:Insert >> External Driver >> LMB on road, intersection or terrain object

[[File:isat_initial_position.png|400px]]

'''NOTE:''' scenarios that only contain data and are not intended to be driven - for example, signs or traffic that are used as external reference files do not require a start location, since that will be defined within the parent scenario.

==Initial Conditions==
Initial conditions define how the simulated scene is configured: will the drive occur during daylight or night time conditions? Will the ownship (external driver vehicle) have headlights enabled? What type of vehicle will it be? Will there be objects or traffic visible to the driver?
These form the initial conditions of the simulation experience. Additional initial conditions would include initialization of variables or establishing networked communication as needed by the scenario.

[[File:isat_initial_conditions_miniSim.png|400px]]

By default ISAT sets the initial condition '''Time of Day''' to 12:00 noon. The time of day is controlled from the Initial Conditions dialog:

Edit >> Initial Conditions

[[File:isat_initial_conditions_scenario.png|400px]]

==Scenario Authoring: Actions==
Actions are the scenario elements that make things happen during simulation. Actions do specific things, like display a text message on screen for the driver, create a scenario element, change the velocity of simulated traffic, change a traffic signal, etc.

[[File:trigger_action_panels.png|400px]]

The diagram above shows the action panel for left to right: an expression trigger, a roadpad trigger and a global time trigger showing different panels based on the actions present in each trigger.

'''NOTE:'''Actions can be created, edited or removed from the '''Actions panel''' of '''any trigger'''.

'''NOTE:''' The Actions panel changes based on the action type created.
When multiple actions have been defined, control the sequence of actions by changing the action order in the list using the up or down arrows next to the list.

[[File:action_panel_overview.png|400px]]

If multiple actions need to happen in a specific order, set the order using the arrows and then flag the action list as '''sequential'''. This instructs behaviors to process the actions in the list order.

Using a delay for any action will pause processing of the '''following actions'''; the action happens first, then the delay is applied.

===Scenario Authoring: Action Types===
There are two types of actions:
# Instantaneous - the action takes up to one frame to complete, i.e.:
:set target velocity
:write to cell
# Persistent
<span style="color:red">'''*Persistent actions do not end'''</span>, or take multiple frames to complete:
:Forced lane offset
:Forced velocity
:Maintain Gap

==='''Actions'''===
*The "Who to Affect" field defines what is affected by the action
:Instigator set: who activated the trigger
:Name: one or more named elements
:Type: Apply changes to all objects matching the specified type
:Relative: Position relative to the trigger location

*Sequential
:Actions to execute sequentially, one after the other
:Specify delay between actions
:: Action executes, then delay

:Some actions are persistent and never "finish"

===Scenario example: display text & roadpad trigger to stop the drive===
This scenario is very simple and contains a global time trigger (GTT) that tells the driver what to do. After the driver travels along the roadway, a roadpad trigger (RPT) is used to tell the driver to stop driving. The same RPT also creates an expression trigger to terminate the drive.

TBC example scenario file

Because the external driver is not under control except by instructions, it's possible they might ignore the halt message and continue driving. A second failsafe RPT then terminates the drive.

==='''Actions: Button vs. Dial'''===
*Dial changes a setting
*Button: always runs in a single frame
:-"immediate" change. Typically buttons have less control than a '''Set Dial''' action

==='''ADO Actions'''===
[[File:ado_action_types_button_vs_dial.png|400px]]

==='''DDO Actions'''===
[[File:ddo_set_dial.png|400px]]

==='''External Driver Actions'''===
External driver behavior can be influenced by reinforcing scenario actions through audible speeding alerts, on-screen text instructions and messages or audio instructions.

Driving behavior can be influenced with situational elements
:Car in the drivers blind spot
:Lead vehicle
:Aggressive following vehicle
:Temporary lane closure
:lane specific instructions

Scenarios should '''not rely on specific driver actions to be successful'''
:to the extent possible; sometimes you do need the driver to respond/behave in a controlled manner.
:A work zone blocking one lane typically will require a roadpad placed upstream from the work zone to shift traffic into the correct lane

'''NOTE:''' Controlling driver actions should be an experimental design consideration.

==='''Special Actions'''===
These actions need special handling:
*Reset or "toggle":
:Audio
:Display Text

:'''Ado'''
::Audio State
::Forced Velocity
::Maintain Gap
::Visual State

*If using these persistent actions, place them at the '''end''' of an action sequence (because no action following these will execute):
:Forced Lane Offset
:Forced Velocity
:Maintain Gap
:Visual State

*Note: If the Visual State action contains a duration then it will be handled as a normal action, with subsequent actions firing after it. However, if there is no duration supplied with the Visual State action it behaves like a persistent action, and nothing following it in the Action stack will ever fire.

[[File:multiple_simultaneous_actions.png|400px]]

The diagram above shows how one parent trigger can be used to create multiple simultaneous triggers

*How to activate multiple unique force velocity (FV) or maintain gap (MG) actions:
#create the needed triggers from a general parent trigger, 1 per action
#put common actions into the parent trigger
::reset FV
::reset MG

==Scenario Authoring How To==
This section contains simple examples for various typical scenario situations.

===How do I specify an event?===
First, determine which method is best for you - the default measures (limited measures, 20 events max) or logstreams (all simulation data, no event maximum).

Regardless of method, you specify an event by identifying areas of significance in the drive and marking them so the data within the event region can be processed. Any trigger combination that can specify event start and event end may be used.

[[File:2022-07-01_11h21_52.png|400px]]

===How to know Which Coordinator or Trigger I need?===
The answer to this question lies in the type of information needed for an event:

*Time
:global time trigger
:or an expression trigger that calculates time
*Position or Location
:roadpad trigger
::or a time to arrival (TTA) trigger
::or an expression trigger that calculates distance
*Calculation
:Expression trigger

===How to Instruct the External Driver===

Instructions to the external driver can be accomplished by three main methods:
# Instruct the driver using experimental protocol (instructional or briefing presentation)
# Information messages displayed on screen: '''Action: ''set visual display text'' '''
# Information messages delivered as audio messages: '''Action: ''write to cell > SCC_Audio_Trigger ><audio ID>'' '''

===How to Add Traffic in the Scene ===

Generating traffic will happen in one of 5 ways:
# Created explicitly by inserting ADO, or copy/paste existing ADOs
# Created with a script
# Via a Create action inside a trigger, or placing scripted traffic inside a create action within a trigger
# From a '''Traffic Source'''*
# From the '''Traffic Manager'''**

Each of these methods has advantages and disadvantages.

==== Create Explicitly ====

The biggest advantage with this method of traffic creation is the high degree of control the scenario author has over:
# location of the created ADO
# Name of the created ADO
# Travel path of the created ADO
# Control when each ADO is created within the scene via Settings >> Creation Radius

The disadvantage is that creating a high volume of traffic will take some work with this method.

==== Created with a Script ====

This method combines the advantages of Creating Explicitly with volume. It is possible to create a large volume of traffic very easily with a script.

Disadvantages of using high volumes of traffic with a script: in the event it becomes necessary for a high degree of control over these ADOs, more is not better because ADOs will adapt to road conditions under their own power, unless the default ADO settings have been modified:
'''lane changes, including lane changes to accommodate freeway ramps'''
'''velocity adjustments'''

==== Via a Create action inside a trigger ====
Combines the advantages of the previous 2 methods with control over when to activate that traffic using a trigger action.

Disadvantages: Creating too many ADOs at one point in the drive can cause the miniSim to bog down for a few frames. If too many ADOs are present and active in the simulation at one time, this can cause the miniSim to drop frames and run sluggishly. This is highly noticeable and may increase the potential for the External Driver to experience '''simulator sickness.'''

==== From a '''Traffic Source''' ====

Traffic Sources rely on two methods to populate a scene with traffic:
# location specific, with each ADO created for a traffic source being a 'spawn location' for ADOs, or
# location agnostic if the ADO has '''relative creation''' enabled, thus being created relative to the object identified.

In addition to being created relative to a scenario element, ADOs are created relative to the specified scenario element:
# In front of (Longitudinal Distance > 0, where the number is feet offset from the object) , or
# Behind (Longitudinal Distance < 0, where the number is feet offset from the object).

Advantages: Can easily populate traffic into the simulation.

Disadvantages: It is easy to generate more traffic than the simulation can maintain at 60Hz frame rate, thus introducing frame lag with the resulting scene 'stutter' and the increased risk of simulator sickness.

Also, traffic created from a Traffic Source is generic traffic. It is not possible to reliably refer to specific ADOs generated from a traffic source except by using Who To Affect >> Relative (versus referring to a named ADO, i.e. Slow_Moving_Lead_Vehicle). Referring by name to Traffic Source generated ADOs will affect all similarly named ADOs at the same time.

==== From a '''Traffic Manager''' ====

The traffic manager interface is problematic in ISAT versions up to 1.8.5, especially when specifying the set of vehicles to be used for generating traffic.

Advantages: Create generic ambient traffic easily.

Disadvantages: Has the same disadvantages as traffic created via a Traffic Source. Also getting a traffic set working by specifying the vehicles to be used within the set. ISAT versions up to 1.8.5 exhibit instability when setting vehicles in ISAT.

Traffic Manager Set workaround: Borrow a working set from an existing scenario or group. Alternatively use a version of ISAT (1.8.6 +) to create the traffic set. This can be saved as a scenario or group file, which can then be used with ISAT 1.8.x as long as there is no attempt to adjust the vehicle weights within ISAT. The scenario or group file can be edited as text in a text editor, but care must be exercised to avoid introducing errors into the file. ISAT will not read invalid scenario or group files.

Traffic generated by the Traffic Manager is controlled through the use of Input Sets. An input set is a collection of vehicles and weights used to populate the scene during simulation. This is how the scenario author can control the vehicle population (type and number), density and creation/deletion distances - these attributes are unique to each set.

Since there is no 'discontinue traffic manager' function, one can be implemented by defining an input set with no traffic (an empty input set). An appropriate name can make the purpose of the set clear: PauseTraffic, Stop_TM, etc.

==== Sample Traffic Manager Set ====
This is a sample traffic manager set that can be pasted into a scenario file after the HCSM VehFail section. Be sure to paste '''after''' the HCSM VehFail end tag ('''&&&End&&&''') in your scenario file.

'''Note:''' A scenario file may contain only '''one''' Traffic Manager section.

There are two input sets in this example; note how they contain different vehicles and different settings from each other.

<span style="color:#2a4b8d">HCSM TrafficManager
GroupName "Traffic Manager"
HCSM InputSet
Name "ONE"
MinDensity 3.0000000E-002
MaxDensity 7.0000000E-002
MaxObjects 9
CreateDist 2.0000000E+003
DeleteDist 3.0000000E+003
AbsDeleteDist 3.4000000E+003
RunFreq 1.0000000E+000
SolWeights "cargill_semi_peterbilt_blu:2" "cargill_semi_freightliner_red:1" "cargill_semi_peterbilt_yel:3" "DumpTruck_org:3" "semi_peterbilt_yel_Walmart:2" "Cadillac_Escalade:10" "Ford_F150Xcab:15" "Saturn_Vue:10" "FordTaurus:15" "Escape:15" "DumpTruck:2"
&&&&End&&&&
HCSM InputSet
Name "TWO"
MinDensity 1.0000000E-002
MaxDensity 3.0000000E-002
MaxObjects 4
CreateDist 2.5000000E+003
DeleteDist 3.3000000E+003
AbsDeleteDist 3.5000000E+003
RunFreq 1.8000000E+000
SolWeights "Taurus2011:12" "Cadillac_Escalade:16" "Ford_F150Xcab:24" "Saturn_Vue:14" "Escape:6" "Deville:24" "Audi:4"
&&&&End&&&&
&&&&End&&&&
</span>

====='''Managing Traffic Manager Input Sets'''=====
During simulation, Input sets are controlled by the action '''Use Traffic Manager Set'''. A set name must be provided for this action to work.

===== Traffic Manager generated Traffic=====
ADOs will populate the road network around the XD based on the parameters of the Input Set. Typically traffic is removed from the scene shortly after passing the XD. This is visible in the rear view mirror. There is currently no way to adjust this delete distance.

====== Traffic Manager Traffic on 2 lane freeway======
Traffic will prefer to be in the XD lane, so ADOs created in any other lane will tend to veer into the XD lane. On a divided highway, traffic is generated moving with the XD.

====== Traffic Manager Traffic on 2 lane road======
Traffic is generated in the oncoming lane. In some cases traffic may be generated then immediately removed in front of the XD.

===How to Control Objects in the Scene during Simulation ===
"Set and forget" options on simulation entities only require the scenario author to "initialize" the element to a desired setting and then it is left alone during simulation.

Controlling objects dynamically during simulation requires the scenario "talk to" each object with a scenario action. This section describes how each scenario object type can be controlled during simulation within a scenario.

All models used in ISAT are listed within the Scenario Object Library (sol2).txt files. Terrain switch names are displayed in the ISAT workspace.

All model switches are listed within the NadsMiniSim_x.x\bin.x64\ModelList.txt file.

'''Note:''' The diligent reader will note discrepancies in model names between the sol2 and ModelList files. This is because the ModelList file contains actual file names, and the sol2 files define a "name label" for models that may, or may not, be the actual model name. Objects are linked between the sol2 and ModelList files through the ModelID/CigiID records. These values will match between sol2 and ModelList files, but IDs are not necessary at this time for scenario authoring purposes.

Complicated object names can be retrieved from the LRI file that was used to build any scenario file; each BLI is preceded by an LRI. The LRI contains all of the terrain models that will be present in ISAT. These are typically speed limit signs, traffic signals or other features that may be controllable.

'''Note:''' this file may not be present for the Springfield.bli file.

An alternative is to capture a screenshot of the ISAT workspace with the element name string showing. By default ISAT reports the name of any objects when the cursor passes over the object, as shown in this example:

[[File:2021-10-27_08h50_14.png|caption =Object Name Screenshot | 400px]]

{|class="wikitable"
|+ Controlling Scenario Elements During Simulation in Scenario
!Date
!Nads miniSim version
!Object Type
!Scenario Action
!Who To Affect
!Value
!Notes
|-
| Oct. 28, 2021
|2.3
|-
|
|
|Static Object (terrain)
| SetDial > StaticObjManager > Set Option1
| StaticObjManager
| switch name : switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
|Static Object, multiple options
| Set Switch
| Name of element
| switch option
|-
|
|
|Obstacle, multiple options
| Set Switch
| Name of element
| switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
| DDO, multiple options
| Set Switch
| Name of element
| switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
| ADO
| Set Dial > ADO > VisualState
| Name of element
| Limited to options present in ISAT
|-
|
|
| Traffic Signal
| Traffic Light
| Assign action to element
| Target state
| Target state must exist within the Traffic Light Manager intersection timing table for the specified signal

|}

===How to Control Simulated Vehicles===
The scenario author can control simulated vehicles by controlling the environment:
#change a traffic signal to cause an ADO to stop or start at intersections
#affect other ADOs to cause a target ADO to respond
# assign a path for the ADO to travel

Direct control:
*Lane related:
:Set button > ADO > ChangeLane, Turn, ProjectAndResetLane

*All other controls:
:Set Dial > ADO > AudioState, ForcedLaneOffset, ForcedVelocity, InhibitLaneChange, LaneChange, MaintainGap, TargetVelocity, VisualState, AudioState

====How to Change ADO Velocity====
ADO velocity can be changed using the SetDial action:
:SetDial > ADO >

:ForcedVelocity
:ForcedVelocity using an expression:
# match external driver speed
expr % OvVel(0) %
# multiply external driver speed
expr -1 9 %ReadCell('OvVelLocal',1)*1.75 %
:TargetVelocity

Indirect Control (dependent on other scenario element):
:MaintainGap

====How to Link ADO Velocity to Something Else====
ADOs velocity can be linked to other ADOs or the external driver using the MaintainGap (MG) action.

SetDial > ADO > MaintainGap

When using a traffic cloud containing multiple ADOs, each ADO in the cloud needs a unique MG. IF multiple ADOs have the same MG settings they will attempt to satisfy their parameters and likely oscillate position in a visually obnoxious way.

===How to Author Loop Scenarios===
A scenario created on a loop road network operates very much like any other scenario, with the exception that it is likely to require tracking the number of times through the loop, or to present scenario events to the external driver depending on each loop context.

[[File:loop_traffic_creation_01.png|400px]]

The simplest method of tracking loops is the use of a loop counter variable. This variable can be set by the driver "stepping onto" a roadpad trigger or it can be initialized through the use of a timer or expression, with increments managed by a roadpad trigger. Each time through the loop increases the loop count variable.

Thus it becomes possible to create events for each loop based on the loop counter variable, typically through an expression trigger.

Loop management triggers

[[File:loop_management_02.png|400px]]

Loop management trigger detail one

[[File:loop_management_vars_02b.png|400px]]

Loop management trigger detail two

[[File:loop_management_3.png|400px]]

====Creating Loop Specific Traffic====
Creating loop traffic is slightly more complicated due to the number of objects to be created and potentially the size of the actual loop. A small loop is installed with the Nads miniSim as simple_rural1 or simple_rural2. Each is a loop road network with two signed 3-way intersections.

Loop specific traffic can be created through the use of a variable (i.e., LoopCount) or within the roadpad trigger that is incrementing the loop count variable. Both methods will incorporate a '''Create Action''' that creates the required elements.

===How to Change Environment Settings===
The scenario author can define global or localized environment conditions.

1. Insert >> Environment Conditions >> <chosen condition>

2. Define a region where the environment condition is active:
:LMB to define polygon points
:RMB to exit point entry mode

[[File:env_condition1.png|400px]]

Choosing an environment condition

[[File:env_condition2.png|400px]]

Environment region defined and parameters panel shows available options

NOTE: The environment condition boundary is a discrete threshold. Condition A will be on one side of the threshold. Immediately after crossing the boundary, condition B will be displayed.

===How to Fade an Environment Condition===
To fade gradually between two conditions requires the use of an expression that continually monitors the desired condition and sets a few variables based on the results.

Examining the demo scenario is the best way to look 'under the hood' to see exact command syntax and values to be used.

[[File:env_fade.png|400px]]

Note: this approach has been used for fog and visibility. It is unknown how it might work with non-visibility conditions such as precipitation and wind.

*From the scenario demo_visibility_transition.scn

[[File:env_fade_schematic.png|400px]]

'''Note:''' although the example above uses an environment condition boundary, '''it is possible''' to omit the defined region, retaining all commands and the scenario will still function. However, without the environment region, it becomes more difficult to determine where conditions are different from the standard settings.

===How to Control a Cab Instrument Panel icon===
In order to control the instrument panel, there are 2 requirements:
The specific cab used for the scenario
The specific control (switch) to be manipulated
The action for addressing the instrument panel is '''ChangeCabSetting'''

Instrument panel models are located in NadsMiniSim_x.x\data\Visuals\Instruments
These files are in OpenFlight format. Any 3D editor capable of reading or importing OpenFlight can be used to review these files. NADS uses the Presagis product Creator[tm].

An alternative method to inventory switches is to use the the '''buildscl.exe''' tool. To run the tool, open a CMD window to the IP folder location above, then run the command:
buildscl <input_file.flt><Enter>.
<input_file.flt> is the name of the file to process, without the '<>' characters.
<Enter> means to press the Enter key,

The result will be in a new file ending with .scl. This is a text file, and can be opened in a text editor or you can use the shell utility '''more''' to view the file contents:

more <input_file.scl> | grep switch<Enter>

An example for the malibu cab is shown below. .

switch s_LowWasher 0
switch s_Cruise 1
switch s_LeftTurn 2
switch s_RightTurn 3
switch s_FwdCollisionWarn 4
switch s_BlindSpotWarn 5
switch s_LaneDeviationWarn 6
switch s_RearCollisionWarn 7
switch s_HighBeamHeadlights 8
switch s_SeatBelt 9
switch s_UpArrow 10
switch s_Airbag 11
switch s_CheckEngine 12
switch s_CheckGuages 13
switch s_ABS 14
switch s_Brake 15
switch s_LowFuel 16
switch s_Gear 17

These controls may be accessed directly in scenario using the ChangeCabSetting action.

'''NOTE:''' Some functions such as Cruise, Gear, High beam headlights, Blind spot, collision, lane deviation warnings are '''normally''' controlled not by direct access as described here but by hardware mechanisms/buttons.

'''NOTE:''' For altering cab instrument panel operation it will be necessary to modify the OpenFlight model to include the desired funationality; for example, instrument panel blanking is not build into the model but can be added by editing the cab instrument panel model file then installing the modified file into miniSim.

===Scenario Hints===
The total number of scenario elements active at any given time can affect simulator performance:

Total number of active elements
*vehicles (ADOs), triggers, animations, etc.

Object management
*Use paths to shift ADOs away from the driver route of travel as they turn off the route
*reduce the number of vehicles in traffic cloud surrounding external driver
*use creation radius to limit the number of active elements, and to remove elements after the driver has traveled beyond the creation radius

[[File:creation_radius_1.png|400px]]

Creation radius works by activating the scenario element only when the driver is within the radius. The scenario element is created when the driver enters the creation radius, and is deleted after the driver leaves the creation radius.

Exploit environment to reduce object load

*Use curves, hills, intersection corners to mask objects

Object deletion
*Remove objects when no longer needed

When creating dynamic elements, create them as close to where they are needed as possible.

====How to Determine When ADOs are Visible to the External Driver====

Some development/setup testing may be needed to determine precise location/distance/speed; i.e., locating ADOs for a freeway ramp merge event where the external driver is merging onto the freeway with other ambient traffic present.

Unless the purpose of the event is to study driver behavior at the merge, ideally the scenario will be authored to have ambient traffic on the freeway but not to present a conflict at the merge for the external driver.

A straightforward way to determine where the ADOs are first visible to the driver is to mock up a scenario placing colored ADOs along the freeway with a velocity of 0. This will ensure the ADOs remain stationary while the scenario author determines where they are first visible to the external driver.

Place the start position/external driver far enough up the ramp to be a reasonable test for the actual scenario.

As you drive the ramp, see which ADO is first visible to the driver. Place ADOs just out of view (upstream) of that location.

[[File:merge_hint.png|400px]]

'''NOTE:''' use test vehicles of the same type and character as the intended scenario vehicles. For example, do not use a sedan test ADO for a larger vehicle (SUV, bus, dump truck). Doing so will invalidate the visibility test, because a larger ADO will be visible over a longer distance than a small ADO.

[[File:ramp_vis_1.png|400px]]

At the scenario start location, ADOs in front of the Coke truck are visible. Note how the larger vehicles are more obvious at this distance.

[[File:ramp_vis_2.png|400px]]

The driver has traveled onto the ramp. At this point, the last ADO visible to the driver is still the Coke truck.

[[File:ramp_vis_3.png|400px]]

As the driver travels farther down the ramp a small ADO is visible behind the Coke truck.

The answer to the question '''When is an ADO visible?''' is thus:
#It depends on how large the ADO is
#Small ADOs can be placed at the location of the red ADO behind the Coke truck.
#Large ADOs may need to be placed farther back (behind the red ADO). This test is inconclusive, but based on the terrain it seems likely that large ADOs would need to be placed at least at the green ADO location (behind the Coke truck).

Creating small ADOs at the green ADO location when the external driver is located at the ramp position in 3 travelling at the same speed as the external driver should arrive at the merge slightly ahead of the driver (because the curved ramp is longer than the straight freeway).

'''NOTE:''' ADO size, ADO color, time of day and visibility settings affect ADO visibility.

====How to Position Objects Precisely using '''Place Object At..'''====

ISAT does not support true precision because it is not currently possible to 'dial in' a position as is typical in 3D modelling tools, but there is a way to approximate precision in cases where a consistent measurement is desired.

In the following example a number of roadpad triggers are placed relative to the location where a roadway enters an intersection. This is a discrete boundary within the simulation world as shown in ISAT.

There are two methods of placement possible:
# Measure the desired distance (CTRL+Shift+RMB, drag); take note of the coordinates updating in realtime and make a mental note of the desired location.
#Place an object (ADO or static object); use the Place Object At.. feature from the context menu when you RMB on a scenario object.
Using this method you can specify a distance - positive numbers move the object downstream/forward, negative numbers move the object upstream/backward.

'''Note:'''If the distance is significant and extends over an intersection, ISAT may produce unexpected and undesired results such as re-starting the measurement from the closest upstream intersection, thus placing the object where it was not intended.

In the following example, Place Object At.. is used to specify a point 50 feet upstream from the road/intersection border.

[[File:precision_placement_1.png|400px]]

A roadpad trigger has been positioned near the area of interest. Any existing roadpad is deleted from the trigger.

[[File:precision_placement_2.png|400px]]

An ADO is used as a marker object inserted temporarily into the scenario. Any convenient object may be used.

'''Note:''' large objects such as ADOs may be less precise than small objects such as the Traffic cone, but is generally easier to access in the ISAT interface unless you have created a script for cone objects.

[[File:precision_placement_3.png|400px]]

RMB on the ADO to access the Place Object At.. request dialog. Only numbers are valid entries.

[[File:precision_placement_4.png|400px]]

The desired distance is entered into the Place Object At.. request dialog. ISAT will then require you to select the object you wish to move using LMB.

[[File:precision_placement_5.png|400px]]

ISAT moves the selected object by the distance you specified.

[[File:precision_placement_6.png|400px]]

Use the ADO CG (model center) to place the start of the road pad.

[[File:precise_placement_7.png|400px]]

Remove the ADO marker and save your scenario.

==Scenario Testing and Debugging==
The primary way to test and debug scenarios is using ISAT rehearsal mode.

'''NOTE:''' the external driver during rehearsal is a simulation. You have limited control over the simulated ownship:
#change speed
#change lane

ISAT has two rehearsal dialogs:
#abbreviated (standard) dialog
#advanced (extended dialog)

===How to change to the advanced rehearsal dialog===
Often it is necessary to control the ownship during rehearsal. The ownship controls are located in the advanced (extended) rehearsal dialog.

ISAT will show the Advanced dialog the first time rehearsal mode is activated. All additional activations show the abbreviated dialog.

TBC abbreviated dialog

To use the Advanced dialog, LMB the Advanced button.

TBC Advanced dialog

===How to change ownship speed during rehearsal mode===
After entering rehearsal mode:
#click the Play icon (start the rehearsal)
#pause.
#adjust ownship speed
#toggle pause off (resume rehearsal)

===How to make ownship lane change during rehearsal mode===
After entering rehearsal mode:
#click the Play icon (start the rehearsal)
#click the desired Lane Change (left or right)

===How to Use Audio in your Scenario===
Scenarios play audio sounds and messages through a write to cell action: '''SCC_Audio_Trigger'''

Use of audio in a scenario typically requires both a write to cell and a 'clear action' that writes a zero (0) to SCC_Audio_Trigger in order to 'clear the channel'. The 'clear' action can happen before or after playing a sound; choose one method and be consistent in your scenario authoring.

Failure to 'clear the channel' or '''not''' writing a value of zero can result in no audio being played for subsequent write to cell SCC_Audio_Trigger actions.

The following shows how this looks in scenario when executed from a roadpad trigger (RPT):

[[File:audio_scn_A.png|400px]]

The above diagram is shown below in text format:

HCSM RoadPadTrigger
GroupName "WindGust_Audio"
ByTypeSet "ExternalDriver"
NthFromStart 0
NthFromEnd 0
VehicleAhead 0
VehicleBehind 0
LongComment "This is a wind gust event"
ShortComment " "
ActvDel 0.0000000E+00
CrRad 0.0000000E+00
Debounce 0.0000000E+00
FireDelFrames 0
Lifetime 0.0000000E+00
Name "RPT_WG_6"
OneShot 1
Priority 0
SeqAct 1
Position 6.7165800E+04 6.0419215E+03 0.0000000E+00
DrawPosition 6.7165800E+04 6.0419215E+03 1.1308095E-317
Path "R:r3_62700_7920:0[3033.04:3245.46]"
HCSM LogData
Comment "LS1=8"
Delay 0.0000000E+00
InstigatorSet 0
Stream 1
StreamVal 8.0000000E+00
&&&&End&&&&
HCSM WriteCell
Comment "Play_Audio"
Delay 2.0000000E+00
InstigatorSet 0
CellName "SCC_Audio_Trigger"
CellData "63000"
CellType 2
CellVar 0
&&&&End&&&&
HCSM WriteCell
Comment "clear_audio"
Delay 0.0000000E+00
InstigatorSet 0
CellName "SCC_Audio_Trigger"
CellData "0"
CellType 2
CellVar 0
&&&&End&&&&
&&&&End&&&&

===How to Add Custom Audio Instructions to miniSim===

''' Please note: Custom audio 'instructions' for a scenario should be added to the instructions.txt file.'''

These are sounds that are played in scenario, typically as directions for the minSim driver.

Adding custom audio files requires the following procedure:

1 Exit miniSim - changes to the miniSim configuration should happen only when miniSim is not running.

2 Copy the audio .wav file to:
:C:\NadsMiniSim_x.x\data\sound\DefaultCabSound\Instructs

:Edit the file instructions.txt in that same folder.

3 Add an entry to instructions.txt to register your audio file in accordance with the following layout using the existing entries as a template:

:Unique_ID Filename Normalized_Volume

:Unique_ID is whatever unique number you assign to your file.

:Filename is the name of your .WAV file.

:Normalized_Volume is the volume your audio file should play, where 0.00 is silence and 1.00 is maximum volume.

'''NOTE: Remove all spaces in your audio filename.''' If needed, use the underscore character instead of spaces.

===Troubleshooting Custom Audio Additions===
After installing new .wav files and adding them into the audio configuration file '''instructions.txt''', if the audio file does not play:
*Check the Audio Engine window while miniSim is still running. The Audio Engine will display file errors,.
*If Audio Engine does not display a message similar to: Audio Engine loaded normally, scroll through the window messages and look for any .wav or load error messages.

==Re-use of Scenario Elements==
Scenario authoring can be an intensive undertaking. It makes sense therefore to leverage your development efforts by re-using scenario elements where possible.

ISAT provides a number of ways to re-use scenario elements:
# copy/paste
# external references
<span style="color:#ac6600"># exporting elements as '''groups'''</span>
# isc scripts

Each of these methods have their strengths and weaknesses.

===copy/paste===
The simplest method to re-use scenario elements among different scenario files is copy/paste. This is possible for most scenario elements* even if the source and destination roadmap/BLIs are radically different.

[[File:copy_paste.png|400px]]

It is also possible to copy an ISAT element from one scenario to another as '''TEXT''' by selecting the element and using the windows copy shortcut CTRL-C, then open a text file and paste it using the windows paste shortcut CTRL-V.

'''NOTE:''' Traffic sources are '''not''' portable using copy/paste.

'''NOTE:''' Not all elements can be copy/pasted. Elements created from a Create Element action cannot be copied - it is necessary to select the parent element and copy that instead.

[[File:copy_paste2.png|400px]]

In the above diagram, elements at '''B''' and '''C''' cannot be copied/pasted because they have been created by element '''A'''. It is necessary to copy the element at '''A''' instead. If only the elements at B are needed, the best method will be to copy/paste as Text.

'''NOTE: ISAT will not copy elements containing road coordinates (elements with a path) to a scenario that does not share the same BLI as the source (copy from) scenario.'''

A partial solution to such cases is to remove the path first, copy the element, paste into the destination scenario, then re-create the path manually.

===External Reference===
An external reference scenario is intended to be re-used by multiple 'parent' scenarios. The effort of authoring objects is thus leverages across multiple files, without needing to re-create the same elements more than once.

[[File:re_use_xref_1.png|400px]]

Common uses of external references include traffic, traffic signal operation, traffic sign appearance or other environment features which have multiple appearances (billboards, some tile related scenery, etc).

NOTE: Multiple external references are possible; but because objects are categorized by group, it is not entirely necessary.

For example, one external reference file contains traffic, another contains signs. These two external reference scenarios could be combined into one file.

[[File:xref_overview2.png|400px]]

NOTE: Each group defined must be unique across all files: parent and external reference files.

In order to use an element in an external reference scenario, it is necessary to define and assign a group to all elements that you wish to control from the parent scenario.
At this time there is no visual hint in ISAT to indicate if a group has been assigned to an element or not - each element has to be confirmed independently.

However, a properly authored external reference element cannot be edited within the parent scenario (after you have done Add Ref. to use the external reference file).

An alternative is to insert groups using a text editor with macro capability, or to use a program or external script to make the necessary changes.

'''NOTE:''' If the external reference file is for object contained in the parent scenario (for example, an external reference file containing traffic signals with a group defined) it is still necessary for that group to be defined in the parent file.

With traffic signals, ISAT requires ONE explicit group reference, which will be contained in the HCSM TrafficLightManager block as shown below. If you require the use of traffic signals in an external reference, the recommended way to do this is through ISAT because then it manages the group assignment for you.

==== HCSM TrafficLightManager scenario block ====

HCSM TrafficLightManager
HCSM CLG
IntrsctnName "I1_40260_4620"
Duration 2.0000000E+01 3.0000000E+00 1.0000000E+00 2.0000000E+01 3.0000000E+00 1.0000000E+00
GroupName "TrafficSignals"
LightName "s_signal_r1_LTRN_40260_4620_270"
LightName "s_signal_r1_RTRN_40260_4620_270"
LightName "s_signal_r2_LTRN_40260_4620_270"
LightName "s_signal_r2_STRT_40260_4620_270"
LightName "s_signal_r3_STRT_40260_4620_270"
LightName "s_signal_r3_NORM_40260_4620_270"
Pattern "FLTY" "R" "R" "R" "R" "R" ""
Pattern "RTG" "R" "R" "R" "R" "R" ""
Pattern "LTR" "LTR" "LTR" "FLTY" "FLTY" "LTR" ""
Pattern "SR" "SR" "SR" "SG" "SY" "SR" ""
Pattern "SR" "SR" "SR" "SG" "SY" "SR" ""
Pattern "R" "R" "R" "G" "Y" "R" ""
&&&&End&&&&
&&&&End&&&&

'''NOTE:''' At this time there is a known issue using the write cell '''SCC_Audio_Trigger''' action in external references. Although the trigger containing this action can be assigned a group and used as an external reference, audio does not play.

<span style="color:#ac6600">'''Because ISAT updates static object positions (elevation) to the terrain (roadway) when the scenario file is saved, the best way to use a custom elevation is to put such objects into an external reference file in order to isolate those objects from normal scenario editing.''' </span>

====Define a Group====
<span style="color:#ac6600">'''NOTE:''' ISAT 1.8.5 and 1.8.6 currently do not work properly with group files. These versions will not import objects within a group file. There is a workaround which involves the following process, but instead of reading the saved group file into a scenario the workaround requires editing the scenario as text and inserting the objects within the group file into the scenario.</span>

RMB on the element and choose from the context menu: Group >> New Group (if this is a new group) or Group >> (choose an already defined group).

'''NOTE:''' The first time you create a group for an object, ISAT will automatically assign the group to that object.

After defining and assigning groups to the scenario elements needed, save the scenario file then close it.

Open or create the parent scenario file and use the Add Ref. button at the bottom of the ISAT window to select your external reference scenario. After you choose a file ISAT will present you with the groups found in that scenario. Choose the groups you with to include and click the 'Okay' button. Click the Add Ref. OK button to complete the process.

Currently import group file operations are not working, but it is possible to insert the group file content (all HCSM StaticObjects) into a scenario manually by using a text editor to copy text from the group file and paste that into a scenario file into the HCSM Static Object section of the scenario file.

[[File:group_text.jpg|400px]]

'''NOTE:''' ISAT does not enforce logic on your external reference authoring. If you add references to scenarios that do not share the same roadmap/BLI as the parent scenario, it is likely that elements will be placed at the origin (in cases where the external reference roadmap contains roadways not found in the parent) if it even loads.

===Exporting ISAT Elements as Groups===
Transferring ISAT elements among scenarios can be accomplished using groups. As with external reference scenarios, one or more groups must be defined and then assigned to one or more elements.

After defining and assigning groups select the group for export using the Group select drop-down located at the lower left corner of ISAT. Choose a group to export and then click the 'Save Group' button. Save the file.

TBC insert graphic sequence diagram here

'''NOTE:''' If you cannot locate the group file in the folder specified, check the ISAT install\data folder. This is typically:

C:\NADS\ISAT\data

===Group File Contents===
The group file is a text file and can be opened or edited in a text editor.

The following is a group file containing one ADO. Note the GroupName line near the bottom:

Header
LriFile "_dev.bli"
LongComment "this is a test group export"
ShortComment "this comment was left empty"
&&&&End&&&&
HCSM Ado
RunMode "eREMOTE_CONTROL"
RandomSol 0
Name "Ado1"
DynModel "Non Linear"
LogFile ""
LatOffsType 0
CreateRelLatInFeet 0
CreateRelOffsLonUsingExpr 0
CreateRelOffsLonExprStr ""
AutoControlBreakLights 0
AutoControlHeadLights 0
UseReaDel 1
StdToAccType 0
StdToDecType 0
StdToDecVal1 9.0000000E-001
StpToAccType 0
DecToAccType 0
FollowTimeMin 1.0000000E+000
FollowTimeMax 2.0000000E+000
EmergDecClip -1.1000000E+001
Accel2Catch 0
NormVel2Kp 7.0000000E-001
PathSearchDepth 2
LcvFall 1.5000000E+000 2.0000000E+000
LcvFreq 3.0000000E-002 5.0000000E-002
LcvRAmpl 1.0000000E-001 5.0000000E-001
VelCtrlInitMatchOvVel 0
VelCtrlFollowSpeedLimit 0
VelCtrlDistType 0
MaxLatOffset 9.0000000E+000
LongComment " "
ShortComment " "
SolName "Audi"
RoadPos "r1_1320_44220:2:32414.44:0.00"
GroupName "TEST_Group"
&&&&End&&&&
HCSM StaticObjManager
&&&&End&&&&
HCSM DriverMirror
&&&&End&&&&
HCSM IntersectionManager
&&&&End&&&&

===ISC Scripts===
Scripts are an efficient way to automate repetitive and/or complex tasks.

ISAT uses a custom language (ISC) to automate placement and manipulation of scenario objects. Combined with simple direction commands and the capability to navigate a road network, ISC scripts can ask the scenario author for input and prompt for selecting objects.

ISAT installs with some ISC script files. If your version of ISAT contains a data\isc
folder, then your version of ISAT is capable of running scripts. You can create
additional scripts as needed. All scripts located in the data\isc folder will load in ISAT
when ISAT is launched.

You can use these scripts for reference in creating your own custom scripts.

New scripts created during an existing ISAT session will not appear until ISAT is re-
launched.
Scripts that have been edited will not update until ISAT is re-launched.

Unless otherwise indicated, scripts are case-sensitive.

'''NOTE:''' Please do not edit the existing scripts!

Make a copy of any existing script before you make changes. In the event your modified script does not work, you can look at the original file for reference.

ISC scripts are located on the ISAT Elements widget. Custom isc scripts are located after the 'Events' separator.

Using an ISC script involves LMB + dragging the desired script onto the workspace. In some cases the script will ask for inputs.

ISC can be also used to create an entire event, thus ensuring that all events created will be entirely identical in terms of settings and locations for all created elements.

ISC scripts are text files located within the ISAT installation data folder. Only the custom ISC scripts are located in this folder. This is typically:

C:\Nads\Isat\data\isc

====Icon Files====
Script icon files are 8-bit windows icon files (file.ico). GIMP is capable of exporting valid ico files. To create an ico file, scale it to 32x32 pixels. Export the file as .ico to the isat\data\isc folder.

In order for a script to use an icon file, both files must exist in the isat\data\isc folder.

====ISC Script Examples====
This section contains example scripts with notes.

'''Rotate sign'''

.Name SetSignRotation
.Icon SignRot.ico
Static sign
Select(sign,"Please Select a Sign")
sign.SetAngle(Anchor)
.End

'''Place Multiple Static Objects (TrafCone)'''
The following script asks the scenario author for number of cones to generate, position and offset values and then generates the objects.

A breakdown of the script follows the code block below.

.Name Cones
.Icon cone.ico

Block coneBlock %%%
HCSM StaticObject
IsNewObj 1
Name "Cone_xxx"
SolName "TrafCone"
Option 0
Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
&&&&End&&&&
%%%
Static cone;

Value dist1
Value numberOfCones
Value distance
Value variablePart
Value randDistance
Value speed
Value Count
Value LatOffset

Block tempBlock
tempBlock = coneBlock
Count = 1
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

Ask(numberOfCones,"How many cones?" )
Ask(dist1,"Distance between cones?" )
Ask(LatOffset,"How much offset?" )

Position posRp
Position tempPos
posRp = Anchor
numberOfCones = numberOfCones

Repeat numberOfCones
posRp.GoForward(dist1)
# test comment
tempPos = posRp;
tempPos.SetOffset(LatOffset)
cone.RoadPos = tempPos
cone.Clone
Count = Count + 1
tempBlock = coneBlock
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

End
.End

====Script Breakdown cones.isc====

This section contains a description of the elements used in the script. The script segment is followed by a brief text description.

This script places a number of object copies (TrafCone) using information provided by a user.

.Name Cones
.Icon cone.ico

The first line contains a keyword '''.Name''' followed by the name of the script. This is the name that ISAT will use on the Isat Elements widget for the script. Note the script name does not have to be the same, but it is good computing practice.

The second line begins with the keyword '''.Icon''' followed by a file name. This file must exist in the ISAT\data\isc folder (accompanying the script file). This is the icon ISAT will use for the script.

Block coneBlock %%%
HCSM StaticObject
IsNewObj 1
Name "Cone_xxx"
SolName "TrafCone"
Option 0
Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
&&&&End&&&&
%%%

This is the data section of the script, which is defined using the keyword '''Block'''. A block name follows the keyword, and the data start is defined with '''%%%'''.

The HCSM StaticObject section has been copied from a scenario. In this case, a static object was placed into the workspace and then copied into a text file.

Name "Cone_xxx"
Note: the object name contains a marker that can be used to programmatically name instances of the object:

SolName "TrafCone"
This line begins with the keyword '''SolName''' followed by the name of the object as it is defined in the sol2.txt file.

Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
The Position of the static object will update when the script activates and instanced objects are placed in the workspace.

Static cone;
This line begins with the keyword '''Static''' followed by a variable name.

Value dist1
Value numberOfCones
Value distance
Value variablePart
Value randDistance
Value speed
Value Count
Value LatOffset

This section defines variables with the keyword '''Value''' followed by variable names. Using descriptive names is better than generic names. From the variable list it already seems clear what the programmer cares about: number of cones and distances.

Block tempBlock
tempBlock = coneBlock

This section defines a block using the keyword '''Block''' followed by the variable name.

The next statement replicates coneBlock into tempBlock.

Count = 1
Initialize the value of the variable Count to 1.

tempBlock.Replace('xxx',Count)
The built-in '''Replace''' function changes the string 'xxx' to the value of the variable Count.

cone.SetBlock(tempBlock)
This statement creates a block using the function '''SetBlock''' called cone, and copies the contents of tempBlock into it.

Ask(numberOfCones,"How many cones?" )
Ask(dist1,"Distance between cones?" )
Ask(LatOffset,"How much offset?" )

This section asks the user for input and puts that information into variables:
*Number of cones
*Distance between cones (dist1)
*Lateral offset (calculated from lane center)

Position posRp
Position tempPos
posRp = Anchor
numberOfCones = numberOfCones

This section contains position variables and assigns the value of numberOfCones.

Repeat numberOfCones
posRp.GoForward(dist1)
# test comment
tempPos = posRp;
tempPos.SetOffset(LatOffset)
cone.RoadPos = tempPos
cone.Clone
Count = Count + 1
tempBlock = coneBlock
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

This section is where the work happens. Reading from the top, this section is contained within a loop defined by the keyword '''Repeat'''. The number of times to repeat follows in a variable numberOfCones.

'''posRP.GoForward()''' is a built-in function to take the current position and shifts it forward by the amount specified in the dist1 variable.

#test comment
This is a comment defined by starting the line with the comment keyword '''#'''

tempPos = posRp;

Assign the value of the variable tempPos to the value currently in '''posRp'''

tempPos.SetOffset(LatOffset)

Another built-in function or attribute to the position element which defines a lateral offset (distance from the lane center). This statement places the value of a variable LatOffset into the offset element of the tempPos variable, using the operand '''SetOffset'''.

cone.RoadPos = tempPos

This statement sets the road position variable for cone to the value in the variable tempPos.

cone.Clone

Duplicate the block cone using the operand '''Clone'''

Count = Count + 1
Set the value of the variable Count to the value of Count plus one. This statement increments the value of Count for each loop processed.

tempBlock = coneBlock

Create a new block tempBlock by setting it to the content of coneBlock.

tempBlock.Replace('xxx',Count)

Use a built-in function to '''Replace''' the string 'xxx' with the value of the Count variable

cone.SetBlock(tempBlock)

Use the built-in function '''SetBlock''' to place the modified tempBlock (modified by the string replacement command earlier) into the cone block.

End
.End

The last two lines terminate the loop and the script, respectively.

====How to Create an ISC Script====
The simplest way to create an ISC script is to find an existing script that does something similar to your desired behavior and edit it.

=miniSim Simulation Data=
MiniSim runs on shared memory:
*miniSim is a collection of programs
*shared memory is a commonly accessed 'blackboard' list: a Cell and a Cell Value
:The DAQ file is a snapshot of this 'blackboard' memory for every frame.

*Scenario can write to cells added by the scenario author
:-i.e., for custom hardware or tasks/events

'''NOTE:''' Custom cells must be present in the collect file (NadsMiniSimCollect.cec) '''prior to''' simulation in order for the custom cells to be present in the DAQ.

NOTE: The cell type defined in the collect file must be followed, or garbage values will be used

Use of a DAQ file implies that at some point, data reduction will be needed.
Data reduction: the process of distilling measures from the DAQ file, i.e.
*Event definition
*SDLP
*Average headway

==What is the Difference? Cell vs. Variable==
*A Cell is a pre-created “slot” in shared memory
:-Specified in the .CEC collect file,
:-Saved in the DAQ file,
:-Can be sent to custom programs;
:-Can create & use custom cells;
*A Variable is a name value internal to the scenario
:-NOT saved to the DAQ file,
:-Can use to track items in the scenario
:i.e., how long the driver has been exceeding the speed limit
:-Initialize conditions in the scenario.

=== Variables Save ===
Variables can be saved to disk as a single value text file (ie, multiple values over time are not supported) through the use of a '''Store Variable''' action:

[[File:2021-08-23_13h28_49.png|400px]]

The file is stored in the miniSim_x.x\bin.x64 folder.

'''NOTE:''' The name of the file is defined within the Store Variable action. '''Care must be taken to save variables to unique file names''' in the case of multiple scenarios running on miniSim at the same time (if they share common variables), as would be the case if triggers are copied from one scenario to another.

=== Variables Restore/Read ===
Variables can be read into the simulation through the use of a '''Load Variable''' action:

[[File:2021-08-23_13h32_39.png|400px]]

==Cell Types==
This is a partial list of cell types.

*CFS = control feel subsystem (steering wheel, pedals)
*CIS = control information subsystem (gear, turn signal, buttons, etc)
*TPR = terrain profiler for terrain queries
*VDS = vehicle dynamics for accelerations, position, engine speed, speed, etc.
*ACC = adaptive cruise control
*RCM = configuration management for setting variables that affect subsystem configuration (ACC enabled or disabled, for instance)
*SCC = scenario
*SOP = for one time initializations at the start of the simulation.

=='''Data Output Actions'''==

*Write to Cell Actions
:-Write the value of a variable or cell to a cell
:-Write to a custom cell
:-Cannot overwrite another systems output
'''NOTE:''' Although it is possible to write to a different system cell, that value will be over-written on the next frame. Thus it is effectively not feasible nor desirable to do.

'''<span style="color:red">Also Note: the limit for maximum number of write to cell actions that can be performed in one frame is 8.</span>'''

*Set Variable Action
:-Sets the value of a variable
:-Does not have to be created first
:-Not saved in the DAQ unless written to a valid cell
*Logstream
:-Log data action

===Data Output Methods===
Your data is the primary reason for simulation.

1. Default miniSim scenario measures
:- Immediately available

2. Alternate scenario measures (DAQ file)
:- Processed through data reduction

====Default miniSim Scenario Measures====
*Saved to a drive report.txt file
*Saved to the same Location as DAQ files;
:Scenarioname_timedatestamp_report.txt
•Measures calculated overall, and up to 20 Events during drive:
:Collision Count Lane Departure Count
:Maximum Speed Lane Departure Percentage
:Minimum Speed Speeding Count
:Average Speed Speeding Percentage
:Standard Deviation of Speed Average Headway
:Standard Deviation of Lane Position

====Default miniSim Scenario Measures Require Scenario Event Definition====
In order to capture meaningful data into the default miniSim measures, a scenario must be configured properly to define events.

Use the Write to Cell action to activate the default measures.

[[File:2021-07-02_11h02_44.png|400px]]

*At the start of scenario, set:
::SCC_EventStatus =0
::SCC_EventNumber = 0
*At the start of the first event, set:
::SCC_EventStatus = 1
::SCC_EventNumber = 1
*At the end of the first event, set:
::SCC_EventStatus = 0
*At the start of the second event, set:
::SCC_EventStatus = 1
::SCC_EventNumber = 2
*At the end of the second event, set:
::SCC_EventStatus = 0

Continue this pattern; at end of final event, set:
::SCC_EventStatus = 0

====Default miniSim Scenario Measures Sample Report====
The following is an example report for 4 events. Note the remaining events present in the report are all zeroes or -1.00.

[[File:default_measures_report.png|400px]]

===="Alternate" Scenario Event Definition aka Using Logtreams====
'''NOTE: This method is the more typical/standard method for defining events.'''

Defining an event is key to partitioning simulator data into useful sections. Processing these sections is the essence of '''data reduction.'''

These useful sections are partitioned using logstreams and are generally called '''Events''':
*A logstream is a data marker present in the DAQ file
:there are 10 logstreams
:use logstreams to indicate when things happen '''in the data:'''
:at the start of an event; i.e.,
::grab all data where logstream 1 = 100 (example value)
:during a sub-section of an event
:at the end of an event (typically clears to 0)

Logstreams help separate/filter data;
*SDLP is not useful during emergency maneuver events

Logstreams can be useful to debug events;
:marking in the data when triggers fire
:ensuring event counters work; these are typically sequential, so any logstream deviation identifies a problem

*How to define a Scenario Event:

Set logstream values at scenario event start
:during and at scenario event end, set or clear logstream values:
For example:
::logstream 1 for event ID
::logstream 2 for sequencing the event (during/within event)
::logstream 3 for restart number, etc.

*Requires data reduction to fully process drive data
*Does '''not''' support default measures
:unless those measures are used in parallel with the logstream method

*The use of logstreams allows a scenario author to encode event and environment information into the scenario and as a result, into the simulator data stream.

====Example Alternate Scenario Event====
This section contains an example of a scenario that uses logstream 1 to define an event and environmental context.

In the following example, logstream 1 (LS1) is used to:
#define the scenario start, which is also in this example the event start. NOTE: This is not typical.
#when the driver is 805f from the intersection halt line, set a value into LS1
#when the driver is 500f from the intersection halt line, set a '''new value''' into LS1 NOTE: This could also use a different LS than the one used to define your event, i.e., 1
#when the driver activates a roadpad trigger to reset a force velocity (FV) on a lead vehicle

[[File:event_def_LS.png|400px]]

In the following event definition, an expression trigger is used to set a logstream value and execute two additional actions pertaining to the event.

[[File:event_ET_LS3.png|400px]]

====How to Export Data from A DAQ file using ISAT====
ISAT can display and export DAQ data. NOTE: This is 'raw data', not previously processed. This method can be used to test scenarios, confirm or identify data issues.

TBC: example export here

=Terminology & Documentation=
This section contains terminology and references to related documentation.

'''Action''' - the basic scenario element; the basis for creating scenarios. Actions may be executed on scenario elements (dynamic or static), create or remove elements, or the environment (time of day, visibility) or the simulated cab instrument panel.

'''ADO''' - Autonomous Dynamic Object; self-controlling to a degree.

'''Cell''' - Data elements that are recorded to during a drive; some cells may be used by the scenario author. Custom cells may be added to miniSim.

'''Event''' - anything significant that happens during a drive where the driver condition or response is desired to be identified in the drive data. Can be isolated from general driving through default measures or logstreams.

'''ISAT''' - Interactive Scenario Authoring Toolkit; used to create scenario files for use on the NADS facility or miniSim simulators.

'''ISC''' - ISAT script file.

'''Scenario''' - The simulation experience during a drive; also known as a scenario file, which contains all instructions to the elements within a simulator drive.

'''SDLP''' - Standard deviation lane position

'''SOL''' - Scenario Object Library; objects that are available to ISAT during scenario authoring must be present within the sol2.txt or an auxiliary sol2 (sol2_aux.xxx.txt) file.

'''Trigger''' - A scenario element that contains actions to execute during simulation. All triggers share the same actions, but execution depends on the trigger type.

'''TTA''' - Time to arrival.

'''TTC''' - Time to collision.

=Reporting ISAT & Scenario Issues=
*How to report ISAT & scenario issues:

When reporting issues with scenarios it is helpful to provide as much information as possible.

This often includes scenarios (including any external reference files) and the .LRI file used by the scenarios, screenshots or video that demonstrate the issue being reported and relevant DAQ files. It can be very helpful to include coordinate information with the screenshot or video.

The .BLI file is created from the .LRI and is much larger than the LRI so it may be more convenient to send the LRI file. NADS staff can re-create the BLI file from the LRI.

Some graphics anomalies may be issues with the tile model and not a scenario or miniSim problem. These include:
#white block shapes in the environment
#gaps or missing geometry; i.e., holes
#improper lighting (dark features present during the day)

If these issues happen on a custom roadmap/database world, please include the TMT .mos file as well so NADS can re-construct your environment.

==How to contact the NADS miniSim team:==

email [mailto:miniSim-Support@uiowa.edu minisim support]

[mailto:andrew-veit@uiowa.edu Andrew Veit]
Director of NADS miniSim

[mailto:joseph-meidlinger@uiowa.edu Joseph Meidlinger]
Program Coordinator NADS miniSim

[mailto:oscar-hernandezmurcia@uiowa.edu Oscar Hernandez Murcia]
MiniSim Application Programmer/Analyst

[mailto:chris-schwarz@uiowa.edu Chris Schwarz]
Data Reduction & Vehicle Dynamics

[mailto:shawn-allen@uiowa.edu Shawn Allen]
TMT, Modelling & Support

==How to check what BLI file is used by a scenario==

#You can edit the scenario in a text editor; near the top of the file will be a line starting with '''LriFile''' followed by the name of the BLI file in double quotes.
#You can use '''grep''' to inventory single or multiple scenarios:
:grep bli <scenario file/s>
:A partial listing is shown in the example below. NOTE: The files shown will likely be different on your PC:
C:\NADS\Isat\data\training.demo_scn>grep bli *.scn
Demo_Expression_Lead_Vehicle_Variables.scn: LriFile "simple_rural.bli"
Demo_Expression_Trigger_to_Lead_Vehicle.scn: LriFile "simple_rural.bli"
Demo_HUDD.scn: LriFile "simple_rural.bli"
ISAT-Samples-Avoid.scn: LriFile "esc_dry_05.bli"
ISAT-Samples-Right-Incursion.scn: LriFile "esc_dry_05.bli"
ISAT-Samples-TrafficLightTest.scn: LriFile "simple_city1.bli"
ISAT-Samples-TrafficLightTestB.scn: LriFile "simple_city1.bli"
ISAT-Samples-YellowLightDilemmaB.scn: LriFile "simple_city1.bli"
KBW_TEST.scn: LriFile "simple_rural.bli"
KBW_TESTB.scn: LriFile "simple_rural.bli"
demo.createADO_and_trigger.scn: LriFile "simple_city1.bli"
demo.creation_radius1.scn: LriFile "simple_city2.bli"
demo_FV_sum_of_Sines.scn: LriFile "simple_city2.bli"
demo_LV_Decelerate.scn: LriFile "simple_city2.bli"
demo_LV_cut_in.scn: LriFile "esc_dry_05.bli"
demo_MG.scn: LriFile "simple_city2.bli"
demo_TM1.scn: LriFile "simple_city2.bli"
demo_TT_null.scn: LriFile "simple_city2.bli"
demo_actions_text.scn: LriFile "simple_city2.bli"
demo_alt_data_measures.scn: LriFile "simple_city2.bli"
demo_audio_virtual_object.scn: LriFile "esc_dry_05.bli"
demo_audio_virtual_object_simple_rural.scn: LriFile "simple_rural.bli"
demo_auto_cloud1.scn: LriFile "simple_city2.bli"
demo_coneISC1.scn: LriFile "simple_city2.bli"
demo_dddo.scn: LriFile "simple_city1.bli"
demo_dddo_B.scn: LriFile "simple_city1.bli"
demo_forXRef_traffic.scn: LriFile "simple_city1.bli"
demo_force_vel_01.scn: LriFile "simple_city1.bli"
demo_groupImport.scn: LriFile "simple_city2.bli"

==How to configure miniSim for screenshots to include coordinates==
You can enable coordinate display on miniSim by changing the focus to the main display. #Move the cursor until it is positioned in the main display area, then LMB. When successful the main display will appear to "blink".

Press the keyboard n key twice. This will cause coordinate information to display in the lower left corner of the main display.

[[File:miniSim_show_coords.png|400px]]

The n key is a toggle; to disable coordinates, press it twice (2x) again. '''NOTE:''' the cursor focus must be in the main display in order for this to work.

=Additional Resources=
[[:File:ISAT_Quick_Start.pdf|ISAT Quick Start Guide]]

[[ISAT_Demonstration_Scenarios|Demonstration Scenarios]]

[[:File:Create_Use_Custom_Cells.pdf|Create and Use Custom Cells on MiniSim]]

[[:File:Function_ReadCell_20180824.pdf|ReadCell function]]

[[:File:TrafficManager_Ch12.NADS.Internal_ISAT_UsersGuide.pdf|Traffic Manager]]

=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 [[ISAT_Reference_Manual_Table_of_Contents#ISAT_Reference_Manual|reference manual for ISAT can be found here.]]

ISAT User Guide Table of Contents

2023-08-29T20:35:41Z

Shawn Allen: /* Triggers */

== 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
*CTL-<some other key> Press and hold the Ctrl and then press <some other key>. Most typically used for copy (CTRL-C) or paste (CTRL-V).
*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 and modify for use in your own scenarios as needed.

== <span style="color:#FF0000"> '''Known Issues'''</span>==

Added 2022.07.01 '''Relative Creation''' does not currently work for ADOs on miniSim.

'''Expression clarification'''

Increment and decrement operators (++, --) are not considered expressions by behaviors. They should not be flagged as expressions when used in the Value field of a Set Variable action.

Added 2019.11.07 '''File reset issue'''

ISAT has a long-standing bug which can reset your static object options when your scenario file is saved to disk.

'''It is strongly recommended that you use external reference scenario files to avoid this. '''ISAT does not reset static object options in the xref file.

Added 2021.12.29 Expression Triggers and Values

'''Using Values in Expression Triggers'''

To ensure proper execution of expression triggers, it is recommended that the values used include the desired range by decreasing the lower threshold or increasing the upper threshold '''instead of using the exact value.'''

For example, to process values in a range (7031 - 7040):

[[File:2021-12-29_12h38_09.png|400px]]

'''Note: remember that negative values must be calculated since the expression parser does not parse negative values otherwise.'''

For example, to properly parse a specific transmission gear (Park):
'''ReadCell('CFS_Auto_Transmission_Mode', 1) = ( 0 - 2 )'''

=='''ISAT Overview & Interface Basics'''==
This section contains information about ISAT and the ISAT interface.

===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 <span style="color:#FF0000">'''not an object editor'''</span> 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.
[[File:miniSim_scenario_compnents.png|center|640px]]

*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.

[[File:anatomy_of_a_scenario.png|center|400px]]

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

[[File:scenario_as_text.png|center|640px]]

This diagram shows the same scenario in (left to right) 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, <u>always</u> check your edits in ISAT!'''
*Copy/Paste - delete paths from elements when the BLI is different between your source & destination BLI files. The following scenario elements contain paths:
::ADO (with a path specified)
:: Any roadpad trigger (roadpad, Time to Arrival, Follow)

'''NOTE: A Traffic Source is not a portable element but it can be re-created in ISAT or integrated into a new scenario by copying the element from the source scenario then using a text editor to paste it into the destination scenario'''

'''How can I find information in multiple files easily?'''

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.

What if you don't know what to look for? How do 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
[[File:action_overview.png|400px||border|caption]]

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)

==='''Adding an action to a trigger'''===

The following example uses a Time Trigger; remember that '''all triggers share the same actions'''.

To add an action to a trigger you can double-click on the trigger, navigate to the '''Actions''' panel, and click on New to create a new action.

[[File:2022-11-30_12h47_23.png|400px]]

The possible actions are listed under the '''Action Type''' drop-down menu.

[[File:2022-11-30_12h47_44.png|400px]]

Actions are arranged in a 'stack' and are processed from top to bottom. If you use multiple actions you should enable the '''sequential flag''' to ensure each action is executed in sequence. Without the sequential flag, actions will be processed as fast as the simulator behaviors can execute.

[[File:2022-11-30_12h52_58.png|400px]]

Actions may be re-ordered in the stack using the '''arrows''' located near the action stack list.

=='''ISAT Modes of Operation'''==
[[File:ISAT_modes_of_operation.png|400px]]

*Edit
*Rehearsal
*DAQ playback
*Monitor '''Currently not available'''

==='''Edit & Rehearsal Modes'''===

*Edit - this is where scenario authors will spend the most time.
::Creation or modification of scenario
::Link to or import portions of other scenario elements

[[File:mode_edit.png|400px]]

*Rehearsal
::Debug & test scenario
::Simulates scenario using Behaviors and Vehicle Dynamics
::Displays error messages from behaviors

[[File:mode_rehearsal.png|400px]]

'''NOTE:''' Rehearsal mode <span style="color:#FF0000">simulates </span>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

[[File:mode_playback.png|400px]]

==='''miniSim Scenario Components'''===

The following diagram shows an overview of scenario related components of the NADS miniSim and how these components work together.

[[File:miniSim_scenario_components_wDAQ.png|400px]]

=='''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.

[[File:isat_workspace_general.png|400px]]

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)
[[File:isat_status_bar_overview.png|400px]]

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.

[[File:isat_user_prefs_status_bar_settings.png|400px]]

====ISAT Iconography====
ISAT provides graphic hints for triggers placed in scenario that can be useful when editing or maintaining scenarios.

The general format is a border enclosing miniature icons of the trigger and first action contained in that trigger. Additional information representing one or many actions is also shown.

[[File:hints1.png|400px]]

ISAT will list all trigger actions when a trigger is selected, but these hints provide a way to quickly identify what actions have been authored.

[[File:hint2.png|400px]]

*A Roadpad trigger, one action: '''Traffic Light Action'''
*B Roadpad trigger, multiple actions, first action is '''Remove Element'''
*C Roadpad trigger, multiple actions, first action is '''Set Dial'''
*D Roadpad trigger, constrained to road (lane), no actions - this is an empty trigger
*E Roadpad trigger, multiple actions, first action is '''Log Data'''
*F Global Time Trigger, single action: '''Set Dial'''

[[File:handle.png|400px]]

The element handle is the red dot visible in most of the triggers.
The handle can be dragged into position, and the trigger will follow the handle

Drag the trigger off the handle to offset it's location from the handle

==='''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.

[[File:object_types_isat.png|400px]]

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
::*Traffic Source

:'''NOTE:''' Virtual objects are defined in the scenario, not in the SOL2.
[[File:object_types_world.png|400px]]

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.
::NOTE: 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.

==='''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:
#Follow a path using kinematics
#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:
#coupled
#relative trajectory
#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'''===
Traffic signals are objects with special operation and function; they are coupled to intersections and routes of travel through intersections to control traffic flow similiar to their function in the real world. Traffic signals are part of the source tile model and may not be re-positioned or physically altered by scenario except for their visual signal state appearance; i.e., red, green or yellow signals.

To control intersection traffic signals use Edit >> Traffic Light ManagerTraffic signals use a Signal State Table (SST) to control which signal states are active and when. Each intersection with traffic signals will have an associated SST.

[[File:traffic_light_state_manager.png|400px]]

The above diagram shows an intersection in the workspace to the right, and the traffic signal state table for that intersection on the left. At this point additional states (for signal condition) can be added by clicking the '''Add state button'''.

[[File:traffic_signal_state_table2.png|400px]]

The above diagram shows two states defined for the intersection, represented by the two columns of state condition.

Continue adding states until the desired signal cycle has been defined. Generally this consists of red, green or yellow states.

NOTE: There is currently no way to automatically author a series of traffic light signals

To author traffic signal lights in sequence or on a route, the scenario author has to manage the signal states

[[File:traffic_signal_state_duration.png|400px]]

To edit the signal state duration RMB on the duration field header and choosing '''Edit state duration''' on the context menu. Enter the desired value then click OK.

====Traffic Signal Types====
The ISAT status bar reports Traffic Signal Type name. There are two signal types:
#Standard signal - IDs may have no identifying information
:Valid signal states: Red, Yellow, Green, Flashing Red, Flashing Yellow, OFF
#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

[[File:traffic_light_extended_type_name_normal.png|400px]]
: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.

[[File:traffic_light_extended_type_name.png|400px]]

===Changing Signal States in Scenario===
Traffic signals are controlled in scenario by using a Traffic Signal Action to change the SST.

'''NOTE:''' The Traffic Signal Action works by changing the SST, '''not by changing the traffic signal.''' This is a subtle but important difference.

Setting a signal to an undefined state effectively does nothing to the traffic signal.

[[File:traffic_light_state_table.png|400px]]

The above diagram shows a fully populated SST, with one signal row highlighted in red, and one state column highlighted in green. The associated intersection corridor is highlighted, showing the signal controls a dedicated left turn.

During simulation, the initial signal state is defined by the left column. As the simulation proceeds, the signal state changes according to the duration states defined across the state table, proceeding left to right and then wrapping around to the beginning after the last defined state. Each traffic signal appearance changes according to the configuration of the SST.

As a driver approaches this intersection, assume the signal state is in the column left of the highlighted column ('''R'''ed), and the desired action is to change the signal to green.

The action used to change a traffic signal state is the '''Traffic Light Action'''.
Using a traffic light action requires the specification of a signal state, the traffic signal to affect, and a duration.

[[File:traffic_signal_action1.png|400px]]

In the above diagram the scenario author has specified the desired state as '''Green''' as shown in the action dialog.

However, referring back to the previous state table diagram, there is no such state present in the SST. That means this particular action will fail, and the traffic signal will not change as the driver approaches the intersection - because the action does not create a new signal state, it works by advancing the state table condition (column) to the specified condition. If the condition is not present in the SST then nothing will appear to happen.

In this example, the action should be edited to use the correct signal state '''Left Turn Green''', which is present in the SST.

'''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

[[File:known_issue_traffic_light_action.png|400px]]

'''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.

[[File:known_issue_traffic_light_action_workaround.png|400px]]

====Change A Traffic Light Using Scenario Action====
To change a traffic signal, use the Set Dial >> Traffic Light action.
'''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

[[File:traffic_light_state_table.png|400px]]

This diagram shows a fully populated traffic signal state change for an intersection.

*Static object traffic lights
:These are objects, not true traffic signals and so they are not controlled with the Traffic Light manager.

==='''Traffic Source'''===
A traffic source is a coordinator used to create traffic at specific locations in the road map (unlike the Traffic Manager). This is useful for creating ambient traffic. Traffic Sources creates ADOs or DDOs at random or user-specified intervals.

Elements created using a Traffic Source will be created at the locations specified by the user. If traffic is specified at multiple locations the actual location for each creation will be determined randomly during simulation.

'''Note:''' Using the Relative Creation flag on ADOs created by the traffic source will not create traffic at the specified location on the map, but use the information in the Relative Creation fields to populate traffic in the scene during simulation.

This method allows for more flexibility but care must be taken not to create so many ADOs that miniSim is unable to make frame rate. Too many ADOs will cause the scene to jump and 'jitter' and it will feel slower than normal.

==='''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 ISAT scenario rehearsal

===Custom (icon) file virtual objects===

[[File:virtual_object_custom_icon_file.png|400px]]

'''Note:''' Some versions of MiniSim_2.3 do not support custom virtual objects. For those installs, if you require this type of functionality, a workaround exists in the form of a 2D model that can be customized (i.e, sprite).

Virtual objects may be customized using graphics files (texture images) to display any desired custom element. This typically requires the use of a bitmap graphic. Various file formats are supported: JPG, BMP, PNG. It is possible some types of these formats may not work - in those cases, try an alternate format.

If image transparency is required and the custom icon does not display during simulation, please email dsri-minisim@uiowa.edu with a description of the issue, your scenario and custom virtual object image file.

Custom icon files must be located within the Nads MiniSim path for resources - at NadsMiniSim_x.x\data\visuals\Models\ModelTx.

===Standard virtual object shapes===
The virtual object shapes include:
# Circle
# Triangle
# Octagon
# Star
# Diamond
# Icon <- this is for custom virtual object graphics
# Rectangle
# Hexagon

The virtual object fill and border color and transparency can be set in the virtual object properties dialog panel.

[[File:virtual_object_std_shape.png|400px]]

====Virtual Object Workaround====

There is a scenario authoring method that can be used to emulate virtual object functionality through the use of a DDO that is coupled to any dynamic scene element, including the External Driver. One model has been created to support this method called "sprite".

'''Note:''' The sprite model is a 2D object present in the scene, and can therefore be occluded by other scene elements during simulation.

[[File:trafsign_sprite.jpg|400px]]

The sprite model is designed as a flat plane that continuously faces the viewer. It contains different sized planes and can be customized through textures.

When authoring your scenario, configure the sprite object to Off unless it should be visible at scenario start. During the scenario you can control the sprite appearance with a setSwitch action.

[[File:sprite_setSwitch_action_021121.png|400px]]

The who to effect should use the name of the DDO placed in your scenario. The switch name will be s_sprite as shown above. Any valid option can be used. An invalid option (greater than 30) will disable the sprite the same as selecting the OFF option.

==='''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'''===
<span style="color:#FF0000">'''All trigger types share the same Action types'''</span>
*IF Then conditional
*Predicate: i.e., the activating agent
:If predicate is TRUE, then do Action(s)
*Road related triggers are categorized by predicate type
:Named element
:Road (lane)
:Nth vehicle on path only

'''What trigger is appropriate?'''
To determine which trigger is most appropriate, consider the task you are trying to accomplish. '''The differences between triggers is their activation methods.'''

'''Global Time Trigger'''
[[File:isat_time_trigger.png|150px]]

Use this trigger when something has to happen at some point in time.

Time triggers are also useful as "placeholder triggers"; used to apply persistent actions to multiple elements with unique settings for each element. Normally a persistent action is the last action possible in a trigger since the persistent action fires continuously. Putting persistent actions into a time trigger allows the scenario author to continue an action stack in the parent trigger if necessary.

Time triggers can be used as a 'stopwatch' - elapsed time, such as ending a drive after 3 minutes by setting the trigger to fire using an Activation Delay of 180s (GTT >> General).

Often used as a placeholder for actions such as initializing variables, displaying text messages to the screen using Set Visual Display Text actions, etc.

'''Note''': A time trigger can have global elapsed time and activation delay of 0, which causes the action stack in the time trigger to activate when that trigger is created.

'''Roadpad Trigger'''
[[File:isat_roadpad_trigger.png|150px]]

Use this trigger when something has to happen at some location in the drive that does not require event timing to be comparable for all participant drivers. For cases where event timing must be comparable among all participant drivers use the Time to Arrival trigger (TTA) instead of a roadpad trigger.

'''Time to Arrival Trigger'''
[[File:isat_time_to_arrival_trigger.png|150px]]

Use this trigger when something has to happen relative to some point in the drive, and also ensure all study drivers experience the same event timing irrespective of driver style (conservative, slow vs. aggressive, fast). Time to arrival (TTA) trigger uses a time calculation from the trigger pad activation to a target location specified in the trigger.

'''Traffic Light Trigger'''
[[File:isat_traffic_light_trigger.png|150px]]

This trigger activates actions when the specified traffic signal state is reached. For example, if the desired action is to create a DDO pedestrian to step into traffic when the traffic signal is yellow, then the Traffic Signal Manager must be used to author the appropriate signal states for the traffic signal.

Typically some other trigger is used to control the traffic signal (ie, to change the signal to Yellow on approach). It is therefore perfectly valid to put the actions within this other trigger rather than relying on the traffic light trigger.

'''Note''': Once a traffic light action has been authored, ISAT may be prone to crashing when accessing that trigger. This problem can be avoided by creating a time trigger and isolating the traffic light action there, allowing the parent trigger to be modified without crashing. Adjustments can be made to the traffic light action time trigger in a text editor, or recreated if it becomes necessary to make adjustments and ISAT continues to crash when trying to make edits.

'''Note:''' The traffic light action does not change the traffic signal state, and it requires a valid state sequence to exist in the signal timing table (Edit >> Traffic Light Manager). The traffic light action '''will not create a signal state''' that does not already exist in the signal timing table.

'''Expression Trigger'''
[[File:isat_expression_trigger.png|150px]]

Use this trigger when something must be monitored, evaluated or calculated such as checking a variable or cell value, velocity of the driver or the state of simulator hardware (steering wheel angle, brake or accelerator pedal position) or distance from the driver to some other object in the scenario.

Multiple expressions can be used within the same expression trigger. In those cases, all expressions must evaluate to True in order for the action stack to execute unless using an '''OR''' operator.

Use the '''OR''' operator - the pipe character "|" if you want to activate the action stack if '''any''' of the expressions evaluates to True.

In the following example, the trigger checks for TrialNumber = 1 and FirstButtonPress variables, and then checks if Aux Button 1 or 0 was pressed:

'''ReadVar('TrialNumber') = 1.0 & ReadVar('FirstButtonPress') = 1.0 & (ReadCell('Auxiliary_Buttons', 0) > 0 | ReadCell('Auxiliary_Buttons',1) > 0)'''

'''Note''': Expressions can also be embedded into some other triggers, most notably the Set Dial >> ADO >> Forced Velocity action often used in Roadpad triggers.

'''Follow Trigger'''
[[File:isat_follow_trigger.png|150px]]

Use this trigger when something has to happen based on one ADO position relative to another scenario element (including the XD). The follow trigger requires a leader and a follower to be specified; when this condition is met, the trigger action stack activates.

'''Note''': Both leader and follower must be positioned on the follow trigger roadpad to satisfy the follow parameters.

'''Geometric Position'''
[[File:isat_geometric_position_trigger.png|150px]]

This trigger is most useful to perform actions for off-road actors such as walkers. The trigger predicate is limited to Name or Type and requires a geometric position to be defined.

A more limited version of the geometric position trigger can be implemented with a Global Time Trigger that contains a Creation Radius. Placing the creation radius defines the area where the trigger may be activate.

===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

[[File:Screenshot (208).png|800px]]

'''Note:''' The highlighted lane shows which lane is the '''activating lane'''. Other lane/s will not activate the trigger action stack.

===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

[[File:TTA.png|400px]]

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===

[[File:other_triggers.png|400px]]

*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===

Execute actions if input expression evaluates to TRUE; the expression is specified on the trigger Predicate tab.

====Syntax====
Expression triggers support a simple language syntax with operators and functions.
The syntax is infix notation; i.e. a + b, not a b +.

Note: It is not generally possible to embed one function call inside another:
cos(sin(x)) is therefore an invalid expression. ISAT will report invalid expressions during rehearsal of a scenario. Invalid expressions are not supported and will not operate as written during simulation.

'''Exception:''' Currently it is possible to use the square root function with GetObjDistPow2 as in the following example:

sqrt(GetObjDistPow2('Target_Object_Name'))

Multiple expressions may be combined using the logical AND (&) or OR ("|" pipe character).

Exp1 '''&''' Exp2, Exp1 '''&''' Exp2 '''&''' Exp ''N''

All expressions must be true for the trigger to evaluate to TRUE and execute the action stack.

Exp1 '''|''' Exp2
One of the expressions must be true for the trigger to execute the action stack.

Negative values are not directly supported by the expression parser. To use a negative value, it must be a calculated value such as the following:

'''ReadCell('CFS_Steering_Wheel_Angle',0)<(0-5.0)'''

==== Operators ====
Operators are used to create expressions.

'''String'''
:Used within quotes as a string literal; i.e., 'some string'

Grouping
:Parentheses group elements together; i.e.,
:'''()'''; (a), (a + b)

Multiplication
:'''*'''; a * b

Division
:'''/'''; a / b

Addition
:'''+'''; a + b

Subtraction
:'''-'''; a - b

Note: negative values must be expressed with a subtraction operation:
(0 - 5), not -5 (invalid)

Greater than
:'''>'''; a > b

Less than
:'''<'''; a < b

Logical And
:'''&'''; a & b

Both a and b, otherwise returns 0 (FALSE)

Logical Or
:'''|'''; a | b

a or b returns 1 (TRUE)

====Expression Functions ====
Functions are used with operators to create expressions.

Function: '''sin'''
:sin -sine

Syntax
:sin(float x)

Description
:The sin() function returns the sine of x, where x is given in radians.

Return Value
:The sin() function returns a value between -1 and 1.

Function: '''cos'''
:cos –cosine

Syntax
:cos(float x)

Description
:The cos() function returns the cosine of x, where x is given in radians.

Return Value
:The cos() function returns a value between -1 and 1.

Function: '''ReadCell'''
:ReadCell()

Read a Cell value.

Syntax
:ReadCell(string Name, int Cell Array index)

Description
:ReadCell returns the value of a given cell (a cell is the current instance of a variable that will be maybe written to a daq file).

Index specifies a 0 based index into the array. Since most cells are single element arrays, a value 0 indicates the first element.

Cells valid for the ReadCell function are defined within the cell collect file NadsMiniSim.cec located in the miniSim_x.x\data folder.
The ReadCell function operates on shared memory during simulation, it does not read cell data from the DAQ file.

Cells that are defined may be written to the DAQ; the collect file specifies which cells are saved into the DAQ and what frequency to use for the write operation.
The NadsMiniSimCollect.general.txt file is located in the miniSim_x.x\data folder.

Available Cells:
Any cell that has been defined in the .cec file. For example:

:'''LogStreams''': Array of 5 floats. Logstreams are a set of values the scenario author can write to through “write to logstream” actions.
:'''AccelPedalPos''': Single Value. The current position of the accelerator pedal
:'''BrakePedalForce''': Single Value. The current force on the brake pedal in pounds
:'''SteeringWheelAngle''': Single Value. The current rotation of the steering wheel
:'''CruiseControl''': Single Value. The current cruise control position. (values are cab/platform specific)
:'''TurnSignal''': Single Value. The current position of the turn signal (values are cab/platform specific)
:'''OvVel''': Single Value. The participant’s current speed in miles per hour
:'''OvLaneDev''': Single Value. The participant’s lane deviation in feet.
:'''OvHeadwayToLeadVeh''': Single Value. The distance in feet to the first vehicle in front of the participant. -1 if no vehicle can be found.
:'''OvTtcToLeadVeh''': Single Value. The time to collision to the first vehicle ahead of the participant.
:'''Horn''': Single Value. The state of the horn (values are cab/platform specific)
:'''DynObj_Vel''': Array of 20 floats. The speed of a given dynamic object. Dynamic Objects are sorted in terms of distance to driver.
:'''OvVelLocal''': Single Value. The participant’s current speed in miles per hour, using the value local to scenario control

For a complete list of cells and array elements please see the miniSim data dictionary spreadsheet.

Return Value
:Returns the value of the specified cell.

Example
ReadCell(‘LogStreams’,5) > 3

Function: '''CellEquals'''
:Cell Equals, array element, value to compare

Syntax
:CellEquals(string name, int index, float value)

Description
:The Cell Equals function is similar to the ReadCell function, except it adds an additional value to compare against the cell value.

Like ReadCell, name specifies the name of the cell, index specifies the cell array index (use 0 for single value cells).

Available Cells:
:Any cell that is defined in the .cec file.

Return Value
:Units: 1 or 0
:1 if the cell value is equal to the passed in comparison value; otherwise 0

Function: '''GetObjDistPow2'''
:Get object distance squared

Syntax
:GetObjDistPow2(string name)

Description
:GetObjDistPow2 returns the distance squared between the external driver and the dynamic object specified by ‘name’.

Distance squared is used to avoid having to perform an expensive square root calculation every frame.

If the specified object cannot be found, a value larger than 100 million is returned.

Return Value
:Feet; Distance in feet measured from the eye position of the driver to the CG (centroid) of the dynamic object specified.

A very large number is returned if the specified object cannot be found (larger than 100 million)

Example
:GetObjDistPow2(‘OncomingCar1’) < 2500

'''Note:''' To get an actual distance, multiply by the square root (sqrt())
: sqrt(GetObjDistPow2('Target_Obj'))

Function: '''GetObjTtcToOv'''
:Get Object Time To Collision to Own Vehicle

Syntax
:GetObjTtcToOv(string object name)

Description
:GetObjTtcToOv gets the time to collision from the dynamic object specified by the name parameter, to the own vehicle.

Return Value
:Unit: Seconds
:Time (seconds) to collision from the own vehicle to the dynamic object specified by the name parameter.
:0 is returned if the object specified cannot be found.

Function: '''GetObjVel'''
:Get Object Velocity

Syntax
:GetObjVel(string object name)

Description
:GetObjVel gets the velocity in meters per second of the first dynamic object with the name specified by the ‘name’ argument.

Return Value
:Unit: Meters per second
:The speed of the specified dynamic object; 0 if no object is found

'''Note:''' Multiply by 2.23694 for miles per hour.

Example
:GetObjVel(‘PullOutVeh’) > 15.4

Function: '''Rand'''
:Random

Syntax
:Rand(int value)
:Rand(string name)
:Rand(string name, string type, double parameter, double parameter)
:Rand(string name, string type, int parameter, int parameter)

Description
:Rand returns a random value specified by the name of the generator, the type of distribution and its parameters.

If the user does not specify the name of the generator and only specifies a number as the only parameter, the Rand function will use a default random number generator to produce random numbers.

If the user only enters the name of a user created random number generator, the random number generator will produce a value between 0 and 1.
If a name of generator is supplied that has not been created, the Rand function will display an error message in the ISAT debug window and return 0 (during scenario rehearsal).

The rand function supports multiple types of distributions that can be used to generate a random number.

Types of Distributions:
:normal: Normal Distribution(mean, standard deviation). The normal distribution generates random numbers near the mean with a specific standard deviation.
:gamma: Gamma Distribution(alpha, beta). The gamma distribution generates a random value that models waiting times for the Poisson process.
:uniformInt: Uniform Integer Distribution(min, max). The uniform integer distribution generates a random integer number between the lower and upper bounds.
:uniform: Uniform Real Distribution(min, max). The uniform real distribution generates a random floating point number between the lower and upper bounds.

The values stated in the parenthesis above are the parameters for each distribution in order. If the incorrect number of parameters are entered or if they are entered incorrectly, the debug window in ISAT will display an error message and the rand function will return 0 (during scenario rehearsal).

If the distribution is entered incorrectly, the debug window will also display an error message.

Return Value
:A random value from 0 to 1 if the type of distribution is not specified.

If the type of distribution is specified, returns a random value determined from the type of distribution and the given parameters.

Example
:Rand(‘myRandGenerator’,’uniformInt’,1,10)
:This example returns a random integer value from 1 to 10.

Rand(5) or Rand(‘myRandGenerator’)
:These examples return a random value between 0 and 1.

Function: '''sqrt'''
Square root

Syntax:
:sqrt(parameter)

Return Value:
: return the square root of the specified parameter.
: parameter can be another function, such as GetObjDistPow2()

Function: '''ReadVar'''
:Read a variable

Syntax:
:ReadVar(string Name)

Return Value:
:Returns the string value of variable specified in <variable_name>

===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.

=='''Audio Components'''==
The components of the Audio sub-system includes configuration and data files installed into the NadsMiniSim_x.xx\data\sound\DefaultCabSound\Instructs folder.

[[File:audio_components.png|400px]]

The audio engine contains multiple channels and has a theoretical limit of 512 simultaneous sounds.

NOTE: Not all .wav files are compatible with the Audio Engine.

=Scenario World Objects=
Scenario world objects are defined in the tile model source. They are not added by the scenario author since they are objects already present in the roadmap/BLI.

[[File:object_types_world.png|400px]]

Typically, but not always, these objects can be authored in ISAT. However, some scenario world objects have no options - these cannot be selected in ISAT; therefore such objects cannot be authored.

Removal of world objects requires editing the source tile model using a 3D application. In some cases an alternate tile model is available identical to the original but without objects.

Contact NADS if removal of a world object is needed.

Other scenario world objects, such as Traffic Signals, are specialized function objects that can be authored. Traffic signals are authored using the Traffic Light Manager: Edit >> Traffic Light Manager.

=Troubleshooting Scenario Objects That Reset=

== Scenario World Objects ==
Scenario world objects are already present when you create a new scenario - they are not added by the scenario author. These objects may be visible in miniSim but not in ISAT, or they may be visible in ISAT and seem to be controllable, but the objects 'reset' to their defaults when viewed on miniSim.

[[File:2019-10-23_16h18_47.png|700px]]

The objects which 'reset' are a symptom of settings in the TMT that are not configured to allow scenario authoring of objects.

[[File:2019-10-23_16h18_52.png|700px]]

When objects appear to 'reset' or if you can edit an object in ISAT but don't see your changes in miniSim, correct the problem by resolving controllability in the TMT settings: https://www.screencast.com/t/ZH5Dh178.

=Scenario Coordinate Types=
There are two types of coordinates used in scenarios. The first is roadway coordinates. These coordinates are contextual (tied to a specific road or intersection and position) and are used for ADO objects and roadpad paths in general.

After a roadway coordinate has been generated, it is not updated unless the scenario author makes changes to the start, end or location of the entire path or pad.

Roadway coordinate are the reason it is not possible to change a roadmap using the TMT and expect a previously authored scenario to work on the altered roadmap. If the length or location of a road changes, the path/pad will update to the extent possible.

If the road has been eliminated and no longer exists in the roadmap/BLI, ISAT will report an error and not open the scenario file.

A. Field breakdown:
RoadPos keyword <name of road:lane:position on road:path length>

Name "Ado1"
RoadPos "r1_-6600_4620:0:5737.06:0.00"
Path "R:r1_-6600_4620:0[5736.06:5873.83]"

[[File:isat_coordinate_types.png|400px]]

B.
Name "VirtObj"
Option 2
Position -6.8375599E+002 5.6331237E+003 0.0000000E+000

The second type is world coordinates, which are Cartesian coordinates with X increasing to the right, Y increasing forward, and Z increasing up.

='''Scenario Authoring'''=
Scenario authoring is the creation, editing and testing of everything that happens during a simulation drive.

==Cell Operations: Best Practice==
Reading and writing to cells is a computationally expensive process. Best practice is to centralize all the reads/write to one place so that it’s only done once per cell.

Once a cell is read, the value is copied to a variable and only the variable is used throughout all the triggers that need it.

The same process applies to writing to cells. Use of variables can reduce the Cell Operations overhead greatly.

==Before You Begin==
Before beginning a scenario, it is necessary to understand the following requirements:

=== Drive Requirements===
How long is the drive?
What type of roadway?
Are there any specialized road elements (intersections, interchanges, freeway ramps)?
Are there any environmental requirements (should the simulation replicate a real world location, or is a generic environment acceptable)?
Is there a particular roadway configuration that is needed (long straight rural road vs. typical urban environment with intersections, signals, etc)?

=== Traffic Requirements ===
What types of traffic will be needed?
Will ambient traffic interact with the external driver?
What types of interaction will be required (traffic cloud, lead vehicle, follow vehicle)?

=== Events ===
The purpose of an event is to present a situation to the external driver. In order for the simulation to produce meaningful data, it is critical that events unfold for each driver in a comparable way. Therefore, each event must be designed with this repeatability in mind.

'''NOTE:''' one of the most variable scenario elements is the driving style of each external driver: how conservative or aggressive they drive, velocities throughout the scenario, how comfortable the driver is travelling with simulated vehicles, etc.

Repeatability often includes static elements (each driver encounters scenario elements in the same location) or in cases where the driver performance is taken into account, accommodation of the driver dynamic (velocity, lane position) through the use of time to arrival triggers (TTA) or follow triggers. A TTA trigger will fire based on time to a target location - thus a driver travelling at 45mph or a driver travelling at 55mph can both experience the same action relative to that target location, irrespective of the different driver velocities.

==Beginning A Scenario==
All scenarios designed to be driven require a start location - the place where the driver will be located when the simulated drive begins.

To insert a start location into a scenario:

:Insert >> External Driver >> LMB on road, intersection or terrain object

[[File:isat_initial_position.png|400px]]

'''NOTE:''' scenarios that only contain data and are not intended to be driven - for example, signs or traffic that are used as external reference files do not require a start location, since that will be defined within the parent scenario.

==Initial Conditions==
Initial conditions define how the simulated scene is configured: will the drive occur during daylight or night time conditions? Will the ownship (external driver vehicle) have headlights enabled? What type of vehicle will it be? Will there be objects or traffic visible to the driver?
These form the initial conditions of the simulation experience. Additional initial conditions would include initialization of variables or establishing networked communication as needed by the scenario.

[[File:isat_initial_conditions_miniSim.png|400px]]

By default ISAT sets the initial condition '''Time of Day''' to 12:00 noon. The time of day is controlled from the Initial Conditions dialog:

Edit >> Initial Conditions

[[File:isat_initial_conditions_scenario.png|400px]]

==Scenario Authoring: Actions==
Actions are the scenario elements that make things happen during simulation. Actions do specific things, like display a text message on screen for the driver, create a scenario element, change the velocity of simulated traffic, change a traffic signal, etc.

[[File:trigger_action_panels.png|400px]]

The diagram above shows the action panel for left to right: an expression trigger, a roadpad trigger and a global time trigger showing different panels based on the actions present in each trigger.

'''NOTE:'''Actions can be created, edited or removed from the '''Actions panel''' of '''any trigger'''.

'''NOTE:''' The Actions panel changes based on the action type created.
When multiple actions have been defined, control the sequence of actions by changing the action order in the list using the up or down arrows next to the list.

[[File:action_panel_overview.png|400px]]

If multiple actions need to happen in a specific order, set the order using the arrows and then flag the action list as '''sequential'''. This instructs behaviors to process the actions in the list order.

Using a delay for any action will pause processing of the '''following actions'''; the action happens first, then the delay is applied.

===Scenario Authoring: Action Types===
There are two types of actions:
# Instantaneous - the action takes up to one frame to complete, i.e.:
:set target velocity
:write to cell
# Persistent
<span style="color:red">'''*Persistent actions do not end'''</span>, or take multiple frames to complete:
:Forced lane offset
:Forced velocity
:Maintain Gap

==='''Actions'''===
*The "Who to Affect" field defines what is affected by the action
:Instigator set: who activated the trigger
:Name: one or more named elements
:Type: Apply changes to all objects matching the specified type
:Relative: Position relative to the trigger location

*Sequential
:Actions to execute sequentially, one after the other
:Specify delay between actions
:: Action executes, then delay

:Some actions are persistent and never "finish"

===Scenario example: display text & roadpad trigger to stop the drive===
This scenario is very simple and contains a global time trigger (GTT) that tells the driver what to do. After the driver travels along the roadway, a roadpad trigger (RPT) is used to tell the driver to stop driving. The same RPT also creates an expression trigger to terminate the drive.

TBC example scenario file

Because the external driver is not under control except by instructions, it's possible they might ignore the halt message and continue driving. A second failsafe RPT then terminates the drive.

==='''Actions: Button vs. Dial'''===
*Dial changes a setting
*Button: always runs in a single frame
:-"immediate" change. Typically buttons have less control than a '''Set Dial''' action

==='''ADO Actions'''===
[[File:ado_action_types_button_vs_dial.png|400px]]

==='''DDO Actions'''===
[[File:ddo_set_dial.png|400px]]

==='''External Driver Actions'''===
External driver behavior can be influenced by reinforcing scenario actions through audible speeding alerts, on-screen text instructions and messages or audio instructions.

Driving behavior can be influenced with situational elements
:Car in the drivers blind spot
:Lead vehicle
:Aggressive following vehicle
:Temporary lane closure
:lane specific instructions

Scenarios should '''not rely on specific driver actions to be successful'''
:to the extent possible; sometimes you do need the driver to respond/behave in a controlled manner.
:A work zone blocking one lane typically will require a roadpad placed upstream from the work zone to shift traffic into the correct lane

'''NOTE:''' Controlling driver actions should be an experimental design consideration.

==='''Special Actions'''===
These actions need special handling:
*Reset or "toggle":
:Audio
:Display Text

:'''Ado'''
::Audio State
::Forced Velocity
::Maintain Gap
::Visual State

*If using these persistent actions, place them at the '''end''' of an action sequence (because no action following these will execute):
:Forced Lane Offset
:Forced Velocity
:Maintain Gap
:Visual State

*Note: If the Visual State action contains a duration then it will be handled as a normal action, with subsequent actions firing after it. However, if there is no duration supplied with the Visual State action it behaves like a persistent action, and nothing following it in the Action stack will ever fire.

[[File:multiple_simultaneous_actions.png|400px]]

The diagram above shows how one parent trigger can be used to create multiple simultaneous triggers

*How to activate multiple unique force velocity (FV) or maintain gap (MG) actions:
#create the needed triggers from a general parent trigger, 1 per action
#put common actions into the parent trigger
::reset FV
::reset MG

==Scenario Authoring How To==
This section contains simple examples for various typical scenario situations.

===How do I specify an event?===
First, determine which method is best for you - the default measures (limited measures, 20 events max) or logstreams (all simulation data, no event maximum).

Regardless of method, you specify an event by identifying areas of significance in the drive and marking them so the data within the event region can be processed. Any trigger combination that can specify event start and event end may be used.

[[File:2022-07-01_11h21_52.png|400px]]

===How to know Which Coordinator or Trigger I need?===
The answer to this question lies in the type of information needed for an event:

*Time
:global time trigger
:or an expression trigger that calculates time
*Position or Location
:roadpad trigger
::or a time to arrival (TTA) trigger
::or an expression trigger that calculates distance
*Calculation
:Expression trigger

===How to Instruct the External Driver===

Instructions to the external driver can be accomplished by three main methods:
# Instruct the driver using experimental protocol (instructional or briefing presentation)
# Information messages displayed on screen: '''Action: ''set visual display text'' '''
# Information messages delivered as audio messages: '''Action: ''write to cell > SCC_Audio_Trigger ><audio ID>'' '''

===How to Add Traffic in the Scene ===

Generating traffic will happen in one of 5 ways:
# Created explicitly by inserting ADO, or copy/paste existing ADOs
# Created with a script
# Via a Create action inside a trigger, or placing scripted traffic inside a create action within a trigger
# From a '''Traffic Source'''*
# From the '''Traffic Manager'''**

Each of these methods has advantages and disadvantages.

==== Create Explicitly ====

The biggest advantage with this method of traffic creation is the high degree of control the scenario author has over:
# location of the created ADO
# Name of the created ADO
# Travel path of the created ADO
# Control when each ADO is created within the scene via Settings >> Creation Radius

The disadvantage is that creating a high volume of traffic will take some work with this method.

==== Created with a Script ====

This method combines the advantages of Creating Explicitly with volume. It is possible to create a large volume of traffic very easily with a script.

Disadvantages of using high volumes of traffic with a script: in the event it becomes necessary for a high degree of control over these ADOs, more is not better because ADOs will adapt to road conditions under their own power, unless the default ADO settings have been modified:
'''lane changes, including lane changes to accommodate freeway ramps'''
'''velocity adjustments'''

==== Via a Create action inside a trigger ====
Combines the advantages of the previous 2 methods with control over when to activate that traffic using a trigger action.

Disadvantages: Creating too many ADOs at one point in the drive can cause the miniSim to bog down for a few frames. If too many ADOs are present and active in the simulation at one time, this can cause the miniSim to drop frames and run sluggishly. This is highly noticeable and may increase the potential for the External Driver to experience '''simulator sickness.'''

==== From a '''Traffic Source''' ====

Traffic Sources rely on two methods to populate a scene with traffic:
# location specific, with each ADO created for a traffic source being a 'spawn location' for ADOs, or
# location agnostic if the ADO has '''relative creation''' enabled, thus being created relative to the object identified.

In addition to being created relative to a scenario element, ADOs are created relative to the specified scenario element:
# In front of (Longitudinal Distance > 0, where the number is feet offset from the object) , or
# Behind (Longitudinal Distance < 0, where the number is feet offset from the object).

Advantages: Can easily populate traffic into the simulation.

Disadvantages: It is easy to generate more traffic than the simulation can maintain at 60Hz frame rate, thus introducing frame lag with the resulting scene 'stutter' and the increased risk of simulator sickness.

Also, traffic created from a Traffic Source is generic traffic. It is not possible to reliably refer to specific ADOs generated from a traffic source except by using Who To Affect >> Relative (versus referring to a named ADO, i.e. Slow_Moving_Lead_Vehicle). Referring by name to Traffic Source generated ADOs will affect all similarly named ADOs at the same time.

==== From a '''Traffic Manager''' ====

The traffic manager interface is problematic in ISAT versions up to 1.8.5, especially when specifying the set of vehicles to be used for generating traffic.

Advantages: Create generic ambient traffic easily.

Disadvantages: Has the same disadvantages as traffic created via a Traffic Source. Also getting a traffic set working by specifying the vehicles to be used within the set. ISAT versions up to 1.8.5 exhibit instability when setting vehicles in ISAT.

Traffic Manager Set workaround: Borrow a working set from an existing scenario or group. Alternatively use a version of ISAT (1.8.6 +) to create the traffic set. This can be saved as a scenario or group file, which can then be used with ISAT 1.8.x as long as there is no attempt to adjust the vehicle weights within ISAT. The scenario or group file can be edited as text in a text editor, but care must be exercised to avoid introducing errors into the file. ISAT will not read invalid scenario or group files.

Traffic generated by the Traffic Manager is controlled through the use of Input Sets. An input set is a collection of vehicles and weights used to populate the scene during simulation. This is how the scenario author can control the vehicle population (type and number), density and creation/deletion distances - these attributes are unique to each set.

Since there is no 'discontinue traffic manager' function, one can be implemented by defining an input set with no traffic (an empty input set). An appropriate name can make the purpose of the set clear: PauseTraffic, Stop_TM, etc.

==== Sample Traffic Manager Set ====
This is a sample traffic manager set that can be pasted into a scenario file after the HCSM VehFail section. Be sure to paste '''after''' the HCSM VehFail end tag ('''&&&End&&&''') in your scenario file.

'''Note:''' A scenario file may contain only '''one''' Traffic Manager section.

There are two input sets in this example; note how they contain different vehicles and different settings from each other.

<span style="color:#2a4b8d">HCSM TrafficManager
GroupName "Traffic Manager"
HCSM InputSet
Name "ONE"
MinDensity 3.0000000E-002
MaxDensity 7.0000000E-002
MaxObjects 9
CreateDist 2.0000000E+003
DeleteDist 3.0000000E+003
AbsDeleteDist 3.4000000E+003
RunFreq 1.0000000E+000
SolWeights "cargill_semi_peterbilt_blu:2" "cargill_semi_freightliner_red:1" "cargill_semi_peterbilt_yel:3" "DumpTruck_org:3" "semi_peterbilt_yel_Walmart:2" "Cadillac_Escalade:10" "Ford_F150Xcab:15" "Saturn_Vue:10" "FordTaurus:15" "Escape:15" "DumpTruck:2"
&&&&End&&&&
HCSM InputSet
Name "TWO"
MinDensity 1.0000000E-002
MaxDensity 3.0000000E-002
MaxObjects 4
CreateDist 2.5000000E+003
DeleteDist 3.3000000E+003
AbsDeleteDist 3.5000000E+003
RunFreq 1.8000000E+000
SolWeights "Taurus2011:12" "Cadillac_Escalade:16" "Ford_F150Xcab:24" "Saturn_Vue:14" "Escape:6" "Deville:24" "Audi:4"
&&&&End&&&&
&&&&End&&&&
</span>

====='''Managing Traffic Manager Input Sets'''=====
During simulation, Input sets are controlled by the action '''Use Traffic Manager Set'''. A set name must be provided for this action to work.

===== Traffic Manager generated Traffic=====
ADOs will populate the road network around the XD based on the parameters of the Input Set. Typically traffic is removed from the scene shortly after passing the XD. This is visible in the rear view mirror. There is currently no way to adjust this delete distance.

====== Traffic Manager Traffic on 2 lane freeway======
Traffic will prefer to be in the XD lane, so ADOs created in any other lane will tend to veer into the XD lane. On a divided highway, traffic is generated moving with the XD.

====== Traffic Manager Traffic on 2 lane road======
Traffic is generated in the oncoming lane. In some cases traffic may be generated then immediately removed in front of the XD.

===How to Control Objects in the Scene during Simulation ===
"Set and forget" options on simulation entities only require the scenario author to "initialize" the element to a desired setting and then it is left alone during simulation.

Controlling objects dynamically during simulation requires the scenario "talk to" each object with a scenario action. This section describes how each scenario object type can be controlled during simulation within a scenario.

All models used in ISAT are listed within the Scenario Object Library (sol2).txt files. Terrain switch names are displayed in the ISAT workspace.

All model switches are listed within the NadsMiniSim_x.x\bin.x64\ModelList.txt file.

'''Note:''' The diligent reader will note discrepancies in model names between the sol2 and ModelList files. This is because the ModelList file contains actual file names, and the sol2 files define a "name label" for models that may, or may not, be the actual model name. Objects are linked between the sol2 and ModelList files through the ModelID/CigiID records. These values will match between sol2 and ModelList files, but IDs are not necessary at this time for scenario authoring purposes.

Complicated object names can be retrieved from the LRI file that was used to build any scenario file; each BLI is preceded by an LRI. The LRI contains all of the terrain models that will be present in ISAT. These are typically speed limit signs, traffic signals or other features that may be controllable.

'''Note:''' this file may not be present for the Springfield.bli file.

An alternative is to capture a screenshot of the ISAT workspace with the element name string showing. By default ISAT reports the name of any objects when the cursor passes over the object, as shown in this example:

[[File:2021-10-27_08h50_14.png|caption =Object Name Screenshot | 400px]]

{|class="wikitable"
|+ Controlling Scenario Elements During Simulation in Scenario
!Date
!Nads miniSim version
!Object Type
!Scenario Action
!Who To Affect
!Value
!Notes
|-
| Oct. 28, 2021
|2.3
|-
|
|
|Static Object (terrain)
| SetDial > StaticObjManager > Set Option1
| StaticObjManager
| switch name : switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
|Static Object, multiple options
| Set Switch
| Name of element
| switch option
|-
|
|
|Obstacle, multiple options
| Set Switch
| Name of element
| switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
| DDO, multiple options
| Set Switch
| Name of element
| switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
| ADO
| Set Dial > ADO > VisualState
| Name of element
| Limited to options present in ISAT
|-
|
|
| Traffic Signal
| Traffic Light
| Assign action to element
| Target state
| Target state must exist within the Traffic Light Manager intersection timing table for the specified signal

|}

===How to Control Simulated Vehicles===
The scenario author can control simulated vehicles by controlling the environment:
#change a traffic signal to cause an ADO to stop or start at intersections
#affect other ADOs to cause a target ADO to respond
# assign a path for the ADO to travel

Direct control:
*Lane related:
:Set button > ADO > ChangeLane, Turn, ProjectAndResetLane

*All other controls:
:Set Dial > ADO > AudioState, ForcedLaneOffset, ForcedVelocity, InhibitLaneChange, LaneChange, MaintainGap, TargetVelocity, VisualState, AudioState

====How to Change ADO Velocity====
ADO velocity can be changed using the SetDial action:
:SetDial > ADO >

:ForcedVelocity
:ForcedVelocity using an expression:
# match external driver speed
expr % OvVel(0) %
# multiply external driver speed
expr -1 9 %ReadCell('OvVelLocal',1)*1.75 %
:TargetVelocity

Indirect Control (dependent on other scenario element):
:MaintainGap

====How to Link ADO Velocity to Something Else====
ADOs velocity can be linked to other ADOs or the external driver using the MaintainGap (MG) action.

SetDial > ADO > MaintainGap

When using a traffic cloud containing multiple ADOs, each ADO in the cloud needs a unique MG. IF multiple ADOs have the same MG settings they will attempt to satisfy their parameters and likely oscillate position in a visually obnoxious way.

===How to Author Loop Scenarios===
A scenario created on a loop road network operates very much like any other scenario, with the exception that it is likely to require tracking the number of times through the loop, or to present scenario events to the external driver depending on each loop context.

[[File:loop_traffic_creation_01.png|400px]]

The simplest method of tracking loops is the use of a loop counter variable. This variable can be set by the driver "stepping onto" a roadpad trigger or it can be initialized through the use of a timer or expression, with increments managed by a roadpad trigger. Each time through the loop increases the loop count variable.

Thus it becomes possible to create events for each loop based on the loop counter variable, typically through an expression trigger.

Loop management triggers

[[File:loop_management_02.png|400px]]

Loop management trigger detail one

[[File:loop_management_vars_02b.png|400px]]

Loop management trigger detail two

[[File:loop_management_3.png|400px]]

====Creating Loop Specific Traffic====
Creating loop traffic is slightly more complicated due to the number of objects to be created and potentially the size of the actual loop. A small loop is installed with the Nads miniSim as simple_rural1 or simple_rural2. Each is a loop road network with two signed 3-way intersections.

Loop specific traffic can be created through the use of a variable (i.e., LoopCount) or within the roadpad trigger that is incrementing the loop count variable. Both methods will incorporate a '''Create Action''' that creates the required elements.

===How to Change Environment Settings===
The scenario author can define global or localized environment conditions.

1. Insert >> Environment Conditions >> <chosen condition>

2. Define a region where the environment condition is active:
:LMB to define polygon points
:RMB to exit point entry mode

[[File:env_condition1.png|400px]]

Choosing an environment condition

[[File:env_condition2.png|400px]]

Environment region defined and parameters panel shows available options

NOTE: The environment condition boundary is a discrete threshold. Condition A will be on one side of the threshold. Immediately after crossing the boundary, condition B will be displayed.

===How to Fade an Environment Condition===
To fade gradually between two conditions requires the use of an expression that continually monitors the desired condition and sets a few variables based on the results.

Examining the demo scenario is the best way to look 'under the hood' to see exact command syntax and values to be used.

[[File:env_fade.png|400px]]

Note: this approach has been used for fog and visibility. It is unknown how it might work with non-visibility conditions such as precipitation and wind.

*From the scenario demo_visibility_transition.scn

[[File:env_fade_schematic.png|400px]]

'''Note:''' although the example above uses an environment condition boundary, '''it is possible''' to omit the defined region, retaining all commands and the scenario will still function. However, without the environment region, it becomes more difficult to determine where conditions are different from the standard settings.

===How to Control a Cab Instrument Panel icon===
In order to control the instrument panel, there are 2 requirements:
The specific cab used for the scenario
The specific control (switch) to be manipulated
The action for addressing the instrument panel is '''ChangeCabSetting'''

Instrument panel models are located in NadsMiniSim_x.x\data\Visuals\Instruments
These files are in OpenFlight format. Any 3D editor capable of reading or importing OpenFlight can be used to review these files. NADS uses the Presagis product Creator[tm].

An alternative method to inventory switches is to use the the '''buildscl.exe''' tool. To run the tool, open a CMD window to the IP folder location above, then run the command:
buildscl <input_file.flt><Enter>.
<input_file.flt> is the name of the file to process, without the '<>' characters.
<Enter> means to press the Enter key,

The result will be in a new file ending with .scl. This is a text file, and can be opened in a text editor or you can use the shell utility '''more''' to view the file contents:

more <input_file.scl> | grep switch<Enter>

An example for the malibu cab is shown below. .

switch s_LowWasher 0
switch s_Cruise 1
switch s_LeftTurn 2
switch s_RightTurn 3
switch s_FwdCollisionWarn 4
switch s_BlindSpotWarn 5
switch s_LaneDeviationWarn 6
switch s_RearCollisionWarn 7
switch s_HighBeamHeadlights 8
switch s_SeatBelt 9
switch s_UpArrow 10
switch s_Airbag 11
switch s_CheckEngine 12
switch s_CheckGuages 13
switch s_ABS 14
switch s_Brake 15
switch s_LowFuel 16
switch s_Gear 17

These controls may be accessed directly in scenario using the ChangeCabSetting action.

'''NOTE:''' Some functions such as Cruise, Gear, High beam headlights, Blind spot, collision, lane deviation warnings are '''normally''' controlled not by direct access as described here but by hardware mechanisms/buttons.

'''NOTE:''' For altering cab instrument panel operation it will be necessary to modify the OpenFlight model to include the desired funationality; for example, instrument panel blanking is not build into the model but can be added by editing the cab instrument panel model file then installing the modified file into miniSim.

===Scenario Hints===
The total number of scenario elements active at any given time can affect simulator performance:

Total number of active elements
*vehicles (ADOs), triggers, animations, etc.

Object management
*Use paths to shift ADOs away from the driver route of travel as they turn off the route
*reduce the number of vehicles in traffic cloud surrounding external driver
*use creation radius to limit the number of active elements, and to remove elements after the driver has traveled beyond the creation radius

[[File:creation_radius_1.png|400px]]

Creation radius works by activating the scenario element only when the driver is within the radius. The scenario element is created when the driver enters the creation radius, and is deleted after the driver leaves the creation radius.

Exploit environment to reduce object load

*Use curves, hills, intersection corners to mask objects

Object deletion
*Remove objects when no longer needed

When creating dynamic elements, create them as close to where they are needed as possible.

====How to Determine When ADOs are Visible to the External Driver====

Some development/setup testing may be needed to determine precise location/distance/speed; i.e., locating ADOs for a freeway ramp merge event where the external driver is merging onto the freeway with other ambient traffic present.

Unless the purpose of the event is to study driver behavior at the merge, ideally the scenario will be authored to have ambient traffic on the freeway but not to present a conflict at the merge for the external driver.

A straightforward way to determine where the ADOs are first visible to the driver is to mock up a scenario placing colored ADOs along the freeway with a velocity of 0. This will ensure the ADOs remain stationary while the scenario author determines where they are first visible to the external driver.

Place the start position/external driver far enough up the ramp to be a reasonable test for the actual scenario.

As you drive the ramp, see which ADO is first visible to the driver. Place ADOs just out of view (upstream) of that location.

[[File:merge_hint.png|400px]]

'''NOTE:''' use test vehicles of the same type and character as the intended scenario vehicles. For example, do not use a sedan test ADO for a larger vehicle (SUV, bus, dump truck). Doing so will invalidate the visibility test, because a larger ADO will be visible over a longer distance than a small ADO.

[[File:ramp_vis_1.png|400px]]

At the scenario start location, ADOs in front of the Coke truck are visible. Note how the larger vehicles are more obvious at this distance.

[[File:ramp_vis_2.png|400px]]

The driver has traveled onto the ramp. At this point, the last ADO visible to the driver is still the Coke truck.

[[File:ramp_vis_3.png|400px]]

As the driver travels farther down the ramp a small ADO is visible behind the Coke truck.

The answer to the question '''When is an ADO visible?''' is thus:
#It depends on how large the ADO is
#Small ADOs can be placed at the location of the red ADO behind the Coke truck.
#Large ADOs may need to be placed farther back (behind the red ADO). This test is inconclusive, but based on the terrain it seems likely that large ADOs would need to be placed at least at the green ADO location (behind the Coke truck).

Creating small ADOs at the green ADO location when the external driver is located at the ramp position in 3 travelling at the same speed as the external driver should arrive at the merge slightly ahead of the driver (because the curved ramp is longer than the straight freeway).

'''NOTE:''' ADO size, ADO color, time of day and visibility settings affect ADO visibility.

====How to Position Objects Precisely using '''Place Object At..'''====

ISAT does not support true precision because it is not currently possible to 'dial in' a position as is typical in 3D modelling tools, but there is a way to approximate precision in cases where a consistent measurement is desired.

In the following example a number of roadpad triggers are placed relative to the location where a roadway enters an intersection. This is a discrete boundary within the simulation world as shown in ISAT.

There are two methods of placement possible:
# Measure the desired distance (CTRL+Shift+RMB, drag); take note of the coordinates updating in realtime and make a mental note of the desired location.
#Place an object (ADO or static object); use the Place Object At.. feature from the context menu when you RMB on a scenario object.
Using this method you can specify a distance - positive numbers move the object downstream/forward, negative numbers move the object upstream/backward.

'''Note:'''If the distance is significant and extends over an intersection, ISAT may produce unexpected and undesired results such as re-starting the measurement from the closest upstream intersection, thus placing the object where it was not intended.

In the following example, Place Object At.. is used to specify a point 50 feet upstream from the road/intersection border.

[[File:precision_placement_1.png|400px]]

A roadpad trigger has been positioned near the area of interest. Any existing roadpad is deleted from the trigger.

[[File:precision_placement_2.png|400px]]

An ADO is used as a marker object inserted temporarily into the scenario. Any convenient object may be used.

'''Note:''' large objects such as ADOs may be less precise than small objects such as the Traffic cone, but is generally easier to access in the ISAT interface unless you have created a script for cone objects.

[[File:precision_placement_3.png|400px]]

RMB on the ADO to access the Place Object At.. request dialog. Only numbers are valid entries.

[[File:precision_placement_4.png|400px]]

The desired distance is entered into the Place Object At.. request dialog. ISAT will then require you to select the object you wish to move using LMB.

[[File:precision_placement_5.png|400px]]

ISAT moves the selected object by the distance you specified.

[[File:precision_placement_6.png|400px]]

Use the ADO CG (model center) to place the start of the road pad.

[[File:precise_placement_7.png|400px]]

Remove the ADO marker and save your scenario.

==Scenario Testing and Debugging==
The primary way to test and debug scenarios is using ISAT rehearsal mode.

'''NOTE:''' the external driver during rehearsal is a simulation. You have limited control over the simulated ownship:
#change speed
#change lane

ISAT has two rehearsal dialogs:
#abbreviated (standard) dialog
#advanced (extended dialog)

===How to change to the advanced rehearsal dialog===
Often it is necessary to control the ownship during rehearsal. The ownship controls are located in the advanced (extended) rehearsal dialog.

ISAT will show the Advanced dialog the first time rehearsal mode is activated. All additional activations show the abbreviated dialog.

TBC abbreviated dialog

To use the Advanced dialog, LMB the Advanced button.

TBC Advanced dialog

===How to change ownship speed during rehearsal mode===
After entering rehearsal mode:
#click the Play icon (start the rehearsal)
#pause.
#adjust ownship speed
#toggle pause off (resume rehearsal)

===How to make ownship lane change during rehearsal mode===
After entering rehearsal mode:
#click the Play icon (start the rehearsal)
#click the desired Lane Change (left or right)

===How to Use Audio in your Scenario===
Scenarios play audio sounds and messages through a write to cell action: '''SCC_Audio_Trigger'''

Use of audio in a scenario typically requires both a write to cell and a 'clear action' that writes a zero (0) to SCC_Audio_Trigger in order to 'clear the channel'. The 'clear' action can happen before or after playing a sound; choose one method and be consistent in your scenario authoring.

Failure to 'clear the channel' or '''not''' writing a value of zero can result in no audio being played for subsequent write to cell SCC_Audio_Trigger actions.

The following shows how this looks in scenario when executed from a roadpad trigger (RPT):

[[File:audio_scn_A.png|400px]]

The above diagram is shown below in text format:

HCSM RoadPadTrigger
GroupName "WindGust_Audio"
ByTypeSet "ExternalDriver"
NthFromStart 0
NthFromEnd 0
VehicleAhead 0
VehicleBehind 0
LongComment "This is a wind gust event"
ShortComment " "
ActvDel 0.0000000E+00
CrRad 0.0000000E+00
Debounce 0.0000000E+00
FireDelFrames 0
Lifetime 0.0000000E+00
Name "RPT_WG_6"
OneShot 1
Priority 0
SeqAct 1
Position 6.7165800E+04 6.0419215E+03 0.0000000E+00
DrawPosition 6.7165800E+04 6.0419215E+03 1.1308095E-317
Path "R:r3_62700_7920:0[3033.04:3245.46]"
HCSM LogData
Comment "LS1=8"
Delay 0.0000000E+00
InstigatorSet 0
Stream 1
StreamVal 8.0000000E+00
&&&&End&&&&
HCSM WriteCell
Comment "Play_Audio"
Delay 2.0000000E+00
InstigatorSet 0
CellName "SCC_Audio_Trigger"
CellData "63000"
CellType 2
CellVar 0
&&&&End&&&&
HCSM WriteCell
Comment "clear_audio"
Delay 0.0000000E+00
InstigatorSet 0
CellName "SCC_Audio_Trigger"
CellData "0"
CellType 2
CellVar 0
&&&&End&&&&
&&&&End&&&&

===How to Add Custom Audio Instructions to miniSim===

''' Please note: Custom audio 'instructions' for a scenario should be added to the instructions.txt file.'''

These are sounds that are played in scenario, typically as directions for the minSim driver.

Adding custom audio files requires the following procedure:

1 Exit miniSim - changes to the miniSim configuration should happen only when miniSim is not running.

2 Copy the audio .wav file to:
:C:\NadsMiniSim_x.x\data\sound\DefaultCabSound\Instructs

:Edit the file instructions.txt in that same folder.

3 Add an entry to instructions.txt to register your audio file in accordance with the following layout using the existing entries as a template:

:Unique_ID Filename Normalized_Volume

:Unique_ID is whatever unique number you assign to your file.

:Filename is the name of your .WAV file.

:Normalized_Volume is the volume your audio file should play, where 0.00 is silence and 1.00 is maximum volume.

'''NOTE: Remove all spaces in your audio filename.''' If needed, use the underscore character instead of spaces.

===Troubleshooting Custom Audio Additions===
After installing new .wav files and adding them into the audio configuration file '''instructions.txt''', if the audio file does not play:
*Check the Audio Engine window while miniSim is still running. The Audio Engine will display file errors,.
*If Audio Engine does not display a message similar to: Audio Engine loaded normally, scroll through the window messages and look for any .wav or load error messages.

==Re-use of Scenario Elements==
Scenario authoring can be an intensive undertaking. It makes sense therefore to leverage your development efforts by re-using scenario elements where possible.

ISAT provides a number of ways to re-use scenario elements:
# copy/paste
# external references
<span style="color:#ac6600"># exporting elements as '''groups'''</span>
# isc scripts

Each of these methods have their strengths and weaknesses.

===copy/paste===
The simplest method to re-use scenario elements among different scenario files is copy/paste. This is possible for most scenario elements* even if the source and destination roadmap/BLIs are radically different.

[[File:copy_paste.png|400px]]

It is also possible to copy an ISAT element from one scenario to another as '''TEXT''' by selecting the element and using the windows copy shortcut CTRL-C, then open a text file and paste it using the windows paste shortcut CTRL-V.

'''NOTE:''' Traffic sources are '''not''' portable using copy/paste.

'''NOTE:''' Not all elements can be copy/pasted. Elements created from a Create Element action cannot be copied - it is necessary to select the parent element and copy that instead.

[[File:copy_paste2.png|400px]]

In the above diagram, elements at '''B''' and '''C''' cannot be copied/pasted because they have been created by element '''A'''. It is necessary to copy the element at '''A''' instead. If only the elements at B are needed, the best method will be to copy/paste as Text.

'''NOTE: ISAT will not copy elements containing road coordinates (elements with a path) to a scenario that does not share the same BLI as the source (copy from) scenario.'''

A partial solution to such cases is to remove the path first, copy the element, paste into the destination scenario, then re-create the path manually.

===External Reference===
An external reference scenario is intended to be re-used by multiple 'parent' scenarios. The effort of authoring objects is thus leverages across multiple files, without needing to re-create the same elements more than once.

[[File:re_use_xref_1.png|400px]]

Common uses of external references include traffic, traffic signal operation, traffic sign appearance or other environment features which have multiple appearances (billboards, some tile related scenery, etc).

NOTE: Multiple external references are possible; but because objects are categorized by group, it is not entirely necessary.

For example, one external reference file contains traffic, another contains signs. These two external reference scenarios could be combined into one file.

[[File:xref_overview2.png|400px]]

NOTE: Each group defined must be unique across all files: parent and external reference files.

In order to use an element in an external reference scenario, it is necessary to define and assign a group to all elements that you wish to control from the parent scenario.
At this time there is no visual hint in ISAT to indicate if a group has been assigned to an element or not - each element has to be confirmed independently.

However, a properly authored external reference element cannot be edited within the parent scenario (after you have done Add Ref. to use the external reference file).

An alternative is to insert groups using a text editor with macro capability, or to use a program or external script to make the necessary changes.

'''NOTE:''' If the external reference file is for object contained in the parent scenario (for example, an external reference file containing traffic signals with a group defined) it is still necessary for that group to be defined in the parent file.

With traffic signals, ISAT requires ONE explicit group reference, which will be contained in the HCSM TrafficLightManager block as shown below. If you require the use of traffic signals in an external reference, the recommended way to do this is through ISAT because then it manages the group assignment for you.

==== HCSM TrafficLightManager scenario block ====

HCSM TrafficLightManager
HCSM CLG
IntrsctnName "I1_40260_4620"
Duration 2.0000000E+01 3.0000000E+00 1.0000000E+00 2.0000000E+01 3.0000000E+00 1.0000000E+00
GroupName "TrafficSignals"
LightName "s_signal_r1_LTRN_40260_4620_270"
LightName "s_signal_r1_RTRN_40260_4620_270"
LightName "s_signal_r2_LTRN_40260_4620_270"
LightName "s_signal_r2_STRT_40260_4620_270"
LightName "s_signal_r3_STRT_40260_4620_270"
LightName "s_signal_r3_NORM_40260_4620_270"
Pattern "FLTY" "R" "R" "R" "R" "R" ""
Pattern "RTG" "R" "R" "R" "R" "R" ""
Pattern "LTR" "LTR" "LTR" "FLTY" "FLTY" "LTR" ""
Pattern "SR" "SR" "SR" "SG" "SY" "SR" ""
Pattern "SR" "SR" "SR" "SG" "SY" "SR" ""
Pattern "R" "R" "R" "G" "Y" "R" ""
&&&&End&&&&
&&&&End&&&&

'''NOTE:''' At this time there is a known issue using the write cell '''SCC_Audio_Trigger''' action in external references. Although the trigger containing this action can be assigned a group and used as an external reference, audio does not play.

<span style="color:#ac6600">'''Because ISAT updates static object positions (elevation) to the terrain (roadway) when the scenario file is saved, the best way to use a custom elevation is to put such objects into an external reference file in order to isolate those objects from normal scenario editing.''' </span>

====Define a Group====
<span style="color:#ac6600">'''NOTE:''' ISAT 1.8.5 and 1.8.6 currently do not work properly with group files. These versions will not import objects within a group file. There is a workaround which involves the following process, but instead of reading the saved group file into a scenario the workaround requires editing the scenario as text and inserting the objects within the group file into the scenario.</span>

RMB on the element and choose from the context menu: Group >> New Group (if this is a new group) or Group >> (choose an already defined group).

'''NOTE:''' The first time you create a group for an object, ISAT will automatically assign the group to that object.

After defining and assigning groups to the scenario elements needed, save the scenario file then close it.

Open or create the parent scenario file and use the Add Ref. button at the bottom of the ISAT window to select your external reference scenario. After you choose a file ISAT will present you with the groups found in that scenario. Choose the groups you with to include and click the 'Okay' button. Click the Add Ref. OK button to complete the process.

Currently import group file operations are not working, but it is possible to insert the group file content (all HCSM StaticObjects) into a scenario manually by using a text editor to copy text from the group file and paste that into a scenario file into the HCSM Static Object section of the scenario file.

[[File:group_text.jpg|400px]]

'''NOTE:''' ISAT does not enforce logic on your external reference authoring. If you add references to scenarios that do not share the same roadmap/BLI as the parent scenario, it is likely that elements will be placed at the origin (in cases where the external reference roadmap contains roadways not found in the parent) if it even loads.

===Exporting ISAT Elements as Groups===
Transferring ISAT elements among scenarios can be accomplished using groups. As with external reference scenarios, one or more groups must be defined and then assigned to one or more elements.

After defining and assigning groups select the group for export using the Group select drop-down located at the lower left corner of ISAT. Choose a group to export and then click the 'Save Group' button. Save the file.

TBC insert graphic sequence diagram here

'''NOTE:''' If you cannot locate the group file in the folder specified, check the ISAT install\data folder. This is typically:

C:\NADS\ISAT\data

===Group File Contents===
The group file is a text file and can be opened or edited in a text editor.

The following is a group file containing one ADO. Note the GroupName line near the bottom:

Header
LriFile "_dev.bli"
LongComment "this is a test group export"
ShortComment "this comment was left empty"
&&&&End&&&&
HCSM Ado
RunMode "eREMOTE_CONTROL"
RandomSol 0
Name "Ado1"
DynModel "Non Linear"
LogFile ""
LatOffsType 0
CreateRelLatInFeet 0
CreateRelOffsLonUsingExpr 0
CreateRelOffsLonExprStr ""
AutoControlBreakLights 0
AutoControlHeadLights 0
UseReaDel 1
StdToAccType 0
StdToDecType 0
StdToDecVal1 9.0000000E-001
StpToAccType 0
DecToAccType 0
FollowTimeMin 1.0000000E+000
FollowTimeMax 2.0000000E+000
EmergDecClip -1.1000000E+001
Accel2Catch 0
NormVel2Kp 7.0000000E-001
PathSearchDepth 2
LcvFall 1.5000000E+000 2.0000000E+000
LcvFreq 3.0000000E-002 5.0000000E-002
LcvRAmpl 1.0000000E-001 5.0000000E-001
VelCtrlInitMatchOvVel 0
VelCtrlFollowSpeedLimit 0
VelCtrlDistType 0
MaxLatOffset 9.0000000E+000
LongComment " "
ShortComment " "
SolName "Audi"
RoadPos "r1_1320_44220:2:32414.44:0.00"
GroupName "TEST_Group"
&&&&End&&&&
HCSM StaticObjManager
&&&&End&&&&
HCSM DriverMirror
&&&&End&&&&
HCSM IntersectionManager
&&&&End&&&&

===ISC Scripts===
Scripts are an efficient way to automate repetitive and/or complex tasks.

ISAT uses a custom language (ISC) to automate placement and manipulation of scenario objects. Combined with simple direction commands and the capability to navigate a road network, ISC scripts can ask the scenario author for input and prompt for selecting objects.

ISAT installs with some ISC script files. If your version of ISAT contains a data\isc
folder, then your version of ISAT is capable of running scripts. You can create
additional scripts as needed. All scripts located in the data\isc folder will load in ISAT
when ISAT is launched.

You can use these scripts for reference in creating your own custom scripts.

New scripts created during an existing ISAT session will not appear until ISAT is re-
launched.
Scripts that have been edited will not update until ISAT is re-launched.

Unless otherwise indicated, scripts are case-sensitive.

'''NOTE:''' Please do not edit the existing scripts!

Make a copy of any existing script before you make changes. In the event your modified script does not work, you can look at the original file for reference.

ISC scripts are located on the ISAT Elements widget. Custom isc scripts are located after the 'Events' separator.

Using an ISC script involves LMB + dragging the desired script onto the workspace. In some cases the script will ask for inputs.

ISC can be also used to create an entire event, thus ensuring that all events created will be entirely identical in terms of settings and locations for all created elements.

ISC scripts are text files located within the ISAT installation data folder. Only the custom ISC scripts are located in this folder. This is typically:

C:\Nads\Isat\data\isc

====Icon Files====
Script icon files are 8-bit windows icon files (file.ico). GIMP is capable of exporting valid ico files. To create an ico file, scale it to 32x32 pixels. Export the file as .ico to the isat\data\isc folder.

In order for a script to use an icon file, both files must exist in the isat\data\isc folder.

====ISC Script Examples====
This section contains example scripts with notes.

'''Rotate sign'''

.Name SetSignRotation
.Icon SignRot.ico
Static sign
Select(sign,"Please Select a Sign")
sign.SetAngle(Anchor)
.End

'''Place Multiple Static Objects (TrafCone)'''
The following script asks the scenario author for number of cones to generate, position and offset values and then generates the objects.

A breakdown of the script follows the code block below.

.Name Cones
.Icon cone.ico

Block coneBlock %%%
HCSM StaticObject
IsNewObj 1
Name "Cone_xxx"
SolName "TrafCone"
Option 0
Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
&&&&End&&&&
%%%
Static cone;

Value dist1
Value numberOfCones
Value distance
Value variablePart
Value randDistance
Value speed
Value Count
Value LatOffset

Block tempBlock
tempBlock = coneBlock
Count = 1
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

Ask(numberOfCones,"How many cones?" )
Ask(dist1,"Distance between cones?" )
Ask(LatOffset,"How much offset?" )

Position posRp
Position tempPos
posRp = Anchor
numberOfCones = numberOfCones

Repeat numberOfCones
posRp.GoForward(dist1)
# test comment
tempPos = posRp;
tempPos.SetOffset(LatOffset)
cone.RoadPos = tempPos
cone.Clone
Count = Count + 1
tempBlock = coneBlock
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

End
.End

====Script Breakdown cones.isc====

This section contains a description of the elements used in the script. The script segment is followed by a brief text description.

This script places a number of object copies (TrafCone) using information provided by a user.

.Name Cones
.Icon cone.ico

The first line contains a keyword '''.Name''' followed by the name of the script. This is the name that ISAT will use on the Isat Elements widget for the script. Note the script name does not have to be the same, but it is good computing practice.

The second line begins with the keyword '''.Icon''' followed by a file name. This file must exist in the ISAT\data\isc folder (accompanying the script file). This is the icon ISAT will use for the script.

Block coneBlock %%%
HCSM StaticObject
IsNewObj 1
Name "Cone_xxx"
SolName "TrafCone"
Option 0
Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
&&&&End&&&&
%%%

This is the data section of the script, which is defined using the keyword '''Block'''. A block name follows the keyword, and the data start is defined with '''%%%'''.

The HCSM StaticObject section has been copied from a scenario. In this case, a static object was placed into the workspace and then copied into a text file.

Name "Cone_xxx"
Note: the object name contains a marker that can be used to programmatically name instances of the object:

SolName "TrafCone"
This line begins with the keyword '''SolName''' followed by the name of the object as it is defined in the sol2.txt file.

Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
The Position of the static object will update when the script activates and instanced objects are placed in the workspace.

Static cone;
This line begins with the keyword '''Static''' followed by a variable name.

Value dist1
Value numberOfCones
Value distance
Value variablePart
Value randDistance
Value speed
Value Count
Value LatOffset

This section defines variables with the keyword '''Value''' followed by variable names. Using descriptive names is better than generic names. From the variable list it already seems clear what the programmer cares about: number of cones and distances.

Block tempBlock
tempBlock = coneBlock

This section defines a block using the keyword '''Block''' followed by the variable name.

The next statement replicates coneBlock into tempBlock.

Count = 1
Initialize the value of the variable Count to 1.

tempBlock.Replace('xxx',Count)
The built-in '''Replace''' function changes the string 'xxx' to the value of the variable Count.

cone.SetBlock(tempBlock)
This statement creates a block using the function '''SetBlock''' called cone, and copies the contents of tempBlock into it.

Ask(numberOfCones,"How many cones?" )
Ask(dist1,"Distance between cones?" )
Ask(LatOffset,"How much offset?" )

This section asks the user for input and puts that information into variables:
*Number of cones
*Distance between cones (dist1)
*Lateral offset (calculated from lane center)

Position posRp
Position tempPos
posRp = Anchor
numberOfCones = numberOfCones

This section contains position variables and assigns the value of numberOfCones.

Repeat numberOfCones
posRp.GoForward(dist1)
# test comment
tempPos = posRp;
tempPos.SetOffset(LatOffset)
cone.RoadPos = tempPos
cone.Clone
Count = Count + 1
tempBlock = coneBlock
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

This section is where the work happens. Reading from the top, this section is contained within a loop defined by the keyword '''Repeat'''. The number of times to repeat follows in a variable numberOfCones.

'''posRP.GoForward()''' is a built-in function to take the current position and shifts it forward by the amount specified in the dist1 variable.

#test comment
This is a comment defined by starting the line with the comment keyword '''#'''

tempPos = posRp;

Assign the value of the variable tempPos to the value currently in '''posRp'''

tempPos.SetOffset(LatOffset)

Another built-in function or attribute to the position element which defines a lateral offset (distance from the lane center). This statement places the value of a variable LatOffset into the offset element of the tempPos variable, using the operand '''SetOffset'''.

cone.RoadPos = tempPos

This statement sets the road position variable for cone to the value in the variable tempPos.

cone.Clone

Duplicate the block cone using the operand '''Clone'''

Count = Count + 1
Set the value of the variable Count to the value of Count plus one. This statement increments the value of Count for each loop processed.

tempBlock = coneBlock

Create a new block tempBlock by setting it to the content of coneBlock.

tempBlock.Replace('xxx',Count)

Use a built-in function to '''Replace''' the string 'xxx' with the value of the Count variable

cone.SetBlock(tempBlock)

Use the built-in function '''SetBlock''' to place the modified tempBlock (modified by the string replacement command earlier) into the cone block.

End
.End

The last two lines terminate the loop and the script, respectively.

====How to Create an ISC Script====
The simplest way to create an ISC script is to find an existing script that does something similar to your desired behavior and edit it.

=miniSim Simulation Data=
MiniSim runs on shared memory:
*miniSim is a collection of programs
*shared memory is a commonly accessed 'blackboard' list: a Cell and a Cell Value
:The DAQ file is a snapshot of this 'blackboard' memory for every frame.

*Scenario can write to cells added by the scenario author
:-i.e., for custom hardware or tasks/events

'''NOTE:''' Custom cells must be present in the collect file (NadsMiniSimCollect.cec) '''prior to''' simulation in order for the custom cells to be present in the DAQ.

NOTE: The cell type defined in the collect file must be followed, or garbage values will be used

Use of a DAQ file implies that at some point, data reduction will be needed.
Data reduction: the process of distilling measures from the DAQ file, i.e.
*Event definition
*SDLP
*Average headway

==What is the Difference? Cell vs. Variable==
*A Cell is a pre-created “slot” in shared memory
:-Specified in the .CEC collect file,
:-Saved in the DAQ file,
:-Can be sent to custom programs;
:-Can create & use custom cells;
*A Variable is a name value internal to the scenario
:-NOT saved to the DAQ file,
:-Can use to track items in the scenario
:i.e., how long the driver has been exceeding the speed limit
:-Initialize conditions in the scenario.

=== Variables Save ===
Variables can be saved to disk as a single value text file (ie, multiple values over time are not supported) through the use of a '''Store Variable''' action:

[[File:2021-08-23_13h28_49.png|400px]]

The file is stored in the miniSim_x.x\bin.x64 folder.

'''NOTE:''' The name of the file is defined within the Store Variable action. '''Care must be taken to save variables to unique file names''' in the case of multiple scenarios running on miniSim at the same time (if they share common variables), as would be the case if triggers are copied from one scenario to another.

=== Variables Restore/Read ===
Variables can be read into the simulation through the use of a '''Load Variable''' action:

[[File:2021-08-23_13h32_39.png|400px]]

==Cell Types==
This is a partial list of cell types.

*CFS = control feel subsystem (steering wheel, pedals)
*CIS = control information subsystem (gear, turn signal, buttons, etc)
*TPR = terrain profiler for terrain queries
*VDS = vehicle dynamics for accelerations, position, engine speed, speed, etc.
*ACC = adaptive cruise control
*RCM = configuration management for setting variables that affect subsystem configuration (ACC enabled or disabled, for instance)
*SCC = scenario
*SOP = for one time initializations at the start of the simulation.

=='''Data Output Actions'''==

*Write to Cell Actions
:-Write the value of a variable or cell to a cell
:-Write to a custom cell
:-Cannot overwrite another systems output
'''NOTE:''' Although it is possible to write to a different system cell, that value will be over-written on the next frame. Thus it is effectively not feasible nor desirable to do.

'''<span style="color:red">Also Note: the limit for maximum number of write to cell actions that can be performed in one frame is 8.</span>'''

*Set Variable Action
:-Sets the value of a variable
:-Does not have to be created first
:-Not saved in the DAQ unless written to a valid cell
*Logstream
:-Log data action

===Data Output Methods===
Your data is the primary reason for simulation.

1. Default miniSim scenario measures
:- Immediately available

2. Alternate scenario measures (DAQ file)
:- Processed through data reduction

====Default miniSim Scenario Measures====
*Saved to a drive report.txt file
*Saved to the same Location as DAQ files;
:Scenarioname_timedatestamp_report.txt
•Measures calculated overall, and up to 20 Events during drive:
:Collision Count Lane Departure Count
:Maximum Speed Lane Departure Percentage
:Minimum Speed Speeding Count
:Average Speed Speeding Percentage
:Standard Deviation of Speed Average Headway
:Standard Deviation of Lane Position

====Default miniSim Scenario Measures Require Scenario Event Definition====
In order to capture meaningful data into the default miniSim measures, a scenario must be configured properly to define events.

Use the Write to Cell action to activate the default measures.

[[File:2021-07-02_11h02_44.png|400px]]

*At the start of scenario, set:
::SCC_EventStatus =0
::SCC_EventNumber = 0
*At the start of the first event, set:
::SCC_EventStatus = 1
::SCC_EventNumber = 1
*At the end of the first event, set:
::SCC_EventStatus = 0
*At the start of the second event, set:
::SCC_EventStatus = 1
::SCC_EventNumber = 2
*At the end of the second event, set:
::SCC_EventStatus = 0

Continue this pattern; at end of final event, set:
::SCC_EventStatus = 0

====Default miniSim Scenario Measures Sample Report====
The following is an example report for 4 events. Note the remaining events present in the report are all zeroes or -1.00.

[[File:default_measures_report.png|400px]]

===="Alternate" Scenario Event Definition aka Using Logtreams====
'''NOTE: This method is the more typical/standard method for defining events.'''

Defining an event is key to partitioning simulator data into useful sections. Processing these sections is the essence of '''data reduction.'''

These useful sections are partitioned using logstreams and are generally called '''Events''':
*A logstream is a data marker present in the DAQ file
:there are 10 logstreams
:use logstreams to indicate when things happen '''in the data:'''
:at the start of an event; i.e.,
::grab all data where logstream 1 = 100 (example value)
:during a sub-section of an event
:at the end of an event (typically clears to 0)

Logstreams help separate/filter data;
*SDLP is not useful during emergency maneuver events

Logstreams can be useful to debug events;
:marking in the data when triggers fire
:ensuring event counters work; these are typically sequential, so any logstream deviation identifies a problem

*How to define a Scenario Event:

Set logstream values at scenario event start
:during and at scenario event end, set or clear logstream values:
For example:
::logstream 1 for event ID
::logstream 2 for sequencing the event (during/within event)
::logstream 3 for restart number, etc.

*Requires data reduction to fully process drive data
*Does '''not''' support default measures
:unless those measures are used in parallel with the logstream method

*The use of logstreams allows a scenario author to encode event and environment information into the scenario and as a result, into the simulator data stream.

====Example Alternate Scenario Event====
This section contains an example of a scenario that uses logstream 1 to define an event and environmental context.

In the following example, logstream 1 (LS1) is used to:
#define the scenario start, which is also in this example the event start. NOTE: This is not typical.
#when the driver is 805f from the intersection halt line, set a value into LS1
#when the driver is 500f from the intersection halt line, set a '''new value''' into LS1 NOTE: This could also use a different LS than the one used to define your event, i.e., 1
#when the driver activates a roadpad trigger to reset a force velocity (FV) on a lead vehicle

[[File:event_def_LS.png|400px]]

In the following event definition, an expression trigger is used to set a logstream value and execute two additional actions pertaining to the event.

[[File:event_ET_LS3.png|400px]]

====How to Export Data from A DAQ file using ISAT====
ISAT can display and export DAQ data. NOTE: This is 'raw data', not previously processed. This method can be used to test scenarios, confirm or identify data issues.

TBC: example export here

=Terminology & Documentation=
This section contains terminology and references to related documentation.

'''Action''' - the basic scenario element; the basis for creating scenarios. Actions may be executed on scenario elements (dynamic or static), create or remove elements, or the environment (time of day, visibility) or the simulated cab instrument panel.

'''ADO''' - Autonomous Dynamic Object; self-controlling to a degree.

'''Cell''' - Data elements that are recorded to during a drive; some cells may be used by the scenario author. Custom cells may be added to miniSim.

'''Event''' - anything significant that happens during a drive where the driver condition or response is desired to be identified in the drive data. Can be isolated from general driving through default measures or logstreams.

'''ISAT''' - Interactive Scenario Authoring Toolkit; used to create scenario files for use on the NADS facility or miniSim simulators.

'''ISC''' - ISAT script file.

'''Scenario''' - The simulation experience during a drive; also known as a scenario file, which contains all instructions to the elements within a simulator drive.

'''SDLP''' - Standard deviation lane position

'''SOL''' - Scenario Object Library; objects that are available to ISAT during scenario authoring must be present within the sol2.txt or an auxiliary sol2 (sol2_aux.xxx.txt) file.

'''Trigger''' - A scenario element that contains actions to execute during simulation. All triggers share the same actions, but execution depends on the trigger type.

'''TTA''' - Time to arrival.

'''TTC''' - Time to collision.

=Reporting ISAT & Scenario Issues=
*How to report ISAT & scenario issues:

When reporting issues with scenarios it is helpful to provide as much information as possible.

This often includes scenarios (including any external reference files) and the .LRI file used by the scenarios, screenshots or video that demonstrate the issue being reported and relevant DAQ files. It can be very helpful to include coordinate information with the screenshot or video.

The .BLI file is created from the .LRI and is much larger than the LRI so it may be more convenient to send the LRI file. NADS staff can re-create the BLI file from the LRI.

Some graphics anomalies may be issues with the tile model and not a scenario or miniSim problem. These include:
#white block shapes in the environment
#gaps or missing geometry; i.e., holes
#improper lighting (dark features present during the day)

If these issues happen on a custom roadmap/database world, please include the TMT .mos file as well so NADS can re-construct your environment.

==How to contact the NADS miniSim team:==

email [mailto:miniSim-Support@uiowa.edu minisim support]

[mailto:andrew-veit@uiowa.edu Andrew Veit]
Director of NADS miniSim

[mailto:joseph-meidlinger@uiowa.edu Joseph Meidlinger]
Program Coordinator NADS miniSim

[mailto:oscar-hernandezmurcia@uiowa.edu Oscar Hernandez Murcia]
MiniSim Application Programmer/Analyst

[mailto:chris-schwarz@uiowa.edu Chris Schwarz]
Data Reduction & Vehicle Dynamics

[mailto:shawn-allen@uiowa.edu Shawn Allen]
TMT, Modelling & Support

==How to check what BLI file is used by a scenario==

#You can edit the scenario in a text editor; near the top of the file will be a line starting with '''LriFile''' followed by the name of the BLI file in double quotes.
#You can use '''grep''' to inventory single or multiple scenarios:
:grep bli <scenario file/s>
:A partial listing is shown in the example below. NOTE: The files shown will likely be different on your PC:
C:\NADS\Isat\data\training.demo_scn>grep bli *.scn
Demo_Expression_Lead_Vehicle_Variables.scn: LriFile "simple_rural.bli"
Demo_Expression_Trigger_to_Lead_Vehicle.scn: LriFile "simple_rural.bli"
Demo_HUDD.scn: LriFile "simple_rural.bli"
ISAT-Samples-Avoid.scn: LriFile "esc_dry_05.bli"
ISAT-Samples-Right-Incursion.scn: LriFile "esc_dry_05.bli"
ISAT-Samples-TrafficLightTest.scn: LriFile "simple_city1.bli"
ISAT-Samples-TrafficLightTestB.scn: LriFile "simple_city1.bli"
ISAT-Samples-YellowLightDilemmaB.scn: LriFile "simple_city1.bli"
KBW_TEST.scn: LriFile "simple_rural.bli"
KBW_TESTB.scn: LriFile "simple_rural.bli"
demo.createADO_and_trigger.scn: LriFile "simple_city1.bli"
demo.creation_radius1.scn: LriFile "simple_city2.bli"
demo_FV_sum_of_Sines.scn: LriFile "simple_city2.bli"
demo_LV_Decelerate.scn: LriFile "simple_city2.bli"
demo_LV_cut_in.scn: LriFile "esc_dry_05.bli"
demo_MG.scn: LriFile "simple_city2.bli"
demo_TM1.scn: LriFile "simple_city2.bli"
demo_TT_null.scn: LriFile "simple_city2.bli"
demo_actions_text.scn: LriFile "simple_city2.bli"
demo_alt_data_measures.scn: LriFile "simple_city2.bli"
demo_audio_virtual_object.scn: LriFile "esc_dry_05.bli"
demo_audio_virtual_object_simple_rural.scn: LriFile "simple_rural.bli"
demo_auto_cloud1.scn: LriFile "simple_city2.bli"
demo_coneISC1.scn: LriFile "simple_city2.bli"
demo_dddo.scn: LriFile "simple_city1.bli"
demo_dddo_B.scn: LriFile "simple_city1.bli"
demo_forXRef_traffic.scn: LriFile "simple_city1.bli"
demo_force_vel_01.scn: LriFile "simple_city1.bli"
demo_groupImport.scn: LriFile "simple_city2.bli"

==How to configure miniSim for screenshots to include coordinates==
You can enable coordinate display on miniSim by changing the focus to the main display. #Move the cursor until it is positioned in the main display area, then LMB. When successful the main display will appear to "blink".

Press the keyboard n key twice. This will cause coordinate information to display in the lower left corner of the main display.

[[File:miniSim_show_coords.png|400px]]

The n key is a toggle; to disable coordinates, press it twice (2x) again. '''NOTE:''' the cursor focus must be in the main display in order for this to work.

=Additional Resources=
[[:File:ISAT_Quick_Start.pdf|ISAT Quick Start Guide]]

[[ISAT_Demonstration_Scenarios|Demonstration Scenarios]]

[[:File:Create_Use_Custom_Cells.pdf|Create and Use Custom Cells on MiniSim]]

[[:File:Function_ReadCell_20180824.pdf|ReadCell function]]

[[:File:TrafficManager_Ch12.NADS.Internal_ISAT_UsersGuide.pdf|Traffic Manager]]

=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 [[ISAT_Reference_Manual_Table_of_Contents#ISAT_Reference_Manual|reference manual for ISAT can be found here.]]

ISAT User Guide Table of Contents

2023-08-29T20:34:07Z

Shawn Allen: /* Roadpad Trigger */

== 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
*CTL-<some other key> Press and hold the Ctrl and then press <some other key>. Most typically used for copy (CTRL-C) or paste (CTRL-V).
*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 and modify for use in your own scenarios as needed.

== <span style="color:#FF0000"> '''Known Issues'''</span>==

Added 2022.07.01 '''Relative Creation''' does not currently work for ADOs on miniSim.

'''Expression clarification'''

Increment and decrement operators (++, --) are not considered expressions by behaviors. They should not be flagged as expressions when used in the Value field of a Set Variable action.

Added 2019.11.07 '''File reset issue'''

ISAT has a long-standing bug which can reset your static object options when your scenario file is saved to disk.

'''It is strongly recommended that you use external reference scenario files to avoid this. '''ISAT does not reset static object options in the xref file.

Added 2021.12.29 Expression Triggers and Values

'''Using Values in Expression Triggers'''

To ensure proper execution of expression triggers, it is recommended that the values used include the desired range by decreasing the lower threshold or increasing the upper threshold '''instead of using the exact value.'''

For example, to process values in a range (7031 - 7040):

[[File:2021-12-29_12h38_09.png|400px]]

'''Note: remember that negative values must be calculated since the expression parser does not parse negative values otherwise.'''

For example, to properly parse a specific transmission gear (Park):
'''ReadCell('CFS_Auto_Transmission_Mode', 1) = ( 0 - 2 )'''

=='''ISAT Overview & Interface Basics'''==
This section contains information about ISAT and the ISAT interface.

===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 <span style="color:#FF0000">'''not an object editor'''</span> 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.
[[File:miniSim_scenario_compnents.png|center|640px]]

*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.

[[File:anatomy_of_a_scenario.png|center|400px]]

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

[[File:scenario_as_text.png|center|640px]]

This diagram shows the same scenario in (left to right) 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, <u>always</u> check your edits in ISAT!'''
*Copy/Paste - delete paths from elements when the BLI is different between your source & destination BLI files. The following scenario elements contain paths:
::ADO (with a path specified)
:: Any roadpad trigger (roadpad, Time to Arrival, Follow)

'''NOTE: A Traffic Source is not a portable element but it can be re-created in ISAT or integrated into a new scenario by copying the element from the source scenario then using a text editor to paste it into the destination scenario'''

'''How can I find information in multiple files easily?'''

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.

What if you don't know what to look for? How do 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
[[File:action_overview.png|400px||border|caption]]

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)

==='''Adding an action to a trigger'''===

The following example uses a Time Trigger; remember that '''all triggers share the same actions'''.

To add an action to a trigger you can double-click on the trigger, navigate to the '''Actions''' panel, and click on New to create a new action.

[[File:2022-11-30_12h47_23.png|400px]]

The possible actions are listed under the '''Action Type''' drop-down menu.

[[File:2022-11-30_12h47_44.png|400px]]

Actions are arranged in a 'stack' and are processed from top to bottom. If you use multiple actions you should enable the '''sequential flag''' to ensure each action is executed in sequence. Without the sequential flag, actions will be processed as fast as the simulator behaviors can execute.

[[File:2022-11-30_12h52_58.png|400px]]

Actions may be re-ordered in the stack using the '''arrows''' located near the action stack list.

=='''ISAT Modes of Operation'''==
[[File:ISAT_modes_of_operation.png|400px]]

*Edit
*Rehearsal
*DAQ playback
*Monitor '''Currently not available'''

==='''Edit & Rehearsal Modes'''===

*Edit - this is where scenario authors will spend the most time.
::Creation or modification of scenario
::Link to or import portions of other scenario elements

[[File:mode_edit.png|400px]]

*Rehearsal
::Debug & test scenario
::Simulates scenario using Behaviors and Vehicle Dynamics
::Displays error messages from behaviors

[[File:mode_rehearsal.png|400px]]

'''NOTE:''' Rehearsal mode <span style="color:#FF0000">simulates </span>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

[[File:mode_playback.png|400px]]

==='''miniSim Scenario Components'''===

The following diagram shows an overview of scenario related components of the NADS miniSim and how these components work together.

[[File:miniSim_scenario_components_wDAQ.png|400px]]

=='''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.

[[File:isat_workspace_general.png|400px]]

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)
[[File:isat_status_bar_overview.png|400px]]

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.

[[File:isat_user_prefs_status_bar_settings.png|400px]]

====ISAT Iconography====
ISAT provides graphic hints for triggers placed in scenario that can be useful when editing or maintaining scenarios.

The general format is a border enclosing miniature icons of the trigger and first action contained in that trigger. Additional information representing one or many actions is also shown.

[[File:hints1.png|400px]]

ISAT will list all trigger actions when a trigger is selected, but these hints provide a way to quickly identify what actions have been authored.

[[File:hint2.png|400px]]

*A Roadpad trigger, one action: '''Traffic Light Action'''
*B Roadpad trigger, multiple actions, first action is '''Remove Element'''
*C Roadpad trigger, multiple actions, first action is '''Set Dial'''
*D Roadpad trigger, constrained to road (lane), no actions - this is an empty trigger
*E Roadpad trigger, multiple actions, first action is '''Log Data'''
*F Global Time Trigger, single action: '''Set Dial'''

[[File:handle.png|400px]]

The element handle is the red dot visible in most of the triggers.
The handle can be dragged into position, and the trigger will follow the handle

Drag the trigger off the handle to offset it's location from the handle

==='''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.

[[File:object_types_isat.png|400px]]

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
::*Traffic Source

:'''NOTE:''' Virtual objects are defined in the scenario, not in the SOL2.
[[File:object_types_world.png|400px]]

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.
::NOTE: 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.

==='''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:
#Follow a path using kinematics
#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:
#coupled
#relative trajectory
#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'''===
Traffic signals are objects with special operation and function; they are coupled to intersections and routes of travel through intersections to control traffic flow similiar to their function in the real world. Traffic signals are part of the source tile model and may not be re-positioned or physically altered by scenario except for their visual signal state appearance; i.e., red, green or yellow signals.

To control intersection traffic signals use Edit >> Traffic Light ManagerTraffic signals use a Signal State Table (SST) to control which signal states are active and when. Each intersection with traffic signals will have an associated SST.

[[File:traffic_light_state_manager.png|400px]]

The above diagram shows an intersection in the workspace to the right, and the traffic signal state table for that intersection on the left. At this point additional states (for signal condition) can be added by clicking the '''Add state button'''.

[[File:traffic_signal_state_table2.png|400px]]

The above diagram shows two states defined for the intersection, represented by the two columns of state condition.

Continue adding states until the desired signal cycle has been defined. Generally this consists of red, green or yellow states.

NOTE: There is currently no way to automatically author a series of traffic light signals

To author traffic signal lights in sequence or on a route, the scenario author has to manage the signal states

[[File:traffic_signal_state_duration.png|400px]]

To edit the signal state duration RMB on the duration field header and choosing '''Edit state duration''' on the context menu. Enter the desired value then click OK.

====Traffic Signal Types====
The ISAT status bar reports Traffic Signal Type name. There are two signal types:
#Standard signal - IDs may have no identifying information
:Valid signal states: Red, Yellow, Green, Flashing Red, Flashing Yellow, OFF
#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

[[File:traffic_light_extended_type_name_normal.png|400px]]
: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.

[[File:traffic_light_extended_type_name.png|400px]]

===Changing Signal States in Scenario===
Traffic signals are controlled in scenario by using a Traffic Signal Action to change the SST.

'''NOTE:''' The Traffic Signal Action works by changing the SST, '''not by changing the traffic signal.''' This is a subtle but important difference.

Setting a signal to an undefined state effectively does nothing to the traffic signal.

[[File:traffic_light_state_table.png|400px]]

The above diagram shows a fully populated SST, with one signal row highlighted in red, and one state column highlighted in green. The associated intersection corridor is highlighted, showing the signal controls a dedicated left turn.

During simulation, the initial signal state is defined by the left column. As the simulation proceeds, the signal state changes according to the duration states defined across the state table, proceeding left to right and then wrapping around to the beginning after the last defined state. Each traffic signal appearance changes according to the configuration of the SST.

As a driver approaches this intersection, assume the signal state is in the column left of the highlighted column ('''R'''ed), and the desired action is to change the signal to green.

The action used to change a traffic signal state is the '''Traffic Light Action'''.
Using a traffic light action requires the specification of a signal state, the traffic signal to affect, and a duration.

[[File:traffic_signal_action1.png|400px]]

In the above diagram the scenario author has specified the desired state as '''Green''' as shown in the action dialog.

However, referring back to the previous state table diagram, there is no such state present in the SST. That means this particular action will fail, and the traffic signal will not change as the driver approaches the intersection - because the action does not create a new signal state, it works by advancing the state table condition (column) to the specified condition. If the condition is not present in the SST then nothing will appear to happen.

In this example, the action should be edited to use the correct signal state '''Left Turn Green''', which is present in the SST.

'''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

[[File:known_issue_traffic_light_action.png|400px]]

'''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.

[[File:known_issue_traffic_light_action_workaround.png|400px]]

====Change A Traffic Light Using Scenario Action====
To change a traffic signal, use the Set Dial >> Traffic Light action.
'''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

[[File:traffic_light_state_table.png|400px]]

This diagram shows a fully populated traffic signal state change for an intersection.

*Static object traffic lights
:These are objects, not true traffic signals and so they are not controlled with the Traffic Light manager.

==='''Traffic Source'''===
A traffic source is a coordinator used to create traffic at specific locations in the road map (unlike the Traffic Manager). This is useful for creating ambient traffic. Traffic Sources creates ADOs or DDOs at random or user-specified intervals.

Elements created using a Traffic Source will be created at the locations specified by the user. If traffic is specified at multiple locations the actual location for each creation will be determined randomly during simulation.

'''Note:''' Using the Relative Creation flag on ADOs created by the traffic source will not create traffic at the specified location on the map, but use the information in the Relative Creation fields to populate traffic in the scene during simulation.

This method allows for more flexibility but care must be taken not to create so many ADOs that miniSim is unable to make frame rate. Too many ADOs will cause the scene to jump and 'jitter' and it will feel slower than normal.

==='''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 ISAT scenario rehearsal

===Custom (icon) file virtual objects===

[[File:virtual_object_custom_icon_file.png|400px]]

'''Note:''' Some versions of MiniSim_2.3 do not support custom virtual objects. For those installs, if you require this type of functionality, a workaround exists in the form of a 2D model that can be customized (i.e, sprite).

Virtual objects may be customized using graphics files (texture images) to display any desired custom element. This typically requires the use of a bitmap graphic. Various file formats are supported: JPG, BMP, PNG. It is possible some types of these formats may not work - in those cases, try an alternate format.

If image transparency is required and the custom icon does not display during simulation, please email dsri-minisim@uiowa.edu with a description of the issue, your scenario and custom virtual object image file.

Custom icon files must be located within the Nads MiniSim path for resources - at NadsMiniSim_x.x\data\visuals\Models\ModelTx.

===Standard virtual object shapes===
The virtual object shapes include:
# Circle
# Triangle
# Octagon
# Star
# Diamond
# Icon <- this is for custom virtual object graphics
# Rectangle
# Hexagon

The virtual object fill and border color and transparency can be set in the virtual object properties dialog panel.

[[File:virtual_object_std_shape.png|400px]]

====Virtual Object Workaround====

There is a scenario authoring method that can be used to emulate virtual object functionality through the use of a DDO that is coupled to any dynamic scene element, including the External Driver. One model has been created to support this method called "sprite".

'''Note:''' The sprite model is a 2D object present in the scene, and can therefore be occluded by other scene elements during simulation.

[[File:trafsign_sprite.jpg|400px]]

The sprite model is designed as a flat plane that continuously faces the viewer. It contains different sized planes and can be customized through textures.

When authoring your scenario, configure the sprite object to Off unless it should be visible at scenario start. During the scenario you can control the sprite appearance with a setSwitch action.

[[File:sprite_setSwitch_action_021121.png|400px]]

The who to effect should use the name of the DDO placed in your scenario. The switch name will be s_sprite as shown above. Any valid option can be used. An invalid option (greater than 30) will disable the sprite the same as selecting the OFF option.

==='''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'''===
<span style="color:#FF0000">'''All trigger types share the same Action types'''</span>
*IF Then conditional
*Predicate: i.e., the activating agent
:If predicate is TRUE, then do Action(s)
*Road related triggers are categorized by predicate type
:Named element
:Road (lane)
:Nth vehicle on path only

'''What trigger is appropriate?'''
To determine which trigger is most appropriate, consider the task you are trying to accomplish.

'''Global Time Trigger'''
[[File:isat_time_trigger.png|150px]]

Use this trigger when something has to happen at some point in time.

Time triggers are also useful as "placeholder triggers"; used to apply persistent actions to multiple elements with unique settings for each element. Normally a persistent action is the last action possible in a trigger since the persistent action fires continuously. Putting persistent actions into a time trigger allows the scenario author to continue an action stack in the parent trigger if necessary.

Time triggers can be used as a 'stopwatch' - elapsed time, such as ending a drive after 3 minutes by setting the trigger to fire using an Activation Delay of 180s (GTT >> General).

Often used as a placeholder for actions such as initializing variables, displaying text messages to the screen using Set Visual Display Text actions, etc.

'''Note''': A time trigger can have global elapsed time and activation delay of 0, which causes the action stack in the time trigger to activate when that trigger is created.

'''Roadpad Trigger'''
[[File:isat_roadpad_trigger.png|150px]]

Use this trigger when something has to happen at some location in the drive that does not require event timing to be comparable for all participant drivers. For cases where event timing must be comparable among all participant drivers use the Time to Arrival trigger (TTA) instead of a roadpad trigger.

'''Time to Arrival Trigger'''
[[File:isat_time_to_arrival_trigger.png|150px]]

Use this trigger when something has to happen relative to some point in the drive, and also ensure all study drivers experience the same event timing irrespective of driver style (conservative, slow vs. aggressive, fast). Time to arrival (TTA) trigger uses a time calculation from the trigger pad activation to a target location specified in the trigger.

'''Traffic Light Trigger'''
[[File:isat_traffic_light_trigger.png|150px]]

This trigger activates actions when the specified traffic signal state is reached. For example, if the desired action is to create a DDO pedestrian to step into traffic when the traffic signal is yellow, then the Traffic Signal Manager must be used to author the appropriate signal states for the traffic signal.

Typically some other trigger is used to control the traffic signal (ie, to change the signal to Yellow on approach). It is therefore perfectly valid to put the actions within this other trigger rather than relying on the traffic light trigger.

'''Note''': Once a traffic light action has been authored, ISAT may be prone to crashing when accessing that trigger. This problem can be avoided by creating a time trigger and isolating the traffic light action there, allowing the parent trigger to be modified without crashing. Adjustments can be made to the traffic light action time trigger in a text editor, or recreated if it becomes necessary to make adjustments and ISAT continues to crash when trying to make edits.

'''Note:''' The traffic light action does not change the traffic signal state, and it requires a valid state sequence to exist in the signal timing table (Edit >> Traffic Light Manager). The traffic light action '''will not create a signal state''' that does not already exist in the signal timing table.

'''Expression Trigger'''
[[File:isat_expression_trigger.png|150px]]

Use this trigger when something must be monitored, evaluated or calculated such as checking a variable or cell value, velocity of the driver or the state of simulator hardware (steering wheel angle, brake or accelerator pedal position) or distance from the driver to some other object in the scenario.

Multiple expressions can be used within the same expression trigger. In those cases, all expressions must evaluate to True in order for the action stack to execute unless using an '''OR''' operator.

Use the '''OR''' operator - the pipe character "|" if you want to activate the action stack if '''any''' of the expressions evaluates to True.

In the following example, the trigger checks for TrialNumber = 1 and FirstButtonPress variables, and then checks if Aux Button 1 or 0 was pressed:

'''ReadVar('TrialNumber') = 1.0 & ReadVar('FirstButtonPress') = 1.0 & (ReadCell('Auxiliary_Buttons', 0) > 0 | ReadCell('Auxiliary_Buttons',1) > 0)'''

'''Note''': Expressions can also be embedded into some other triggers, most notably the Set Dial >> ADO >> Forced Velocity action often used in Roadpad triggers.

'''Follow Trigger'''
[[File:isat_follow_trigger.png|150px]]

Use this trigger when something has to happen based on one ADO position relative to another scenario element (including the XD). The follow trigger requires a leader and a follower to be specified; when this condition is met, the trigger action stack activates.

'''Note''': Both leader and follower must be positioned on the follow trigger roadpad to satisfy the follow parameters.

'''Geometric Position'''
[[File:isat_geometric_position_trigger.png|150px]]

This trigger is most useful to perform actions for off-road actors such as walkers. The trigger predicate is limited to Name or Type and requires a geometric position to be defined.

A more limited version of the geometric position trigger can be implemented with a Global Time Trigger that contains a Creation Radius. Placing the creation radius defines the area where the trigger may be activate.

===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

[[File:Screenshot (208).png|800px]]

'''Note:''' The highlighted lane shows which lane is the '''activating lane'''. Other lane/s will not activate the trigger action stack.

===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

[[File:TTA.png|400px]]

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===

[[File:other_triggers.png|400px]]

*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===

Execute actions if input expression evaluates to TRUE; the expression is specified on the trigger Predicate tab.

====Syntax====
Expression triggers support a simple language syntax with operators and functions.
The syntax is infix notation; i.e. a + b, not a b +.

Note: It is not generally possible to embed one function call inside another:
cos(sin(x)) is therefore an invalid expression. ISAT will report invalid expressions during rehearsal of a scenario. Invalid expressions are not supported and will not operate as written during simulation.

'''Exception:''' Currently it is possible to use the square root function with GetObjDistPow2 as in the following example:

sqrt(GetObjDistPow2('Target_Object_Name'))

Multiple expressions may be combined using the logical AND (&) or OR ("|" pipe character).

Exp1 '''&''' Exp2, Exp1 '''&''' Exp2 '''&''' Exp ''N''

All expressions must be true for the trigger to evaluate to TRUE and execute the action stack.

Exp1 '''|''' Exp2
One of the expressions must be true for the trigger to execute the action stack.

Negative values are not directly supported by the expression parser. To use a negative value, it must be a calculated value such as the following:

'''ReadCell('CFS_Steering_Wheel_Angle',0)<(0-5.0)'''

==== Operators ====
Operators are used to create expressions.

'''String'''
:Used within quotes as a string literal; i.e., 'some string'

Grouping
:Parentheses group elements together; i.e.,
:'''()'''; (a), (a + b)

Multiplication
:'''*'''; a * b

Division
:'''/'''; a / b

Addition
:'''+'''; a + b

Subtraction
:'''-'''; a - b

Note: negative values must be expressed with a subtraction operation:
(0 - 5), not -5 (invalid)

Greater than
:'''>'''; a > b

Less than
:'''<'''; a < b

Logical And
:'''&'''; a & b

Both a and b, otherwise returns 0 (FALSE)

Logical Or
:'''|'''; a | b

a or b returns 1 (TRUE)

====Expression Functions ====
Functions are used with operators to create expressions.

Function: '''sin'''
:sin -sine

Syntax
:sin(float x)

Description
:The sin() function returns the sine of x, where x is given in radians.

Return Value
:The sin() function returns a value between -1 and 1.

Function: '''cos'''
:cos –cosine

Syntax
:cos(float x)

Description
:The cos() function returns the cosine of x, where x is given in radians.

Return Value
:The cos() function returns a value between -1 and 1.

Function: '''ReadCell'''
:ReadCell()

Read a Cell value.

Syntax
:ReadCell(string Name, int Cell Array index)

Description
:ReadCell returns the value of a given cell (a cell is the current instance of a variable that will be maybe written to a daq file).

Index specifies a 0 based index into the array. Since most cells are single element arrays, a value 0 indicates the first element.

Cells valid for the ReadCell function are defined within the cell collect file NadsMiniSim.cec located in the miniSim_x.x\data folder.
The ReadCell function operates on shared memory during simulation, it does not read cell data from the DAQ file.

Cells that are defined may be written to the DAQ; the collect file specifies which cells are saved into the DAQ and what frequency to use for the write operation.
The NadsMiniSimCollect.general.txt file is located in the miniSim_x.x\data folder.

Available Cells:
Any cell that has been defined in the .cec file. For example:

:'''LogStreams''': Array of 5 floats. Logstreams are a set of values the scenario author can write to through “write to logstream” actions.
:'''AccelPedalPos''': Single Value. The current position of the accelerator pedal
:'''BrakePedalForce''': Single Value. The current force on the brake pedal in pounds
:'''SteeringWheelAngle''': Single Value. The current rotation of the steering wheel
:'''CruiseControl''': Single Value. The current cruise control position. (values are cab/platform specific)
:'''TurnSignal''': Single Value. The current position of the turn signal (values are cab/platform specific)
:'''OvVel''': Single Value. The participant’s current speed in miles per hour
:'''OvLaneDev''': Single Value. The participant’s lane deviation in feet.
:'''OvHeadwayToLeadVeh''': Single Value. The distance in feet to the first vehicle in front of the participant. -1 if no vehicle can be found.
:'''OvTtcToLeadVeh''': Single Value. The time to collision to the first vehicle ahead of the participant.
:'''Horn''': Single Value. The state of the horn (values are cab/platform specific)
:'''DynObj_Vel''': Array of 20 floats. The speed of a given dynamic object. Dynamic Objects are sorted in terms of distance to driver.
:'''OvVelLocal''': Single Value. The participant’s current speed in miles per hour, using the value local to scenario control

For a complete list of cells and array elements please see the miniSim data dictionary spreadsheet.

Return Value
:Returns the value of the specified cell.

Example
ReadCell(‘LogStreams’,5) > 3

Function: '''CellEquals'''
:Cell Equals, array element, value to compare

Syntax
:CellEquals(string name, int index, float value)

Description
:The Cell Equals function is similar to the ReadCell function, except it adds an additional value to compare against the cell value.

Like ReadCell, name specifies the name of the cell, index specifies the cell array index (use 0 for single value cells).

Available Cells:
:Any cell that is defined in the .cec file.

Return Value
:Units: 1 or 0
:1 if the cell value is equal to the passed in comparison value; otherwise 0

Function: '''GetObjDistPow2'''
:Get object distance squared

Syntax
:GetObjDistPow2(string name)

Description
:GetObjDistPow2 returns the distance squared between the external driver and the dynamic object specified by ‘name’.

Distance squared is used to avoid having to perform an expensive square root calculation every frame.

If the specified object cannot be found, a value larger than 100 million is returned.

Return Value
:Feet; Distance in feet measured from the eye position of the driver to the CG (centroid) of the dynamic object specified.

A very large number is returned if the specified object cannot be found (larger than 100 million)

Example
:GetObjDistPow2(‘OncomingCar1’) < 2500

'''Note:''' To get an actual distance, multiply by the square root (sqrt())
: sqrt(GetObjDistPow2('Target_Obj'))

Function: '''GetObjTtcToOv'''
:Get Object Time To Collision to Own Vehicle

Syntax
:GetObjTtcToOv(string object name)

Description
:GetObjTtcToOv gets the time to collision from the dynamic object specified by the name parameter, to the own vehicle.

Return Value
:Unit: Seconds
:Time (seconds) to collision from the own vehicle to the dynamic object specified by the name parameter.
:0 is returned if the object specified cannot be found.

Function: '''GetObjVel'''
:Get Object Velocity

Syntax
:GetObjVel(string object name)

Description
:GetObjVel gets the velocity in meters per second of the first dynamic object with the name specified by the ‘name’ argument.

Return Value
:Unit: Meters per second
:The speed of the specified dynamic object; 0 if no object is found

'''Note:''' Multiply by 2.23694 for miles per hour.

Example
:GetObjVel(‘PullOutVeh’) > 15.4

Function: '''Rand'''
:Random

Syntax
:Rand(int value)
:Rand(string name)
:Rand(string name, string type, double parameter, double parameter)
:Rand(string name, string type, int parameter, int parameter)

Description
:Rand returns a random value specified by the name of the generator, the type of distribution and its parameters.

If the user does not specify the name of the generator and only specifies a number as the only parameter, the Rand function will use a default random number generator to produce random numbers.

If the user only enters the name of a user created random number generator, the random number generator will produce a value between 0 and 1.
If a name of generator is supplied that has not been created, the Rand function will display an error message in the ISAT debug window and return 0 (during scenario rehearsal).

The rand function supports multiple types of distributions that can be used to generate a random number.

Types of Distributions:
:normal: Normal Distribution(mean, standard deviation). The normal distribution generates random numbers near the mean with a specific standard deviation.
:gamma: Gamma Distribution(alpha, beta). The gamma distribution generates a random value that models waiting times for the Poisson process.
:uniformInt: Uniform Integer Distribution(min, max). The uniform integer distribution generates a random integer number between the lower and upper bounds.
:uniform: Uniform Real Distribution(min, max). The uniform real distribution generates a random floating point number between the lower and upper bounds.

The values stated in the parenthesis above are the parameters for each distribution in order. If the incorrect number of parameters are entered or if they are entered incorrectly, the debug window in ISAT will display an error message and the rand function will return 0 (during scenario rehearsal).

If the distribution is entered incorrectly, the debug window will also display an error message.

Return Value
:A random value from 0 to 1 if the type of distribution is not specified.

If the type of distribution is specified, returns a random value determined from the type of distribution and the given parameters.

Example
:Rand(‘myRandGenerator’,’uniformInt’,1,10)
:This example returns a random integer value from 1 to 10.

Rand(5) or Rand(‘myRandGenerator’)
:These examples return a random value between 0 and 1.

Function: '''sqrt'''
Square root

Syntax:
:sqrt(parameter)

Return Value:
: return the square root of the specified parameter.
: parameter can be another function, such as GetObjDistPow2()

Function: '''ReadVar'''
:Read a variable

Syntax:
:ReadVar(string Name)

Return Value:
:Returns the string value of variable specified in <variable_name>

===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.

=='''Audio Components'''==
The components of the Audio sub-system includes configuration and data files installed into the NadsMiniSim_x.xx\data\sound\DefaultCabSound\Instructs folder.

[[File:audio_components.png|400px]]

The audio engine contains multiple channels and has a theoretical limit of 512 simultaneous sounds.

NOTE: Not all .wav files are compatible with the Audio Engine.

=Scenario World Objects=
Scenario world objects are defined in the tile model source. They are not added by the scenario author since they are objects already present in the roadmap/BLI.

[[File:object_types_world.png|400px]]

Typically, but not always, these objects can be authored in ISAT. However, some scenario world objects have no options - these cannot be selected in ISAT; therefore such objects cannot be authored.

Removal of world objects requires editing the source tile model using a 3D application. In some cases an alternate tile model is available identical to the original but without objects.

Contact NADS if removal of a world object is needed.

Other scenario world objects, such as Traffic Signals, are specialized function objects that can be authored. Traffic signals are authored using the Traffic Light Manager: Edit >> Traffic Light Manager.

=Troubleshooting Scenario Objects That Reset=

== Scenario World Objects ==
Scenario world objects are already present when you create a new scenario - they are not added by the scenario author. These objects may be visible in miniSim but not in ISAT, or they may be visible in ISAT and seem to be controllable, but the objects 'reset' to their defaults when viewed on miniSim.

[[File:2019-10-23_16h18_47.png|700px]]

The objects which 'reset' are a symptom of settings in the TMT that are not configured to allow scenario authoring of objects.

[[File:2019-10-23_16h18_52.png|700px]]

When objects appear to 'reset' or if you can edit an object in ISAT but don't see your changes in miniSim, correct the problem by resolving controllability in the TMT settings: https://www.screencast.com/t/ZH5Dh178.

=Scenario Coordinate Types=
There are two types of coordinates used in scenarios. The first is roadway coordinates. These coordinates are contextual (tied to a specific road or intersection and position) and are used for ADO objects and roadpad paths in general.

After a roadway coordinate has been generated, it is not updated unless the scenario author makes changes to the start, end or location of the entire path or pad.

Roadway coordinate are the reason it is not possible to change a roadmap using the TMT and expect a previously authored scenario to work on the altered roadmap. If the length or location of a road changes, the path/pad will update to the extent possible.

If the road has been eliminated and no longer exists in the roadmap/BLI, ISAT will report an error and not open the scenario file.

A. Field breakdown:
RoadPos keyword <name of road:lane:position on road:path length>

Name "Ado1"
RoadPos "r1_-6600_4620:0:5737.06:0.00"
Path "R:r1_-6600_4620:0[5736.06:5873.83]"

[[File:isat_coordinate_types.png|400px]]

B.
Name "VirtObj"
Option 2
Position -6.8375599E+002 5.6331237E+003 0.0000000E+000

The second type is world coordinates, which are Cartesian coordinates with X increasing to the right, Y increasing forward, and Z increasing up.

='''Scenario Authoring'''=
Scenario authoring is the creation, editing and testing of everything that happens during a simulation drive.

==Cell Operations: Best Practice==
Reading and writing to cells is a computationally expensive process. Best practice is to centralize all the reads/write to one place so that it’s only done once per cell.

Once a cell is read, the value is copied to a variable and only the variable is used throughout all the triggers that need it.

The same process applies to writing to cells. Use of variables can reduce the Cell Operations overhead greatly.

==Before You Begin==
Before beginning a scenario, it is necessary to understand the following requirements:

=== Drive Requirements===
How long is the drive?
What type of roadway?
Are there any specialized road elements (intersections, interchanges, freeway ramps)?
Are there any environmental requirements (should the simulation replicate a real world location, or is a generic environment acceptable)?
Is there a particular roadway configuration that is needed (long straight rural road vs. typical urban environment with intersections, signals, etc)?

=== Traffic Requirements ===
What types of traffic will be needed?
Will ambient traffic interact with the external driver?
What types of interaction will be required (traffic cloud, lead vehicle, follow vehicle)?

=== Events ===
The purpose of an event is to present a situation to the external driver. In order for the simulation to produce meaningful data, it is critical that events unfold for each driver in a comparable way. Therefore, each event must be designed with this repeatability in mind.

'''NOTE:''' one of the most variable scenario elements is the driving style of each external driver: how conservative or aggressive they drive, velocities throughout the scenario, how comfortable the driver is travelling with simulated vehicles, etc.

Repeatability often includes static elements (each driver encounters scenario elements in the same location) or in cases where the driver performance is taken into account, accommodation of the driver dynamic (velocity, lane position) through the use of time to arrival triggers (TTA) or follow triggers. A TTA trigger will fire based on time to a target location - thus a driver travelling at 45mph or a driver travelling at 55mph can both experience the same action relative to that target location, irrespective of the different driver velocities.

==Beginning A Scenario==
All scenarios designed to be driven require a start location - the place where the driver will be located when the simulated drive begins.

To insert a start location into a scenario:

:Insert >> External Driver >> LMB on road, intersection or terrain object

[[File:isat_initial_position.png|400px]]

'''NOTE:''' scenarios that only contain data and are not intended to be driven - for example, signs or traffic that are used as external reference files do not require a start location, since that will be defined within the parent scenario.

==Initial Conditions==
Initial conditions define how the simulated scene is configured: will the drive occur during daylight or night time conditions? Will the ownship (external driver vehicle) have headlights enabled? What type of vehicle will it be? Will there be objects or traffic visible to the driver?
These form the initial conditions of the simulation experience. Additional initial conditions would include initialization of variables or establishing networked communication as needed by the scenario.

[[File:isat_initial_conditions_miniSim.png|400px]]

By default ISAT sets the initial condition '''Time of Day''' to 12:00 noon. The time of day is controlled from the Initial Conditions dialog:

Edit >> Initial Conditions

[[File:isat_initial_conditions_scenario.png|400px]]

==Scenario Authoring: Actions==
Actions are the scenario elements that make things happen during simulation. Actions do specific things, like display a text message on screen for the driver, create a scenario element, change the velocity of simulated traffic, change a traffic signal, etc.

[[File:trigger_action_panels.png|400px]]

The diagram above shows the action panel for left to right: an expression trigger, a roadpad trigger and a global time trigger showing different panels based on the actions present in each trigger.

'''NOTE:'''Actions can be created, edited or removed from the '''Actions panel''' of '''any trigger'''.

'''NOTE:''' The Actions panel changes based on the action type created.
When multiple actions have been defined, control the sequence of actions by changing the action order in the list using the up or down arrows next to the list.

[[File:action_panel_overview.png|400px]]

If multiple actions need to happen in a specific order, set the order using the arrows and then flag the action list as '''sequential'''. This instructs behaviors to process the actions in the list order.

Using a delay for any action will pause processing of the '''following actions'''; the action happens first, then the delay is applied.

===Scenario Authoring: Action Types===
There are two types of actions:
# Instantaneous - the action takes up to one frame to complete, i.e.:
:set target velocity
:write to cell
# Persistent
<span style="color:red">'''*Persistent actions do not end'''</span>, or take multiple frames to complete:
:Forced lane offset
:Forced velocity
:Maintain Gap

==='''Actions'''===
*The "Who to Affect" field defines what is affected by the action
:Instigator set: who activated the trigger
:Name: one or more named elements
:Type: Apply changes to all objects matching the specified type
:Relative: Position relative to the trigger location

*Sequential
:Actions to execute sequentially, one after the other
:Specify delay between actions
:: Action executes, then delay

:Some actions are persistent and never "finish"

===Scenario example: display text & roadpad trigger to stop the drive===
This scenario is very simple and contains a global time trigger (GTT) that tells the driver what to do. After the driver travels along the roadway, a roadpad trigger (RPT) is used to tell the driver to stop driving. The same RPT also creates an expression trigger to terminate the drive.

TBC example scenario file

Because the external driver is not under control except by instructions, it's possible they might ignore the halt message and continue driving. A second failsafe RPT then terminates the drive.

==='''Actions: Button vs. Dial'''===
*Dial changes a setting
*Button: always runs in a single frame
:-"immediate" change. Typically buttons have less control than a '''Set Dial''' action

==='''ADO Actions'''===
[[File:ado_action_types_button_vs_dial.png|400px]]

==='''DDO Actions'''===
[[File:ddo_set_dial.png|400px]]

==='''External Driver Actions'''===
External driver behavior can be influenced by reinforcing scenario actions through audible speeding alerts, on-screen text instructions and messages or audio instructions.

Driving behavior can be influenced with situational elements
:Car in the drivers blind spot
:Lead vehicle
:Aggressive following vehicle
:Temporary lane closure
:lane specific instructions

Scenarios should '''not rely on specific driver actions to be successful'''
:to the extent possible; sometimes you do need the driver to respond/behave in a controlled manner.
:A work zone blocking one lane typically will require a roadpad placed upstream from the work zone to shift traffic into the correct lane

'''NOTE:''' Controlling driver actions should be an experimental design consideration.

==='''Special Actions'''===
These actions need special handling:
*Reset or "toggle":
:Audio
:Display Text

:'''Ado'''
::Audio State
::Forced Velocity
::Maintain Gap
::Visual State

*If using these persistent actions, place them at the '''end''' of an action sequence (because no action following these will execute):
:Forced Lane Offset
:Forced Velocity
:Maintain Gap
:Visual State

*Note: If the Visual State action contains a duration then it will be handled as a normal action, with subsequent actions firing after it. However, if there is no duration supplied with the Visual State action it behaves like a persistent action, and nothing following it in the Action stack will ever fire.

[[File:multiple_simultaneous_actions.png|400px]]

The diagram above shows how one parent trigger can be used to create multiple simultaneous triggers

*How to activate multiple unique force velocity (FV) or maintain gap (MG) actions:
#create the needed triggers from a general parent trigger, 1 per action
#put common actions into the parent trigger
::reset FV
::reset MG

==Scenario Authoring How To==
This section contains simple examples for various typical scenario situations.

===How do I specify an event?===
First, determine which method is best for you - the default measures (limited measures, 20 events max) or logstreams (all simulation data, no event maximum).

Regardless of method, you specify an event by identifying areas of significance in the drive and marking them so the data within the event region can be processed. Any trigger combination that can specify event start and event end may be used.

[[File:2022-07-01_11h21_52.png|400px]]

===How to know Which Coordinator or Trigger I need?===
The answer to this question lies in the type of information needed for an event:

*Time
:global time trigger
:or an expression trigger that calculates time
*Position or Location
:roadpad trigger
::or a time to arrival (TTA) trigger
::or an expression trigger that calculates distance
*Calculation
:Expression trigger

===How to Instruct the External Driver===

Instructions to the external driver can be accomplished by three main methods:
# Instruct the driver using experimental protocol (instructional or briefing presentation)
# Information messages displayed on screen: '''Action: ''set visual display text'' '''
# Information messages delivered as audio messages: '''Action: ''write to cell > SCC_Audio_Trigger ><audio ID>'' '''

===How to Add Traffic in the Scene ===

Generating traffic will happen in one of 5 ways:
# Created explicitly by inserting ADO, or copy/paste existing ADOs
# Created with a script
# Via a Create action inside a trigger, or placing scripted traffic inside a create action within a trigger
# From a '''Traffic Source'''*
# From the '''Traffic Manager'''**

Each of these methods has advantages and disadvantages.

==== Create Explicitly ====

The biggest advantage with this method of traffic creation is the high degree of control the scenario author has over:
# location of the created ADO
# Name of the created ADO
# Travel path of the created ADO
# Control when each ADO is created within the scene via Settings >> Creation Radius

The disadvantage is that creating a high volume of traffic will take some work with this method.

==== Created with a Script ====

This method combines the advantages of Creating Explicitly with volume. It is possible to create a large volume of traffic very easily with a script.

Disadvantages of using high volumes of traffic with a script: in the event it becomes necessary for a high degree of control over these ADOs, more is not better because ADOs will adapt to road conditions under their own power, unless the default ADO settings have been modified:
'''lane changes, including lane changes to accommodate freeway ramps'''
'''velocity adjustments'''

==== Via a Create action inside a trigger ====
Combines the advantages of the previous 2 methods with control over when to activate that traffic using a trigger action.

Disadvantages: Creating too many ADOs at one point in the drive can cause the miniSim to bog down for a few frames. If too many ADOs are present and active in the simulation at one time, this can cause the miniSim to drop frames and run sluggishly. This is highly noticeable and may increase the potential for the External Driver to experience '''simulator sickness.'''

==== From a '''Traffic Source''' ====

Traffic Sources rely on two methods to populate a scene with traffic:
# location specific, with each ADO created for a traffic source being a 'spawn location' for ADOs, or
# location agnostic if the ADO has '''relative creation''' enabled, thus being created relative to the object identified.

In addition to being created relative to a scenario element, ADOs are created relative to the specified scenario element:
# In front of (Longitudinal Distance > 0, where the number is feet offset from the object) , or
# Behind (Longitudinal Distance < 0, where the number is feet offset from the object).

Advantages: Can easily populate traffic into the simulation.

Disadvantages: It is easy to generate more traffic than the simulation can maintain at 60Hz frame rate, thus introducing frame lag with the resulting scene 'stutter' and the increased risk of simulator sickness.

Also, traffic created from a Traffic Source is generic traffic. It is not possible to reliably refer to specific ADOs generated from a traffic source except by using Who To Affect >> Relative (versus referring to a named ADO, i.e. Slow_Moving_Lead_Vehicle). Referring by name to Traffic Source generated ADOs will affect all similarly named ADOs at the same time.

==== From a '''Traffic Manager''' ====

The traffic manager interface is problematic in ISAT versions up to 1.8.5, especially when specifying the set of vehicles to be used for generating traffic.

Advantages: Create generic ambient traffic easily.

Disadvantages: Has the same disadvantages as traffic created via a Traffic Source. Also getting a traffic set working by specifying the vehicles to be used within the set. ISAT versions up to 1.8.5 exhibit instability when setting vehicles in ISAT.

Traffic Manager Set workaround: Borrow a working set from an existing scenario or group. Alternatively use a version of ISAT (1.8.6 +) to create the traffic set. This can be saved as a scenario or group file, which can then be used with ISAT 1.8.x as long as there is no attempt to adjust the vehicle weights within ISAT. The scenario or group file can be edited as text in a text editor, but care must be exercised to avoid introducing errors into the file. ISAT will not read invalid scenario or group files.

Traffic generated by the Traffic Manager is controlled through the use of Input Sets. An input set is a collection of vehicles and weights used to populate the scene during simulation. This is how the scenario author can control the vehicle population (type and number), density and creation/deletion distances - these attributes are unique to each set.

Since there is no 'discontinue traffic manager' function, one can be implemented by defining an input set with no traffic (an empty input set). An appropriate name can make the purpose of the set clear: PauseTraffic, Stop_TM, etc.

==== Sample Traffic Manager Set ====
This is a sample traffic manager set that can be pasted into a scenario file after the HCSM VehFail section. Be sure to paste '''after''' the HCSM VehFail end tag ('''&&&End&&&''') in your scenario file.

'''Note:''' A scenario file may contain only '''one''' Traffic Manager section.

There are two input sets in this example; note how they contain different vehicles and different settings from each other.

<span style="color:#2a4b8d">HCSM TrafficManager
GroupName "Traffic Manager"
HCSM InputSet
Name "ONE"
MinDensity 3.0000000E-002
MaxDensity 7.0000000E-002
MaxObjects 9
CreateDist 2.0000000E+003
DeleteDist 3.0000000E+003
AbsDeleteDist 3.4000000E+003
RunFreq 1.0000000E+000
SolWeights "cargill_semi_peterbilt_blu:2" "cargill_semi_freightliner_red:1" "cargill_semi_peterbilt_yel:3" "DumpTruck_org:3" "semi_peterbilt_yel_Walmart:2" "Cadillac_Escalade:10" "Ford_F150Xcab:15" "Saturn_Vue:10" "FordTaurus:15" "Escape:15" "DumpTruck:2"
&&&&End&&&&
HCSM InputSet
Name "TWO"
MinDensity 1.0000000E-002
MaxDensity 3.0000000E-002
MaxObjects 4
CreateDist 2.5000000E+003
DeleteDist 3.3000000E+003
AbsDeleteDist 3.5000000E+003
RunFreq 1.8000000E+000
SolWeights "Taurus2011:12" "Cadillac_Escalade:16" "Ford_F150Xcab:24" "Saturn_Vue:14" "Escape:6" "Deville:24" "Audi:4"
&&&&End&&&&
&&&&End&&&&
</span>

====='''Managing Traffic Manager Input Sets'''=====
During simulation, Input sets are controlled by the action '''Use Traffic Manager Set'''. A set name must be provided for this action to work.

===== Traffic Manager generated Traffic=====
ADOs will populate the road network around the XD based on the parameters of the Input Set. Typically traffic is removed from the scene shortly after passing the XD. This is visible in the rear view mirror. There is currently no way to adjust this delete distance.

====== Traffic Manager Traffic on 2 lane freeway======
Traffic will prefer to be in the XD lane, so ADOs created in any other lane will tend to veer into the XD lane. On a divided highway, traffic is generated moving with the XD.

====== Traffic Manager Traffic on 2 lane road======
Traffic is generated in the oncoming lane. In some cases traffic may be generated then immediately removed in front of the XD.

===How to Control Objects in the Scene during Simulation ===
"Set and forget" options on simulation entities only require the scenario author to "initialize" the element to a desired setting and then it is left alone during simulation.

Controlling objects dynamically during simulation requires the scenario "talk to" each object with a scenario action. This section describes how each scenario object type can be controlled during simulation within a scenario.

All models used in ISAT are listed within the Scenario Object Library (sol2).txt files. Terrain switch names are displayed in the ISAT workspace.

All model switches are listed within the NadsMiniSim_x.x\bin.x64\ModelList.txt file.

'''Note:''' The diligent reader will note discrepancies in model names between the sol2 and ModelList files. This is because the ModelList file contains actual file names, and the sol2 files define a "name label" for models that may, or may not, be the actual model name. Objects are linked between the sol2 and ModelList files through the ModelID/CigiID records. These values will match between sol2 and ModelList files, but IDs are not necessary at this time for scenario authoring purposes.

Complicated object names can be retrieved from the LRI file that was used to build any scenario file; each BLI is preceded by an LRI. The LRI contains all of the terrain models that will be present in ISAT. These are typically speed limit signs, traffic signals or other features that may be controllable.

'''Note:''' this file may not be present for the Springfield.bli file.

An alternative is to capture a screenshot of the ISAT workspace with the element name string showing. By default ISAT reports the name of any objects when the cursor passes over the object, as shown in this example:

[[File:2021-10-27_08h50_14.png|caption =Object Name Screenshot | 400px]]

{|class="wikitable"
|+ Controlling Scenario Elements During Simulation in Scenario
!Date
!Nads miniSim version
!Object Type
!Scenario Action
!Who To Affect
!Value
!Notes
|-
| Oct. 28, 2021
|2.3
|-
|
|
|Static Object (terrain)
| SetDial > StaticObjManager > Set Option1
| StaticObjManager
| switch name : switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
|Static Object, multiple options
| Set Switch
| Name of element
| switch option
|-
|
|
|Obstacle, multiple options
| Set Switch
| Name of element
| switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
| DDO, multiple options
| Set Switch
| Name of element
| switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
| ADO
| Set Dial > ADO > VisualState
| Name of element
| Limited to options present in ISAT
|-
|
|
| Traffic Signal
| Traffic Light
| Assign action to element
| Target state
| Target state must exist within the Traffic Light Manager intersection timing table for the specified signal

|}

===How to Control Simulated Vehicles===
The scenario author can control simulated vehicles by controlling the environment:
#change a traffic signal to cause an ADO to stop or start at intersections
#affect other ADOs to cause a target ADO to respond
# assign a path for the ADO to travel

Direct control:
*Lane related:
:Set button > ADO > ChangeLane, Turn, ProjectAndResetLane

*All other controls:
:Set Dial > ADO > AudioState, ForcedLaneOffset, ForcedVelocity, InhibitLaneChange, LaneChange, MaintainGap, TargetVelocity, VisualState, AudioState

====How to Change ADO Velocity====
ADO velocity can be changed using the SetDial action:
:SetDial > ADO >

:ForcedVelocity
:ForcedVelocity using an expression:
# match external driver speed
expr % OvVel(0) %
# multiply external driver speed
expr -1 9 %ReadCell('OvVelLocal',1)*1.75 %
:TargetVelocity

Indirect Control (dependent on other scenario element):
:MaintainGap

====How to Link ADO Velocity to Something Else====
ADOs velocity can be linked to other ADOs or the external driver using the MaintainGap (MG) action.

SetDial > ADO > MaintainGap

When using a traffic cloud containing multiple ADOs, each ADO in the cloud needs a unique MG. IF multiple ADOs have the same MG settings they will attempt to satisfy their parameters and likely oscillate position in a visually obnoxious way.

===How to Author Loop Scenarios===
A scenario created on a loop road network operates very much like any other scenario, with the exception that it is likely to require tracking the number of times through the loop, or to present scenario events to the external driver depending on each loop context.

[[File:loop_traffic_creation_01.png|400px]]

The simplest method of tracking loops is the use of a loop counter variable. This variable can be set by the driver "stepping onto" a roadpad trigger or it can be initialized through the use of a timer or expression, with increments managed by a roadpad trigger. Each time through the loop increases the loop count variable.

Thus it becomes possible to create events for each loop based on the loop counter variable, typically through an expression trigger.

Loop management triggers

[[File:loop_management_02.png|400px]]

Loop management trigger detail one

[[File:loop_management_vars_02b.png|400px]]

Loop management trigger detail two

[[File:loop_management_3.png|400px]]

====Creating Loop Specific Traffic====
Creating loop traffic is slightly more complicated due to the number of objects to be created and potentially the size of the actual loop. A small loop is installed with the Nads miniSim as simple_rural1 or simple_rural2. Each is a loop road network with two signed 3-way intersections.

Loop specific traffic can be created through the use of a variable (i.e., LoopCount) or within the roadpad trigger that is incrementing the loop count variable. Both methods will incorporate a '''Create Action''' that creates the required elements.

===How to Change Environment Settings===
The scenario author can define global or localized environment conditions.

1. Insert >> Environment Conditions >> <chosen condition>

2. Define a region where the environment condition is active:
:LMB to define polygon points
:RMB to exit point entry mode

[[File:env_condition1.png|400px]]

Choosing an environment condition

[[File:env_condition2.png|400px]]

Environment region defined and parameters panel shows available options

NOTE: The environment condition boundary is a discrete threshold. Condition A will be on one side of the threshold. Immediately after crossing the boundary, condition B will be displayed.

===How to Fade an Environment Condition===
To fade gradually between two conditions requires the use of an expression that continually monitors the desired condition and sets a few variables based on the results.

Examining the demo scenario is the best way to look 'under the hood' to see exact command syntax and values to be used.

[[File:env_fade.png|400px]]

Note: this approach has been used for fog and visibility. It is unknown how it might work with non-visibility conditions such as precipitation and wind.

*From the scenario demo_visibility_transition.scn

[[File:env_fade_schematic.png|400px]]

'''Note:''' although the example above uses an environment condition boundary, '''it is possible''' to omit the defined region, retaining all commands and the scenario will still function. However, without the environment region, it becomes more difficult to determine where conditions are different from the standard settings.

===How to Control a Cab Instrument Panel icon===
In order to control the instrument panel, there are 2 requirements:
The specific cab used for the scenario
The specific control (switch) to be manipulated
The action for addressing the instrument panel is '''ChangeCabSetting'''

Instrument panel models are located in NadsMiniSim_x.x\data\Visuals\Instruments
These files are in OpenFlight format. Any 3D editor capable of reading or importing OpenFlight can be used to review these files. NADS uses the Presagis product Creator[tm].

An alternative method to inventory switches is to use the the '''buildscl.exe''' tool. To run the tool, open a CMD window to the IP folder location above, then run the command:
buildscl <input_file.flt><Enter>.
<input_file.flt> is the name of the file to process, without the '<>' characters.
<Enter> means to press the Enter key,

The result will be in a new file ending with .scl. This is a text file, and can be opened in a text editor or you can use the shell utility '''more''' to view the file contents:

more <input_file.scl> | grep switch<Enter>

An example for the malibu cab is shown below. .

switch s_LowWasher 0
switch s_Cruise 1
switch s_LeftTurn 2
switch s_RightTurn 3
switch s_FwdCollisionWarn 4
switch s_BlindSpotWarn 5
switch s_LaneDeviationWarn 6
switch s_RearCollisionWarn 7
switch s_HighBeamHeadlights 8
switch s_SeatBelt 9
switch s_UpArrow 10
switch s_Airbag 11
switch s_CheckEngine 12
switch s_CheckGuages 13
switch s_ABS 14
switch s_Brake 15
switch s_LowFuel 16
switch s_Gear 17

These controls may be accessed directly in scenario using the ChangeCabSetting action.

'''NOTE:''' Some functions such as Cruise, Gear, High beam headlights, Blind spot, collision, lane deviation warnings are '''normally''' controlled not by direct access as described here but by hardware mechanisms/buttons.

'''NOTE:''' For altering cab instrument panel operation it will be necessary to modify the OpenFlight model to include the desired funationality; for example, instrument panel blanking is not build into the model but can be added by editing the cab instrument panel model file then installing the modified file into miniSim.

===Scenario Hints===
The total number of scenario elements active at any given time can affect simulator performance:

Total number of active elements
*vehicles (ADOs), triggers, animations, etc.

Object management
*Use paths to shift ADOs away from the driver route of travel as they turn off the route
*reduce the number of vehicles in traffic cloud surrounding external driver
*use creation radius to limit the number of active elements, and to remove elements after the driver has traveled beyond the creation radius

[[File:creation_radius_1.png|400px]]

Creation radius works by activating the scenario element only when the driver is within the radius. The scenario element is created when the driver enters the creation radius, and is deleted after the driver leaves the creation radius.

Exploit environment to reduce object load

*Use curves, hills, intersection corners to mask objects

Object deletion
*Remove objects when no longer needed

When creating dynamic elements, create them as close to where they are needed as possible.

====How to Determine When ADOs are Visible to the External Driver====

Some development/setup testing may be needed to determine precise location/distance/speed; i.e., locating ADOs for a freeway ramp merge event where the external driver is merging onto the freeway with other ambient traffic present.

Unless the purpose of the event is to study driver behavior at the merge, ideally the scenario will be authored to have ambient traffic on the freeway but not to present a conflict at the merge for the external driver.

A straightforward way to determine where the ADOs are first visible to the driver is to mock up a scenario placing colored ADOs along the freeway with a velocity of 0. This will ensure the ADOs remain stationary while the scenario author determines where they are first visible to the external driver.

Place the start position/external driver far enough up the ramp to be a reasonable test for the actual scenario.

As you drive the ramp, see which ADO is first visible to the driver. Place ADOs just out of view (upstream) of that location.

[[File:merge_hint.png|400px]]

'''NOTE:''' use test vehicles of the same type and character as the intended scenario vehicles. For example, do not use a sedan test ADO for a larger vehicle (SUV, bus, dump truck). Doing so will invalidate the visibility test, because a larger ADO will be visible over a longer distance than a small ADO.

[[File:ramp_vis_1.png|400px]]

At the scenario start location, ADOs in front of the Coke truck are visible. Note how the larger vehicles are more obvious at this distance.

[[File:ramp_vis_2.png|400px]]

The driver has traveled onto the ramp. At this point, the last ADO visible to the driver is still the Coke truck.

[[File:ramp_vis_3.png|400px]]

As the driver travels farther down the ramp a small ADO is visible behind the Coke truck.

The answer to the question '''When is an ADO visible?''' is thus:
#It depends on how large the ADO is
#Small ADOs can be placed at the location of the red ADO behind the Coke truck.
#Large ADOs may need to be placed farther back (behind the red ADO). This test is inconclusive, but based on the terrain it seems likely that large ADOs would need to be placed at least at the green ADO location (behind the Coke truck).

Creating small ADOs at the green ADO location when the external driver is located at the ramp position in 3 travelling at the same speed as the external driver should arrive at the merge slightly ahead of the driver (because the curved ramp is longer than the straight freeway).

'''NOTE:''' ADO size, ADO color, time of day and visibility settings affect ADO visibility.

====How to Position Objects Precisely using '''Place Object At..'''====

ISAT does not support true precision because it is not currently possible to 'dial in' a position as is typical in 3D modelling tools, but there is a way to approximate precision in cases where a consistent measurement is desired.

In the following example a number of roadpad triggers are placed relative to the location where a roadway enters an intersection. This is a discrete boundary within the simulation world as shown in ISAT.

There are two methods of placement possible:
# Measure the desired distance (CTRL+Shift+RMB, drag); take note of the coordinates updating in realtime and make a mental note of the desired location.
#Place an object (ADO or static object); use the Place Object At.. feature from the context menu when you RMB on a scenario object.
Using this method you can specify a distance - positive numbers move the object downstream/forward, negative numbers move the object upstream/backward.

'''Note:'''If the distance is significant and extends over an intersection, ISAT may produce unexpected and undesired results such as re-starting the measurement from the closest upstream intersection, thus placing the object where it was not intended.

In the following example, Place Object At.. is used to specify a point 50 feet upstream from the road/intersection border.

[[File:precision_placement_1.png|400px]]

A roadpad trigger has been positioned near the area of interest. Any existing roadpad is deleted from the trigger.

[[File:precision_placement_2.png|400px]]

An ADO is used as a marker object inserted temporarily into the scenario. Any convenient object may be used.

'''Note:''' large objects such as ADOs may be less precise than small objects such as the Traffic cone, but is generally easier to access in the ISAT interface unless you have created a script for cone objects.

[[File:precision_placement_3.png|400px]]

RMB on the ADO to access the Place Object At.. request dialog. Only numbers are valid entries.

[[File:precision_placement_4.png|400px]]

The desired distance is entered into the Place Object At.. request dialog. ISAT will then require you to select the object you wish to move using LMB.

[[File:precision_placement_5.png|400px]]

ISAT moves the selected object by the distance you specified.

[[File:precision_placement_6.png|400px]]

Use the ADO CG (model center) to place the start of the road pad.

[[File:precise_placement_7.png|400px]]

Remove the ADO marker and save your scenario.

==Scenario Testing and Debugging==
The primary way to test and debug scenarios is using ISAT rehearsal mode.

'''NOTE:''' the external driver during rehearsal is a simulation. You have limited control over the simulated ownship:
#change speed
#change lane

ISAT has two rehearsal dialogs:
#abbreviated (standard) dialog
#advanced (extended dialog)

===How to change to the advanced rehearsal dialog===
Often it is necessary to control the ownship during rehearsal. The ownship controls are located in the advanced (extended) rehearsal dialog.

ISAT will show the Advanced dialog the first time rehearsal mode is activated. All additional activations show the abbreviated dialog.

TBC abbreviated dialog

To use the Advanced dialog, LMB the Advanced button.

TBC Advanced dialog

===How to change ownship speed during rehearsal mode===
After entering rehearsal mode:
#click the Play icon (start the rehearsal)
#pause.
#adjust ownship speed
#toggle pause off (resume rehearsal)

===How to make ownship lane change during rehearsal mode===
After entering rehearsal mode:
#click the Play icon (start the rehearsal)
#click the desired Lane Change (left or right)

===How to Use Audio in your Scenario===
Scenarios play audio sounds and messages through a write to cell action: '''SCC_Audio_Trigger'''

Use of audio in a scenario typically requires both a write to cell and a 'clear action' that writes a zero (0) to SCC_Audio_Trigger in order to 'clear the channel'. The 'clear' action can happen before or after playing a sound; choose one method and be consistent in your scenario authoring.

Failure to 'clear the channel' or '''not''' writing a value of zero can result in no audio being played for subsequent write to cell SCC_Audio_Trigger actions.

The following shows how this looks in scenario when executed from a roadpad trigger (RPT):

[[File:audio_scn_A.png|400px]]

The above diagram is shown below in text format:

HCSM RoadPadTrigger
GroupName "WindGust_Audio"
ByTypeSet "ExternalDriver"
NthFromStart 0
NthFromEnd 0
VehicleAhead 0
VehicleBehind 0
LongComment "This is a wind gust event"
ShortComment " "
ActvDel 0.0000000E+00
CrRad 0.0000000E+00
Debounce 0.0000000E+00
FireDelFrames 0
Lifetime 0.0000000E+00
Name "RPT_WG_6"
OneShot 1
Priority 0
SeqAct 1
Position 6.7165800E+04 6.0419215E+03 0.0000000E+00
DrawPosition 6.7165800E+04 6.0419215E+03 1.1308095E-317
Path "R:r3_62700_7920:0[3033.04:3245.46]"
HCSM LogData
Comment "LS1=8"
Delay 0.0000000E+00
InstigatorSet 0
Stream 1
StreamVal 8.0000000E+00
&&&&End&&&&
HCSM WriteCell
Comment "Play_Audio"
Delay 2.0000000E+00
InstigatorSet 0
CellName "SCC_Audio_Trigger"
CellData "63000"
CellType 2
CellVar 0
&&&&End&&&&
HCSM WriteCell
Comment "clear_audio"
Delay 0.0000000E+00
InstigatorSet 0
CellName "SCC_Audio_Trigger"
CellData "0"
CellType 2
CellVar 0
&&&&End&&&&
&&&&End&&&&

===How to Add Custom Audio Instructions to miniSim===

''' Please note: Custom audio 'instructions' for a scenario should be added to the instructions.txt file.'''

These are sounds that are played in scenario, typically as directions for the minSim driver.

Adding custom audio files requires the following procedure:

1 Exit miniSim - changes to the miniSim configuration should happen only when miniSim is not running.

2 Copy the audio .wav file to:
:C:\NadsMiniSim_x.x\data\sound\DefaultCabSound\Instructs

:Edit the file instructions.txt in that same folder.

3 Add an entry to instructions.txt to register your audio file in accordance with the following layout using the existing entries as a template:

:Unique_ID Filename Normalized_Volume

:Unique_ID is whatever unique number you assign to your file.

:Filename is the name of your .WAV file.

:Normalized_Volume is the volume your audio file should play, where 0.00 is silence and 1.00 is maximum volume.

'''NOTE: Remove all spaces in your audio filename.''' If needed, use the underscore character instead of spaces.

===Troubleshooting Custom Audio Additions===
After installing new .wav files and adding them into the audio configuration file '''instructions.txt''', if the audio file does not play:
*Check the Audio Engine window while miniSim is still running. The Audio Engine will display file errors,.
*If Audio Engine does not display a message similar to: Audio Engine loaded normally, scroll through the window messages and look for any .wav or load error messages.

==Re-use of Scenario Elements==
Scenario authoring can be an intensive undertaking. It makes sense therefore to leverage your development efforts by re-using scenario elements where possible.

ISAT provides a number of ways to re-use scenario elements:
# copy/paste
# external references
<span style="color:#ac6600"># exporting elements as '''groups'''</span>
# isc scripts

Each of these methods have their strengths and weaknesses.

===copy/paste===
The simplest method to re-use scenario elements among different scenario files is copy/paste. This is possible for most scenario elements* even if the source and destination roadmap/BLIs are radically different.

[[File:copy_paste.png|400px]]

It is also possible to copy an ISAT element from one scenario to another as '''TEXT''' by selecting the element and using the windows copy shortcut CTRL-C, then open a text file and paste it using the windows paste shortcut CTRL-V.

'''NOTE:''' Traffic sources are '''not''' portable using copy/paste.

'''NOTE:''' Not all elements can be copy/pasted. Elements created from a Create Element action cannot be copied - it is necessary to select the parent element and copy that instead.

[[File:copy_paste2.png|400px]]

In the above diagram, elements at '''B''' and '''C''' cannot be copied/pasted because they have been created by element '''A'''. It is necessary to copy the element at '''A''' instead. If only the elements at B are needed, the best method will be to copy/paste as Text.

'''NOTE: ISAT will not copy elements containing road coordinates (elements with a path) to a scenario that does not share the same BLI as the source (copy from) scenario.'''

A partial solution to such cases is to remove the path first, copy the element, paste into the destination scenario, then re-create the path manually.

===External Reference===
An external reference scenario is intended to be re-used by multiple 'parent' scenarios. The effort of authoring objects is thus leverages across multiple files, without needing to re-create the same elements more than once.

[[File:re_use_xref_1.png|400px]]

Common uses of external references include traffic, traffic signal operation, traffic sign appearance or other environment features which have multiple appearances (billboards, some tile related scenery, etc).

NOTE: Multiple external references are possible; but because objects are categorized by group, it is not entirely necessary.

For example, one external reference file contains traffic, another contains signs. These two external reference scenarios could be combined into one file.

[[File:xref_overview2.png|400px]]

NOTE: Each group defined must be unique across all files: parent and external reference files.

In order to use an element in an external reference scenario, it is necessary to define and assign a group to all elements that you wish to control from the parent scenario.
At this time there is no visual hint in ISAT to indicate if a group has been assigned to an element or not - each element has to be confirmed independently.

However, a properly authored external reference element cannot be edited within the parent scenario (after you have done Add Ref. to use the external reference file).

An alternative is to insert groups using a text editor with macro capability, or to use a program or external script to make the necessary changes.

'''NOTE:''' If the external reference file is for object contained in the parent scenario (for example, an external reference file containing traffic signals with a group defined) it is still necessary for that group to be defined in the parent file.

With traffic signals, ISAT requires ONE explicit group reference, which will be contained in the HCSM TrafficLightManager block as shown below. If you require the use of traffic signals in an external reference, the recommended way to do this is through ISAT because then it manages the group assignment for you.

==== HCSM TrafficLightManager scenario block ====

HCSM TrafficLightManager
HCSM CLG
IntrsctnName "I1_40260_4620"
Duration 2.0000000E+01 3.0000000E+00 1.0000000E+00 2.0000000E+01 3.0000000E+00 1.0000000E+00
GroupName "TrafficSignals"
LightName "s_signal_r1_LTRN_40260_4620_270"
LightName "s_signal_r1_RTRN_40260_4620_270"
LightName "s_signal_r2_LTRN_40260_4620_270"
LightName "s_signal_r2_STRT_40260_4620_270"
LightName "s_signal_r3_STRT_40260_4620_270"
LightName "s_signal_r3_NORM_40260_4620_270"
Pattern "FLTY" "R" "R" "R" "R" "R" ""
Pattern "RTG" "R" "R" "R" "R" "R" ""
Pattern "LTR" "LTR" "LTR" "FLTY" "FLTY" "LTR" ""
Pattern "SR" "SR" "SR" "SG" "SY" "SR" ""
Pattern "SR" "SR" "SR" "SG" "SY" "SR" ""
Pattern "R" "R" "R" "G" "Y" "R" ""
&&&&End&&&&
&&&&End&&&&

'''NOTE:''' At this time there is a known issue using the write cell '''SCC_Audio_Trigger''' action in external references. Although the trigger containing this action can be assigned a group and used as an external reference, audio does not play.

<span style="color:#ac6600">'''Because ISAT updates static object positions (elevation) to the terrain (roadway) when the scenario file is saved, the best way to use a custom elevation is to put such objects into an external reference file in order to isolate those objects from normal scenario editing.''' </span>

====Define a Group====
<span style="color:#ac6600">'''NOTE:''' ISAT 1.8.5 and 1.8.6 currently do not work properly with group files. These versions will not import objects within a group file. There is a workaround which involves the following process, but instead of reading the saved group file into a scenario the workaround requires editing the scenario as text and inserting the objects within the group file into the scenario.</span>

RMB on the element and choose from the context menu: Group >> New Group (if this is a new group) or Group >> (choose an already defined group).

'''NOTE:''' The first time you create a group for an object, ISAT will automatically assign the group to that object.

After defining and assigning groups to the scenario elements needed, save the scenario file then close it.

Open or create the parent scenario file and use the Add Ref. button at the bottom of the ISAT window to select your external reference scenario. After you choose a file ISAT will present you with the groups found in that scenario. Choose the groups you with to include and click the 'Okay' button. Click the Add Ref. OK button to complete the process.

Currently import group file operations are not working, but it is possible to insert the group file content (all HCSM StaticObjects) into a scenario manually by using a text editor to copy text from the group file and paste that into a scenario file into the HCSM Static Object section of the scenario file.

[[File:group_text.jpg|400px]]

'''NOTE:''' ISAT does not enforce logic on your external reference authoring. If you add references to scenarios that do not share the same roadmap/BLI as the parent scenario, it is likely that elements will be placed at the origin (in cases where the external reference roadmap contains roadways not found in the parent) if it even loads.

===Exporting ISAT Elements as Groups===
Transferring ISAT elements among scenarios can be accomplished using groups. As with external reference scenarios, one or more groups must be defined and then assigned to one or more elements.

After defining and assigning groups select the group for export using the Group select drop-down located at the lower left corner of ISAT. Choose a group to export and then click the 'Save Group' button. Save the file.

TBC insert graphic sequence diagram here

'''NOTE:''' If you cannot locate the group file in the folder specified, check the ISAT install\data folder. This is typically:

C:\NADS\ISAT\data

===Group File Contents===
The group file is a text file and can be opened or edited in a text editor.

The following is a group file containing one ADO. Note the GroupName line near the bottom:

Header
LriFile "_dev.bli"
LongComment "this is a test group export"
ShortComment "this comment was left empty"
&&&&End&&&&
HCSM Ado
RunMode "eREMOTE_CONTROL"
RandomSol 0
Name "Ado1"
DynModel "Non Linear"
LogFile ""
LatOffsType 0
CreateRelLatInFeet 0
CreateRelOffsLonUsingExpr 0
CreateRelOffsLonExprStr ""
AutoControlBreakLights 0
AutoControlHeadLights 0
UseReaDel 1
StdToAccType 0
StdToDecType 0
StdToDecVal1 9.0000000E-001
StpToAccType 0
DecToAccType 0
FollowTimeMin 1.0000000E+000
FollowTimeMax 2.0000000E+000
EmergDecClip -1.1000000E+001
Accel2Catch 0
NormVel2Kp 7.0000000E-001
PathSearchDepth 2
LcvFall 1.5000000E+000 2.0000000E+000
LcvFreq 3.0000000E-002 5.0000000E-002
LcvRAmpl 1.0000000E-001 5.0000000E-001
VelCtrlInitMatchOvVel 0
VelCtrlFollowSpeedLimit 0
VelCtrlDistType 0
MaxLatOffset 9.0000000E+000
LongComment " "
ShortComment " "
SolName "Audi"
RoadPos "r1_1320_44220:2:32414.44:0.00"
GroupName "TEST_Group"
&&&&End&&&&
HCSM StaticObjManager
&&&&End&&&&
HCSM DriverMirror
&&&&End&&&&
HCSM IntersectionManager
&&&&End&&&&

===ISC Scripts===
Scripts are an efficient way to automate repetitive and/or complex tasks.

ISAT uses a custom language (ISC) to automate placement and manipulation of scenario objects. Combined with simple direction commands and the capability to navigate a road network, ISC scripts can ask the scenario author for input and prompt for selecting objects.

ISAT installs with some ISC script files. If your version of ISAT contains a data\isc
folder, then your version of ISAT is capable of running scripts. You can create
additional scripts as needed. All scripts located in the data\isc folder will load in ISAT
when ISAT is launched.

You can use these scripts for reference in creating your own custom scripts.

New scripts created during an existing ISAT session will not appear until ISAT is re-
launched.
Scripts that have been edited will not update until ISAT is re-launched.

Unless otherwise indicated, scripts are case-sensitive.

'''NOTE:''' Please do not edit the existing scripts!

Make a copy of any existing script before you make changes. In the event your modified script does not work, you can look at the original file for reference.

ISC scripts are located on the ISAT Elements widget. Custom isc scripts are located after the 'Events' separator.

Using an ISC script involves LMB + dragging the desired script onto the workspace. In some cases the script will ask for inputs.

ISC can be also used to create an entire event, thus ensuring that all events created will be entirely identical in terms of settings and locations for all created elements.

ISC scripts are text files located within the ISAT installation data folder. Only the custom ISC scripts are located in this folder. This is typically:

C:\Nads\Isat\data\isc

====Icon Files====
Script icon files are 8-bit windows icon files (file.ico). GIMP is capable of exporting valid ico files. To create an ico file, scale it to 32x32 pixels. Export the file as .ico to the isat\data\isc folder.

In order for a script to use an icon file, both files must exist in the isat\data\isc folder.

====ISC Script Examples====
This section contains example scripts with notes.

'''Rotate sign'''

.Name SetSignRotation
.Icon SignRot.ico
Static sign
Select(sign,"Please Select a Sign")
sign.SetAngle(Anchor)
.End

'''Place Multiple Static Objects (TrafCone)'''
The following script asks the scenario author for number of cones to generate, position and offset values and then generates the objects.

A breakdown of the script follows the code block below.

.Name Cones
.Icon cone.ico

Block coneBlock %%%
HCSM StaticObject
IsNewObj 1
Name "Cone_xxx"
SolName "TrafCone"
Option 0
Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
&&&&End&&&&
%%%
Static cone;

Value dist1
Value numberOfCones
Value distance
Value variablePart
Value randDistance
Value speed
Value Count
Value LatOffset

Block tempBlock
tempBlock = coneBlock
Count = 1
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

Ask(numberOfCones,"How many cones?" )
Ask(dist1,"Distance between cones?" )
Ask(LatOffset,"How much offset?" )

Position posRp
Position tempPos
posRp = Anchor
numberOfCones = numberOfCones

Repeat numberOfCones
posRp.GoForward(dist1)
# test comment
tempPos = posRp;
tempPos.SetOffset(LatOffset)
cone.RoadPos = tempPos
cone.Clone
Count = Count + 1
tempBlock = coneBlock
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

End
.End

====Script Breakdown cones.isc====

This section contains a description of the elements used in the script. The script segment is followed by a brief text description.

This script places a number of object copies (TrafCone) using information provided by a user.

.Name Cones
.Icon cone.ico

The first line contains a keyword '''.Name''' followed by the name of the script. This is the name that ISAT will use on the Isat Elements widget for the script. Note the script name does not have to be the same, but it is good computing practice.

The second line begins with the keyword '''.Icon''' followed by a file name. This file must exist in the ISAT\data\isc folder (accompanying the script file). This is the icon ISAT will use for the script.

Block coneBlock %%%
HCSM StaticObject
IsNewObj 1
Name "Cone_xxx"
SolName "TrafCone"
Option 0
Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
&&&&End&&&&
%%%

This is the data section of the script, which is defined using the keyword '''Block'''. A block name follows the keyword, and the data start is defined with '''%%%'''.

The HCSM StaticObject section has been copied from a scenario. In this case, a static object was placed into the workspace and then copied into a text file.

Name "Cone_xxx"
Note: the object name contains a marker that can be used to programmatically name instances of the object:

SolName "TrafCone"
This line begins with the keyword '''SolName''' followed by the name of the object as it is defined in the sol2.txt file.

Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
The Position of the static object will update when the script activates and instanced objects are placed in the workspace.

Static cone;
This line begins with the keyword '''Static''' followed by a variable name.

Value dist1
Value numberOfCones
Value distance
Value variablePart
Value randDistance
Value speed
Value Count
Value LatOffset

This section defines variables with the keyword '''Value''' followed by variable names. Using descriptive names is better than generic names. From the variable list it already seems clear what the programmer cares about: number of cones and distances.

Block tempBlock
tempBlock = coneBlock

This section defines a block using the keyword '''Block''' followed by the variable name.

The next statement replicates coneBlock into tempBlock.

Count = 1
Initialize the value of the variable Count to 1.

tempBlock.Replace('xxx',Count)
The built-in '''Replace''' function changes the string 'xxx' to the value of the variable Count.

cone.SetBlock(tempBlock)
This statement creates a block using the function '''SetBlock''' called cone, and copies the contents of tempBlock into it.

Ask(numberOfCones,"How many cones?" )
Ask(dist1,"Distance between cones?" )
Ask(LatOffset,"How much offset?" )

This section asks the user for input and puts that information into variables:
*Number of cones
*Distance between cones (dist1)
*Lateral offset (calculated from lane center)

Position posRp
Position tempPos
posRp = Anchor
numberOfCones = numberOfCones

This section contains position variables and assigns the value of numberOfCones.

Repeat numberOfCones
posRp.GoForward(dist1)
# test comment
tempPos = posRp;
tempPos.SetOffset(LatOffset)
cone.RoadPos = tempPos
cone.Clone
Count = Count + 1
tempBlock = coneBlock
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

This section is where the work happens. Reading from the top, this section is contained within a loop defined by the keyword '''Repeat'''. The number of times to repeat follows in a variable numberOfCones.

'''posRP.GoForward()''' is a built-in function to take the current position and shifts it forward by the amount specified in the dist1 variable.

#test comment
This is a comment defined by starting the line with the comment keyword '''#'''

tempPos = posRp;

Assign the value of the variable tempPos to the value currently in '''posRp'''

tempPos.SetOffset(LatOffset)

Another built-in function or attribute to the position element which defines a lateral offset (distance from the lane center). This statement places the value of a variable LatOffset into the offset element of the tempPos variable, using the operand '''SetOffset'''.

cone.RoadPos = tempPos

This statement sets the road position variable for cone to the value in the variable tempPos.

cone.Clone

Duplicate the block cone using the operand '''Clone'''

Count = Count + 1
Set the value of the variable Count to the value of Count plus one. This statement increments the value of Count for each loop processed.

tempBlock = coneBlock

Create a new block tempBlock by setting it to the content of coneBlock.

tempBlock.Replace('xxx',Count)

Use a built-in function to '''Replace''' the string 'xxx' with the value of the Count variable

cone.SetBlock(tempBlock)

Use the built-in function '''SetBlock''' to place the modified tempBlock (modified by the string replacement command earlier) into the cone block.

End
.End

The last two lines terminate the loop and the script, respectively.

====How to Create an ISC Script====
The simplest way to create an ISC script is to find an existing script that does something similar to your desired behavior and edit it.

=miniSim Simulation Data=
MiniSim runs on shared memory:
*miniSim is a collection of programs
*shared memory is a commonly accessed 'blackboard' list: a Cell and a Cell Value
:The DAQ file is a snapshot of this 'blackboard' memory for every frame.

*Scenario can write to cells added by the scenario author
:-i.e., for custom hardware or tasks/events

'''NOTE:''' Custom cells must be present in the collect file (NadsMiniSimCollect.cec) '''prior to''' simulation in order for the custom cells to be present in the DAQ.

NOTE: The cell type defined in the collect file must be followed, or garbage values will be used

Use of a DAQ file implies that at some point, data reduction will be needed.
Data reduction: the process of distilling measures from the DAQ file, i.e.
*Event definition
*SDLP
*Average headway

==What is the Difference? Cell vs. Variable==
*A Cell is a pre-created “slot” in shared memory
:-Specified in the .CEC collect file,
:-Saved in the DAQ file,
:-Can be sent to custom programs;
:-Can create & use custom cells;
*A Variable is a name value internal to the scenario
:-NOT saved to the DAQ file,
:-Can use to track items in the scenario
:i.e., how long the driver has been exceeding the speed limit
:-Initialize conditions in the scenario.

=== Variables Save ===
Variables can be saved to disk as a single value text file (ie, multiple values over time are not supported) through the use of a '''Store Variable''' action:

[[File:2021-08-23_13h28_49.png|400px]]

The file is stored in the miniSim_x.x\bin.x64 folder.

'''NOTE:''' The name of the file is defined within the Store Variable action. '''Care must be taken to save variables to unique file names''' in the case of multiple scenarios running on miniSim at the same time (if they share common variables), as would be the case if triggers are copied from one scenario to another.

=== Variables Restore/Read ===
Variables can be read into the simulation through the use of a '''Load Variable''' action:

[[File:2021-08-23_13h32_39.png|400px]]

==Cell Types==
This is a partial list of cell types.

*CFS = control feel subsystem (steering wheel, pedals)
*CIS = control information subsystem (gear, turn signal, buttons, etc)
*TPR = terrain profiler for terrain queries
*VDS = vehicle dynamics for accelerations, position, engine speed, speed, etc.
*ACC = adaptive cruise control
*RCM = configuration management for setting variables that affect subsystem configuration (ACC enabled or disabled, for instance)
*SCC = scenario
*SOP = for one time initializations at the start of the simulation.

=='''Data Output Actions'''==

*Write to Cell Actions
:-Write the value of a variable or cell to a cell
:-Write to a custom cell
:-Cannot overwrite another systems output
'''NOTE:''' Although it is possible to write to a different system cell, that value will be over-written on the next frame. Thus it is effectively not feasible nor desirable to do.

'''<span style="color:red">Also Note: the limit for maximum number of write to cell actions that can be performed in one frame is 8.</span>'''

*Set Variable Action
:-Sets the value of a variable
:-Does not have to be created first
:-Not saved in the DAQ unless written to a valid cell
*Logstream
:-Log data action

===Data Output Methods===
Your data is the primary reason for simulation.

1. Default miniSim scenario measures
:- Immediately available

2. Alternate scenario measures (DAQ file)
:- Processed through data reduction

====Default miniSim Scenario Measures====
*Saved to a drive report.txt file
*Saved to the same Location as DAQ files;
:Scenarioname_timedatestamp_report.txt
•Measures calculated overall, and up to 20 Events during drive:
:Collision Count Lane Departure Count
:Maximum Speed Lane Departure Percentage
:Minimum Speed Speeding Count
:Average Speed Speeding Percentage
:Standard Deviation of Speed Average Headway
:Standard Deviation of Lane Position

====Default miniSim Scenario Measures Require Scenario Event Definition====
In order to capture meaningful data into the default miniSim measures, a scenario must be configured properly to define events.

Use the Write to Cell action to activate the default measures.

[[File:2021-07-02_11h02_44.png|400px]]

*At the start of scenario, set:
::SCC_EventStatus =0
::SCC_EventNumber = 0
*At the start of the first event, set:
::SCC_EventStatus = 1
::SCC_EventNumber = 1
*At the end of the first event, set:
::SCC_EventStatus = 0
*At the start of the second event, set:
::SCC_EventStatus = 1
::SCC_EventNumber = 2
*At the end of the second event, set:
::SCC_EventStatus = 0

Continue this pattern; at end of final event, set:
::SCC_EventStatus = 0

====Default miniSim Scenario Measures Sample Report====
The following is an example report for 4 events. Note the remaining events present in the report are all zeroes or -1.00.

[[File:default_measures_report.png|400px]]

===="Alternate" Scenario Event Definition aka Using Logtreams====
'''NOTE: This method is the more typical/standard method for defining events.'''

Defining an event is key to partitioning simulator data into useful sections. Processing these sections is the essence of '''data reduction.'''

These useful sections are partitioned using logstreams and are generally called '''Events''':
*A logstream is a data marker present in the DAQ file
:there are 10 logstreams
:use logstreams to indicate when things happen '''in the data:'''
:at the start of an event; i.e.,
::grab all data where logstream 1 = 100 (example value)
:during a sub-section of an event
:at the end of an event (typically clears to 0)

Logstreams help separate/filter data;
*SDLP is not useful during emergency maneuver events

Logstreams can be useful to debug events;
:marking in the data when triggers fire
:ensuring event counters work; these are typically sequential, so any logstream deviation identifies a problem

*How to define a Scenario Event:

Set logstream values at scenario event start
:during and at scenario event end, set or clear logstream values:
For example:
::logstream 1 for event ID
::logstream 2 for sequencing the event (during/within event)
::logstream 3 for restart number, etc.

*Requires data reduction to fully process drive data
*Does '''not''' support default measures
:unless those measures are used in parallel with the logstream method

*The use of logstreams allows a scenario author to encode event and environment information into the scenario and as a result, into the simulator data stream.

====Example Alternate Scenario Event====
This section contains an example of a scenario that uses logstream 1 to define an event and environmental context.

In the following example, logstream 1 (LS1) is used to:
#define the scenario start, which is also in this example the event start. NOTE: This is not typical.
#when the driver is 805f from the intersection halt line, set a value into LS1
#when the driver is 500f from the intersection halt line, set a '''new value''' into LS1 NOTE: This could also use a different LS than the one used to define your event, i.e., 1
#when the driver activates a roadpad trigger to reset a force velocity (FV) on a lead vehicle

[[File:event_def_LS.png|400px]]

In the following event definition, an expression trigger is used to set a logstream value and execute two additional actions pertaining to the event.

[[File:event_ET_LS3.png|400px]]

====How to Export Data from A DAQ file using ISAT====
ISAT can display and export DAQ data. NOTE: This is 'raw data', not previously processed. This method can be used to test scenarios, confirm or identify data issues.

TBC: example export here

=Terminology & Documentation=
This section contains terminology and references to related documentation.

'''Action''' - the basic scenario element; the basis for creating scenarios. Actions may be executed on scenario elements (dynamic or static), create or remove elements, or the environment (time of day, visibility) or the simulated cab instrument panel.

'''ADO''' - Autonomous Dynamic Object; self-controlling to a degree.

'''Cell''' - Data elements that are recorded to during a drive; some cells may be used by the scenario author. Custom cells may be added to miniSim.

'''Event''' - anything significant that happens during a drive where the driver condition or response is desired to be identified in the drive data. Can be isolated from general driving through default measures or logstreams.

'''ISAT''' - Interactive Scenario Authoring Toolkit; used to create scenario files for use on the NADS facility or miniSim simulators.

'''ISC''' - ISAT script file.

'''Scenario''' - The simulation experience during a drive; also known as a scenario file, which contains all instructions to the elements within a simulator drive.

'''SDLP''' - Standard deviation lane position

'''SOL''' - Scenario Object Library; objects that are available to ISAT during scenario authoring must be present within the sol2.txt or an auxiliary sol2 (sol2_aux.xxx.txt) file.

'''Trigger''' - A scenario element that contains actions to execute during simulation. All triggers share the same actions, but execution depends on the trigger type.

'''TTA''' - Time to arrival.

'''TTC''' - Time to collision.

=Reporting ISAT & Scenario Issues=
*How to report ISAT & scenario issues:

When reporting issues with scenarios it is helpful to provide as much information as possible.

This often includes scenarios (including any external reference files) and the .LRI file used by the scenarios, screenshots or video that demonstrate the issue being reported and relevant DAQ files. It can be very helpful to include coordinate information with the screenshot or video.

The .BLI file is created from the .LRI and is much larger than the LRI so it may be more convenient to send the LRI file. NADS staff can re-create the BLI file from the LRI.

Some graphics anomalies may be issues with the tile model and not a scenario or miniSim problem. These include:
#white block shapes in the environment
#gaps or missing geometry; i.e., holes
#improper lighting (dark features present during the day)

If these issues happen on a custom roadmap/database world, please include the TMT .mos file as well so NADS can re-construct your environment.

==How to contact the NADS miniSim team:==

email [mailto:miniSim-Support@uiowa.edu minisim support]

[mailto:andrew-veit@uiowa.edu Andrew Veit]
Director of NADS miniSim

[mailto:joseph-meidlinger@uiowa.edu Joseph Meidlinger]
Program Coordinator NADS miniSim

[mailto:oscar-hernandezmurcia@uiowa.edu Oscar Hernandez Murcia]
MiniSim Application Programmer/Analyst

[mailto:chris-schwarz@uiowa.edu Chris Schwarz]
Data Reduction & Vehicle Dynamics

[mailto:shawn-allen@uiowa.edu Shawn Allen]
TMT, Modelling & Support

==How to check what BLI file is used by a scenario==

#You can edit the scenario in a text editor; near the top of the file will be a line starting with '''LriFile''' followed by the name of the BLI file in double quotes.
#You can use '''grep''' to inventory single or multiple scenarios:
:grep bli <scenario file/s>
:A partial listing is shown in the example below. NOTE: The files shown will likely be different on your PC:
C:\NADS\Isat\data\training.demo_scn>grep bli *.scn
Demo_Expression_Lead_Vehicle_Variables.scn: LriFile "simple_rural.bli"
Demo_Expression_Trigger_to_Lead_Vehicle.scn: LriFile "simple_rural.bli"
Demo_HUDD.scn: LriFile "simple_rural.bli"
ISAT-Samples-Avoid.scn: LriFile "esc_dry_05.bli"
ISAT-Samples-Right-Incursion.scn: LriFile "esc_dry_05.bli"
ISAT-Samples-TrafficLightTest.scn: LriFile "simple_city1.bli"
ISAT-Samples-TrafficLightTestB.scn: LriFile "simple_city1.bli"
ISAT-Samples-YellowLightDilemmaB.scn: LriFile "simple_city1.bli"
KBW_TEST.scn: LriFile "simple_rural.bli"
KBW_TESTB.scn: LriFile "simple_rural.bli"
demo.createADO_and_trigger.scn: LriFile "simple_city1.bli"
demo.creation_radius1.scn: LriFile "simple_city2.bli"
demo_FV_sum_of_Sines.scn: LriFile "simple_city2.bli"
demo_LV_Decelerate.scn: LriFile "simple_city2.bli"
demo_LV_cut_in.scn: LriFile "esc_dry_05.bli"
demo_MG.scn: LriFile "simple_city2.bli"
demo_TM1.scn: LriFile "simple_city2.bli"
demo_TT_null.scn: LriFile "simple_city2.bli"
demo_actions_text.scn: LriFile "simple_city2.bli"
demo_alt_data_measures.scn: LriFile "simple_city2.bli"
demo_audio_virtual_object.scn: LriFile "esc_dry_05.bli"
demo_audio_virtual_object_simple_rural.scn: LriFile "simple_rural.bli"
demo_auto_cloud1.scn: LriFile "simple_city2.bli"
demo_coneISC1.scn: LriFile "simple_city2.bli"
demo_dddo.scn: LriFile "simple_city1.bli"
demo_dddo_B.scn: LriFile "simple_city1.bli"
demo_forXRef_traffic.scn: LriFile "simple_city1.bli"
demo_force_vel_01.scn: LriFile "simple_city1.bli"
demo_groupImport.scn: LriFile "simple_city2.bli"

==How to configure miniSim for screenshots to include coordinates==
You can enable coordinate display on miniSim by changing the focus to the main display. #Move the cursor until it is positioned in the main display area, then LMB. When successful the main display will appear to "blink".

Press the keyboard n key twice. This will cause coordinate information to display in the lower left corner of the main display.

[[File:miniSim_show_coords.png|400px]]

The n key is a toggle; to disable coordinates, press it twice (2x) again. '''NOTE:''' the cursor focus must be in the main display in order for this to work.

=Additional Resources=
[[:File:ISAT_Quick_Start.pdf|ISAT Quick Start Guide]]

[[ISAT_Demonstration_Scenarios|Demonstration Scenarios]]

[[:File:Create_Use_Custom_Cells.pdf|Create and Use Custom Cells on MiniSim]]

[[:File:Function_ReadCell_20180824.pdf|ReadCell function]]

[[:File:TrafficManager_Ch12.NADS.Internal_ISAT_UsersGuide.pdf|Traffic Manager]]

=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 [[ISAT_Reference_Manual_Table_of_Contents#ISAT_Reference_Manual|reference manual for ISAT can be found here.]]

ISAT User Guide Table of Contents

2023-08-29T20:33:43Z

Shawn Allen: /* Roadpad Trigger */

== 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
*CTL-<some other key> Press and hold the Ctrl and then press <some other key>. Most typically used for copy (CTRL-C) or paste (CTRL-V).
*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 and modify for use in your own scenarios as needed.

== <span style="color:#FF0000"> '''Known Issues'''</span>==

Added 2022.07.01 '''Relative Creation''' does not currently work for ADOs on miniSim.

'''Expression clarification'''

Increment and decrement operators (++, --) are not considered expressions by behaviors. They should not be flagged as expressions when used in the Value field of a Set Variable action.

Added 2019.11.07 '''File reset issue'''

ISAT has a long-standing bug which can reset your static object options when your scenario file is saved to disk.

'''It is strongly recommended that you use external reference scenario files to avoid this. '''ISAT does not reset static object options in the xref file.

Added 2021.12.29 Expression Triggers and Values

'''Using Values in Expression Triggers'''

To ensure proper execution of expression triggers, it is recommended that the values used include the desired range by decreasing the lower threshold or increasing the upper threshold '''instead of using the exact value.'''

For example, to process values in a range (7031 - 7040):

[[File:2021-12-29_12h38_09.png|400px]]

'''Note: remember that negative values must be calculated since the expression parser does not parse negative values otherwise.'''

For example, to properly parse a specific transmission gear (Park):
'''ReadCell('CFS_Auto_Transmission_Mode', 1) = ( 0 - 2 )'''

=='''ISAT Overview & Interface Basics'''==
This section contains information about ISAT and the ISAT interface.

===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 <span style="color:#FF0000">'''not an object editor'''</span> 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.
[[File:miniSim_scenario_compnents.png|center|640px]]

*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.

[[File:anatomy_of_a_scenario.png|center|400px]]

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

[[File:scenario_as_text.png|center|640px]]

This diagram shows the same scenario in (left to right) 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, <u>always</u> check your edits in ISAT!'''
*Copy/Paste - delete paths from elements when the BLI is different between your source & destination BLI files. The following scenario elements contain paths:
::ADO (with a path specified)
:: Any roadpad trigger (roadpad, Time to Arrival, Follow)

'''NOTE: A Traffic Source is not a portable element but it can be re-created in ISAT or integrated into a new scenario by copying the element from the source scenario then using a text editor to paste it into the destination scenario'''

'''How can I find information in multiple files easily?'''

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.

What if you don't know what to look for? How do 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
[[File:action_overview.png|400px||border|caption]]

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)

==='''Adding an action to a trigger'''===

The following example uses a Time Trigger; remember that '''all triggers share the same actions'''.

To add an action to a trigger you can double-click on the trigger, navigate to the '''Actions''' panel, and click on New to create a new action.

[[File:2022-11-30_12h47_23.png|400px]]

The possible actions are listed under the '''Action Type''' drop-down menu.

[[File:2022-11-30_12h47_44.png|400px]]

Actions are arranged in a 'stack' and are processed from top to bottom. If you use multiple actions you should enable the '''sequential flag''' to ensure each action is executed in sequence. Without the sequential flag, actions will be processed as fast as the simulator behaviors can execute.

[[File:2022-11-30_12h52_58.png|400px]]

Actions may be re-ordered in the stack using the '''arrows''' located near the action stack list.

=='''ISAT Modes of Operation'''==
[[File:ISAT_modes_of_operation.png|400px]]

*Edit
*Rehearsal
*DAQ playback
*Monitor '''Currently not available'''

==='''Edit & Rehearsal Modes'''===

*Edit - this is where scenario authors will spend the most time.
::Creation or modification of scenario
::Link to or import portions of other scenario elements

[[File:mode_edit.png|400px]]

*Rehearsal
::Debug & test scenario
::Simulates scenario using Behaviors and Vehicle Dynamics
::Displays error messages from behaviors

[[File:mode_rehearsal.png|400px]]

'''NOTE:''' Rehearsal mode <span style="color:#FF0000">simulates </span>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

[[File:mode_playback.png|400px]]

==='''miniSim Scenario Components'''===

The following diagram shows an overview of scenario related components of the NADS miniSim and how these components work together.

[[File:miniSim_scenario_components_wDAQ.png|400px]]

=='''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.

[[File:isat_workspace_general.png|400px]]

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)
[[File:isat_status_bar_overview.png|400px]]

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.

[[File:isat_user_prefs_status_bar_settings.png|400px]]

====ISAT Iconography====
ISAT provides graphic hints for triggers placed in scenario that can be useful when editing or maintaining scenarios.

The general format is a border enclosing miniature icons of the trigger and first action contained in that trigger. Additional information representing one or many actions is also shown.

[[File:hints1.png|400px]]

ISAT will list all trigger actions when a trigger is selected, but these hints provide a way to quickly identify what actions have been authored.

[[File:hint2.png|400px]]

*A Roadpad trigger, one action: '''Traffic Light Action'''
*B Roadpad trigger, multiple actions, first action is '''Remove Element'''
*C Roadpad trigger, multiple actions, first action is '''Set Dial'''
*D Roadpad trigger, constrained to road (lane), no actions - this is an empty trigger
*E Roadpad trigger, multiple actions, first action is '''Log Data'''
*F Global Time Trigger, single action: '''Set Dial'''

[[File:handle.png|400px]]

The element handle is the red dot visible in most of the triggers.
The handle can be dragged into position, and the trigger will follow the handle

Drag the trigger off the handle to offset it's location from the handle

==='''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.

[[File:object_types_isat.png|400px]]

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
::*Traffic Source

:'''NOTE:''' Virtual objects are defined in the scenario, not in the SOL2.
[[File:object_types_world.png|400px]]

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.
::NOTE: 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.

==='''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:
#Follow a path using kinematics
#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:
#coupled
#relative trajectory
#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'''===
Traffic signals are objects with special operation and function; they are coupled to intersections and routes of travel through intersections to control traffic flow similiar to their function in the real world. Traffic signals are part of the source tile model and may not be re-positioned or physically altered by scenario except for their visual signal state appearance; i.e., red, green or yellow signals.

To control intersection traffic signals use Edit >> Traffic Light ManagerTraffic signals use a Signal State Table (SST) to control which signal states are active and when. Each intersection with traffic signals will have an associated SST.

[[File:traffic_light_state_manager.png|400px]]

The above diagram shows an intersection in the workspace to the right, and the traffic signal state table for that intersection on the left. At this point additional states (for signal condition) can be added by clicking the '''Add state button'''.

[[File:traffic_signal_state_table2.png|400px]]

The above diagram shows two states defined for the intersection, represented by the two columns of state condition.

Continue adding states until the desired signal cycle has been defined. Generally this consists of red, green or yellow states.

NOTE: There is currently no way to automatically author a series of traffic light signals

To author traffic signal lights in sequence or on a route, the scenario author has to manage the signal states

[[File:traffic_signal_state_duration.png|400px]]

To edit the signal state duration RMB on the duration field header and choosing '''Edit state duration''' on the context menu. Enter the desired value then click OK.

====Traffic Signal Types====
The ISAT status bar reports Traffic Signal Type name. There are two signal types:
#Standard signal - IDs may have no identifying information
:Valid signal states: Red, Yellow, Green, Flashing Red, Flashing Yellow, OFF
#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

[[File:traffic_light_extended_type_name_normal.png|400px]]
: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.

[[File:traffic_light_extended_type_name.png|400px]]

===Changing Signal States in Scenario===
Traffic signals are controlled in scenario by using a Traffic Signal Action to change the SST.

'''NOTE:''' The Traffic Signal Action works by changing the SST, '''not by changing the traffic signal.''' This is a subtle but important difference.

Setting a signal to an undefined state effectively does nothing to the traffic signal.

[[File:traffic_light_state_table.png|400px]]

The above diagram shows a fully populated SST, with one signal row highlighted in red, and one state column highlighted in green. The associated intersection corridor is highlighted, showing the signal controls a dedicated left turn.

During simulation, the initial signal state is defined by the left column. As the simulation proceeds, the signal state changes according to the duration states defined across the state table, proceeding left to right and then wrapping around to the beginning after the last defined state. Each traffic signal appearance changes according to the configuration of the SST.

As a driver approaches this intersection, assume the signal state is in the column left of the highlighted column ('''R'''ed), and the desired action is to change the signal to green.

The action used to change a traffic signal state is the '''Traffic Light Action'''.
Using a traffic light action requires the specification of a signal state, the traffic signal to affect, and a duration.

[[File:traffic_signal_action1.png|400px]]

In the above diagram the scenario author has specified the desired state as '''Green''' as shown in the action dialog.

However, referring back to the previous state table diagram, there is no such state present in the SST. That means this particular action will fail, and the traffic signal will not change as the driver approaches the intersection - because the action does not create a new signal state, it works by advancing the state table condition (column) to the specified condition. If the condition is not present in the SST then nothing will appear to happen.

In this example, the action should be edited to use the correct signal state '''Left Turn Green''', which is present in the SST.

'''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

[[File:known_issue_traffic_light_action.png|400px]]

'''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.

[[File:known_issue_traffic_light_action_workaround.png|400px]]

====Change A Traffic Light Using Scenario Action====
To change a traffic signal, use the Set Dial >> Traffic Light action.
'''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

[[File:traffic_light_state_table.png|400px]]

This diagram shows a fully populated traffic signal state change for an intersection.

*Static object traffic lights
:These are objects, not true traffic signals and so they are not controlled with the Traffic Light manager.

==='''Traffic Source'''===
A traffic source is a coordinator used to create traffic at specific locations in the road map (unlike the Traffic Manager). This is useful for creating ambient traffic. Traffic Sources creates ADOs or DDOs at random or user-specified intervals.

Elements created using a Traffic Source will be created at the locations specified by the user. If traffic is specified at multiple locations the actual location for each creation will be determined randomly during simulation.

'''Note:''' Using the Relative Creation flag on ADOs created by the traffic source will not create traffic at the specified location on the map, but use the information in the Relative Creation fields to populate traffic in the scene during simulation.

This method allows for more flexibility but care must be taken not to create so many ADOs that miniSim is unable to make frame rate. Too many ADOs will cause the scene to jump and 'jitter' and it will feel slower than normal.

==='''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 ISAT scenario rehearsal

===Custom (icon) file virtual objects===

[[File:virtual_object_custom_icon_file.png|400px]]

'''Note:''' Some versions of MiniSim_2.3 do not support custom virtual objects. For those installs, if you require this type of functionality, a workaround exists in the form of a 2D model that can be customized (i.e, sprite).

Virtual objects may be customized using graphics files (texture images) to display any desired custom element. This typically requires the use of a bitmap graphic. Various file formats are supported: JPG, BMP, PNG. It is possible some types of these formats may not work - in those cases, try an alternate format.

If image transparency is required and the custom icon does not display during simulation, please email dsri-minisim@uiowa.edu with a description of the issue, your scenario and custom virtual object image file.

Custom icon files must be located within the Nads MiniSim path for resources - at NadsMiniSim_x.x\data\visuals\Models\ModelTx.

===Standard virtual object shapes===
The virtual object shapes include:
# Circle
# Triangle
# Octagon
# Star
# Diamond
# Icon <- this is for custom virtual object graphics
# Rectangle
# Hexagon

The virtual object fill and border color and transparency can be set in the virtual object properties dialog panel.

[[File:virtual_object_std_shape.png|400px]]

====Virtual Object Workaround====

There is a scenario authoring method that can be used to emulate virtual object functionality through the use of a DDO that is coupled to any dynamic scene element, including the External Driver. One model has been created to support this method called "sprite".

'''Note:''' The sprite model is a 2D object present in the scene, and can therefore be occluded by other scene elements during simulation.

[[File:trafsign_sprite.jpg|400px]]

The sprite model is designed as a flat plane that continuously faces the viewer. It contains different sized planes and can be customized through textures.

When authoring your scenario, configure the sprite object to Off unless it should be visible at scenario start. During the scenario you can control the sprite appearance with a setSwitch action.

[[File:sprite_setSwitch_action_021121.png|400px]]

The who to effect should use the name of the DDO placed in your scenario. The switch name will be s_sprite as shown above. Any valid option can be used. An invalid option (greater than 30) will disable the sprite the same as selecting the OFF option.

==='''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'''===
<span style="color:#FF0000">'''All trigger types share the same Action types'''</span>
*IF Then conditional
*Predicate: i.e., the activating agent
:If predicate is TRUE, then do Action(s)
*Road related triggers are categorized by predicate type
:Named element
:Road (lane)
:Nth vehicle on path only

'''What trigger is appropriate?'''
To determine which trigger is most appropriate, consider the task you are trying to accomplish.

'''Global Time Trigger'''
[[File:isat_time_trigger.png|150px]]

Use this trigger when something has to happen at some point in time.

Time triggers are also useful as "placeholder triggers"; used to apply persistent actions to multiple elements with unique settings for each element. Normally a persistent action is the last action possible in a trigger since the persistent action fires continuously. Putting persistent actions into a time trigger allows the scenario author to continue an action stack in the parent trigger if necessary.

Time triggers can be used as a 'stopwatch' - elapsed time, such as ending a drive after 3 minutes by setting the trigger to fire using an Activation Delay of 180s (GTT >> General).

Often used as a placeholder for actions such as initializing variables, displaying text messages to the screen using Set Visual Display Text actions, etc.

'''Note''': A time trigger can have global elapsed time and activation delay of 0, which causes the action stack in the time trigger to activate when that trigger is created.

'''Roadpad Trigger'''
[[File:isat_roadpad_trigger.png|150px]]

Use this trigger when something has to happen at some location in the drive that does not require event timing to be comparable for all participant drivers. For cases where event timing must be comparable among all participant drivers use the Time to Arrival trigger (TTA) instead of a roadpad trigger.

'''Time to Arrival Trigger'''
[[File:isat_time_to_arrival_trigger.png|150px]]

Use this trigger when something has to happen relative to some point in the drive, and also ensure all study drivers experience the same event timing irrespective of driver style (conservative, slow vs. aggressive, fast). Time to arrival (TTA) trigger uses a time calculation from the trigger pad activation to a target location specified in the trigger.

'''Traffic Light Trigger'''
[[File:isat_traffic_light_trigger.png|150px]]

This trigger activates actions when the specified traffic signal state is reached. For example, if the desired action is to create a DDO pedestrian to step into traffic when the traffic signal is yellow, then the Traffic Signal Manager must be used to author the appropriate signal states for the traffic signal.

Typically some other trigger is used to control the traffic signal (ie, to change the signal to Yellow on approach). It is therefore perfectly valid to put the actions within this other trigger rather than relying on the traffic light trigger.

'''Note''': Once a traffic light action has been authored, ISAT may be prone to crashing when accessing that trigger. This problem can be avoided by creating a time trigger and isolating the traffic light action there, allowing the parent trigger to be modified without crashing. Adjustments can be made to the traffic light action time trigger in a text editor, or recreated if it becomes necessary to make adjustments and ISAT continues to crash when trying to make edits.

'''Note:''' The traffic light action does not change the traffic signal state, and it requires a valid state sequence to exist in the signal timing table (Edit >> Traffic Light Manager). The traffic light action '''will not create a signal state''' that does not already exist in the signal timing table.

'''Expression Trigger'''
[[File:isat_expression_trigger.png|150px]]

Use this trigger when something must be monitored, evaluated or calculated such as checking a variable or cell value, velocity of the driver or the state of simulator hardware (steering wheel angle, brake or accelerator pedal position) or distance from the driver to some other object in the scenario.

Multiple expressions can be used within the same expression trigger. In those cases, all expressions must evaluate to True in order for the action stack to execute unless using an '''OR''' operator.

Use the '''OR''' operator - the pipe character "|" if you want to activate the action stack if '''any''' of the expressions evaluates to True.

In the following example, the trigger checks for TrialNumber = 1 and FirstButtonPress variables, and then checks if Aux Button 1 or 0 was pressed:

'''ReadVar('TrialNumber') = 1.0 & ReadVar('FirstButtonPress') = 1.0 & (ReadCell('Auxiliary_Buttons', 0) > 0 | ReadCell('Auxiliary_Buttons',1) > 0)'''

'''Note''': Expressions can also be embedded into some other triggers, most notably the Set Dial >> ADO >> Forced Velocity action often used in Roadpad triggers.

'''Follow Trigger'''
[[File:isat_follow_trigger.png|150px]]

Use this trigger when something has to happen based on one ADO position relative to another scenario element (including the XD). The follow trigger requires a leader and a follower to be specified; when this condition is met, the trigger action stack activates.

'''Note''': Both leader and follower must be positioned on the follow trigger roadpad to satisfy the follow parameters.

'''Geometric Position'''
[[File:isat_geometric_position_trigger.png|150px]]

This trigger is most useful to perform actions for off-road actors such as walkers. The trigger predicate is limited to Name or Type and requires a geometric position to be defined.

A more limited version of the geometric position trigger can be implemented with a Global Time Trigger that contains a Creation Radius. Placing the creation radius defines the area where the trigger may be activate.

===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

[[File:Screenshot (208).png|800px]]

'''Note:''' The highlighted lane shows which lane is the '''activating lane'''. Other lane/s will not activate the trigger action stack.

===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

[[File:TTA.png|400px]]

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===

[[File:other_triggers.png|400px]]

*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===

Execute actions if input expression evaluates to TRUE; the expression is specified on the trigger Predicate tab.

====Syntax====
Expression triggers support a simple language syntax with operators and functions.
The syntax is infix notation; i.e. a + b, not a b +.

Note: It is not generally possible to embed one function call inside another:
cos(sin(x)) is therefore an invalid expression. ISAT will report invalid expressions during rehearsal of a scenario. Invalid expressions are not supported and will not operate as written during simulation.

'''Exception:''' Currently it is possible to use the square root function with GetObjDistPow2 as in the following example:

sqrt(GetObjDistPow2('Target_Object_Name'))

Multiple expressions may be combined using the logical AND (&) or OR ("|" pipe character).

Exp1 '''&''' Exp2, Exp1 '''&''' Exp2 '''&''' Exp ''N''

All expressions must be true for the trigger to evaluate to TRUE and execute the action stack.

Exp1 '''|''' Exp2
One of the expressions must be true for the trigger to execute the action stack.

Negative values are not directly supported by the expression parser. To use a negative value, it must be a calculated value such as the following:

'''ReadCell('CFS_Steering_Wheel_Angle',0)<(0-5.0)'''

==== Operators ====
Operators are used to create expressions.

'''String'''
:Used within quotes as a string literal; i.e., 'some string'

Grouping
:Parentheses group elements together; i.e.,
:'''()'''; (a), (a + b)

Multiplication
:'''*'''; a * b

Division
:'''/'''; a / b

Addition
:'''+'''; a + b

Subtraction
:'''-'''; a - b

Note: negative values must be expressed with a subtraction operation:
(0 - 5), not -5 (invalid)

Greater than
:'''>'''; a > b

Less than
:'''<'''; a < b

Logical And
:'''&'''; a & b

Both a and b, otherwise returns 0 (FALSE)

Logical Or
:'''|'''; a | b

a or b returns 1 (TRUE)

====Expression Functions ====
Functions are used with operators to create expressions.

Function: '''sin'''
:sin -sine

Syntax
:sin(float x)

Description
:The sin() function returns the sine of x, where x is given in radians.

Return Value
:The sin() function returns a value between -1 and 1.

Function: '''cos'''
:cos –cosine

Syntax
:cos(float x)

Description
:The cos() function returns the cosine of x, where x is given in radians.

Return Value
:The cos() function returns a value between -1 and 1.

Function: '''ReadCell'''
:ReadCell()

Read a Cell value.

Syntax
:ReadCell(string Name, int Cell Array index)

Description
:ReadCell returns the value of a given cell (a cell is the current instance of a variable that will be maybe written to a daq file).

Index specifies a 0 based index into the array. Since most cells are single element arrays, a value 0 indicates the first element.

Cells valid for the ReadCell function are defined within the cell collect file NadsMiniSim.cec located in the miniSim_x.x\data folder.
The ReadCell function operates on shared memory during simulation, it does not read cell data from the DAQ file.

Cells that are defined may be written to the DAQ; the collect file specifies which cells are saved into the DAQ and what frequency to use for the write operation.
The NadsMiniSimCollect.general.txt file is located in the miniSim_x.x\data folder.

Available Cells:
Any cell that has been defined in the .cec file. For example:

:'''LogStreams''': Array of 5 floats. Logstreams are a set of values the scenario author can write to through “write to logstream” actions.
:'''AccelPedalPos''': Single Value. The current position of the accelerator pedal
:'''BrakePedalForce''': Single Value. The current force on the brake pedal in pounds
:'''SteeringWheelAngle''': Single Value. The current rotation of the steering wheel
:'''CruiseControl''': Single Value. The current cruise control position. (values are cab/platform specific)
:'''TurnSignal''': Single Value. The current position of the turn signal (values are cab/platform specific)
:'''OvVel''': Single Value. The participant’s current speed in miles per hour
:'''OvLaneDev''': Single Value. The participant’s lane deviation in feet.
:'''OvHeadwayToLeadVeh''': Single Value. The distance in feet to the first vehicle in front of the participant. -1 if no vehicle can be found.
:'''OvTtcToLeadVeh''': Single Value. The time to collision to the first vehicle ahead of the participant.
:'''Horn''': Single Value. The state of the horn (values are cab/platform specific)
:'''DynObj_Vel''': Array of 20 floats. The speed of a given dynamic object. Dynamic Objects are sorted in terms of distance to driver.
:'''OvVelLocal''': Single Value. The participant’s current speed in miles per hour, using the value local to scenario control

For a complete list of cells and array elements please see the miniSim data dictionary spreadsheet.

Return Value
:Returns the value of the specified cell.

Example
ReadCell(‘LogStreams’,5) > 3

Function: '''CellEquals'''
:Cell Equals, array element, value to compare

Syntax
:CellEquals(string name, int index, float value)

Description
:The Cell Equals function is similar to the ReadCell function, except it adds an additional value to compare against the cell value.

Like ReadCell, name specifies the name of the cell, index specifies the cell array index (use 0 for single value cells).

Available Cells:
:Any cell that is defined in the .cec file.

Return Value
:Units: 1 or 0
:1 if the cell value is equal to the passed in comparison value; otherwise 0

Function: '''GetObjDistPow2'''
:Get object distance squared

Syntax
:GetObjDistPow2(string name)

Description
:GetObjDistPow2 returns the distance squared between the external driver and the dynamic object specified by ‘name’.

Distance squared is used to avoid having to perform an expensive square root calculation every frame.

If the specified object cannot be found, a value larger than 100 million is returned.

Return Value
:Feet; Distance in feet measured from the eye position of the driver to the CG (centroid) of the dynamic object specified.

A very large number is returned if the specified object cannot be found (larger than 100 million)

Example
:GetObjDistPow2(‘OncomingCar1’) < 2500

'''Note:''' To get an actual distance, multiply by the square root (sqrt())
: sqrt(GetObjDistPow2('Target_Obj'))

Function: '''GetObjTtcToOv'''
:Get Object Time To Collision to Own Vehicle

Syntax
:GetObjTtcToOv(string object name)

Description
:GetObjTtcToOv gets the time to collision from the dynamic object specified by the name parameter, to the own vehicle.

Return Value
:Unit: Seconds
:Time (seconds) to collision from the own vehicle to the dynamic object specified by the name parameter.
:0 is returned if the object specified cannot be found.

Function: '''GetObjVel'''
:Get Object Velocity

Syntax
:GetObjVel(string object name)

Description
:GetObjVel gets the velocity in meters per second of the first dynamic object with the name specified by the ‘name’ argument.

Return Value
:Unit: Meters per second
:The speed of the specified dynamic object; 0 if no object is found

'''Note:''' Multiply by 2.23694 for miles per hour.

Example
:GetObjVel(‘PullOutVeh’) > 15.4

Function: '''Rand'''
:Random

Syntax
:Rand(int value)
:Rand(string name)
:Rand(string name, string type, double parameter, double parameter)
:Rand(string name, string type, int parameter, int parameter)

Description
:Rand returns a random value specified by the name of the generator, the type of distribution and its parameters.

If the user does not specify the name of the generator and only specifies a number as the only parameter, the Rand function will use a default random number generator to produce random numbers.

If the user only enters the name of a user created random number generator, the random number generator will produce a value between 0 and 1.
If a name of generator is supplied that has not been created, the Rand function will display an error message in the ISAT debug window and return 0 (during scenario rehearsal).

The rand function supports multiple types of distributions that can be used to generate a random number.

Types of Distributions:
:normal: Normal Distribution(mean, standard deviation). The normal distribution generates random numbers near the mean with a specific standard deviation.
:gamma: Gamma Distribution(alpha, beta). The gamma distribution generates a random value that models waiting times for the Poisson process.
:uniformInt: Uniform Integer Distribution(min, max). The uniform integer distribution generates a random integer number between the lower and upper bounds.
:uniform: Uniform Real Distribution(min, max). The uniform real distribution generates a random floating point number between the lower and upper bounds.

The values stated in the parenthesis above are the parameters for each distribution in order. If the incorrect number of parameters are entered or if they are entered incorrectly, the debug window in ISAT will display an error message and the rand function will return 0 (during scenario rehearsal).

If the distribution is entered incorrectly, the debug window will also display an error message.

Return Value
:A random value from 0 to 1 if the type of distribution is not specified.

If the type of distribution is specified, returns a random value determined from the type of distribution and the given parameters.

Example
:Rand(‘myRandGenerator’,’uniformInt’,1,10)
:This example returns a random integer value from 1 to 10.

Rand(5) or Rand(‘myRandGenerator’)
:These examples return a random value between 0 and 1.

Function: '''sqrt'''
Square root

Syntax:
:sqrt(parameter)

Return Value:
: return the square root of the specified parameter.
: parameter can be another function, such as GetObjDistPow2()

Function: '''ReadVar'''
:Read a variable

Syntax:
:ReadVar(string Name)

Return Value:
:Returns the string value of variable specified in <variable_name>

===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.

=='''Audio Components'''==
The components of the Audio sub-system includes configuration and data files installed into the NadsMiniSim_x.xx\data\sound\DefaultCabSound\Instructs folder.

[[File:audio_components.png|400px]]

The audio engine contains multiple channels and has a theoretical limit of 512 simultaneous sounds.

NOTE: Not all .wav files are compatible with the Audio Engine.

=Scenario World Objects=
Scenario world objects are defined in the tile model source. They are not added by the scenario author since they are objects already present in the roadmap/BLI.

[[File:object_types_world.png|400px]]

Typically, but not always, these objects can be authored in ISAT. However, some scenario world objects have no options - these cannot be selected in ISAT; therefore such objects cannot be authored.

Removal of world objects requires editing the source tile model using a 3D application. In some cases an alternate tile model is available identical to the original but without objects.

Contact NADS if removal of a world object is needed.

Other scenario world objects, such as Traffic Signals, are specialized function objects that can be authored. Traffic signals are authored using the Traffic Light Manager: Edit >> Traffic Light Manager.

=Troubleshooting Scenario Objects That Reset=

== Scenario World Objects ==
Scenario world objects are already present when you create a new scenario - they are not added by the scenario author. These objects may be visible in miniSim but not in ISAT, or they may be visible in ISAT and seem to be controllable, but the objects 'reset' to their defaults when viewed on miniSim.

[[File:2019-10-23_16h18_47.png|700px]]

The objects which 'reset' are a symptom of settings in the TMT that are not configured to allow scenario authoring of objects.

[[File:2019-10-23_16h18_52.png|700px]]

When objects appear to 'reset' or if you can edit an object in ISAT but don't see your changes in miniSim, correct the problem by resolving controllability in the TMT settings: https://www.screencast.com/t/ZH5Dh178.

=Scenario Coordinate Types=
There are two types of coordinates used in scenarios. The first is roadway coordinates. These coordinates are contextual (tied to a specific road or intersection and position) and are used for ADO objects and roadpad paths in general.

After a roadway coordinate has been generated, it is not updated unless the scenario author makes changes to the start, end or location of the entire path or pad.

Roadway coordinate are the reason it is not possible to change a roadmap using the TMT and expect a previously authored scenario to work on the altered roadmap. If the length or location of a road changes, the path/pad will update to the extent possible.

If the road has been eliminated and no longer exists in the roadmap/BLI, ISAT will report an error and not open the scenario file.

A. Field breakdown:
RoadPos keyword <name of road:lane:position on road:path length>

Name "Ado1"
RoadPos "r1_-6600_4620:0:5737.06:0.00"
Path "R:r1_-6600_4620:0[5736.06:5873.83]"

[[File:isat_coordinate_types.png|400px]]

B.
Name "VirtObj"
Option 2
Position -6.8375599E+002 5.6331237E+003 0.0000000E+000

The second type is world coordinates, which are Cartesian coordinates with X increasing to the right, Y increasing forward, and Z increasing up.

='''Scenario Authoring'''=
Scenario authoring is the creation, editing and testing of everything that happens during a simulation drive.

==Cell Operations: Best Practice==
Reading and writing to cells is a computationally expensive process. Best practice is to centralize all the reads/write to one place so that it’s only done once per cell.

Once a cell is read, the value is copied to a variable and only the variable is used throughout all the triggers that need it.

The same process applies to writing to cells. Use of variables can reduce the Cell Operations overhead greatly.

==Before You Begin==
Before beginning a scenario, it is necessary to understand the following requirements:

=== Drive Requirements===
How long is the drive?
What type of roadway?
Are there any specialized road elements (intersections, interchanges, freeway ramps)?
Are there any environmental requirements (should the simulation replicate a real world location, or is a generic environment acceptable)?
Is there a particular roadway configuration that is needed (long straight rural road vs. typical urban environment with intersections, signals, etc)?

=== Traffic Requirements ===
What types of traffic will be needed?
Will ambient traffic interact with the external driver?
What types of interaction will be required (traffic cloud, lead vehicle, follow vehicle)?

=== Events ===
The purpose of an event is to present a situation to the external driver. In order for the simulation to produce meaningful data, it is critical that events unfold for each driver in a comparable way. Therefore, each event must be designed with this repeatability in mind.

'''NOTE:''' one of the most variable scenario elements is the driving style of each external driver: how conservative or aggressive they drive, velocities throughout the scenario, how comfortable the driver is travelling with simulated vehicles, etc.

Repeatability often includes static elements (each driver encounters scenario elements in the same location) or in cases where the driver performance is taken into account, accommodation of the driver dynamic (velocity, lane position) through the use of time to arrival triggers (TTA) or follow triggers. A TTA trigger will fire based on time to a target location - thus a driver travelling at 45mph or a driver travelling at 55mph can both experience the same action relative to that target location, irrespective of the different driver velocities.

==Beginning A Scenario==
All scenarios designed to be driven require a start location - the place where the driver will be located when the simulated drive begins.

To insert a start location into a scenario:

:Insert >> External Driver >> LMB on road, intersection or terrain object

[[File:isat_initial_position.png|400px]]

'''NOTE:''' scenarios that only contain data and are not intended to be driven - for example, signs or traffic that are used as external reference files do not require a start location, since that will be defined within the parent scenario.

==Initial Conditions==
Initial conditions define how the simulated scene is configured: will the drive occur during daylight or night time conditions? Will the ownship (external driver vehicle) have headlights enabled? What type of vehicle will it be? Will there be objects or traffic visible to the driver?
These form the initial conditions of the simulation experience. Additional initial conditions would include initialization of variables or establishing networked communication as needed by the scenario.

[[File:isat_initial_conditions_miniSim.png|400px]]

By default ISAT sets the initial condition '''Time of Day''' to 12:00 noon. The time of day is controlled from the Initial Conditions dialog:

Edit >> Initial Conditions

[[File:isat_initial_conditions_scenario.png|400px]]

==Scenario Authoring: Actions==
Actions are the scenario elements that make things happen during simulation. Actions do specific things, like display a text message on screen for the driver, create a scenario element, change the velocity of simulated traffic, change a traffic signal, etc.

[[File:trigger_action_panels.png|400px]]

The diagram above shows the action panel for left to right: an expression trigger, a roadpad trigger and a global time trigger showing different panels based on the actions present in each trigger.

'''NOTE:'''Actions can be created, edited or removed from the '''Actions panel''' of '''any trigger'''.

'''NOTE:''' The Actions panel changes based on the action type created.
When multiple actions have been defined, control the sequence of actions by changing the action order in the list using the up or down arrows next to the list.

[[File:action_panel_overview.png|400px]]

If multiple actions need to happen in a specific order, set the order using the arrows and then flag the action list as '''sequential'''. This instructs behaviors to process the actions in the list order.

Using a delay for any action will pause processing of the '''following actions'''; the action happens first, then the delay is applied.

===Scenario Authoring: Action Types===
There are two types of actions:
# Instantaneous - the action takes up to one frame to complete, i.e.:
:set target velocity
:write to cell
# Persistent
<span style="color:red">'''*Persistent actions do not end'''</span>, or take multiple frames to complete:
:Forced lane offset
:Forced velocity
:Maintain Gap

==='''Actions'''===
*The "Who to Affect" field defines what is affected by the action
:Instigator set: who activated the trigger
:Name: one or more named elements
:Type: Apply changes to all objects matching the specified type
:Relative: Position relative to the trigger location

*Sequential
:Actions to execute sequentially, one after the other
:Specify delay between actions
:: Action executes, then delay

:Some actions are persistent and never "finish"

===Scenario example: display text & roadpad trigger to stop the drive===
This scenario is very simple and contains a global time trigger (GTT) that tells the driver what to do. After the driver travels along the roadway, a roadpad trigger (RPT) is used to tell the driver to stop driving. The same RPT also creates an expression trigger to terminate the drive.

TBC example scenario file

Because the external driver is not under control except by instructions, it's possible they might ignore the halt message and continue driving. A second failsafe RPT then terminates the drive.

==='''Actions: Button vs. Dial'''===
*Dial changes a setting
*Button: always runs in a single frame
:-"immediate" change. Typically buttons have less control than a '''Set Dial''' action

==='''ADO Actions'''===
[[File:ado_action_types_button_vs_dial.png|400px]]

==='''DDO Actions'''===
[[File:ddo_set_dial.png|400px]]

==='''External Driver Actions'''===
External driver behavior can be influenced by reinforcing scenario actions through audible speeding alerts, on-screen text instructions and messages or audio instructions.

Driving behavior can be influenced with situational elements
:Car in the drivers blind spot
:Lead vehicle
:Aggressive following vehicle
:Temporary lane closure
:lane specific instructions

Scenarios should '''not rely on specific driver actions to be successful'''
:to the extent possible; sometimes you do need the driver to respond/behave in a controlled manner.
:A work zone blocking one lane typically will require a roadpad placed upstream from the work zone to shift traffic into the correct lane

'''NOTE:''' Controlling driver actions should be an experimental design consideration.

==='''Special Actions'''===
These actions need special handling:
*Reset or "toggle":
:Audio
:Display Text

:'''Ado'''
::Audio State
::Forced Velocity
::Maintain Gap
::Visual State

*If using these persistent actions, place them at the '''end''' of an action sequence (because no action following these will execute):
:Forced Lane Offset
:Forced Velocity
:Maintain Gap
:Visual State

*Note: If the Visual State action contains a duration then it will be handled as a normal action, with subsequent actions firing after it. However, if there is no duration supplied with the Visual State action it behaves like a persistent action, and nothing following it in the Action stack will ever fire.

[[File:multiple_simultaneous_actions.png|400px]]

The diagram above shows how one parent trigger can be used to create multiple simultaneous triggers

*How to activate multiple unique force velocity (FV) or maintain gap (MG) actions:
#create the needed triggers from a general parent trigger, 1 per action
#put common actions into the parent trigger
::reset FV
::reset MG

==Scenario Authoring How To==
This section contains simple examples for various typical scenario situations.

===How do I specify an event?===
First, determine which method is best for you - the default measures (limited measures, 20 events max) or logstreams (all simulation data, no event maximum).

Regardless of method, you specify an event by identifying areas of significance in the drive and marking them so the data within the event region can be processed. Any trigger combination that can specify event start and event end may be used.

[[File:2022-07-01_11h21_52.png|400px]]

===How to know Which Coordinator or Trigger I need?===
The answer to this question lies in the type of information needed for an event:

*Time
:global time trigger
:or an expression trigger that calculates time
*Position or Location
:roadpad trigger
::or a time to arrival (TTA) trigger
::or an expression trigger that calculates distance
*Calculation
:Expression trigger

===How to Instruct the External Driver===

Instructions to the external driver can be accomplished by three main methods:
# Instruct the driver using experimental protocol (instructional or briefing presentation)
# Information messages displayed on screen: '''Action: ''set visual display text'' '''
# Information messages delivered as audio messages: '''Action: ''write to cell > SCC_Audio_Trigger ><audio ID>'' '''

===How to Add Traffic in the Scene ===

Generating traffic will happen in one of 5 ways:
# Created explicitly by inserting ADO, or copy/paste existing ADOs
# Created with a script
# Via a Create action inside a trigger, or placing scripted traffic inside a create action within a trigger
# From a '''Traffic Source'''*
# From the '''Traffic Manager'''**

Each of these methods has advantages and disadvantages.

==== Create Explicitly ====

The biggest advantage with this method of traffic creation is the high degree of control the scenario author has over:
# location of the created ADO
# Name of the created ADO
# Travel path of the created ADO
# Control when each ADO is created within the scene via Settings >> Creation Radius

The disadvantage is that creating a high volume of traffic will take some work with this method.

==== Created with a Script ====

This method combines the advantages of Creating Explicitly with volume. It is possible to create a large volume of traffic very easily with a script.

Disadvantages of using high volumes of traffic with a script: in the event it becomes necessary for a high degree of control over these ADOs, more is not better because ADOs will adapt to road conditions under their own power, unless the default ADO settings have been modified:
'''lane changes, including lane changes to accommodate freeway ramps'''
'''velocity adjustments'''

==== Via a Create action inside a trigger ====
Combines the advantages of the previous 2 methods with control over when to activate that traffic using a trigger action.

Disadvantages: Creating too many ADOs at one point in the drive can cause the miniSim to bog down for a few frames. If too many ADOs are present and active in the simulation at one time, this can cause the miniSim to drop frames and run sluggishly. This is highly noticeable and may increase the potential for the External Driver to experience '''simulator sickness.'''

==== From a '''Traffic Source''' ====

Traffic Sources rely on two methods to populate a scene with traffic:
# location specific, with each ADO created for a traffic source being a 'spawn location' for ADOs, or
# location agnostic if the ADO has '''relative creation''' enabled, thus being created relative to the object identified.

In addition to being created relative to a scenario element, ADOs are created relative to the specified scenario element:
# In front of (Longitudinal Distance > 0, where the number is feet offset from the object) , or
# Behind (Longitudinal Distance < 0, where the number is feet offset from the object).

Advantages: Can easily populate traffic into the simulation.

Disadvantages: It is easy to generate more traffic than the simulation can maintain at 60Hz frame rate, thus introducing frame lag with the resulting scene 'stutter' and the increased risk of simulator sickness.

Also, traffic created from a Traffic Source is generic traffic. It is not possible to reliably refer to specific ADOs generated from a traffic source except by using Who To Affect >> Relative (versus referring to a named ADO, i.e. Slow_Moving_Lead_Vehicle). Referring by name to Traffic Source generated ADOs will affect all similarly named ADOs at the same time.

==== From a '''Traffic Manager''' ====

The traffic manager interface is problematic in ISAT versions up to 1.8.5, especially when specifying the set of vehicles to be used for generating traffic.

Advantages: Create generic ambient traffic easily.

Disadvantages: Has the same disadvantages as traffic created via a Traffic Source. Also getting a traffic set working by specifying the vehicles to be used within the set. ISAT versions up to 1.8.5 exhibit instability when setting vehicles in ISAT.

Traffic Manager Set workaround: Borrow a working set from an existing scenario or group. Alternatively use a version of ISAT (1.8.6 +) to create the traffic set. This can be saved as a scenario or group file, which can then be used with ISAT 1.8.x as long as there is no attempt to adjust the vehicle weights within ISAT. The scenario or group file can be edited as text in a text editor, but care must be exercised to avoid introducing errors into the file. ISAT will not read invalid scenario or group files.

Traffic generated by the Traffic Manager is controlled through the use of Input Sets. An input set is a collection of vehicles and weights used to populate the scene during simulation. This is how the scenario author can control the vehicle population (type and number), density and creation/deletion distances - these attributes are unique to each set.

Since there is no 'discontinue traffic manager' function, one can be implemented by defining an input set with no traffic (an empty input set). An appropriate name can make the purpose of the set clear: PauseTraffic, Stop_TM, etc.

==== Sample Traffic Manager Set ====
This is a sample traffic manager set that can be pasted into a scenario file after the HCSM VehFail section. Be sure to paste '''after''' the HCSM VehFail end tag ('''&&&End&&&''') in your scenario file.

'''Note:''' A scenario file may contain only '''one''' Traffic Manager section.

There are two input sets in this example; note how they contain different vehicles and different settings from each other.

<span style="color:#2a4b8d">HCSM TrafficManager
GroupName "Traffic Manager"
HCSM InputSet
Name "ONE"
MinDensity 3.0000000E-002
MaxDensity 7.0000000E-002
MaxObjects 9
CreateDist 2.0000000E+003
DeleteDist 3.0000000E+003
AbsDeleteDist 3.4000000E+003
RunFreq 1.0000000E+000
SolWeights "cargill_semi_peterbilt_blu:2" "cargill_semi_freightliner_red:1" "cargill_semi_peterbilt_yel:3" "DumpTruck_org:3" "semi_peterbilt_yel_Walmart:2" "Cadillac_Escalade:10" "Ford_F150Xcab:15" "Saturn_Vue:10" "FordTaurus:15" "Escape:15" "DumpTruck:2"
&&&&End&&&&
HCSM InputSet
Name "TWO"
MinDensity 1.0000000E-002
MaxDensity 3.0000000E-002
MaxObjects 4
CreateDist 2.5000000E+003
DeleteDist 3.3000000E+003
AbsDeleteDist 3.5000000E+003
RunFreq 1.8000000E+000
SolWeights "Taurus2011:12" "Cadillac_Escalade:16" "Ford_F150Xcab:24" "Saturn_Vue:14" "Escape:6" "Deville:24" "Audi:4"
&&&&End&&&&
&&&&End&&&&
</span>

====='''Managing Traffic Manager Input Sets'''=====
During simulation, Input sets are controlled by the action '''Use Traffic Manager Set'''. A set name must be provided for this action to work.

===== Traffic Manager generated Traffic=====
ADOs will populate the road network around the XD based on the parameters of the Input Set. Typically traffic is removed from the scene shortly after passing the XD. This is visible in the rear view mirror. There is currently no way to adjust this delete distance.

====== Traffic Manager Traffic on 2 lane freeway======
Traffic will prefer to be in the XD lane, so ADOs created in any other lane will tend to veer into the XD lane. On a divided highway, traffic is generated moving with the XD.

====== Traffic Manager Traffic on 2 lane road======
Traffic is generated in the oncoming lane. In some cases traffic may be generated then immediately removed in front of the XD.

===How to Control Objects in the Scene during Simulation ===
"Set and forget" options on simulation entities only require the scenario author to "initialize" the element to a desired setting and then it is left alone during simulation.

Controlling objects dynamically during simulation requires the scenario "talk to" each object with a scenario action. This section describes how each scenario object type can be controlled during simulation within a scenario.

All models used in ISAT are listed within the Scenario Object Library (sol2).txt files. Terrain switch names are displayed in the ISAT workspace.

All model switches are listed within the NadsMiniSim_x.x\bin.x64\ModelList.txt file.

'''Note:''' The diligent reader will note discrepancies in model names between the sol2 and ModelList files. This is because the ModelList file contains actual file names, and the sol2 files define a "name label" for models that may, or may not, be the actual model name. Objects are linked between the sol2 and ModelList files through the ModelID/CigiID records. These values will match between sol2 and ModelList files, but IDs are not necessary at this time for scenario authoring purposes.

Complicated object names can be retrieved from the LRI file that was used to build any scenario file; each BLI is preceded by an LRI. The LRI contains all of the terrain models that will be present in ISAT. These are typically speed limit signs, traffic signals or other features that may be controllable.

'''Note:''' this file may not be present for the Springfield.bli file.

An alternative is to capture a screenshot of the ISAT workspace with the element name string showing. By default ISAT reports the name of any objects when the cursor passes over the object, as shown in this example:

[[File:2021-10-27_08h50_14.png|caption =Object Name Screenshot | 400px]]

{|class="wikitable"
|+ Controlling Scenario Elements During Simulation in Scenario
!Date
!Nads miniSim version
!Object Type
!Scenario Action
!Who To Affect
!Value
!Notes
|-
| Oct. 28, 2021
|2.3
|-
|
|
|Static Object (terrain)
| SetDial > StaticObjManager > Set Option1
| StaticObjManager
| switch name : switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
|Static Object, multiple options
| Set Switch
| Name of element
| switch option
|-
|
|
|Obstacle, multiple options
| Set Switch
| Name of element
| switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
| DDO, multiple options
| Set Switch
| Name of element
| switch option
| Switch names are listed in bin.x64\ModelList.txt
|-
|
|
| ADO
| Set Dial > ADO > VisualState
| Name of element
| Limited to options present in ISAT
|-
|
|
| Traffic Signal
| Traffic Light
| Assign action to element
| Target state
| Target state must exist within the Traffic Light Manager intersection timing table for the specified signal

|}

===How to Control Simulated Vehicles===
The scenario author can control simulated vehicles by controlling the environment:
#change a traffic signal to cause an ADO to stop or start at intersections
#affect other ADOs to cause a target ADO to respond
# assign a path for the ADO to travel

Direct control:
*Lane related:
:Set button > ADO > ChangeLane, Turn, ProjectAndResetLane

*All other controls:
:Set Dial > ADO > AudioState, ForcedLaneOffset, ForcedVelocity, InhibitLaneChange, LaneChange, MaintainGap, TargetVelocity, VisualState, AudioState

====How to Change ADO Velocity====
ADO velocity can be changed using the SetDial action:
:SetDial > ADO >

:ForcedVelocity
:ForcedVelocity using an expression:
# match external driver speed
expr % OvVel(0) %
# multiply external driver speed
expr -1 9 %ReadCell('OvVelLocal',1)*1.75 %
:TargetVelocity

Indirect Control (dependent on other scenario element):
:MaintainGap

====How to Link ADO Velocity to Something Else====
ADOs velocity can be linked to other ADOs or the external driver using the MaintainGap (MG) action.

SetDial > ADO > MaintainGap

When using a traffic cloud containing multiple ADOs, each ADO in the cloud needs a unique MG. IF multiple ADOs have the same MG settings they will attempt to satisfy their parameters and likely oscillate position in a visually obnoxious way.

===How to Author Loop Scenarios===
A scenario created on a loop road network operates very much like any other scenario, with the exception that it is likely to require tracking the number of times through the loop, or to present scenario events to the external driver depending on each loop context.

[[File:loop_traffic_creation_01.png|400px]]

The simplest method of tracking loops is the use of a loop counter variable. This variable can be set by the driver "stepping onto" a roadpad trigger or it can be initialized through the use of a timer or expression, with increments managed by a roadpad trigger. Each time through the loop increases the loop count variable.

Thus it becomes possible to create events for each loop based on the loop counter variable, typically through an expression trigger.

Loop management triggers

[[File:loop_management_02.png|400px]]

Loop management trigger detail one

[[File:loop_management_vars_02b.png|400px]]

Loop management trigger detail two

[[File:loop_management_3.png|400px]]

====Creating Loop Specific Traffic====
Creating loop traffic is slightly more complicated due to the number of objects to be created and potentially the size of the actual loop. A small loop is installed with the Nads miniSim as simple_rural1 or simple_rural2. Each is a loop road network with two signed 3-way intersections.

Loop specific traffic can be created through the use of a variable (i.e., LoopCount) or within the roadpad trigger that is incrementing the loop count variable. Both methods will incorporate a '''Create Action''' that creates the required elements.

===How to Change Environment Settings===
The scenario author can define global or localized environment conditions.

1. Insert >> Environment Conditions >> <chosen condition>

2. Define a region where the environment condition is active:
:LMB to define polygon points
:RMB to exit point entry mode

[[File:env_condition1.png|400px]]

Choosing an environment condition

[[File:env_condition2.png|400px]]

Environment region defined and parameters panel shows available options

NOTE: The environment condition boundary is a discrete threshold. Condition A will be on one side of the threshold. Immediately after crossing the boundary, condition B will be displayed.

===How to Fade an Environment Condition===
To fade gradually between two conditions requires the use of an expression that continually monitors the desired condition and sets a few variables based on the results.

Examining the demo scenario is the best way to look 'under the hood' to see exact command syntax and values to be used.

[[File:env_fade.png|400px]]

Note: this approach has been used for fog and visibility. It is unknown how it might work with non-visibility conditions such as precipitation and wind.

*From the scenario demo_visibility_transition.scn

[[File:env_fade_schematic.png|400px]]

'''Note:''' although the example above uses an environment condition boundary, '''it is possible''' to omit the defined region, retaining all commands and the scenario will still function. However, without the environment region, it becomes more difficult to determine where conditions are different from the standard settings.

===How to Control a Cab Instrument Panel icon===
In order to control the instrument panel, there are 2 requirements:
The specific cab used for the scenario
The specific control (switch) to be manipulated
The action for addressing the instrument panel is '''ChangeCabSetting'''

Instrument panel models are located in NadsMiniSim_x.x\data\Visuals\Instruments
These files are in OpenFlight format. Any 3D editor capable of reading or importing OpenFlight can be used to review these files. NADS uses the Presagis product Creator[tm].

An alternative method to inventory switches is to use the the '''buildscl.exe''' tool. To run the tool, open a CMD window to the IP folder location above, then run the command:
buildscl <input_file.flt><Enter>.
<input_file.flt> is the name of the file to process, without the '<>' characters.
<Enter> means to press the Enter key,

The result will be in a new file ending with .scl. This is a text file, and can be opened in a text editor or you can use the shell utility '''more''' to view the file contents:

more <input_file.scl> | grep switch<Enter>

An example for the malibu cab is shown below. .

switch s_LowWasher 0
switch s_Cruise 1
switch s_LeftTurn 2
switch s_RightTurn 3
switch s_FwdCollisionWarn 4
switch s_BlindSpotWarn 5
switch s_LaneDeviationWarn 6
switch s_RearCollisionWarn 7
switch s_HighBeamHeadlights 8
switch s_SeatBelt 9
switch s_UpArrow 10
switch s_Airbag 11
switch s_CheckEngine 12
switch s_CheckGuages 13
switch s_ABS 14
switch s_Brake 15
switch s_LowFuel 16
switch s_Gear 17

These controls may be accessed directly in scenario using the ChangeCabSetting action.

'''NOTE:''' Some functions such as Cruise, Gear, High beam headlights, Blind spot, collision, lane deviation warnings are '''normally''' controlled not by direct access as described here but by hardware mechanisms/buttons.

'''NOTE:''' For altering cab instrument panel operation it will be necessary to modify the OpenFlight model to include the desired funationality; for example, instrument panel blanking is not build into the model but can be added by editing the cab instrument panel model file then installing the modified file into miniSim.

===Scenario Hints===
The total number of scenario elements active at any given time can affect simulator performance:

Total number of active elements
*vehicles (ADOs), triggers, animations, etc.

Object management
*Use paths to shift ADOs away from the driver route of travel as they turn off the route
*reduce the number of vehicles in traffic cloud surrounding external driver
*use creation radius to limit the number of active elements, and to remove elements after the driver has traveled beyond the creation radius

[[File:creation_radius_1.png|400px]]

Creation radius works by activating the scenario element only when the driver is within the radius. The scenario element is created when the driver enters the creation radius, and is deleted after the driver leaves the creation radius.

Exploit environment to reduce object load

*Use curves, hills, intersection corners to mask objects

Object deletion
*Remove objects when no longer needed

When creating dynamic elements, create them as close to where they are needed as possible.

====How to Determine When ADOs are Visible to the External Driver====

Some development/setup testing may be needed to determine precise location/distance/speed; i.e., locating ADOs for a freeway ramp merge event where the external driver is merging onto the freeway with other ambient traffic present.

Unless the purpose of the event is to study driver behavior at the merge, ideally the scenario will be authored to have ambient traffic on the freeway but not to present a conflict at the merge for the external driver.

A straightforward way to determine where the ADOs are first visible to the driver is to mock up a scenario placing colored ADOs along the freeway with a velocity of 0. This will ensure the ADOs remain stationary while the scenario author determines where they are first visible to the external driver.

Place the start position/external driver far enough up the ramp to be a reasonable test for the actual scenario.

As you drive the ramp, see which ADO is first visible to the driver. Place ADOs just out of view (upstream) of that location.

[[File:merge_hint.png|400px]]

'''NOTE:''' use test vehicles of the same type and character as the intended scenario vehicles. For example, do not use a sedan test ADO for a larger vehicle (SUV, bus, dump truck). Doing so will invalidate the visibility test, because a larger ADO will be visible over a longer distance than a small ADO.

[[File:ramp_vis_1.png|400px]]

At the scenario start location, ADOs in front of the Coke truck are visible. Note how the larger vehicles are more obvious at this distance.

[[File:ramp_vis_2.png|400px]]

The driver has traveled onto the ramp. At this point, the last ADO visible to the driver is still the Coke truck.

[[File:ramp_vis_3.png|400px]]

As the driver travels farther down the ramp a small ADO is visible behind the Coke truck.

The answer to the question '''When is an ADO visible?''' is thus:
#It depends on how large the ADO is
#Small ADOs can be placed at the location of the red ADO behind the Coke truck.
#Large ADOs may need to be placed farther back (behind the red ADO). This test is inconclusive, but based on the terrain it seems likely that large ADOs would need to be placed at least at the green ADO location (behind the Coke truck).

Creating small ADOs at the green ADO location when the external driver is located at the ramp position in 3 travelling at the same speed as the external driver should arrive at the merge slightly ahead of the driver (because the curved ramp is longer than the straight freeway).

'''NOTE:''' ADO size, ADO color, time of day and visibility settings affect ADO visibility.

====How to Position Objects Precisely using '''Place Object At..'''====

ISAT does not support true precision because it is not currently possible to 'dial in' a position as is typical in 3D modelling tools, but there is a way to approximate precision in cases where a consistent measurement is desired.

In the following example a number of roadpad triggers are placed relative to the location where a roadway enters an intersection. This is a discrete boundary within the simulation world as shown in ISAT.

There are two methods of placement possible:
# Measure the desired distance (CTRL+Shift+RMB, drag); take note of the coordinates updating in realtime and make a mental note of the desired location.
#Place an object (ADO or static object); use the Place Object At.. feature from the context menu when you RMB on a scenario object.
Using this method you can specify a distance - positive numbers move the object downstream/forward, negative numbers move the object upstream/backward.

'''Note:'''If the distance is significant and extends over an intersection, ISAT may produce unexpected and undesired results such as re-starting the measurement from the closest upstream intersection, thus placing the object where it was not intended.

In the following example, Place Object At.. is used to specify a point 50 feet upstream from the road/intersection border.

[[File:precision_placement_1.png|400px]]

A roadpad trigger has been positioned near the area of interest. Any existing roadpad is deleted from the trigger.

[[File:precision_placement_2.png|400px]]

An ADO is used as a marker object inserted temporarily into the scenario. Any convenient object may be used.

'''Note:''' large objects such as ADOs may be less precise than small objects such as the Traffic cone, but is generally easier to access in the ISAT interface unless you have created a script for cone objects.

[[File:precision_placement_3.png|400px]]

RMB on the ADO to access the Place Object At.. request dialog. Only numbers are valid entries.

[[File:precision_placement_4.png|400px]]

The desired distance is entered into the Place Object At.. request dialog. ISAT will then require you to select the object you wish to move using LMB.

[[File:precision_placement_5.png|400px]]

ISAT moves the selected object by the distance you specified.

[[File:precision_placement_6.png|400px]]

Use the ADO CG (model center) to place the start of the road pad.

[[File:precise_placement_7.png|400px]]

Remove the ADO marker and save your scenario.

==Scenario Testing and Debugging==
The primary way to test and debug scenarios is using ISAT rehearsal mode.

'''NOTE:''' the external driver during rehearsal is a simulation. You have limited control over the simulated ownship:
#change speed
#change lane

ISAT has two rehearsal dialogs:
#abbreviated (standard) dialog
#advanced (extended dialog)

===How to change to the advanced rehearsal dialog===
Often it is necessary to control the ownship during rehearsal. The ownship controls are located in the advanced (extended) rehearsal dialog.

ISAT will show the Advanced dialog the first time rehearsal mode is activated. All additional activations show the abbreviated dialog.

TBC abbreviated dialog

To use the Advanced dialog, LMB the Advanced button.

TBC Advanced dialog

===How to change ownship speed during rehearsal mode===
After entering rehearsal mode:
#click the Play icon (start the rehearsal)
#pause.
#adjust ownship speed
#toggle pause off (resume rehearsal)

===How to make ownship lane change during rehearsal mode===
After entering rehearsal mode:
#click the Play icon (start the rehearsal)
#click the desired Lane Change (left or right)

===How to Use Audio in your Scenario===
Scenarios play audio sounds and messages through a write to cell action: '''SCC_Audio_Trigger'''

Use of audio in a scenario typically requires both a write to cell and a 'clear action' that writes a zero (0) to SCC_Audio_Trigger in order to 'clear the channel'. The 'clear' action can happen before or after playing a sound; choose one method and be consistent in your scenario authoring.

Failure to 'clear the channel' or '''not''' writing a value of zero can result in no audio being played for subsequent write to cell SCC_Audio_Trigger actions.

The following shows how this looks in scenario when executed from a roadpad trigger (RPT):

[[File:audio_scn_A.png|400px]]

The above diagram is shown below in text format:

HCSM RoadPadTrigger
GroupName "WindGust_Audio"
ByTypeSet "ExternalDriver"
NthFromStart 0
NthFromEnd 0
VehicleAhead 0
VehicleBehind 0
LongComment "This is a wind gust event"
ShortComment " "
ActvDel 0.0000000E+00
CrRad 0.0000000E+00
Debounce 0.0000000E+00
FireDelFrames 0
Lifetime 0.0000000E+00
Name "RPT_WG_6"
OneShot 1
Priority 0
SeqAct 1
Position 6.7165800E+04 6.0419215E+03 0.0000000E+00
DrawPosition 6.7165800E+04 6.0419215E+03 1.1308095E-317
Path "R:r3_62700_7920:0[3033.04:3245.46]"
HCSM LogData
Comment "LS1=8"
Delay 0.0000000E+00
InstigatorSet 0
Stream 1
StreamVal 8.0000000E+00
&&&&End&&&&
HCSM WriteCell
Comment "Play_Audio"
Delay 2.0000000E+00
InstigatorSet 0
CellName "SCC_Audio_Trigger"
CellData "63000"
CellType 2
CellVar 0
&&&&End&&&&
HCSM WriteCell
Comment "clear_audio"
Delay 0.0000000E+00
InstigatorSet 0
CellName "SCC_Audio_Trigger"
CellData "0"
CellType 2
CellVar 0
&&&&End&&&&
&&&&End&&&&

===How to Add Custom Audio Instructions to miniSim===

''' Please note: Custom audio 'instructions' for a scenario should be added to the instructions.txt file.'''

These are sounds that are played in scenario, typically as directions for the minSim driver.

Adding custom audio files requires the following procedure:

1 Exit miniSim - changes to the miniSim configuration should happen only when miniSim is not running.

2 Copy the audio .wav file to:
:C:\NadsMiniSim_x.x\data\sound\DefaultCabSound\Instructs

:Edit the file instructions.txt in that same folder.

3 Add an entry to instructions.txt to register your audio file in accordance with the following layout using the existing entries as a template:

:Unique_ID Filename Normalized_Volume

:Unique_ID is whatever unique number you assign to your file.

:Filename is the name of your .WAV file.

:Normalized_Volume is the volume your audio file should play, where 0.00 is silence and 1.00 is maximum volume.

'''NOTE: Remove all spaces in your audio filename.''' If needed, use the underscore character instead of spaces.

===Troubleshooting Custom Audio Additions===
After installing new .wav files and adding them into the audio configuration file '''instructions.txt''', if the audio file does not play:
*Check the Audio Engine window while miniSim is still running. The Audio Engine will display file errors,.
*If Audio Engine does not display a message similar to: Audio Engine loaded normally, scroll through the window messages and look for any .wav or load error messages.

==Re-use of Scenario Elements==
Scenario authoring can be an intensive undertaking. It makes sense therefore to leverage your development efforts by re-using scenario elements where possible.

ISAT provides a number of ways to re-use scenario elements:
# copy/paste
# external references
<span style="color:#ac6600"># exporting elements as '''groups'''</span>
# isc scripts

Each of these methods have their strengths and weaknesses.

===copy/paste===
The simplest method to re-use scenario elements among different scenario files is copy/paste. This is possible for most scenario elements* even if the source and destination roadmap/BLIs are radically different.

[[File:copy_paste.png|400px]]

It is also possible to copy an ISAT element from one scenario to another as '''TEXT''' by selecting the element and using the windows copy shortcut CTRL-C, then open a text file and paste it using the windows paste shortcut CTRL-V.

'''NOTE:''' Traffic sources are '''not''' portable using copy/paste.

'''NOTE:''' Not all elements can be copy/pasted. Elements created from a Create Element action cannot be copied - it is necessary to select the parent element and copy that instead.

[[File:copy_paste2.png|400px]]

In the above diagram, elements at '''B''' and '''C''' cannot be copied/pasted because they have been created by element '''A'''. It is necessary to copy the element at '''A''' instead. If only the elements at B are needed, the best method will be to copy/paste as Text.

'''NOTE: ISAT will not copy elements containing road coordinates (elements with a path) to a scenario that does not share the same BLI as the source (copy from) scenario.'''

A partial solution to such cases is to remove the path first, copy the element, paste into the destination scenario, then re-create the path manually.

===External Reference===
An external reference scenario is intended to be re-used by multiple 'parent' scenarios. The effort of authoring objects is thus leverages across multiple files, without needing to re-create the same elements more than once.

[[File:re_use_xref_1.png|400px]]

Common uses of external references include traffic, traffic signal operation, traffic sign appearance or other environment features which have multiple appearances (billboards, some tile related scenery, etc).

NOTE: Multiple external references are possible; but because objects are categorized by group, it is not entirely necessary.

For example, one external reference file contains traffic, another contains signs. These two external reference scenarios could be combined into one file.

[[File:xref_overview2.png|400px]]

NOTE: Each group defined must be unique across all files: parent and external reference files.

In order to use an element in an external reference scenario, it is necessary to define and assign a group to all elements that you wish to control from the parent scenario.
At this time there is no visual hint in ISAT to indicate if a group has been assigned to an element or not - each element has to be confirmed independently.

However, a properly authored external reference element cannot be edited within the parent scenario (after you have done Add Ref. to use the external reference file).

An alternative is to insert groups using a text editor with macro capability, or to use a program or external script to make the necessary changes.

'''NOTE:''' If the external reference file is for object contained in the parent scenario (for example, an external reference file containing traffic signals with a group defined) it is still necessary for that group to be defined in the parent file.

With traffic signals, ISAT requires ONE explicit group reference, which will be contained in the HCSM TrafficLightManager block as shown below. If you require the use of traffic signals in an external reference, the recommended way to do this is through ISAT because then it manages the group assignment for you.

==== HCSM TrafficLightManager scenario block ====

HCSM TrafficLightManager
HCSM CLG
IntrsctnName "I1_40260_4620"
Duration 2.0000000E+01 3.0000000E+00 1.0000000E+00 2.0000000E+01 3.0000000E+00 1.0000000E+00
GroupName "TrafficSignals"
LightName "s_signal_r1_LTRN_40260_4620_270"
LightName "s_signal_r1_RTRN_40260_4620_270"
LightName "s_signal_r2_LTRN_40260_4620_270"
LightName "s_signal_r2_STRT_40260_4620_270"
LightName "s_signal_r3_STRT_40260_4620_270"
LightName "s_signal_r3_NORM_40260_4620_270"
Pattern "FLTY" "R" "R" "R" "R" "R" ""
Pattern "RTG" "R" "R" "R" "R" "R" ""
Pattern "LTR" "LTR" "LTR" "FLTY" "FLTY" "LTR" ""
Pattern "SR" "SR" "SR" "SG" "SY" "SR" ""
Pattern "SR" "SR" "SR" "SG" "SY" "SR" ""
Pattern "R" "R" "R" "G" "Y" "R" ""
&&&&End&&&&
&&&&End&&&&

'''NOTE:''' At this time there is a known issue using the write cell '''SCC_Audio_Trigger''' action in external references. Although the trigger containing this action can be assigned a group and used as an external reference, audio does not play.

<span style="color:#ac6600">'''Because ISAT updates static object positions (elevation) to the terrain (roadway) when the scenario file is saved, the best way to use a custom elevation is to put such objects into an external reference file in order to isolate those objects from normal scenario editing.''' </span>

====Define a Group====
<span style="color:#ac6600">'''NOTE:''' ISAT 1.8.5 and 1.8.6 currently do not work properly with group files. These versions will not import objects within a group file. There is a workaround which involves the following process, but instead of reading the saved group file into a scenario the workaround requires editing the scenario as text and inserting the objects within the group file into the scenario.</span>

RMB on the element and choose from the context menu: Group >> New Group (if this is a new group) or Group >> (choose an already defined group).

'''NOTE:''' The first time you create a group for an object, ISAT will automatically assign the group to that object.

After defining and assigning groups to the scenario elements needed, save the scenario file then close it.

Open or create the parent scenario file and use the Add Ref. button at the bottom of the ISAT window to select your external reference scenario. After you choose a file ISAT will present you with the groups found in that scenario. Choose the groups you with to include and click the 'Okay' button. Click the Add Ref. OK button to complete the process.

Currently import group file operations are not working, but it is possible to insert the group file content (all HCSM StaticObjects) into a scenario manually by using a text editor to copy text from the group file and paste that into a scenario file into the HCSM Static Object section of the scenario file.

[[File:group_text.jpg|400px]]

'''NOTE:''' ISAT does not enforce logic on your external reference authoring. If you add references to scenarios that do not share the same roadmap/BLI as the parent scenario, it is likely that elements will be placed at the origin (in cases where the external reference roadmap contains roadways not found in the parent) if it even loads.

===Exporting ISAT Elements as Groups===
Transferring ISAT elements among scenarios can be accomplished using groups. As with external reference scenarios, one or more groups must be defined and then assigned to one or more elements.

After defining and assigning groups select the group for export using the Group select drop-down located at the lower left corner of ISAT. Choose a group to export and then click the 'Save Group' button. Save the file.

TBC insert graphic sequence diagram here

'''NOTE:''' If you cannot locate the group file in the folder specified, check the ISAT install\data folder. This is typically:

C:\NADS\ISAT\data

===Group File Contents===
The group file is a text file and can be opened or edited in a text editor.

The following is a group file containing one ADO. Note the GroupName line near the bottom:

Header
LriFile "_dev.bli"
LongComment "this is a test group export"
ShortComment "this comment was left empty"
&&&&End&&&&
HCSM Ado
RunMode "eREMOTE_CONTROL"
RandomSol 0
Name "Ado1"
DynModel "Non Linear"
LogFile ""
LatOffsType 0
CreateRelLatInFeet 0
CreateRelOffsLonUsingExpr 0
CreateRelOffsLonExprStr ""
AutoControlBreakLights 0
AutoControlHeadLights 0
UseReaDel 1
StdToAccType 0
StdToDecType 0
StdToDecVal1 9.0000000E-001
StpToAccType 0
DecToAccType 0
FollowTimeMin 1.0000000E+000
FollowTimeMax 2.0000000E+000
EmergDecClip -1.1000000E+001
Accel2Catch 0
NormVel2Kp 7.0000000E-001
PathSearchDepth 2
LcvFall 1.5000000E+000 2.0000000E+000
LcvFreq 3.0000000E-002 5.0000000E-002
LcvRAmpl 1.0000000E-001 5.0000000E-001
VelCtrlInitMatchOvVel 0
VelCtrlFollowSpeedLimit 0
VelCtrlDistType 0
MaxLatOffset 9.0000000E+000
LongComment " "
ShortComment " "
SolName "Audi"
RoadPos "r1_1320_44220:2:32414.44:0.00"
GroupName "TEST_Group"
&&&&End&&&&
HCSM StaticObjManager
&&&&End&&&&
HCSM DriverMirror
&&&&End&&&&
HCSM IntersectionManager
&&&&End&&&&

===ISC Scripts===
Scripts are an efficient way to automate repetitive and/or complex tasks.

ISAT uses a custom language (ISC) to automate placement and manipulation of scenario objects. Combined with simple direction commands and the capability to navigate a road network, ISC scripts can ask the scenario author for input and prompt for selecting objects.

ISAT installs with some ISC script files. If your version of ISAT contains a data\isc
folder, then your version of ISAT is capable of running scripts. You can create
additional scripts as needed. All scripts located in the data\isc folder will load in ISAT
when ISAT is launched.

You can use these scripts for reference in creating your own custom scripts.

New scripts created during an existing ISAT session will not appear until ISAT is re-
launched.
Scripts that have been edited will not update until ISAT is re-launched.

Unless otherwise indicated, scripts are case-sensitive.

'''NOTE:''' Please do not edit the existing scripts!

Make a copy of any existing script before you make changes. In the event your modified script does not work, you can look at the original file for reference.

ISC scripts are located on the ISAT Elements widget. Custom isc scripts are located after the 'Events' separator.

Using an ISC script involves LMB + dragging the desired script onto the workspace. In some cases the script will ask for inputs.

ISC can be also used to create an entire event, thus ensuring that all events created will be entirely identical in terms of settings and locations for all created elements.

ISC scripts are text files located within the ISAT installation data folder. Only the custom ISC scripts are located in this folder. This is typically:

C:\Nads\Isat\data\isc

====Icon Files====
Script icon files are 8-bit windows icon files (file.ico). GIMP is capable of exporting valid ico files. To create an ico file, scale it to 32x32 pixels. Export the file as .ico to the isat\data\isc folder.

In order for a script to use an icon file, both files must exist in the isat\data\isc folder.

====ISC Script Examples====
This section contains example scripts with notes.

'''Rotate sign'''

.Name SetSignRotation
.Icon SignRot.ico
Static sign
Select(sign,"Please Select a Sign")
sign.SetAngle(Anchor)
.End

'''Place Multiple Static Objects (TrafCone)'''
The following script asks the scenario author for number of cones to generate, position and offset values and then generates the objects.

A breakdown of the script follows the code block below.

.Name Cones
.Icon cone.ico

Block coneBlock %%%
HCSM StaticObject
IsNewObj 1
Name "Cone_xxx"
SolName "TrafCone"
Option 0
Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
&&&&End&&&&
%%%
Static cone;

Value dist1
Value numberOfCones
Value distance
Value variablePart
Value randDistance
Value speed
Value Count
Value LatOffset

Block tempBlock
tempBlock = coneBlock
Count = 1
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

Ask(numberOfCones,"How many cones?" )
Ask(dist1,"Distance between cones?" )
Ask(LatOffset,"How much offset?" )

Position posRp
Position tempPos
posRp = Anchor
numberOfCones = numberOfCones

Repeat numberOfCones
posRp.GoForward(dist1)
# test comment
tempPos = posRp;
tempPos.SetOffset(LatOffset)
cone.RoadPos = tempPos
cone.Clone
Count = Count + 1
tempBlock = coneBlock
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

End
.End

====Script Breakdown cones.isc====

This section contains a description of the elements used in the script. The script segment is followed by a brief text description.

This script places a number of object copies (TrafCone) using information provided by a user.

.Name Cones
.Icon cone.ico

The first line contains a keyword '''.Name''' followed by the name of the script. This is the name that ISAT will use on the Isat Elements widget for the script. Note the script name does not have to be the same, but it is good computing practice.

The second line begins with the keyword '''.Icon''' followed by a file name. This file must exist in the ISAT\data\isc folder (accompanying the script file). This is the icon ISAT will use for the script.

Block coneBlock %%%
HCSM StaticObject
IsNewObj 1
Name "Cone_xxx"
SolName "TrafCone"
Option 0
Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
&&&&End&&&&
%%%

This is the data section of the script, which is defined using the keyword '''Block'''. A block name follows the keyword, and the data start is defined with '''%%%'''.

The HCSM StaticObject section has been copied from a scenario. In this case, a static object was placed into the workspace and then copied into a text file.

Name "Cone_xxx"
Note: the object name contains a marker that can be used to programmatically name instances of the object:

SolName "TrafCone"
This line begins with the keyword '''SolName''' followed by the name of the object as it is defined in the sol2.txt file.

Position 3.4312599E+002 -7.2408282E+004 0.0000000E+000
The Position of the static object will update when the script activates and instanced objects are placed in the workspace.

Static cone;
This line begins with the keyword '''Static''' followed by a variable name.

Value dist1
Value numberOfCones
Value distance
Value variablePart
Value randDistance
Value speed
Value Count
Value LatOffset

This section defines variables with the keyword '''Value''' followed by variable names. Using descriptive names is better than generic names. From the variable list it already seems clear what the programmer cares about: number of cones and distances.

Block tempBlock
tempBlock = coneBlock

This section defines a block using the keyword '''Block''' followed by the variable name.

The next statement replicates coneBlock into tempBlock.

Count = 1
Initialize the value of the variable Count to 1.

tempBlock.Replace('xxx',Count)
The built-in '''Replace''' function changes the string 'xxx' to the value of the variable Count.

cone.SetBlock(tempBlock)
This statement creates a block using the function '''SetBlock''' called cone, and copies the contents of tempBlock into it.

Ask(numberOfCones,"How many cones?" )
Ask(dist1,"Distance between cones?" )
Ask(LatOffset,"How much offset?" )

This section asks the user for input and puts that information into variables:
*Number of cones
*Distance between cones (dist1)
*Lateral offset (calculated from lane center)

Position posRp
Position tempPos
posRp = Anchor
numberOfCones = numberOfCones

This section contains position variables and assigns the value of numberOfCones.

Repeat numberOfCones
posRp.GoForward(dist1)
# test comment
tempPos = posRp;
tempPos.SetOffset(LatOffset)
cone.RoadPos = tempPos
cone.Clone
Count = Count + 1
tempBlock = coneBlock
tempBlock.Replace('xxx',Count)
cone.SetBlock(tempBlock)

This section is where the work happens. Reading from the top, this section is contained within a loop defined by the keyword '''Repeat'''. The number of times to repeat follows in a variable numberOfCones.

'''posRP.GoForward()''' is a built-in function to take the current position and shifts it forward by the amount specified in the dist1 variable.

#test comment
This is a comment defined by starting the line with the comment keyword '''#'''

tempPos = posRp;

Assign the value of the variable tempPos to the value currently in '''posRp'''

tempPos.SetOffset(LatOffset)

Another built-in function or attribute to the position element which defines a lateral offset (distance from the lane center). This statement places the value of a variable LatOffset into the offset element of the tempPos variable, using the operand '''SetOffset'''.

cone.RoadPos = tempPos

This statement sets the road position variable for cone to the value in the variable tempPos.

cone.Clone

Duplicate the block cone using the operand '''Clone'''

Count = Count + 1
Set the value of the variable Count to the value of Count plus one. This statement increments the value of Count for each loop processed.

tempBlock = coneBlock

Create a new block tempBlock by setting it to the content of coneBlock.

tempBlock.Replace('xxx',Count)

Use a built-in function to '''Replace''' the string 'xxx' with the value of the Count variable

cone.SetBlock(tempBlock)

Use the built-in function '''SetBlock''' to place the modified tempBlock (modified by the string replacement command earlier) into the cone block.

End
.End

The last two lines terminate the loop and the script, respectively.

====How to Create an ISC Script====
The simplest way to create an ISC script is to find an existing script that does something similar to your desired behavior and edit it.

=miniSim Simulation Data=
MiniSim runs on shared memory:
*miniSim is a collection of programs
*shared memory is a commonly accessed 'blackboard' list: a Cell and a Cell Value
:The DAQ file is a snapshot of this 'blackboard' memory for every frame.

*Scenario can write to cells added by the scenario author
:-i.e., for custom hardware or tasks/events

'''NOTE:''' Custom cells must be present in the collect file (NadsMiniSimCollect.cec) '''prior to''' simulation in order for the custom cells to be present in the DAQ.

NOTE: The cell type defined in the collect file must be followed, or garbage values will be used

Use of a DAQ file implies that at some point, data reduction will be needed.
Data reduction: the process of distilling measures from the DAQ file, i.e.
*Event definition
*SDLP
*Average headway

==What is the Difference? Cell vs. Variable==
*A Cell is a pre-created “slot” in shared memory
:-Specified in the .CEC collect file,
:-Saved in the DAQ file,
:-Can be sent to custom programs;
:-Can create & use custom cells;
*A Variable is a name value internal to the scenario
:-NOT saved to the DAQ file,
:-Can use to track items in the scenario
:i.e., how long the driver has been exceeding the speed limit
:-Initialize conditions in the scenario.

=== Variables Save ===
Variables can be saved to disk as a single value text file (ie, multiple values over time are not supported) through the use of a '''Store Variable''' action:

[[File:2021-08-23_13h28_49.png|400px]]

The file is stored in the miniSim_x.x\bin.x64 folder.

'''NOTE:''' The name of the file is defined within the Store Variable action. '''Care must be taken to save variables to unique file names''' in the case of multiple scenarios running on miniSim at the same time (if they share common variables), as would be the case if triggers are copied from one scenario to another.

=== Variables Restore/Read ===
Variables can be read into the simulation through the use of a '''Load Variable''' action:

[[File:2021-08-23_13h32_39.png|400px]]

==Cell Types==
This is a partial list of cell types.

*CFS = control feel subsystem (steering wheel, pedals)
*CIS = control information subsystem (gear, turn signal, buttons, etc)
*TPR = terrain profiler for terrain queries
*VDS = vehicle dynamics for accelerations, position, engine speed, speed, etc.
*ACC = adaptive cruise control
*RCM = configuration management for setting variables that affect subsystem configuration (ACC enabled or disabled, for instance)
*SCC = scenario
*SOP = for one time initializations at the start of the simulation.

=='''Data Output Actions'''==

*Write to Cell Actions
:-Write the value of a variable or cell to a cell
:-Write to a custom cell
:-Cannot overwrite another systems output
'''NOTE:''' Although it is possible to write to a different system cell, that value will be over-written on the next frame. Thus it is effectively not feasible nor desirable to do.

'''<span style="color:red">Also Note: the limit for maximum number of write to cell actions that can be performed in one frame is 8.</span>'''

*Set Variable Action
:-Sets the value of a variable
:-Does not have to be created first
:-Not saved in the DAQ unless written to a valid cell
*Logstream
:-Log data action

===Data Output Methods===
Your data is the primary reason for simulation.

1. Default miniSim scenario measures
:- Immediately available

2. Alternate scenario measures (DAQ file)
:- Processed through data reduction

====Default miniSim Scenario Measures====
*Saved to a drive report.txt file
*Saved to the same Location as DAQ files;
:Scenarioname_timedatestamp_report.txt
•Measures calculated overall, and up to 20 Events during drive:
:Collision Count Lane Departure Count
:Maximum Speed Lane Departure Percentage
:Minimum Speed Speeding Count
:Average Speed Speeding Percentage
:Standard Deviation of Speed Average Headway
:Standard Deviation of Lane Position

====Default miniSim Scenario Measures Require Scenario Event Definition====
In order to capture meaningful data into the default miniSim measures, a scenario must be configured properly to define events.

Use the Write to Cell action to activate the default measures.

[[File:2021-07-02_11h02_44.png|400px]]

*At the start of scenario, set:
::SCC_EventStatus =0
::SCC_EventNumber = 0
*At the start of the first event, set:
::SCC_EventStatus = 1
::SCC_EventNumber = 1
*At the end of the first event, set:
::SCC_EventStatus = 0
*At the start of the second event, set:
::SCC_EventStatus = 1
::SCC_EventNumber = 2
*At the end of the second event, set:
::SCC_EventStatus = 0

Continue this pattern; at end of final event, set:
::SCC_EventStatus = 0

====Default miniSim Scenario Measures Sample Report====
The following is an example report for 4 events. Note the remaining events present in the report are all zeroes or -1.00.

[[File:default_measures_report.png|400px]]

===="Alternate" Scenario Event Definition aka Using Logtreams====
'''NOTE: This method is the more typical/standard method for defining events.'''

Defining an event is key to partitioning simulator data into useful sections. Processing these sections is the essence of '''data reduction.'''

These useful sections are partitioned using logstreams and are generally called '''Events''':
*A logstream is a data marker present in the DAQ file
:there are 10 logstreams
:use logstreams to indicate when things happen '''in the data:'''
:at the start of an event; i.e.,
::grab all data where logstream 1 = 100 (example value)
:during a sub-section of an event
:at the end of an event (typically clears to 0)

Logstreams help separate/filter data;
*SDLP is not useful during emergency maneuver events

Logstreams can be useful to debug events;
:marking in the data when triggers fire
:ensuring event counters work; these are typically sequential, so any logstream deviation identifies a problem

*How to define a Scenario Event:

Set logstream values at scenario event start
:during and at scenario event end, set or clear logstream values:
For example:
::logstream 1 for event ID
::logstream 2 for sequencing the event (during/within event)
::logstream 3 for restart number, etc.

*Requires data reduction to fully process drive data
*Does '''not''' support default measures
:unless those measures are used in parallel with the logstream method

*The use of logstreams allows a scenario author to encode event and environment information into the scenario and as a result, into the simulator data stream.

====Example Alternate Scenario Event====
This section contains an example of a scenario that uses logstream 1 to define an event and environmental context.

In the following example, logstream 1 (LS1) is used to:
#define the scenario start, which is also in this example the event start. NOTE: This is not typical.
#when the driver is 805f from the intersection halt line, set a value into LS1
#when the driver is 500f from the intersection halt line, set a '''new value''' into LS1 NOTE: This could also use a different LS than the one used to define your event, i.e., 1
#when the driver activates a roadpad trigger to reset a force velocity (FV) on a lead vehicle

[[File:event_def_LS.png|400px]]

In the following event definition, an expression trigger is used to set a logstream value and execute two additional actions pertaining to the event.

[[File:event_ET_LS3.png|400px]]

====How to Export Data from A DAQ file using ISAT====
ISAT can display and export DAQ data. NOTE: This is 'raw data', not previously processed. This method can be used to test scenarios, confirm or identify data issues.

TBC: example export here

=Terminology & Documentation=
This section contains terminology and references to related documentation.

'''Action''' - the basic scenario element; the basis for creating scenarios. Actions may be executed on scenario elements (dynamic or static), create or remove elements, or the environment (time of day, visibility) or the simulated cab instrument panel.

'''ADO''' - Autonomous Dynamic Object; self-controlling to a degree.

'''Cell''' - Data elements that are recorded to during a drive; some cells may be used by the scenario author. Custom cells may be added to miniSim.

'''Event''' - anything significant that happens during a drive where the driver condition or response is desired to be identified in the drive data. Can be isolated from general driving through default measures or logstreams.

'''ISAT''' - Interactive Scenario Authoring Toolkit; used to create scenario files for use on the NADS facility or miniSim simulators.

'''ISC''' - ISAT script file.

'''Scenario''' - The simulation experience during a drive; also known as a scenario file, which contains all instructions to the elements within a simulator drive.

'''SDLP''' - Standard deviation lane position

'''SOL''' - Scenario Object Library; objects that are available to ISAT during scenario authoring must be present within the sol2.txt or an auxiliary sol2 (sol2_aux.xxx.txt) file.

'''Trigger''' - A scenario element that contains actions to execute during simulation. All triggers share the same actions, but execution depends on the trigger type.

'''TTA''' - Time to arrival.

'''TTC''' - Time to collision.

=Reporting ISAT & Scenario Issues=
*How to report ISAT & scenario issues:

When reporting issues with scenarios it is helpful to provide as much information as possible.

This often includes scenarios (including any external reference files) and the .LRI file used by the scenarios, screenshots or video that demonstrate the issue being reported and relevant DAQ files. It can be very helpful to include coordinate information with the screenshot or video.

The .BLI file is created from the .LRI and is much larger than the LRI so it may be more convenient to send the LRI file. NADS staff can re-create the BLI file from the LRI.

Some graphics anomalies may be issues with the tile model and not a scenario or miniSim problem. These include:
#white block shapes in the environment
#gaps or missing geometry; i.e., holes
#improper lighting (dark features present during the day)

If these issues happen on a custom roadmap/database world, please include the TMT .mos file as well so NADS can re-construct your environment.

==How to contact the NADS miniSim team:==

email [mailto:miniSim-Support@uiowa.edu minisim support]

[mailto:andrew-veit@uiowa.edu Andrew Veit]
Director of NADS miniSim

[mailto:joseph-meidlinger@uiowa.edu Joseph Meidlinger]
Program Coordinator NADS miniSim

[mailto:oscar-hernandezmurcia@uiowa.edu Oscar Hernandez Murcia]
MiniSim Application Programmer/Analyst

[mailto:chris-schwarz@uiowa.edu Chris Schwarz]
Data Reduction & Vehicle Dynamics

[mailto:shawn-allen@uiowa.edu Shawn Allen]
TMT, Modelling & Support

==How to check what BLI file is used by a scenario==

#You can edit the scenario in a text editor; near the top of the file will be a line starting with '''LriFile''' followed by the name of the BLI file in double quotes.
#You can use '''grep''' to inventory single or multiple scenarios:
:grep bli <scenario file/s>
:A partial listing is shown in the example below. NOTE: The files shown will likely be different on your PC:
C:\NADS\Isat\data\training.demo_scn>grep bli *.scn
Demo_Expression_Lead_Vehicle_Variables.scn: LriFile "simple_rural.bli"
Demo_Expression_Trigger_to_Lead_Vehicle.scn: LriFile "simple_rural.bli"
Demo_HUDD.scn: LriFile "simple_rural.bli"
ISAT-Samples-Avoid.scn: LriFile "esc_dry_05.bli"
ISAT-Samples-Right-Incursion.scn: LriFile "esc_dry_05.bli"
ISAT-Samples-TrafficLightTest.scn: LriFile "simple_city1.bli"
ISAT-Samples-TrafficLightTestB.scn: LriFile "simple_city1.bli"
ISAT-Samples-YellowLightDilemmaB.scn: LriFile "simple_city1.bli"
KBW_TEST.scn: LriFile "simple_rural.bli"
KBW_TESTB.scn: LriFile "simple_rural.bli"
demo.createADO_and_trigger.scn: LriFile "simple_city1.bli"
demo.creation_radius1.scn: LriFile "simple_city2.bli"
demo_FV_sum_of_Sines.scn: LriFile "simple_city2.bli"
demo_LV_Decelerate.scn: LriFile "simple_city2.bli"
demo_LV_cut_in.scn: LriFile "esc_dry_05.bli"
demo_MG.scn: LriFile "simple_city2.bli"
demo_TM1.scn: LriFile "simple_city2.bli"
demo_TT_null.scn: LriFile "simple_city2.bli"
demo_actions_text.scn: LriFile "simple_city2.bli"
demo_alt_data_measures.scn: LriFile "simple_city2.bli"
demo_audio_virtual_object.scn: LriFile "esc_dry_05.bli"
demo_audio_virtual_object_simple_rural.scn: LriFile "simple_rural.bli"
demo_auto_cloud1.scn: LriFile "simple_city2.bli"
demo_coneISC1.scn: LriFile "simple_city2.bli"
demo_dddo.scn: LriFile "simple_city1.bli"
demo_dddo_B.scn: LriFile "simple_city1.bli"
demo_forXRef_traffic.scn: LriFile "simple_city1.bli"
demo_force_vel_01.scn: LriFile "simple_city1.bli"
demo_groupImport.scn: LriFile "simple_city2.bli"

==How to configure miniSim for screenshots to include coordinates==
You can enable coordinate display on miniSim by changing the focus to the main display. #Move the cursor until it is positioned in the main display area, then LMB. When successful the main display will appear to "blink".

Press the keyboard n key twice. This will cause coordinate information to display in the lower left corner of the main display.

[[File:miniSim_show_coords.png|400px]]

The n key is a toggle; to disable coordinates, press it twice (2x) again. '''NOTE:''' the cursor focus must be in the main display in order for this to work.

=Additional Resources=
[[:File:ISAT_Quick_Start.pdf|ISAT Quick Start Guide]]

[[ISAT_Demonstration_Scenarios|Demonstration Scenarios]]

[[:File:Create_Use_Custom_Cells.pdf|Create and Use Custom Cells on MiniSim]]

[[:File:Function_ReadCell_20180824.pdf|ReadCell function]]

[[:File:TrafficManager_Ch12.NADS.Internal_ISAT_UsersGuide.pdf|Traffic Manager]]

=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 [[ISAT_Reference_Manual_Table_of_Contents#ISAT_Reference_Manual|reference manual for ISAT can be found here.]]