Skip to content

Commit

Permalink
misc(readme): update readme (autowarefoundation#41)
Browse files Browse the repository at this point in the history 
* add youtube link and change thumbnail

Signed-off-by: Kento Yabuuchi <kento.yabuuchi.2@tier4.jp>

* improve input/output topics

Signed-off-by: Kento Yabuuchi <kento.yabuuchi.2@tier4.jp>

* quick start demo screen image

Signed-off-by: Kento Yabuuchi <kento.yabuuchi.2@tier4.jp>

* add abstruct architecture and detail architecture

Signed-off-by: Kento Yabuuchi <kento.yabuuchi.2@tier4.jp>

---------

Signed-off-by: Kento Yabuuchi <kento.yabuuchi.2@tier4.jp>
  • Loading branch information
@KYabuuchi
KYabuuchi committed Jun 12, 2023
1 parent 37c80cb commit 9b4b641
Show file tree
Hide file tree
Showing 6 changed files with 1,625 additions and 148 deletions.
116 changes: 66 additions & 50 deletions localization/yabloc/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,27 +1,34 @@
# YabLoc

**YabLoc** is vision-baed localization with vector map.
**YabLoc** is vision-baed localization with vector map. [https://youtu.be/Eaf6r_BNFfk](https://youtu.be/Eaf6r_BNFfk)

This has been developed as a new localization stack for [Autoware](https://github.com/autowarefoundation/autoware).
Yabloc has been developed as a new localization stack for [Autoware](https://github.com/autowarefoundation/autoware).

[![thumbnail](docs/yabloc_thumbnail.jpg)](https://youtu.be/Eaf6r_BNFfk)

![thumbnail](docs/yabloc_thumbnail.jpg)

## Installation

### Prerequisites
### Prerequisite

**supporting `Ubuntu 22.04` + `ROS2 humble` now.**

**NOTE:** Currently, this software is assumed to be built in a separate workspace in order not to contaminate the autoware workspace.
Someday this will be located in the workspace where Autoware blongs. The following submodules will be removed at the time.

Branches

**Supporting `Ubuntu 22.04` + `ROS2 humble` now.**
* [main](https://github.com/tier4/YabLoc/tree/main) is a branch to work with minimal dependence on autoware.
* If you want to try the YabLoc demo, please use `main` branch.
* [autoware(under construction)](https://github.com/tier4/YabLoc/tree/autoware) is a branch made to run as part of Autoware.

### Submodules
Submodules

* [external/autoware_auto_msgs](https://github.com/tier4/autoware_auto_msgs)
* [external/autoware_msgs](https://github.com/autowarefoundation/autoware_msgs.git)
* [external/septentrio_gnss_driver](https://github.com/tier4/septentrio_gnss_driver.git)
* [external/tier4_autoware_msgs](https://github.com/tier4/tier4_autoware_msgs.git)

**NOTE:** Currently, this software is assumed to be built in a separate workspace in order not to contaminate the autoware workspace.
Someday this will be located in the workspace where Autoware blongs. These submodules will be removed at the time.

### How to build

```shell
Expand Down Expand Up @@ -50,7 +57,7 @@ colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release -DCMAKE_E

![how_to_launch_with_rosbag](docs/how_to_launch_quick_start_demo.drawio.svg)

sample rosbag: [Google Drive link](https://drive.google.com/file/d/1UqULyfidxcA5JidfHWAsSqNy8itampAX/view?usp=share_link)
* sample rosbag: [Google Drive link](https://drive.google.com/file/d/1UqULyfidxcA5JidfHWAsSqNy8itampAX/view?usp=share_link)

```shell
# terminal 1
Expand All @@ -66,14 +73,21 @@ source install/setup.bash
ros2 bag play awsim_yabloc_rosbag_sample_0.db3 -s sqlite3
```

If YabLoc runs successfully, you will see a screen like the following.

<img src="docs/quick_start_demo_screen.png" width="600">


## Demo with Autoware

**NOTE:** `use_sim_time` is TRUE as default.

### Run with rosbag
### Run with rosbag

<details><summary>click to open </summary><div>

**This is a procedure for self-localization, planning/control components of Autoware would not work in this way.**

![how_to_launch_with_rosbag](docs/how_to_launch_with_rosbag.drawio.svg)

```shell
Expand Down Expand Up @@ -101,6 +115,8 @@ ros2 bag play your_rosbag --clock 100

<details><summary>click to open </summary><div>

**This is a procedure for self-localization, planning/control components of Autoware would not work in this way.**

![how_to_launch_with_rosbag](docs/how_to_launch_in_real.drawio.svg)

```shell
Expand All @@ -119,16 +135,13 @@ ros2 launch autoware_launch autoware.launch.xml \
**You have to change autoware.universe branch.**

```shell
ros2 launch yabloc_launch sample_launch.xml standalone:=false
ros2 launch yabloc_launch rviz.launch.xml
ros2 launch autoware_launch e2e_simulator.launch.xml
```

</div></details>

## How to set initial pose

### 1. When YabLoc works `standalone:=true`(default) (without Autoware's pose_initializer)
### 1. When YabLoc runs `standalone:=true`(default) (without Autoware's pose_initializer)

1. `2D Pose Estimate` in Rviz

Expand All @@ -138,32 +151,38 @@ You can inidcate x, y and yaw manually in rviz.

If doppler (`ublox_msgs/msg/navpvt`) is available and the vehicle moves enough fast, YabLoc will estiamte the initial pose **automatically**.

### 2. When Yabloc works `standalone:=false` (through Autoware's pose_initializer)
### 2. When Yabloc runs `standalone:=false` (through Autoware's pose_initializer)

<ins>UNDER CONSTRUCTION</ins>

## Architecture

![node_diagram](docs/yabloc_abstruct_architecture.drawio.svg)

<details><summary>click to more detail</summary><div>

![node_diagram](docs/yabloc_architecture.drawio.svg)

</div></details>

### Input topics

from sesnors

| topic name | msg type | description |
| ---- | ---- | -- |
| `/sensing/imu/tamagawa/imu_raw` | `sensor_msgs/msg/Imu` | |
| `/sensing/camera/traffic_light/image_raw/compressed` | `sensor_msgs/msg/CompressedImage` | |
| `/sensing/camera/traffic_light/camera_info` | `sensor_msgs/msg/CameraInfo` | |
| `/sensing/gnss/ublox/navpvt` | `ublox_msgs/msg/NavPVT` | If you use ublox |
| `/sensing/gnss/septentrio/poscovgeodetic` | `septentrio_gnss_driver_msgs/msg/PosCovGeodetic` | If you use Septentrio |
| `/vehicle/status/velocity_status` | `autoware_auto_vehicle_msgs/msg/VelocityReport` | |
| topic name | msg type | description |
|------------------------------------------------------|--------------------------------------------------|-----------------------|
| `/sensing/imu/tamagawa/imu_raw` | `sensor_msgs/msg/Imu` | |
| `/sensing/camera/traffic_light/image_raw/compressed` | `sensor_msgs/msg/CompressedImage` | |
| `/sensing/camera/traffic_light/camera_info` | `sensor_msgs/msg/CameraInfo` | |
| `/sensing/gnss/ublox/navpvt` | `ublox_msgs/msg/NavPVT` | If you use ublox |
| `/sensing/gnss/septentrio/poscovgeodetic` | `septentrio_gnss_driver_msgs/msg/PosCovGeodetic` | If you use Septentrio |
| `/vehicle/status/velocity_status` | `autoware_auto_vehicle_msgs/msg/VelocityReport` | |

from autoware
| topic name | msg type | description |
| ---- | ---- | -- |
| `/tf_static` | `tf2_msgs/msg/TFMessage` | published from `sensor_kit` |
| `/map/vector_map` | `autoware_auto_mapping_msgs/msg/HADMapBin` | published from `/map/lanelet2_map_loader` |
| topic name | msg type | description |
|-------------------|--------------------------------------------|-------------------------------------------|
| `/tf_static` | `tf2_msgs/msg/TFMessage` | published from `sensor_kit` |
| `/map/vector_map` | `autoware_auto_mapping_msgs/msg/HADMapBin` | published from `/map/lanelet2_map_loader` |

#### about tf_static

Expand All @@ -176,7 +195,7 @@ You can verify that the tf_static is correct with the following command.
ros2 run tf2_ros tf2_echo base_link traffic_light_left_camera/camera_optical_link
```

If the wrong `/tf_static` are broadcasted because you are using a prototype vehicle, it is useful to give the frame_id in `override_camera_frame_id`.
If the wrong `/tf_static` are broadcasted due to using a prototype vehicle, not having accurate calibration data, or some other unavoidable reason, it is useful to give the frame_id in `override_camera_frame_id`.
If you give it a non-empty string, `/imgproc/undistort_node` will rewrite the frame_id in camera_info.
For example, you can give a different tf_static as follows.

Expand All @@ -191,34 +210,31 @@ ros2 run tf2_ros static_transform_publisher \

</div></details>

### Output topics
### Output topics about pose


| topic name | msg type | description |
| ---- | ---- | -- |
| `/localicazation/pf/pose` | `geometry_msgs/msg/PoseStamped` | estimated pose |
| `/localicazation/validation/overlay_image` | `sensor_msgs/msg/Image` | really nice image for demonstration |
| `/localicazation/pf/cost_map_image` | `sensor_msgs/msg/Image` | visualization of cost map for debug |
| `/localicazation/pf/predicted_particles_marker` | `visualization_msgs/msg/MarkerArray` | particles of particle filter |
| `/localicazation/imgproc/image_with_line_segments` | `sensor_msgs/msg/Image` | image |
| `/localicazation/imgproc/projected_image_with_line_segments` | `sensor_msgs/msg/Image` | image |
| topic name | msg type | description |
|-------------------------------------------------------|--------------------------------------|--------------------------------------------|
| `/localicazation/pf/pose` | `geometry_msgs/msg/PoseStamped` | estimated pose |
| `/localicazation/pose_estimator/pose_with_covariance` | `geometry_msgs/msg/PoseStamped` | estimated pose with covariance |

## Visualization
### Output topics for visualization

This project contains original rviz plugins. [rviz2_overlay_plugins](./rviz2_plugins/rviz2_overlay_plugins/README.md)

![rviz](docs/rviz_description.png)

| index | topic name | description |
| ---- | ---- | -- |
| 1 | `/localicazation/validation/overlay_image` | Projection of lanelet2 (yellow lines) onto image based on estimated pose. If they match well with the actual road markings, it means that the localization performs well. |
| 2 | `/localicazation/imgproc/segmented_image` | result of graph-based segmetation. yellow area is identified as the road surface.|
| 3 | `/localicazation/pf/cost_map_image` | cost map generated from lanelet2. |
| 4 | `/localicazation/imgproc/image_with_line_segments` | detected line segments |
| 5 | `/localicazation/map/ground_status` | ground height and tilt estimatation status |
| 6 | `/localicazation/twist/kalman/status` | twist estimation status |
| 7 | `/localicazation/pf/predicted_particle_marker` | particle distribution of particle fitler (red means a probable candidate) |
| 8 | `/localicazation/pf/gnss/range_marker` | particle weight distribution by GNSS |
| 9 | `/localicazation/pf/scored_cloud` | 3D projected line segments. the color means the how match they are |
| index | topic name | description |
|-------|----------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1 | `/localicazation/imgproc/lanelet2_overlay_image` | Projection of lanelet2 (yellow lines) onto image based on estimated pose. If they match well with the actual road markings, it means that the localization performs well. |
| 2 | `/localicazation/imgproc/segmented_image` | result of graph-based segmetation. yellow area is identified as the road surface. |
| 3 | `/localicazation/pf/cost_map_image` | cost map generated from lanelet2. |
| 4 | `/localicazation/imgproc/image_with_line_segments` | detected line segments |
| 5 | `/localicazation/map/ground_status` | ground height and tilt estimatation status |
| 6 | `/localicazation/twist/kalman/status` | twist estimation status |
| 7 | `/localicazation/pf/predicted_particle_marker` | particle distribution of particle fitler (red means a probable candidate) |
| 8 | `/localicazation/pf/gnss/range_marker` | particle weight distribution by GNSS |
| 9 | `/localicazation/pf/scored_cloud` | 3D projected line segments. the color means the how match they are |

## License

Expand Down
Loading

0 comments on commit 9b4b641

Please sign in to comment.