383. Traffic density watcher

The vehicle.traffic_density watcher monitors the traffic conditions in the immediate vicinity of a vehicle and emits intervals when traffic density changes across different categories. This watcher provides real-time assessment of traffic conditions in the Ego lane, left lanes, and right lanes, along with an overall traffic density indicator based on established traffic engineering standards.

383.0.1 Start condition

A new interval starts when all the following conditions are met:

• No active interval exists (data == null)
• Lane information is available
• The Ego exists in the simulator
• The Ego's speed is greater than or equal to min_activation_speed

383.0.2 End condition

An active interval ends when any of the following conditions are met:

1. Category change (with delayed restart):

• The traffic density category changes from one level to another (e.g., from light to moderate)
• The previous interval ends immediately at the current sampling time
• The watcher prevents starting a new interval within the same clock cycle
• The new interval starts at the next clock cycle in which the conditions are met. This ensures distinct start and end timestamps and prevents overlap.

2. Invalid operating conditions (end without restart):

• The Ego's speed drops below the min_activation_speed
• Lane information becomes unavailable
• The interval ends but does not restart automatically

• A new interval starts when all start conditions are met again.
• The check for invalid operating conditions (speed and lane information) runs on every clock tick, not just at sampling intervals. This ensures intervals end promptly when the Ego slows down or leaves the road network, even between sampling times.

383.1 Configuration parameters

The following parameters can be configured to customize the evaluator's behavior.

383.2 Metrics

The following metrics are recorded and tracked by the evaluator.

383.3 Log and Error Messages

No error messages found.

383.4 Additional information

Custom traffic density interval watcher configuration example

extend top.main:
watcher my_traffic_density_watcher is traffic_density(
vehicle: sut.car,
detection_range_forward: 150m,
detection_range_backward: 75m,
min_vehicle_speed: 10kph,
min_activation_speed: 15kph,
light_traffic_density_threshold: 10.0,
moderate_traffic_density_threshold: 25.0,
heavy_traffic_density_threshold: 50.0,
sampling_frequency: 1s,
rolling_window_size: 3,
log_level: debug_level
)

Traffic density categories

The watcher classifies traffic density into the following five categories based on spatial density of vehicles per kilometer per lane (vehicles/km/lane).