Merge pull request #30 from Andrea-Ricciardi-99/master

Website Update: General Localization Readme Update

Author: petrlmat

docs/50-features/26-localization/01-gnsss+magnetometer.md

@@ -0,0 +1,12 @@
+---
+title: GNSS + Magnetometer
+pagination_label: GNSS + Magnetometer Localization Algorithm
+description: GNSS + Magnetometer Localization Algorithm
+---
+
+:::warning
+This page is describing the upcoming ROS2 version of the MRS UAV System (however, it may be still outdated). If you are looking for ROS1 version of the docs, follow to https://ctu-mrs.github.io/docs/1.5.0/introduction/.
+:::
+
+* TODO State estimator is part of the MRS core.
+* TODO Direct integration with PX4 over the HW API.

docs/50-features/26-localization/02-rtk_gnss.md

@@ -0,0 +1,12 @@
+---
+title: RTK GNSS
+pagination_label: RTK GNSS Localization Algorithm
+description: RTK GNSS Localization Algorithm
+---
+
+:::warning
+This page is describing the upcoming ROS2 version of the MRS UAV System (however, it may be still outdated). If you are looking for ROS1 version of the docs, follow to https://ctu-mrs.github.io/docs/1.5.0/introduction/.
+:::
+
+* TODO State estimator is part of the MRS core.
+* TODO Direct integration with Emlid Reach.

docs/50-features/26-localization/03-hector_slam.md

@@ -0,0 +1,11 @@
+---
+title: Hector SLAM
+pagination_label: Hector SLAM Localization Algorithm
+description: Hector SLAM Localization Algorithm
+---
+
+:::warning
+This page is describing the upcoming ROS2 version of the MRS UAV System (however, it may be still outdated). If you are looking for ROS1 version of the docs, follow to https://ctu-mrs.github.io/docs/1.5.0/introduction/.
+:::
+
+* TODO Is prebuilt and part of the MRS

docs/50-features/26-localization/04-aloam_slam.md

@@ -0,0 +1,11 @@
+---
+title: ALOAM SLAM
+pagination_label: ALOAM SLAM Localization Algorithm
+description: ALOAM SLAM Localization Algorithm
+---
+
+:::warning
+This page is describing the upcoming ROS2 version of the MRS UAV System (however, it may be still outdated). If you are looking for ROS1 version of the docs, follow to https://ctu-mrs.github.io/docs/1.5.0/introduction/.
+:::
+
+* TODO Is prebuilt and part of the MRS

docs/50-features/26-localization/05-open_vins.md

@@ -0,0 +1,11 @@
+---
+title: Open Vins
+pagination_label: Open Vins VIO Localization Algorithm
+description: Open Vins Visual Inertial Odometry (VIO) Localization Algorithm
+---
+
+:::warning
+This page is describing the upcoming ROS2 version of the MRS UAV System (however, it may be still outdated). If you are looking for ROS1 version of the docs, follow to https://ctu-mrs.github.io/docs/1.5.0/introduction/.
+:::
+
+* TODO Is prebuilt and part of the MRS

docs/50-features/26-localization/06-pointlio_slam.md

@@ -0,0 +1,12 @@
+---
+title: PointLIO SLAM
+pagination_label: PointLIO SLAM LIO Localization Algorithm
+description: PointLIO SLAM Lidar Inertial Odometry (LIO) Localization Algorithm
+---
+
+:::warning
+This page is describing the upcoming ROS2 version of the MRS UAV System (however, it may be still outdated). If you are looking for ROS1 version of the docs, follow to https://ctu-mrs.github.io/docs/1.5.0/introduction/.
+:::
+
+* TODO the estimator plugin is prebuilt
+* TODO the SLAM is not part of the MRS

docs/50-features/26-localization/07-liosam_slam.md

@@ -0,0 +1,11 @@
+---
+title: LIOSAM SLAM
+pagination_label: LIOSAM SLAM Localization Algorithm
+description: LIOSAM SLAM Localization Algorithm
+---
+
+:::warning
+This page is describing the upcoming ROS2 version of the MRS UAV System (however, it may be still outdated). If you are looking for ROS1 version of the docs, follow to https://ctu-mrs.github.io/docs/1.5.0/introduction/.
+:::
+
+* TODO The SLAM and the estimator plugins are prebuilt in the MRS but not test in the realworld

docs/50-features/26-localization/fig/Algo_Integration_Pipeline_MRS.png

@@ -10,37 +10,70 @@ This page is describing the upcoming ROS2 version of the MRS UAV System (however
 
 # Localization sources within the MRS
 
-* TODO explain the reason for the need of localization
-* TODO explain that the sources of localizaton are fused by the estimation manager
-* TODO point to the metapackages responsible for defining the estimator plugin and the other dependencies
+## The Need for Localization
 
-## GNSS + Magnetometer
+Accurate and reliable localization is the cornerstone of autonomous UAV operation. For a drone to navigate its environment, execute complex missions, and avoid obstacles, it must have a precise understanding of its own position and orientation (collectively known as *pose*). This awareness is fundamental for everything from simple waypoint following to advanced tasks like autonomous landing and interaction with the environment. Without a robust localization system, a UAV is essentially flying blind, posing a significant risk to itself and its surroundings.
 
-* TODO State estimator is part of the MRS core.
-* TODO Direct integration with PX4 over the HW API.
+### Localization Sources
 
-## RTK GNSS
+The MRS UAV System is designed to be versatile and can utilize a variety of localization sources. These sources are fused by an estimation manager, which combines the data to produce a single, highly accurate state estimate. The primary sources can be broadly categorized into two groups: GNSS-aided and GNSS-denied.
 
-* TODO State estimator is part of the MRS core.
-* TODO Direct integration with Emlid Reach.
+#### GNSS-Aided Localization
 
-## Hector SLAM
+When operating in open, outdoor environments, Global Navigation Satellite Systems (GNSS) are the most common source for localization. These systems provide a global position estimate with reasonable accuracy.
 
-* TODO Is prebuilt and part of the MRS
+* **GNSS:** Basic GNSS receivers provide position information that can be fused with data from an Inertial Measurement Unit (IMU) and a magnetometer to get a full pose estimate.
+* **RTK GNSS:** For applications requiring higher precision, Real-Time Kinematic (RTK) GNSS can provide centimeter-level accuracy by using a secondary base station to correct for satellite signal errors.
 
-## ALOAM SLAM
 
-* TODO Is prebuilt and part of the MRS
+#### GNSS-Denied Localization
 
-## OpenVINS Visual Inertial Odometry (VIO)
+In many critical scenarios, relying on GNSS is not an option. This can be due to signal obstruction, such as in underground tunnels or dense urban canyons, or due to intentional interference like GPS jamming in security-sensitive missions. In these cases, the UAV must rely on its onboard sensors to estimate its motion. This is where GNSS-denied localization algorithms become essential.
 
-* TODO Is prebuilt and part of the MRS
+The most common approaches are:
 
-## PointLIO SLAM
+* **Visual-Inertial Odometry (VIO):** This technique uses one or more cameras combined with an IMU to track the drone's motion. VIO is a popular choice as cameras are lightweight, low-power, and relatively inexpensive. By tracking visual features in the environment from frame to frame, VIO algorithms can estimate the drone's ego-motion. However, they can be susceptible to drift over long distances and may struggle in visually-degraded environments (e.g., low light or textureless surfaces).
+* **Lidar-Inertial Odometry (LIO):** LIO replaces cameras with a LiDAR sensor to build a point cloud of the environment. By matching consecutive point clouds, LIO systems can very accurately track the drone's movement. LIO is generally more robust than VIO in challenging lighting conditions and can provide higher accuracy. The tradeoff is that LiDAR sensors are typically more expensive, heavier, and consume more power, which can impact the drone's flight time and budget.
+* **Simultaneous Localization and Mapping (SLAM):** Both VIO and LIO are often integral parts of a larger SLAM system. SLAM algorithms not only track the drone's pose but also build a persistent map of the environment. This map can then be used to correct for drift when the drone revisits a previously mapped area (an event known as a *loop closure*), leading to globally consistent trajectories.
 
-* TODO the estimator plugin is prebuilt
-* TODO the SLAM is not part of the MRS
+The choice of a particular localization algorithm is a trade-off that depends on the specific application, the operational environment, and, significantly, the available budget. While a high-end LiDAR-based system might offer the best performance, a well-tuned VIO system can provide excellent results for many applications at a fraction of the cost.
 
-## LIOSAM SLAM
+## Estimation Manager and Source Fusion
+
+The MRS estimation manager fuses multiple localization sources, including GNSS, VIO, and LIO, into a single, robust state estimate for the UAV. It manages switching between estimator plugins based on their health and publishes essential topics such as the UAV state, odometry, and height above terrain. Estimator plugins provide a standardized interface to expose different localization algorithms to the manager. For detailed information, see the [Estimation Manager documentation](../../50-features/01-managers/index.md#estimationmanager).
+
+## Localization Integration Structure
+
+<div style={{textAlign: 'center'}}>
+  <img src={require('./fig/Algo_Integration_Pipeline_MRS.png').default} alt="MRS Localization Layers" style={{width: '35%'}} />
+</div>
+
+To integrate a localization algorithm into the MRS UAV System, the implementation follows a three-layer structure that bridges the raw algorithm to the system's estimation framework.
+
+### Algorithm Library
+
+The algorithm library contains the core implementation of the localization algorithm (for example, `open_vins` for OpenVINS). This layer includes all mathematical models, feature tracking, optimization, and pose estimation code, but it operates in its own coordinate frames and ROS topics, which are not directly compatible with the MRS UAV System.
+
+### Core Folder
+
+The core folder (for example, `mrs_open_vins_core`) acts as the ROS integration wrapper. It provides configuration files, launch files for node wrapping and topic remapping, and tmux scripts for simulation startup (including RViz visualization). This layer handles all MRS-specific wiring and supports both simulation and real-world deployment. It allows the [Algorithm Library](#algorithm-library) to remain untouched, while still integrating the algorithm into the MRS UAV System. For instructions on how to start the Gazebo simulation, see the [How to Simulate](./../../60-simulations/01-gazebo/01-howto.md) page.
+
+
+### Estimator Plugin Folder
+
+The estimator plugin folder (e.g., `mrs_open_vins_estimator_plugin`) implements the MRS estimator plugin interface, making the algorithm selectable by the estimation manager. See the [estimator plugins documentation](./../../45-plugin-interface/04-estimators.md) for full interface details.
+
+## Optional Components
+
+Algorithms that generate their own TF trees (such as VINS-based approaches) typically require a republisher node. This node is responsible for transforming the algorithm's odometry into the MRS `world` frame and linking the algorithm's internal TF tree to the main `fcu` frame via static transforms (specifically from `fcu` to the algorithm's `body` or `imu` frame). For a reference implementation, see the [VINS Republisher](https://github.com/ctu-mrs/mrs_vins_republisher.git).
+
+For detailed information on the system's coordinate frame conventions, refer to the [Frames of Reference](./../../40-api/20-frames_of_reference.md) page.
+
+## Available Localization Algorithms
+
+Below you can find the localization algorithms currently integrated into the MRS UAV System. Refer to the documentation of each algorithm to learn about its installation, configuration, and usage within the estimation framework.
+
+import DocCardList from '@theme/DocCardList';
+
+<DocCardList />
 
-* TODO The SLAM and the estimator plugins are prebuilt in the MRS but not test in the realworld

docs/50-features/26-localization/index.md

@@ -0,0 +1,8 @@
+---
+title: GNSS + Magnetometer
+pagination_label: GNSS + Magnetometer Localization Algorithm
+description: GNSS + Magnetometer Localization Algorithm
+---
+
+* TODO State estimator is part of the MRS core.
+* TODO Direct integration with PX4 over the HW API.