From ffd96b731de65172078f99b1417eaa92ac7815dc Mon Sep 17 00:00:00 2001 From: Antoine Beyeler <49431240+abey79@users.noreply.github.com> Date: Wed, 13 Nov 2024 09:54:57 +0100 Subject: [PATCH] Add an how-to guide for the map view (#8075) ### What How-to guide for the map view. Spirit: - information dense (no super-basic tutorial material) - easy to maintain (no snippets/screenshots) ### Checklist * [x] I have read and agree to [Contributor Guide](https://github.com/rerun-io/rerun/blob/main/CONTRIBUTING.md) and the [Code of Conduct](https://github.com/rerun-io/rerun/blob/main/CODE_OF_CONDUCT.md) * [x] I've included a screenshot or gif (if applicable) * [x] I have tested the web demo (if applicable): * Using examples from latest `main` build: [rerun.io/viewer](https://rerun.io/viewer/pr/8075?manifest_url=https://app.rerun.io/version/main/examples_manifest.json) * Using full set of examples from `nightly` build: [rerun.io/viewer](https://rerun.io/viewer/pr/8075?manifest_url=https://app.rerun.io/version/nightly/examples_manifest.json) * [x] The PR title and labels are set such as to maximize their usefulness for the next release's CHANGELOG * [x] If applicable, add a new check to the [release checklist](https://github.com/rerun-io/rerun/blob/main/tests/python/release_checklist)! * [x] If have noted any breaking changes to the log API in `CHANGELOG.md` and the migration guide - [PR Build Summary](https://build.rerun.io/pr/8075) - [Recent benchmark results](https://build.rerun.io/graphs/crates.html) - [Wasm size tracking](https://build.rerun.io/graphs/sizes.html) To run all checks from `main`, comment on the PR with `@rerun-bot full-check`. --- .../howto/visualization/geospatial-data.md | 71 +++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 docs/content/howto/visualization/geospatial-data.md diff --git a/docs/content/howto/visualization/geospatial-data.md b/docs/content/howto/visualization/geospatial-data.md new file mode 100644 index 000000000000..851a62cd01b8 --- /dev/null +++ b/docs/content/howto/visualization/geospatial-data.md @@ -0,0 +1,71 @@ +--- +title: Visualize geospatial data +order: 300 +--- + +Rerun 0.20 introduced a new, experimental [map view](../../reference/types/views/map_view.md). +This guide provides a short overview on how to use it to visualise geospatial data. + +## Coordinate system + +The map view uses the [ESPG:3857](https://epsg.io/3857) [spherical mercator projection](https://en.wikipedia.org/wiki/Web_Mercator_projection) commonly used by web services such as [OpenStreetMap](https://www.openstreetmap.org/). +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 [ESPG:4326](https://epsg.io/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`](../../reference/types/archetypes/geo_points.md) represent a single geospatial location (or a batch thereof). The location of the Eiffel Tower can be logged as follows: + +```python +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](https://stackoverflow.com/questions/7309121/preferred-order-of-writing-latitude-longitude-tuples-in-gis-services), 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`](../../reference/types/archetypes/geo_points.md): batch of individual points, with optional [radius](../../reference/types/components/radius.md) and [color](../../reference/types/components/color.md) +- [`GeoLineStrings`](../../reference/types/archetypes/geo_line_strings.md): batch of line strings, with optional [radius](../../reference/types/components/radius.md) and [color](../../reference/types/components/color.md) + +*Note*: polygons are planned but are not supported yet (see [this issue](https://github.com/rerun-io/rerun/issues/8066)). + +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 are scene units. + +Apart from the use of latitude and longitude, `GeoPoints` and `GeoLineStrings` are otherwise similar to the [`Points2D`](../../reference/types/archetypes/points2d.md) and [`LineStrip2D`](../../reference/types/archetypes/line_strips2d.md) archetypes used in the [2D view](../../reference/types/views/spatial2d_view.md). + + +## Using Mapbox background maps + +The map view supports several types of background maps, including a few from [Mapbox](https://www.mapbox.com). +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](https://rerun.io/docs/howto/configure-viewer-through-code): + +```python +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/types/views/map_view.md) reference for details.