docs/simulators/trafficsign_simulator.md.backup - gerrit/www.eclipse.org/mosaic - Git at Google

 ## Traffic Signs Simulator

 With MOSAIC Extended it is possible to extend SUMO scenarios with variable traffic signs. Traffic signs can be placed on the map and
  connected to specific edges or even lanes.
 During the simulation the Traffic Sign Ambassador checks if traffic signs are in the sight distance of vehicles that are equipped with the Traffic
 Signs Application and informs them via an RTI interaction.

 {{% alert note %}}
 The **Traffic Sign Simulator** is available in MOSAIC Extended and can be used for free for research and academical
  purposes.
 {{% /alert %}}

 ### Add Traffic Signs to Scenario

 To configure your simulation to enable vehicles to react on traffic signs your scenario needs to contain the following files:

 ```FOLDER
 <scenario-name>
   trafficsigns
     trafficsigns_config.xml [Traffic Sign Ambassador configuration]
     signs.xml [List of Eclipse MOSAIC traffic signs]
   sumo [Only necessary for visual representations of traffic signs in SUMO GUI]
     <scenario-name>.sumo.cfg [Include additional files for the SUMO GUI]
     <scenario-name>.trafficsigns.xml [List of SUMO GUI representations of Eclipse MOSAIC traffic signs]
     images [Directory including image files of traffic signs]
   applications
     TrafficSignsApplications.jar [Vehicle application: Reaction on traffic signs]
     TrafficSignsVehicleApplication.json [Vehicle application configuration]
   mapping
     mapping_config.json [Equipping vehicles with the traffic signs application]
   scenario_config.json [Enable traffic signs ambassador]
 ```

 #### 1. Enable Traffic Signs Ambassador
 To enable the Traffic Signs Ambassador in your simulation activate it in `mosaic/mosaic_config.xml` like:

 ```xml
 <federates>
     <federate id="trafficsigns" active="true"/>
 </federates>
 ```

 #### 2. Configure the Traffic Signs Ambassador
 Configuring the Traffic Sign Ambassador in `trafficsigns/trafficsigns_config.json`:

 ```json
 {
     // Name of the XML file which contains the traffic signs
     "signsFilename": "signs.xml",

     // Path to the scenario database
     "database": "../application/<scenario-name>.db"
 }
 ```

 #### 3. Create traffic signs
 Currently implemented traffic signs:
 * __Lane Assignment Sign__
   Lanes can be assinged to a specific vehicle type (Bus, Taxi, Autonomous Vehicle,...).
   - Vehicles driving on such a lane which are not of the allowed vehicle class try to change to a different lane as soon as possible.
   - If a Taxi drives on the leftmost lane, but the rightmost is assigned to Taxis only, it tries to change to that lane as soon as possible.
 * __Speed Limit Signs__
   Speed limits can be set for specific streets or even lanes.
   - Vehicles driving on a lane with a speed limit change their maximum speed (SUMO parameter) to the value the sign specifies.
   - When vehicles change lane they adapt the new speed limit.
   - Vehicles do not prefer faster lanes.

 {{% alert note %}}
 - Generally, vehicles try to execute these maneuvers as soon as they see the traffic sign.
 - Signs have a visibility that defines how good the sign is visible to drivers.
 - Variable traffic signs can be changed during the simulation i.e. by a Traffic Management Center (TMC) or other simulation units.
 - The area of validity of a sign ends as soon another sign is placed downstream on the road and just before any on-ramp or crossing.
 - The `x,y` coordinates of signs in the XML definition are SUMO coordinates.
 - The visibility of signs is defined between `0.0` (not visible) and `1.0` (very good visible).
 - A vehicle only reacts on an update of a variable traffic signs if the sign is in front of the vehicle. If the sign is behind the vehicle and it is updated, the vehicle misses the update.
 - If a vehicle is not allowed to drive on any lane of the road, it stops.
 {{% /alert %}}

 The file `trafficsigns/signs.xml` stores all traffic signs of the scenario.

 Following examples show how to describe speed limit signs:
 ```xml
 <trafficsigns>
     <!-- Speed limit of 130km/h on all lanes of the specified edge. Not variable. -->
     <speedLimit id="speed-limit-sign-1"
                 x="51421.50" y="58297.29"
                 edge="4822486_685163613_31022629_31022620"
                 visibility="1.0"
                 variable="false"
                 limit="36.1">
     </speedLimit>

     <!-- Three variable speed limit signs for each lane of the edge with different speed limits. -->
     <speedLimit id="speed-limit-sign-2"
                 x="51421.50" y="58297.29"
                 edge="4822486_685163613_31022629_31022620"
                 visibility="1.0"
                 variable="true"
                 limit="36.1" >
         <lane index="0" limit="27.7" /> <!-- 100km/h on lane 0 -->
         <lane index="1" limit="33.3" /> <!-- 120km/h on lane 1 -->
         <lane index="2" limit="36.1" /> <!-- 130km/h on lane 2 -->
     </speedLimit>
 </trafficsigns>
 ```

 Following examples show how to describe lane assignment signs:
 ```xml
 <trafficsigns>
     <!-- Variable lane assignment sign that assignes all lanes of the specified edge to all vehicle classes.
             With this sign previous lane assignment signs can be neutraized.
             The sign has also a bad visibility. -->
     <laneAssignment id="lane-assignment-sign-1"
                     x="51419.73" y="58294.31"
                     edge="4822486_685163613_31022629_31022620"
                     visibility="0.3"
                     variable="true"
                     allowedVehicleClasses="ALL" >
     </laneAssignment>

     <!-- Three variable lane assignment signs with different vehicle class assignments per lane. -->
     <laneAssignment id="lane-assignment-sign-2"
                     x="51419.73" y="58294.31"
                     edge="4822486_685163613_31022629_31022620"
                     visibility="1.0"
                     variable="true"
                     allowedVehicleClasses="ALL" >
         <lane index="0" allowedVehicleClasses="Taxi Bus" /> <!-- The rightmost lane is assigned to busses and taxis only. -->
         <lane index="1" allowedVehicleClasses="Taxi" /> <!-- The center lane is assigned to taxis only. -->
         <lane index="2" allowedVehicleClasses="ALL" /> <!-- on the leftmost lane all vehicle types are allowed to drive. -->
     </laneAssignment>
 </trafficsigns>
 ```

 #### 8. Configure Traffic Signs Vehicle Application
 For your simulations you may want to change the mean sight distance of vehicles and define a deviation for that. You can do this by creating the file `application/TrafficSignsVehicleApplication.json` and edit it as following:
 ```json
 {
     // Mean sight distance of a driver in meters
     "meanSightDistance": 400.0,

     // Max. deviation of sight distance in meters
     "sightDistanceDeviation": 20.0
 }
 ```

 {{% alert note %}}
 This configuration effects each vehicle that is equipped with the `TrafficSignsVehicleApplication`.
 {{% /alert %}}

 #### 8. Equip vehicles with Traffic Signs Vehicle Application
 To equip vehicles with the `TrafficSignsVehicleApplication` you need to add `com.dcaiti.vsimrti.applications.trafficsigns.TrafficSignsVehicleApplication` to the applications list of the vehicle in the `mapping/mapping_config.json`.

 {{% alert note %}}
 [Read more about the Mapping configuration](/docs/simulators/application_simulator/#eclipse-mosaic-mapping)
 {{% /alert %}}

 You can specify the duration after which vehicles shall react on traffic signs by adding the `reactionTime` parameter (in seconds) to the application in `mapping_config.json`:
 ```json
 "applications": [
     "com.dcaiti.vsimrti.applications.trafficsigns.TrafficSignsVehicleApplication(5)"
 ]
 ```

 ### Change VMS during simulation

 #### Change variable speed limit signs
 ```java
 long timeToSend = 150 * TIME.SECOND;
 String signId = "speed-limit-sign-1"; // As defined in <scenario-name>/trafficsigns/signs.xml
 double newSpeedLimit = 13.89; // in m/s
 TrafficSignSpeedLimitChange interaction = new TrafficSignSpeedLimitChange(
     timeToSend,
     signId,
     newSpeedLimit
 );
 getOperatingSystem().getEventManager().addEvent(new Event(timeToSend, this, interaction));
 ```

 #### Change variable lane assignment signs
 ```java
 long timeToSend = 160 * TIME.SECOND;
 String signId = "lane-assignment-sign-2"; // As defined in <scenario-name>/trafficsigns/signs.xml
 int laneIndex = 0;
 List<VehicleClass> allowedVehicleClasses = new ArrayList<>();
 allowedVehicleClasses.add(VehicleClass.ElectricVehicle);
 TrafficSignLaneAssignmentChange interaction = new TrafficSignLaneAssignmentChange(
     timeToSend,
     signId,
     laneIndex, // NOTE: If you don't provide a lane index here, all lanes are assigned to electric vehicles only.
     allowedVehicleClasses
 );
 getOperatingSystem().getEventManager().addEvent(new Event(timeToSend, this, interaction));
 ```
 ---
	## Traffic Signs Simulator

	With MOSAIC Extended it is possible to extend SUMO scenarios with variable traffic signs. Traffic signs can be placed on the map and
	connected to specific edges or even lanes.
	During the simulation the Traffic Sign Ambassador checks if traffic signs are in the sight distance of vehicles that are equipped with the Traffic
	Signs Application and informs them via an RTI interaction.

	{{% alert note %}}
	The Traffic Sign Simulator is available in MOSAIC Extended and can be used for free for research and academical
	purposes.
	{{% /alert %}}

	### Add Traffic Signs to Scenario

	To configure your simulation to enable vehicles to react on traffic signs your scenario needs to contain the following files:

	```FOLDER
	<scenario-name>
	trafficsigns
	trafficsigns_config.xml [Traffic Sign Ambassador configuration]
	signs.xml [List of Eclipse MOSAIC traffic signs]
	sumo [Only necessary for visual representations of traffic signs in SUMO GUI]
	<scenario-name>.sumo.cfg [Include additional files for the SUMO GUI]
	<scenario-name>.trafficsigns.xml [List of SUMO GUI representations of Eclipse MOSAIC traffic signs]
	images [Directory including image files of traffic signs]
	applications
	TrafficSignsApplications.jar [Vehicle application: Reaction on traffic signs]
	TrafficSignsVehicleApplication.json [Vehicle application configuration]
	mapping
	mapping_config.json [Equipping vehicles with the traffic signs application]
	scenario_config.json [Enable traffic signs ambassador]
	```

	#### 1. Enable Traffic Signs Ambassador
	To enable the Traffic Signs Ambassador in your simulation activate it in `mosaic/mosaic_config.xml` like:

	```xml
	<federates>
	<federate id="trafficsigns" active="true"/>
	</federates>
	```

	#### 2. Configure the Traffic Signs Ambassador
	Configuring the Traffic Sign Ambassador in `trafficsigns/trafficsigns_config.json`:

	```json
	{
	// Name of the XML file which contains the traffic signs
	"signsFilename": "signs.xml",

	// Path to the scenario database
	"database": "../application/<scenario-name>.db"
	}
	```

	#### 3. Create traffic signs
	Currently implemented traffic signs:
	* __Lane Assignment Sign__
	Lanes can be assinged to a specific vehicle type (Bus, Taxi, Autonomous Vehicle,...).
	- Vehicles driving on such a lane which are not of the allowed vehicle class try to change to a different lane as soon as possible.
	- If a Taxi drives on the leftmost lane, but the rightmost is assigned to Taxis only, it tries to change to that lane as soon as possible.
	* __Speed Limit Signs__
	Speed limits can be set for specific streets or even lanes.
	- Vehicles driving on a lane with a speed limit change their maximum speed (SUMO parameter) to the value the sign specifies.
	- When vehicles change lane they adapt the new speed limit.
	- Vehicles do not prefer faster lanes.

	{{% alert note %}}
	- Generally, vehicles try to execute these maneuvers as soon as they see the traffic sign.
	- Signs have a visibility that defines how good the sign is visible to drivers.
	- Variable traffic signs can be changed during the simulation i.e. by a Traffic Management Center (TMC) or other simulation units.
	- The area of validity of a sign ends as soon another sign is placed downstream on the road and just before any on-ramp or crossing.
	- The `x,y` coordinates of signs in the XML definition are SUMO coordinates.
	- The visibility of signs is defined between `0.0` (not visible) and `1.0` (very good visible).
	- A vehicle only reacts on an update of a variable traffic signs if the sign is in front of the vehicle. If the sign is behind the vehicle and it is updated, the vehicle misses the update.
	- If a vehicle is not allowed to drive on any lane of the road, it stops.
	{{% /alert %}}

	The file `trafficsigns/signs.xml` stores all traffic signs of the scenario.

	Following examples show how to describe speed limit signs:
	```xml
	<trafficsigns>
	<!-- Speed limit of 130km/h on all lanes of the specified edge. Not variable. -->
	<speedLimit id="speed-limit-sign-1"
	x="51421.50" y="58297.29"
	edge="4822486_685163613_31022629_31022620"
	visibility="1.0"
	variable="false"
	limit="36.1">
	</speedLimit>

	<!-- Three variable speed limit signs for each lane of the edge with different speed limits. -->
	<speedLimit id="speed-limit-sign-2"
	x="51421.50" y="58297.29"
	edge="4822486_685163613_31022629_31022620"
	visibility="1.0"
	variable="true"
	limit="36.1" >
	<lane index="0" limit="27.7" /> <!-- 100km/h on lane 0 -->
	<lane index="1" limit="33.3" /> <!-- 120km/h on lane 1 -->
	<lane index="2" limit="36.1" /> <!-- 130km/h on lane 2 -->
	</speedLimit>
	</trafficsigns>
	```

	Following examples show how to describe lane assignment signs:
	```xml
	<trafficsigns>
	<!-- Variable lane assignment sign that assignes all lanes of the specified edge to all vehicle classes.
	With this sign previous lane assignment signs can be neutraized.
	The sign has also a bad visibility. -->
	<laneAssignment id="lane-assignment-sign-1"
	x="51419.73" y="58294.31"
	edge="4822486_685163613_31022629_31022620"
	visibility="0.3"
	variable="true"
	allowedVehicleClasses="ALL" >
	</laneAssignment>

	<!-- Three variable lane assignment signs with different vehicle class assignments per lane. -->
	<laneAssignment id="lane-assignment-sign-2"
	x="51419.73" y="58294.31"
	edge="4822486_685163613_31022629_31022620"
	visibility="1.0"
	variable="true"
	allowedVehicleClasses="ALL" >
	<lane index="0" allowedVehicleClasses="Taxi Bus" /> <!-- The rightmost lane is assigned to busses and taxis only. -->
	<lane index="1" allowedVehicleClasses="Taxi" /> <!-- The center lane is assigned to taxis only. -->
	<lane index="2" allowedVehicleClasses="ALL" /> <!-- on the leftmost lane all vehicle types are allowed to drive. -->
	</laneAssignment>
	</trafficsigns>
	```

	#### 8. Configure Traffic Signs Vehicle Application
	For your simulations you may want to change the mean sight distance of vehicles and define a deviation for that. You can do this by creating the file `application/TrafficSignsVehicleApplication.json` and edit it as following:
	```json
	{
	// Mean sight distance of a driver in meters
	"meanSightDistance": 400.0,

	// Max. deviation of sight distance in meters
	"sightDistanceDeviation": 20.0
	}
	```

	{{% alert note %}}
	This configuration effects each vehicle that is equipped with the `TrafficSignsVehicleApplication`.
	{{% /alert %}}

	#### 8. Equip vehicles with Traffic Signs Vehicle Application
	To equip vehicles with the `TrafficSignsVehicleApplication` you need to add `com.dcaiti.vsimrti.applications.trafficsigns.TrafficSignsVehicleApplication` to the applications list of the vehicle in the `mapping/mapping_config.json`.

	{{% alert note %}}
	[Read more about the Mapping configuration](/docs/simulators/application_simulator/#eclipse-mosaic-mapping)
	{{% /alert %}}

	You can specify the duration after which vehicles shall react on traffic signs by adding the `reactionTime` parameter (in seconds) to the application in `mapping_config.json`:
	```json
	"applications": [
	"com.dcaiti.vsimrti.applications.trafficsigns.TrafficSignsVehicleApplication(5)"
	]
	```

	### Change VMS during simulation

	#### Change variable speed limit signs
	```java
	long timeToSend = 150 * TIME.SECOND;
	String signId = "speed-limit-sign-1"; // As defined in <scenario-name>/trafficsigns/signs.xml
	double newSpeedLimit = 13.89; // in m/s
	TrafficSignSpeedLimitChange interaction = new TrafficSignSpeedLimitChange(
	timeToSend,
	signId,
	newSpeedLimit
	);
	getOperatingSystem().getEventManager().addEvent(new Event(timeToSend, this, interaction));
	```

	#### Change variable lane assignment signs
	```java
	long timeToSend = 160 * TIME.SECOND;
	String signId = "lane-assignment-sign-2"; // As defined in <scenario-name>/trafficsigns/signs.xml
	int laneIndex = 0;
	List<VehicleClass> allowedVehicleClasses = new ArrayList<>();
	allowedVehicleClasses.add(VehicleClass.ElectricVehicle);
	TrafficSignLaneAssignmentChange interaction = new TrafficSignLaneAssignmentChange(
	timeToSend,
	signId,
	laneIndex, // NOTE: If you don't provide a lane index here, all lanes are assigned to electric vehicles only.
	allowedVehicleClasses
	);
	getOperatingSystem().getEventManager().addEvent(new Event(timeToSend, this, interaction));
	```
	---