MapsHD · JanuszBedkowski · Aug 10, 2026 · Aug 10, 2026 · Aug 10, 2026 · Aug 10, 2026
diff --git a/README.md b/README.md
diff --git a/documentation/Applications/README.md b/documentation/Applications/README.md
@@ -0,0 +1,40 @@
+# Possible applications:
+- caving
+- speleology
+- surveying
+- culture heritage
+- environmental management
+- geology
+- urban search and rescue
+- urban mapping
+- ground truth for AGV (Automated Guided Vehicle)
+- mobile robot navigation
+- precision forestry
+- agricultural robotics
+- underground mining
+- education
+- entertainment
+- forensics
+- critical infrastructure inspection
+- space exploration
+- protection systems
+- digital twin content generation
+- automation in construction
+- etc...
+
+![largescalemapping1](images/100-2.gif)
+City level survey (perspective view).
+![largescalemapping2](images/100.gif)
+City level survey (top view).
+
+![largescalemapping1](images/a.jpg)
+3D data from aerial LiDAR mapping.
+![largescalemapping2](images/b.jpg)
+Aerial LiDAR fused with ground MANDEYE data (fixed issue with missing elevations).
+
+![largescalemapping1](images/a0.jpg)
+Construction site.
+![largescalemapping2](images/a6.jpg)
+Construction site augmented with MANDEYE 3D data.
+![largescalemapping2](images/change.jpg)
+Construction progress monitoring, scale blue - smallest changes, red - largest changes.
diff --git a/documentation/Benchmarks/LIDAR_BA/README.md b/documentation/Benchmarks/LIDAR_BA/README.md
diff --git a/documentation/Benchmarks/LIO/README.md b/documentation/Benchmarks/LIO/README.md
diff --git a/documentation/Benchmarks/LOOP_CLOSURE/README.md b/documentation/Benchmarks/LOOP_CLOSURE/README.md
@@ -0,0 +1,12 @@
+# Automatic loop closure
+
+We provide easy tool that will help You annotating ground truth SLAM loop closures. You mark pair of point clouds that forms edge, then use ICP like pair wise registration to generatie ground truth for AI training.
+Annotated ground truth edges for LiDAR pose graph slam are available at [ground truth edges](https://zenodo.org/records/18527593).
+Movie how to use it is available at [prepare training dataset movie](https://youtu.be/LOGpVg1Nc3k).
+
+[![GROUND-TRUTH-EDGE-ANNOTATION-TOOL](https://img.youtube.com/vi/tJdNNfBubeM/default.jpg)](https://youtu.be/tJdNNfBubeM)
+[![MANUAL-LOOP_CLOSURE-TOOL](https://img.youtube.com/vi/6SNvrZ2ROKg/default.jpg)](https://youtu.be/6SNvrZ2ROKg)
+
+## loop closure benchmark [https://github.com/MapsHD/benchmark-HDMapping-AILoopClosure-Orchestration](https://github.com/MapsHD/benchmark-HDMapping-AILoopClosure-Orchestration)
+- [1] https://github.com/MapsHD/benchmark-HDMapping-AILoopClosure-LCR-Net (in progress)
+- [2] https://github.com/MapsHD/benchmark-HDMapping-AILoopClosure-TransLO (in progress)
diff --git a/documentation/Benchmarks/README.md b/documentation/Benchmarks/README.md
diff --git a/documentation/CompatibleCommunityProjects/README.md b/documentation/CompatibleCommunityProjects/README.md
@@ -0,0 +1,4 @@
+# Compatible community projects
+
+- Handheld Setup for Recording with Mid360 Lidar and Camera https://github.com/RomanStadlhuber/livo-handheld
+- Lidar odometry for HDMapping project utilizing KISS-ICP https://github.com/michalpelka/kiss-lidarodometry
diff --git a/documentation/HARDWARE/README.md b/documentation/HARDWARE/README.md
@@ -0,0 +1,32 @@
+# Supported LiDARs
+
+![lidars](images/IMG_2561.jpeg)
+We support LIVOX AVIA, HAP, MID360, Ouster OS0, OS1, OS2, OSDome, SICK multiScan100, HESAI JT16, HESAI JT128, HESAI XT, Robosense AIRY.
+HESAI XT requires external IMU. We are going to support more LiDARs ASAP.
+
+More information can be found here:
+
+- The introductory paper is available here: https://www.sciencedirect.com/science/article/pii/S235271102300314X
+- Sample data is available at https://github.com/MapsHD/OmniWarsawDataset
+- VIDEO (how to build mobile mapping hardware) https://www.youtube.com/watch?v=BXBbuSJMFEo
+- If you are a ROS user, please visit https://github.com/MapsHD/mandeye_to_bag to convert MANDEYE data to ROSBAG
+- ROS2 wrapper for HDMapping LiDAR Inertial Odometry (HDMapping-LIO) https://github.com/MapsHD/HDMapping-LIO
+- ROSCON 2024 workshop (sample data sets and more ...): https://michalpelka.github.io/RosCon2024_workshop/
+- You can use it also for multi-view Terrestrial Laser Scanner Registration (Faro, Leica, Z+F, Riegl, etc...) https://www.sciencedirect.com/science/article/abs/pii/S0263224123007637
+- Info for Windows users: please use the latest release https://github.com/MapsHD/HDMapping/releases
+- Contact email: januszbedkowski@gmail.com
+
+
+![mandeye](images/softwareX1.png)
+
+Mobile mapping systems is based on LiVOX MID360 - laser scanner with non repetetive scanning pattern.
+Specification is available at https://www.livoxtech.com/mid-360/specs. Important parameters:
+
+- weight: less than 1kg,
+- battery life: up to 5 hours,
+- suggested speed during data acquisition: walking speed (4km/h),
+- LiDAR type: Livox MID360,
+- LiDAR non-repetitive scanning pattern,
+- LiDAR range 40m @ 10\% reflectivity, 70 m @ 80\% reflectivity,
+- Range Precision (1 $\sigma$): up to 2cm (@ 10m),
+- Integrated IMU (Inertial Measurement Unit).
diff --git a/documentation/InstallationGuide/README.md b/documentation/InstallationGuide/README.md
@@ -0,0 +1,165 @@
+## Quick Start (Ubuntu / Ubuntu 24.04 @ WSL2)
+
+### CMake 4.0.0 or Higher
+
+This project requires **CMake 4.0.0** or higher. If you don't have it installed, you can download it from:
+
+**Official CMake Downloads:**
+
+- **Linux/macOS/Windows:** https://cmake.org/download/
+- **GitHub Releases (Linux binaries):** https://github.com/Kitware/CMake/releases/tag/v4.0.0
+
+**Installation on Linux:**
+
+```bash
+wget https://github.com/Kitware/CMake/releases/download/v4.0.0/cmake-4.0.0-linux-x86_64.sh
+sudo sh cmake-4.0.0-linux-x86_64.sh --skip-license --prefix=/usr/local
+cmake --version
+```
+
+```bash
+git clone --recursive https://github.com/MapsHD/HDMapping.git
+cd HDMapping
+./ubuntu-24.04-apt-requirements.sh
+
+# Auto-optimized build (detects your CPU automatically)
+cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
+cmake --build build --config Release -j
+```
+
+**Laptops with hybrid NVIDIA/Intel graphics:** the raylib-based apps (e.g. `multi_view_tls_registration_step_2`) may default to the integrated GPU even with `prime-select nvidia` set, since PRIME's on-demand/offload mode is a per-launch choice, not a system default. Force the discrete NVIDIA GPU with:
+
+```bash
+__NV_PRIME_RENDER_OFFLOAD=1 __GLX_VENDOR_LIBRARY_NAME=nvidia ./build/bin/multi_view_tls_registration_step_2
+```
+
+If the `nvidia-prime` package is installed, `prime-run` wraps the same env vars:
+
+```bash
+prime-run ./build/bin/multi_view_tls_registration_step_2
+```
+
+## Quick Start (macOS)
+
+**Prerequisites:**
+
+1. Install **XCode Command Line Tools**: `xcode-select --install`
+2. Install **Homebrew** from [brew.sh](https://brew.sh)
+3. Install dependencies:
+
+```bash
+brew install cmake opencv
+```
+
+**Build:**
+
+```bash
+git clone --recursive https://github.com/MapsHD/HDMapping.git
+cd HDMapping
+
+# Configure with Cocoa support (native macOS windowing)
+cmake -B build -S . -DCMAKE_BUILD_TYPE=Release -DFREEGLUT_COCOA=ON
+
+# Build (auto-detects number of cores)
+cmake --build build -j$(sysctl -n hw.ncpu)
+```
+
+# Building commands
+
+## Requirements
+
+**Installation on Windows:**
+
+- Download the installer from https://cmake.org/download/
+- Run the installer and follow the instructions
+- Ensure CMake is added to your system PATH
+
+### clang-format
+
+**Instalation on Linux:**
+
+```bash
+sudo apt install clang-format
+```
+
+**Installation on Windows**
+
+1. Go to offical llvm-project GitHub [releases page](https://github.com/llvm/llvm-project/releases)
+2. Download Windows x64 installer (for example version [21.1.8](https://github.com/llvm/llvm-project/releases/download/llvmorg-21.1.8/LLVM-21.1.8-win64.exe)) - browser might flag exe file malware in that case mark it as "Keep it"
+3. Run installer exe
+4. In installation program mark "Add LLVM to the system PATH for all users" or "Add LLVM to the system PATH for all current user"
+5. Restart any terminal or IDE that you want to use clang-format in so it reloads paths from ENV
+
+**Verification**
+
+To verify that clang-format is installed run:
+Verify installation by running:
+
+```bash
+clang-format --version
+```
+
+**Formating codebase**
+
+In order to format code base run:
+
+```bash
+python3 run_clang_fromat.py
+```
+
+_Note that PRs without formatting might be rejected from merging_
+
+## Quick Start (Windows)
+
+```bash
+git clone --recursive https://github.com/MapsHD/HDMapping.git
+cd HDMapping
+
+# Auto-optimized build (detects your CPU automatically)
+cmake  -B build -S . -DCMAKE_BUILD_TYPE=Release
+cmake --build build --config Release
+```
+
+## WSL2 GUI
+
+On WSL2 to enable file dialogs in GUI applications you need to install one of the packages used by portable-file-dialogs listed [here](https://github.com/samhocevar/portable-file-dialogs/blob/c12ea8c9a727f5320a2b4570aee863bbede2a204/portable-file-dialogs.h#L539C1-L542C57).
+
+For example on WSL2 Ubuntu-24.04 following package is required to run GUI applications:
+
+```bash
+sudo apt install zenity
+```
+# Profiling
+
+You can use multiple backends to profile the code (UTL, Tracy-Profiler)
+
+- Using Tracy-Profiler requires to install / build from source Tracy-Profiler from https://github.com/wolfpld/tracy/releases/tag/v0.13.1.
+- Build and run the project with `cmake .. -DCMAKE_BUILD_TYPE=ReleaseWithDebInfo -DHDMAPPING_PROFILER=TRACY`
+- Open Tracy Profiler and run e.g. `lidar_odometry_step_1`. Tracy-Profiler should recongnize the code and show the results.
+- 
+To use UTL profiler build and run the project with `cmake .. -DCMAKE_BUILD_TYPE=ReleaseWithDebInfo -DHDMAPPING_PROFILER=UTL`
+
+# Building Debian package.
+
+The standard build contains all necessary libraries compiled with project.
+This approach allows smooth build on Windows platform and guarantee predictable experience.
+If you want to build Debian package, you can depends on system-provided libraries:
+Before build install 3rd party libraries:
+
+```
+sudo apt-get install freeglut3-dev libeigen3-dev liblaszip-dev libopencv-dev
+```
+
+Next build Debian package:
+
+```
+cmake .. -DBUILD_WITH_BUNDLED_FREEGLUT=0 -DBUILD_WITH_BUNDLED_EIGEN=0 -DBUILD_WITH_BUNDLED_LIBLASZIP=0 -DCMAKE_BUILD_TYPE=Release
+make -j16
+make package
+```
+
+To install package :
+
+```
+sudo dpkg -i hd_mapping-0.*.*-Linux.deb
+```
diff --git a/documentation/KnowledgeBase/README.md b/documentation/KnowledgeBase/README.md
@@ -0,0 +1,26 @@
+# Knowledge base (accuracy, precision, benchmarks, comparison to other mobile mapping systems, etc.)
+- Cosme Hernanz-Gilbert, Carlos Cabo, Álvaro Moreno-Martínez, and Mónica Herrero-Huerta, "Exploring the Potential of the MandEye Handheld LiDAR System for Mediterranean Understorey Characterisation", [[PDF]](https://isprs-archives.copernicus.org/articles/XLIX-B2-2026/413/2026/)
+- Wang, Z., Trybała, P., Wieser, A., and Remondino, F.: MultiChange3D: A Multi-Scene, Multi-Sensor Dataset for Benchmarking 3D Geometric Change Detection (2026, ISPRS Ann. Photogramm. Remote Sens. Spatial Inf. Sci., [[PDF]](https://isprs-annals.copernicus.org/articles/XI-2-2026/639/2026/index.html), [[BIB]](https://github.com/MapsHD/HDMapping/blob/main/bib/isprs-annals-XI-2-2026-639-2026.bib))
+- Janusz Będkowski et al., "MapsHD: A benchmark suite for LiDAR odometry frameworks", SoftwareX Volume 35, September 2026, 102822 (2026, SoftwareX, [[PDF]](https://www.sciencedirect.com/science/article/pii/S2352711026003146), [[BIB]](https://github.com/MapsHD/HDMapping/blob/main/bib/SoftwareX2026.bib))
+- Janusz Będkowski et al., "Wearable Mobile Mapping System for Cave Surveying - Part 1 (3-6)", CREG Journal (ISSN 1361-4800), 134, (2026, CREG Journal, [[PDF]](https://bcra.org.uk/pub/docs/downloads.html?f=j134003), [[BIB]](https://github.com/MapsHD/HDMapping/blob/main/bib/Creg2026.bib))
+- Jozef Výbošťok et al., "Low-cost mobile laser scanning for urban tree assessment: accuracy evaluation and application potential", ([[PDF]](https://www.frontiersin.org/journals/remote-sensing/articles/10.3389/frsen.2026.1774149/full))
+- Janusz Będkowski et al., "Comprehensive solution for georeferencing of humanitarian demining tools" ([[PDF]](https://dial.uclouvain.be/pr/boreal/object/boreal%3A313158/datastream/PDF_01/view#page=49))
+- Andro Kokeza et al. "Comparative Performance of Handheld Personal Laser Scanning Instruments and Operator Experience in Forest Inventory of Even-Aged European Beech Stand"(2026, MDPI-Forests, [[PDF]](https://www.mdpi.com/1999-4907/17/2/216) [[BIB]](https://github.com/MapsHD/HDMapping/blob/main/bib/forests-v17-i02_20260213.bib))
+- Janusz Będkowski et al., "The benchmark of LiDAR odometry algorithms utilised for a low-cost mobile mapping system" (2025, GEOBENCH, [[PDF]](https://isprs-archives.copernicus.org/articles/XLVIII-1-W6-2025/25/2025/isprs-archives-XLVIII-1-W6-2025-25-2025.pdf) [[BIB]](https://github.com/MapsHD/HDMapping/blob/main/bib/isprs-archives-XLVIII-1-W6-2025-25-2025.bib))
+- Jozef Výbošťok et al.. "An Open and Novel Low-Cost Terrestrial Laser Scanner Prototype for Forest Monitoring" (2025, MDPI-Sensors, [[PDF]](https://www.mdpi.com/1424-8220/26/1/63), [[BIB]](https://github.com/MapsHD/HDMapping/blob/main/bib/sensors-v26-i01_20260104.bib))
+- Samuele Facenda et al. 3D Robotics and LMM for Vineyard Inspection [[PDF]](https://isprs-archives.copernicus.org/articles/XLVIII-G-2025/431/2025/isprs-archives-XLVIII-G-2025-431-2025.pdf)
+- Janusz Będkowski et al., "Acquisition and digitization of large scale heritage scenes with open source project https://github.com/MapsHD/HDMapping" (2025, DIGITAL HERITAGE, [[PDF]](https://diglib.eg.org/items/5ce9eb81-e04f-4e58-a0c8-4e66c4ae6960), [[BIB]](https://github.com/MapsHD/HDMapping/blob/main/bib/dh.bib))
+- Jozef Výbošťok et al., "An Open and Low-Cost Terrestrial Laser Scanner Prototype: Delivering Reliable Accuracy for Forest Practice on a Budget" (2025, SSRN, [[PDF]](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=5386703))
+- Janusz Będkowski et al., "Affordable air-ground mobile mapping system for precise forestry applications" (2025, EuroCOW, [[PDF]](https://isprs-archives.copernicus.org/articles/XLVIII-1-W4-2025/5/2025/isprs-archives-XLVIII-1-W4-2025-5-2025.pdf), [[BIB]](https://github.com/MapsHD/HDMapping/blob/main/bib/isprs-archives-XLVIII-1-W4-2025-5-2025.bib))
+- Janusz Będkowski et al., "Method for spherical camera to 3D LiDAR calibration and synchronization with example on Insta360 X4 and LiVOX MID 360" (2025, EuroCOW, [[PDF]](https://isprs-archives.copernicus.org/articles/XLVIII-1-W4-2025/13/2025/isprs-archives-XLVIII-1-W4-2025-13-2025.pdf), [[BIB]](https://github.com/MapsHD/HDMapping/blob/main/bib/isprs-archives-XLVIII-1-W4-2025-13-2025.bib))
+- Janusz Będkowski, "Novel wearable mobile mapping system for Forensic and Security, mountable on trained dogs and humans" (2025, TechRxiv, [[PDF]](https://www.techrxiv.org/users/915148/articles/1288112-novel-wearable-mobile-mapping-system-for-forensic-and-security-mountable-on-trained-dog-and-human), [[BIB]](https://github.com/MapsHD/HDMapping/blob/main/bib/citation.bib))
+- Aguilar Fernando J., et al., "Preliminary Results of a Low-Cost Portable Terrestrial LiDAR Based on ICP-SLAM Algorithms. Application to Automatic Forest Digital Inventory" (2024, EMCEI, [[PDF]](https://www.ibles.pl/wp-content/uploads/2024/06/Torana-Arya.pdf))
+- Janusz Będkowski, Affordable geo-localisation of humanitarian demining tools (mountable on K9, robot, hand-held device, etc.) in GNSS-denied environment, (2024, HCR-CTRO [[PDF]](https://www.ctro.hr/userfiles/files/Affordable%20geo-localisation%20in%20GNSS%20denied%20environment%2C%20Janusz%20B%C4%99dkowski.pdf))
+- Janusz Będkowski, "Benchmark of multi-view Terrestrial Laser Scanning Point Cloud data registration algorithms." (2023, Elsevier-Measurement, [[PDF]](https://www.sciencedirect.com/science/article/abs/pii/S0263224123007637), [[BIB]](https://github.com/MapsHD/HDMapping/blob/main/bib/S0263224123007637.bib))
+- Biloš Josip, "3D mobilno kartiranje pomoću MandEye sustava prikupljanja i obrade prostornih podataka" (2024, [[PDF]](https://repozitorij.geof.unizg.hr/islandora/object/geof%3A142/datastream/PDF/view))
+- Janusz Będkowski et al., "Novel (re-configurable, wearable, lightweight, ergonomic) low cost 3D mobile mapping system not only for extreme mapping applications." (2024, LowCost 3D, [[PDF]](https://isprs-archives.copernicus.org/articles/XLVIII-2-W8-2024/25/2024/isprs-archives-XLVIII-2-W8-2024-25-2024.pdf), [[BIB]](https://github.com/MapsHD/HDMapping/blob/main/bib/isprs-archives-XLVIII-2-W8-2024-25-2024.bib))
+- Balestra Mattia, et al., "Advancing forest inventory: a comparative study of low-cost MLS lidar device with professional laser scanners." (2024, LowCost 3D, [[PDF]](https://isprs-archives.copernicus.org/articles/XLVIII-2-W8-2024/9/2024/isprs-archives-XLVIII-2-W8-2024-9-2024.pdf), [[BIB]](https://github.com/MapsHD/HDMapping/blob/main/bib/isprs-archives-XLVIII-2-W8-2024-9-2024.bib))
+- Elalailyi, Ahmad, et al., "Pose Graph Data Fusion for Visual-and LiDAR-based Low-Cost Portable Mapping Systems." (2024, LowCost 3D, [[PDF]](https://isprs-archives.copernicus.org/articles/XLVIII-2-W8-2024/147/2024/isprs-archives-XLVIII-2-W8-2024-147-2024.pdf), [[BIB]](https://github.com/MapsHD/HDMapping/blob/main/bib/isprs-archives-XLVIII-2-W8-2024-147-2024.bib))
+- Bartosz Mitka, Klapa Przemysław and Gawronek Pelagia, "Laboratory Tests of Metrological Characteristics of a Non-Repetitive Low-Cost Mobile Handheld Laser Scanner." (2024, MDPI-Sensors, [[PDF]](https://www.mdpi.com/1424-8220/24/18/6010), [[BIB]](https://github.com/MapsHD/HDMapping/blob/main/bib/sensors-v24-i18_20260104.bib))
+- Loris Redovniković, Antun Jakopec, Janusz Będkowski, Jurica Jagetić, "The affordable DIY Mandeye LiDAR system for surveying caves, and how to convert 3D clouds into traditional cave ground plans and extended profiles." (2024, IJS, [[PDF]](https://digitalcommons.usf.edu/cgi/viewcontent.cgi?article=2535&context=ijs), [[BIB]](https://github.com/MapsHD/HDMapping/blob/main/bib/ijs.bib))
+- Janusz Będkowski et al., "A Novel Approach to Global Positioning System Accuracy Assessment, Verified on LiDAR Alignment of One Million Kilometers at a Continent Scale, as a Foundation for Autonomous DRIVING Safety Analysis." (2021, MDPI-Sensors, [[PDF]](https://www.mdpi.com/1424-8220/21/17/5691), [[BIB]](https://github.com/MapsHD/HDMapping/blob/main/bib/sensors-v21-i17_20260104.bib))
diff --git a/documentation/README.md b/documentation/README.md
diff --git a/documentation/Tools/README.md b/documentation/Tools/README.md
@@ -0,0 +1,11 @@
+# Camera-LiDAR calibration tools
+
+Three tools (`apps/camera_lidar_*`) supports camera calibration with LIDAR and perofming applying colors to data from session.
+
+- **camera_lidar_intrinsics_calib** -- checkerboard-based camera intrinsic calibration (OpenCV rational distortion model).
+- **camera_lidar_calibration** -- interactive LiDAR-camera extrinsic calibration: aligns a LAZ/LAS point cloud to a camera image with live GPU-shader reprojection feedback.
+- **camera_lidar_trajectory_viewer** -- multi-camera trajectory/point-cloud viewer that assigns per-point "which camera colored this point" RGB, with LAZ export, plus optional COLMAP sparse-model and ROS 2 bag export.
+
+# GNSS with RTK
+
+A portable NTRIP (Networked Transport of RTCM via Internet Protocol) client for M5Stack devices that receives RTK correction data from NTRIP casters and forwards it to u-blox GNSS receivers for high-precision positioning https://github.com/michalpelka/M5NtripClient.