Skip to content

tactics2d.map

tactics2d.map.element

Node

This class implements the map element Node.

The add operation of the node is defined as the addition of the coordinates of the node.

The subtract operation of the node is defined as the subtraction of the coordinates of the node.

Attributes:

Name Type Description
id_ str

The id of the node.

x float

The x coordinate of the node.

y float

The y coordinate of the node.

location Point

The location of the node expressed in geometry format. This attribute is read-only.

__init__(id_, x, y)

Initialize an instance of this class.

Parameters:

Name Type Description Default
id_ str

The id of the node.

required
x float

The x coordinate of the node.

required
y float

The y coordinate of the node.

required

RoadLine

This class implements the map element LineString

Attributes:

Name Type Description
id_ str

The unique identifier of the roadline.

geometry LineString

The geometry information of the roadline.

type_ str

The type of the roadline. Defaults to "virtual".

subtype str

The subtype of the line. Defaults to None.

color Any

The color of the area. If not specified, the color will be assigned based on the rendering template later. Defaults to None.

width float

The width of the line (in m). Used in rendering. Defaults to None.

height float

The height of line (in m). The linestring then represents the lower outline/lowest edge of the object. Defaults to None.

lane_change Tuple[bool, bool]

Whether a vehicle can switch to a left lane or a right lane. The first element in the tuple denotes whether the vehicle can switch from the left to the right of the line, and the second element denotes whether the vehicle can switch from the right to the left of the line. Defaults to None.

temporary bool

Whether the roadline is a temporary lane mark or not. Defaults to False.

custom_tags dict

The custom tags of the raodline. Defaults to None.

head Point

The head point of the roadline. This attribute is read-only.

end Point

The end point of the roadline. This attribute is read-only.

shape list

The shape of the roadline. This attribute is read-only.

__init__(id_, geometry, type_='virtual', subtype=None, color=None, width=None, height=None, lane_change=None, temporary=False, custom_tags=None)

Initialize an instance of the class.

Parameters:

Name Type Description Default
id_ str

The unique identifier of the roadline.

required
geometry LineString

The shape of the line expressed in geometry format.

required
type_ str

The type of the roadline.

'virtual'
subtype str

The subtype of the line.

None
color tuple

The color of the area. If not specified, the color will be assigned based on the rendering template later.

None
width float

The width of the line (in m). Used in rendering.

None
height float
None
lane_change Tuple[bool, bool]

Whether a vehicle can switch to a left lane or a right lane. The first element in the tuple denotes whether the vehicle can switch from the left to the right of the line, and the second element denotes whether the vehicle can switch from the right to the left of the line.

None
temporary bool

Whether the roadline is a temporary lane mark or not.

False
custom_tags dict

The custom tags of the raodline.

None

Lane

This class implements the map element Lane

Attributes:

Name Type Description
id_ str

The unique identifier of the lane.

left_side LineString

The left side of the lane.

right_side LineString

The right side of the lane.

line_ids dict

The ids of the roadline components. The dictionary has two keys: left and right. Defaults to dict(left=[], right=[]).

regulatory_ids set

The ids of the regulations that apply to the lane. Defaults to set().

type_ str

The type of the lane. The default value is "lanelet".

subtype str

The subtype of the lane. Defaults to None.

color Any

The color of the area. If not specified, the color will be assigned based on the rendering template later. Defaults to None.

location str

The location of the lane (urban, nonurban, etc.). Defaults to None.

inferred_participants list

he allowing type of traffic participants that can pass the area. If not specified, the area is not restricted to any type of traffic participants. Defaults to None.

speed_limit float

The speed limit in this area The unit is m/s. Defaults to None.

speed_limit_mandatory bool

Whether the speed limit is mandatory or not. Defaults to True.

custom_tags dict

The custom tags of the area. Defaults to None.

custom_tags dict

The custom tags of the lane. Defaults to None.

predecessors set

The ids of the available lanes before entering the current lane.

successors set

The ids of the available lanes after exiting the current lane.

left_neighbors set

The ids of the lanes that is adjacent to the left side of the current lane and in the same direction.

right_neighbors set

The ids of the lanes that is adjacent to the right side of the current lane and in the same direction.

starts list

The start points of the lane.

ends list

The end points of the lane.

geometry LinearRing

The geometry representation of the lane. This attribute will be automatically obtained during the initialization if there is no None in left_side and right_side.

shape list

The shape of the lane. This attribute is read-only.

__init__(id_, left_side, right_side, line_ids=dict(left=[], right=[]), regulatory_ids=set(), type_='lanelet', subtype=None, color=None, location=None, inferred_participants=None, speed_limit=None, speed_limit_unit='km/h', speed_limit_mandatory=True, custom_tags=None)

Initialize an instance of this class.

Parameters:

Name Type Description Default
id_ str

The unique identifier of the lane.

required
left_side LineString

The left side of the lane.

required
right_side LineString

The right side of the lane.

required
line_ids set

The ids of the lines that make up the lane.

dict(left=[], right=[])
regulatory_ids set

The ids of the regulations that apply to the lane.

set()
type_ str

The type of the lane.

'lanelet'
subtype str

The subtype of the lane.

None
color Any

The color of the lane. If not specified, the color will be assigned based on the rendering template later.

None
location str

The location of the lane (urban, nonurban, etc.).

None
inferred_participants list

The allowing type of traffic participants that can pass the lane. If not specified, the lane is not restricted to any type of traffic participants.

None
speed_limit float

The speed limit in this lane.

None
speed_limit_unit str

The unit of speed limit in this lane. The valid units are km/h, mi/h, and m/s. Defaults to "km/h". The speed limit will be automatically converted to m/s when initializing the instance. If the unit is invalid, the speed limit will be set to None.

'km/h'
speed_limit_mandatory bool

Whether the speed limit is mandatory or not.

True
custom_tags dict

The custom tags of the lane.

None

Add a related lane's id to the corresponding list

Parameters:

Name Type Description Default
id_ str

The related lane's id

required
relationship LaneRelationship

The relationship of the lanes. The possible values are 1/PREDECESSOR, 2/SUCCESSOR, 3/LEFT_NEIGHBOR, and 4/RIGHT_NEIGHBOR.

required

Check if a given lane is related to the lane

Parameters:

Name Type Description Default
id_ str

The given lane's id.

required

Area

This class implements the Area

Reference

[Lanelet2's description of an area](https://github.com/fzi-forschungszentrum-informatik/Lanelet2/blob/master/lanelet2_core/doc/LaneletPrimitives.md

Attributes:

Name Type Description
id_ str

The unique identifier of the area.

geometry Polygon

The geometry information of the area.

line_ids dict

The ids of the lines that circle this area. Defaults to dict(inner=[], outer=[]).

regulatory_ids set

The ids of the regulations that apply to the area. Defaults to set().

type_ str

The type of the area. The default value is "multipolygon".

subtype str

The subtype of the area. Defaults to None.

color Any

The color of the area. If not specified, the color will be assigned based on the rendering template later. Defaults to None.

location str

The location of the area (urban, nonurban, etc.). Defaults to None.

inferred_participants list

The allowing type of traffic participants that can pass the area. If not specified, the area is not restricted to any type of traffic participants. Defaults to None.

speed_limit float

The speed limit in this area The unit is m/s. Defaults to None.

speed_limit_mandatory bool

Whether the speed limit is mandatory or not. Defaults to True.

custom_tags dict

The custom tags of the lane. Defaults to None.

shape List[list, list]

The shape of the area. The first list contains the outer shape, and the second list contains the inner shapes. Defaults to None. This attribute is read-only.

__init__(id_, geometry, line_ids=dict(inner=[], outer=[]), regulatory_ids=set(), type_='multipolygon', subtype=None, color=None, location=None, inferred_participants=None, speed_limit=None, speed_limit_unit='km/h', speed_limit_mandatory=True, custom_tags=None)

Initialize an instance of this class.

Parameters:

Name Type Description Default
id_ str

The unique identifier of the area.

required
geometry Polygon

The geometry shape of the area.

required
line_ids dict

The ids of the lines that circle this area.

dict(inner=[], outer=[])
regulatory_ids set

The ids of the regulations that apply to the area.

set()
type_ str

The type of the area.

'multipolygon'
subtype str

The subtype of the area.

None
color Any

The color of the area. If not specified, the color will be assigned based on the rendering template later.

None
location str

The location of the area (urban, nonurban, etc.).

None
inferred_participants list

The allowing type of traffic participants that can pass the area. If not specified, the area is not restricted to any type of traffic participants.

None
speed_limit float

The speed limit in this area.

None
speed_limit_unit str

The unit of speed limit in this area. The valid units are km/h, mi/h, and m/s. Defaults to "km/h". The speed limit will be automatically converted to m/s when initializing the instance. If the unit is invalid, the speed limit will be set to None.

'km/h'
speed_limit_mandatory bool

Whether the speed limit is mandatory or not.

True
custom_tags dict

The custom tags of the area.

None

Regulatory

This class implements the lanelet2-style map element RegulatoryElement.

Note

This class is still under development. It is supposed to support the detection of traffic events in the future.

Attributes:

Name Type Description
id_ str

The id of the regulatory element.

relations dict

A dictionary of the relations that the regulatory element belongs to. The key is the id of the relation, and the value is the role of the relation. Defaults to an empty dictionary.

ways dict

A dictionary of the ways that the regulatory element belongs to. The key is the id of the way, and the value is the role of the way. Defaults to an empty dictionary.

nodes dict

A dictionary of the nodes that the regulatory element belongs to. The key is the id of the node, and the value is the role of the node. Defaults to an empty dictionary.

type_ str

The type of the regulatory element. Defaults to "regulatory_element".

subtype str

The subtype of the regulatory element.

position str

The position of the regulatory element. Defaults to None.

location str

The location of the regulatory element. Defaults to None.

dynamic bool

Whether the regulatory element is dynamic. Defaults to False.

fallback bool

Whether the regulatory element is a fallback. Defaults to False.

custom_tags dict

The custom tags of the regulatory element. Defaults to None.

__init__(id_, relations=dict(), ways=dict(), nodes=dict(), type_='regulatory_element', subtype=None, position=None, location=None, dynamic=False, fallback=False, custom_tags=None)

Initialize the attributes in the class.

Parameters:

Name Type Description Default
id_ str

The id of the regulatory element.

required
relations dict

A dictionary of the relations that the regulatory element belongs to. The key is the id of the relation, and the value is the role of the relation.

dict()
ways dict

A dictionary of the ways that the regulatory element belongs to. The key is the id of the way, and the value is the role of the way.

dict()
nodes dict

A dictionary of the nodes that the regulatory element belongs to. The key is the id of the node, and the value is the role of the node.

dict()
type_ str

The type of the regulatory element.

'regulatory_element'
subtype str

The subtype of the regulatory element.

None
position str

The position of the regulatory element.

None
location str

The location of the regulatory element.

None
dynamic bool

Whether the regulatory element is dynamic.

False
fallback bool

Whether the regulatory element is a fallback.

False
custom_tags dict

The custom tags of the regulatory element.

None

Map

This class implements a map to manage the road elements. The elements in the map include nodes, lanes, areas, roadlines, and regulations. The map is used to store the road elements and provide the interface to access the elements. Every element in the map should have a unique id.

Attributes:

Name Type Description
name str

The name of the map. Defaults to None.

scenario_type str

The scenario type of the map. Defaults to None.

country str

The country that the map is located in. Defaults to None.

ids set

The identifier of the elements in the map. All elements in the map should have a unique id. A conflict in ids will raise a KeyError.

nodes dict

The nodes in the map. Defaults to an empty dictionary. This attribute needs to be set manually by trigger the add_node method.

lanes dict

The lanes in the map. Defaults to an empty dictionary. This attribute needs to be set manually by trigger the add_lane method.

areas dict

The areas in the map. Defaults to an empty dictionary. This attribute needs to be set manually by trigger the add_area method.

roadlines dict

The roadlines in the map. Defaults to an empty dictionary. This attribute needs to be set manually by trigger the add_roadline method.

regulations dict

The regulations in the map. Defaults to an empty dictionary. This attribute needs to be set manually by trigger the add_regulatory method.

boundary tuple

The boundary of the map expressed in the form of (min_x, max_x, min_y, max_y). This attribute is read-only.

__init__(name=None, scenario_type=None, country=None)

Initialize the attributes in the class.

Parameters:

Name Type Description Default
name str

The name of the map. Defaults to None.

None
scenario_type str

The scenario type of the map. Defaults to None.

None
country str

The country that the map is located in. Defaults to None.

None

add_area(area)

This function adds an area to the map.

Parameters:

Name Type Description Default
area Area

The area to be added to the map.

required

Raises:

Type Description
KeyError

If the id of the area is used by any other road element.

add_junction(junction)

This function adds a junction to the map.

Parameters:

Name Type Description Default
junction Junction

The junction to be added to the map.

required

add_lane(lane)

This function adds a lane to the map.

Parameters:

Name Type Description Default
lane Lane

The lane to be added to the map.

required

Raises:

Type Description
KeyError

If the id of the lane is used by any other road element.

add_node(node)

This function adds a node to the map.

Parameters:

Name Type Description Default
node Node

The node to be added to the map.

required

Raises:

Type Description
KeyError

If the id of the node is used by any other road element.

add_regulatory(regulatory)

This function adds a traffic regulation to the map.

Parameters:

Name Type Description Default
regulatory Regulatory

The regulatory to be added to the map.

required

Raises:

Type Description
KeyError

If the id of the regulatory is used by any other road element.

add_roadline(roadline)

This function adds a roadline to the map.

Parameters:

Name Type Description Default
roadline RoadLine

The roadline to be added to the map.

required

Raises:

Type Description
KeyError

If the id of the roadline is used by any other road element.

get_by_id(id_)

This function returns the road element with the given id.

Parameters:

Name Type Description Default
id_ str

The id of the road element.

required

reset()

This function resets the map by clearing all the road elements.

set_boundary(boundary)

This function sets the boundary of the map.

Parameters:

Name Type Description Default
boundary tuple

The boundary of the map expressed in the form of (min_x, max_x, min_y, max_y).

required

tactics2d.map.converter

tactics2d.map.generator

ParkingLotGenerator

Generate a random bay parking lot scenario with determined start and destination.

Attributes:

Name Type Description
vehicle_size Tuple[float, float]

The size of the vehicle. The first element is the length and the second element is the width. This value is used to generate the target parking space. Defaults to (5.3, 2.5).

type_proportion float

The proportion of "bay" parking scenario in all generated scenarios. It should be in the range of [0, 1]. If the input is out of the range, it will be clipped to the range. When it is 0, the generator only generates "parallel" parking scenarios. Defaults to 0.5.

mode str

The type of the parking scenario. It can be "bay" or "parallel". Defaults to None.

__init__(vehicle_size=(5.3, 2.5), type_proportion=0.5)

Initialize the attributes in the class.

Parameters:

Name Type Description Default
vehicle_size Tuple[float, float]

he size of the vehicle. The first element is the length and the second element is the width. This value is used to generate the target parking space.

(5.3, 2.5)
type_proportion float

The proportion of "bay" parking scenario in all generated scenarios. It should be in the range of [0, 1]. If the input is out of the range, it will be clipped to the range. When it is 0, the generator only generates "parallel" parking scenarios. When it is 1, the generator only generates "bay" parking scenarios.

0.5

generate(map_)

Generate a random parking scenario.

Parameters:

Name Type Description Default
map_ Map

The map instance to store the generated parking scenario.

required

Returns:

Name Type Description
start_state State

The start state of the vehicle.

target_area Area

The target area of the parking scenario.

target_heading float

The heading of the target area.

RacingTrackGenerator

This class generates random racing tracks.

The generating process can be described as follows:

  1. Generate a circle with a radius = 800 m. Ideally, the time needed for a vehicle to make a full turn in this circle is around 3 minutes if it drives at a speed of 100 km/h.
  2. Generate some checkpoints that are deviated from the circle.
  3. Generate the center line by interpolating the checkpoints with Bezier curves.
  4. Check if the center line has extremely sharp turns. If so, adjust the checkpoints.
  5. Iterate until the center line is valid.
  6. Generate the tiles by interpolating the center line.
  7. Generate the road bounds by adding the track width to the left and right of the center line.

Attributes:

Name Type Description
bezier_order int

The order of the Bezier curve. Defaults to 2.

bezier_interpolation int

The number of interpolation points for each Bezier curve. Defaults to 50.

__init__(bezier_order=2, bezier_interpolation=50)

Initialize the attributes in the class.

generate(map_)

This method generates a racing scenario and stores it in the given map instance.

Parameters:

Name Type Description Default
map_ Map

The map instance to store the generated racing scenario.

required

tactics2d.map.parser

OSMParser

This class implements a parser for the original OpenStreetMap format map.

The parser is tested with data generated by the official website of OpenStreetMap and the software application JOSM.

load_area_lanelet2(xml_node, map_)

This function loads a Lanelet 2 area from the XML node.

Parameters:

Name Type Description Default
xml_node Element

The XML node of the area.

required
map_ Map

The map that the area belongs to.

required

Returns:

Type Description
Area

An area labeled with Lanelet 2 tags.

load_bounds(xml_node, projector, origin)

This function loads the boundary of the map from the XML node. The coordinates will be projected.

Parameters:

Name Type Description Default
xml_node Element

The XML node of the boundary.

required
projector Proj

The projection rule of the map.

required
origin tuple

The origin of the GPS coordinates.

required

Returns:

Type Description
tuple

The boundary of the map expressed as (min_x, max_x, min_y, max_y).

load_bounds_no_proj(xml_node)

This function loads the boundary of the map from the XML node. The coordinates will not be projected.

Parameters:

Name Type Description Default
xml_node Element

The XML node of the boundary.

required

Returns:

Type Description
tuple

The boundary of the map expressed as (min_lon, max_lon, min_lat, max_lat).

load_nodes(xml_node, projector, origin)

This function loads the nodes from the XML node. The coordinates will be projected.

Parameters:

Name Type Description Default
xml_node Element

The XML node of the nodes.

required
projector Proj

The projection rule of the map.

required
origin tuple

The origin of the GPS coordinates.

required

Returns:

Type Description
Node

A node under the x-y coordinates.

load_nodes_no_proj(xml_node)

This function loads the nodes from the XML node. The coordinates will not be projected.

Parameters:

Name Type Description Default
xml_node Element

The XML node of the nodes.

required

Returns:

Type Description
Node

A node under the GPS coordinates.

load_relation(xml_node, map_)

This function loads an OSM road elements from the XML node.

Parameters:

Name Type Description Default
xml_node Element

The XML node of the road element.

required
map_ Map

The map that the road element belongs to.

required

Returns:

Type Description
Tuple[Area, RoadLine, Regulatory]

A road element.

load_roadline_lanelet2(xml_node, map_)

This function loads a Lanelet 2 roadline from the XML node.

Parameters:

Name Type Description Default
xml_node Element

The XML node of the roadline.

required
map_ Map

The map that the roadline belongs to.

required

Returns:

Type Description
RoadLine

A roadline labeled with Lanelet 2 tags.

load_way(xml_node, map_)

This function loads an OSM road elements from the XML node.

Parameters:

Name Type Description Default
xml_node Element

The XML node of the road element.

required
map_ Map

The map that the road element belongs to.

required

Returns:

Type Description
Tuple[Area, RoadLine]

A road element.

parse(xml_root, project_rule=None, gps_origin=None, configs=None)

This function parses the OpenStreetMap format map.

Parameters:

Name Type Description Default
xml_root Element

The root of the XML tree.

required
project_rule dict

The projection rule of the map.

None
gps_origin tuple

The origin of the GPS coordinates.

None
configs dict

The configurations of the map.

None

XODRParser

This class implements a parser for the OpenDRIVE format map.

The general structure of the OpenDRIVE map is as follows:

/ header
    // geoReference
/ road []
    // link
    // type
        /// speed
    // planView
        /// geometry []
    // elevationProfile
    // lateralProfile
    // lanes
        /// laneOffset
        /// laneSection
    // objects
    // signals
        /// signal []
    // surface
/ controller
    // control []
/ junction
    // connection []

load_header(xml_node)

This function loads the header of the OpenDRIVE map.

Parameters:

Name Type Description Default
xml_node Element

The XML node of the header.

required

parse(xml_root)

This function parses the OpenDRIVE format map. To ensure that all road elements have an unique id, the function automatically reassign the id of the road elements.

Parameters:

Name Type Description Default
xml_root Element

The root of the XML tree.

required

Returns:

Name Type Description
map_ Map

The parsed map.