8.7 Physical object actors

8.7.1 Physical objects

8.7.2 Actor osc_actor

Parent of all actors in the standard library.

Child traffic_participant_group is an actor that is defined in the informative part for groups of traffic participants and therefore not part of the normative domain model.

Basic information

Table 15. Basic information of actor osc_actor
Instantiable	no
Children	environment, map, physical_object, traffic_light_controller, traffic_participant_group

8.7.3 Actor physical_object

All tangible objects close to earth, excluding celestial objects such as sun or moon.

Basic information

Table 16. Basic information of actor physical_object
Instantiable	no
Parents	osc_actor
Children	movable_object, stationary_object

Parameters

Table 17. Actor physical_object
Parameter	Type	Mandatory	Description
bounding_box	bounding_box	yes	See bounding_box
color	color	no	See color
geometry_reference	string	no	Opaque reference of an associated 3D geometry model of the physical object. It is implementation-specific how model references are resolved to 3D models.
center_of_gravity	position_3d	yes	Center of gravity of the object. If unknown, the center of the bounding box may be used instead.

State variables

Table 18. State variables of actor physical_object
Variable	Type	Mandatory	Description
pose	pose_3d	yes	Position and orientation measured in world coordinates with world system as reference.

8.7.3.1 Methods

8.7.3.1.1 Method object_distance()

Returns the relative distance between the physical_object that calls the method and a reference entity.

The distance is computed as the position of the reference entity, measured in the coordinate system of the physical_object that calls the method. This calculation is performed either in the longitudinal direction (x-axis), lateral direction (y-axis), vertical direction (z-axis), or as a+ Euclidean distance (length of a straight line).

By default, the distance is measured between the reference points of the respective entities. Optionally, the distance between the bounding boxes can be computed instead.

Prototype

extend physical_object:
    def object_distance(reference: physical_object, direction: distance_direction, mode: distance_mode = reference_points) -> length

Return value

The relative distance between the physical_object that calls the method and the reference entity.

Parameters

Table 19. Parameters for method object_distance()
Parameter	Type	Description
reference	physical_object	The reference entity.
direction	distance_direction	Use `longitudinal` to measure the distance in the x-coordinate. Use `lateral` to measure the distance in the y-coordinate. Use `vertical` to measure the distance in the z-coordinate. Use `euclidean` to measure the Euclidean distance (length of a straight line).
mode	distance_mode	Use `reference_points` to measure the distance between the reference points. (Default) Use `bounding_boxes` to measure the distance between the bounding boxes.

8.7.3.1.2 Method road_distance()

Returns the relative road distance between the physical_object that calls the method and a reference entity.

The distance is computed as the difference between the s-t-coordinates of the reference entity and the s-t-coordinates of the physical_object that calls the method. This calculation is performed either in the longitudinal direction (s-axis) or the lateral direction (t-axis).

By default, the distance is measured between the reference points of the respective entities. Optionally, the distance between the bounding boxes can be computed.

Prototype

extend physical_object:
    def road_distance(reference: physical_object, direction: road_distance_direction, mode: distance_mode = reference_points, route_type: on_route_type = on_road) -> length

Return value

The relative distance between the physical_object that calls the method and the reference entity.

Parameters

Table 20. Parameters for method road_distance()
Parameter	Type	Description
reference	physical_object	The reference entity.
direction	road_distance_direction	Use `longitudinal` to measure the distance in the s-coordinate. Use `lateral` to measure the distance in the t-coordinate.
mode	distance_mode	Use `reference_points` to measure the distance between the reference points. (Default) Use `bounding_boxes` to measure the distance between the bounding boxes.
route_type	on_route_type	Select the type of route that will be used to compute the s-coordinate. (Default is `on_road`.)

8.7.3.1.3 Method distance_to_xyz_point()

Returns the relative distance between the physical_object that calls the method and an xyz_point.

The distance is computed as the position of the xyz_point, measured in the coordinate system of the physical_object that calls the method. This calculation is performed either in the longitudinal direction (x-axis), lateral direction (y-axis), vertical direction (z-axis), or as a Euclidean distance (length of a straight line).

By default, the distance is measured from the reference point of the physical_object. Optionally, the distance from the bounding box can be computed.

Prototype

extend physical_object:
    def distance_to_xyz_point(point: xyz_point, direction: distance_direction, mode: distance_mode = reference_points) -> length

Return value

The relative distance between the physical_object that calls the method and the reference point.

Parameters

Table 21. Parameters for method distance_to_xyz_point()
Parameter	Type	Description
point	xyz_point	The reference point.
direction	distance_direction	Use `longitudinal` to measure the distance in the x-coordinate. Use `lateral` to measure the distance in the y-coordinate. Use `vertical` to measure the distance in the z-coordinate. Use `euclidean` to measure the Euclidean distance (length of a straight line).
mode	distance_mode	Use `reference_points` to measure the distance from the reference point of the actor. (Default) Use `bounding_boxes` to measure the distance from the bounding box of the actor.

8.7.3.1.4 Method distance_to_route_point()

Returns the relative distance between the physical_object that calls the method and a route_point.

The distance is computed as the difference between the s-t-coordinates of the route_point and the s-t-coordinates of the physical_object that calls the method. This calculation is performed either in the longitudinal direction (s-axis) or the lateral direction (t-axis).

By default, the distance is measured from the reference point of the physical_object. Optionally, the distance from the bounding box can be computed.

Prototype

extend physical_object:
    def distance_to_route_point(point: route_point, direction: road_distance_direction, mode: distance_mode = reference_points, route_type: on_route_type = on_road) -> length

Return value

The relative distance between the physical_object that calls the method and the reference point.

Parameters

Table 22. Parameters for method distance_to_route_point()
Parameter	Type	Description
point	route_point	The reference point.
direction	road_distance_direction	Use `longitudinal` to measure the distance in the s-coordinate. Use `lateral` to measure the distance in the t-coordinate.
mode	distance_mode	Use `reference_points` to measure the distance from the reference point of the actor. (Default) Use `bounding_boxes` to measure the distance from the bounding box of the actor.
route_type	on_route_type	Select the type of route that will be used to compute the s-coordinate. (Default is `on_road`.)

8.7.3.1.5 Method distance_to_odr_point()

Returns the relative distance between the physical_object that calls the method and an odr_point.

The distance is computed as the difference between the s-t-coordinates of the odr_point and the s-t-coordinates of the physical_object that calls the method. This calculation is performed either in the longitudinal direction (s-axis) or the lateral direction (t-axis).

By default, the distance is measured from the reference point of the physical_object. Optionally, the distance from the bounding box can be computed.

Prototype

extend physical_object:
    def distance_to_odr_point(point: odr_point, direction: road_distance_direction, mode: distance_mode = reference_points, route_type: on_route_type = on_road) -> length

Return value

The relative distance between the physical_object that calls the method and the reference point.

Parameters

Table 23. Parameters for method distance_to_odr_point()
Parameter	Type	Description
point	odr_point	The reference point.
direction	road_distance_direction	Use `longitudinal` to measure the distance in the s-coordinate. Use `lateral` to measure the distance in the t-coordinate.
mode	distance_mode	Use `reference_points` to measure the distance from the reference point of the actor. (Default) Use `bounding_boxes` to measure the distance from the bounding box of the actor.
route_type	on_route_type	Select the type of route that will be used to compute the s-coordinate. (Default is `on_road`.)

8.7.3.1.6 Method get_s_coord()

Returns the s-coordinate of the physical_object.

By default, the method uses the s-axis of the road where the physical_object is located, but the user can select other route element types. If the physical_object is not on a route the method returns an error.

Prototype

extend physical_object:
    def get_s_coord(route_type: on_route_type = on_road) -> length

Return value

Returns a length with the s-coordinate.

Parameters

Table 24. Parameters for method get_s_coord()
Parameter	Type	Description
route_type	on_route_type	Select the type of route that will be used to compute the s-coordinate: `on_road` (default) Use the s-axis of the `road` where the actor is located. If the actor is not on a road the method returns an error. `on_lane_section` Use the s-axis of the `lane_section` where the actor is located. If the actor is not on a lane section the method returns an error. `on_lane` Use the s-axis of the `lane` where the actor is located. If the actor is not on a lane the method returns an error. `on_crossing` Use the s-axis of the `crossing` where the actor is located. If the actor is not on a crossing the method returns an error.

8.7.3.1.7 Method get_t_coord()

Returns the t-coordinate of the physical_object.

By default, the method uses the t-axis of the road where the physical_object is located, but the user can select other route element types. If the physical_object is not on a route the method returns an error.

Prototype

extend physical_object:
    def get_t_coord(route_type: on_route_type = on_road) -> length

Return value

Returns a length with the t-coordinate.

Parameters

Table 25. Parameters for method get_t_coord()
Parameter	Type	Description
route_type	on_route_type	Select the type of route that will be used to compute the t-coordinate: `on_road` (default) Use the t-axis of the `road` where the actor is located. If the actor is not on a road the method returns an error. `on_lane_section` Use the t-axis of the `lane_section` where the actor is located. If the actor is not on a lane section the method returns an error. `on_lane` Use the t-axis of the `lane` where the actor is located. If the actor is not on a lane the method returns an error. `on_crossing` Use the t-axis of the `crossing` where the actor is located. If the actor is not on a crossing the method returns an error.

8.7.3.1.8 Method get_route_point()

Returns the route_point where the physical_object is located.

By default, the method uses the road where the physical_object is located, but the user can select other route element types. If the physical_object is not on a route the method returns an error.

Prototype

extend physical_object:
    def get_route_point(route_type: on_route_type = on_road) -> route_point

Return value

Returns a route_point.

Parameters

Table 26. Parameters for method get_route_point()
Parameter	Type	Description
route_type	on_route_type	Select the type of route that will be used to compute the route_point: `on_road` (default) Use the t-axis of the `road` where the actor is located. If the actor is not on a road the method returns an error. `on_lane_section` Use the t-axis of the `lane_section` where the actor is located. If the actor is not on a lane section the method returns an error. `on_lane` Use the t-axis of the `lane` where the actor is located. If the actor is not on a lane the method returns an error. `on_crossing` Use the t-axis of the `crossing` where the actor is located. If the actor is not on a crossing the method returns an error.

8.7.3.1.9 Method set_bm()

Sets the behavioral model of a physical_object.

Prototype

extend physical_object:
    def set_bm(behavioral_model : behavioral_model)

Return value

None

Parameters

Table 27. Parameter for method set_bm()
Parameter	Type	Description
behavioral_model	behavioral_model	The behavioral model to set.

8.7.3.2 Examples

Code 71. Syntax examples for physical_object

# Constrain vehicle to be a wide car
my_wide_car: vehicle
keep(my_wide_car.vehicle_category == car)
keep(my_wide_car.bounding_box.width >= 1.95m)
keep(my_wide_car.color == maroon)
keep(my_wide_car.axles.size() == 2)
keep(my_wide_car.axles[0].number_of_wheels == 2)
keep(my_wide_car.axles[1].number_of_wheels == 2)
keep(my_wide_car.intended_infrastructure[0] == driving)

# Constrain vehicle to be a motorcycle
my_motorcycle: vehicle
keep(my_motorcycle.vehicle_category == vru_vehicle)
keep(my_motorcycle.axles.size() == 2)
keep(my_motorcycle.axles[0].number_of_wheels == 1)
keep(my_motorcycle.axles[1].number_of_wheels == 1)
keep(my_motorcycle.intended_infrastructure[0] == driving)

# Constrain vehicle to be a bicycle
my_bicycle: vehicle
keep(my_bicycle.vehicle_category == vru_vehicle)
keep(my_bicycle.axles.size() == 2)
keep(my_bicycle.axles[0].number_of_wheels == 1)
keep(my_bicycle.axles[1].number_of_wheels == 1)
keep(my_bicycle.intended_infrastructure[0] == biking)

8.7.4 Actor stationary_object

A stationary_object is a physical_object that is anchored and whose bounding box cannot change its position or speed like a tree or a building.

Basic information

Table 28. Basic information of actor stationary_object
Instantiable	yes
Parents	physical_object

Inherited parameters and variables

Table 29. Inherited parameters and variables of actor stationary_object
Parent	Inherited parameters and variables
physical_object	pose, bounding_box, color, geometry_reference, center_of_gravity

8.7.4.1 Modifiers

8.7.4.1.1 Modifier location()

Specifies the location of a stationary_object. Shall be invoked before the do section, as the location cannot be time-dependent.

Parameters

Table 30. Parameters for modifier stationary_object.location()
Parameter	Type	Description
pose	pose_3d	Location of the stationary object for the whole scenario.

Syntax

Code 72. Syntax examples for stationary_object.location()

my_pose: pose_3d
# Add constraints for fields of my_pose
my_building: stationary_object
my_building.location(my_pose)

do: ...

8.7.5 Actor movable_object

A movable_object is a physical_object that is not anchored and can, therefore, be moved and change its position and speed like a rock or a ball.

Basic information

Table 31. Basic information of actor movable_object
Instantiable	yes
Parents	physical_object
Children	traffic_participant

State variables

Table 32. State variables of actor movable_object
Variable	Type	Mandatory	Description
velocity	velocity_6d	yes	Translational and rotational velocity measured in object coordinates with world system as reference.
acceleration	acceleration_6d	yes	Translational and rotational acceleration measured in object coordinates with world system as reference.
speed	speed	yes	Speed in center_of_gravity defined as sqrt(velocity.translational.x² + velocity.translational.y²) * sign(velocity.translational.x)

Inherited parameters and variables

Table 33. Inherited parameters and variables of actor movable_object
Parent	Inherited parameters and variables
physical_object	pose, bounding_box, color, geometry_reference, center_of_gravity

8.7.5.1 Methods

8.7.5.1.1 Method distance_along_route()

Returns the distance between an actor and the start or end of a route, measured along the s-axis of the route. User can pass either a route_element or a compound_route.

Prototype

extend traffic_participant:
    def distance_along_route(route: route, from: route_distance_enum = from_start) -> length

Return value

Returns a length measured along the s-axis of the route.

Parameters

Table 34. Parameters for method distance_along_route()
Parameter	Type	Description
route	route	The route along which the distance should be measured. If the actor calling the method is not on the given route the method returns an error.
from	route_distance_enum	Reference point from which the distance is measured. `from_start` (default) Method returns the relative s-coordinate from route.start_point() to the actor. Positive means that the traffic participant is ahead of the start point. `from_end` Method returns the relative s-coordinate from the actor to the route.end_point(). Positive means that the traffic participant is behind of the end point.

8.7.6 Actor traffic_participant

A traffic_participant is a physical_object that is relevant within traffic and may perform traffic-related actions (see traffic_participant actions) such as following a route. A traffic_participant includes both, objects that do participate in traffic actively like a driven vehicle and objects that do not move throughout the scenario like a parked vehicle.

Basic information

Table 35. Basic information of actor traffic_participant
Instantiable	no
Parents	movable_object
Children	animal, person, vehicle

Parameters

Table 36. Actor traffic_participant
Parameter	Type	Mandatory	Description
intended_infrastructure	list of intended_infrastructure	yes	See intended_infrastructure for definition. Intended usage is for further specification of an entity. For example, together with vehicle_category or to provide hints for implemenations where to spawn and / or auto-route entities. Note that multiple types of infrastructure can be assigned because of the list character of this type.
role	traffic_participant_role	no	See traffic_participant_role enum. Role for the traffic participant.

Inherited parameters and variables

Table 37. Inherited parameters and variables of actor traffic_participant
Parent	Inherited parameters and variables
movable_object	velocity, acceleration, speed
physical_object	pose, bounding_box, color, geometry_reference, center_of_gravity

8.7.6.1 Methods

8.7.6.1.1 Method time_to_collision()

Returns the time that is left until a possible collision between a traffic_participant and a reference physical_object takes place.

Prototype

extend traffic_participant:
    def time_to_collision(reference: physical_object) -> time

Return value

Returns the time until the bounding_box of traffic_participant would collide with the bounding box of the reference physical_object, assuming both keep moving with their current velocity.

Parameters

Table 38. Parameter for method time_to_collision()
Parameter	Type	Description
reference	physical_object	The reference physical_object.

Syntax

Code 73. Syntax example for method time_to_collision()

scenario prevent_collision:
    ego: vehicle
    other_car: vehicle

    var collision_time: time = sample(ego.time_to_collision(reference: other_car), every(2s))

    do parallel:
        other_car.drive() with:
            speed(50kph)

        ego.drive() with:
            position(behind: other_car)
            until rise(collision_time < 10s)

8.7.6.1.2 Method time_headway()

Measure the time headway between the traffic_participant that calls the method and a reference physical_object. Time headway is defined as the time it will take the trailing actor to reach the current position of the leading actor.

The traffic_participant and the reference physical_object are assumed to be moving in a common direction.

The distance between the objects is measured from the front of the leading object to the front of the trailing object.
- For example, for two vehicles heading in the same direction, from front bumper to front bumper.
A positive value means that the traffic_participant is trailing behind the reference physical_object.
A negative value means that the traffic_participant is leading ahead of the reference physical_object.
This distance is divided by the speed of the trailing object.

The result of this division is the time headway.

Prototype

extend vehicle:
    def time_headway(reference: physical_object) -> time

Return value

Returns the time headway according to the above definition.

Parameters

Table 39. Parameter for method time_headway()
Parameter	Type	Description
reference	physical_object	The reference physical_object.

8.7.6.1.3 Method time_gap()

Returns the time distance between a traffic_participant and a reference physical_object.

For example, assume two vehicles (a traffic participant and a reference physical object) moving along a road in a common direction.

If direction is set to longitudinal, calculate the return value in the following way:

Measure the distance from the rear bumper of the leading vehicle to the front bumper of the trailing vehicle.
Divide this distance by the speed of the trailing vehicle.
The result is the longitudinal time gap.

For two vehicles traveling in the same lane the lateral time gap is not defined.

Now consider the two vehicles traveling in the same way but in different lanes.

If direction is set to lateral, calculate the return value in the following way:

Measure the distance from the right side of the vehicle on the left to the left side of the vehicle on the right.
Divide by the lateral velocity of the traffic_participant in the direction of the reference physical_object.
The result is the lateral time gap.

If the bounding boxes of traffic_participant and the reference physical_object are overlapping in the desired direction, the method shall return zero.

For two vehicles traveling in different lanes the longitudinal time gap is not defined.

Prototype

extend traffic_participant:
    def time_gap(reference: physical_object, direction: road_distance_direction) -> time

Return value

Returns the time gap according to the definition above.

Parameters

Table 40. Parameters for method time_gap()
Parameter	Type	Description
reference	physical_object	The reference entity.
direction	road_distance_direction	`longitudinal` The relative s-coordinate. Positive means that the traffic participant is ahead of the reference. `lateral` The relative t-coordinate. Positive means that the traffic participant is left of the reference.

8.7.6.1.4 Method space_gap()

Returns the space distance between a traffic_participant and a reference physical_object. The space gap distance is defined as the distance one object would need to travel to touch another object, in a given direction.

For example, assume two vehicles (a traffic participant and a reference physical object) moving along a road in a common direction. If direction is set to longitudinal, then the space gap should be measured as the distance from the rear bumper of the leading vehicle to the front bumper of the trailing vehicle.

For two vehicles traveling in the same lane the space time gap is not defined.

Now consider the two vehicles traveling in the same way but in different lanes. If direction is set to lateral, then the space gap should be measured as the distance from the right side of the vehicle on the left to the left side of the vehicle on the right.

For two vehicles traveling in different lanes the longitudinal space gap is not defined.

If the bounding boxes of the two vehicles are overlapping in the desired direction, the method shall return zero.

Prototype

extend traffic_participant:
    def space_gap(reference: physical_object, direction: road_distance_direction) -> length

Return value

Returns the space gap distance according to the definition above.

Parameters

Table 41. Parameters for method space_gap()
Parameter	Type	Description
reference	physical_object	The reference entity.
direction	road_distance_direction	`longitudinal` The relative s-coordinate. Positive means that the traffic participant is ahead of the reference. `lateral` The relative t-coordinate. Positive means that the traffic participant is left of the reference.

8.7.6.1.5 Method space_headway()

Measure the space headway between the traffic_participant that calls the method and a reference physical_object. Space headway is defined as the distance that the trailing actor needs to travel to reach the current position of the leading actor.

The traffic_participant and the reference physical_object are assumed to be moving in a common direction.

The space headway is measured as the distance from the front of the leading object to the front of the trailing object.
- For example, for two vehicles heading in the same direction, from front bumper to front bumper.
A positive value means that the traffic_participant is trailing behind the reference physical_object.
A negative value means that the traffic_participant is leading ahead of the reference physical_object.

This distance is the space headway.

Prototype

extend vehicle:
    def space_headway(reference: physical_object) -> length

Return value

Returns the space headway according to the description above.

Parameters

Table 42. Parameter for method space_headway()
Parameter	Type	Description
reference	physical_object	The reference physical_object.

8.7.7 Actor vehicle

A device intended for transport of people or cargo. Here restricted to land vehicles, meaning vehicles that move on a land surface such as a road or sidewalk.

Basic information

Table 43. Basic information of actor vehicle
Instantiable	yes
Parents	traffic_participant
Children	trailer

Parameters

Table 44. Actor vehicle
Parameter	Type	Mandatory	Description
vehicle_category	vehicle_category	yes	See vehicle_category
axles	list of axle	yes	See axle
rear_overhang	length	yes	Rear overhang of the vehicle or more explicitly the horizontal distance between the end of the bounding_box and the center of the rear axle.
trailer_receiver	hitch_receiver	no	Receiver part of the hitch that acts as mounting point for connecting a trailer. If not specified, the vehicle does not have a receiver hitching device for trailers.

Inherited parameters and variables

Table 45. Inherited parameters and variables of actor vehicle
Parent	Inherited parameters and variables
movable_object	velocity, acceleration, speed
physical_object	pose, bounding_box, color, geometry_reference, center_of_gravity
traffic_participant	intended_infrastructure, role

8.7.7.1 Modifiers

8.7.7.1.1 Modifier tow_trailer()

Specifies that the vehicle is towing a trailer. This means that the trailer receiver of the vehicle must be connected to the coupler of the trailer. Relevant state variables shall be updated to specify the connection between tow vehicle and trailer.

Parameters

Table 46. Parameters for modifier vehicle.tow_trailer()
Parameter	Type	Description
trailer	trailer	Trailer to be towed.

Syntax

Code 74. Syntax examples for vehicle.tow_trailer()

my_car: vehicle
my_trailer: trailer

my_car.tow_trailer(my_trailer)

do: ...

8.7.8 Actor trailer

A trailer is any non-self-propelled vehicle that is constructed to be towed by a power-driven vehicle. This also includes semi–trailers. (According to ECE/TRANS/WP.29/78/Rev.4)

Basic information

Table 47. Basic information of actor trailer
Instantiable	yes
Parents	vehicle

Parameters

Table 48. Actor trailer
Parameter	Type	Mandatory	Description
trailer_category	trailer_category	yes	Specify trailer category.
coupler	hitch_coupler	yes	Coupler part of the hitch that acts as mounting point to connect this trailer to the tow vehicle.

State variables

Table 49. State variables of actor trailer
Variable	Type	Mandatory	Description
tow_vehicle	vehicle	yes	Reference to the vehicle that is towing this trailer. The tow vehicle can also be another trailer. If not specified, the trailer is not towable.

Inherited parameters and variables

Table 50. Inherited parameters and variables of actor trailer
Parent	Inherited parameters and variables
movable_object	velocity, acceleration, speed
physical_object	pose, bounding_box, color, geometry_reference, center_of_gravity
traffic_participant	intended_infrastructure, role
vehicle	vehicle_category, axles, rear_overhang, trailer_receiver

8.7.8.1 Examples

Code 75. Example 1: A vehicle with a trailer attached

my_towing_truck: vehicle
keep(my_towing_truck.vehicle_category == truck)

my_receiver: hitch_receiver
keep(my_receiver.trailer_category == fifth_wheel)
keep(my_receiver.position_x == -1.2)
keep(my_receiver.position_z == 0.5)

# Specify hitch receiver characteristics on tow vehicle:
keep(my_towing_truck.trailer_receiver == my_receiver)

my_trailer: trailer
keep(my_trailer.trailer_category == full_trailer)

my_coupler: coupler_hitch
keep(my_coupler.position_x == 2.5)
keep(my_coupler.position_z == 0.5)

# Specify hitch coupler characteristics on trailer:
keep(my_trailer.coupler == my_coupler)

# The truck is towing a trailer:
my_towing_truck.tow_trailer(my_trailer)

Add the following lines to attach a second trailer to the combination in Code 75:

Code 76. Example 2: Attach a second trailer

my_trailer_also_has_a_receiver: hitch_receiver
keep(my_trailer_also_has_a_receiver.trailer_category == ball)
keep(my_trailer_also_has_a_receiver.position_x == -1.6)
keep(my_trailer_also_has_a_receiver.position_z == 0.5)

# Specify the hitch receiver on the first trailer:
keep(my_trailer.trailer_receiver == my_trailer_also_has_a_receiver)

my_second_trailer: trailer
keep(my_second_trailer.trailer_category == full_trailer)

second_trailer_coupler: hitch_coupler
keep(second_trailer_coupler.position_x == 2.5)
keep(second_trailer_coupler.position_z == 0.5)

# Specify the hitch coupler on the second trailer
keep(my_second_trailer.coupler == second_trailer_coupler)

# The second trailer is towed by the first trailer
my_trailer.tow_trailer(my_second_trailer)

When viewed driving to the left, the combination is now <my_towing_truck|--<my_trailer|--<my_second_trailer|

8.7.9 Actor person

A person represents a human being. A person may act in different and changing modalitites throughout a scenario. For example, walking or being in a car.

Basic information

Table 51. Basic information of actor person
Instantiable	yes
Parents	traffic_participant

Inherited parameters and variables

Table 52. Inherited parameters and variables of actor person
Parent	Inherited parameters and variables
movable_object	velocity, acceleration, speed
physical_object	pose, bounding_box, color, geometry_reference, center_of_gravity
traffic_participant	intended_infrastructure, role

8.7.10 Actor animal

An animal represents a living being which is not a human. An animal may act in different and changing modalitites throughout a scenario. For example, running or being in a car.

Basic information

Table 53. Basic information of actor animal
Instantiable	yes
Parents	traffic_participant

Inherited parameters and variables

Table 54. Inherited parameters and variables of actor animal
Parent	Inherited parameters and variables
movable_object	velocity, acceleration, speed
physical_object	pose, bounding_box, color, geometry_reference, center_of_gravity
traffic_participant	intended_infrastructure, role

8.7.11 Struct bounding_box

Simplified three dimensional shape enclosing the physical_object. The bounding box does NOT include side mirrors for vehicles. The height includes the ground_clearance, therefore it always goes from the top to the ground.

Basic information

Table 55. Basic information of struct bounding_box
Instantiable	no

Parameters

Table 56. Struct bounding_box
Parameter	Type	Mandatory	Description
center	position_3d	yes	Represents the geometrical center of the bounding box expressed in coordinates that refer to the coordinate system of the physical_object
length	length	yes	Dimension in x-direction of the coordinate system of the physical_object
width	length	yes	Dimension in y-direction of the coordinate system of the physical_object
height	length	yes	Dimension in z-direction of the coordinate system of the physical_object

8.7.12 Struct axle

Taken from ASAM OpenSCENARIO 1.x plus number of wheels to avoid ambiguities (for example, twin tires). Check definitions there for now.

Basic information

Table 57. Basic information of struct axle
Instantiable	no
Used by	vehicle

Parameters

Table 58. Struct axle
Parameter	Type	Mandatory	Description
max_steering	angle	yes	Maximum steering angle for the wheels on the axle
wheel_diameter	length	yes	Diameter for the wheels on this axle
track_width	length	yes	Distance between the centerline of the outer wheels on opposing sides of the axle
position_x	length	yes	Longitudinal position of the axle in the x-axis of the vehicle. For a 2-axle vehicle, the rear axle must have position_x = 0m
position_z	length	yes	Vertical position of the axle in the z-axis of the vehicle
number_of_wheels	uint	yes	Number of wheels on the axle

8.7.13 Struct hitch_receiver

A hitch is a device that connects a trailer to a towing vehicle. The hitch_receiver is on the tow vehicle. For a successful connection between tow vehicle and trailer, the hitch_type between receiver and coupler must match.

Basic information

Table 59. Basic information of struct hitch_receiver
Instantiable	no
Used by	vehicle

Parameters

Table 60. Struct hitch_receiver
Parameter	Type	Mandatory	Description
hitch_type	hitch_type	yes	Type of hitch connector. Default: none, for vehicles that do not have a hitch receiver.
position_x	length	yes	Position of the `hitch_receiver` on the x-axis of the tow vehicle.
position_z	length	yes	Position of the `hitch_receiver` on the z-axis of the tow vehicle.
max_rotation	angle	no	Maximum relative rotation between the tow vehicle and the trailer.
max_tilt	angle	no	Maximum relative tilt (pitch, roll) between the towing vehicle and the trailer.

State variables

Table 61. State variables of struct hitch_receiver
Variable	Type	Mandatory	Description
is_towing	bool	yes	Indicates if tow vehicle and trailer are connected (true) or disconnected (false).

8.7.14 Struct hitch_coupler

A hitch is a device that connects a trailer to a towing vehicle. The hitch_coupler is on the trailer. For a successful connection between tow vehicle and trailer, the hitch_type between receiver and coupler must match.

Basic information

Table 62. Basic information of struct hitch_coupler
Instantiable	no
Used by	trailer

Parameters

Table 63. Struct hitch_coupler
Parameter	Type	Mandatory	Description
hitch_type	hitch_type	yes	Type of hitch connector. There is no default type for the hitch coupler.
position_x	length	yes	Position of the `hitch_coupler` on the x-axis of the trailer.
position_z	length	yes	Position of the `hitch_coupler` on the z-axis of the trailer.

State variables

Table 64. State variables of struct hitch_coupler
Variable	Type	Mandatory	Description
is_towed	bool	yes	Indicates if tow vehicle and trailer are connected (true) or disconnected (false).

8.7.15 Enum color

Description of the color of a physical_object. Specifies the color of a physical object. Not intended to replace more detailed material properties, but rather for debugging purposes. For a vehicle this should affect the vehicle body, for pedestrians it may affect the main piece of clothing. Based on the set defined by W3C for HTML_ "basic colors".

Basic information

Table 65. Basic information of enum color
Instantiable	no

Values

Table 66. Enum color
Value	Comment
white	RGB(255,255,255)
silver	RGB(192,192,192)
gray	RGB(128,128,128)
black	RGB(0,0,0)
red	RGB(255,0,0)
maroon	RGB(128,0,0)
yellow	RGB(255,255,0)
olive	RGB(128,128,0)
lime	RGB(0,255,0)
green	RGB(0,128,0)
aqua	RGB(0,255,255)
teal	RGB(0,128,128)
blue	RGB(0,0,255)
navy	RGB(0,0,128)
fuchsia	RGB(255,0,255)
purple	RGB(128,0,128)
violet	RGB(238,130,238)
orange	RGB(255,165,0)
brown	RGB(165,42,42)
other	Other (unspecified but known) color

8.7.16 Enum vehicle_category

Vehicle category based on UN ECE/TRANS/WP.29/78/Rev.6 extended by non-self-propelled vehicles.

Basic information

Table 67. Basic information of enum vehicle_category
Instantiable	no
Used by	vehicle

Values

Table 68. Enum vehicle_category
Value	Comment
car	Power-driven vehicle with maximum mass not exceeding 3.5 t having at least four wheels comprising not more than eight seats in addition to the driver seat. Designed for the carriage of passengers or small goods. (UN category L7,M1,N1)
bus	Power-driven vehicle having at least four wheels comprising more than eight seats in addition to the driver seat.(UN category M2,M3)
truck	Power-driven vehicle with maximum mass exceeding 3.5t having at least four wheels. Designed for the carriage of goods. (UN category N2,N3)
trailer	Vehicle designed to be towed by another vehicle. Non-permanently connected to towing vehicle, meaning it can be separated by an operation without involving facilities normally only found in workshop.
vru_vehicle	Vehicle without a crash-resistant passenger cell intended for one to few passengers or small goods transport. With its occupant it results in a vulnerable road user. (UN category L1-L6 plus bicycles, pedelecs, e-bicycles, personal mobility devices, wheelchairs, mobility scooters and so on.)
other	Unspecified but known type of vehicle (for example, stroller, shopping cart, …)

8.7.17 Enum trailer_category

Trailer categories according to ECE/TRANS/WP.29/78/Rev.4

Basic information

Table 69. Basic information of enum trailer_category
Instantiable	no
Used by	trailer

Values

Table 70. Enum trailer_category
Value	Comment
semi_trailer	A towed vehicle in which the axle(s) is (are) positioned behind the centre of gravity of the vehicle (when uniformly loaded), and which is equipped with a connecting device permitting horizontal and vertical forces to be transmitted to the towing vehicle. One or more of the axles may be driven by the towing vehicle.
full_trailer	A towed vehicle that has at least two axles and is equipped with a towing device that can move vertically (in relation to the trailer) and controls the direction of the front axle(s), but that transmits no significant static load to the towing vehicle. One or more of the axles may be driven by the towing vehicle.
central_axle_trailer	A towed vehicle, equipped with a towing device that cannot move vertically (in relation to the trailer) and in which the axle(s) is (are) positioned close to the centre of gravity of the vehicle (when uniformly loaded) such that only a small static vertical load - not exceeding 10 percent of that corresponding to the maximum mass of the trailer or a load of 1,000 daN (whichever is the lesser) - is transmitted to the towing vehicle. One or more of the axles may be driven by the towing vehicle.

8.7.18 Enum hitch_type

Types of trailer hitches

Basic information

Table 71. Basic information of enum hitch_type
Instantiable	no
Used by	hitch_receiver

Values

Table 72. Enum hitch_type
Value	Comment
ball	Standard ball and coupler (including gooseneck) connector.
pintle	Pintle and hook connector.
fifth_wheel	Fifth wheel connector with jaws and kingpin.
other	Other type.
none	There is no hitch connector. Default value for all vehicles.

8.7.19 Enum intended_infrastructure

Infrastructure that is typically used by a traffic participant. Can be used to further specify an entity. For example, together with vehicle_category or to provide hints for simulators where to spawn entities. Each entity can be assigned multiple values. Note that this needs to be aligned with road abstraction feature.

Basic information

Table 73. Basic information of enum intended_infrastructure
Instantiable	no

Values

Table 74. Enum intended_infrastructure
Value	Comment
driving	Taken from ASAM OpenDRIVE: "Normal" drivable road that is not one of the other types
sidewalk	Taken from ASAM OpenDRIVE: Lane reserved for pedestrians
biking	Taken from ASAM OpenDRIVE: Lane reserved for cyclists
rail	Taken from ASAM OpenDRIVE: Lane reserved for trains
tram	Taken from ASAM OpenDRIVE: Lane reserved for trams
bus	Taken from ASAM OpenDRIVE: Lane reserved for buses
taxi	Taken from ASAM OpenDRIVE: Lane reserved for taxis
hov	Taken from ASAM OpenDRIVE: Lane reserved for High Occupancy Vehicles (HOVs)

8.7.20 Enum traffic_participant_role

The role specifies the perceivable role of a traffic participant, as that might influence the behavior in traffic of surrounding traffic participants. The majority of traffic participants are civil, representing normal traffic participants. Whether a role is active (for example, in the sense of an ambulance flashing its emergency vehicle lighting) is independent of the role of the traffic participant.

Basic information

Table 75. Basic information of enum traffic_participant_role
Instantiable	no

Values

Table 76. Enum traffic_participant_role
Value	Comment
civil	The entity role is civil (for example, a "normal" vehicle).
ambulance	The entity role is ambulance.
fire	The entity role is fire fighting (for example, a fire engine).
military	The entity role is military (for example, a camouflaged truck).
police	The entity role is police.
public_transport	The entity role is public transport (for example, a school bus).
road_assistance	The entity role is roadside assistance (for example, a tow truck).
garbage_collection	The entity role is garbage collection, (for example, a garbage truck or sweeper).
road_construction	The entity role is road construction (for example, an excavator or a tipper truck).
other	The entity has another unspecified but known role.

8.7.21 Enum distance_direction

Basic information

Table 77. Basic information of enum distance_direction
Used by	keep_space_gap

Values

Table 78. Enum distance_direction
Value	Comment
longitudinal	Measure distance in the x-coordinate. Positive means that the `reference` is in front of the `physical_object` that calls the method.
lateral	Measure distance in the y-coordinate. Positive means that the `reference` is to the left of the `physical_object` that calls the method.
vertical	Measure distance in the z-coordinate. Positive means that the `reference` is to the above the `physical_object` that calls the method.
euclidean	Measure distance in a Eucledian (or straight-line) way. Result is always positive.

8.7.22 Enum road_distance_direction

Values

Table 79. Enum road_distance_direction
Value	Comment
longitudinal	Measure distance in the s-coordinate. Positive means that the `reference` is in front of the `physical_object` that calls the method.
lateral	Measure distance in the t-coordinate. Positive means that the `reference` is to the left of the `physical_object` that calls the method.

8.7.23 Enum distance_mode

Values

Table 80. Enum distance_mode
Value	Comment
reference_points	Measures the distance between the reference points.
bounding_boxes	Measures the distance between the bounding boxes.

8.7.24 Enum on_route_type

Select which s/t coordinate system is used to obtain the coordinates

Values

Table 81. Enum on_route_type
Value	Comment
on_road	Use the `road` s/t coordinates
on_lane_section	Use the `lane_section` s/t coordinates
on_lane	Use the `lane` s/t coordinates
on_crossing	Use the `crossing` s/t coordinates

8.7.25 Enum route_distance_enum

Reference point from which the distance is measured.

Values

Table 82. Enum route_distance_enum
Value	Comment
from_start	Measure distance from the start of the route.
from_end	Measure distance from the end of the route.

8.7.26 Groups of traffic participants

Please note that the following section and its sub-sections are non-normative.

Many implementations for the creation and the handling of groups of traffic participants exist. Some traffic flow simulators use stochastic traffic flow models and others use deterministic modeling approaches.

The following content is an example on how to build groups using only generic ASAM OpenSCENARIO language features. A standard group model may be included in future versions of the standard.

Groups represent multiple actor instances with multiple definitions and states. It is assumed that scenario authors will likely define groups at the top level and not under lower levels in the domain model hierarchy such as physical_actor.

8.7.26.1 Actor vehicle_group

A traffic_participant_group serves as a collection of traffic_participant actors. A group represents multiple actor instances with multiple definitions and states.

There are two main use cases for vehicle groups:

Adding entities to a scenario to have more participants in the scenario. By generating multiple vehicles in the surrounding environment of the scenario these vehicles act as 'noise' in the scenario.
Creating multiple vehicles with predefined initial conditions.
For example, creating a single-lane or convoy formation of vehicles, or both.

Initial conditions of actors and the actual behavior of actors throughout the scenarios differ:

The group defines the initial conditions of actors in the scenario, meaning their creation and destruction.
The behavioral model assigned to each vehicle defines the actual behavior of the vehicle within the group.

Basic information

Table 83. Basic information of actor vehicle_group
Instantiable	no
Parents	traffic_participant_group
Children	common_route_vehicle_group, random_traffic_vehicle_group

Parameters

Table 84. Actor vehicle_group
Parameter	Type	Mandatory	Description
vehicles	list of vehicle	yes	List of vehicles being part of this group.

8.7.26.1.1 Examples

Code 77. Example for vehicle_group

scenario dut.driving_alongside_group:
    # Defining a group with a common route and
    # a single-lane formation
    g: single_lane_vehicle_group

    # Using 'for' constraint to control vehicles
    # parameters
    for v in g.vehicles:
        keep(v.category in [bus, truck])

    r: route

    do parallel:
        g.drive() with:
            along(r)
            lane(side_of: dut.vehicle, at: start)
        dut.vehicle.drive() with:
            along(r)