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)

.github/actions/install-windows-cuda-deps/action.yml

@@ -26,7 +26,7 @@ runs:
       uses: actions/cache@v4
       with:
         path: ${{ runner.workspace }}/vcpkg_installed
-        key: ${{ runner.os }}-vcpkg-export-66c0373d-x64-vs2022-cuda130_v4
+        key: ${{ runner.os }}-vcpkg-export-66c0373d-x64-vs2022-cuda130_v5
 
     - name: Download and Install vcpkg
       if: steps.cache-vcpkg.outputs.cache-hit != 'true'

.github/actions/install-windows-deps/action.yml

@@ -13,7 +13,7 @@ runs:
       uses: actions/cache@v4
       with:
         path: ${{ runner.workspace }}/vcpkg_installed
-        key: ${{ runner.os }}-vcpkg-export-66c0373d-x64-vs2022-v6
+        key: ${{ runner.os }}-vcpkg-export-66c0373d-x64-vs2022-v7
 
     - name: Download and Install vcpkg
       if: steps.cache-vcpkg.outputs.cache-hit != 'true'

.github/workflows/cmake-linux.yml

@@ -19,6 +19,9 @@ jobs:
   build:
     name: ${{ matrix.build_name }}
     runs-on: ${{ matrix.os }}
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}-${{ matrix.build_name }}
+      cancel-in-progress: true
     strategy:
       fail-fast: true
       matrix:
@@ -44,6 +47,21 @@ jobs:
     steps:
     - uses: actions/checkout@v4
 
+    - name: Restore test data
+      id: cache-testdata
+      uses: actions/cache@v4
+      with:
+        # SQLite DBs are binary-portable -> share the cache across
+        # linux / macos / windows. Key omits runner.os on purpose so all
+        # three OSes hit the same entry.
+        path: data/tests/*.db
+        key: testdata-${{ hashFiles('data/tests/manifest.txt') }}
+
+    - name: Fetch test data
+      if: steps.cache-testdata.outputs.cache-hit != 'true'
+      shell: bash
+      run: bash scripts/fetch_test_data.sh
+
     - name: Install Linux Dependencies
       run: |
         DEBIAN_FRONTEND=noninteractive
@@ -72,9 +90,14 @@ jobs:
       run: |
         ./rtabmap-console --version
 
-#    - name: Test
-#      working-directory: ${{github.workspace}}/build
-#      # Execute tests defined by the CMake configuration.  
-#      # See https://cmake.org/cmake/help/latest/manual/ctest.1.html for more detail
-#      run: ctest -C ${{env.BUILD_TYPE}}
-      
+    - name: Test
+      working-directory: ${{github.workspace}}/build
+      # PYTHONNOUSERSITE=1: prevent the embedded Python interpreter from
+      # loading numpy / other site-packages from ~/.local that were compiled
+      # against a different ABI than the build-time Python (causes numpy
+      # 1.x/2.x mismatch crashes in test_pydetector / test_pydescriptor /
+      # test_pymatcher).
+      env:
+        PYTHONNOUSERSITE: 1
+      run: |
+        ctest -C ${{env.BUILD_TYPE}} --output-on-failure

.github/workflows/cmake-macos.yml

@@ -22,11 +22,12 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        build_name: [macos-sequoia-intel, macos-sequoia-apple-silicon, macos-tahoe-intel, macos-tahoe-apple-silicon, macos-tahoe-intel-cv5, macos-tahoe-apple-silicon-cv5]
+        build_name: [macos-sequoia-apple-silicon, macos-tahoe-intel, macos-tahoe-apple-silicon, macos-tahoe-intel-cv5, macos-tahoe-apple-silicon-cv5]
         include:
-        - build_name: macos-sequoia-intel
-          os: macos-15-intel
-          cv: opencv@4
+        # macos-sequoia-intel temporarily disabled. Had some g2o optimizer issues.
+        #- build_name: macos-sequoia-intel
+        #  os: macos-15-intel
+        #  cv: opencv@4
         - build_name: macos-sequoia-apple-silicon
           os: macos-15
           cv: opencv@4
@@ -45,6 +46,21 @@ jobs:
     steps:
     - uses: actions/checkout@v4
 
+    - name: Restore test data
+      id: cache-testdata
+      uses: actions/cache@v4
+      with:
+        # SQLite DBs are binary-portable -> share the cache across
+        # linux / macos / windows. Key omits runner.os on purpose so all
+        # three OSes hit the same entry.
+        path: data/tests/*.db
+        key: testdata-${{ hashFiles('data/tests/manifest.txt') }}
+
+    - name: Fetch test data
+      if: steps.cache-testdata.outputs.cache-hit != 'true'
+      shell: bash
+      run: bash scripts/fetch_test_data.sh
+
     - name: Install Brew Dependencies
       run: |
         # Update brew and install from Brewfile if present, or specific packages
@@ -66,6 +82,7 @@ jobs:
         LIBOMP=$(brew --prefix libomp)
         cmake -B ${{github.workspace}}/build \
           -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}} \
+          -DBUILD_TESTING=ON \
           -DBUILD_AS_BUNDLE=ON \
           -DWITH_ORBBEC_SDK=ON \
           -DWITH_DEPTHAI=ON \
@@ -98,9 +115,45 @@ jobs:
         if-no-files-found: warn
         retention-days: ${{ github.event_name == 'pull_request' && 1 || 90 }}
 
-#    - name: Test
-#      working-directory: ${{github.workspace}}/build
-#      # Execute tests defined by the CMake configuration.  
-#      # See https://cmake.org/cmake/help/latest/manual/ctest.1.html for more detail
-#      run: ctest -C ${{env.BUILD_TYPE}}
-      
+    - name: Test
+      working-directory: ${{github.workspace}}/build
+      # PYTHONNOUSERSITE=1: prevent the embedded Python interpreter from
+      # loading numpy / other site-packages from the user's site that were
+      # compiled against a different ABI than the build-time Python.
+      env:
+        PYTHONNOUSERSITE: 1
+      run: |
+        ctest -C ${{env.BUILD_TYPE}} --output-on-failure
+
+    # A ctest SEGFAULT is reported as just "SEGFAULT" with no backtrace, which
+    # makes a crash inside a long integration test invisible -- the log simply
+    # stops mid-test. macOS's ReportCrash writes a symbolized .ips report for
+    # every crashed process, so surface any that appeared during this job.
+    - name: Dump macOS crash reports on failure
+      if: failure()
+      run: |
+        # ReportCrash can lag the process death by a few seconds.
+        sleep 20
+        found=0
+        for d in "$HOME/Library/Logs/DiagnosticReports" /Library/Logs/DiagnosticReports; do
+          [ -d "$d" ] || continue
+          while IFS= read -r f; do
+            found=1
+            echo "::group::$f"
+            cat "$f"
+            echo "::endgroup::"
+          done < <(find "$d" -type f \( -name '*.ips' -o -name '*.crash' \) -mtime -1 2>/dev/null | sort)
+        done
+        if [ "$found" = 0 ]; then
+          echo "No crash reports found -- the job may have failed without a crash."
+        fi
+
+    - name: Upload ctest log on failure
+      if: failure()
+      uses: actions/upload-artifact@v4
+      with:
+        name: ctest-log-${{ matrix.build_name }}
+        path: build/Testing/Temporary/LastTest.log
+        if-no-files-found: warn
+        retention-days: 7
+

.github/workflows/cmake-ros.yml

@@ -19,6 +19,9 @@ jobs:
   build:
     name: ${{ matrix.ros_distribution }}
     runs-on: ubuntu-latest
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}-${{ matrix.ros_distribution }}
+      cancel-in-progress: true
     strategy:
       fail-fast: false
       matrix:
@@ -39,6 +42,45 @@ jobs:
       image: osrf/ros:${{ matrix.ros_distribution }}-desktop-full
     steps:
     - uses: actions/checkout@v4
+
+    - name: Restore test data
+      id: cache-testdata
+      uses: actions/cache@v4
+      with:
+        path: data/tests/*.db
+        key: testdata-${{ hashFiles('data/tests/manifest.txt') }}
+
+    - name: Fetch test data
+      if: steps.cache-testdata.outputs.cache-hit != 'true'
+      shell: bash
+      run: |
+        # The ROS images are slim; fetch_test_data.sh needs curl.
+        command -v curl >/dev/null || (apt-get update && apt-get install -y --no-install-recommends curl)
+        bash scripts/fetch_test_data.sh
+
+    # `${{ github.workspace }}` is expanded by the runner on the *host*
+    # (/home/runner/work/...), but this job runs in a container where the runner
+    # bind-mounts that directory somewhere else (/__w/...). Baking the host path
+    # into RTABMAP_TEST_DATA_ROOT points every data-driven test at a directory
+    # that does not exist in the container: the integration tests silently skip
+    # and the ones that imread() committed fixtures abort outright.
+    #
+    # Resolve the path inside the container instead. A `run` step's cwd is the
+    # checkout root -- the same assumption the relative `scripts/...` and
+    # `data/tests/*.db` paths in the steps above already rely on -- so derive it
+    # from $PWD rather than trusting a path computed outside the container. The
+    # existence checks then turn that into a verified precondition: a wrong
+    # mount point or a failed fetch fails here, with the path printed, instead
+    # of degrading into skipped tests.
+    - name: Resolve test data root in the container
+      id: testdata
+      shell: bash
+      run: |
+        root="$PWD/data"
+        test -f "$root/samples/17.jpg" || { echo "::error::test data root $root is missing committed fixtures"; exit 1; }
+        ls "$root"/tests/*.db >/dev/null || { echo "::error::no test databases in $root/tests"; exit 1; }
+        echo "root=$root" >> "$GITHUB_OUTPUT"
+
     - uses: ros-tooling/setup-ros@v0.7
       with:
         required-ros-distributions: ${{ matrix.ros_distribution }}
@@ -48,4 +90,5 @@ jobs:
         package-name: rtabmap
         target-ros2-distro: ${{ matrix.ros_distribution }}
         rosdep-skip-keys: "${{ matrix.skip_keys }}"
-      
+        coverage-result: false
+        extra-cmake-args: -DTEST_DATA_ROOT=${{ steps.testdata.outputs.root }}

.github/workflows/cmake-windows.yml

@@ -36,6 +36,22 @@ jobs:
     steps:
     - uses: actions/checkout@v4
 
+    - name: Restore test data
+      id: cache-testdata
+      if: matrix.build_name != 'windows-2022-cuda'
+      uses: actions/cache@v4
+      with:
+        # SQLite DBs are binary-portable -> share the cache across
+        # linux / macos / windows. Key omits runner.os on purpose so all
+        # three OSes hit the same entry.
+        path: data/tests/*.db
+        key: testdata-${{ hashFiles('data/tests/manifest.txt') }}
+
+    - name: Fetch test data
+      if: matrix.build_name != 'windows-2022-cuda' && steps.cache-testdata.outputs.cache-hit != 'true'
+      shell: bash
+      run: bash scripts/fetch_test_data.sh
+
     - name: Install Windows Dependencies
       if: matrix.build_name == 'windows-2022'
       uses: ./.github/actions/install-windows-deps
@@ -65,6 +81,7 @@ jobs:
           -DWITH_REALSENSE2=ON `
           -DWITH_CCCORELIB=ON `
           ${{ matrix.extra_cmake_def }} `
+          -DBUILD_TESTING=ON `
           -DVCPKG_MANIFEST_INSTALL=OFF `
           -DVCPKG_TARGET_TRIPLET=x64-windows-release `
           -DVCPKG_INSTALLED_DIR="${{env.VCPKG_EXPORT_PATH}}/installed" `
@@ -72,7 +89,42 @@ jobs:
           -DTorch_DIR=${{env.VCPKG_EXPORT_PATH}}/installed/x64-windows-release/tools/python3/Lib/site-packages/torch/share/cmake/Torch
 
     - name: Build
-      run: cmake --build ${{github.workspace}}/build --config ${{env.BUILD_TYPE}}
+      run: cmake --build ${{github.workspace}}/build --config ${{env.BUILD_TYPE}} --target ALL_BUILD
+
+    - name: Test
+      # Not run on the CUDA build, which is a build+package job only.
+      #
+      # The runner has no NVIDIA GPU or driver (see the driver-DLL note in
+      # app/src/CMakeLists.txt), so no cv::cuda / CUDASIFT path can actually
+      # execute there -- everything falls back to CPU and the run just repeats
+      # the coverage the non-CUDA job already gives, on the same sources. It
+      # used to cost more than it returned: the two cv::cuda-touching tests
+      # (test_util3d_features, test_localgrid) had to be excluded because lazy
+      # CUDA-init stalled them past the 300 s timeout, and once WITH_ZED=ON was
+      # added to this job every remaining corelib test died in the loader with
+      # 0xc0000135 (STATUS_DLL_NOT_FOUND) before reaching main(): rtabmap_core
+      # links sl_zed64.dll, which imports the driver-only nvcuvid.dll /
+      # nvEncodeAPI64.dll that a driver-less runner does not have.
+      #
+      # So this job compiles, links and packages the CUDA artifact; the
+      # non-CUDA job is what verifies behaviour. Same reason the Info step
+      # below is skipped here.
+      if: matrix.build_name != 'windows-2022-cuda'
+      working-directory: ${{github.workspace}}/build
+      # PYTHONHOME points the embedded interpreter at vcpkg's bundled
+      # Python install (where Lib/, DLLs/ live). Without it Python emits
+      # "Could not find platform independent libraries <prefix>" at init
+      # and runs without a stdlib, breaking every numpy import.
+      # PYTHONNOUSERSITE=1: prevent the embedded Python interpreter from
+      # loading numpy / other site-packages from %APPDATA%\Python that
+      # were compiled against a different ABI than the build-time Python
+      # (numpy 1.x/2.x mismatch crashes in test_pydetector /
+      # test_pydescriptor / test_pymatcher).
+      env:
+        PYTHONHOME: ${{env.VCPKG_EXPORT_PATH}}/installed/x64-windows-release/tools/python3
+        PYTHONNOUSERSITE: 1
+      run: |
+        ctest -C ${{env.BUILD_TYPE}} --output-on-failure --timeout 300
 
     - name: Info
       # Skipped for CUDA: the binary links ZED (sl_zed64.dll -> nvcuvid/nvEncodeAPI64),
@@ -116,10 +168,3 @@ jobs:
         compression-level: 0
         if-no-files-found: warn
         retention-days: ${{ github.event_name == 'pull_request' && 1 || 90 }}
-
-#    - name: Test
-#      working-directory: ${{github.workspace}}/build
-#      # Execute tests defined by the CMake configuration.  
-#      # See https://cmake.org/cmake/help/latest/manual/ctest.1.html for more detail
-#      run: ctest -C ${{env.BUILD_TYPE}}
-      

.github/workflows/coverage.yml

@@ -0,0 +1,125 @@
+name: Coverage
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches: 
+      - '**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+  id-token: write
+
+env:
+  BUILD_TYPE: Debug
+
+jobs:
+  coverage:
+    name: Coverage (ubuntu-24.04)
+    runs-on: ubuntu-24.04
+    env:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Linux dependencies
+        run: |
+          DEBIAN_FRONTEND=noninteractive
+          sudo apt-get update
+          sudo apt-get install -y \
+            lcov \
+            libopencv-dev \
+            libpcl-dev \
+            git \
+            cmake \
+            software-properties-common \
+            libyaml-cpp-dev
+
+      - name: Configure CMake
+        run: |
+          cmake -B ${{ github.workspace }}/build \
+            -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} \
+            -DENABLE_COVERAGE=ON \
+            -DBUILD_TESTING=ON \
+            -DBUILD_APP=OFF \
+            -DBUILD_TOOLS=OFF \
+            -DBUILD_EXAMPLES=OFF \
+            -DWITH_QT=OFF \
+            -DWITH_PYTHON=OFF \
+            -DWITH_CERES=OFF \
+            -DWITH_G2O=OFF \
+            -DWITH_GTSAM=OFF \
+            -DWITH_MRPT=OFF \
+            -DWITH_VERTIGO=OFF \
+            -DWITH_CVSBA=OFF \
+            -DWITH_POINTMATCHER=OFF \
+            -DWITH_CCCORELIB=OFF \
+            -DWITH_OPEN3D=OFF \
+            -DWITH_LOAM=OFF \
+            -DWITH_FLOAM=OFF \
+            -DWITH_LIOSAM=OFF \
+            -DWITH_FLYCAPTURE2=OFF \
+            -DWITH_ZED=OFF \
+            -DWITH_ZEDOC=OFF \
+            -DWITH_REALSENSE=OFF
+
+      - name: Build
+        run: cmake --build ${{ github.workspace }}/build -j$(nproc)
+
+      - name: Test
+        working-directory: ${{ github.workspace }}/build
+        run: |
+          export LD_LIBRARY_PATH="${{ github.workspace }}/build/bin${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
+          find ${{ github.workspace }}/build -name '*.gcda' -delete
+          ctest --output-on-failure
+
+      - name: Generate LCOV report
+        run: |
+          GCOV_VER="$(gcc -dumpversion | cut -d. -f1)"
+          if command -v "gcov-${GCOV_VER}" >/dev/null 2>&1; then
+            GCOV_TOOL="gcov-${GCOV_VER}"
+          else
+            GCOV_TOOL="gcov"
+          fi
+          LCOV_IGNORE=(--ignore-errors gcov,source,graph,mismatch,unused)
+
+          lcov --gcov-tool "$GCOV_TOOL" "${LCOV_IGNORE[@]}" \
+            --capture \
+            --directory ${{ github.workspace }}/build/corelib/src \
+            --directory ${{ github.workspace }}/build/utilite/src \
+            --output-file lcov.info
+
+          lcov "${LCOV_IGNORE[@]}" --extract lcov.info \
+            '${{ github.workspace }}/*' \
+            --output-file lcov.info
+          lcov "${LCOV_IGNORE[@]}" --remove lcov.info \
+            '*/sqlite3/*' \
+            '*/rtflann/*' \
+            --output-file lcov.info
+
+          lcov --summary lcov.info
+
+      - name: HTML coverage report
+        run: genhtml --ignore-errors source,mismatch lcov.info --output-directory coverage-html --legend --demangle-cpp
+
+      - name: Upload HTML coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-html
+          path: coverage-html
+          retention-days: 14
+
+      - name: Upload to Codecov
+        if: ${{ env.CODECOV_TOKEN != '' }}
+        uses: codecov/codecov-action@v5
+        with:
+          files: lcov.info
+          token: ${{ env.CODECOV_TOKEN }}
+          fail_ci_if_error: false

.github/workflows/docs-preview-cleanup.yml

@@ -0,0 +1,54 @@
+name: Documentation preview cleanup
+
+# Removes the per-PR documentation preview published by docs.yml under
+# gh-pages:preview/pr-<number>/ once the pull request is closed (merged or not).
+#
+# Deliberately has no `paths` filter: docs.yml only publishes a preview when
+# documentation-related files changed, but this must fire for every close so a
+# preview can never be orphaned on the branch.
+on:
+  pull_request:
+    types: [closed]
+
+permissions:
+  contents: read
+
+jobs:
+  cleanup:
+    name: Remove PR preview
+    # Forks never get a preview (their token is read-only), so nothing to clean.
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-24.04
+
+    # Same group as docs.yml's publish job: both push to gh-pages, and two
+    # concurrent pushes would collide.
+    concurrency:
+      group: gh-pages-publish
+      cancel-in-progress: false
+
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout gh-pages
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+          fetch-depth: 1
+
+      - name: Remove preview directory
+        env:
+          PREVIEW_DIR: preview/pr-${{ github.event.number }}
+        run: |
+          set -eux
+          if [[ ! -d "${PREVIEW_DIR}" ]]; then
+            echo "No preview at ${PREVIEW_DIR}, nothing to do."
+            exit 0
+          fi
+          git config user.name 'github-actions[bot]'
+          git config user.email 'github-actions[bot]@users.noreply.github.com'
+          git rm -r --quiet "${PREVIEW_DIR}"
+          # Drop the parent too once the last preview is gone.
+          rmdir preview 2>/dev/null || true
+          git commit -m "Remove preview for PR #${{ github.event.number }}"
+          git push

.github/workflows/docs.yml

@@ -0,0 +1,211 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master
+    tags:
+      - '*'
+    # Publishing commits to the gh-pages branch, so only run when something that
+    # affects the documentation actually changed. Use the manual "Run workflow"
+    # button if a deploy is needed outside of these paths.
+    paths: &docs_paths
+      - '.github/workflows/docs.yml'
+      - 'CMakeLists.txt'
+      - 'Doxyfile.in'
+      - 'docs-report.sh'
+      - 'website/**'
+      - 'doxygen/**'
+      - 'package.xml'
+      - 'corelib/include/**'
+      - 'utilite/include/**'
+  pull_request:
+    branches:
+      - '**'
+    paths: *docs_paths
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build site (ubuntu-24.04)
+    runs-on: ubuntu-24.04
+
+    outputs:
+      version: ${{ steps.site.outputs.version }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          DEBIAN_FRONTEND=noninteractive
+          sudo apt-get update
+          sudo apt-get install -y \
+            doxygen \
+            graphviz \
+            cmake \
+            libopencv-dev \
+            libpcl-dev \
+            libyaml-cpp-dev \
+            git
+
+      # Configures build-docs (CMake generates the export headers that are part
+      # of Doxygen's INPUT), runs Doxygen into build-docs/api/latest/. Same
+      # script used locally, so a local preview matches what gets published.
+      - name: Generate C++ API documentation (Doxygen)
+        run: ./docs-report.sh
+
+      # The theme emits absolute asset links built from site.baseurl, which
+      # GitHub's own Jekyll infers from the repository (/rtabmap). A PR preview
+      # is served from a deeper path, so those links would 404 there. Pin
+      # baseurl to the path this particular build gets published to.
+      - name: Set Jekyll baseurl
+        run: |
+          set -eux
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            baseurl="/${{ github.event.repository.name }}/preview/pr-${{ github.event.number }}"
+          else
+            baseurl="/${{ github.event.repository.name }}"
+          fi
+          echo "baseurl: ${baseurl}" >> website/_config.yml
+
+      # Landing page: built here rather than by GitHub's own Jekyll, so that
+      # .nojekyll can be set below and the Doxygen output is served untouched.
+      - name: Build landing page (Jekyll)
+        uses: actions/jekyll-build-pages@v1
+        with:
+          source: ./website
+          destination: ./_site
+
+      - name: Assemble site
+        id: site
+        run: |
+          set -eux
+          # jekyll-build-pages is a container action running as root, so _site
+          # comes back owned by root and the steps below (running as the runner
+          # user) cannot write into it.
+          sudo chown -R "$(id -u):$(id -g)" _site
+
+          # Serve everything verbatim: the site is already built, and Jekyll
+          # would otherwise skip Doxygen files/folders starting with '_'.
+          touch _site/.nojekyll
+
+          mkdir -p _site/api
+          cp -r build-docs/api/latest _site/api/latest
+
+          # On a release tag (plain X.Y.Z, not the ROS-distro variants such as
+          # 0.23.7-jazzy), also publish under the version number. Older versions
+          # already on the branch are preserved by keep_files when publishing.
+          version=""
+          if [[ "${GITHUB_REF_TYPE}" == "tag" && "${GITHUB_REF_NAME}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            version="${GITHUB_REF_NAME}"
+            cp -r build-docs/api/latest "_site/api/${version}"
+          fi
+          echo "version=${version}" >> "$GITHUB_OUTPUT"
+
+          # The dropdown list is maintained by hand in the repository (one entry
+          # per release) and shared by every published version -- see the header
+          # comment in doxygen/versions.js.
+          cp doxygen/versions.js _site/api/versions.js
+
+          # /api/ has no content of its own: send it to the current docs so a
+          # bare .../api/ link lands somewhere useful instead of a 404. The
+          # target is relative, so it works at the site root and under a
+          # preview prefix alike.
+          printf '%s\n' \
+            '<!doctype html>' \
+            '<meta charset="utf-8">' \
+            '<title>RTAB-Map API documentation</title>' \
+            '<meta http-equiv="refresh" content="0; url=latest/">' \
+            '<link rel="canonical" href="latest/">' \
+            '<p>Redirecting to the <a href="latest/">latest API documentation</a>.</p>' \
+            > _site/api/index.html
+
+          test -f _site/index.html
+          test -f _site/api/index.html
+          test -f _site/api/latest/index.html
+
+      - name: Upload site artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: documentation-site
+          path: _site
+          # include-hidden-files keeps .nojekyll, which the publish job needs.
+          include-hidden-files: true
+          retention-days: 14
+
+  publish:
+    name: Publish to gh-pages
+    needs: build
+    # Forks are skipped for pull requests: their GITHUB_TOKEN is read-only, and
+    # granting write access to a workflow that builds untrusted code would be a
+    # security hole.
+    if: >-
+      github.event_name != 'pull_request' ||
+      github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-24.04
+
+    # Serialize every push to gh-pages, including the preview cleanup workflow,
+    # and never cancel one in flight: two concurrent pushes would collide.
+    concurrency:
+      group: gh-pages-publish
+      cancel-in-progress: false
+
+    permissions:
+      contents: write
+
+    steps:
+      - name: Download site
+        uses: actions/download-artifact@v4
+        with:
+          name: documentation-site
+          path: _site
+
+      # Pull requests go to preview/pr-<number>/, everything else to the site
+      # root. keep_files preserves what this run does not carry: the published
+      # version folders (api/0.23.x/) and the other PRs' previews.
+      - name: Publish
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
+          publish_dir: ./_site
+          destination_dir: ${{ github.event_name == 'pull_request' && format('preview/pr-{0}', github.event.number) || '' }}
+          keep_files: true
+          # Do not let the action drop a .nojekyll at the *branch root*: that
+          # disables Jekyll for everything on the branch, including content
+          # published outside this deployment. The site we publish carries its
+          # own .nojekyll inside destination_dir, which is the only place it
+          # should apply.
+          enable_jekyll: true
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'
+          commit_message: >-
+            ${{ github.event_name == 'pull_request'
+                && format('Preview for PR #{0}', github.event.number)
+                || format('Update documentation ({0})', needs.build.outputs.version || 'latest') }}
+
+      - name: Link the site
+        run: |
+          base="https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}"
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            url="${base}/preview/pr-${{ github.event.number }}"
+            note="Removed automatically when this pull request is closed."
+          else
+            url="${base}"
+            note=""
+          fi
+          {
+            echo "### Documentation"
+            echo ""
+            echo "- Landing page: ${url}/"
+            echo "- C++ API: ${url}/api/latest/"
+            [[ -n "${note}" ]] && { echo ""; echo "${note}"; }
+          } >> "$GITHUB_STEP_SUMMARY"