Lanelet2: high-definition map handling for automated driving

A map library, not a coordinate list

Lanelet2 is a C++ library for handling map data in the context of automated driving, designed to use high-definition map data in order to efficiently handle the challenges posed to a vehicle in complex traffic scenarios. The last phrase of that sentence is the whole reason the library exists. A vehicle in a city does not just need to know where the road is, it needs to know which lane it is in, where the lane can lead, who is allowed to use which connection, and what the rules are, and treating all of that as points and polylines makes every one of those questions an application problem. The project frames flexibility and extensibility as core principles, given that the challenges of future maps are not yet known, and it is the successor of the older liblanelet developed in 2013, with a compatibility document for people who know Lanelet1. The feature list is dense but readable: 2D and 3D support, lane changes, routing through areas, and a set of convenience functions for common map tasks. It is BSD 3-Clause licensed and it supports ROS1, ROS2, Docker and Conan.

Consistent modification is the guarantee that matters

One item on the feature list deserves more attention than the others, and it is the consistent modification. If one point is modified, all owning objects see the change. That sounds like a small promise until you consider what a map model actually looks like. A single point in a high-definition map is not a point, it is a corner shared by a lane boundary, a regulatory element, a traffic light, a stop line and possibly a polygon. If a library lets those objects hold independent copies of that point, then a change to a curb has to be applied in five places, and the fifth one is where the bug lives. The lanelet model is designed to prevent that, and the primitives documentation in the package explains the basic primitives that make up a map, with a separate primer on the software architecture and another on the geometry calculations you can perform on them. The consistency guarantee is the reason to use a map library at all rather than your own struct with a few vectors, and it is the reason an edit to a shared point in a map editor is safe.

Routing that knows the difference between a pedestrian and a car

Lanelet2 supports separated routing for pedestrians, vehicles, bikes and so on, and the separation is not a flag on a single router. It is a property of the map data, because a map encodes a footpath, a bike lane and a motorway lane as different primitives with different regulatory elements attached, and a router that ignores those attributes will happily send a bicycle down a motorway. The library also supports lane changes and routing through areas, the awkward cases where the answer to a question is a region rather than a line, which is where naive graph routing falls apart. Extensibility comes in the same area. There are many customization points to add new traffic rules, routing costs and parsers, which is how a project with its own regulatory model extends the library without forking it, and the traffic rules package is a separate directory for the same reason. If you are working outside the automotive world and your map has a different notion of who may go where, those customization points are the API you are meant to use.

Projection: the step everybody gets wrong

One feature line in the readme deserves to be called out on its own, accurate projection between the lat and lon geographic world and local metric coordinates. It sounds mundane, and it is the single most common source of silent errors in map code. A vehicle perceives metres, acceleration is metres per second squared, and a heading is a bearing, while the map is stored in degrees, and a degree of longitude is a different distance in metres depending on where you are on the globe. Doing that conversion approximately is fine for plotting and wrong for anything a controller closes a loop on. Lanelet2 handles it as a first class concern, with a projection package, a dependency on geographiclib, and its own documentation page on map projections and coordinate systems, and the geometry primer covers the calculations the primitives support. Boost Geometry is in the dependency list for the same reason, since the geometric operations involved, offsets, intersections, polygons, are not things to write from scratch.

Four install routes, and one version trap

Inside ROS the install is one apt command, because Lanelet2 has been released for ROS and you install the package for your distribution:

sudo apt install ros-noetic-lanelet2

Outside ROS the library is on PyPI:

pip install lanelet2

And that route has a trap the readme documents at length, because only Python 3.8 to 3.11 Linux builds are available, and Python 3.10 or newer is only supported for recent distributions such as Ubuntu 20.04 and later. If pip cannot find a version at all, the diagnosis is usually an old pip rather than a missing package, and the fix is:

pip3 install -U pip

Docker is the third route and the one that gets you moving fastest:

docker build -t lanelet2 .
docker run -it --rm lanelet2:latest /bin/bash
python -c "import lanelet2"

The image contains a link to your local lanelet2, so you can work and see changes almost at the same time, and the suggested pattern is two screens, one local and one in the container, making your code changes locally and then running catkin build in the container to recompile. The manual route is the fourth, and it is the one to read if you want to build it in your own way, because the build relies mainly on Catkin and is targeted towards Linux, with at least C++14 required.

Dependencies and the packages behind them

The dependency list is short and each entry maps to a package in the tree. Besides Catkin you need Boost from version 1.58, eigen3, the mrt_cmake_modules CMake helper library, pugixml for the IO package, boost-python with python2 or python3 for the Python package, geographiclib for the projection package and rosbash for the examples. On Ubuntu the readme gives the apt line:

sudo apt-get install libboost-dev libeigen3-dev libgeographic-dev libpugixml-dev libpython-dev libboost-python-dev python-catkin-tools

with a note that on Ubuntu 24.04 and later you install libgeographiclib-dev instead of libgeographic-dev, which is the kind of detail that costs an afternoon when it is missing. The repository layout mirrors the feature list, with a core package, separate packages for IO, matching, projection, Python bindings, routing, traffic rules, validation, examples and maps, plus a top level package that ties them together. There is a conanfile.py for Conan users, a Dockerfile, mkdocs.yml and rosdoc.yaml for documentation, a .clang-format and .clang-tidy for the C++ side, and a CODEOWNERS file.

Where the project stands

The release history is 1.2.1 in May 2023, 1.2.2 in October 2024 and 1.2.3 in June 2026, and the last push was on 2026-10-10, so the work is current even though the versioning has moved slowly over the last three years. The build badges tell you more about the support matrix than the release notes do, because they cover ROS on Ubuntu focal, ROS2 on focal with foxy and ROS2 on jammy with humble, and there is a separate continuous delivery workflow alongside the ordinary CI. That spread of badges is the strongest evidence in the readme, because it means the library is compiled against several combinations of operating system, ROS distribution and Python version on every change. The limitation that follows from all of this is plain. The project is targeted at Linux, the PyPI wheels cover a narrow Python window, and the build system assumes Catkin or a manual CMake path, so a team on Windows or on a modern macOS is going to do more work than the documentation suggests. The documentation itself is thorough for a research library, with a primitives primer, an architecture primer, a geometry primer, a projection reference and a map creation guide, plus a published site built with mkdocs.

Editorial conclusion

Lanelet2 is the right choice if you are building anything that has to reason about a road network as a map rather than as a list of coordinates, because the primitive model and the consistent modification guarantee are the parts that are painful to build yourself. It is the wrong choice if you need a Windows or macOS build, since the project is targeted towards Linux, and it is the wrong choice if your data pipeline only produces OpenStreetMap tiles, since the read and write interface covers data formats such as OSM without meaning that it can process OSM maps. Before you start, pick your install route, and if you take the PyPI route check the Python version window, because only 3.8 to 3.11 builds exist.

Frequently asked questions

Official sources

1. fzi-forschungszentrum-informatik/Lanelet2 on GitHub
2. Issues
3. License: BSD-3-Clause
4. README
5. Releases