# robosense_localization

**Repository Path**: zijinyang/robosense_localization

## Basic Information

- **Project Name**: robosense_localization
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-13
- **Last Updated**: 2026-02-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# localization

[README](README.md) | [中文文档](README_CN.md)

## 1. Introduction
**localization** is used to provide real-time relative or global positioning information. This project includes the following two modules:

`msf_localization` is a fusion localization module based on the **ESKF** framework, which can provide relative positioning information based only on **IMU + wheel speed** and global positioning information by fusing **point cloud localization results**. This module can also be extended with other sensor observations.

`lidar_localization` is a point cloud localization module based on point cloud maps, using ceres for optimization and pcl for point cloud processing.

## 2. Prerequisites

This project is developed and tested based on `ros2 humble/ros1 noetic`+ `python 3.8.10` .

The `msf_localization` and `lidar_localization` modules depend on `ros2/ros1` and the dependencies defined in `package.xml`.

`msf_localization` depend on glog to log information  

**Ubuntu:**
```bash
sudo apt install libgoogle-glog-dev
```

### 2.1 Install ros

Follow the specified content in the [official tutorial](https://fishros.org/doc/ros2/humble/Installation.html) for your operating system.

### 2.2 Install python3 [Optional]

You can install Python3 by following the Python installation guide for your platform. It is recommended to use version `3.8.10` or above.

* **Windows:** Download and run https://www.python.org/ftp/python/3.8.10/python-3.8.10-amd64.exe to complete the installation.

* **Ubuntu:** 
```bash
sudo apt-get install -y python3 python3-pip
```

## 3. Installation

### 3.1 Pulling Source Code

You can create a new folder or go into your existing `ros` workspace and execute the following command to clone the code into the workspace.

```bash
git clone git@gitlab.robosense.cn:super_sensor_sdk/ros2_sdk/localization.git -b main
```

### 3.3 Compile localization

This project supports both `ros1` and `ros2`

**ros1:**

Execute the following commands in your workspace to compile and install `localization`.

```bash
catkin_make
```

After compilation and installation, it is recommended to refresh the workspace's `bash profile` to ensure everything functions properly.

```bash
source devel/setup.bash
```

**ros2:**

Execute the following commands in your workspace to compile and install `localization`.

```bash
colcon build --symlink-install 
```

After compilation and installation, it is recommended to refresh the workspace's `bash profile` to ensure everything functions properly.

```bash
source install/setup.bash
```

## 4. Usage

### 4.1 Run Localization Nodes

**ros1:**

Run the fusion localization node

```bash
rosrun msf_localization msf_localization_node 
```

Run the point cloud localization node

```bash
rosrun lidar_localization lidar_localization_node
```

**ros2:**

Run the fusion localization node

```bash
ros2 run msf_localization msf_localization_node 
```

Run the point cloud localization node
```bash
ros2 run lidar_localization lidar_localization_node
```

### 4.2 Rviz Visualize 

**ros2:**

```bash
rviz -d msf_localization/rviz/rviz2_config.rviz
```

**ros2:**

```bash
rviz2 -d msf_localization/rviz/rviz2_config.rviz
```
### 4.3 Required Sensor Messages

* `msf_localization` : IMU messages, wheel speed messages, lidar localization result (optional), user-extended other sensor messages (optional)

* `lidar_localization` : LiDAR point cloud messages, msf localization result

### 4.4 localization initialization

fusion localization and lidar localization default initial position is' [0,0,0] ', and the default initial pose is the identity matrix. If the user 

knows the initial pose in the pointcloud map or can obtain the initial pose through external devices such as RTK, they can modify the configuration file

* fusion localization: `msf_localization/config/loc_param.yaml`:

```yaml
#init pose
x_init: 2.0
y_init: 4.0
z_init: 0.0
roll_init: 0.0
pitch_init: 0.0
yaw_init: 0.0
```

* lidar localization: `lidar_localization/config/config.yaml`:

```yaml
#init position
init_position: [2.0, 4.0, 0.0]  # x, y, z
#init euler
init_euler: [0.0, 0.0, 0.0] # roll, pitch, yaw
```

### 4.5 Prepare the dataset

* `Point Cloud Map`: Point cloud map PCD files generated by rs_slam mapping software or other mapping software, placed in 

    `lidar_localization/map` directory, user need to set `map_path` parameter in configuration file of lidar localization

* `Example Data Path` : https://cdn.robosense.cn/AC_wiki/localization_demo.zip

## 5. Function Description

### 5.1 Configuration Files

Fusion localization related configuration file: msf_localization/config/loc_param.yaml

Point cloud localization related configuration file: lidar_localization/config/config.yaml

## 6. FAQ

[Create New Issue](http://gitlab.robosense.cn/super_sensor_sdk/ros2_sdk/localization/-/issues/new)