202. Curvature Watcher

The curvature watcher provides valuable context for interval-based analysis by detecting and recording instances when the Ego drives on a road with a curvature radius less than or equal to max_radius_large_threshold. It uses the vehicle.get_road_radius() function to get the radius of each map segment. A curve begins when a segment's radius is less than or equal to the max_radius_large_threshold threshold. Subsequent segments are considered part of the same curve as long as their radii do not exceed this threshold. The curve is then categorized based on the minimum radius found within these segments. The minimum radius is used for categorization because curves typically start and end with a large radius, which does not represent their sharpest point. Users can customize categories by setting the maximum radius for each one; the minimum radius of the next category is then automatically adjusted to be greater than the previous category's minimum.

202.0.1 Start condition

The curvature watcher samples the road radius on each top.w_clk. If the absolute radius is within the range (0..max_radius_large_threshold] meters and the vehicle remains in its lane, a new watcher interval starts and stays active as long as the radius remains within this range.

202.0.2 End condition

An active curvature interval ends when the absolute radius leaves the range (0..max_radius_large_threshold] meters or when the vehicle leaves its lane. A new interval is emitted whenever the radius re-enters the specified range.

202.1 Plot

202.2 Configuration parameters

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

Parameter	Type	Unit	Description	Default Value	Range
`max_radius_sharp_threshold`	length	m	Upper threshold for a curve to be classified as sharp	150m	[0, 2000]m
`max_radius_medium_threshold`	length	m	Upper threshold for a curve to be classified as medium	500m	[0, 2000]m
`max_radius_large_threshold`	length	m	Upper threshold for a curve to be classified as large	2000m	[0, 2000]m
`debounce_time_last_curve`	time	s	Debounce time to delay ending the interval when the end condition is met	0.5s	[0, 10]s

202.3 Metrics

The following metrics are recorded and tracked by the evaluator.

Metric	Type	Description	Unit
`avg_velocity`	speed	Speed of vehicle while navigating the curve	kph
`max_lat_acceleration`	acceleration	Maximum lateral acceleration of the vehicle while navigating the curve	mpsps
`min_curve_radius`	length	Minimum interval curve_radius of the curve	m
`avg_curve_radius`	length	Average radius of the curve	m
`curve_category`	enum (`sharp`, `medium`, `large`)	Category of the curve (sharp, medium, large)
`curve_side`	enum (`left`, `right`)	Side to which the curve turns (left, right)

202.4 Log and Error Messages

No error messages found.

202.5 Usage

202.5.1 How to instantiate

The curvature watcher can be instantiated for any vehicle actor.

watcher curvature_watcher is curvature(vehicle: vehicle actor,
    max_radius_sharp_threshold: length,
    max_radius_medium_threshold: length,
    max_radius_large_threshold: length,
    debounce_time_last_curve: time,
    log_level: log_level)

202.5.2 Set parameters at instantiation time

Pass parameters in the keep(...) binding at instantiation time, either from ftlx_global_eval_config or as explicit values.

watcher curvature_watcher is curvature(vehicle: sut.car):
    keep(max_radius_sharp_threshold == 100m)
    keep(max_radius_medium_threshold == 200m)
    keep(max_radius_large_threshold == 300m)
    keep(debounce_time_last_curve == 1s)
    keep(log_level == ftlx_global_eval_config.ego_curvature_watcher_config.log_level)

202.5.3 Define and use a custom parameter set

A new struct can be created to customize the watcher's parameters in a more organized and modular way.

const custom_curvature_watcher_config: curvature_watcher_config = new
set custom_curvature_watcher_config.max_radius_sharp_threshold = 100m
set custom_curvature_watcher_config.max_radius_medium_threshold = 200m
set custom_curvature_watcher_config.max_radius_large_threshold = 300m
set custom_curvature_watcher_config.debounce_time_last_curve = 1s
set custom_curvature_watcher_config.log_level = info_level

To use the custom struct, its values should be passed to the watcher instantiation as parameters.

watcher custom_curvature_watcher is curvature(vehicle: sut.car,
    max_radius_sharp_threshold: custom_curvature_watcher_config.max_radius_sharp_threshold,
    max_radius_medium_threshold: custom_curvature_watcher_config.max_radius_medium_threshold,
    max_radius_large_threshold: custom_curvature_watcher_config.max_radius_large_threshold,
    debounce_time_last_curve: custom_curvature_watcher_config.debounce_time_last_curve,
    log_level: custom_curvature_watcher_config.log_level)

202.5.4 Disabling the watcher

To disable the watcher, set the enabled flag to false in the curvature_watcher_config struct.

const curvature_watcher_config: curvature_watcher_config = new
set curvature_watcher_config.enabled = false

202.6 Additional information

All parameters are required, but you don't need to customize all of them. For any parameter you don't customize with set, the default value defined in curvature_watcher_config is used.