From 24e0e5d364d04b062d9b8250bc1ec95d1175f8fd Mon Sep 17 00:00:00 2001 From: Jose Luis Blanco-Claraco Date: Fri, 13 Sep 2024 12:05:00 +0200 Subject: [PATCH] docs: explain the UTM and ENU frames --- docs/source/geo-referencing.rst | 77 ++++++++++++++++++++++++++++----- 1 file changed, 66 insertions(+), 11 deletions(-) diff --git a/docs/source/geo-referencing.rst b/docs/source/geo-referencing.rst index b7ddc6e..b8c0df2 100644 --- a/docs/source/geo-referencing.rst +++ b/docs/source/geo-referencing.rst @@ -8,10 +8,12 @@ Georeferencing trajectories and metric maps is implemented in the :ref:`mola_sm_ The concept of using simple-maps as intermediary map format together with the layered metric map format (see :cite:`blanco2024mola_lo`) enables embedding georeferenced coordinates to any kind of map typically used in robotics: grid maps, voxel maps, point clouds, etc. -.. image:: https://mrpt.github.io/imgs/kaist01_georef_sample.png - | +.. image:: https://mrpt.github.io/imgs/kaist01_georef_sample.png + :width: 250 + :align: right + .. contents:: Table of Contents :depth: 1 :local: @@ -19,7 +21,38 @@ enables embedding georeferenced coordinates to any kind of map typically used in | -1. How to build a georeferenced map +1. Frames for geo-referenced maps +-------------------------------------------- +When working with ROS ``tf`` (transformations), MOLA packages use the following frame convention, +which extends the standard `REP-105 `_ with additional +``enu`` and ``utm`` frames: + +.. figure:: https://mrpt.github.io/imgs/mola_mrpt_ros_geo_referenced_utm_frames.png + :width: 500 + :align: center + +These are the existing frames: + +- ``base_link``: The robot reference frame. For ground vehicles, normally placed at the + center of the rear axle. +- ``odom``: The arbitrary origin for odometry measurements. +- ``map``: The origin of the reference metric map used for localization. +- ``enu``: For geo-referenced maps, the North (``y`` axis), East (``x`` axis), Up (``z`` axis) frame for which + we have reference geodetic coordinates (latitude and longitude). Different maps built in the same zone + will surely have different ``enu`` frames, since it is defined by collected GNSS measurements. +- ``utm``: The origin of the `UTM zone `_ + in which ``enu`` falls. Unlike ``enu``, it is **independent** of the trajectory followed while building the map. + +And this is who is responsible of publishing each transformation: + +- ``odom → base_link``: Odometry module. High-frequency, accurate in the short term, but drifts in the long term. +- ``map → odom``: :ref:`Localization ` module, which corrects the odometry drift. +- ``enu → {map, utm}``: Published by ``mrpt_map_server`` (`github `_), + if fed with a geo-referenced metric map (``.mm``) file. + +| + +2. How to build a georeferenced map -------------------------------------------- First, build a simple-map from a dataset or a live robot as described in :ref:`building-maps`. Make sure of having a GPS (GNSS) sensor source emitting observations, and that they were captured @@ -41,6 +74,15 @@ map file, use: # georeference it: mola-sm-georeferencing -i datasetWithGPS.simplemap --write-into myMap.mm +Alternatively, the georeferenciation metadata can be also stored, independently of a metric map, +in an independent file with: + +.. code-block:: bash + + # georeference it: + mola-sm-georeferencing -i datasetWithGPS.simplemap --output myMap.georef + + .. dropdown:: Full CLI reference :icon: code-review @@ -49,9 +91,10 @@ map file, use: USAGE: - mola-sm-georeferencing [-v ] [-l ] [--write-into - ] -i [--] - [--version] [-h] + mola-sm-georeferencing [-v ] [-l ] + [--horizontality-sigma <1.0>] [-o ] + [--write-into ] -i [--] + [--version] [-h] Where: @@ -63,6 +106,13 @@ map file, use: One or more (comma separated) *.so files to load as plugins, e.g. defining new CMetricMap classes + --horizontality-sigma <1.0> + For short trajectories (not >10x the GPS uncertainty), this helps to + avoid degeneracy. + + -o , --output + Write the obtained georeferencing metadata to a .georef file + --write-into An existing .mm file in which to write the georeferencing metadata @@ -78,9 +128,10 @@ map file, use: -h, --help Displays usage information and exits. + | -2. Georeferenced trajectories +3. Georeferenced trajectories -------------------------------------- Once you already have a **trajectory** file in the **local map frame of reference**, for example, as generated by MOLA-LO in TUM format, @@ -95,8 +146,9 @@ for example in KML format suitable for visualization in Google Earth. USAGE: - mola-trajectory-georef -o -t -m [--] - [--version] [-h] + mola-trajectory-georef -o -t [-g ] + [-m ] [--] [--version] [-h] + Where: @@ -106,8 +158,11 @@ for example in KML format suitable for visualization in Google Earth. -t , --trajectory (required) Input .tum trajectory, in map local coordinates + -g , --geo-ref + Input .georef file with georef info + -m , --map - (required) Input .mm map with georef info + Input .mm map with georef info --, --ignore_rest Ignores the rest of the labeled arguments following this flag. @@ -121,7 +176,7 @@ for example in KML format suitable for visualization in Google Earth. | -3. Georeferenced maps in mm-viewer +4. Georeferenced maps in mm-viewer ---------------------------------------- Write me!