DOCSEARCHbyAlgolia
Submit Docs

Lanelet2 Documentation

repository·master·Indexed 21 days ago

https://github.com/fzi-forschungszentrum-informatik/lanelet2

A C++ library for handling high-definition (HD) map data in automated driving contexts. It supports 2D/3D data, consistent object modification, and complex routing. The library includes modules for core primitives and geometry, IO support for OSM and binary formats, coordinate projections (UTM, Mercator, Geocentric, LocalCartesian), and a matching module for deterministic and probabilistic object-to-lanelet localization. It provides C++ and Python APIs, as well as JOSM styles and presets for map editing.

Tokens
22.5K
Snippets
45
Records
96
Agent score
76%

What's inside Lanelet2

  1. Overview of Lanelet2 packages

    master

    Lanelet2 is composed of several specialized packages:

    • lanelet2: The meta-package for the entire framework.
    • lanelet2_core: Basic library containing primitives, geometry calculations, and the LaneletMap object.
    • lanelet2_io: Reading and writing lanelet maps.
    • lanelet2_traffic_rules: Interpreting traffic rules encoded in maps.
    • lanelet2_projection: Projecting maps from WGS84 (lat/lon) to local metric coordinates.
    • lanelet2_routing: Routing graph implementation, reachable set queries, and collision checking.
    • lanelet2_maps: Example maps and tools for JOSM visualization/modification.
    • lanelet2_matching: Determining which lanelet an object is currently located in.
    • lanelet2_python: Python interface for Lanelet2.
    • lanelet2_validation: Map validation checks.
    • lanelet2_examples: Tutorials for C++ and Python.

  2. Supported Lanelet2 IO formats

    master

    The Lanelet2 IO module provides reader and writer functions for different map formats. The specific format used is automatically determined by the file extension of the provided filename. If a parser or writer is registered for that extension, it will be selected automatically.

    Currently supported formats:

    • OSM (.osm): Loads/writes specialized lanelet maps from OpenStreetMap files.
    • Binary (.bin): Loads/writes the map using an internal binary format. This is highly efficient for reading and writing but is not human-readable.

  3. Core Lanelet2 components and their interactions

    master

    Understanding the relationship between the following core components is essential for using Lanelet2:

    ComponentDescription
    PrimitiveAny basic Lanelet2 object (e.g., Lanelet, LineString2d, ConstLanelet).
    LaneletMapThe primary storage container. It organizes primitives into layers and provides access via BoundingBox, ID, or nearest point. It does not handle routing.
    TrafficRulesAn object that interprets the map from the perspective of a specific road participant (e.g., a vehicle vs. a pedestrian). It determines properties like isPassable or valid lane changes.
    RoutingCostClasses used by the routing graph to assign costs (e.g., distance, time, or lane change penalties) to movements between Lanelets.
    RoutingGraphBuilt from a LaneletMap, TrafficRules, and RoutingCost. It is specific to one participant type and is used to query valid paths.
    RouteThe result of a routing query. It contains the sequence of Lanelets and lane changes required to travel from A to B with the lowest cost.
    LaneletPath / PathA sequence of adjacent Lanelets (including those connected by lane changes) returned by the RoutingGraph.
    LaneletSequenceA special case of a LaneletPath where no lane changes are required to follow the sequence.
    ProjectorUsed by the IO module to convert between WGS84 (lat/lon) coordinates and the local coordinate system used by Lanelet2. UTM is recommended if unsure which projection to use.

  4. Explore Lanelet2 Core primitives and geometry

    master

    The lanelet2_core package provides the fundamental building blocks for Lanelet2 maps. It includes:

    • Basic Primitives: Core map elements including LaneletMap and other fundamental lanelet objects.
    • Geometry Functions: A suite of functions for geometric operations required for map processing.

    For practical implementation details, refer to the lanelet2_examples package in the repository.

  5. Structure of Regulatory Elements in Lanelet2

    master

    Regulatory Elements are used to model traffic restrictions on lanelets and areas. Every Regulatory Element must have the tag type=regulatory_element. If this tag is missing, Lanelet2 will automatically add it when writing to an .osm file.

    Subtypes

    The subtype tag distinguishes the specific type of regulation. Common subtypes include:

    • traffic_sign
    • traffic_light
    • speed_limit
    • right_of_way
    • all_way_stop

    Optional Tags

    • dynamic (yes or no): Indicates if the element changes based on conditions (e.g., road closures on weekends). By default, Lanelet2 ignores dynamic elements.
    • fallback (yes or no): Indicates if the element has lower priority than another (e.g., right-of-way rules that apply only when traffic lights fail).

  6. Define Lanelets for atomic lane sections

    master

    A Lanelet represents an atomic section of a lane where traffic rules and lane changes remain constant.

    Structure and Requirements:

    • Bounds: Consists of exactly one left and one right Linestring. Both Linestrings must point in the same direction.
    • Centerline: An optional centerline can be provided to guide vehicles. It must stay within the bounds and not touch them. If not provided, the library calculates it automatically.
    • Directionality: Lanelets are one-directional by default. They must be explicitly tagged as bidirectional to be treated as such.
    • Adjacency: Adjacent Lanelets must share the same endpoints. Lanelets that are reachable via a lane change must share a border.
    • Rules and Participants: A Lanelet must allow for the determination of:
      • Speed limits: Either via a SpeedLimit regulatory element or by tagging the Lanelet's location.
      • Participants: Which types of vehicles/users can use the lane.
    • Regulatory Elements: Lanelets can reference regulatory elements to apply specific traffic rules.

  7. How the Lanelet2 routing components work together

    master

    To create a functional routing graph, three main components must interact:

    1. Lanelet Map: The base map containing Lanelets, Areas, and Regulatory Elements (from lanelet2_core).
    2. Traffic Rules: Defines which lanelets/areas are passable for a specific participant (e.g., Participants::Vehicle vs Participants::Bicycle). This determines the possible paths.
    3. Routing Cost Modules: Determines the cost of traveling along a lanelet/area (e.g., distance or travel time). You can plug in custom cost calculations. This influences the preferred path.

    Key Relations in the Graph: Lanelets in a routing graph can have several relations:

    • left, right: Reachable via lane change.
    • adjacent left, adjacent right: Neighbors that are not reachable via lane change.
    • succeeding: Relation between two subsequent lanelets.
    • conflicting: Intersecting lanelets/areas.
    • area: Reachable area to lanelet/area relation.

  9. How geometry calculations work with boost::geometry

    master

    Lanelet2 objects are compatible with boost::geometry, allowing for direct geometric queries. For example, you can calculate the distance between two points using:

    double d = boost::geometry::distance(laneletPoint1, laneletPoint2);

    Behavior:

    • If both points are 2D, the calculation is performed in 2D.
    • If either point is 3D, the calculation is performed in 3D.

    ⚠️ Known Limitation: There is a known compatibility issue between Lanelet2's ConstCorrectness and boost::geometry's template system. Using different point types in const vs. non-const contexts can cause complex compiler errors. Refer to the Geometry Primer in the repository for specific workarounds.

  10. Area OSM Structure

    master

    Areas are represented as OSM relations using the multipolygon representation with the tag type=multipolygon.

    • Outer Bounds: An ordered list of relation members with the role outer.
    • Inner Bounds: An ordered list of relation members with the role inner.

    Parsing Logic: Lanelet2 parses inner bounds in the provided order and starts a new hole whenever the last point of one linestring matches the first point of the next.

  11. Key differences between Lanelet1 and Lanelet2

    master

    When migrating from Lanelet1 to Lanelet2, be aware of these fundamental changes in map specification and implementation:

    Map Specification Changes

    • Redesigned Features: Traffic light handling, parking places, and event regions have been replaced.
    • Lanelet Borders: Borders now have semantic meaning and are used to infer lane change maneuvers.
    • Representation vs. Interpretation: Lanelet2 distinguishes between the map representation and how it is interpreted based on the road user.
    • Lanelet Constraints: Lanelets are restricted to exactly one single left bound and one single right bound to support lane change features.
    • New Area Type: A dedicated Area type is used for undirected traffic (e.g., parking lots, pedestrian walkways).

    Implementation Changes

    • Coordinate System: Lanelet2 converts geographic coordinates to a local metric coordinate system upon loading, improving performance and enabling complex projections.
    • Renamed Types: LineStrip is now LineString.
    • Modular Architecture: The monolithic LaneletMap is split. The new LaneletMap holds primitives, while the RoutingGraph holds the topology.
    • Primitive Identity: Primitives (points, linestrings, lanelets) have unique identities and are shared. Modifying a shared point in one linestring will modify it in all other linestrings referencing that point.
    • 3D Support: Primitives support 3D calculations and can be inverted or converted between 2D and 3D without data copying.
    • Safety: Maps can be safely modified, copied, and saved.

  12. Choosing the correct primitive type for Boost.Geometry

    master

    Lanelet2 provides three flavors of every geometric primitive (2D and 3D). Choosing the right one is critical for compatibility with Boost.Geometry algorithms and avoiding compiler errors.

    TypeExampleUse for Boost.GeometryDescription
    MutableLineString2dOnly for mutating algorithms (use with care)Returns mutable members. Can cause issues if Boost incorrectly treats them as const or if Boost attempts to modify data unexpectedly.
    ConstConstLineString2dNoImmutable. Often causes long compiler errors because some Boost algorithms attempt to instantiate templates that require mutability.
    HybridConstHybridLineString2dYes (Recommended)Immutable, but returns non-lanelet objects (e.g., BasicPoint2d). This is the most compatible and safest option for almost all calculations.

    Decision Rule: If in doubt, use the Hybrid version. Note that Hybrid versions are immutable, so you cannot use them with algorithms that mutate the primitive (like correct).