MSP entities

MSP position

Proprietary or custom maps require the support of a Map Support Package (MSP). An MSP contains a list of roads (a road graph) and for each road, a list of lanes (a lane graph).

msp_position

Defines a position on a map.

OSC2 code: msp_position syntax

struct msp_position:
    var global_position: global_position
    var lane_position: msp_lane_position
    var road_position: msp_road_position

    # Get position at given offset using current position's rotation
    def at_offset_local(dx: length, dy: length, dz: length)-> msp_position

    # Get position at given distance and rotation relative to current position
    # (given rotation is relative to current position's rotation)
    def at_rotated_offset(offset: length, yaw: angle)-> msp_position

    # Get position rotated around given point and given rotation angle
    # (given rotation is relative to current position's rotation)
    #
    def at_rotated_around(rotation_center: msp_coordinates, yaw: angle) -> msp_position

    # Get a duplicate of position
    def deep_copy()-> msp_position

global_position

Defines a position in three-dimensional space.

OSC2 code: global_position syntax

struct global_position:
    var coord: msp_coordinates # x, y and z coordinates
    var rotation: msp_angles # roll, yaw, and pitch angles

    # Get a duplicate of global position
    def deep_copy()-> global_position

See Foretify's coordinate system.

msp_coordinates

Defines coordinates in three-dimensional space.

OSC2 code: msp_position syntax

struct msp_coordinates:
    x: length
    y: length
    z: length

    def distance(other: msp_coordinates)-> length
    def sqr_distance(other: msp_coordinates)-> float
    def angle_from(other: msp_coordinates)-> angle  # The range of the result is [-180..180] (not [0..360])
    def angle_to(other: msp_coordinates)-> angle    # The range of the result is [-180..180]
    def get_point_at(distance: length, angle: angle)-> msp_coordinates

See Foretify's coordinate system.

msp_angles

Defines angles in three-dimensional space.

OSC2 code: msp_angles syntax

struct msp_angles:
    roll: angle
    yaw: angle
    pitch: angle

msp_lane_position

Defines a logical position on the lane graph.

OSC2 code: msp_lane_position syntax

struct msp_lane_position:

    # Logical lane object
    var lane: msp_lane

    # Offset from lane start
    var lon_offset: length

    # Distance from lane center (negative is right, positive is left)
    var lat_offset: length

    # Angle relative to the lane center line
    var relative_yaw: angle

msp_lane

Defines a single lane in the lanes graph.

OSC2 code: msp_lane syntax

struct msp_lane:
    # Internal unique ID
    #
    var internal_id: uint

    # Lane ID from the loaded map
    #
    var map_id: string

    # Offset from the original lane start
    #
    var map_offset: length

    # Previous lanes in graph
    #
    var previous: list of msp_lane

    # Next lanes in graph
    #
    var next: list of msp_lane

    # Parent road
    #
    var road: msp_road

    # From right edge (starts from 1)
    #
    var index_in_road: uint

    # Total length - according to lane center line
    #
    var length: length

    # Coordinates at lane start
    # Optional, used for debugging purposes
    #
    var start_coord: msp_coordinates

    # Coordinates at lane end
    # Optional, used for debugging purposes
    #
    var end_coord: msp_coordinates

    # Defined lane uses
    #
    var lane_uses: list of msp_lane_use

msp_road_position

Defines a logical position on the road graph.

OSC2 code: msp_road_position syntax

    struct msp_road_position:

    # Logical road object
    #
    var road: msp_road

    # Offset from road start
    #
    var lon_offset: length

msp_road

Defines a single road in the roads graph.

OSC2 code: msp_road syntax

# msp_road_category - can be used to limit actors to roads with specific categories.
#
enum msp_road_category: [regular=0]

struct msp_road:
   # Internal unique ID
   #
   var internal_id: uint

   # Road length
   # As there is no single correct length for a road,
   # this value should represent the length of its lanes as much as possible.
   # This value can be measured according to the
   # judgement of the Map Support Package implementor
   #
   var length: length

   # Previous roads in graph
   #
   var previous: list of msp_road

   # Next roads in graph
   #
   var next: list of msp_road

   # Road's lanes
   #
   var lanes: list of msp_lane

   # Points to the msp_road that corresponds to the opposite
   # driving side of the "real" road. May be null
   #
   var opposite_road: msp_road

   # Flag to mark virtual roads
   #
   var is_virtual: bool

    # By default SUT is limitted to 'regular' roads.
    #
    var category: msp_road_category

crossing_path

This road element represents a road that crosses a referenced path on a custom map.

Definition:

OSC2 code: crossing_path syntax

struct crossing_path: road_element:
    kind:road_pattern_id
    segment_id: int
    var cross_point: msp_lane_position

Fields:

kind is oncoming or traverse.

MSP traffic signal

MSP traffic signals include both:

Dynamic traffic lights
Static traffic signs

msp_traffic_signal

This struct is the base type for traffic signals, including both static signs and dynamic lights:

msp_traffic_sign (static)
msp_traffic_light (dynamic)
msp_physical_traffic_light (dynamic)

OSC2 code: msp_traffic_signal syntax

struct msp_traffic_signal:
    # 'id' is unique within each subtype
    var id: uint

msp_traffic_signal_lane_ref

This struct is a per-lane reference to an msp_traffic_signal holding the logical-position or stopping-offset on the lane.

OSC2 code: msp_traffic_signal_lane_ref syntax

struct msp_traffic_signal_lane_ref:
    var signal: msp_traffic_signal
    # logical-position / stopping-offset on the lane
    #
    var lane_pos: msp_lane_position

msp_lane (extension)

The msp_lane struct is extended to hold a list of msp_traffic_signal_lane_ref sorted in ascending order by msp_traffic_signal_lane_ref.lane_pos.lon_offset.

OSC2 code: msp_lane extension

extend msp_lane:
    # traffic signals sorted by msp_traffic_signal_lane_ref.lane_pos.lon_offset ascending
    #
    var signals: list of msp_traffic_signal_lane_ref

msp_traffic_sign

This struct models static traffic signs, such as stop signs, yield signs and so on.

OSC2 code: traffic_sign syntax

struct msp_traffic_sign: msp_traffic_signal:
    var kind: traffic_sign_kind

msp_traffic_light

This struct models a "logical" traffic light. It can be used if both the map and the simulator support logical traffic lights.

An msp_traffic_light is a set of physical traffic-light "boxes" (msp_physical_traffic_light), and its bulbs_state is a union of the bulbs of its member boxes.

OSC2 code: msp_traffic_light syntax

struct msp_traffic_light: msp_traffic_signal:
    # Loaded from map if it has a definition of logical TL
    #
    var map_id: string

    var bulbs: list of msp_traffic_light_bulb
    var bulbs_state: list of bulb_state_kind
    var tl_boxes: list of msp_physical_traffic_light

msp_physical_traffic_light

This struct models a "physical" traffic light. It can be used if both the map and the simulator support physical traffic lights.

OSC2 code: msp_physical_traffic_light syntax

struct msp_physical_traffic_light:
    var internal_id: uint

    # Loaded from map if it has a definition of physical TL
    #
    var map_id: string

    var bulbs: list of msp_traffic_light_bulb
    var logical_tl: msp_traffic_light

msp_traffic_light_bulb

This struct represents a single bulb in a physical or logical traffic light.

OSC2 code: msp_traffic_light_bulb syntax

struct msp_traffic_light_bulb:
    var map_id: string
    var icon: bulb_icon_kind
    var color: bulb_color_kind

map (extension)

This construct extends map to add a list of traffic lights.

OSC2 code: map extension for traffic_lights syntax

extend map:
    # All traffic lights in map. traffic_lights[n].id == n
    #
    var traffic_lights: list of msp_traffic_light

Lane marks

This struct defines the lines that mark a lane's boundary. line_kind and line_color are defined in Predefined enums.

OSC2 code: lane mark syntax

struct lane_mark:
    kind: line_kind
    color: line_color

The methods in the following table calculate the distance between two positions on the map.

Signature	Description
map.distance_from_ref_position(ref_pos: msp_road_position, pos: msp_road_position)-> length	Returns the distance between two positions along the road network in the driving direction. To do so, it checks the shortest distance from `ref_pos` to `pos` and the shortest distance from `pos` to `ref_pos`. Note these can be different since it is the distance along the road network in the driving direction. If the distance from `pos` to `ref_pos` is shorter or equal to the distance from `ref_pos` to `pos`, the method returns a negative value. If the distance from `ref_pos` to `pos` is shorter, then the method returns that value. The coordinate system used is the road/lane system. If none of the two distances actually exists, the function will return MAX_INT.
map.abs_distance_between_positions(road_pos1 : msp_road_position, road_pos2 : msp_road_position)-> length	Returns the absolute distance between two positions. To do so, it takes the absolute value of `map.distance_from_ref_position` described above.
msp_position.at_offset_local(dx: length , dy: length , dz: length )-> msp_position	Returns a position that is at the specified X/Y/Z offset from the referenced msp_position.

Type name	Value	Description
traffic_sign_kind	stop, yield, other	Define the type of traffic sign.
logical_traffic_light_state	red, green, yellow	Define the state of a logical traffic light.
bulb_color_kind	unknown, red, yellow, green, blue, white	Define the color of a physical traffic light bulb.
bulb_icon_kind	unknown, none, arrow_straight, arrow_left, arrow_right, pedestrian, walk, dont_walk, bicycle, countdown	Define the icon of a physical traffic light bulb.
bulb_state_kind	unknown, is_off, is_on, flashing	Define the state of a physical traffic light bulb.

Type name	Value	Description
traffic_lights_api_level	One of none: no support for traffic lights in SSP for the simulator. physical: the field "signal ID" in SSP API represents a physical traffic light. logical: the field "signal ID" in SSP API represents logical traffic light.	Define the level used in the SSP API to control traffic lights.
traffic_lights_default_color	One of none: traffic lights start in their default state as defined by simulator. green: all traffic lights are initialized to green. red: all traffic lights are initialized to red.	Defines options for setting the default color of all traffic lights on simulation start.