Georeferencing

Georeferencing trajectories and metric maps is implemented in the mola_state_estimation package.

The concept of using simple-maps as intermediary map format together with the layered metric map format (see [BC25]) enables embedding georeferenced coordinates to any kind of map typically used in robotics: grid maps, voxel maps, point clouds, etc.

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:

The existing frames are explained here.

2. Geo-referencing related applications

2.1. mola-sm-georeferencing: optimal geo-referencing

This program finds the optimal geo-referencing parameters for a map.

First, build a simple-map from a dataset or a live robot as described in Tutorial: build a map. Make sure of having a GPS (GNSS) sensor source emitting observations, and that they were captured by MOLA-LO (see the corresponding variable in the LO pipeline).

Then, build the corresponding metric map by applying a metric map generation pipeline (see [BC25]) or this step in the tutorial:

# Build metric map (mm) from simplemap (sm):
sm2mm -i datasetWithGPS.simplemap -o myMap.mm -p sm2mm_pipeline.yaml

Now, to find out the optimized map-to-ENU transformation and write it into the 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:

# georeference it:
mola-sm-georeferencing -i datasetWithGPS.simplemap --output myMap.georef

Full CLI reference

USAGE:

   mola-sm-georeferencing  [-v <INFO>] [--no-imu-gravity] [-l <foobar.so>]
                           [--imu-gravity-sigma-deg <3.0>]
                           [--horizontality-sigma <1.0>] [-o <map.georef>]
                           [--write-into <map.mm>] -i <map.simplemap> [--]
                           [--version] [-h]


Where:

   -v <INFO>,  --verbosity <INFO>
   Verbosity level: ERROR|WARN|INFO|DEBUG (Default: INFO)

   --no-imu-gravity
   Disable using IMU acceleration data for gravity alignment (enabled by
   default).

   -l <foobar.so>,  --load-plugins <foobar.so>
   One or more (comma separated) *.so files to load as plugins, e.g.
   defining new CMetricMap classes

   --imu-gravity-sigma-deg <3.0>
   IMU gravity alignment uncertainty (degrees).

   --horizontality-sigma <1.0>
   For short trajectories (not >10x the GPS uncertainty), this helps to
   avoid degeneracy.

   -o <map.georef>,  --output <map.georef>
   Write the obtained georeferencing metadata to a .georef file

   --write-into <map.mm>
   An existing .mm file in which to write the georeferencing metadata

   -i <map.simplemap>,  --input <map.simplemap>
   (required)  Input .simplemap file

   --,  --ignore_rest
   Ignores the rest of the labeled arguments following this flag.

   --version
   Displays version information and exits.

   -h,  --help
   Displays usage information and exits.

2.2. mola-trajectory-georef: 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, and after georeferencing the generated map as shown above, you can use the CLI tool mola-trajectory-georef to convert it into geodetic coordinates, for example in KML format suitable for visualization in Google Earth.

Full CLI reference

USAGE:

   mola-trajectory-georef  -o <path.kml> -t <traj.tum> [-g <map.georef>]
                           [-m <map.mm>] [--] [--version] [-h]


Where:

   -o <path.kml>,  --output <path.kml>
   (required)  The name of the google earth kml file to write to

   -t <traj.tum>,  --trajectory <traj.tum>
   (required)  Input .tum trajectory, in map local coordinates

   -g <map.georef>,  --geo-ref <map.georef>
   Input .georef file with georef info

   -m <map.mm>,  --map <map.mm>
   Input .mm map with georef info

   --,  --ignore_rest
   Ignores the rest of the labeled arguments following this flag.

   --version
   Displays version information and exits.

   -h,  --help
   Displays usage information and exits.

2.3. mola-mm-add-geodetic: add geodetic coordinates to point clouds

Once you have a georeferenced metric map (*.mm file), you can use the CLI tool mola-mm-add-geodetic to enrich point cloud layers with geodetic coordinates (latitude, longitude, altitude in WGS84). This adds three new double-precision fields to each point in CGenericPointsMap-based layers, enabling direct use of geographic coordinates in subsequent analysis or export to GIS applications.

The tool automatically handles the coordinate transformation from the map’s local frame to geodetic coordinates using either embedded georeferencing metadata or an external georeferencing file.

The output metric map will contain the same structure as the input, but point cloud layers (CGenericPointsMap-based) will have three additional double-precision fields:

• latitude: WGS84 latitude in decimal degrees

• longitude: WGS84 longitude in decimal degrees

• altitude: WGS84 ellipsoidal height in meters

These fields can then be exported to text or PLY format using mm2txt or mm2ply respectively, with the --export-fields option to include the geodetic coordinates.

For example, to export only coordinates and geodetic information:

mm2txt output.mm --export-fields "x,y,z,latitude,longitude,altitude"

Full CLI reference

USAGE:

   mola-mm-add-geodetic  -i <input.mm> -o <output.mm> [-g <map.georef>]
                         [-l <layerName>] ... [-p <foobar.so>] [-v] [--]
                         [--version] [-h]


Where:

   -i <input.mm>,  --input <input.mm>
   (required)  Input metric map file (*.mm)

   -o <output.mm>,  --output <output.mm>
   (required)  Output metric map file (*.mm) with geodetic coordinates
   added

   -g <map.georef>,  --georef <map.georef>
   Optional geo-referencing file (*.georef or *.yaml) to use if the
   input map does not have embedded georeferencing information

   -l <layerName>,  --layer <layerName>  (accepted multiple times)
   Layer(s) to process. If not provided, all CGenericPointsMap layers
   will be processed. This argument can appear multiple times.

   -p <foobar.so>,  --load-plugins <foobar.so>
   One or more (comma separated) *.so files to load as plugins

   -v,  --verbose
   Enable verbose output with progress information

   --,  --ignore_rest
   Ignores the rest of the labeled arguments following this flag.

   --version
   Displays version information and exits.

   -h,  --help
   Displays usage information and exits.

Examples

Basic usage with embedded georeferencing:

mola-mm-add-geodetic -i input.mm -o output.mm

Using an external georeferencing file:

mola-mm-add-geodetic -i input.mm -o output.mm -g map.georef

Process specific layers only:

mola-mm-add-geodetic -i input.mm -o output.mm -l raw -l filtered

Verbose mode for large datasets:

mola-mm-add-geodetic -i input.mm -o output.mm -v

3. Georeferenced maps in mm-viewer

Write me!

4. View GPS readings on a georeferenced map

Once you have published a georeferenced map (via mrpt_map_server or directly from mola_lidar_odometry), you can visualize in RViz or FoxGlove the localization from the GNSS sensor and its covariance uncertainty by installing mola_gnss_to_markers and then:

ros2 launch mola_gnss_to_markers mola_gnss_to_markers_launch.py