Adding doc and tests (#1492)

* added doc and tests for util2d.h

* updated cmake-ros ci

* Added util3d.h doc and tests

* util3d_transforms.h: Added doc and tests

* util3d_filtering.h: started doc and test

* util3d_filtering.h: more tests and doc

* Added more doc/tests

* finished util3d_filtering doc and tests

* added test for util2d::depthBleedingFiltering

* Added util3d_registration tests

* Added util3d_features.h doc/tests

* added doc/tests for util3d_correspondences.h

* added doc/gtest for util3d_mapping.h (missing hpp functions)

* finished testing util3d_mapping.hpp

* Added util3d_motion_estimation.h tests (2D->3D done)

* finished util3d_motion_estimation.h tests

* minimal util3d_surface.h

* Added Transform and VisualWord tests

* Added doc for CameraModel and StereoCameraModel

* Added more logs in ros ci

* Passing tests on fical

* improved all devcontainer

* added devcontainer kilted, fixed source setup.bash, removed ldconfig in ros-cmake workflow

* cleanup

* source ros

* Added utilite tests

* Added testing to appveyor, github actions cancellable on re-commit on same branch

* appveyor testing without all targets

* appveyor: specifying ALL_BUILD target

* Fixed Util2dTest.NMSImageBoundsRespected test

* Fixing PCL Indices error on old pcl

* Added VWDictionary tests and doc. Fixed LSH not working (fix from https://github.com/flann-lib/flann/pull/472

* fixing some appveyor CI errors, added test to check dictionary serialization against all type

* Added StereoDense, StereoBM and StereoSGBM doc and tests

* Added Stereo tests

* Added CameraModel and StereoCameraModel tests

* Added doc and test for Statistics

* Added doc/tests for Signature

* Added doc/test for SensorEvent, added doc for SensorCaptureInfo

* Added doc to SensorData

* Added SensorData tests

* Added SensorCapture and SensorCaptureThread doc and tests

* fixed sensordata test

* updated SSC test and doc

* Added doc and tests for BayesFilter class

* Enabled testing on mac, updated windows testing like on linux

* added test_link

* fixed unresolved on windows

* fixed ThreadHandle error on macos ci

* Added GPS and GeodeticCoords tests

* Added tests for compression

* Added Odometry tests (base class only)

* Added DBDriver tests

* Added coverage report

* uniformized test names

* fixing concurancy and coverage ci

* dont built tools, examples and app for coverage build

* fixed report tool rebuilt without qt compilation error

* updated coverage option

* updated coverage config

* added doc CI job

* fixing windows and mac ci errors

* Added DBDriverSqlite3 tests

* Added IMU tests

* Added Graph tests

* fixing flaky macos test

* Added IMUThread and IMUFilter tests

* Added Landmarks tests

* Added LASWriter tests

* fixing seed flaky test

* fixing flaky macos timing tests

* Added LocalGrid tests

* Added LocalGridMaker tests

* fixing ci errors

* Added GlobalMap tests

* Added doc for EnvSensor

* Added Features2D tests

* Added Registration tests

* Added RegistrationVis tests

* Added doc for Rtabmap and Memory classes

* Added Memory and Rtabmap tests

* making some tests less flaky

* lcov 1.14 support

* updated compatible tool arguments

* Added integration tests (RGB-D, Stereo, Lidar2d, Lidar3d)

* More octomap checks

* Refactored how/when python interpretor is created to simplify library usage

* Added python tests

* fixed some flaky tests

* suppressed some third party related warnings

* fixed ceres tests

* more flaky fixes

* Fixing tests without libpointmatcher

* Added RANSAC rejection filter to PCL ICP

* fixing multi platform flakiness

* Added test to detect regression

* Fixing windows pcl link error

* fixed some macos flakiness

* bigger 2D2D registration error on opencv 4.6.0

* flakiness

* fixing flaky tests on windows and mac

* flaky thread test on slow mac VM

* windows slow test

* fixing more ci erros

* fxing temp dir on windows

* Added Optimizer tests and discovered some bugs (fixed)

* fixing flaky tests in mac and windows

* Added Optimizer doc

* Added GTSAM BA, updated Ceres to use g2o ba parameters. Renamed g2o's ba related parameters to Optimizer group and used by both gtsam and ceres.

* fixing build without gtsam

* fixing home dir

* fixing python ci isssues

* Added multicam ba tests

* Added Ceres multicam BA support

* Aligned BundleAdjustment parameters with Optimizer/Strategy to avoid confusion in the code

* Added BA integration test

* Added robust graph optimization integration test

* Added loop3it test

* Added stereo20Hz test

* Added smartfactor gtsam

* Fixed bugged check and warn if python didn't return any descriptors

* Fixing gtsam version build issues

* fixing tilt on windows ci

* loosing ceres integration test for ci

* mac ci flakiness

* updating missing param in gui

* updating test bound for mac

* added appearance-based tests, set min gftt quality to quality level

* testing more stuff

* improving features2d tests

* ci flakiness

* fixing flaky ci

* ci fixes

* flaky fixes

* Added RegistrationIcp tests

* Added icp integration test with real-worl corridor like env

* intermediate nodes

* fixing enum

* Updated test to catch #1714

* Fixed 2d corridor failing on pcl

* flaky pnp test

* flaky brisk test

* Set rtabmap_integration test as long

* updating loop closure test

* flaky ci tests

* TEsting roundtrip g2o/toro save/load

* loosing test bound

* fixed cuda capable checks

* flaky tests

* Debugging test hanging

* more debugging stuff

* updating limit

* windows: disabled cuda on ci to avoid incompatible driver issue. Fixing a bad test mem allocation

* trying fixing cuda hanging issue

* fixing ci flakyness

* flaky tests

* Updated BOW flaky tests by checking min precision/recall instead of recall@100precision. Fixed signature test

* CameraModel::load() test initRectificationMap param

* test dbdriver load dictionary idsOnly

* Memory: test keepLinkedInDb param

* added dummyDictionary tests

* test intermediate nodes count

* Added MarkerDetector tests

* reverted breaking change of UMutex and USemaphore

* Features2d: fixed compiltion warnings with clang about override

* clang warnings

* fixing test build with pcl 1.8

* g2o and gtsam build errors on android

* opencv5 test fixes

* disabled testing for ios and android builds

* normalized endline characters for easier diff

* added LF CRLF rule

* bump 0.23.10. fixing doc version

* Publish rtabmap website doc from ci

* fixing MSCVC build error

* macos icp flaky test

* fixing ceres macos test bound

* ficing more flaky tests

* fixing opencv5 related test errors. Also fixed an actual bug in ENU_WGS84ToGeocentric_WGS84()

* added comment about mrpt change

* removed rosdoc2 (will add it for rtabmap_ros later)

* fixing website style

* updated download links

* locally deployable website with api

* sweep doxygen issues

* improved/revised doxygen main pages

* removed examples empty page

* Updated doxygen style

* more concise doxygen groups

* added api link on main readme

* fixing utilite test error

* fixing CommonFilteringGroundNormalsUp test

* updated precisionRecall test bounds for Freak and brief descriptors

* fixing scale check in ba tests

* disabled tests on windows cuda build (missing dlls amd runner cannot test cuda anyway)

* ceres: missing suitesparse dep in windows ci

* adjusting recall thr for fast/freak

* ficing more flaky tests

* fixing flaky tests

* disabled coverage in ros ci

* Enable integration tests for ros ci jobs

* loosing up some threshold for failing tests

* trigger cache

* fixing test data in ros ci. Updated flaky test for mac

* slaking some test limit

* Fixed rtabmap-detectMoreLoopClosures inverted output value

* loosing up sift recall on mac

* optimizer re-ordered distribution for reproducible results (mac g2o)

* macos dump test crash log

* combining all tests to save time on shared library reload. Also fixed Logs with missing arguments.

* Added ENABLE_FORMAT_ERRORS cmake option

* do test only one time

* fixed all format warnings

* format security android build errors

* less verbose tests

* updated ImuUThread test

* fixed a log

* Fixed libpointmatcher 2d normals eigen issue

* Fixing libpointmatcher conversion issues

* fixing libpointmatcher test on windows ci

* cleanup comments, relax some test thr

* disabled sequoia-intel ci build (too flaky, would need extensive testing directly on that machine)

corelib/include/rtabmap/core/RtabmapThread.h

@@ -48,40 +48,138 @@ namespace rtabmap {
 
 class Rtabmap;
 
+/**
+ * @class RtabmapThread
+ * @brief Runs a @ref Rtabmap instance in its own thread, driven by events.
+ *
+ * The thread owns the @ref Rtabmap object and calls @ref Rtabmap::process() on the
+ * data it receives, so that mapping never blocks the sensor or odometry threads.
+ * It is the last stage of the event-based pipeline:
+ * @ref SensorCaptureThread → @ref OdometryThread → RtabmapThread.
+ *
+ * **Input events** (handled in @ref handleEvent(), i.e. in the caller's thread):
+ * - @ref OdometryEvent and @ref SensorEvent -- the frame and its odometry pose are
+ *   buffered for the main loop. A null pose means odometry is lost and the frame
+ *   is dropped (unless the memory is in localization mode).
+ * - @ref UserDataEvent -- user data attached to the next processed frame.
+ * - @ref RtabmapEventCmd -- a command (see @ref RtabmapEventCmd::Cmd), such as
+ *   initializing or closing the map, triggering a new map, pausing, setting a
+ *   goal, labelling a node or requesting the map.
+ * - @ref ParamEvent -- applies new parameters, equivalent to a
+ *   @ref RtabmapEventCmd::kCmdUpdateParams command.
+ *
+ * **Output events**, posted from the thread:
+ * - @ref RtabmapEvent with the @ref Statistics of an iteration that added a node.
+ * - @ref RtabmapEvent3DMap in answer to a map request.
+ * - @ref RtabmapGlobalPathEvent and @ref RtabmapGoalStatusEvent for path planning.
+ * - @ref RtabmapLabelErrorEvent when a label could not be set.
+ *
+ * **Input regulation**, on top of what @ref Rtabmap does:
+ * - Frames are queued in a buffer of @ref Parameters::kRtabmapImageBufferSize()
+ *   elements; when it is full the oldest frame is dropped, so a slow map update
+ *   never delays the live pipeline.
+ * - Frames arriving faster than @ref Parameters::kRtabmapDetectionRate() are
+ *   skipped, which is the rate limiting that @ref Rtabmap::process() itself does
+ *   not do. With @ref Parameters::kRtabmapCreateIntermediateNodes() enabled they
+ *   are kept instead, and added as intermediate nodes (odometry-only, not used
+ *   for loop closure detection).
+ * - An identity odometry pose, or a covariance ≥ 9999, is read as an odometry
+ *   reset and triggers a new map id on the next processed frame. The largest
+ *   covariance seen between two processed frames is the one passed on, so the
+ *   link weight does not depend on the odometry frame rate.
+ *
+ * The object registers itself as a @ref UEventsHandler, so posting an event to
+ * @ref UEventsManager is enough to feed it:
+ * @code
+ * rtabmap::RtabmapThread rtabmapThread(new rtabmap::Rtabmap()); // takes ownership
+ * rtabmapThread.start();
+ * UEventsManager::addHandler(&rtabmapThread);
+ * UEventsManager::createPipe(&odomThread, &rtabmapThread, "OdometryEvent");
+ * @endcode
+ *
+ * @see Rtabmap
+ * @see OdometryThread
+ * @see SensorCaptureThread
+ */
 class RTABMAP_CORE_EXPORT RtabmapThread :
 	public UThreadNode,
 	public UEventsHandler
 {
 public:
+	/** @brief What the main loop does on its next wake-up. */
 	enum State {
-		kStateDetecting,
-		kStateProcessCommand
+		kStateDetecting,      /**< Process the next buffered frame. */
+		kStateProcessCommand  /**< Execute the next queued @ref RtabmapEventCmd. */
 	};
 
 public:
-	// take ownership
+	/**
+	 * @brief Constructor.
+	 * @param rtabmap The map to run; must not be null. The thread takes ownership
+	 *                and deletes it in @ref close(), which the destructor calls.
+	 *
+	 * The buffer size, detection rate and intermediate node settings are taken
+	 * from the default parameters here, then updated by every
+	 * @ref RtabmapEventCmd::kCmdInit and @ref RtabmapEventCmd::kCmdUpdateParams
+	 * command.
+	 */
 	RtabmapThread(Rtabmap * rtabmap);
 	virtual ~RtabmapThread();
 
+	/** @brief Drops the buffered frames, the pending user data and the odometry state. */
 	void clearBufferedData();
+	/**
+	 * @brief Sets the maximum rate at which frames are processed (Hz, 0 = unlimited).
+	 *
+	 * Same setting as @ref Parameters::kRtabmapDetectionRate(). Frames arriving
+	 * faster are dropped, or added as intermediate nodes if
+	 * @ref createIntermediateNodes() is enabled.
+	 */
 	void setDetectorRate(float rate);
+	/**
+	 * @brief Sets how many frames may wait in the buffer (0 = unlimited).
+	 *
+	 * Same setting as @ref Parameters::kRtabmapImageBufferSize(). Once full, the
+	 * oldest frame is dropped to make room for the new one.
+	 */
 	void setDataBufferSize(unsigned int bufferSize);
+	/**
+	 * @brief Keeps the frames skipped by @ref setDetectorRate() as intermediate nodes.
+	 *
+	 * Same setting as @ref Parameters::kRtabmapCreateIntermediateNodes(). Those
+	 * nodes carry the odometry link but take no part in loop closure detection.
+	 */
 	void createIntermediateNodes(bool enabled);
 
+	/** @return Maximum processing rate in Hz (0 = unlimited). */
 	float getDetectorRate() const {return _rate;}
+	/** @return Maximum number of buffered frames (0 = unlimited). */
 	unsigned int getDataBufferSize() const {return _dataBufferMaxSize;}
+	/** @return True if skipped frames are added as intermediate nodes. */
 	bool getCreateIntermediateNodes() const {return _createIntermediateNodes;}
 
 	/**
-	 * Close rtabmap. This will delete rtabmap object if set.
+	 * @brief Joins the thread and closes rtabmap. This will delete rtabmap object if set.
 	 * @param databaseSaved true=database saved, false=database discarded.
 	 * @param databasePath output database file name, ignored if
 	 *                     Db/Sqlite3InMemory=false (opened database is
 	 *                     then overwritten).
+	 *
+	 * Called by the destructor with @p databaseSaved true. The object cannot be
+	 * used afterwards: the @ref Rtabmap instance it owned is gone.
 	 */
 	void close(bool databaseSaved, const std::string & databasePath = "");
 
 protected:
+	/**
+	 * @brief Receives the events listed in the class description.
+	 *
+	 * Runs in the posting thread: data events are only queued here, the work
+	 * happens in the thread's main loop. Events are ignored until the thread is
+	 * started.
+	 *
+	 * @return Always false, so the event keeps being dispatched to other handlers.
+	 */
 	virtual bool handleEvent(UEvent * anEvent);
 
 private: