Skip to content

Commit

Permalink
Add an how-to guide for the map view (#8075)
Browse files Browse the repository at this point in the history
### 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`.
  • Loading branch information
abey79 authored Nov 13, 2024
1 parent 81ccf44 commit ffd96b7
Showing 1 changed file with 71 additions and 0 deletions.
71 changes: 71 additions & 0 deletions docs/content/howto/visualization/geospatial-data.md
Original file line number Diff line number Diff line change
@@ -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 <!-- NOLINT -->

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.

0 comments on commit ffd96b7

Please sign in to comment.