docs updates

doc/source/bibliography.bib

@@ -111,3 +111,11 @@ @article{neira2001data
   year={2001},
   publisher={IEEE}
 }
+
+@article{blanco2008ekf,
+  title={Derivation and implementation of a full 6d ekf-based solution to bearing-range slam},
+  author={Blanco, Jose-Luis},
+  journal={University of Malaga, Spain, Technical Report},
+  url={https://ingmec.ual.es/~jlblanco/papers/RangeBearingSLAM6D.pdf},
+  year={2008}
+}

doc/source/doxygen-docs/lib_mrpt_gui.md

@@ -23,8 +23,7 @@ optionally sets of points over them, etc.
  - mrpt::gui::CDisplayWindow3D: A powerful 3D rendering window capable of
 displaying a mrpt::opengl::COpenGLScene, or efficiently displaying 2D images
 using graphics card acceleration. It features mouse navigation, Alt+Enter
-fullscreen switching, multiple viewports, etc. See [this
-tutorial](https://www.mrpt.org/Tutorial_3D_Scenes).
+fullscreen switching, multiple viewports, etc. See \ref tutorial_3D_scenes.
    ![mrpt::gui::CDisplayWindow3D screenshot](_static/preview_CDisplayWindow3D.png)
 
  - mrpt::gui::CDisplayWindowPlots: Displays one or more 2D vectorial graphs,

doc/source/doxygen-docs/lib_mrpt_opengl.md

@@ -21,7 +21,7 @@ A good starting point to explore this library is the base class for all the
 A 3D scene is represented by an object of the type mrpt::opengl::COpenGLScene,
 which in turn can contain one or several "viewports" in such a way that the
 rendering area is divided into several spaces, each displaying the same or different
-objects. See the tutorial online: https://www.mrpt.org/Tutorial_3D_Scenes
+objects. See the tutorial: \ref tutorial_3D_scenes
 
 See the full list of classes in mrpt::opengl.
 

doc/source/doxygen-docs/tutorial_math_levenberg_marquardt.md

@@ -89,10 +89,12 @@ the change in the parameter vector is very small.
 
 # 4. C++ Implementation
 
-The LM algorithm is implemented in the C++ template class mrpt::math::CLevenbergMarquardtTempl<T>,
+The LM algorithm is implemented in the C++ template class
+[`mrpt::math::CLevenbergMarquardtTempl<T>`](class_mrpt_math_CLevenbergMarquardtTempl.html),
 and there is an example in MRPT/samples/optimize-lm, which is described next.
 
-The type mrpt::math::CLevenbergMarquard is actually a shortcut for the template instantiation mrpt::math::CLevenbergMarquardtTempl<double>.
+The type [`mrpt::math::CLevenbergMarquard`](namespace_mrpt_math.html#doxid-namespacemrpt-1-1math-1ae54dd61d03206aef14cfbea53165d239)
+is actually a shortcut for the template instantiation `mrpt::math::CLevenbergMarquardtTempl<double>`.
 
 The image below represents the resulting path from the initial guess to the minimum for this example.
 The displayed equation is the one-dimensional error (cost) function,

doc/source/tutorial-mrpt-maps-model.rst

@@ -0,0 +1,108 @@
+.. _tutorial-mrpt-maps-model:
+
+===========================================================================
+MRPT design of map classes
+===========================================================================
+
+.. contents:: :local:
+
+1. Maps in mobile robotics and in MRPT
+========================================
+
+In mobile robotics, a "map" is any representation of the external world useful
+for the robot to achieve its tasks. 
+In particular, localization and navigation both require some kind of "map"
+to refer to **places**.
+
+At the top conceptual level, maps can be classified as either 
+metrical (i.e. distances, areas) or
+topological (i.e. just the connectivity between the different areas).
+MRPT focuses on **metric maps**.
+
+All metric maps in MRPT inherit from the common interface
+`mrpt::maps::CMetricMap <class_mrpt_maps_CMetricMap.html>`_
+to ease polymorphism and generic programming.
+
+.. note::
+   The base virtual **class** `mrpt::maps::CMetricMap <class_mrpt_maps_CMetricMap.html>`_
+   is defined in the **library** `mrpt-obs <group_mrpt_obs_grp.html>`_ for convenience,
+   but most actual maps are implemented in the library `mrpt-maps <group_mrpt_maps_grp.html>`_
+
+
+2. Why only one map?
+======================
+
+To ease even more the implementation of generic mapping or SLAM algorithms,
+MRPT defines the "**multi-metric map**".
+This class offers the interface of a regular metric map, but it can hold 
+internally **an arbitrary number of other metric maps**.
+
+To realize of the power and simplicity of this approach, imagine programming
+a method which insert scans from 3 laser range finders into a 3D point map
+(so, a point cloud is built incrementally).
+By just replacing the point map by a multi-metric map, we can now build
+the point cloud and, at our choice, three occupancy grid maps, once for each height, 
+or an additional 3D octomap, for example.
+
+The original code would need no changes at all.
+
+This is the reason of calling the MRPT map model "hierarchical", 
+in the sense that one map (the "multi-metric map") propagates all
+the calls to its "children maps".
+
+Localization (e.g. SE(2) or SE(3) particle-filter localization) also benefits
+from this model, by automatically **merging all sources of information** from
+all the metric maps to evaluate the point-wise likelihood function required
+by this localization approach. In other words: in MRPT you can use either a
+simple 2D gridmap to localize your robot, or a much richer representation
+like a 3D point cloud, several 2D grids (e.g. at different heights),
+a Wi-Fi signal strength map, gas concentration maps, floor reflectivity,
+or define your own map layer.
+
+3. Metric maps classes
+=======================
+
+It is recommended to start reading the documentation for the multi-metric map class
+`mrpt::maps::CMultiMetricMap <class_mrpt_maps_CMultiMetricMap.html>`_, which
+enumerates all metric map types and explains the different ways to create and populate a
+multi-metric map with one or several metric map types.
+
+The most common map types are:
+
+- `mrpt::maps::CSimplePointsMap <class_mrpt_maps_CSimplePointsMap.html>`_: 2D or 3D point clouds of points without any additional annotation or attributes.
+- `mrpt::maps::COccupancyGridMap2D <class_mrpt_maps_COccupancyGridMap2D.html>`_: A planar occupancy grid map for one particular sensor height.
+- `mrpt::maps::COccupancyGridMap3D <class_mrpt_maps_COccupancyGridMap3D.html>`_: 3D occupancy voxel map.
+- `mrpt::maps::COctoMap <class_mrpt_maps_COctoMap.html>`_: For 3D occupancy grids of variable resolution, with octrees (based on the library `octomap`).
+- `mrpt::maps::CColouredOctoMap <class_mrpt_maps_CColouredOctoMap.html>`_: The same than above, but nodes can store RGB data appart from occupancy.
+- `mrpt::maps::CHeightGridMap2D <class_mrpt_maps_CHeightGridMap2D.html>`_: For elevation maps of height for each (x,y) location (Digital elevation model, DEM)
+- `mrpt::maps::CColouredPointsMap <class_mrpt_maps_CColouredPointsMap.html>`_: For point clouds with per-point RGB information.
+
+
+4. Powerful visualization and debugging
+=========================================
+
+All MRPT metric maps, including any combination of them via 
+`mrpt::maps::CMultiMetricMap <class_mrpt_maps_CMultiMetricMap.html>`_,
+can be easily visualized in a 3D viewer, either online or offline
+for posterior debugging.
+
+Since `mrpt::maps::CMetricMap <class_mrpt_maps_CMetricMap.html>`_
+inherits from the virtual interface
+`mrpt::opengl::Visualizable <class_mrpt_opengl_Visualizable.html>`_
+all maps expose a method `getVisualization()` returning a
+`mrpt::opengl::CSetOfObjects::Ptr` which can be inserted in a 3D scene
+for direct visualization or to be saved to disk for posterior inspection
+with the application `SceneViewer3D <page_app_SceneViewer3D.html>`_.
+
+.. note::
+   Refer to the `tutorial on 3D scenes <page_tutorial_3D_scenes.html>`_.
+
+When visualizing a multi-metric map with different map types, they will be 
+all viewed together with the same frame of reference, as in the following 
+example showing a joint mapping of a 3D pointcloud and a 2D gridmaps:
+
+
+.. image:: images/screenshot_joint_gridmap_pointcloud.png
+   :alt: Joint map building of a pointcloud and a gridmap
+
+

libs/maps/include/mrpt/maps/CMultiMetricMap.h

@@ -26,28 +26,28 @@ class TSetOfMetricMapInitializers;
  * evaluate the likelihood of one observation by fusing (multiplying) the
  *likelihoods over the different maps, etc.
  *
- *  <b>These kinds of metric maps can be kept inside</b> (list may be
- *incomplete, refer to classes derived from mrpt::maps::CMetricMap):
- *		- mrpt::maps::CSimplePointsMap: For 2D or 3D range scans, ...
- *		- mrpt::maps::COccupancyGridMap2D: 2D, <b>horizontal</b>  laser range
- *scans, at different altitudes.
- *		- mrpt::maps::COctoMap: For 3D occupancy grids of variable resolution,
- *with octrees (based on the library `octomap`).
- *		- mrpt::maps::CColouredOctoMap: The same than above, but nodes can store
- *RGB data appart from occupancy.
- *		- mrpt::maps::CLandmarksMap: For visual landmarks,etc...
- *		- mrpt::maps::CGasConcentrationGridMap2D: For gas concentration maps.
- *		- mrpt::maps::CWirelessPowerGridMap2D: For wifi power maps.
- *		- mrpt::maps::CBeaconMap: For range-only SLAM.
- *		- mrpt::maps::CHeightGridMap2D: For elevation maps of height for each
- *(x,y) location (Digital elevation model, DEM)
- *		- mrpt::maps::CHeightGridMap2D_MRF: DEMs as Markov Random Field (MRF)
- *		- mrpt::maps::CReflectivityGridMap2D: For maps of "reflectivity" for
- *each
- *(x,y) location.
- *		- mrpt::maps::CColouredPointsMap: For point map with color.
- *		- mrpt::maps::CWeightedPointsMap: For point map with weights (capable of
- *"fusing").
+ * <b>These kinds of metric maps can be kept inside</b> (list may be
+ * incomplete, refer to classes derived from mrpt::maps::CMetricMap):
+ *	- mrpt::maps::CSimplePointsMap: For 2D or 3D range scans, ...
+ *	- mrpt::maps::COccupancyGridMap2D: 2D, <b>horizontal</b>  laser range
+ *    scans, at different altitudes.
+ *	- mrpt::maps::COccupancyGridMap3D: 3D occupancy voxel map.
+ *	- mrpt::maps::COctoMap: For 3D occupancy grids of variable resolution,
+ *    with octrees (based on the library `octomap`).
+ *	- mrpt::maps::CColouredOctoMap: The same than above, but nodes can store
+ *    RGB data appart from occupancy.
+ *	- mrpt::maps::CLandmarksMap: For visual landmarks,etc...
+ *	- mrpt::maps::CGasConcentrationGridMap2D: For gas concentration maps.
+ *	- mrpt::maps::CWirelessPowerGridMap2D: For wifi power maps.
+ *	- mrpt::maps::CBeaconMap: For range-only SLAM.
+ *	- mrpt::maps::CHeightGridMap2D: For elevation maps of height for each
+ *    (x,y) location (Digital elevation model, DEM)
+ *	- mrpt::maps::CHeightGridMap2D_MRF: DEMs as Markov Random Field (MRF)
+ *	- mrpt::maps::CReflectivityGridMap2D: For maps of "reflectivity" for
+ *    each (x,y) location.
+ *	- mrpt::maps::CColouredPointsMap: For point map with color.
+ *	- mrpt::maps::CWeightedPointsMap: For point map with weights (capable of
+ *    "fusing").
  *
  * See CMultiMetricMap::setListOfMaps() for the method for initializing this
  *class programmatically.

libs/math/include/mrpt/math/CLevenbergMarquardt.h

@@ -256,7 +256,9 @@ class CLevenbergMarquardtTempl : public mrpt::system::COutputLogger
 
 };	// End of class def.
 
-/** The default name for the LM class is an instantiation for "double" */
+/** The default name for the LM class is an instantiation for "double"
+ * \ingroup mrpt_math_grp
+ */
 using CLevenbergMarquardt = CLevenbergMarquardtTempl<mrpt::math::CVectorDouble>;
 
 }  // namespace mrpt::math

libs/slam/include/mrpt/slam/CRangeBearingKFSLAM.h

@@ -28,20 +28,21 @@
 namespace mrpt::slam
 {
 /** An implementation of EKF-based SLAM with range-bearing sensors, odometry, a
- * full 6D robot pose, and 3D landmarks.
- *  The main method is "processActionObservation" which processes pairs of
- * action/observation.
- *  The state vector comprises: 3D robot position, a quaternion for its
+ * SE(3) robot pose, and 3D landmarks.
+ * The main method is processActionObservation() which processes pairs of
+ * actions/observations.
+ *
+ * The state vector comprises: 3D robot position, a quaternion for its
  * attitude, and the 3D landmarks in the map.
  *
- *   The following Wiki page describes an front-end application based on this
- * class:
- *     https://www.mrpt.org/Application:kf-slam
+ * The front-end application [kf-slam](page_app_kf-slam.html) is based on this
+ * class.
+ *
+ * For the theory behind this implementation, see the technical report:
+ * \cite blanco2008ekf
  *
- *  For the theory behind this implementation, see the technical report in:
- *     https://www.mrpt.org/6D-SLAM
+ * \sa An implementation for 2D and SE(2) is in CRangeBearingKFSLAM2D
  *
- * \sa An implementation for 2D only: CRangeBearingKFSLAM2D
  * \ingroup metric_slam_grp
  */
 class CRangeBearingKFSLAM

libs/slam/include/mrpt/slam/CRangeBearingKFSLAM2D.h

@@ -27,13 +27,13 @@
 namespace mrpt::slam
 {
 /** An implementation of EKF-based SLAM with range-bearing sensors, odometry,
- *and a 2D (+heading) robot pose, and 2D landmarks.
- *  The main method is "processActionObservation" which processes pairs of
- *action/observation.
+ * SE(2) robot pose, and 2D landmarks.
+ * The main method is processActionObservation() which processes pairs of
+ * actions/observations.
  *
- *   The following pages describe front-end applications based on this class:
- *		- https://www.mrpt.org/Application:2d-slam-demo
- *		- https://www.mrpt.org/Application:kf-slam
+ * The following front-end applications are based on this class:
+ *	- [2d-slam-demo](app_2d-slam-demo.html)
+ *	- [kf-slam](page_app_kf-slam.html)
  *
  * \sa CRangeBearingKFSLAM  \ingroup metric_slam_grp
  */

libs/slam/src/slam/CRangeBearingKFSLAM.cpp

@@ -11,9 +11,8 @@
 //
 
 // ----------------------------------------------------------------------------------------
-// For the theory behind this implementation, see the technical report in:
-//
-//            https://www.mrpt.org/6D-SLAM
+// For the theory behind this implementation, see the
+// technical report cited in the .h file.
 // ----------------------------------------------------------------------------------------
 
 #include <mrpt/math/ops_containers.h>