Scenario Building Help II - Revision history

Anna Dizack at 21:45, 24 February 2017

2017-02-24T21:45:23Z

Ciera Headley at 01:06, 7 December 2016

2016-12-07T01:06:41Z

Ciera Headley at 00:55, 7 December 2016

2016-12-07T00:55:28Z

Ciera Headley at 00:08, 7 December 2016

2016-12-07T00:08:09Z

Ciera Headley at 00:07, 7 December 2016

2016-12-07T00:07:15Z

Ciera Headley: Created page with "==Scenario Building Help== ===Segmentation=== A big help in authoring, and debugging scenarios is to break them up into segments. ===Independent Events=== Try to ensure th..."

2016-12-06T00:04:29Z

Created page with "==Scenario Building Help== ===Segmentation=== A big help in authoring, and debugging scenarios is to break them up into segments. ===Independent Events=== Try to ensure th..."

New page

==Scenario Building Help==

===Segmentation===

A big help in authoring, and debugging scenarios is to break them up into segments.

===Independent Events===

Try to ensure that each event is not dependent upon a previous event’s outcome. For instance, if you plan to have a lead vehicle breaking event, followed by a time of following the lead vehicle, and then another lead vehicle break. It would be best to have a different lead vehicle for each portion. The driver often does something completely unexpected, and if, instead of breaking for the first event, he passes the lead vehicle, the rest of your events have been ruined. It would be better to have a lead vehicle break, then another vehicle pull in and be the leader for the follow portion, then a different vehicle be the leader for the final break event.

===Logstream Divisions===

Breaking the route into sections physical sections is also useful. Set up roadpad triggers to increment one of the logstreams as the driver proceeds through the route. For example, at the start of the scenario, set logstream1 to 0, then every 2 miles increment that logstream by 1. This logstream value can either be displayed on the screen, or found in the DAQ replay. Having these logstream values helps pinpoint problem locations during debugging. It is also allows test drivers to better report the results of their drives.

===Restart locations===

Since scenarios can be very long, and drivers do unexpected things or simply don’t follow the drive instructions, restart scenarios are often part of the experimental plan. Restart scenarios may also be useful in authoring and debugging long, or complicated scenarios. Normally restart scenarios can be made by taking a copy of the original scenario, changing the start location, deleting the unnecessary objects and modifying the objects near the start of this new scenario. Having the different parts of the scenario independent of other parts, makes creating restart scenarios easier.

===Scenario reuse===

To simplify the authoring of scenarios, there are various forms of scenario reuse.

===Object cut and paste===

Once you have an object’s settings the way you like, it is often easier to copy and paste that object then to create another one. This is especially helpful if you are creating a lot of oncoming traffic ADOs or deletion triggers. To copy an object, select it, then Edit->Copy. When you choose Edit->Paste, the cursor will become the insertion cursor and hitting enter will place the object in the new location. If you were placing a series or oncoming ADOs you would only need to rename it, and possibly change its model.

If you copy and paste a roadpad trigger, the trigger will be in the new location, but its roadpad may not. If it isn’t, simply delete the old roadpad and place a new one. You can also copy groups of objects, like DDOs by simply selecting all of them before choosing Copy.

===Merge Component and External References===

The ISAT manual has specifics on creating groups of objects and then either merging then from one scenario into a second scenario, or referencing those objects from a second scenario. Briefly, right clicking an object brings up a menu with Group as the top option. Either select an already created Group, or make a new one, to put that object into the group. An object can only be a part of one group. Once you have groups in one scenario, from your second scenario select File and then Merge Component or External Reference. With Merge Component the group of objects will be written into your second file, and editable within it. With External Reference, the group of objects will be written into the scenario at run-time, and only editable in the first file.

In the sample scenarios, ISAT-Samples-Avoid.scn, and ISAT-Samples-Left- Incursion.scn refer to traffic and parked cars created in ISAT-Samples-Right- Incursion.scn. The same group of oncoming traffic could be used in multiple scenarios with slightly different event criteria. A close look at ISAT-Samples-Right-Incursion.scn shows that static objects as well as database sign settings, can also be included in a group, and also therefore as part of an external reference.

===Format===

The following sections list some formatting techniques I’ve found helpful in authoring scenarios. Since scenarios can be quite complicated it helps to have a consistent format so that others (or yourself after a period of time) can make sense of the scenarios.

Unique object names
Give each object a unique name. Since objects in the goto bar, objects are listed
alphabetically, it won’t help you find a specific ADO if they are all named: “Traffic ADO.” Also, objects for a specific event could be given group names like: incursionAdo, incursionParked1, incursionDeletTrigger, etc.
For triggers, unless they are part of a specific group, I normally give them names that indicate their type, followed by their main action. A Road Pad Trigger would be “RPT Delete1” or “RPT Create oncoming Traffic.” Time Trigger names would be prefaced by a “TT,” Expression Triggers by “ET,” etc.
For traffic ADOs, I either give them just generic names like Ado1,Ado2, etc, or area specific names such as Down1, Down2, Oncoming1, Oncoming2, etc.

===Initializations at start===

Some logstreams, cells, and variables need to be initialized at scenario start. It is best to put the trigger(s) that sets these initialization values close to the scenario start location.

===Created triggers===

If one trigger creates another trigger, put them close to each other for easy reference and editing. It also helps to always put them in the same relationship to each other. For example always put the created trigger on top of the creating trigger.

===Trigger point by road pad===

I put roadpad triggers close to the start of their roadpad. This way, when you are looking at the big picture of the scenario, it’s easy to get a sense of where the triggers are happening.

===Give all actions meaningful names===

When a trigger is selected, it displays its name, as well as its actions. Since the default names are action1, action2, etc, it is better to give them a meaningful name so you can quickly find the trigger to edit.

===Debugging===

When you test the scenario by running it in Rehearsal Mode, the debug side bar comes up. Since some error messages give the object’s name and location, having unique object names helps track down the errors.

===Scenario Robustness===

There are a few different things you can do to ensure that scenarios perform, each time, as you expect.

===Long Roadpads===
Roadpad triggers are one of the most common scenario elements. If they are triggered by the driver, it is a good idea to give them a long roadpad, even up to a couple hundred feet, since it is not uncommon for the driver to swerve out of the lane, especially during events.

===Clean Deletions===

Delete ADOs quickly after they have served their purpose. Otherwise they could end up driving around and firing triggers in unexpected manners.

===One Shot and Debounce===
If you only want a trigger to fire once, make sure the One Shop option is checked. If you want a trigger to fire multiple times, make sure to set the Debounce correctly. The Debounce setting determines the time, while its predicate is true, between firings. For instance you may use an Expression Trigger to play a play a message every time the driver reaches a certain speed. In that case, give the Debounce a value slightly longer then the length of the message, or you may have that message play multiple times.

===Performance===

===Pre-creation of all objects===
The process of creating an object could cause a hiccup in the visuals. In order to minimize this, all models that will be needed during the simulation should be created at the beginning of the scenario. When an object is created, and then deleted, the Image Generator (IG) doesn’t delete the object it just moves it to a place out of sight. And then when the object is needed again, it is moved instead of being created. The process of moving the object to the correct location doesn’t cause a jitter, while the act of creating that object could.

This pre-creation needs to occur at the beginning of the scenario, and the models need to be pre-created within about 500 feet of the driver’s starting location. Figure 2 shows the starting location from ISAT-Samples-Right-Incursion.scn. Notice the group of models just below the driver. Each is a DDO, since ADOs being created off road generate errors. There is a model and color of each ADO used in the scenario. They each have a lifetime of one second. The one uppermost and to the left has an activation delay of 0, the one next to it, and activation delay of 0.1, the one next to it, an activation delay of 0.2 seconds, etc, and in the same manner for all 80 models. This way all models are created and exist for one second, which is enough for each model to be instantiated by the image generating software. Also notice that the models are created fairly close to the driver, but off to the side so that they don’t appear when they are created.

[[File:roadWithTruck.png|800px|thumb|center|'''Figure 2 – Pre-creation Example''']]

===Minimization of active objects===
Each object puts a load upon the image generating software, the behaviors, and the dynamics. Too many objects will put enough load on the system that you will start to see visual jitters, and eventually some scenario objects will become unstable and may do unexpected things.

===Planned path===
To help minimize the amount of active objects, create a different scenario for each experimental drive. That way each scenario will have a specific path and traffic and objects can be tailored to fit that drive, and only traffic that is actually seen by the driver needs to be created.

===Cloud of traffic with driver===
Creating a cloud of traffic, travelling in the same direction as the driver, gives a sense of being full, without putting too much load on the system. On a two lane road, it might be sufficient to put three vehicles in front of the driver, and one or two behind it. On a four lane road you might need to add a couple more in front and behind

==='Creation radius for triggers===
Triggers put a load on the behaviors software, since they check, every frame, to see if their predicate is true. If the driver is going to hit a roadpad trigger, give the trigger a small creation radius, like three hundred feet. Doing this will cause the trigger to only be active when the driver is close. Other triggers could be deleted once they have fired, or will no longer be needed.

===Creation radius and Curves for oncoming traffic===
To minimize the time that oncoming traffic is active, give them a creation radius of 2000 or more feet. At about 2000 feet, you can see objects “pop in” as they are created, beyond that you normally don’t see that effect. If you give objects a creation radius greater then the pop-in distance, they will only be created, as needed, and will be deleted when out of sight. To further minimize the load, you could use curves and hills to shrink the creation radius further.

===Clean deletions===
Sometimes you will not be able to give vehicles or triggers a creation radius. If that is the case you could have the driver delete them with a road pad trigger, when they are no longer needed. If ADOs are not deleted, they may interact in unexpected ways, like driving back around and a loop, and hitting triggers at unexpected times. They also put unneeded load on the system

=Other Things=

'''Traffic Light Authoring'''

The ISAT manual has details on authoring a scenario’s traffic lights. Figure 3 shows the settings for a typical type of intersection, with lights along one lane being red for thirty- three seconds then turning green for thirty and yellow for three. Along the other line of traffic, the pattern is reversed. Sometimes you may never want the lights to change, in which case you give them one desired state.

[[File:fig3.png|600px|thumb|center|'''Figure 3 – Traffic Light Authoring Dialog''']]

'''Triggers Creating Time Triggers'''

Time Triggers use global time, they are not timers. If you want to create a use a Global Time Trigger as a timer, you will need to modify its activation settings. For example, you may want to play a message, exactly forty-five seconds after the driver passes a certain portion of the road. You would then use a RoadPad Trigger to create a TimeTrigger. Set the TimeTrigger to fire at zero seconds with an activation delay of forty-five seconds.

'''Persistent Actions'''

Most actions are completed shortly after they are initiated. So if you are using a trigger, you could have that one trigger do a series or actions. You could create and object, then 5 seconds later, delete it, then 5 seconds later play an audio message, then 10 seconds later terminate the simulation.

Some actions are persistent, that is they are never completed, and could not be part of a series of actions. The persistent actions are those which set some of the ADO’s dials. Specifically, MaintainGap, ForcedVelocity, VisualState, and AudioState. These actions need to be reset, with the reset action, if they will be changed. For example, if you set an ADO’s visual state to display its brake lights, you could not immediately turn on its turn signals. You would have to reset its Visual State and then set it to display brake lights. The ISAT manual gives more specifics on ADO dials and whether they are persistent or not.

Figure 4 shows the settings for a trigger in '''ISAT-Samples-Avoid.scn'''. It is described here because it shows how to coordinate several actions at once. The trigger is named:''' Avoid RPT Move Second Follower'''. At this point in the scenario, there are two vehicles which have their MaintainGap dial set such that they are following the External Driver at a fixed distance. The first action of the trigger is to create three Time Triggers to do other actions. Then 0.1 seconds later it resets the MaintainGap dial on the vehicle named Second Follower, then 0.1 seconds after that it sets the MaintainGap dial of Second Follower to a different value. It could not do another action after this since MaintainGap is a persistent action and would never be completed.

So the right-most of the three created triggers is a Time Trigger, with a firing time of zero, meaning it will fire as soon as it is created. It resets the MaintainGap dial on the event van, and then gives that dial another setting, making the Event Van move closer to the External Driver.

The middle trigger is a Time Trigger with a firing time of zero, but an Activation Delay of five seconds. It will therefore fire five seconds after it is created. It affects the Second Follower by making it change lanes to the right. This action could not be done as part of the trigger shown below since its final action, setting the MaintainGap dial, will never be complete.

The left most, of the three triggers, is also a Time Trigger, with an Activation Delay of 10 seconds. It fires and resets the Second Follower’s MaintainGap, and then sets it ForcedVelocity dial to 83 mph so that it speeds out ahead of the Driver.

[[File:fig4.png|600px|thumb|center|'''Figure 4 – Sequential Action Example''']]

=Sample Scenarios=

The data directory contains a few sample scenarios that illustrate some of the points in this document, as well as showing how to author simple events.

'''ISAT-Samples-Right-Incursion.scn'''

In this scenario there is an incursion from the right. Figure 5 shows a view of the main action. The selected trigger creates the incurring vehicle (the white car), when the driver is 1.85 seconds away from the driveway. The Roadpad Trigger next to is set to make the oncoming car slow down, to simulate another driver attempting to avoid the accident. The Roadpad Trigger also creates the TimeTrigger above which sets the ForcedLaneOffset of that oncoming vehicle, causing it to also pull off the road in an attempt to avoid the accident.

To get the oncoming car to always be in the correct location, it (and another vehicle behing it) are created 2,500 feet from the event, when the driver is 2,500 feet from the event. As soon as it is created, it hits a Roadpad Trigger which sets its ForcedVelocity Dial to match the velocity of the driver, and also sets the ForcedVelocity Dial of the car behind it. This setting is shown in Figure 6. Creating the car this way ensures that no matter the speed of the driver, it will always be at the appropriate distance from the event.

[[File:fig5.png|600px|thumb|center|'''Figure 5 – Incursion From Right Scenario''']]

[[File:fig6.png|600px|thumb|center|'''Figure 6 – Oncoming Match Driver’s Velocity''']]

'''ISAT-Samples-Left-Incursion.scn'''

This scenario is similar to the right incursion, except the incursion occurs from the left. A car pulling out into the road, causes the car behind it to pull into the driver’s lane. The oncoming car is set to be at the correct distance from the event, in the same manner as the right incursion scenario. Figure 7 shows the event location with the TimeToArrival Trigger which creates the pulling out car when the driver is six seconds away. The other TimeToArrival Trigger causes the oncoming car to pull into the driver’s lane when the driver is 3 seconds from the event.

This scenario also uses traffic, parked vehicles, and signs, as an external reference from the right scenario.

[[File:fig7.png|600px|thumb|center|'''Figure 7 - Incursion From Left''']]

'''ISAT-Samples-Avoid.scn'''

In this scenario, the driver is instructed to stay in the right lane. When the cars that are following the driver, get to the four lane portion of the road they start to pass the driver.

Eventually a construction van passes the driver and maintains its position in front of the driver. Within that van is a desk named AvoidDesk. Its settings are shown in Figure 8. Even though the desk is on the ground, somewhere in the scenario, when the scenario starts it is coupled to the van, sitting at 1.46 feet above the center of the van, as shown by its Relative Offset settings.

[[File:fig8.png|600px|thumb|center|'''Figure 8 - Desk Settings'']]

Figure 10 shows the three triggers that cause the event. The first trigger starts the van doors opening, and is shown in Figure 11. Opening of the doors is a visual state. Since the van has no other visual state set, the dial does not need to be reset, before it is set. The next trigger causes the desk to start sliding, relative to the van, and its settings are shown in Figure 12. It does this by changing its state from Coupled (state 2) to Relative (state 3). When it is moving in the Relative state, it is following its own path, but moving relative to the van in which is initially located. The actual path of the Desk is shown in Figure 9. The last trigger, shown in Figure 13, drops the desk, by changing its state to free (state 1). When its state changes, it receives the Initial Velocity shown in Figure 8, where the first three components are the x, y, and z components. While the last three are the roll, pitch, and yaw components.

[[File:fig9.png|600px|thumb|center|'''Figure 9 - Desk in Scenario''']]

[[File:fig10.png|600px|thumb|center|'''Figure 10 - Avoid Triggers''']]

[[File:fig11.png|600px|thumb|center|'''Figure 11 - Open Van Doors''']]

[[File:fig12.png|600px|thumb|center|'''Figure 12 - Slide Desk''']]

[[File:fig13.png|600px|thumb|center|'''Figure 13 - Drop Desk''']]

'''ISAT-Samples-TrafficLight.scn'''

This scenario has two traffic light intersections, and the Traffic Light Manager has been used to set the traffic light pattern.

= ISAT Scripting =

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.

Scripts are an efficient way to automate repetitive and/or complex tasks.

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.

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.

You can use these scripts for reference in creating your own custom scripts.

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.

== 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.

== Examples ==

This section contains example scripts.

=== '''Rotate sign''' ===

<nowiki># prompt author for a sign to rotate</nowiki>

<nowiki>.Name SetSignRotation</nowiki>

<nowiki>.Icon SignRot.ico</nowiki>

<nowiki>Static sign</nowiki>

<nowiki>Select(sign,"Please Select a Sign")</nowiki>

<nowiki>sign.SetAngle(Anchor)</nowiki>

<nowiki>.End</nowiki>

== Reference ==

[[:File:ISC_Image2011_ISC.pdf]]Image ISC Paper

← Older revision		Revision as of 21:45, 24 February 2017
Line 1:		Line 1:
		+	[[ISAT_User%27s_Guide_Table_of_Contents\|ISAT User's Guide Table of Contents]]
		+
	[[Scenario_Building_Help\|◄PREVIOUS]] [[Other_Things\|NEXT►]]		[[Scenario_Building_Help\|◄PREVIOUS]] [[Other_Things\|NEXT►]]
	==Scenario Building Help==		==Scenario Building Help==

← Older revision		Revision as of 01:06, 7 December 2016
Line 121:		Line 121:

	[[#top\|TOP]]		[[#top\|TOP]]
		+
		+	[[Scenario_Building_Help\|◄PREVIOUS]] [[Other_Things\|NEXT►]]

← Older revision		Revision as of 00:08, 7 December 2016
Line 1:		Line 1:
−	[[Scenario_Building_Help\|◄PREVIOUS]] [[~~_II~~\|NEXT►]]	+	[[Scenario_Building_Help\|◄PREVIOUS]] [[Other_Things\|NEXT►]]
	==Scenario Building Help==		==Scenario Building Help==

@@ Line 10: / Line 10: @@
 Try to ensure that each event is not dependent upon a previous event’s outcome. For instance, if you plan to have a lead vehicle breaking event, followed by a time of following the lead vehicle, and then another lead vehicle break. It would be best to have a different lead vehicle for each portion. The driver often does something completely unexpected, and if, instead of breaking for the first event, he passes the lead vehicle, the rest of your events have been ruined. It would be better to have a lead vehicle break, then another vehicle pull in and be the leader for the follow portion, then a different vehicle be the leader for the final break event.
 ===Logstream Divisions===
@@ Line 22: / Line 23: @@
 To simplify the authoring of scenarios, there are various forms of scenario reuse.
 ===Object cut and paste===
@@ Line 28: / Line 30: @@
 If you copy and paste a roadpad trigger, the trigger will be in the new location, but its roadpad may not. If it isn’t, simply delete the old roadpad and place a new one. You can also copy groups of objects, like DDOs by simply selecting all of them before choosing Copy.
 ===Merge Component and External References===
@@ Line 34: / Line 37: @@
 In the sample scenarios, ISAT-Samples-Avoid.scn, and ISAT-Samples-Left- Incursion.scn refer to traffic and parked cars created in ISAT-Samples-Right- Incursion.scn. The same group of oncoming traffic could be used in multiple scenarios with slightly different event criteria. A close look at ISAT-Samples-Right-Incursion.scn shows that static objects as well as database sign settings, can also be included in a group, and also therefore as part of an external reference.
 ===Format===
@@ Line 44: / Line 48: @@
 For traffic ADOs, I either give them just generic names like Ado1,Ado2, etc, or area specific names such as Down1, Down2, Oncoming1, Oncoming2, etc.
 ===Initializations at start===
@@ Line 56: / Line 61: @@
 I put roadpad triggers close to the start of their roadpad. This way, when you are looking at the big picture of the scenario, it’s easy to get a sense of where the triggers are happening.
 ===Give all actions meaningful names===
@@ Line 69: / Line 75: @@
 There are a few different things you can do to ensure that scenarios perform, each time, as you expect.
 ===Long Roadpads===
 Roadpad triggers are one of the most common scenario elements. If they are triggered by the driver, it is a good idea to give them a long roadpad, even up to a couple hundred feet, since it is not uncommon for the driver to swerve out of the lane, especially during events.
@@ Line 76: / Line 83: @@
 Delete ADOs quickly after they have served their purpose. Otherwise they could end up driving around and firing triggers in unexpected manners.
 ===One Shot and Debounce===
 If you only want a trigger to fire once, make sure the One Shop option is checked. If you want a trigger to fire multiple times, make sure to set the Debounce correctly. The Debounce setting determines the time, while its predicate is true, between firings. For instance you may use an Expression Trigger to play a play a message every time the driver reaches a certain speed. In that case, give the Debounce a value slightly longer then the length of the message, or you may have that message play multiple times.
 ===Performance===
@@ Line 89: / Line 98: @@
 ===Minimization of active objects===
 Each object puts a load upon the image generating software, the behaviors, and the dynamics. Too many objects will put enough load on the system that you will start to see visual jitters, and eventually some scenario objects will become unstable and may do unexpected things.
@@ Line 98: / Line 108: @@
 Creating a cloud of traffic, travelling in the same direction as the driver, gives a sense of being full, without putting too much load on the system. On a two lane road, it might be sufficient to put three vehicles in front of the driver, and one or two behind it. On a four lane road you might need to add a couple more in front and behind
 ==='Creation radius for triggers===
 Triggers put a load on the behaviors software, since they check, every frame, to see if their predicate is true. If the driver is going to hit a roadpad trigger, give the trigger a small creation radius, like three hundred feet. Doing this will cause the trigger to only be active when the driver is close. Other triggers could be deleted once they have fired, or will no longer be needed.
 ===Creation radius and Curves for oncoming traffic===
 To minimize the time that oncoming traffic is active, give them a creation radius of 2000 or more feet. At about 2000 feet, you can see objects “pop in” as they are created, beyond that you normally don’t see that effect. If you give objects a creation radius greater then the pop-in distance, they will only be created, as needed, and will be deleted when out of sight. To further minimize the load, you could use curves and hills to shrink the creation radius further.
 ===Clean deletions===
 Sometimes you will not be able to give vehicles or triggers a creation radius. If that is the case you could have the driver delete them with a road pad trigger, when they are no longer needed. If ADOs are not deleted, they may interact in unexpected ways, like driving back around and a loop, and hitting triggers at unexpected times. They also put unneeded load on the system

@@ Line 1: / Line 1: @@
 ==Scenario Building Help==
@@ Line 105: / Line 106: @@
 ===Clean deletions===
 Sometimes you will not be able to give vehicles or triggers a creation radius. If that is the case you could have the driver delete them with a road pad trigger, when they are no longer needed. If ADOs are not deleted, they may interact in unexpected ways, like driving back around and a loop, and hitting triggers at unexpected times. They also put unneeded load on the system