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/test/test_pydetector.cpp

@@ -0,0 +1,328 @@
+// Tests for PyDetector: rtabmap's bridge to Python-backed local-feature
+// detectors (SuperPoint, custom networks, etc.).
+//
+// We stand in a tiny numpy-only stub script for whatever the user would
+// normally point PyDetector at, so the test exercises the full pipeline
+// (script load -> init() -> detect() -> keypoint/descriptor parsing) without
+// pulling in heavy ML model weights. The whole file is a no-op when rtabmap
+// is built without Python -- the CMakeLists.txt only registers it when
+// WITH_PYTHON AND Python3_FOUND, and a defensive #ifdef matches that.
+
+#include <gtest/gtest.h>
+#include <rtabmap/core/Version.h>
+
+#ifdef RTABMAP_PYTHON
+
+#include <rtabmap/core/Features2d.h>
+#include <rtabmap/core/Parameters.h>
+#include <rtabmap/utilite/UConversion.h>
+#include <rtabmap/utilite/UFile.h>
+
+#include <opencv2/core.hpp>
+
+#include "TestUtils.h"
+#include <fstream>
+#include <memory>
+#include <string>
+
+using namespace rtabmap;
+
+namespace {
+
+// Drops a minimal detector script implementing the contract PyDetector.cpp
+// expects:
+//   init(cuda)            -- called once
+//   detect(imageBuffer)   -- returns (Nx3 float32 [x, y, response], NxDIM float32)
+// Three hard-coded keypoints at (w/4, h/4), (w/2, h/2), (3w/4, 3h/4) with
+// descending responses; descriptor rows filled with (row_index + 1) so the
+// test can identify them. Numpy-only, no heavy deps.
+//
+// Each test uses a unique filename via `tag` so the Python module cache
+// reloads fresh content on each TEST().
+std::string writeStubScript(int tag)
+{
+	const std::string path = test::tempPath(uFormat("rtabmap_test_pydetector_%d_%d.py", test::getPid(), tag));
+	std::ofstream out(path);
+	out <<
+		"import numpy as np\n"
+		"\n"
+		"INITIALIZED = False\n"
+		"CUDA_ARG = None\n"
+		"DESCRIPTOR_DIM = 8\n"
+		"\n"
+		"def init(cuda):\n"
+		"    global INITIALIZED, CUDA_ARG\n"
+		"    INITIALIZED = True\n"
+		"    CUDA_ARG = int(cuda)\n"
+		"\n"
+		"def detect(image):\n"
+		"    h, w = image.shape\n"
+		"    pts = np.array([\n"
+		"        [w * 0.25, h * 0.25, 0.9],\n"
+		"        [w * 0.50, h * 0.50, 0.8],\n"
+		"        [w * 0.75, h * 0.75, 0.7],\n"
+		"    ], dtype=np.float32)\n"
+		"    desc = np.zeros((3, DESCRIPTOR_DIM), dtype=np.float32)\n"
+		"    for i in range(3):\n"
+		"        desc[i, :] = float(i + 1)\n"
+		"    return pts, desc\n";
+	return path;
+}
+
+// Variant stubs to exercise the edge cases that previously triggered
+// asserts in PyDetector / generateDescriptorsImpl. Each returns shapes
+// that violate the (Nx3, NxDIM) contract that the happy path expects.
+
+// Returns 3 keypoints but a (0,0) descriptor array -- the original
+// SuperPoint-style failure: nDesc=0, dim=0, but nKpts>0.
+std::string writeStubScriptEmptyDescriptors(int tag)
+{
+	const std::string path = test::tempPath(uFormat("rtabmap_test_pydetector_emptydesc_%d_%d.py", test::getPid(), tag));
+	std::ofstream out(path);
+	out <<
+		"import numpy as np\n"
+		"def init(cuda):\n"
+		"    pass\n"
+		"def detect(image):\n"
+		"    h, w = image.shape\n"
+		"    pts = np.array([\n"
+		"        [w * 0.25, h * 0.25, 0.9],\n"
+		"        [w * 0.50, h * 0.50, 0.8],\n"
+		"        [w * 0.75, h * 0.75, 0.7],\n"
+		"    ], dtype=np.float32)\n"
+		"    desc = np.zeros((0, 0), dtype=np.float32)\n"
+		"    return pts, desc\n";
+	return path;
+}
+
+// 3 keypoints but only 2 descriptors -- mismatched row count.
+std::string writeStubScriptMismatchedCounts(int tag)
+{
+	const std::string path = test::tempPath(uFormat("rtabmap_test_pydetector_mismatch_%d_%d.py", test::getPid(), tag));
+	std::ofstream out(path);
+	out <<
+		"import numpy as np\n"
+		"def init(cuda):\n"
+		"    pass\n"
+		"def detect(image):\n"
+		"    h, w = image.shape\n"
+		"    pts = np.array([\n"
+		"        [w * 0.25, h * 0.25, 0.9],\n"
+		"        [w * 0.50, h * 0.50, 0.8],\n"
+		"        [w * 0.75, h * 0.75, 0.7],\n"
+		"    ], dtype=np.float32)\n"
+		"    desc = np.zeros((2, 8), dtype=np.float32)\n"
+		"    return pts, desc\n";
+	return path;
+}
+
+// Both arrays empty -- the well-behaved "I found nothing" return.
+std::string writeStubScriptBothEmpty(int tag)
+{
+	const std::string path = test::tempPath(uFormat("rtabmap_test_pydetector_bothempty_%d_%d.py", test::getPid(), tag));
+	std::ofstream out(path);
+	out <<
+		"import numpy as np\n"
+		"def init(cuda):\n"
+		"    pass\n"
+		"def detect(image):\n"
+		"    pts  = np.zeros((0, 3), dtype=np.float32)\n"
+		"    desc = np.zeros((0, 8), dtype=np.float32)\n"
+		"    return pts, desc\n";
+	return path;
+}
+
+ParametersMap baseParams(const std::string & scriptPath)
+{
+	ParametersMap p;
+	p.insert(ParametersPair(Parameters::kPyDetectorPath(), scriptPath));
+	p.insert(ParametersPair(Parameters::kPyDetectorCuda(), "false"));
+	p.insert(ParametersPair(Parameters::kKpMaxFeatures(), "100"));
+	p.insert(ParametersPair(Parameters::kKpSSC(), "false"));
+	return p;
+}
+
+cv::Mat makeImage(int rows = 64, int cols = 64)
+{
+	// PyDetector requires CV_8UC1; uniform content is fine for the stub
+	// which ignores pixel values.
+	return cv::Mat(rows, cols, CV_8UC1, cv::Scalar(0));
+}
+
+}  // namespace
+
+// Full happy path: the script loads, returns 3 keypoints + descriptors, and
+// the keypoint positions, responses, and descriptor rows survive end to end.
+TEST(PyDetector, BasicDetection)
+{
+	const std::string scriptPath = writeStubScript(1);
+	std::unique_ptr<Feature2D> detector(Feature2D::create(
+			Feature2D::kFeaturePyDetector, baseParams(scriptPath)));
+	ASSERT_NE(detector.get(), nullptr);
+	EXPECT_EQ(Feature2D::kFeaturePyDetector, detector->getType());
+
+	cv::Mat image = makeImage(64, 64);
+	std::vector<cv::KeyPoint> kpts = detector->generateKeypoints(image);
+	ASSERT_EQ(3u, kpts.size());
+
+	// Stub points: (w/4, h/4), (w/2, h/2), (3w/4, 3h/4) with responses
+	// 0.9, 0.8, 0.7.
+	EXPECT_NEAR(16.0f, kpts[0].pt.x, 1e-3f);
+	EXPECT_NEAR(16.0f, kpts[0].pt.y, 1e-3f);
+	EXPECT_NEAR(32.0f, kpts[1].pt.x, 1e-3f);
+	EXPECT_NEAR(48.0f, kpts[2].pt.x, 1e-3f);
+	EXPECT_NEAR(0.9f, kpts[0].response, 1e-5f);
+	EXPECT_NEAR(0.8f, kpts[1].response, 1e-5f);
+	EXPECT_NEAR(0.7f, kpts[2].response, 1e-5f);
+
+	cv::Mat descriptors = detector->generateDescriptors(image, kpts);
+	EXPECT_EQ(3, descriptors.rows);
+	EXPECT_EQ(8, descriptors.cols);
+	EXPECT_EQ(CV_32FC1, descriptors.type());
+	for(int r = 0; r < descriptors.rows; ++r)
+	{
+		EXPECT_NEAR(float(r + 1), descriptors.at<float>(r, 0), 1e-5f);
+	}
+
+	UFile::erase(scriptPath);
+}
+
+// PyDetector logs an error and silently returns no keypoints when the
+// script path doesn't exist -- the constructor doesn't throw. Pin that
+// contract so callers can safely construct without pre-checking the path.
+TEST(PyDetector, MissingPathReturnsEmpty)
+{
+	const std::string scriptPath = test::tempPath(uFormat("rtabmap_test_pydetector_does_not_exist_%d.py", test::getPid()));
+	std::unique_ptr<Feature2D> detector(Feature2D::create(
+			Feature2D::kFeaturePyDetector, baseParams(scriptPath)));
+	ASSERT_NE(detector.get(), nullptr);
+
+	cv::Mat image = makeImage(32, 32);
+	std::vector<cv::KeyPoint> kpts = detector->generateKeypoints(image);
+	EXPECT_TRUE(kpts.empty());
+}
+
+// A non-empty mask removes keypoints whose (x, y) falls on a 0 pixel. The
+// stub returns one keypoint at (48, 48); we mask everything from row/col 33
+// onward so it gets dropped while the two earlier points survive.
+TEST(PyDetector, MaskFiltersKeypoints)
+{
+	const std::string scriptPath = writeStubScript(2);
+	std::unique_ptr<Feature2D> detector(Feature2D::create(
+			Feature2D::kFeaturePyDetector, baseParams(scriptPath)));
+	ASSERT_NE(detector.get(), nullptr);
+
+	cv::Mat image = makeImage(64, 64);
+	cv::Mat mask(image.size(), CV_8UC1, cv::Scalar(255));
+	mask(cv::Rect(33, 33, mask.cols - 33, mask.rows - 33)).setTo(0);
+	std::vector<cv::KeyPoint> kpts = detector->generateKeypoints(image, mask);
+	EXPECT_EQ(2u, kpts.size());
+
+	UFile::erase(scriptPath);
+}
+
+// Kp/MaxFeatures caps the returned keypoint list inside generateKeypointsImpl
+// (PyDetector calls limitKeypoints with its own descriptor matrix at the end).
+// The stub returns 3 keypoints; cap at 2 and verify the rest are dropped.
+TEST(PyDetector, MaxFeaturesCap)
+{
+	const std::string scriptPath = writeStubScript(3);
+	ParametersMap p = baseParams(scriptPath);
+	p[Parameters::kKpMaxFeatures()] = "2";
+	std::unique_ptr<Feature2D> detector(
+			Feature2D::create(Feature2D::kFeaturePyDetector, p));
+	ASSERT_NE(detector.get(), nullptr);
+
+	cv::Mat image = makeImage(64, 64);
+	std::vector<cv::KeyPoint> kpts = detector->generateKeypoints(image);
+	EXPECT_EQ(2u, kpts.size());
+
+	UFile::erase(scriptPath);
+}
+
+// Regression: a Python script returned non-empty (Nx3) keypoints but an
+// empty (0x0) descriptor array (observed with SuperPoint when its descriptor
+// head short-circuits). The old code wrote `UASSERT(nDesc = nKpts)` -- a
+// typo that assigned instead of compared -- and then silently produced
+// keypoints with no descriptors, tripping generateDescriptorsImpl's
+// `keypoints.size() == descriptors_.rows` assert downstream. Contract now:
+// detector logs and returns empty keypoints + empty descriptors.
+TEST(PyDetector, EmptyDescriptorsWithKeypoints)
+{
+	const std::string scriptPath = writeStubScriptEmptyDescriptors(1);
+	std::unique_ptr<Feature2D> detector(Feature2D::create(
+			Feature2D::kFeaturePyDetector, baseParams(scriptPath)));
+	ASSERT_NE(detector.get(), nullptr);
+
+	cv::Mat image = makeImage(64, 64);
+	std::vector<cv::KeyPoint> kpts = detector->generateKeypoints(image);
+	EXPECT_TRUE(kpts.empty());
+
+	cv::Mat descriptors = detector->generateDescriptors(image, kpts);
+	EXPECT_EQ(0, descriptors.rows);
+
+	UFile::erase(scriptPath);
+}
+
+// If the script returns mismatched row counts (e.g. 3 keypoints, 2
+// descriptors), the previous code would silently walk past the descriptor
+// buffer (UB read) using nDesc clobbered to nKpts. Now we detect the
+// mismatch and return empty.
+TEST(PyDetector, MismatchedKeypointAndDescriptorCounts)
+{
+	const std::string scriptPath = writeStubScriptMismatchedCounts(1);
+	std::unique_ptr<Feature2D> detector(Feature2D::create(
+			Feature2D::kFeaturePyDetector, baseParams(scriptPath)));
+	ASSERT_NE(detector.get(), nullptr);
+
+	cv::Mat image = makeImage(64, 64);
+	std::vector<cv::KeyPoint> kpts = detector->generateKeypoints(image);
+	EXPECT_TRUE(kpts.empty());
+
+	cv::Mat descriptors = detector->generateDescriptors(image, kpts);
+	EXPECT_EQ(0, descriptors.rows);
+}
+
+// A script that returns (0x3, 0x8) -- the polite "I found nothing" case.
+// Must not assert and must produce an empty result.
+TEST(PyDetector, BothArraysEmpty)
+{
+	const std::string scriptPath = writeStubScriptBothEmpty(1);
+	std::unique_ptr<Feature2D> detector(Feature2D::create(
+			Feature2D::kFeaturePyDetector, baseParams(scriptPath)));
+	ASSERT_NE(detector.get(), nullptr);
+
+	cv::Mat image = makeImage(64, 64);
+	std::vector<cv::KeyPoint> kpts = detector->generateKeypoints(image);
+	EXPECT_TRUE(kpts.empty());
+
+	cv::Mat descriptors = detector->generateDescriptors(image, kpts);
+	EXPECT_EQ(0, descriptors.rows);
+
+	UFile::erase(scriptPath);
+}
+
+// Full-zero mask drops every keypoint via keep_kpt. The keypoint loop pushes
+// nothing, but the descriptor loop still iterates over the python-returned
+// rows -- previously this could leave keypoints.size() != descriptors_.rows
+// if the keep_kpt logic and descriptor-read loop disagreed on what to skip.
+// Verify both stay empty.
+TEST(PyDetector, AllKeypointsMaskedOut)
+{
+	const std::string scriptPath = writeStubScript(4);
+	std::unique_ptr<Feature2D> detector(Feature2D::create(
+			Feature2D::kFeaturePyDetector, baseParams(scriptPath)));
+	ASSERT_NE(detector.get(), nullptr);
+
+	cv::Mat image = makeImage(64, 64);
+	cv::Mat mask(image.size(), CV_8UC1, cv::Scalar(0));
+	std::vector<cv::KeyPoint> kpts = detector->generateKeypoints(image, mask);
+	EXPECT_TRUE(kpts.empty());
+
+	cv::Mat descriptors = detector->generateDescriptors(image, kpts);
+	EXPECT_EQ(0, descriptors.rows);
+
+	UFile::erase(scriptPath);
+}
+
+#endif  // RTABMAP_PYTHON