document GPS sensors

MRPT · Dec 4, 2024 · 4ceb3ee · 4ceb3ee
1 parent 18ab3df
commit 4ceb3ee
Show file tree

Hide file tree

Showing 3 changed files with 63 additions and 0 deletions.
diff --git a/docs/sensors.rst b/docs/sensors.rst
@@ -57,6 +57,9 @@ respectively.
 Each sensor ``class`` has its own additional parameters, listed in the next sections.
 
 
+3D LiDARs
+-----------------------------------------
+
 HELIOS 32 (26 deg FOV)
 ##########################
 
@@ -343,3 +346,31 @@ Depth (RGBD) camera
 
    .. literalinclude:: ../definitions/rgbd_camera.sensor.xml
       :language: xml
+
+
+GNSS sensor ("GPS")
+---------------------
+A "GPS sensor" can be attached to a robot with the code shown below. 
+For it to work, the ``world`` XML needs to have a :ref:`georeference tag <world-georeference>`.
+
+.. dropdown:: To use in your robot, copy and paste this inside a ``<vehicle>`` or ``<vehicle:class>`` tag.
+   :open:
+
+   .. code-block:: xml
+
+		<include file="../definitions/gnss.sensor.xml"
+		  sensor_x="0.0"  sensor_y="0.0" sensor_z="0.50"
+		  sensor_period_sec="1.0"
+		  sensor_name="gps"
+		  sensor_horizontal_std_noise="1.5"
+		  sensor_vertical_std_noise="2.5"
+		  />
+
+.. dropdown:: All parameters available in gnss.sensor.xml
+
+   File: `mvsim_tutorial/definitions/gnss.sensor.xml <https://github.com/MRPT/mvsim/blob/develop/definitions/gnss.sensor.xml>`_
+
+   .. literalinclude:: ../definitions/gnss.sensor.xml
+      :language: xml
+
+
diff --git a/docs/world.rst b/docs/world.rst
@@ -39,6 +39,7 @@ First, we have global definitions on the simulation itself, the GUI, and the lig
 
    world_global
    world_gui
+   world_georeference
    world_lighting
 
 World contents

diff --git a/docs/world_georeference.rst b/docs/world_georeference.rst
@@ -0,0 +1,31 @@
+.. _world-georeference:
+
+Georeference options
+--------------------------------------------
+
+For GNSS ("GPS") sensors to work, they need to know the transformation between
+the simulator world local coordinates and the Earth.
+This can be specified with a ``<georeference>`` tag as documented below.
+
+
+.. code-block:: xml
+   :caption: Georeference example (Using geodetic coordinates)
+
+    <mvsim_world version="1.0">
+    ...
+      <!-- Define georeferenced coordinates to the world so GNSS/GPS sensors can be properly simulated -->
+      <georeference>
+        <latitude>36.894718</latitude>
+        <longitude>-2.316988</longitude>
+        <height>100.0</height>
+        <world_to_enu_rotation_deg>0.0</world_to_enu_rotation_deg>
+      </georeference>
+    ...
+    </mvsim_world>
+
+
+- ``<latitude>yy</latitude>`` and ``<longitude>xx</longitude>``. Geodetic coordinates of the world (0,0,0) origin.
+
+- ``<height>zz</height>``: The height over the WGS84 ellipsoid for the world (0,0,0).
+
+- ``<world_to_enu_rotation_deg>tt</world_to_enu_rotation_deg>``: An optional rotation (in degrees) if you want North not to be aligned with +Y as it is the default.