Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update tuning parameters and performance page #473

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
nav:
- evaluating-controller-performance.md
- evaluating-real-time-performance.md
- Sample tuning for campus environment: tuning-parameters
- Evaluation: evaluation
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
nav:
- Evaluating the controller performance: evaluating-controller-performance
- Evaluating real-time performance: evaluating-real-time-performance
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ If you need more detailed information about package, refer to the [control_perfo

#### 2. Initialize the vehicle and send goal position to create route

- If you have any problem with launching Autoware, please see the [tutorials](../../../tutorials/index.md) page.
- If you have any problem with launching Autoware, please see the [tutorials](../../../../../tutorials/index.md) page.

#### 3. Launch the control_performance_analysis package

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
nav:
- index.md
- Tuning localization: localization-tuning
- Tuning perception: perception-tuning
- Tuning planning: planning-tuning
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
# Sample tuning for campus environment

## Introduction

This section will guide you on how to fine-tune Autoware's localization, perception,
and planning stacks for the Yıldız Technical University (YTU) campus environment.
This document serves as your roadmap for optimizing the performance of
Autoware within the cutting-edge capabilities of a sample university campus environment.
Through meticulous parameter adjustments, our aim is to ensure that your
autonomous systems operate seamlessly and efficiently in similar complex real-world scenarios.

## Yıldız Technical University Campus Environment

[Yıldız Technical University (YTU)](https://yildiz.edu.tr/en) is located in Istanbul, Turkey,
and it encompasses multiple campuses. One of these campuses is the
Davutpaşa Campus, where we operate autonomous vehicles. Here is some
general information about the YTU Davutpaşa Campus:

1. **Slopes and Terrains**

YTU Davutpaşa Campus has varied topography.
Some areas may be flat, while others may have gentle or steep slopes.
These features can influence accessibility and landscaping choices.

2. **Greenery and Trees**

YTU Davutpaşa Campus is typically landscaped with a variety of plants and trees. They provide aesthetic
appeal, shade, and contribute to the overall environment. There may be designated green spaces,
gardens, and courtyards.

3. **Building structures**

The Davutpaşa Campus features a diverse range of buildings, ranging in size from small-scale structures
to more substantial edifices. These buildings will be utilized for NDT localization.

<figure markdown>
![ytu-campus-environment](images/ytu-campus.png){ align=center }
<figcaption>
Yıldız Technical University (YTU) campus map.
</figcaption>
</figure>

## Yıldız Technical University Campus Map

### Yıldız Technical University Campus Pointcloud Map

Utilizing the LIO-SAM mapping package, we have effectively created a point cloud map of Yıldız
Technical University's Davutpaşa campus. This real-time lidar-inertial odometry system has empowered
us to achieve precision in this unique campus environment. For detailed information on how we
constructed the point cloud map at YTU Davutpaşa, please refer to the
[LIO-SAM page](../../creating-maps/open-source-slam/lio-sam). Additionally,
we have converted the output map into MGRS format.

<figure markdown>
![ytu-campus-pcd-map](images/ytu-campus-pcd-map.png){ align=center }
<figcaption>
Yıldız Technical University (YTU) campus pointcloud map.
</figcaption>
</figure>

### Yıldız Technical University Campus Lanelet2 Map

We have generated a Lanelet2 HD map, incorporating regulatory elements like crosswalks,
speed bumps, stop lines etc., tailored for the YTU campus environment. For more detailed
information on the Lanelet2 map creation process, please refer to the [`Creating Maps` page](../../creating-maps).

<figure markdown>
![ytu-campus-lanelet2-map](images/ytu-campus-lanelet2-map.png){ align=center }
<figcaption>
Yıldız Technical University (YTU) campus lanelet2 map.
</figcaption>
</figure>
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
@@ -0,0 +1,148 @@
# Tuning localization

## Introduction

In this section,
our focus will be on refining localization accuracy within the YTU Campus environment through updates to localization parameters and methods.
Our approach involves
utilizing NDT as the pose input source and the Gyro Odometer as the twist input source.
These adjustments play a pivotal role
in achieving a heightened level of precision and reliability in our localization processes,
ensuring optimal performance in the specific conditions of the YTU campus.

## NDT parameter tuning

### Crop-box filter for localization input

- In our campus environment, certain areas can be challenging for NDT localization,
particularly those near cliffs or wooded areas that are far from buildings.

<figure markdown>
![ytu-campus-pcd-range](images/pcd-range-cloud-compare.png){ align=center }
<figcaption>
Yıldız Technical University (YTU) campus challenging areas for NDT localization.
</figcaption>
</figure>

- In these areas,
the default NDT range
(which involves cropping the NDT input point cloud at the localization utility point cloud pipeline)
may prove insufficient for aligning point clouds.
The default NDT input point cloud parameters are shown below:

!!! note "The default [crop_box_filter_measurement_range.param.yaml](https://github.com/autowarefoundation/autoware_launch/blob/main/autoware_launch/config/localization/crop_box_filter_measurement_range.param.yaml) file for localization util."

```yaml
/**:
ros__parameters:
input_frame: "base_link"
output_frame: "base_link"
min_x: -60.0
max_x: 60.0
min_y: -60.0
max_y: 60.0
min_z: -30.0
max_z: 50.0
negative: False
```

- The green points (topic name: `/localization/pose_estimator/points_aligned`)
represent the NDT localization aligned points on the map in the image below.
The default range is 60 meters, meaning points beyond this distance cannot be utilized.

<figure markdown>
![ytu-campus-pcd-range](images/ndt-range-60m.png){ align=center }
<figcaption>
NDT aligned points within a 60-meter crop box range
</figcaption>
</figure>

- If we wish to increase our NDT input point cloud range,
we can make the following changes in the `crop_box_filter_measurement_range.param.yaml` file.
However,
please bear in mind that since this alteration enlarges the size of the NDT input point cloud,
it will require additional resources on your processor.

!!! note "[`crop_box_filter_measurement_range.param.yaml`](https://github.com/autowarefoundation/autoware_launch/blob/main/autoware_launch/config/localization/crop_box_filter_measurement_range.param.yaml) parameter file:"

```diff
/**:
ros__parameters:
input_frame: "base_link"
output_frame: "base_link"
- min_x: -60.0
+ min_x: -150.0
- max_x: 60.0
+ max_x: 150.0
- min_y: -60.0
+ min_y: -150.0
- max_y: 60.0
+ max_y: 150.0
min_z: -30.0
max_z: 50.0
negative: False
```

<figure markdown>
![ytu-campus-pcd-range](images/ndt-range-150m.png){ align=center }
<figcaption>
NDT aligned points within a 150-meter crop box range
</figcaption>
</figure>

### Voxel-grid filter for localization input

- Voxel Grid filtering is a technique used in point cloud pre-processing
to reduce the density of 3D point cloud data while preserving its overall structure.
This is especially useful in scenarios
where high-resolution point clouds are computationally expensive
to process or unnecessary for the task at hand.
The default voxel size for all three axes in Autoware is 3.0.
If you have additional computational resources,
reducing the voxel size can enhance localization accuracy.
However, please be aware that this will demand more computational power.

!!! note " The default [voxel_grid_filter.param.yaml](https://github.com/autowarefoundation/autoware_launch/blob/main/autoware_launch/config/localization/voxel_grid_filter.param.yaml) file for localization util."

```yaml
/**:
ros__parameters:
voxel_size_x: 3.0
voxel_size_y: 3.0
voxel_size_z: 3.0
```

- The default voxel size for downsampling is 3.0,
and the resulting aligned points will resemble the image below.

<figure markdown>
![voxel-size-1.0](images/voxel-size-3.0.png){ align=center }
<figcaption>
Voxel size 3.0 aligned points (more sparse)
</figcaption>
</figure>

- We have sufficient computational power available on our tutorial vehicle,
so we will reduce the voxel size to improve localization accuracy.
Feel free to experiment with tuning the voxel size for your own computer setup.

!!! note "[voxel_grid_filter.param.yaml](https://github.com/autowarefoundation/autoware_launch/blob/main/autoware_launch/config/localization/voxel_grid_filter.param.yaml) parameter file:"

```diff

/**:
ros__parameters:
- voxel_size_x: 3.0
+ voxel_size_x: 1.0
- voxel_size_y: 3.0
+ voxel_size_y: 1.0
- voxel_size_z: 3.0
+ voxel_size_z: 1.0
```

<figure markdown>
![voxel-size-1.0](images/voxel-size-1.0.png){ align=center }
<figcaption>
Voxel size 1.0 aligned points (more dense but it requires computational power)
</figcaption>
</figure>
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading