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

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

191.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 with deferred restart):

• The Ego's speed drops below the min_activation_speed
• Lane information becomes unavailable, or lane/occupancy consistency checks fail
• The interval ends on that tick. When activation is OK again, the next interval starts on the following w_clk (you do not need to wait for sampling_frequency).

Take note of the following rules governing interval timing, validity checks, and the use of rolling versus interval-based metrics.

• Category change ends at the sample time and opens the next interval on the next w_clk. Invalid activation ends on any tick; the same deferred start applies when speed and lane checks pass again.
• The check for invalid operating conditions runs on every clock tick, not just at sampling intervals, so intervals can end between traffic-density samples.
• Rolling window vs what you see on the closed interval: A per-lane rolling average of instantaneous spatial density (last up to rolling_window_size samples) decides when the overall category changes and thus when the interval ends on category change. Reported lane/overall density and categories on data when the interval closes use interval-mean occupancy: mean vehicle count per sample over the whole interval (computed with a fractional mean), converted to vehicles/km/lane. That aligns density with min/max/avg count statistics over the same interval. Sparse traffic (many zero samples, a few non-zero) can still show integer *_vehicle_count_avg as 0 while density reflects the true fractional mean.
• Lane validity can use either lane_position.lane or msp_pos_closest_lane when both match an occupied driving lane, to reduce one-tick glitches.
• Longitudinal distance for the detection window uses route-based road distance (driving lanes only), consistent with lane-relative counting.
• Rolling density sample lists are cleared at each interval start so rolling state applies only within that interval.

191.1 Configuration parameters

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

191.2 Metrics

The following metrics are recorded and tracked by the evaluator.

191.3 Log and Error Messages

No error messages found.

191.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).