195. Road Departure Checker

The vehicle.road_departure is a modifier responsible for emitting intervals and raising issues when a vehicle drives off-road.

195.0.1 Start condition

An interval starts when the off_road_deviation becomes greater than the relevant threshold: warning_threshold or junction_warning_threshold for a warning, and error_threshold or junction_error_threshold for an error.

195.0.2 End condition

The interval ends when off_road_deviation falls below the relevant threshold again, at which point a warning or error is raised.

195.1 Plot

Road Departure Checker interval representation

195.2 Attributes

The following attributes define the behavior and characteristics of the evaluator.

Checker attribute	Description
Parent object	`vehicle.road_departure`
Issue category	`sut` or `other`
Issue kind	`road_departure`
Default severity	warning, error
Trigger condition	Based on `passive_w` watcher

195.3 Configuration parameters

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

Parameter	Type	Unit	Description	Default Value	Range
`warning_threshold`	length	m	Off-road deviation threshold for warnings outside junctions	0.1m	[0, 5]m
`junction_warning_threshold`	length	m	Off-road deviation threshold for warnings inside junctions	1m	[0, 5]m
`error_threshold`	length	m	Off-road deviation threshold for errors outside junctions	actor.bbox.width / 4	[0, 5]m
`junction_error_threshold`	length	m	Off-road deviation threshold for errors inside junctions	2m	[0, 5]m

195.4 Metrics

The following metrics are recorded and tracked by the evaluator.

Metric	Type	Description	Range	Unit
`max_distance_to_road`	length	Maximum distance of any bounding box point towards the closest road element during the interval		m
`time_off_road`	time	Duration the vehicle spends off-road		s

195.5 Log and Error Messages

Output Condition	Description	Default Severity	Action
off-road deviation was above warning_threshold for 3 consecutive samples while not in a junction	{driver_modes}: Vehicle position was too far off road. Maximum deviation of {value} was reached at {time} for <{ref_point}> point [of {compound_part}] at global coordinate [{coord}]. It exceeded vehicle.road_departure.warning_threshold of {threshold}	Warning	Investigate the SUT behaviour.
off-road deviation was above junction_warning_threshold for 3 consecutive samples while in a junction	{driver_modes}: Vehicle position was too far off road. Maximum deviation of {value} was reached at {time} for <{ref_point}> point [of {compound_part}] at global coordinate [{coord}]. It exceeded vehicle.road_departure.junction_warning_threshold of {threshold}	Warning	Investigate the SUT behaviour.
off-road deviation was above error_threshold for 3 consecutive samples while not in a junction	{driver_modes}: Vehicle position was too far off road. Maximum deviation of {value} was reached at {time} for <{ref_point}> point [of {compound_part}] at global coordinate [{coord}]. It exceeded vehicle.road_departure.error_threshold of {threshold}	Error	Investigate the SUT behaviour.
off-road deviation was above junction_error_threshold for 3 consecutive samples while in a junction	{driver_modes}: Vehicle position was too far off road. Maximum deviation of {value} was reached at {time} for <{ref_point}> point [of {compound_part}] at global coordinate [{coord}]. It exceeded vehicle.road_departure.junction_error_threshold of {threshold}	Error	Investigate the SUT behaviour.

195.6 Usage

The road_departure_checker monitors road deviation using two checkers: checker_warning and checker_error. Four thresholds control when each triggers: warning_threshold and junction_warning_threshold for warnings, and error_threshold and junction_error_threshold for errors. When a vehicle's deviation exceeds a threshold, an interval begins. When the deviation drops below the threshold, the interval ends and Foretify raises a warning or error issue.

195.6.1 How to instantiate

The road_departure modifier is built into every vehicle via vehicle.global_checkers and does not require a separate declaration per vehicle in scenario OSC files:

extend vehicle.global_checkers:
    road_departure: road_departure()

The modifier is active on the Ego, NPCs, and all other vehicles. Each vehicle has its own road_departure instance with separate thresholds and intervals.

195.6.2 Set parameters at instantiation time

There is no separate configuration struct. Set thresholds by extending vehicle.road_departure:

extend vehicle.road_departure:
    keep(warning_threshold == 18cm)
    keep(junction_warning_threshold == 1.5m)
    keep(error_threshold == actor.bbox.width / 3)
    keep(junction_error_threshold == 2.5m)

195.6.3 Define and use a custom parameter set

There is no road_departure_checker_config struct. Customize behavior per actor or scenario using the following patterns.

Per-vehicle thresholds (for example, only the Ego):

extend sut_vehicle:
    keep(global_checkers.road_departure.warning_threshold == 18cm)

Current threshold values are accessible at runtime via sut.car.global_checkers.road_departure.warning_threshold and the other threshold fields.

195.6.4 Disabling the checker for all vehicles:

extend vehicle.global_checkers:
    on @start:
        override(road_departure, run_mode: freeze)

In strict regression tests the checker is frozen by default. To activate it:

extend vehicle.global_checkers:
    on @start:
        override(road_departure, run_mode: unfreeze)

Adjust default severity:

extend vehicle.global_checkers:
    set_issue(target_checker: road_departure.checker_warning, severity: warning)

Downgrade or modify issues on @top.new_issue:

extend top.main:
    on @top.new_issue:
        if issues.curr.kind == road_departure:
            issues.curr.modify(road_departure, info, "downgrade road_departure severity for analysis")

195.7 Additional information

Road Definition: Includes all outermost lanes, sidewalks, and shoulders.
Junction Logic: Active if at least one vehicle corner is inside the junction area.

Road Departure Checker reference points
Deviation Measurement: Measured from the closest road edge to the farthest vehicle reference point (corners and mid-edges).
Compound Objects: Deviation is calculated independently for each part (e.g., both truck and trailer).
Threshold Intervals:
- Start: An interval is triggered when off_road_deviation exceeds the warning, error, or junction-specific thresholds.
- End: An interval ends when the value drops below the threshold, raising a warning or error issue.
- Initial state: If a vehicle starts off-road, the checker waits until the vehicle is fully on-road before monitoring begins.

Resolution options This check identifies the driver that is at fault. In the most simplistic approach, there are the following cases:

ftx_driver (Foretellix Human Driver Model) or external_driver (typically the simulator): This issue needs investigation and possible optimization of Foretify parameter settings for your environment. Please check with your AE.
SUT_driver (the SUT): This is most likely an issue in the SUT. You should investigate whether there is a bug in the SUT.
hybrid_driver: In this case, the ftx_driver (Foretellix Human Driver Model) and SUT_driver (the SUT) drive the vehicle in parallel. Therefore each case needs to be examined separately. In general, the SUT stack is expected to be robust enough to withstand issues that might happen in the ftx_driver. But this depends significantly on the specific SUT functionality (the type of ADAS) and the scenario.