progress with documentation

doc/source/doxygen-docs/example-gui_display3D_custom_render.md

@@ -1,3 +1,6 @@
 \page gui_display3D_custom_render Example: gui_display3D_custom_render
+
+See: \ref tutorial_3D_scenes
+
 C++ example source code:
 \include gui_display3D_custom_render/test.cpp

doc/source/doxygen-docs/example-gui_display3D_example.md

@@ -1,3 +1,8 @@
 \page gui_display3D_example Example: gui_display3D_example
+
+See: \ref tutorial_3D_scenes
+
+
+![gui_display3D_example screenshot](doc/source/images/gui_display3D_example_screenshot.png)
 C++ example source code:
 \include gui_display3D_example/test.cpp

doc/source/doxygen-docs/example-gui_fbo_render_example.md

@@ -1,3 +1,6 @@
 \page gui_fbo_render_example Example: gui_fbo_render_example
+
+See: \ref tutorial_3D_scenes
+
 C++ example source code:
 \include gui_fbo_render_example/test.cpp

doc/source/doxygen-docs/example-gui_nanogui_demo.md

@@ -1,5 +1,8 @@
 \page gui_nanogui_demo Example: gui_nanogui_demo
 
+See: \ref tutorial_3D_scenes
+
+
 ![gui_nanogui_demo screenshot](doc/source/images/gui_nanogui_demo_screenshot.png)
 C++ example source code:
 \include gui_nanogui_demo/test.cpp

doc/source/doxygen-docs/example-gui_windows_events.md

@@ -1,3 +1,6 @@
 \page gui_windows_events Example: gui_windows_events
+
+See: \ref tutorial_3D_scenes
+
 C++ example source code:
 \include gui_windows_events/test.cpp

doc/source/doxygen-docs/tutorial-3D-scenes.md

@@ -0,0 +1,103 @@
+\page tutorial_3D_scenes Tutorial: 3D scenes
+
+# 1. Examples
+
+If you prefer directly jumping to example code, see:
+
+- \ref opengl_objects_demo
+- \ref gui_display3D_example
+- \ref gui_nanogui_demo
+
+# 2. Relevant C++ classes
+
+The main class behind 3D scenes is mrpt::opengl::COpenGLScene, which allows the user to create, load, save, and render 3D scenes using predefined 3D entities.
+The class can be understood as a program to be run on the OpenGL system,
+containing a sequence of viewport definitions, primitive objects, shaders, etc...
+
+An "OpenGL scene" contains from 1 up to any number of **Viewports**, each one
+associated a set of visual objects and, optionally, a preferred camera position.
+Both orthogonal (2D/3D) and projective camera models can be used for each
+viewport independently, greatly increasing the possibilities of rendered scenes.
+An instance of mrpt::opengl::COpenGLScene always contains **at least one viewport** (mrpt::opengl::COpenGLViewport), named `"main"`, covering the entire window area by default.
+If you do not provide a viewport name in API calls, `"main"` will be always be used by default,
+so do not worry on remembering that name.
+
+Viewports are referenced by their names, case-sensitive strings. Each viewport contains a different
+"3D scene" (i.e. they render different objects), though a mechanism exists to share the same 3D scene by a number of viewports so memory is not wasted replicating the same smart pointers (see mrpt::opengl::COpenGLViewport::setCloneView()).
+
+The main rendering method, COpenGLScene::render(), assumes that a viewport has been set-up for the entire target window. That method will internally make the required calls to opengl for creating the additional viewports. Note that only the depth buffer is cleared by default for each (non-main) viewport, to allow transparencies. This can be disabled by the approppriate member in COpenGLViewport.
+
+Users will never normally need to invoke COpenGLScene::render() manually, but use instead:
+- the 3D standalone viewer: [SceneViewer3D](app_SceneViewer3D.html)
+- the basic runtime 3D display windows mrpt::gui::CDisplayWindow3D
+- the advanced GUI-controls capable display  mrpt::gui::CDisplayWindowGUI
+- wxWidgets / Qt controls also exist for integration into custom GUIs (see mrpt::gui:: mrpt::gui::CGlCanvasBase)
+
+An object mrpt::opengl::COpenGLScene can be saved to a `.3Dscene` file using 
+mrpt::opengl::COpenGLScene::saveToFile(), for posterior visualization from
+the standalone application [SceneViewer3D](app_SceneViewer3D.html).
+
+# 3. Creating, populating and updating a COpenGLScene
+
+Since 3D rendering is performed in a detached thread, especial care must be taken when updating the 3D scene to be rendered. Updating here means either (i) inserting/removing new primitives to the COpenGLScene object associated with a CDisplayWindow3D, or (ii) modifying the pose, color, contents, etc. of any of the primitives previously inserted into such COpenGLScene object.
+
+To avoid rance conditions (rendering always happens on an standalone thread),
+the process of updating a 3D scene must make use of a mechanism that
+locks/unlocks an internal critical section, and it comprises these steps:
+
+    // Create the GUI window object.
+    // This will lock until the detached MRPT GUI thread creates
+    // the window successfully.
+    mrpt::gui::CDisplayWindow3D win("My window", 1024, 800);
+
+    // Lock the 3D scene (**Enter critical section**)
+    // get3DSceneAndLock() must be called to prevent the rendering
+    // thread accessing the OpenGLScene while we are manipulating its contents.
+    // This function returns a reference to a smart pointer which may be used for:
+    // a) Create mrpt::opengl primitives and insert them into the scene. This is
+    //    the typical first use of get3DSceneAndLock().
+    // b) Just ignore it. In subsequent calls, if the scene was already populated
+    //    and you don't need to search for any primitive object (e.g. because you
+    //    kept a copy of all mrpt::opengl::XXX::Ptr pointers for direct access),
+    //    just ignore the return value.
+    // c) Replace the entire 3D scene (read below after the code snippet)
+    mrpt::opengl::COpenGLScene::Ptr &ptrScene = win.get3DSceneAndLock();
+
+    // Modify the scene or the primitives therein:
+    ptrScene->...
+
+    // Unlock the 3D scene (**Exit critical section**).
+    // Required for the window to be able to be redrawn.
+    win.unlockAccess3DScene();
+
+    // Force a window update, if required:
+    win.forceRepaint();
+
+An alternative way of updating the scene is by creating,
+before locking the 3D window, a new object of class COpenGLScene, then locking
+the window only for replacing the smart pointer. This may be advantageous
+is generating the 3D scene takes a long time, since while the window is locked
+it will not be responsive to the user input or window redraw.
+
+
+# 4. Existing visualization primitives
+
+For a list of existing visualization primitive classes, browse the namespace mrpt::opengl,
+or inspect the example: \ref opengl_objects_demo
+
+![MRPT opengl primitives](opengl_objects_demo_screenshot.png)
+
+# 5. Text messages
+
+GUI windows offer the possibility of displaying any number of text labels on
+top of the rendered scene. Refer to:
+
+- \ref gui_display3D_example
+- API: mrpt::gui::CDisplayWindow3D::addTextMessage()
+
+# 6. Advanced UI controls
+
+For more advanced UI controls, including subwindows that can be dragged,
+minimized and restored, etc. see:
+- mrpt::gui::CDisplayWindowGUI
+- \ref gui_nanogui_demo

doc/source/tutorials.rst

@@ -7,10 +7,40 @@ Note: This page is in the process of being imported from https://www.mrpt.org/tu
 
 .. toctree::
   :maxdepth: 2
+  :caption: Basics
 
   using_mrpt_apps
   mrpt_from_cmake
+
+.. toctree::
+  :maxdepth: 2
+  :caption: GUI and 3D graphics
+
+  page_tutorial_3D_scenes.rst
+
+.. toctree::
+  :maxdepth: 2
+  :caption: Robotics, SLAM
+
+  tutorial-mrpt-maps-model
   range_only_localization_mapping
+  tutorial-icp-alignment
+
+.. toctree::
+  :maxdepth: 2
+  :caption: Maths, Geometry
+
+  tutorial-ransac
+
+.. toctree::
+  :maxdepth: 2
+  :caption: Robotics file formats
+
+  tutorial-file-formats
+
+.. toctree::
+  :maxdepth: 2
+  :caption: Miscellaneous
+
   page_porting_mrpt2
   env-vars
-  tutorial-icp-alignment

libs/gui/include/mrpt/gui/CDisplayWindow3D.h

@@ -77,41 +77,35 @@ class CMyGLCanvas_DisplayWindow3D;
  *      mrpt::opengl::COpenGLScene::Ptr ptrScene;
  *      mrpt::gui::CDisplayWindow3DLocker  locker(win,ptrScene);
  *      //...
+ *      // Either:
+ *      // - modify ptrScene
+ *      // - Or assign it a prebuilt object with:
+ *      *ptrScene = *otherScene;
  *
  *   } // scene is unlocked upon dtor of `locker`
  * \endcode
  *
  * Notice however that a copy of the smart pointer is made, so replacement of
- * the entire scene
- * via `operator =` is not possible if using this method. Still, in general it
- * should be preferred because
- * the mutexes are automatically released in case of unexpected exceptions.
+ * the entire scene via `operator =` is not possible if using this method.
+ * Instead, the content of the scene should be assigned using the `operator =`
+ * of the **dereferenced** object as illustrated with
+ * the `*ptrScene = *otherScene;` above.
  *
  * The window can also display a set of 2D text messages overlapped to the 3D
- * scene.
- *  See CDisplayWindow3D::addTextMessage
+ * scene. See CDisplayWindow3D::addTextMessage
  *
  *  For a list of supported events with the observer/observable pattern, see
  * the discussion in mrpt::gui::CBaseGUIWindow.
  *  In addition to those events, this class introduces
  * mrpt::gui::mrptEvent3DWindowGrabImageFile
  *
- * ** CDisplayWindow3D mouse view navigation cheatsheet **
- *  - <b>Orbit camera</b>: Left-button pressed + move
- *  - <b>Zoom in / out</b>:
- *    - Mouse scroll wheel, or
- *    - SHIFT+Left-button pressed + move up/down
- *  - <b>Look around (pivot camera)</b>: CTRL+Left-button pressed + move
- * up/down
- *  - <b>Pan (XY plane)</b>: Right-button pressed + move
- *  - <b>Move camera along Z axis</b>: SHIFT+Left-button pressed + move
- * left/right
- *
+ * [CDisplayWindow3D mouse view navigation
+ * cheatsheet](tutorial-3d-navigation-cheatsheet.html)
  *
  * ![mrpt::gui::CDisplayWindow3D screenshot](preview_CDisplayWindow3D.png)
  *
- * \sa  The example /samples/display3D, the <a
- * href="http://www.mrpt.org/Tutorial_3D_Scenes" > tutorial only</a>.
+ * \sa \ref tutorial_3D_scenes
+ *
  * \ingroup mrpt_gui_grp
  */
 class CDisplayWindow3D : public mrpt::gui::CBaseGUIWindow

libs/gui/include/mrpt/gui/CDisplayWindowGUI.h

@@ -50,18 +50,18 @@ struct CDisplayWindowGUI_Params
  * Refer to nanogui API docs or MRPT examples for further usage examples.
  * A typical lifecycle of a GUI app with this class might look like:
  *
- * \rst
- * .. code-block:: cpp
- *
- *    nanogui::init();
- *    {
- *      mrpt::gui::CDisplayWindowGUI win;
- *      win.drawAll();
- *      win.setVisible(true);
- *      nanogui::mainloop();
- *    }
- *    nanogui::shutdown();
- * \endrst
+ * \code
+ * nanogui::init();
+ * {
+ *   mrpt::gui::CDisplayWindowGUI win;
+ *   // Populate win adding UI controls, etc.
+ *   // ...
+ *   win.drawAll();
+ *   win.setVisible(true);
+ *   nanogui::mainloop();
+ * }
+ * nanogui::shutdown();
+ * \endcode
  *
  *
  * ![mrpt::gui::CDisplayWindowGUI screenshot](preview_CDisplayWindowGUI.png)

libs/img/include/mrpt/img/CImage.h

@@ -27,6 +27,7 @@ namespace mrpt::io { class CStream; }
 // Add for declaration of mexplus::from template specialization
 DECLARE_MEXPLUS_FROM(mrpt::img::CImage)
 
+/** Classes for image storage and manipulation \ingroup mrpt_img_grp */
 namespace mrpt::img
 {
 enum class PixelDepth : int32_t

libs/math/include/mrpt/math/CMatrixDynamic.h

@@ -20,6 +20,7 @@
 #include <cstring>	// memset()
 #include <type_traits>
 
+/** Math and geometry \ingroup mrpt_math_grp */
 namespace mrpt::math
 {
 /**  This template class provides the basic functionality for a general 2D

libs/system/include/mrpt/system/COutputLogger.h

@@ -25,6 +25,7 @@
 #include <string>
 #include <string_view>
 
+/** System helpers and utilities \ingroup mrpt_system_grp */
 namespace mrpt::system
 {
 /** \brief Enumeration of available verbosity levels. \sa COutputLogger */

samples/gui_display3D_custom_render/README.md

@@ -0,0 +1 @@
+See: \ref tutorial_3D_scenes

samples/gui_display3D_example/README.md

@@ -0,0 +1 @@
+See: \ref tutorial_3D_scenes

samples/gui_fbo_render_example/README.md

@@ -0,0 +1 @@
+See: \ref tutorial_3D_scenes

samples/gui_nanogui_demo/README.md

@@ -0,0 +1 @@
+See: \ref tutorial_3D_scenes

samples/gui_windows_events/README.md

@@ -0,0 +1 @@
+See: \ref tutorial_3D_scenes