Visualize geospatial data

The map view shows geospatial data (GPS coordinates) on top of a background map. This guide provides a short overview on how to use it.

Coordinate system

The map view uses the EPSG:3857 spherical mercator projection commonly used by web services such as OpenStreetMap. This enables the use of commonly available web tiles for the background map.

To be compatible with this view, geospatial data must be expressed using EPSG:4326 (aka WGS84) latitudes and longitudes. This corresponds to what is commonly referred to as "GPS coordinates." Rerun provides a set of archetypes prefixed with Geo designed to encapsulate such data.

For example, GeoPoints represent a single geospatial location (or a batch thereof). The location of the Eiffel Tower can be logged as follows:

rr.log("eiffel_tower", rr.GeoPoints(lat_lon=[48.858222, 2.2945]))

Both the latitude and longitude must be provided in degrees, with positive values corresponding to the North, resp. East directions.

Note that Rerun always expects latitudes first and longitudes second. As there is no accepted ordering standard, our APIs strive to make this ordering choice as explicit as possible. In this case, the lat_lon argument is keyword-only and must thus be explicitly named as a reminder of this order.

Types of geometries

Rerun currently supports two types of geometries:

• GeoPoints: batch of individual points, with optional radius and color
• GeoLineStrings: batch of line strings, with optional radius and color

As in other views, radii may be expressed either as UI points (negative values) or scene units (positive values). For the latter case, the map view uses meters as scene units.

Apart from the use of latitude and longitude, GeoPoints and GeoLineStrings are otherwise similar to the Points2D and LineStrips2D archetypes used in the 2D view.

Using Mapbox background maps

The map view supports several types of background maps, including a few from Mapbox. A Mapbox access token is required to use them. It must be provided either using the RERUN_MAPBOX_ACCESS_TOKEN environment variable or configured in the settings screen ("Settings…" item in the Rerun menu). An access token may be freely obtained by creating a Mapbox account.

Creating a map view from code

Like other views, the map view can be configured using the blueprint API:

import rerun.blueprint as rrb

blueprint = rrb.Blueprint(
    rrb.MapView(
        origin="/robot/position",
        name="map view",
        zoom=16.0,
        background=rrb.MapProvider.OpenStreetMap,
    ),
)

Check the map view reference for details.

Limitations

• No heading or orientation. GeoPoints are drawn as circles, without a direction. As a workaround, log a short GeoLineStrings segment from the position in the direction of the heading.
• No custom tile servers. The background map can only be one of the built-in providers: OpenStreetMap and four Mapbox styles (see rrb.MapProvider). You cannot set your own tile URL or use offline tiles.
• 2D only. The map view is a flat 2D map. There is no 3D terrain, and no altitude.
• No polygons yet, see above.

See missing features.