8.9 Movement modifiers

8.9.1 Modifiers for movement actions

The movement of physical objects, including vehicles and pedestrians, is specified using movement actions. These actions can be tuned with the use of movement modifiers. These modifiers can be applied to either the generic movement actions, like move(), drive(), or walk(), or to the specialized movement actions, like change_speed(), change_lane(), and so on. Users are free to combine modifiers and actions, as long as the combination provides a consistent set of constraints for the actor behavior. These modifiers must appear either as members of other action modifiers or as members of a movement action after with.

Code 1. Modifier drive()

do serial:
   vehicle1.drive() with:
       speed([30kph..70kph])

Code 2. Modifier follow_lane()

do serial:
    vehicle2.follow_lane(offset: 0.375m, target: lane2) with:
        position(1m, ahead_of: ego_vehicle, at: start)
        speed(60kph)

Some parameters can be passed by order, meaning without the parameter name. If no arguments are passed, the defaults are applied.

The following three invocations of lane() are supported and have the same effect:

Code 3. Different kinds of passing parameters

   lane(lane: 1)
   lane(1)
   lane()

8.9.1.1 Common parameters

The following parameters are common to all domain model movement modifiers.

8.9.1.1.1. Parameter `at`

All movement modifiers have an optional parameter at with the following possible values:

all
This constraint holds throughout this phase (default).
start
This constraint holds at the start of the phase.
end
This constraint holds at the end of the phase.

8.9.1.1.2. Parameter `movement_mode`

The parameter movement_mode has the following values:

monotonous
This movement mode adheres to the laws of physics. On top of that it limits the level of surprise that a movement may have.
other
Not necessarily monotonous. This is the default.

8.9.1.1.3. Parameter `track`

track
Actual or projected. The default is actual, meaning that the vehicle reacts to the behavior of the referenced vehicle.

8.9.1.1.4. Parameter `shape`

shape
A shape struct is an object that contains a duration() and a compute() method, plus a set of parameters that allow users to shape the way a state variable (like lateral position, speed or acceleration) changes during an action/modifier invocation. The duration() method returns the time duration of the shape. The compute() method returns concrete values for the relevant state variable as a function of time.

The following is a typical use of a shape struct.

Code 4. Shape

scenario my_scenario:
    spd_shape: common_speed_shape with:
        keep(it.target == 50kph)
        keep(it.rate_profile == smooth)
        keep(it.rate_peak == 5mpsps)
    v1: vehicle

    do serial:
       v1.drive() with:
           speed(shape: spd_shape)

The example below exhibits the same behavior as the example above. Note that, in general, the shape’s target parameter may overlap with at: end constraints introduced in the modifier. In this case, the shape’s target parameter can be taken from the speed modifier. However, to avoid confusion or contradictions, it is suggested to create shape struct instances that are fully defined.

Code 5. Shape with target parameter from speed modifier

scenario my_scenario:
    spd_shape: common_speed_shape with:
        keep(it.rate_profile == smooth)
        keep(it.rate_peak == 5mpsps)
    v1: vehicle

    do serial:
       v1.drive() with:
           speed(50kph, at: end, shape: spd_shape)

This shape example causes the vehicle v1 to drive with 50 kph. This speed is achieved with a smooth acceleration profile with a peak acceleration of 5 mpsps, as specified by the rate_profile and rate_peak parameters.

A set of built-in shape objects is provided in ASAM OpenSCENARIO. Users can extend these built-in shape objects with their own desired shape objects.

Note that using the shape strcuts will specify the exact values for certain state variables (or their derivatives) throughout the corresponding action execution. This can limit the degrees of freedom of the actor during the action execution and could have strict implications on other scenario attributes. For example, when using a shape struct on a speed modifier, this will also constrain the acceleration attributes of the actor. Be careful not to use excessive shape attributes on the modifier that may restrict the generated movements, unless this is your goal.

For more information on shape objects please read the shape object description below.

8.9.1.2 Shape object description

The shape structs are a way to describe the behavior of a state variable as a function of time within a modifier invocation, enabling a fine-grained control of the actor’s maneuver. any_shape is the base struct of the shape hierarchy, thus any user-defined shape structs should inherit from any_shape or one of its children. any_shape contains the duration() function which returns the time duration of that shape.

Concrete shape types implement their shape compute() function which gets a time argument and returns the corresponding value of the state variable that is modified by the shape. The time is measured from the start of the scenario phase that invokes the modifier.

Specific shape objects can have additional arbitrary attributes.

The shape hierarchy definition is as follows:

struct any_shape:
    def duration() -> time is undefined

struct any_acceleration_shape inherits any_shape:
    def compute(time: time) -> acceleration is undefined

struct any_speed_shape inherits any_shape:
    def compute(time: time) -> speed is undefined

struct any_position_shape inherits any_shape:
    def compute(time: time) -> length is undefined

struct any_lateral_shape inherits any_shape:
    def compute(time: time) -> length is undefined

ASAM OpenSCENARIO also provides predefined shapes for common maneuvers. The common shapes include a target parameter for the relevant state variable, as well as two parameters related to the first derivative of the state. The rate_profile parameter indicates the type of dynamic_profile for the first derivative of the state. The rate_peak parameter is the peak value that must be reached by the first derivative of the state during the maneuver. These parameters provide a complete set of constraints to resolve the target shape of the state (as a function of time) that should be achieved during execution of the action.

Code 6. Built-in common shapes

struct common_acceleration_shape inherits any_acceleration_shape:
    rate_profile: dynamic_profile
    rate_peak: jerk
    target: acceleration

struct common_speed_shape inherits any_speed_shape:
    rate_profile: dynamic_profile
    rate_peak: acceleration
    target: speed

struct common_position_shape inherits any_position_shape:
    rate_profile: dynamic_profile
    rate_peak: speed
    target: length

struct common_lateral_shape inherits any_lateral_shape:
    rate_profile: dynamic_profile
    rate_peak: speed
    target: length

Users and implementers can extend the domain model and create their own shape structs with additional parameters to solve specific functional forms or sets of constraints for the shape of the state variable trajectory.

8.9.1.3 Absolute or relative movement modifiers

The scenario modifiers that set a speed, position, or lane can be either absolute or relative.

Code 7. Absolute and relative speed modifiers

position([10m..20m], at: start) # Absolute distance from the start of the path
speed([10kph..15kph], faster_than: vehicle1) # Relative
lane(same_as: vehicle1) # Relative

The relative versions require two vehicles moving in parallel. They may also have multiple parameters such as faster_than and slower_than, but at most you can specify one. These two constraints are checked at compile time. These modifiers have a track parameter that specifies whether the vehicle reacts to the actual behavior of the referenced vehicle or to its expected behavior. By default, the vehicle reacts to the actual behavior of the referenced vehicle, but there may be cases where the referenced vehicle behaves in ways that you want the vehicle to ignore. In those cases, you can require the vehicle to track the projected behavior of the referenced vehicle. For example, consider the l2: lane() and the p2: position() modifiers in phase2 of the following scenario.

Code 8. Movement modifiers

do serial():
    phase1: parallel(duration: [1.5s..3s]):
        d1: dut.vehicle.drive()
        d2: vehicle1.drive()
    phase2: parallel(duration: [1.5s..3s]):
        d3: dut.vehicle.drive()
        d4: vehicle1.drive() with:
            speed(speed: [30kph..200kph])
            l1: lane(side_of: dut.vehicle, at: start)
            p1: position(time: [0.5s..1s], ahead_of: dut.vehicle, at: start)
            l2: lane(same_as: dut.vehicle, at: end)
            p2: position(time: [1.5s..2s], ahead_of: dut.vehicle, at: end)

Because of these modifiers, at the end of phase2 the following happens:

vehicle1 ends on the same lane as the ego, even if the ego has changed lanes.
vehicle1 ends ahead of the ego, even if it has accelerated.

This behavior may be exactly what is intended. But maybe the following is intended:

vehicle1 ends in the lane where the ego was at the start of p2.
vehicle1 ends [1.5s..2s] seconds ahead of where the ego would have been, if it had continued at the same speed it was at the start of p2.

In this case, change the last two lines to:

Code 9. Adapting behavior

l2: lane(same_as: dut.vehicle, at: end, track: projected)
p2: position(time: [1.5s..2s], ahead_of: dut.vehicle, at: end, track: projected)

Negative distance values are allowed and mean "going to the other side".

Code 10. Negative distance values

lateral(distance: -2m, side: left)

The example shows being two meters to the right.

8.9.2 Modifier position()

Purpose

Set the position of an actor along the s-coordinate of the road the related actors are located on.

Category

Scenario modifier

Usage

Code 11. Position modifier

position(distance: length | time: time
[, <standard-movement-parameters>])

position(distance: length | time: time,
[ahead_of: physical_object | behind: physical_object]
[, <standard-movement-parameters>])

position(distance: length | time: time,
[ahead_of_point: position_3d | behind_point: position_3d]
[, <standard-movement-parameters>])

position(at_point: position_3d, project_on_route: bool
[, <standard-movement-parameters>])

Parameters

distance
A target length value including a length unit. The distance is calculated using the route-based s-coordinate. It is mandatory to include one (and only one) of distance or time or at_point arguments.
time
A target time value with a time unit, to determine headway time between the actor and a movable object or point. It is mandatory to include one (and only one) of distance or time or at_point arguments.
ahead_of
When ahead_of is specified, the actor must be ahead of the physical_object by the specified value using road coordinates.
behind
When behind is specified, the actor must be behind the physical_object by the specified value.
ahead_of_point
when ahead_of_point is specified, the actor must be a head of the specified point. By default the projected route.
behind_point
when behind_point is specified, the actor must be a head of the specified point. By default the projected route.
at_point
when at_point is specified, the actor must be at the specified point.
project_on_route
This option is relevant only if at_point is specified. If true (the default), project the point on the actor’s route as the reference point. If false, use the actual point. In all other cases (not using at_point), the distance or time values must be projected on the road. If the point cannot be uniqely projected on the road (for example the road ends before reaching this point), an error should be issued.
<standard-movement-parameters>
A set of parameters that are relevant for most movement modifiers. For example, at. For more information please refer to Section 8.9.1.1, “Common parameters”.

Description

The position() modifier lets you specify the position of an actor relative to the start of the path or relative to another actor.

You can specify the position by distance or time (but not both).

When ahead_of is specified, the actor must be ahead of vehicle by the specified value in the relevant period. behind contradicts ahead_of, so you cannot use them together.

When time is specified along with ahead_of or behind_of, the physical distance is calculated using the speed of the vehicle that is behind (irrespective of whether it is the actor of the scenario or the referenced vehicle) and the location at that moment of the vehicle that is ahead.

The speed of the vehicle that is ahead is not taken into the calculation. If the at parameter is all, the physical distance at any point in time refers to the speed of vehicle that is behind at that moment and the location of the vehicle that is ahead at that same moment (meaning that the physical distance may vary during the time period).

The following two examples are equivalent. In both cases the physical distance is calculated according to the speed of vehicle2.

do parallel:
    vehicle1.drive() with:
        speed(speed: 30kph, at: end)
    vehicle2.drive() with:
        speed(speed: 40kph, at: end)
        position(time: 3second, behind: vehicle1, at: end)

# is identical to:

do parallel:
    vehicle1.drive() with:
        speed(speed: 30kph, at: end)
        position(time: 3second, ahead_of: vehicle2, at: end)
    vehicle2.drive() with:
        speed(speed: 40kph, at: end)

Examples

Code 12. Position modifier

do serial:
    vehicle1.drive() with:
        # Absolute from the start of the path
        position([10m..20m])

do parallel:
    vehicle1.drive()
    vehicle2.drive() with:
        # 40 meters ahead of vehicle1 at end
         position(40meter, ahead_of: vehicle1, at: end)

do parallel:
    vehicle1.drive()
    vehicle2.drive() with:
        # Behind vehicle1 throughout
        position([20m..30m], behind: vehicle1)

do parallel:
    vehicle1.drive()
    vehicle2.drive() with:
        # Behind vehicle1, measured by time
        position(time: [2s..3s], behind: vehicle1)

8.9.3 Modifier keep_position()

Purpose

Maintain absolute position of the actor for the current period.

Category

Scenario modifier

Usage

Code 13. Keep position modifier

keep_position()

Modifier constraints are enforced during both planning and execution.

Example

Code 14. Keep position modifier

do serial:
    vehicle1.drive() with:
        keep_position()

8.9.4 Modifier speed()

Purpose

Set the speed of an actor for the current period.

Category

Scenario modifier

Usage

Code 15. Speed modifier

speed(speed: speed
[, direction: lon_lat]
[, <standard-movement-parameters>])

speed(speed: speed,
[faster_than: physical_object | slower_than: physical_object, same_as: physical_object]
[, direction: lon_lat]
[, <standard-movement-parameters>])

Parameters

speed
A target speed value, including a speed unit.
faster_than | slower_than | same_as
Use one (and only one) of these arguments set the speed target relative to another physical_object, like a vehicle, person or movable_object.
direction Determines the direction of the controlled speed. The default value is longitudinal, which controls the speed state as defined in movable_object states When the value is lateral, this modifies the lateral speed.
<standard-movement-parameters>
A set of parameters that are relevant for most movement modifiers. For example, at. For more information please refer to Section 8.9.1.1, “Common parameters”.

Description

When faster_than is specified, the actor must be faster than the physical_object by the specified value in the relevant period. The arguments slower_than, faster_than and same_as contradict each other, and cannot be used together.

Examples

Code 16. Speed modifier

do serial:
    vehicle1.drive() with:
        # Absolute speed range
        speed([10kph..20kph])

do parallel:
    vehicle1.drive()
    vehicle2.drive() with:
        # Faster than vehicle1 by [1kph..5kph]
        speed([1kph..5kph], faster_than: vehicle1)

do serial:
    vehicle1.drive() with:
        # Have that speed at end of the phase
        speed(5kph, at: end)

do parallel:
    vehicle1.drive()
    vehicle2.drive() with:
        # Either slower or faster than vehicle1
        speed([-20kph..20kph], faster_than: vehicle1)

8.9.5 Modifier change_speed()

Purpose

Change the speed of the actor for the current period.

Category

Scenario modifier

Usage

Code 17. Change speed modifier

change_speed(speed: speed
[, <standard-movement-parameters>])

Parameters

speed
A target speed value, including a speed unit.
<standard-movement-parameters>
A set of parameters that are relevant for most movement modifiers.
For example, at. For more information please refer to Section 8.9.1.1, “Common parameters”.

Example

Code 18. Change speed modifier

do serial:
    vehicle1.drive() with:
        change_speed([-20kph..20kph])

8.9.6 Modifier keep_speed()

Purpose

Maintain absolute speed of the actor for the current period.

Category

Scenario modifier

Usage

Code 19. Keep speed modifier

keep_speed()

Example

Code 20. Keep speed modifier

do serial:
    vehicle1.drive() with:
    keep_speed()

8.9.7 Modifier acceleration()

Purpose

Specify the rate of acceleration of an actor.

Category

Scenario modifier

Usage

Code 21. Acceleration modifier

acceleration(acceleration: acceleration
[, <standard-movement-parameters>])

Parameters

acceleration
A target acceleration value, with acceleration unit.
<standard-movement-parameters>
A set of parameters that are relevant for most movement modifiers.
For example, at. For more information please refer to Section 8.9.1.1, “Common parameters”.

Example

Code 22. Acceleration modifier

# Accelerate by 5kph every second
do serial:
    vehicle1.drive() with:
        acceleration(5kphps)

8.9.8 Modifier lateral()

Purpose

Set location inside the line along the lateral axis using road coordinates (T-axis).

Category

Scenario modifier

Usage

Code 23. Lateral modifier

lateral(distance: length, side_of: vehicle, side: side_left_right
[, measure_by: lat_measure_by]
[, <standard-movement-parameters>])

Parameters

distance
The offset from reference line.
side_of
The location relative to a specific vehicle.
side
Set the location on the left or on the right.
measure_by
This parameter specifies the measurement start and end points.
For example, measuring the distance from the left side of one vehicle to the right side of another vehicle.
Values can be:
- left_to_left
- left_to_center
- left_to_right
- center_to_left
- center_to_center
- center_to_right
- right_to_left
- right_to_center
- right_to_right
- closest (default)
<standard-movement-parameters>
A set of parameters that are relevant for most movement modifiers. For example, at. For more information please refer to Section 8.9.1.1, “Common parameters”.

Example

Code 24. Lateral modifier

do serial:
    vehicle1.drive() with:
        lateral(distance: 1.5meter, measure_by: right_to_right, at: start)
        # Lateral distance is measured from the right side of the vehicle to the lane edge on the right.

do serial:
    vehicle1.drive() with:
        lateral(distance: 1.5meter, side_of: v1, side: right, measure_by: right_to_left, at: start)
        # Lateral distance is measured from the right side of the vehicle to the left side of v1

8.9.9 Modifier yaw()

Purpose

Set the yaw of the vehicle.

Category

Scenario modifier

Usage

Code 25. Yaw modifier

yaw(angle: angle
[, <standard-movement-parameters>])

yaw(angle: angle, relative_to: physical_object
[, measure_by: yaw_measure_by ]
[, <standard-movement-parameters>])

Parameters

angle A single value or range with an angle unit. This parameter is mandatory.
relative_to
A named instance of the vehicle actor.
measure_by
This option is relevant only if relative_to is specified. Defines reference lines of the actor and the referenced physical_object, where width is an x-axis and long is a y-axis.
Values include:
- length_to_length
- length_to_width
- width_to_length
- width_to_width
- relative_to_north
- relative_to_road (default)
<standard-movement-parameters>
A set of parameters that are relevant for most movement modifiers.
For example, at. For more information please refer to Section 8.9.1.1, “Common parameters”.

Description

Modify the yaw angle of the actor.

Examples

Code 26. Yaw modifier

# The angle between the y-axis of the actor (vehicle1) and the s-axis of the lane is between 2 and 3 radians.
do serial:
    vehicle1.drive() with:
        yaw([2rad..3rad])

# The angle between the y-axis of the actor (vehicle1) and the y-axis of car1 is between 2 and 3 radians
do serial:
    vehicle1.drive() with:
        yaw([2rad..3rad], relative_to: car1, measure_by: length_to_length)

8.9.10 Modifier orientation()

Purpose

Specify the orientation of an actor.

Category

Scenario modifier

Usage

Code 27. Orientation modifier

orientation(yaw: angle  [, pitch: angle] [, roll: angle]
[, relative_to: physical_object] [, measure_by: orientation_measured_by]
[, <standard-movement-parameters>])

orientation(pitch: angle  [, roll: angle] [, yaw: angle]
[, relative_to: physical_object] [, measure_by: orientation_measured_by]
[, <standard-movement-parameters>])

orientation(roll: angle  [, yaw: angle] [, pitch: angle]
[, relative_to: physical_object] [, measure_by: orientation_measured_by]
[, <standard-movement-parameters>])

Parameters

yaw, pitch, roll
is an angle value, including an angle unit. Include one, two or three of the angle arguments.

relative_to
is the object relative to whom the angles will be measured. If the argument is ignored, the global coordinate system is used.

measure_by
defines how to measure the desired orientation. Values include absolute, relative_to_reference, relative_to_road. The default is relative_to_road.

<standard-movement-parameters>
are set of parameters that are relevant for most movement modifiers. For example, at. For more information please refer to Section 8.9.1.1, “Common parameters”.

Example

Code 28. Orientation modifier

# The angle between the x-axis of the actor and the s-axis of the lane is between 2 and 3 radians.
do serial:
    vehicle1.drive() with:
        orientation(yaw: [2rad..3rad])

# The angle between the x-axis of the actor and the x-axis of car1 is between 60 and 80 degrees
do serial:
    vehicle1.drive() with:
        orientation(yaw: [60deg..80deg], relative_to: car1, measure_by: length_to_length)

8.9.11 Modifier along()

Purpose

The actor moves along a route.

Category

Scenario modifier

Usage

Code 29. Along modifier

along(route: route
[, start_offset: length] [, end_offset: length]
[, <standard-movement-parameters>])

Parameters

route
The route to move along.
start_offset
How far along the route should the motion start. Default = 0m.
end_offset
How far from the end of the route should the motion end. Default = 0m.
<standard-movement-parameters>

A set of parameters that are relevant for most movement modifiers. For example, at. For more information please refer to Section 8.9.1.1, “Common parameters”.

Example

Code 30. Along modifier

# Move along a road
my_road: road
do:
    my_car.drive() with:
        along(my_road)

# Move along a path
my_path: path = map.create_path(my_list_of_points, smooth)
do:
    my_car.drive() with:
        along(my_path)

# Move along a compound route
my_route: route = map.create_route([road_01, lane_A, road_34])
do:
    my_car.drive() with:
        along(my_route)

8.9.12 Modifier along_trajectory()

Purpose

The actor moves along a trajectory.

Category

Scenario modifier

Usage

Code 31. Along trajectory modifier

along_trajectory(trajectory: trajectory
[, start_offset: length] [, end_offset: length]
[, <standard-movement-parameters>])

Parameters

trajectory
The trajectory to move along.
start_offset
How far along the trajectory should the motion start. Default = 0m.
end_offset
How far from the end of the trajectory should the motion end. Default = 0m.
<standard-movement-parameters>

A set of parameters that are relevant for most movement modifiers. For example, at. For more information please refer to Section 8.9.1.1, “Common parameters”.

Example

Code 32. Along trajectory modifier

# car1 moves along the trajectory t
car1.drive() with:
    along_trajectory(t)

8.9.13 Modifier distance()

Purpose

Constrain the distance traveled by an actor during a movement.

Category

Scenario modifier

Usage

Code 33. Distance modifier

distance(distance: length)
[, <standard-movement-parameters>]

Parameters

distance
The distance the actor should travel in the current movement.
<standard-movement-parameters>
A set of parameters that are relevant for most movement modifiers.
For example, at. For more information please refer to Section 8.9.1.1, “Common parameters”.

Description

Constrains the distance traveled by an actor during a movement such as drive().

Example

In the following example, the distance traveled by vehicle1 during the d1 phase should be within 30 to 50 meters.

Code 34. Distance modifier

do serial()
    d1: vehicle1.drive() with:
        distance([30m..50m])

8.9.14 Modifier lane()

Purpose

Set the lane in which an actor moves.

Category

Scenario modifier

Usage

Code 35. Lane syntax

lane(lane: uint, side_of: physical_object, side: side_left_right
[, standard-movement-parameters])

lane(lane: uint, from: side_left_right
[, standard-movement-parameters])

lane(same_as: physical_object
[, standard-movement-parameters])

Parameters

lane
A single unsigned integer or range of unsigned integers indicating a lane or range of lanes to move in relative to a certain reference. The parameter value (range) specifies a relative number with respect to a certain reference. This reference is given through one of the other parameters. If no lane parameter is specified, the default is 1. For the interpretation of the uint-value see the other parameter descriptions.
same_as
Option to specify that the vehicle must be in the same lane as the referenced vehicle. The default-value for the lane-parameter must be neglected.
side_of
Option to specify that the vehicle must be in another lane than the referenced vehicle. Which side is specified with the following side parameter
side
Depending on the value the actor shall be on the right or left side of the referenced physical_object. How many lanes right or left of that physical_object is specified by the lane-parameter.
from
Option to specify that the vehicle is in a certain lane with reference to the road. How many lanes from the right or left of the road is specified by the lane-parameter.
<standard-movement-parameters>
A set of parameters that are relevant for most movement modifiers. For example, at. For more information please refer to Section 8.9.1.1, “Common parameters”.

Description

Specify a lane for the actor to drive on. The lane can be chosed either relative to another physical_object on the road, or relative to the edges of the road.

Examples

Code 36. Lane modifier

do serial:
    vehicle1.drive() with:
        # Drive in lane closest to the right (right is the default)
        lane(1)

do serial:
    vehicle1.drive() with:
        # Drive in lane closest to the left side
        lane(1, from: left)

do parallel:
    vehicle2.drive()
    vehicle1.drive() with:
        # Drive one lane left of vehicle2
        lane(side_of: vehicle2, side: left)

do parallel:
    vehicle2.drive()
    vehicle1.drive() with:
        # At the end of this phase, be either one or two lanes
        # to the right of vehicle2
        lane([1..2], side_of: vehicle2, side: right, at: end)

do parallel:
    vehicle2.drive()
    vehicle1.drive() with:
        # Be in the same lane as vehicle2
        lane(same_as: vehicle2)

do serial:
    vehicle1.drive() with:
        # Drive in lane closest to the inner side (closest to opposing traffic)
        lane(1, from: map.inner_side())

do serial:
    vehicle1.drive() with:
        # Drive in lane closest to the outter side (farthest to opposing traffic)
        lane(1, from: map.outer_side())

8.9.15 Modifier change_lane()

Purpose

Specify that the actor changes lane.

Category

Scenario modifier

Usage

Code 37. Change lane modifier

change_lane(lane: int, side: side_left_right
[, <standard-movement-parameters>])

Parameters

lane
The number of lanes to change, counting from the lane where the actor starts the action. The default is 1.
side
Left or right. The side is randomized if not specified.
<standard-movement-parameters>
A set of parameters that are relevant for most movement modifiers.
For example, at. For more information please refer to Section 8.9.1.1, “Common parameters”.

Examples

Code 38. Change lane modifier

# Change lane one lane to the left
do serial:
    vehicle1.drive() with:
        change_lane(side: left)

# Change the lane 1, 2 or 3 lanes to the right
do serial:
    vehicle1.drive() with:
        change_lane([1..3], right)

8.9.16 Modifier keep_lane()

Purpose

Specify that the actor stays in the current lane.

Category

Scenario modifier

Usage

Code 39. Keep lane modifier

keep_lane()

Example

Code 40. Keep lane modifier

do serial:
    vehicle1.drive() with:
        keep_lane()

8.9.17 Modifier physical_movement()

Purpose

Set the actor movement to be physical or non-physical.

Category

Scenario modifier

Usage

Code 41. Physical movement modifier

physical_movement(option: movement_options)

Parameters

option
Can be:
- prefer_physical
  Perform the movement physical if possible.
- prefer_non_physical
  Perform the non physical way if the implementation allows that. For example, a test track may ignore this request.
- must_be_physical (default)
  An error message is issued, if this action cannot be physically performed for any reason.

Description

Describes the preferences with regard to the physical modeling of the movement of actors in the scenario.

Examples

Code 42. Physical movement modifier

do serial:
    vehicle1.drive() with:
        speed(10kph)
    vehicle1.drive() with:
        # If possible, try to make speed jump from 10kph to 20kph in zero time
        speed(20kph)
        physical_movement(prefer_non_physical)

8.9.18 Modifier avoid_collisions()

Purpose

Allow or disallow an actor to collide with another object.

Category

Scenario modifier

Usage

Code 43. Avoid collisions modifier

avoid_collisions(avoid: bool)

Parameters

avoid
Either true or false.

Description

By default, all actors avoid collisions (avoid_collisions(true)). This means that a runtime mechanism (if exists) for collision avoidance is on for the drive() scenario specified by the modifier. When set to false, the actor moves regardless of surrounding traffic and may collide.

Example

Code 44. Avoid collisions modifier

do serial:
    vehicle1.drive() with:
        avoid_collisions(false)

8.9.19 Enum at

Specify at which moments within the phase the constraint must hold.

Values

Table 130. Enum at
Value	Comment
start	This constraint holds at the start of the phase.
end	This constraint holds at the end of the phase.
all	This constraint holds throughout this phase (default).

8.9.20 Enum movement_mode

Values

Table 131. Enum movement_mode
Value	Comment
monotonous	This movement mode adheres to the laws of physics. On top of that it limits the level of surprise that a movement may have.
other	Not necessarily monotonous. This is the default.

8.9.21 Enum track

Values

Table 132. Enum track
Value	Comment
actual	Track the actual movement of the reference vehicle. This is the default.
projected	Track the "projected" movement of the reference vehicle, as it would have been if it kept the speed and direction at the start of the action.

8.9.22 Enum lat_measure_by

Specify the start and end points for lateral distance measurement. For example, measuring the distance from the left side of the actor to the right side of the reference physical_object.

Values

Table 133. Enum lat_measure_by
Value	Comment
left_to_left	From actor left to physical_object left.
left_to_center	From actor left to physical_object center.
left_to_right	From actor left to physical_object right.
center_to_left	From actor center to physical_object left.
center_to_right	From actor center to physical_object right.
right_to_left	From actor right to physical_object left.
right_to_center	From actor right to physical_object center.
right_to_right	From actor right to physical_object right.
closest	Closest lateral distance between object and physical_object.

8.9.23 Enum yaw_measure_by

Specify how relative the yaw angle is measured. Defines from which reference line on the actor and to which reference line on the referenced physical_object the yaw angle is measured.

Values

Table 134. Enum yaw_measure_by
Value	Comment
length_to_length	From actor length to physical_object length.
length_to_width	From actor length to physical_object width.
width_to_length	From actor width to physical_object length.
width_to_width	From actor width to physical_object width.
relative_to_north	Actor yaw relative to geographic North.
relative_to_road	Actor yaw relative to road s-axis.

8.9.24 Enum orientation_measured_by

Specify how to measure the orientation.

Values

Table 135. Enum orientation_measured_by
Value	Comment
absolute	Measure orientation in world coordinates.
relative_to_reference	Measure orientation relative to a reference physical_object.
relative_to_road	Measure orientation relative to road coordinates.

8.9.25 Enum movement_options

Specify how actor movement should be implemented.

Values

Table 136. Enum movement_options
Value	Comment
prefer_physical	Perform the movement physical if possible.
prefer_non_physical	Perform the non physical way if the implementation allows that. For example, a test track may ignore this request.
must_be_physical	An error message is issued, if this action cannot be physically performed for any reason.

8.9 Movement modifiers

8.9.1 Modifiers for movement actions

8.9.1.1 Common parameters

8.9.1.1.1. Parameter at

8.9.1.1.2. Parameter movement_mode

8.9.1.1.3. Parameter track

8.9.1.1.4. Parameter shape

8.9.1.2 Shape object description

8.9.1.3 Absolute or relative movement modifiers

8.9.2 Modifier position()

8.9.3 Modifier keep_position()

8.9.4 Modifier speed()

8.9.5 Modifier change_speed()

8.9.6 Modifier keep_speed()

8.9.7 Modifier acceleration()

8.9.8 Modifier lateral()

8.9.9 Modifier yaw()

8.9.10 Modifier orientation()

8.9.11 Modifier along()

8.9.12 Modifier along_trajectory()

8.9.13 Modifier distance()

8.9.14 Modifier lane()

8.9.15 Modifier change_lane()

8.9.16 Modifier keep_lane()

8.9.17 Modifier physical_movement()

8.9.18 Modifier avoid_collisions()

8.9.19 Enum at

8.9.20 Enum movement_mode

8.9.21 Enum track

8.9.22 Enum lat_measure_by

8.9.23 Enum yaw_measure_by

8.9.24 Enum orientation_measured_by

8.9.25 Enum movement_options

8.9.1.1.1. Parameter `at`

8.9.1.1.2. Parameter `movement_mode`

8.9.1.1.3. Parameter `track`

8.9.1.1.4. Parameter `shape`