diff --git a/.github/sync-files.yaml b/.github/sync-files.yaml index 2d3cf84f184..14edfb3aa6d 100644 --- a/.github/sync-files.yaml +++ b/.github/sync-files.yaml @@ -15,6 +15,14 @@ - source: .github/workflows/spell-check-differential.yaml - source: .github/workflows/sync-files.yaml - source: .markdown-link-check.json + pre-commands: | + sd -s -- \ + ' "pattern": "^http://localhost"' \ + ' "pattern": "^https://www\\.autosar\\.org/*" + }, + { + "pattern": "^http://localhost"' \ + {source} - source: .markdownlint.yaml - source: .pre-commit-config-optional.yaml - source: .prettierignore diff --git a/.github/workflows/github-release.yaml b/.github/workflows/github-release.yaml index 19e1e9c12e5..95ebb8725f6 100644 --- a/.github/workflows/github-release.yaml +++ b/.github/workflows/github-release.yaml @@ -26,8 +26,8 @@ jobs: REF_NAME="${{ github.ref_name }}" fi - echo ::set-output name=ref-name::"$REF_NAME" - echo ::set-output name=tag-name::"${REF_NAME#beta/}" + echo "ref-name=$REF_NAME" >> $GITHUB_OUTPUT + echo "tag-name=${REF_NAME#beta/}" >> $GITHUB_OUTPUT - name: Check out repository uses: actions/checkout@v3 @@ -39,7 +39,7 @@ jobs: id: set-target-name run: | if [[ "${{ steps.set-tag-name.outputs.ref-name }}" =~ "beta/" ]]; then - echo ::set-output name=target-name::"${{ steps.set-tag-name.outputs.ref-name }}" + echo "target-name=${{ steps.set-tag-name.outputs.ref-name }}" >> $GITHUB_OUTPUT fi - name: Create a local tag for beta branches @@ -62,7 +62,7 @@ jobs: verb=edit fi - echo ::set-output name=verb::"$verb" + echo "verb=$verb" >> $GITHUB_OUTPUT env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/pre-commit.yaml b/.github/workflows/pre-commit.yaml index bda722c87ef..b231dbda879 100644 --- a/.github/workflows/pre-commit.yaml +++ b/.github/workflows/pre-commit.yaml @@ -20,11 +20,6 @@ jobs: with: ref: ${{ github.event.pull_request.head.ref }} - - name: Set git config - uses: autowarefoundation/autoware-github-actions/set-git-config@v1 - with: - token: ${{ steps.generate-token.outputs.token }} - - name: Run pre-commit uses: autowarefoundation/autoware-github-actions/pre-commit@v1 with: diff --git a/.markdown-link-check.json b/.markdown-link-check.json index a753f144d03..1c743d60343 100644 --- a/.markdown-link-check.json +++ b/.markdown-link-check.json @@ -1,6 +1,9 @@ { "aliveStatusCodes": [200, 206, 403], "ignorePatterns": [ + { + "pattern": "^https://www\\.autosar\\.org/*" + }, { "pattern": "^http://localhost" }, @@ -9,9 +12,6 @@ }, { "pattern": "^https://github.com/.*/discussions/new" - }, - { - "pattern": "^https://www\\.autosar\\.org/*" } ], "retryOn429": true, diff --git a/.pre-commit-config-optional.yaml b/.pre-commit-config-optional.yaml index e0019e10d52..eb008730c15 100644 --- a/.pre-commit-config-optional.yaml +++ b/.pre-commit-config-optional.yaml @@ -1,6 +1,6 @@ repos: - repo: https://github.com/tcort/markdown-link-check - rev: v3.10.3 + rev: v3.11.1 hooks: - id: markdown-link-check - args: [--config=.markdown-link-check.json] + args: [--quiet, --config=.markdown-link-check.json] diff --git a/docs/assets/images/detection_area_turnaround_time.png b/docs/assets/images/detection_area_turnaround_time.png new file mode 100644 index 00000000000..f42d74ba267 Binary files /dev/null and b/docs/assets/images/detection_area_turnaround_time.png differ diff --git a/docs/assets/images/ring_outlier_filter_minor_faults.png b/docs/assets/images/ring_outlier_filter_minor_faults.png new file mode 100644 index 00000000000..b64b3746cad Binary files /dev/null and b/docs/assets/images/ring_outlier_filter_minor_faults.png differ diff --git a/docs/assets/images/ring_outlier_filter_turnaround_time.png b/docs/assets/images/ring_outlier_filter_turnaround_time.png new file mode 100644 index 00000000000..496e68f21fa Binary files /dev/null and b/docs/assets/images/ring_outlier_filter_turnaround_time.png differ diff --git a/docs/contributing/coding-guidelines/languages/cpp.md b/docs/contributing/coding-guidelines/languages/cpp.md index 491450c548c..ab4d39e4cbf 100644 --- a/docs/contributing/coding-guidelines/languages/cpp.md +++ b/docs/contributing/coding-guidelines/languages/cpp.md @@ -13,7 +13,7 @@ Follow the guidelines below if a rule is not defined on this page. 3. Also, it is encouraged to apply Clang-Tidy to each file. -For the usage, see [Applying Clang-Tidy to ROS packages](../../../how-to-guides/applying-clang-tidy-to-ros-packages.md). +For the usage, see [Applying Clang-Tidy to ROS packages](../../../how-to-guides/others/applying-clang-tidy-to-ros-packages.md). Note that not all rules are covered by Clang-Tidy. diff --git a/docs/contributing/coding-guidelines/ros-nodes/.pages b/docs/contributing/coding-guidelines/ros-nodes/.pages index 797e85cadc6..e446c5224d5 100644 --- a/docs/contributing/coding-guidelines/ros-nodes/.pages +++ b/docs/contributing/coding-guidelines/ros-nodes/.pages @@ -5,7 +5,6 @@ nav: - directory-structure.md - launch-files.md - message-guidelines.md - - naming.md - parameters.md - task-scheduling.md - topic-namespaces.md diff --git a/docs/contributing/coding-guidelines/ros-nodes/coordinate-system.md b/docs/contributing/coding-guidelines/ros-nodes/coordinate-system.md index 480c5a25c27..29c1252bd52 100644 --- a/docs/contributing/coding-guidelines/ros-nodes/coordinate-system.md +++ b/docs/contributing/coding-guidelines/ros-nodes/coordinate-system.md @@ -16,7 +16,7 @@ In Autoware, coordinate systems are typically used to represent the position and 1. Transformation of sensor data - In Autoware, each sensor has a unique coordinate system and their data is expressed in terms of the coordinates. In order to correlate the independent datas between different sensors, we need to find the position relationship between each sensor and the vehicle body. Once the installation position of the sensor on the vehicle body is determined, it will remain fixed during running, so the offline calibration method can be used to determine the precise position of each sensor relative to the vehicle body. + In Autoware, each sensor has a unique coordinate system and their data is expressed in terms of the coordinates. In order to correlate the independent data between different sensors, we need to find the position relationship between each sensor and the vehicle body. Once the installation position of the sensor on the vehicle body is determined, it will remain fixed during running, so the offline calibration method can be used to determine the precise position of each sensor relative to the vehicle body. 2. ROS TF2 @@ -117,12 +117,12 @@ References: 1. Calibration of sensor - The conversion relationship between every sensor coordinate system and `base_link` can be obtained through sensor calibration technology. How to calibrating your sensors refer to this link [calibrating your sensors](https://autowarefoundation.github.io/autoware-documentation/main/how-to-guides/calibrating-your-sensors/). + The conversion relationship between every sensor coordinate system and `base_link` can be obtained through sensor calibration technology. How to calibrating your sensors refer to this link [calibrating your sensors](../../../how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors.md). 2. Localization The relationship between the `base_link` coordinate system and the `map` coordinate system is determined by the position and orientation of the vehicle, and can be obtained from the vehicle localization result. -3. Georeferencing of map data +3. Geo-referencing of map data - The georeferencing information can get the transformation relationship of `earth` coordinate system to local `map` coordinate system. + The geo-referencing information can get the transformation relationship of `earth` coordinate system to local `map` coordinate system. diff --git a/docs/contributing/coding-guidelines/ros-nodes/launch-files.md b/docs/contributing/coding-guidelines/ros-nodes/launch-files.md index c39bd75e891..5e81bdd1ba1 100644 --- a/docs/contributing/coding-guidelines/ros-nodes/launch-files.md +++ b/docs/contributing/coding-guidelines/ros-nodes/launch-files.md @@ -1,5 +1,67 @@ # Launch files -!!! warning +## Overview - Under Construction +Autoware use ROS2 launch system to startup the software. Please see the [official documentation](https://docs.ros.org/en/humble/Tutorials/Intermediate/Launch/Launch-Main.html) to get a basic understanding about ROS 2 Launch system if you are not familiar with it. + +## Guideline + +### The organization of launch files in Autoware + +Autoware mainly has two repositories related to launch file organization: the [autoware.universe](https://github.com/autowarefoundation/autoware.universe) and the [autoware_launch](https://github.com/autowarefoundation/autoware_launch). + +#### autoware.universe + +the `autoware.universe` contains the code of the main Autoware modules, and its `launch` directory is responsible for launching the nodes of each module. Autoware software stack is organized based on the [architecture](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-architecture/#high-level-architecture-design), so you may find that we try to match the launch structure similar to the architecture (splitting of files, namespace). For example, the `tier4_map_launch` subdirectory corresponds to the map module, so do the other `tier4_*_launch` subdirectories. + +#### autoware_launch + +The `autoware_launch` is a repository referring to `autoware.universe`. The mainly purpose of introducing this repository is to provide the general entrance to start the Autoware software stacks, i.e, calling the launch file of each module. + +- The `autoware.launch.xml` is the basic launch file for road driving scenarios. + + As can be seen from the content, the entire launch file is divided into several different modules, including _Vehicle_, _System_, _Map_, _Sensing_, _Localization_, _Perception_, _Planning_, _Control_, etc. By setting the `launch_*` argument equals to `true` or `false` , we can determine which modules to be loaded. + +- The `logging_simulator.launch.xml` is often used together with the recorded ROS bag to debug if the target module (e.g, _Sensing_, _Localization_ or _Perception_) functions normally. + +- The `planning_simulator.launch.xml` is based on the Planning Simulator tool, mainly used for testing/validation of _Planning_ module by simulating traffic rules, interactions with dynamic objects and control commands to the ego vehicle. + +- The `e2e_simulator.launch.xml` is the launcher for digital twin simulation environment. + +```mermaid +graph LR +A11[logging_simulator.launch.xml]-.->A10[autoware.launch.xml] +A12[planning_simulator.launch.xml]-.->A10[autoware.launch.xml] +A13[e2e_simulator.launch.xml]-.->A10[autoware.launch.xml] + +A10-->A21[tier4_map_component.launch.xml] +A10-->A22[xxx.launch.py] +A10-->A23[tier4_localization_component.launch.xml] +A10-->A24[xxx.launch.xml] +A10-->A25[tier4_sensing_component.launch.xml] + +A23-->A30[localization.launch.xml] +A30-->A31[pose_estimator.launch.xml] +A30-->A32[util.launch.xml] +A30-->A33[pose_twist_fusion_filter.launch.xml] +A30-->A34[xxx.launch.xml] +A30-->A35[twist_estimator.launch.xml] + +A33-->A41[stop_filter.launch.xml] +A33-->A42[ekf_localizer.launch.xml] +A33-->A43[twist2accel.launch.xml] +``` + +### Add a new package in Autoware + +If a newly created package has executable node, we expect sample launch file and configuration within the package, just like the recommended structure shown in previous [directory structure](https://autowarefoundation.github.io/autoware-documentation/main/contributing/coding-guidelines/ros-nodes/directory-structure/) page. + +In order to automatically load the newly added package when starting Autoware, you need to make some necessary changes to the corresponding launch file. For example, if using ICP instead of NDT as the pointcloud registration algorithm, you can modify the `autoware.universe/launch/tier4_localization_launch/launch/pose_estimator/pose_estimator.launch.xml` file to load the newly added ICP package. + +## Parameter management + +Another purpose of introducing the `autoware_launch` repository is to facilitate the parameter management of Autoware. Thinking about this situation: if we want to integrate Autoware to a specific vehicle and modify parameters, we have to fork `autoware.universe` which also has a lot of code other than parameters and is frequently updated by developers. By intergrating these parameters in `autoware_launch`, we can customize the Autoware parameters just by forking `autoware_launch` repository. Taking the localization module as an examples: + +1. all the “launch parameters” for localization component is listed in the files under `autoware_launch/autoware_launch/config/localization`. +2. the "launch parameters" file paths are set in the `autoware_launch/autoware_launch/launch/components/tier4_localization_component.launch.xml` file. +3. in `autoware.universe/launch/tier4_localization_launch/launch`, the launch files loads the “launch parameters” if the argument is given in the parameter configuration file. You can still use the default parameters in each packages to launch `tier4_localization_launch` within `autoware.universe`. diff --git a/docs/contributing/coding-guidelines/ros-nodes/topic-namespaces.md b/docs/contributing/coding-guidelines/ros-nodes/topic-namespaces.md index 28da97b6fc4..93756186da9 100644 --- a/docs/contributing/coding-guidelines/ros-nodes/topic-namespaces.md +++ b/docs/contributing/coding-guidelines/ros-nodes/topic-namespaces.md @@ -11,7 +11,7 @@ ROS allows topics, parameters and nodes to be namespaced which provides the foll This page focuses on how to use namespaces in Autoware and shows some useful examples. For basic information on topic namespaces, refer to [this tutorial](https://design.ros2.org/articles/topic_and_service_names.html). -## How topics should be named in Node +## How topics should be named in node Autoware divides the node into the following functional categories, and adds the start namespace for the nodes according to the categories. @@ -30,7 +30,7 @@ In general, topics should be namespaced based on the function of the node which Classify topics as input or output topics based on they are subscribed or published by the node. In the node, input topic is named `input/topic_name` and output topic is named `output/topic_name`. -Configure the topic in the node's launch file. Take the `joy_controller` node as an example, in the following example, set the input and output topics and remap topics in the `joy_controller.luanch.xml` file. +Configure the topic in the node's launch file. Take the `joy_controller` node as an example, in the following example, set the input and output topics and remap topics in the `joy_controller.launch.xml` file. ```xml @@ -92,7 +92,7 @@ Configure the topic in the node's launch file. Take the `joy_controller` node as create_publisher("~/debug/calculation_time", 1); ``` - The launch configurated namespace will be add the topics before, so the topic names will be as following: + The launch configured namespace will be add the topics before, so the topic names will be as following: `/planning/scenario_planning/lane_driving/motion_planning/obstacle_avoidance_planner/debug/marker /planning/scenario_planning/lane_driving/motion_planning/obstacle_avoidance_planner/debug/calculation_time` diff --git a/docs/contributing/pull-request-guidelines/index.md b/docs/contributing/pull-request-guidelines/index.md index 670d7115b95..a38a3618535 100644 --- a/docs/contributing/pull-request-guidelines/index.md +++ b/docs/contributing/pull-request-guidelines/index.md @@ -50,6 +50,26 @@ Use this workflow as a reference when you contribute to Autoware. #### Example +There are two types of templates. Select one based on the following condition. + +1. [Standard change](https://github.com/autowarefoundation/autoware/blob/main/.github/PULL_REQUEST_TEMPLATE/standard-change.md): + - Complexity: + - New features or significant updates. + - Requires deeper understanding of the codebase. + - Impact: + - Affects multiple parts of the system. + - Basically includes minor features, bug fixes and performance improvement. + - Needs testing before merging. +2. [Small change](https://github.com/autowarefoundation/autoware/blob/main/.github/PULL_REQUEST_TEMPLATE/small-change.md): + - Complexity: + - Documentation, simple refactoring, or style adjustments. + - Easy to understand and review. + - Impact: + - Minimal effect on the system. + - Quicker merge with less testing needed. + +##### Steps to use an appropriate pull request template + 1. Select the appropriate template, as shown in [this video](https://user-images.githubusercontent.com/31987104/184344710-2adee239-799f-4fdf-bfab-be76345bfac1.mp4). 2. Read the selected template carefully and fill the required content. 3. Check the checkboxes during a review. diff --git a/docs/datasets/index.md b/docs/datasets/index.md index 9504df74e06..475c999a76a 100644 --- a/docs/datasets/index.md +++ b/docs/datasets/index.md @@ -68,7 +68,7 @@ $ aws s3 ls s3://autoware-files/collected_data/2022-08-22_leo_drive_isuzu_bags/ aws s3 sync s3://autoware-files/collected_data/2022-08-22_leo_drive_isuzu_bags/all-sensors-bag1_compressed/ ./all-sensors-bag1_compressed --no-sign-request ``` -### AutoCore.ai - lidar ROS2 bag file and pcap +### AutoCore.ai - lidar ROS 2 bag file and pcap This dataset contains pcap files and ros2 bag files from Ouster OS1-64 Lidar. The pcap file and ros2 bag file is recorded in the same time with slight difference in duration. diff --git a/docs/design/autoware-architecture/control/image/control-component.drawio.svg b/docs/design/autoware-architecture/control/image/control-component.drawio.svg new file mode 100644 index 00000000000..f028e9325c1 --- /dev/null +++ b/docs/design/autoware-architecture/control/image/control-component.drawio.svg @@ -0,0 +1,145 @@ + + + + + + + +
+
+
+
+ + Control + +
+
+
+ + + Control + + + + + + + +
+
+
+ Trajectory Follower +
+
+
+ + + Trajectory Follower + + + + + + + +
+
+
+ Vehicle Cmd Gate +
+
+
+ + + Vehicle Cmd Gate + + + + + + + + + + + +
+
+
+ Control Command +
+
+
+ + + Control Command + + + + + + + +
+
+
+ Control Command +
+
+
+ + + Control Command + + + + + + + + + +
+
+
+ Reference Trajectory +
+
+
+ + + Reference Trajectory + + + + + + + + + +
+
+
+ External +
+ Control Commands +
+
+
+ + + External... + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/control/image/vehicle-interface-hw-abstraction.drawio.svg b/docs/design/autoware-architecture/control/image/vehicle-interface-hw-abstraction.drawio.svg new file mode 100644 index 00000000000..a09e8fce71d --- /dev/null +++ b/docs/design/autoware-architecture/control/image/vehicle-interface-hw-abstraction.drawio.svg @@ -0,0 +1,528 @@ + + + + + + + +
+
+
+
+ + + Vehicle +
+
+
+ + + Vehicle + + + + + + + +
+
+
+
+ Application +
+
+
+ + + Application + + + + + + + + + +
+
+
+ Status +
+
+
+ + + Status + + + + + + + +
+
+
+ Vehicle I/F +
+
+
+ + + Vehicle I/F + + + + + + + + + +
+
+
+ Steering Voltage +
+ Engine Torque +
+ Brake Pressure +
+
+
+ + + Steering Voltage... + + + + + + + + + +
+
+
+ Status +
+
+
+ + + Status + + + + + + + +
+
+
+ Vehicle I/F +
+
+
+ + + Vehicle I/F + + + + + + + + + +
+
+
+ Steering Angle +
+ Accel Pedal +
+ Brake Pedal +
+
+
+ + + Steering Angle... + + + + + + + + + +
+
+
+ Status +
+
+
+ + + Status + + + + + + + +
+
+
+ Vehicle I/F +
+
+
+ + + Vehicle I/F + + + + + + + + + +
+
+
+ Yaw Rate +
+ Velocity +
+
+
+ + + Yaw Rate... + + + + + + + + + +
+
+
+ Status +
+
+
+ + + Status + + + + + + + + + + +
+
+
+ Adapter +
+
+
+ + + Adapter + + + + + + + + + +
+
+
+ Vehicle I/F +
+
+
+ + + Vehicle I/F + + + + + + + +
+
+
+ Lateral Actuation +
+ Acceleration Actuation +
+ Deceleration Actuation +
+
+
+ + + Lateral Actuation... + + + + + + + +
+
+
+ Vehicle Driver +
+
+
+ + + Vehicle Driver + + + + + + + + + + +
+
+
+ vehicle +
+ configuration +
+
+
+ + + vehicle... + + + + + + + + + +
+
+
+ Control Component +
+
+
+ + + Control Component + + + + + + + +
+
+
+ ControlCommand: +
+ - Steering Angle +
+ - Steering Rate +
+ - Steering Torque +
+ - Velocity +
+ - Acceleration +
+
+
+ + + ControlCommand:... + + + + + + + +
+
+
+ ActuationCommand: +
+ - Lateral Actuation +
+ - Acceleration Actuation +
+ - Deceleration Actuation +
+
+
+ + + ActuationCommand:... + + + + + + + +
+
+
+ + ... + +
+
+
+ + + ... + + + + + + + + + + +
+
+
+ Auto Calibration +
+ Tools +
+
+
+ + + Auto Calibration... + + + + + + + +
+
+
+ Provided by OEMs or made/updated by calibration tools +
+
+
+ + + Provided by OEMs or made/update... + + + + + + + + + + + + + +
+
+
+ Generate generic control commands. +
+
+
+ + + Generate generic control commands. + + + + + + + +
+
+
+ Generate vehicle-specific control commands from generic control commands based on given configuration information. +
+
+
+ + + Generate vehicle-specific control comman... + + + + + + + +
+
+
+ Send control commands with vehicle-specific communication protocol. +
+
+
+ + + Send control commands with vehicle-speci... + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/control/index.md b/docs/design/autoware-architecture/control/index.md index a91185f72ee..65f977e5829 100644 --- a/docs/design/autoware-architecture/control/index.md +++ b/docs/design/autoware-architecture/control/index.md @@ -1,5 +1,102 @@ # Control component design -!!! warning +## Abstract - Under Construction +This document presents the design concept of the Control Component. The content is as follows: + +- [Autoware Control Design](#autoware-control-design) + - Outlining the policy for Autoware's control, which deals with only general information for autonomous driving systems and provides generic control commands to the vehicle. +- [Vehicle Adaptation Design](#vehicle-adaptation-design) + - Describing the policy for vehicle adaptation, which utilizes adapter mechanisms to standardize the characteristics of the vehicle's drive system and integrate it with Autoware. +- [Control Feature Design](#control-feature-design) + - Demonstrating the features provided by Autoware's control. + - Presenting the approach towards the functions installed in the vehicle such as ABS. + +## Autoware Control Design + +The Control Component generates the control signal to which the Vehicle Component subscribes. The generated control signals are computed based on the reference trajectories from the Planning Component. + +![control-component](image/control-component.drawio.svg) + +The Control Component consists of two modules. The `trajectory_follower` module generates a vehicle control command to follow the reference trajectory received from the planning module. The command includes, for example, the desired steering angle and target speed. The `vehicle_command_gate` is responsible for filtering the control command to prevent abnormal values and then sending it to the vehicle. This gate also allows switching between multiple sources such as the MRM (minimal risk maneuver) module or some remote control module, in addition to the trajectory follower. + +The Autoware control system is designed as a platform for automated driving systems that can be compatible with a diverse range of vehicles. + +The control process in Autoware uses general information (such as target acceleration and deceleration) and no vehicle-specific information (such as brake pressure) is used. Hence it can be adjusted independently of the vehicle's drive interface enabling easy integration or performance tuning. + +Furthermore, significant differences that affect vehicle motion constraints, such as two-wheel steering or four-wheel steering, are addressed by switching the control vehicle model, achieving control specialized for each characteristic. + +Autoware's control module outputs the necessary information to control the vehicle as a substitute for a human driver. For example, the control command from the control module looks like the following: + +```msg +- Target steering angle +- Target steering torque +- Target speed +- Target acceleration +``` + +Note that vehicle-specific values such as pedal positions and low-level information such as individual wheel rotation speeds are excluded from the command. + +## Vehicle Adaptation Design + +### Vehicle interface adapter + +Autoware is designed to be an autonomous driving platform able to accommodate vehicles with various drivetrain types. + +This is an explanation of how Autoware handles the standardization of systems with different vehicle drivetrains. The interfaces for vehicle drivetrains are diverse, including steering angle, steering angular velocity, steering torque, speed, accel/brake pedals, and brake pressure. To accommodate these differences, Autoware adds an adapter module between the control component and the vehicle interface. This module performs the conversion between the proprietary message types used by the vehicle (such as brake pressure) and the generic types used by Autoware (such as desired acceleration). By providing this conversion information, the differences in vehicle drivetrain can be accommodated. + +If the information is not known in advance, an automatic calibration tool can be used. Calibration will occur within limited degrees of freedom, generating the information necessary for the drivetrain conversion automatically. + +This configuration is summarized in the following diagram. + +![vehicle-abstraction](image/vehicle-interface-hw-abstraction.drawio.svg) + +### Examples of several vehicle interfaces + +This is an example of the several drivetrain types in the vehicle interface. + +| Vehicle | Lateral interface | Longitudinal interface | Note | +| ------------ | -------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| Lexus | Steering angle | Accel/brake pedal position | Acceleration lookup table conversion for longitudinal | +| JPN TAXI | Steering angle | Accel/brake pedal position | Acceleration lookup table conversion for longitudinal | +| GSM8 | Steering EPS voltage | Acceleration motor voltage, Deceleration brake hydraulic pressure | lookup table and PID conversion for lateral and longitudinal | +| YMC Golfcart | Steering angle | Velocity | | +| Logiees | yaw rate | Velocity | | +| F1 TENTH | Steering angle | Motor RPM | [interface code](https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/-/blob/master/src/drivers/vesc_interface/src/vesc_interface.cpp) | + +## Control Feature Design + +The following lists the features provided by Autoware's Control/Vehicle component, as well as the conditions and assumptions required to utilize them effectively. + +The proper operation of the ODD is limited by factors such as whether the functions are enabled, delay time, calibration accuracy and degradation rate, and sensor accuracy. + +| Feature | Description　 | Requirements/Assumptions | Note | 　Limitation for now | +| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Lateral Control | Control the drivetrain system related to lateral vehicle motion | | Trying to increase the number of vehicle types that can be supported in the future. | Only front-steering type is supported. | +| Longitudinal Control | Control the drivetrain system related to longitudinal vehicle motion | | | | +| Slope Compensation | Supports precise vehicle motion control on slopes | Gradient information can be obtained from maps or sensors attached to the chassis | If gradient information is not available, the gradient is estimated from the vehicle's pitch angle. | | +| Delay Compensation | Controls the drivetrain system appropriately in the presence of time delays | The drivetrain delay information is provided in advance | If there is no delay information, the drivetrain delay is estimated automatically (automatic calibration). However, the effect of delay cannot be completely eliminated, especially in scenarios with sudden changes in speed. | Only fixed delay times can be set for longitudinal and lateral drivetrain systems separately. It does not accommodate different delay times for the accelerator and brake. | +| Drivetrain IF Conversion (Lateral Control) | Converts the drivetrain-specific information of the vehicle into the drivetrain information used by Autoware (e.g., target steering angular velocity → steering torque) | The conversion information is provided in advance | If there is no conversion information, the conversion map is estimated automatically (automatic calibration). | The degree of freedom for conversion is limited (2D lookup table + PID FB). | +| Drivetrain IF Conversion (Longitudinal Control) | Converts the drivetrain-specific information of the vehicle into the drivetrain information used by Autoware (e.g., target acceleration → accelerator/brake pedal value) | The conversion information is provided in advance | If there is no conversion information, the conversion map is estimated automatically (automatic calibration). | The degree of freedom for conversion is limited (2D lookup table + PID FB). | +| Automatic Calibration | Automatically estimates and applies values such as drivetrain IF conversion map and delay time. | The drivetrain status can be obtained (must) | | | +| Anomaly Detection | Notifies when there is a discrepancy in the calibration or unexpected drivetrain behavior | The drivetrain status can be obtained (must) | | | +| Steering Zero Point Correction | Corrects the midpoint of the steering to achieve appropriate steering control | The drivetrain status can be obtained (must) | | | +| Steering Deadzone Correction | Corrects the deadzone of the steering to achieve appropriate steering control | The steering deadzone parameter is provided in advance | If the parameter is unknown, the deadzone parameter is estimated from driving information | Not available now | +| Steering Deadzone Estimation | Dynamically estimates the steering deadzone from driving data | | | Not available now | +| Weight Compensation | Performs appropriate vehicle control according to weight | Weight information can be obtained from sensors | If there is no weight sensor, estimate the weight from driving information. | Currently not available | +| Weight Estimation | Dynamically estimates weight from driving data | | | Currently not available | + +The list above does not cover wheel control systems such as ABS commonly used in vehicles. Regarding these features, the following considerations are taken into account. + +### Integration with vehicle-side functions + +ABS (Anti-lock Brake System) and ESC (Electric Stability Control) are two functions that may be pre-installed on a vehicle, directly impacting its controllability. +The control modules of Autoware assume that both ABS and ESC are installed on the vehicle and their absence may cause unreliable controls depending on the target ODD. For example, with low-velocity driving in a controlled environment, these functions are not necessary. + +Also, note that this statement does not negate the development of ABS functionality in autonomous driving systems. + +### Autoware Capabilities and Vehicle Requirements + +As an alternative to human driving, autonomous driving systems essentially aim to handle tasks that humans can perform. This includes not only controlling the steering wheel, accel, and brake, but also automatically detecting issues such as poor brake response or a misaligned steering angle. However, this is a trade-off, as better vehicle performance will lead to superior system behavior, ultimately affecting the design of ODD. + +On the other hand, for tasks that are not typically anticipated or cannot be handled by a human driver, processing in the vehicle ECU is expected. Examples of such scenarios include cases where the brake response is clearly delayed or when the vehicle rotates due to a single-side tire slipping. These tasks are typically handled by ABS or ESC. diff --git a/docs/design/autoware-architecture/map/index.md b/docs/design/autoware-architecture/map/index.md index 6912823c9cf..ee27ab96a3a 100644 --- a/docs/design/autoware-architecture/map/index.md +++ b/docs/design/autoware-architecture/map/index.md @@ -1,5 +1,102 @@ # Map component design +## 1. Overview + +Autoware relies on high-definition point cloud maps and vector maps of the driving environment to perform various tasks such as localization, route planning, traffic light detection, and predicting the trajectories of pedestrians and other vehicles. + +This document describes the design of map component of Autoware, including its requirements, architecture design, features, data formats, and interface to distribute map information to the rest of autonomous driving stack. + +## 2. Requirements + +Map should provide two types of information to the rest of the stack: + +- Semantic information about roads as a vector map +- Geometric information about the environment as a point cloud map (optional) + +A vector map contains highly accurate information about a road network, lane geometry, and traffic lights. It is required for route planning, traffic light detection, and predicting the trajectories of other vehicles and pedestrians. + +A 3D point cloud map is primarily used for LiDAR-based localization and part of perception in Autoware. In order to determine the current position and orientation of the vehicle, a live scan captured from one or more LiDAR units is matched against a pre-generated 3D point cloud map. Therefore, an accurate point cloud map is crucial for good localization results. However, if the vehicle has an alternate localization method with enough accuracy, for example using camera-based localization, point cloud map may not be required to use Autoware. + +## 3. Architecture + +!!! warning + + Under Construction + +## 4. Features + +!!! warning + + Under Construction + +## 5. Map Specification + +### Point Cloud Map + +The point cloud map must be supplied as a file with the following requirements: + +- It must be in the [PCD (Point Cloud Data) file format](https://pointclouds.org/documentation/tutorials/pcd_file_format.html), but can be a single PCD file or divided into multiple PCD files. +- Each point in the map must contain X, Y, and Z coordinates. +- An intensity or RGB value for each point may be optionally included. +- It must cover the entire operational area of the vehicle. It is also recommended to include an additional buffer zone according to the detection range of sensors attached to the vehicle. +- Its resolution should be at least 0.2 m to yield reliable localization results. +- It can be in either local or global coordinates, but must be in global coordinates (georeferenced) to use GNSS data for localization. + +!!! note + + Three global coordinate systems are currently supported by Autoware, including [Military Grid Reference System (MGRS)](https://en.wikipedia.org/wiki/Military_Grid_Reference_System), [Universal Transverse Mercator (UTM)](https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system), and [Japan Rectangular Coordinate System](https://ja.wikipedia.org/wiki/%E5%B9%B3%E9%9D%A2%E7%9B%B4%E8%A7%92%E5%BA%A7%E6%A8%99%E7%B3%BB). + However, MGRS is a preferred coordinate system for georeferenced maps. + In a map with MGRS coordinate system, the X and Y coordinates of each point represent the point's location within the 100,000-meter square, while the Z coordinate represents the point's elevation. + +If it is split into a single file, Autoware assumes the following directory structure by default. + +```bash +sample-map-rosbag +├── lanelet2_map.osm +├── pointcloud_map.pcd +``` + +If it is split into multiple files, Autoware assumes the following directory structure by default. + +```bash +sample-map-rosbag +├── lanelet2_map.osm +├── pointcloud_map +├── pcd_00.pcd +├── pcd_01.pcd +├── pcd_02.pcd +├── ... +└── pointcloud_map_metadata.yaml +``` + +Note that, if you split the map into multiple files, you must meet the following additional conditions: + +- It must be split by lines parallel to the x-y axis. +- Additional metadata must be provided as well. + +Metadata should look like as follows: + +```yaml +x_resolution: 100.0 +y_resolution: 150.0 +A.pcd: [1200, 2500] # -> 1200 < x < 1300, 2500 < y < 2650 +B.pcd: [1300, 2500] # -> 1300 < x < 1400, 2500 < y < 2650 +C.pcd: [1200, 2650] # -> 1200 < x < 1300, 2650 < y < 2800 +D.pcd: [1400, 2650] # -> 1400 < x < 1500, 2650 < y < 2800 +``` + +You may use [pointcloud_divider](https://github.com/MapIV/pointcloud_divider) from MAP IV for dividing pointcloud map as well as generating the compatible metadata.yaml. + +#### Vector Map + +The vector cloud map must be supplied as a file with the following requirements: + +- It must be in [Lanelet2](https://github.com/fzi-forschungszentrum-informatik/Lanelet2) format, with [additional modifications required by Autoware](https://github.com/autowarefoundation/autoware_common/blob/main/tmp/lanelet2_extension/docs/lanelet2_format_extension.md). +- It must contain the shape and position information of lanes, traffic lights, stop lines, crosswalks, parking spaces, and parking lots. +- Except at the beginning or end of a road, each lanelet in the map must be correctly connected to its predecessor, successors, left neighbor, and right neighbor. +- Each lanelet in the map must contain traffic rule information including its speed limit, right of way, traffic direction, associated traffic lights, stop lines, and traffic signs. +- It must cover the entire operational area of the vehicle. + !!! warning Under Construction diff --git a/docs/design/autoware-architecture/planning/image/features-adaptive-cruise.drawio.svg b/docs/design/autoware-architecture/planning/image/features-adaptive-cruise.drawio.svg new file mode 100644 index 00000000000..a02e0088582 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-adaptive-cruise.drawio.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-avoidance.drawio.svg b/docs/design/autoware-architecture/planning/image/features-avoidance.drawio.svg new file mode 100644 index 00000000000..9720c34ce03 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-avoidance.drawio.svg @@ -0,0 +1,15 @@ + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-blind-spot.drawio.svg b/docs/design/autoware-architecture/planning/image/features-blind-spot.drawio.svg new file mode 100644 index 00000000000..0dc0e3865e1 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-blind-spot.drawio.svg @@ -0,0 +1,24 @@ + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-crosswalk.drawio.svg b/docs/design/autoware-architecture/planning/image/features-crosswalk.drawio.svg new file mode 100644 index 00000000000..17d9452f8a8 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-crosswalk.drawio.svg @@ -0,0 +1,24 @@ + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-cut-in.drawio.svg b/docs/design/autoware-architecture/planning/image/features-cut-in.drawio.svg new file mode 100644 index 00000000000..094ffc7baad --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-cut-in.drawio.svg @@ -0,0 +1,17 @@ + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-decel-on-curve-obstacles.drawio.svg b/docs/design/autoware-architecture/planning/image/features-decel-on-curve-obstacles.drawio.svg new file mode 100644 index 00000000000..328fd0c5319 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-decel-on-curve-obstacles.drawio.svg @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-decel-on-curve.drawio.svg b/docs/design/autoware-architecture/planning/image/features-decel-on-curve.drawio.svg new file mode 100644 index 00000000000..a36583390e4 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-decel-on-curve.drawio.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-detection-area.drawio.svg b/docs/design/autoware-architecture/planning/image/features-detection-area.drawio.svg new file mode 100644 index 00000000000..aa0656bc169 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-detection-area.drawio.svg @@ -0,0 +1,18 @@ + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-intersection-traffic-jam.drawio.svg b/docs/design/autoware-architecture/planning/image/features-intersection-traffic-jam.drawio.svg new file mode 100644 index 00000000000..10177591fd4 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-intersection-traffic-jam.drawio.svg @@ -0,0 +1,26 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-intersection.drawio.svg b/docs/design/autoware-architecture/planning/image/features-intersection.drawio.svg new file mode 100644 index 00000000000..80de7420572 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-intersection.drawio.svg @@ -0,0 +1,28 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-lane-change.drawio.svg b/docs/design/autoware-architecture/planning/image/features-lane-change.drawio.svg new file mode 100644 index 00000000000..20f7b98fe88 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-lane-change.drawio.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-lane-follow.drawio.svg b/docs/design/autoware-architecture/planning/image/features-lane-follow.drawio.svg new file mode 100644 index 00000000000..324e3862333 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-lane-follow.drawio.svg @@ -0,0 +1,11 @@ + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-narrow-space-driving.drawio.svg b/docs/design/autoware-architecture/planning/image/features-narrow-space-driving.drawio.svg new file mode 100644 index 00000000000..ee55fd69109 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-narrow-space-driving.drawio.svg @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-no-stopping-area.drawio.svg b/docs/design/autoware-architecture/planning/image/features-no-stopping-area.drawio.svg new file mode 100644 index 00000000000..7159aed2202 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-no-stopping-area.drawio.svg @@ -0,0 +1,22 @@ + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-obstacle-decel.drawio.svg b/docs/design/autoware-architecture/planning/image/features-obstacle-decel.drawio.svg new file mode 100644 index 00000000000..c48e529b9c6 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-obstacle-decel.drawio.svg @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-obstacle-stop.drawio.svg b/docs/design/autoware-architecture/planning/image/features-obstacle-stop.drawio.svg new file mode 100644 index 00000000000..6e9595cf515 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-obstacle-stop.drawio.svg @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-occlusion-spot.drawio.svg b/docs/design/autoware-architecture/planning/image/features-occlusion-spot.drawio.svg new file mode 100644 index 00000000000..7da738574af --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-occlusion-spot.drawio.svg @@ -0,0 +1,18 @@ + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-parking.drawio.svg b/docs/design/autoware-architecture/planning/image/features-parking.drawio.svg new file mode 100644 index 00000000000..4fa74d36225 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-parking.drawio.svg @@ -0,0 +1,29 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-path-smoothing.drawio.svg b/docs/design/autoware-architecture/planning/image/features-path-smoothing.drawio.svg new file mode 100644 index 00000000000..6eaded25545 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-path-smoothing.drawio.svg @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-pull-out.drawio.svg b/docs/design/autoware-architecture/planning/image/features-pull-out.drawio.svg new file mode 100644 index 00000000000..8c67f0a8605 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-pull-out.drawio.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-pull-over.drawio.svg b/docs/design/autoware-architecture/planning/image/features-pull-over.drawio.svg new file mode 100644 index 00000000000..696d069d507 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-pull-over.drawio.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-route-planning.drawio.svg b/docs/design/autoware-architecture/planning/image/features-route-planning.drawio.svg new file mode 100644 index 00000000000..972c23fafac --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-route-planning.drawio.svg @@ -0,0 +1,103 @@ + + + + + + + + + + + + + + + + + +
+
+
+ + start + +
+
+
+ + + start + + + + + + +
+
+
+ + check +
+ point 1 + +
+
+
+ + + check... + + + + + + +
+
+
+ + check point 2 + +
+
+
+ + + check p... + + + + + + +
+
+
+ + goal + +
+
+
+ + + goal + + + + + + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-run-out.drawio.svg b/docs/design/autoware-architecture/planning/image/features-run-out.drawio.svg new file mode 100644 index 00000000000..783cb364852 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-run-out.drawio.svg @@ -0,0 +1,15 @@ + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-side-shift.drawio.svg b/docs/design/autoware-architecture/planning/image/features-side-shift.drawio.svg new file mode 100644 index 00000000000..0317f5abb28 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-side-shift.drawio.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-stop-line.drawio.svg b/docs/design/autoware-architecture/planning/image/features-stop-line.drawio.svg new file mode 100644 index 00000000000..6c7fe0cc020 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-stop-line.drawio.svg @@ -0,0 +1,42 @@ + + + + + + + + + + + + + + + +
+
+
+ + + STOP + + +
+
+
+ + + STOP + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-surround-check.drawio.svg b/docs/design/autoware-architecture/planning/image/features-surround-check.drawio.svg new file mode 100644 index 00000000000..a698da0add1 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-surround-check.drawio.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-traffic-light.drawio.svg b/docs/design/autoware-architecture/planning/image/features-traffic-light.drawio.svg new file mode 100644 index 00000000000..39cd9d0e0c9 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-traffic-light.drawio.svg @@ -0,0 +1,23 @@ + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/features-velocity-smoothing.drawio.svg b/docs/design/autoware-architecture/planning/image/features-velocity-smoothing.drawio.svg new file mode 100644 index 00000000000..3c239429c1f --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/features-velocity-smoothing.drawio.svg @@ -0,0 +1,86 @@ + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ + + speed limit + +
+ + 50 + + +
+
+
+ + + speed li... + + + + + + + + + + + + +
+
+
+ + + speed limit + +
+ + 30 + + +
+
+
+ + + speed li... + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/high-level-planning-diagram.drawio.svg b/docs/design/autoware-architecture/planning/image/high-level-planning-diagram.drawio.svg new file mode 100644 index 00000000000..bbf860704b2 --- /dev/null +++ b/docs/design/autoware-architecture/planning/image/high-level-planning-diagram.drawio.svg @@ -0,0 +1,582 @@ + + + + + + + + + +
+
+
+
+ Localization +
+
+ Component +
+
+
+
+ + + Localization... + + + + + + + +
+
+
+ Perception +
+ Component +
+
+
+ + + Perception... + + + + + + + + + +
+
+
+ Human +
+ Machine +
+ Interface +
+
+
+ + + Human... + + + + + + + +
+
+
+ API Layer +
+
+
+ + + API Layer + + + + + + + + + + + + +
+
+
+ + Mission Planning + +
+
+
+ + + Mission Planning + + + + + + + +
+
+
+ +
+ Scenario Planning + +
+
+
+ + + Scenario Planning + + + + + + + +
+
+
+ +
+ Lane Driving Scenario + +
+
+
+ + + Lane Driving Scenario + + + + + + + + + +
+
+
+ +
+ Parking Scenario + +
+
+
+ + + Parking Scenario + + + + + + + + + +
+
+
+ + Behavior Planning + +
+
+
+ + + Behavior Planning + + + + + + + + + +
+
+
+ + Motion Planning + +
+
+
+ + + Motion Planning + + + + + + + + + +
+
+
+ + Validation + +
+
+
+ + + Validation + + + + + + + +
+
+
+ Control Component +
+
+
+ + + Control Component + + + + + + + + +
+
+
+ + Planning Component + +
+
+
+ + + Planning Component + + + + + + + + + +
+
+
+
+ System +
+
+ Component +
+
+
+
+ + + System... + + + + + + + + + +
+
+
+ Map +
+ Component +
+
+
+ + + Map... + + + + + + + +
+
+
+
+ Lane Change +
+
+
+
+ + + Lane Change + + + + + + + +
+
+
+
+ Intersection +
+
+
+
+ + + Intersection + + + + + + + +
+
+
+
+ Crosswalk +
+
+
+
+ + + Crosswalk + + + + + + + +
+
+
+
+ etc... +
+
+
+
+ + + etc... + + + + + + + +
+
+
+
+ Path Smooth +
+
+
+
+ + + Path Smooth + + + + + + + +
+
+
+
+ Velocity Smooth +
+
+
+
+ + + Velocity Smooth + + + + + + + +
+
+
+
+ Collision Check +
+
+
+
+ + + Collision Check + + + + + + + +
+
+
+
+ etc... +
+
+
+
+ + + etc... + + + + + + + +
+
+
+
+ Free Space +
+
+
+
+ + + Free Space + + + + + + + +
+
+
+
+ Cost map +
+
+
+
+ + + Cost map + + + + + + + +
+
+
+
+ etc... +
+
+
+
+ + + etc... + + + + + + + + + + + + + + + +
+
+
+
+ Trajectory Validation +
+
+
+
+ + + Trajectory Validation + + + + + + + +
+
+
+
+ Route Planning +
+
+
+
+ + + Route Planning + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/docs/design/autoware-architecture/planning/image/planning-diagram.drawio.svg b/docs/design/autoware-architecture/planning/image/planning-diagram.drawio.svg index 1c2f1bc2022..45f9ed13045 100644 --- a/docs/design/autoware-architecture/planning/image/planning-diagram.drawio.svg +++ b/docs/design/autoware-architecture/planning/image/planning-diagram.drawio.svg @@ -1,16 +1,16 @@ - + - - - - - - + + + + + + -
+
Parking Scenario @@ -18,19 +18,19 @@
- + Parking Scenario - - - - + + + + -
+
route @@ -38,17 +38,17 @@
- + route - + -
+
mission_planner @@ -56,18 +56,18 @@
- + mission_planner - - + + -
+
path_with_lane_id @@ -75,20 +75,20 @@
- + path_with_lane_id - + - - + + -
+
path @@ -96,20 +96,20 @@
- + path - + - - + + -
+
Trajectory @@ -117,17 +117,17 @@
- + Trajectory - + -
+
obstacle_ @@ -137,18 +137,18 @@
- + obstacle_... - - + + -
+
Trajectory @@ -156,17 +156,17 @@
- + Trajectory - + -
+
obstacle_velocity_limiter @@ -174,18 +174,18 @@
- + obstacle_velocity_limiter - - + + -
+
Trajectory @@ -193,20 +193,20 @@
- + Trajectory - + - - + + -
+
Trajectory @@ -214,17 +214,17 @@
- + Trajectory - + -
+
scenario_selector @@ -232,18 +232,18 @@
- + scenario_selector - - + + -
+
@@ -253,17 +253,17 @@
- + Trajectory - + -
+
motion_velocity_ @@ -273,18 +273,18 @@
- + motion_velocity_... - - + + -
+
Trajectory @@ -292,17 +292,17 @@
- + Trajectory - + -
+
freespace_planner @@ -310,18 +310,18 @@
- + freespace_planner - - + + -
+
occupancy_grid @@ -329,17 +329,17 @@
- + occupancy_grid - + -
+
costmap_generator @@ -347,17 +347,17 @@
- + costmap_generator - + -
+
behavior @@ -369,16 +369,16 @@
- + behavior... - + -
+
behavior @@ -390,17 +390,17 @@
- + behavior... - - + + -
+
goal @@ -408,18 +408,18 @@
- + goal - - - + + + -
+
obstacle @@ -431,16 +431,16 @@
- + obstacle... - + -
+
slow_down @@ -448,16 +448,16 @@
- + slow_down - + -
+
adaptive_cruise @@ -465,16 +465,16 @@
- + adaptive_cruise - + -
+
stop @@ -482,16 +482,16 @@
- + stop - + -
+
LaneDriving Scenario @@ -499,16 +499,16 @@
- + LaneDriving Sce... - + -
+
@@ -520,16 +520,16 @@
- + Behavior Planning - + -
+
@@ -541,19 +541,19 @@
- + Motion Planning - - - - + + + + -
+
vector_map @@ -561,16 +561,16 @@
- + vector_map - + -
+
To Control @@ -578,17 +578,17 @@
- + To Control - - + + -
+
vector_map @@ -596,17 +596,17 @@
- + vector_map - - + + -
+
Dynamic Objects @@ -614,17 +614,17 @@
- + Dynamic Objects - - + + -
+
Dynamic Objects @@ -632,17 +632,17 @@
- + Dynamic Objects - - + + -
+
Dynamic Objects @@ -650,17 +650,17 @@
- + Dynamic Objects - - + + -
+
Dynamic Objects @@ -668,17 +668,17 @@
- + Dynamic Objects - - + + -
+
Obstacle Points @@ -686,17 +686,17 @@
- + Obstacle Points - - + + -
+
Obstacle Points @@ -704,17 +704,17 @@
- + Obstacle Points - - + + -
+
Dynamic Objects @@ -722,17 +722,17 @@
- + Dynamic Objects - - + + -
+
Obstacle Points @@ -740,17 +740,17 @@
- + Obstacle Points - - + + -
+
route (from mission_planner) @@ -758,17 +758,17 @@
- + route (from mission_planner) - - + + -
+
map @@ -776,19 +776,19 @@
- + map - - - - + + + + -
+
map @@ -796,17 +796,17 @@
- + map - - + + -
+
vehicle_state @@ -816,16 +816,16 @@
- + vehicle_state... - + -
+
@@ -835,17 +835,17 @@
- + Localization - - + + -
+
approval, @@ -855,17 +855,17 @@
- + approval,... - - + + -
+
external_crosswalk_states, @@ -877,16 +877,16 @@
- + external_crosswalk_states,... - + -
+
Planning @@ -894,17 +894,17 @@
- + Planning - - + + -
+
Traffic Light States @@ -912,17 +912,17 @@
- + Traffic Light States - - + + -
+
expand_stop_range @@ -930,16 +930,16 @@
- + expand_stop_range - + -
+
Perception @@ -947,17 +947,17 @@
- + Perception - - + + -
+
velocity_limit @@ -967,16 +967,16 @@
- + velocity_limit... - + -
+
Human @@ -988,18 +988,18 @@
- + Human... - - - + + + -
+
Perception @@ -1007,18 +1007,18 @@
- + Perception - - - + + + -
+
external_velocity @@ -1028,17 +1028,17 @@
- + external_velocity... - - + + -
+
velocity_limit @@ -1052,11 +1052,11 @@ - + -
+
avoidance @@ -1064,16 +1064,16 @@
- + avoidance - + -
+
side_shift @@ -1081,16 +1081,16 @@
- + side_shift - + -
+
lane_change @@ -1098,16 +1098,16 @@
- + lane_change - + -
+
lane_following @@ -1115,16 +1115,16 @@
- + lane_following - + -
+
pull_over @@ -1132,16 +1132,16 @@
- + pull_over - + -
+
pull_out @@ -1149,16 +1149,16 @@
- + pull_out - + -
+
blind_spot @@ -1166,16 +1166,16 @@
- + blind_spot - + -
+
cross_walk @@ -1183,16 +1183,16 @@
- + cross_walk - + -
+
stop_line @@ -1200,16 +1200,16 @@
- + stop_line - + -
+
traffic_light @@ -1217,16 +1217,16 @@
- + traffic_light - + -
+
intersection @@ -1234,16 +1234,16 @@
- + intersection - + -
+
detection_area @@ -1251,16 +1251,16 @@
- + detection_area - + -
+
no_stopping_area @@ -1268,16 +1268,16 @@
- + no_stopping_area - + -
+
virtual_traffic_light @@ -1285,16 +1285,16 @@
- + virtual_traffic_light - + -
+
occlusion_spot @@ -1302,16 +1302,16 @@
- + occlusion_spot - + -
+
run_out @@ -1319,17 +1319,17 @@
- + run_out - - + + -
+
check_point @@ -1337,17 +1337,17 @@
- + check_point - - + + -
+
vector_map @@ -1355,17 +1355,17 @@
- + vector_map - + -
+
surround_obstacle_checker @@ -1373,17 +1373,17 @@
- + surround_obstacle_checker - + -
+
(from other planning modules) @@ -1391,17 +1391,17 @@
- + (from othe... - - + + -
+
Obstacle Points @@ -1409,17 +1409,17 @@
- + Obstacle Points - - + + -
+
Dynamic Objects @@ -1427,17 +1427,17 @@
- + Dynamic Objects - - + + -
+
@@ -1447,17 +1447,17 @@
- + Trajectory - + -
+
planning_validator @@ -1465,7 +1465,7 @@
- + planning_validator diff --git a/docs/design/autoware-architecture/planning/index.md b/docs/design/autoware-architecture/planning/index.md index 81fa79fe4ab..48448b5a1cb 100644 --- a/docs/design/autoware-architecture/planning/index.md +++ b/docs/design/autoware-architecture/planning/index.md @@ -2,43 +2,122 @@ ## Overview -Planning stack acts as the “brain” of autonomous driving. It uses all the results from Localization, Perception, and Map stacks to decide its maneuver and gives final trajectory to Control stack. +The Planning component generates the trajectory message that will be subscribed to by the Control component based on the environmental state obtained from the Localization and the Perception components. -## Role +## Requirements -These are high-level roles of Planning stack: +The goal of the Planning component is to generate a trajectory (path and velocity) of the ego vehicle that is safe and well-regulated while satisfying the given mission. -- Calculates route that navigates to desired goal -- Plans trajectory to follow the route - - Make sure that vehicle does not collide with obstacles, including pedestrians and other vehicles - - Make sure that the vehicle follows traffic rules during the navigation. This includes following traffic light, stopping at stoplines, stopping at crosswalks, etc. -- Plan sequences of trajectories that is feasible for the vehicle. (e.g. no sharp turns that is kinematically impossible) +**Goals:** -## Input +- The basic functions are provided so that a simple ODD can be defined. +- The functionality is modularized to accommodate the third-party components. That is, a complicated or realistic ODD needs not be defined by the basic functions provided by default. +- The capability is extensible with the third-party components or the decision of human operators. +- The mechanism and policy are separated to allow the system or operators to change the behavior of the ego vehicle. Ultimately speaking, the policy can be set to crash an obstacle and the mechanism always follows. Otherwise, the system is not safe from the design point of view. -The table below summarizes the overall input into Planning stack: +**Non-goals:** -| Input | Topic Name(Data Type) | Explanation | -| ------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Vehicle Pose | `/tf (map->base_link)`
(_tf::tfMessage_) | Planning requires vehicle pose in map frame, which is the frame where all planning takes place. | -| Vehicle Kinematics | `/localization/kinematic_state`
(_nav_msgs/msg/Odometry_) | This includes vehicle's pose and velocity information. It is used to predict future pose on trajectory to detect collision with other objects. | -| Map data | `/map/vector_map`
(_autoware_auto_mapping_msgs/msg/HADMapBin_) | This includes all static information about the environment, such as:
  • Lane connection information used for route planning from starting position to goal position
  • Lane geometry to generate reference path used to calculate trajectory
  • All information related to traffic rules
| -| Detected Object Information | `/perception/object_recognition/objects`
(_autoware_auto_perception_msgs/msg/PredictedObjects_) | This includes information that cannot be known beforehand such as pedestrians and other vehicles. Planning stack will plan maneuvers to avoid collision with such objects. | -| Detected Obstacle Information | `/perception/obstacle_segmentation/pointcloud`
(_sensor_msgs/msg/PointCloud2_) | This includes information on the location of obstacles. This is more primitive information and is used for emergency stops, etc. | -| Occupancy Map Information | `/perception/occupancy_grid_map/map`
(_nav_msgs/msg/OccupancyGrid_) | This includes information that cannot be known beforehand such as pedestrians and other vehicles. Planning stack will plan maneuvers to avoid collision with such objects. | -| TrafficLight recognition result | `/perception/traffic_light_recognition/traffic_signals`
(_autoware_auto_perception_msgs/msg/TrafficSignalArray_) | This is the real time information about the state of each traffic light. Planning stack will extract the one that is relevant to planned path and use it to decide whether to stop at intersections. | -| Goal position | `/planning/mission_planning/goal`
(_geometry_msgs::PoseStamped_) | This is the final pose that Planning stack will try to achieve. | -| Check point position | `/planning/mission_planning/check_point`
(_geometry_msgs::PoseStamped_) | This is the midpoint that Planning will try to go at on the way to the destination. This is used when calculating the route. | +- The Planning component is not self-contained but can be extended with third parties. +- The Planning component is not aimed at the complete functionality and capability. +- The Planning component is not designed to always outperform human drivers. +- The Planning component is not capable of “never crashes”. -## Output +## High-level architecture -The table below summarizes the final output from Planning stack: +This diagram describes the high-level architecture of the Planning Component. -| Output | Topic(Data Type) | Explanation | -| ------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Trajectory | `/planning/trajectory`
(_autoware_auto_planning_msgs/msg/Trajectory_) | This is the sequence of pose, twist and acceleration that Control stack must follow. This must be smooth, and kinematically possible to follow by the Control stack. By default, the trajectory is 10 seconds long at 0.1 second resolution. | -| Turn Signal | `/planning/turn_indicators_cmd`
(_autoware_auto_vehicle_msgs/msg/TurnIndicatorsCommand_) | This is the output to control turn signals of the vehicle. Planning stack will make sure that turn signal will be turned on according to planned maneuver. | -| Hazard Signal | `/planning/hazard_lights_cmd`
(_autoware_auto_vehicle_msgs/msg/HazardLightsCommand_) | This is the output to control hazard signals of the vehicle. Planning stack will make sure that hazard signal will be turned on according to planned maneuver. | +![overall-planning-architecture](image/high-level-planning-diagram.drawio.svg) + +The Planning component consists of the following sub-components: + +- **Mission Planning**: Calculates the route based on the given goal and map information. +- **Scenario Planning**: Determines the trajectory based on the current scenario, such as Lane Driving or Parking. + - **Lane Driving**: Calculates the trajectory for driving within constructed lanes. + - **Behavior Planner**: Calculates suitable trajectory based on safety considerations and traffic rules. + - **Motion Planner**: Calculates suitable trajectory for the vehicle by taking into account safety factors, vehicle motion considerations, and instructions from the behavior planner. + - **Parking**: Calculates the trajectory for parking in unconstructed areas. +- **Validation**: Verifies the safety of the trajectory. + +## Component interface + +The following describes the input/output concept between Planning Component and other components. See [Planning Component Interface](/docs/design/autoware-interfaces/components/planning.md) for the current implementation. + +### Input to the planning component + +- **From Map** + - Vector map: Contains all static information about the environment, including lane connection information for route planning, lane geometry for generating a reference path, and traffic rule-related information. +- **From Perception** + - Detected object information: Provides real-time information about objects that cannot be known in advance, such as pedestrians and other vehicles. The Planning Component plans maneuvers to avoid collisions with these objects. + - Detected obstacle information: Supplies real-time information about the location of obstacles, which is more primitive than Detected Object and used for emergency stops and other safety measures. + - Occupancy map information: Offers real-time information about the presence of pedestrians and other vehicles and occluded area information. + - Traffic light recognition result: Provides the current state of each traffic light in real time. The Planning Component extracts relevant information for the planned path and determines whether to stop at intersections. +- **From Localization** + - Vehicle motion information: Includes the ego vehicle's position, velocity, acceleration, and other motion-related data. +- **From System** + - Operation mode: Indicates whether the vehicle is operating in Autonomous mode. +- **From Human Machine Interface (HMI)** + - Feature execution: Allows for executing/authorizing autonomous driving operations, such as lane changes or entering intersections, by human operators. +- **From API Layer** + - Goal: Represents the final position that the Planning Component aims to reach. + - Checkpoint: Represents a midpoint along the route to the destination. This is used during route calculation. + - Velocity limit: Sets the maximum speed limit for the vehicle. + +### Output from the planning component + +- **To Control** + - Trajectory: Provides a smooth sequence of pose, twist, and acceleration that the Control Component must follow. The trajectory is typically 10 seconds long with a 0.1-second resolution. + - Turn Signals: Controls the vehicle's turn indicators, such as right, left, hazard, etc. based on the planned maneuvers. +- **To System** + - Diagnostics: Reports the state of the Planning Component, indicating whether the processing is running correctly and whether a safe plan is being generated. +- **To Human Machine Interface (HMI)** + - Feature execution availability: Indicates the status of operations that can be executed or are required, such as lane changes or entering intersections. + - Trajectory candidate: Shows the potential trajectory that will be executed after the user's execution. +- **To API Layer** + - Planning factors: Provides information about the reasoning behind the current planning behavior. This may include the position of target objects to avoid, obstacles that led to the decision to stop, and other relevant information. + +## Supported Functions + +| Feature | Description | Requirements | Figure | +| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | +| Route Planning | Plan route from the ego vehicle position to the destination.

Reference implementation is in [Mission Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/mission_planner/), enabled by launching the `mission_planner` node. | - Lanelet map (driving lanelets) | ![route-planning](image/features-route-planning.drawio.svg) | +| Path Planning from Route | Plan path to be followed from the given route.

Reference implementation is in [Behavior Path Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_path_planner/). | - Lanelet map (driving lanelets) | ![lane-follow](image/features-lane-follow.drawio.svg) | +| Obstacle Avoidance | Plan path to avoid obstacles by steering operation.

Reference implementation is in [Avoidance](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_path_planner/docs/behavior_path_planner_avoidance_design/), [Obstacle Avoidance Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/obstacle_avoidance_planner/). Enable flag in parameter: `launch obstacle_avoidance_planner true` | - objects information | ![obstacle-avoidance](image/features-avoidance.drawio.svg) | +| Path Smoothing | Plan path to achieve smooth steering.

Reference implementation is in [Obstacle Avoidance Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/obstacle_avoidance_planner/). | - Lanelet map (driving lanelet) | ![path-smoothing](image/features-path-smoothing.drawio.svg) | +| Narrow Space Driving | Plan path to drive within the drivable area. Furthermore, when it is not possible to drive within the drivable area, stop the vehicle to avoid exiting the drivable area.

Reference implementation is in [Obstacle Avoidance Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/obstacle_avoidance_planner/). | - Lanelet map (high-precision lane boundaries) | ![narrow-space-driving](image/features-narrow-space-driving.drawio.svg) | +| Lane Change | Plan path for lane change to reach the destination.

Reference implementation is in [Lane Change](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_path_planner/docs/behavior_path_planner_lane_change_design/).. Enable flag in both parameters: | - Lanelet map (driving lanelets) | ![lane-change](image/features-lane-change.drawio.svg) | +| Pull Over | Plan path for pull over to park at the road shoulder.

Reference implementation is in [Goal Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_path_planner/docs/behavior_path_planner_goal_planner_design/). | - Lanelet map (shoulder lane) | ![pull-over](image/features-pull-over.drawio.svg) | +| Pull Out | Plan path for pull over to start from the road shoulder.

Reference implementation is in [Pull Out Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_path_planner/docs/behavior_path_planner_pull_out_design/). | - Lanelet map (shoulder lane) | ![pull-out](image/features-pull-out.drawio.svg) | +| Path Shift | Plan path in lateral direction in response to external instructions.

Reference implementation is in [Side Shift Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_path_planner/docs/behavior_path_planner_side_shift_design/). | - None | ![side-shift](image/features-side-shift.drawio.svg) | +| Obstacle Stop | Plan velocity to stop for an obstacle on the path.

Reference implementation is in [Obstacle Stop Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/obstacle_stop_planner/), [Obstacle Cruise Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/obstacle_cruise_planner/). `launch obstacle_stop_planner` and enable flag: `TODO`, `launch obstacle_cruise_planner` and enable flag: `TODO` | - objects information | ![obstacle-stop](image/features-obstacle-stop.drawio.svg) | +| Obstacle Deceleration | Plan velocity to decelerate for an obstacle located around the path.

Reference implementation is in [Obstacle Stop Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/obstacle_stop_planner/), [Obstacle Cruise Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/obstacle_cruise_planner/). | - objects information | ![obstacle-decel](image/features-obstacle-decel.drawio.svg) | +| Adaptive Cruise Control | Plan velocity to follow the vehicle driving in front of the ego vehicle.

Reference implementation is in [Obstacle Stop Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/obstacle_stop_planner/), [Obstacle Cruise Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/obstacle_cruise_planner/). | - objects information | ![adaptive-cruise](image/features-adaptive-cruise.drawio.svg) | +| Decelerate for cut-in vehicles | Plan velocity to avoid a risk for cutting-in vehicle to ego lane.

Reference implementation is in [Obstacle Cruise Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/obstacle_cruise_planner/). | - objects information | ![cut-in](image/features-cut-in.drawio.svg) | +| Surround Check at starting | Plan velocity to prevent moving when an obstacle exists around the vehicle.

Reference implementation is in [Surround Obstacle Checker](https://autowarefoundation.github.io/autoware.universe/main/planning/surround_obstacle_checker/). | - objects information | ![surround-check](image/features-surround-check.drawio.svg) | +| Curve Deceleration | Plan velocity to decelerate the speed on a curve.

Reference implementation is in [Motion Velocity Smoother](https://autowarefoundation.github.io/autoware.universe/main/planning/motion_velocity_smoother/). | - None | ![decel-on-curve](image/features-decel-on-curve.drawio.svg) | +| Curve Deceleration for Obstacle | Plan velocity to decelerate the speed on a curve for a risk of obstacle collision around the path.

Reference implementation is in [Obstacle Velocity Limiter](https://autowarefoundation.github.io/autoware.universe/main/planning/obstacle_velocity_limiter/). | - objects information
- Lanelet map (static obstacle) | ![decel-on-curve-obstacles](image/features-decel-on-curve-obstacles.drawio.svg) | +| Crosswalk | Plan velocity to stop or decelerate for pedestrians approaching or walking on a crosswalk.

Reference implementation is in [Crosswalk Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/crosswalk-design/). | - objects information
- Lanelet map (pedestrian crossing) | ![crosswalk](image/features-crosswalk.drawio.svg) | +| Intersection Oncoming Vehicle Check | Plan velocity for turning right/left at intersection to avoid a risk with oncoming other vehicles.

Reference implementation is in [Intersection Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/intersection-design/). | - objects information
- Lanelet map (intersection lane and yield lane) | ![intersection](image/features-intersection.drawio.svg) | +| Intersection Blind Spot Check | Plan velocity for turning right/left at intersection to avoid a risk with other vehicles or motorcycles coming from behind blind spot.

Reference implementation is in [Intersection Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/intersection-design/). | - objects information
- Lanelet map (intersection lane) | ![blind-spot](image/features-blind-spot.drawio.svg) | +| Intersection Occlusion Check | Plan velocity for turning right/left at intersection to avoid a risk with the possibility of coming vehicles from occlusion area.

Reference implementation is in [Intersection Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/intersection-design/). | - objects information
- Lanelet map (intersection lane) | WIP | +| Intersection Traffic Jam Detection | Plan velocity for intersection not to enter the intersection when a vehicle is stopped ahead for a traffic jam.

Reference implementation is in [Intersection Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/intersection-design/). | - objects information
- Lanelet map (intersection lane) | ![intersection-traffic-jam](image/features-intersection-traffic-jam.drawio.svg) | +| Traffic Light | Plan velocity for intersection according to a traffic light signal.

Reference implementation is in [Traffic Light Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/traffic-light-design/). | - Traffic light color information | ![traffic-light](image/features-traffic-light.drawio.svg) | +| Run-out Check | Plan velocity to decelerate for the possibility of nearby objects running out into the path.

Reference implementation is in [Run Out Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/run-out-design/). | - objects information | ![run-out](image/features-run-out.drawio.svg) | +| Stop Line | Plan velocity to stop at a stop line.

Reference implementation is in [Stop Line Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/stop-line-design/). | - Lanelet map (stop line) | ![stop-line](image/features-stop-line.drawio.svg) | +| Occlusion Spot Check | Plan velocity to decelerate for objects running out from occlusion area, for example, from behind a large vehicle.

Reference implementation is in [Occlusion Spot Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/occlusion-spot-design/). | - objects information
- Lanelet map (private/public lane) | ![occlusion-spot](image/features-occlusion-spot.drawio.svg) | +| No Stop Area | Plan velocity not to stop in areas where stopping is prohibited, such as in front of the fire station entrance.

Reference implementation is in [No Stopping Area Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/no-stopping-area-design/). | - Lanelet map (no stopping area) | ![no-stopping-area](image/features-no-stopping-area.drawio.svg) | +| Merge from Private Area to Public Road | Plan velocity for entering the public road from a private driveway to avoid a risk of collision with pedestrians or other vehicles.

Reference implementation is in [Merge from Private Area Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/merge-from-private-design/). | - objects information
- Lanelet map (private/public lane) | WIP | +| Speed Bump | Plan velocity to decelerate for speed bumps.

Reference implementation is in [Speed Bump Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/speed-bump-design/). | - Lanelet map (speed bump) | WIP | +| Detection Area | Plan velocity to stop at the corresponding stop when an object exist in the designated detection area.

Reference implementation is in [Detection Area Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/detection-area-design/). | - Lanelet map (detection area) | ![detection-area](image/features-detection-area.drawio.svg) | +| Out of ODD area | Plan velocity to stop before exiting the area designated by ODD (Operational Design Domain).

Reference implementation is in (WIP). | - Lanelet map (invalid lanelet) | WIP | +| Collision Detection when deviating from lane | Plan velocity to avoid conflict with other vehicles driving in the another lane when the ego vehicle is deviating from own lane.

Reference implementation is in [Out of Lane Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/out-of-lane-design/). | - objects information
- Lanelet map (driving lane) | WIP | +| Parking | Plan path and velocity for given goal in parking area.

Reference implementation is in [Free Space Planner](https://autowarefoundation.github.io/autoware.universe/main/planning/freespace_planner/). | - objects information
- Lanelet map (parking area) | ![parking](image/features-parking.drawio.svg) | +| Autonomous Emergency Braking (AEB) | Perform an emergency stop if a collision with an object ahead is anticipated. It is noted that this function is expected as a final safety layer, and this should work even in the event of failures in the Localization or Perception system.

Reference implementation is in [Out of Lane Module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_planner/out-of-lane-design/). | - Primitive objects | WIP | +| Minimum Risk Maneuver (MRM) | Provide appropriate MRM (Minimum Risk Maneuver) instructions when a hazardous event occurs. For example, when a sensor trouble found, send an instruction for emergency braking, moderate stop, or pulling over to the shoulder, depending on the severity of the situation.

Reference implementation is in TODO | - TODO | WIP | +| Trajectory Validation | Check the planned trajectory is safe. If it is unsafe, take appropriate action, such as modify the trajectory, stop sending the trajectory or report to the autonomous driving system.

Reference implementation is in [Planning Validator](https://autowarefoundation.github.io/autoware.universe/main/planning/planning_validator/). | - None | WIP | +| Running Lane Map Generation | Generate lane map from localization data recorded in manual driving.

Reference implementation is in WIP | - None | WIP | +| Running Lane Optimization | Optimize the centerline (reference path) of the map to make it smooth considering the vehicle kinematics.

Reference implementation is in [Static Centerline Optimizer](https://autowarefoundation.github.io/autoware.universe/main/planning/static_centerline_optimizer/). | - Lanelet map (driving lanes) | WIP | + + ## Implementation @@ -79,9 +158,15 @@ For more details, please refer to the design documents in each package. - [_external_velocity_limit_selector_](https://autowarefoundation.github.io/autoware.universe/main/planning/external_velocity_limit_selector/): takes an appropriate velocity limit from multiple candidates. - [_motion_velocity_smoother_](https://autowarefoundation.github.io/autoware.universe/main/planning/motion_velocity_smoother/): calculates final velocity considering velocity, acceleration, and jerk constraints. -## Supported Functions +## Important Parameters -![supported-functions](image/planning-functions.drawio.svg) +| Package | Parameter | Type | Description | +| ---------------------------- | ------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------ | +| `obstacle_stop_planner` | `stop_planner.stop_position.max_longitudinal_margin` | double | distance between the ego and the front vehicle when stopping (when `cruise_planner_type:=obstacle_stop_planner`) | +| `obstacle_cruise_planner` | `common.safe_distance_margin` | double | distance between the ego and the front vehicle when stopping (when `cruise_planner_type:=obstacle_cruise_planner`) | +| `behavior_path_planner` | `avoidance.avoidance.lateral.lateral_collision_margin` | double | minimum lateral margin to obstacle on avoidance | +| `behavior_path_planner` | `avoidance.avoidance.lateral.lateral_collision_safety_buffer` | double | additional lateral margin to obstacle if possible on avoidance | +| `obstacle_avoidance_planner` | `option.enable_outside_drivable_area_stop` | bool | If set true, a stop point will be inserted before the path footprint is outside the drivable area. | ## Notation @@ -99,6 +184,6 @@ Currently, the supported modules are as follows. - obstacle_stop_planner - motion_velocity_smoother -#### [2] Size of Path Points +### [2] Size of Path Points Some functions do not support paths with only one point. Therefore, each modules should generate the path with more than two path points. diff --git a/docs/design/autoware-architecture/sensing/data-types/point-cloud.md b/docs/design/autoware-architecture/sensing/data-types/point-cloud.md index 46731a8f91a..7c44603b7de 100644 --- a/docs/design/autoware-architecture/sensing/data-types/point-cloud.md +++ b/docs/design/autoware-architecture/sensing/data-types/point-cloud.md @@ -31,7 +31,7 @@ The modules used here are from [pointcloud_preprocessor package](https://github. For details about the modules, see [the following table](https://github.com/autowarefoundation/autoware.universe/tree/main/sensing/pointcloud_preprocessor#inner-workings--algorithms). -It is recommended that these modules are used in a single container as components. For details see [ROS2 Composition](https://docs.ros.org/en/rolling/Tutorials/Intermediate/Composition.html) +It is recommended that these modules are used in a single container as components. For details see [ROS 2 Composition](https://docs.ros.org/en/rolling/Tutorials/Intermediate/Composition.html) ## Point cloud fields @@ -199,8 +199,8 @@ The header of the point cloud message is expected to have the time of the earlie !!! note - The `sec` field is `int32` in ROS2 humble. The largest value it can represent is 2^31 seconds, it is subject to - year 2038 problems. We will wait for actions on ROS2 community side. + The `sec` field is `int32` in ROS 2 humble. The largest value it can represent is 2^31 seconds, it is subject to + year 2038 problems. We will wait for actions on ROS 2 community side. **More info at:** https://github.com/ros2/rcl_interfaces/issues/85 diff --git a/docs/design/autoware-interfaces/ad-api/index.md b/docs/design/autoware-interfaces/ad-api/index.md index 91e28c21d10..69247ea8a3d 100644 --- a/docs/design/autoware-interfaces/ad-api/index.md +++ b/docs/design/autoware-interfaces/ad-api/index.md @@ -3,3 +3,5 @@ !!! warning Under Construction + +See [here](../index.md) for an overview. diff --git a/docs/design/autoware-interfaces/components/.pages b/docs/design/autoware-interfaces/components/.pages index e1830c8e4d6..e06a4052a0e 100644 --- a/docs/design/autoware-interfaces/components/.pages +++ b/docs/design/autoware-interfaces/components/.pages @@ -2,5 +2,7 @@ nav: - index.md - planning.md - control.md + - localization.md + - map.md - vehicle-interface.md - vehicle-dimensions.md diff --git a/docs/design/autoware-interfaces/components/images/Localization-Bus-ODD-Architecture.drawio.svg b/docs/design/autoware-interfaces/components/images/Localization-Bus-ODD-Architecture.drawio.svg new file mode 100644 index 00000000000..d51e205fa97 --- /dev/null +++ b/docs/design/autoware-interfaces/components/images/Localization-Bus-ODD-Architecture.drawio.svg @@ -0,0 +1,4 @@ + + + +
Manual Inital Pose
Manual Inital Pose
geometry_msgs/msg/
PoseWithCovarianceStamped
geometry_msgs/msg/...
Localization
Localization
User Interface
User Interface
Planning
Planning
Map Server
Map Server
Pointcloud Map
Pointcloud Map
sensor_msgs/msg/PointCloud2
sensor_msgs/msg/PointCloud2
Control
Control
Sensing
Sensing
 Automatic Initial Pose
 Automatic Initial Pose
geometry_msgs/msg/
PoseWithCovarianceStamped
geometry_msgs/msg/...
IMU Data
IMU Data
sensor_msgs/msg/Imu
sensor_msgs/msg/Imu
Vehicle Interface
Vehicle Interface
Velocity Status
Velocity Status
autoware_auto_vehicle_msgs/
msg/VelocityReport
autoware_auto_vehicle_msgs/...
LiDAR Scanning
LiDAR Scanning
sensor_msgs/msg/PointCloud2
sensor_msgs/msg/PointCloud2
Vehicle Control Command
Vehicle Control Command
autoware_auto_vehicle_msgs/
msg/AckermannControlCommand
autoware_auto_vehicle_msgs/...
Trajectory
Trajectory
autoware_auto_planning_msgs/
msg/Trajectory
autoware_auto_planning_msgs/...
Vehicle Acceleration
Vehicle Acceleration
geometry_msgs/msg/
AccelWithCovarianceStamped
geometry_msgs/msg/...
Vehicle Kinematic State
Vehicle Kinematic State
autoware_msgs/autoware_localization_msgs/
msg/KinematicState
autoware_msgs/autoware_localization_msgs/...
Diagnostic Manager
Diagnostic Manager
LocalizationAccuracy
LocalizationAccuracy
Vehicle Twist
Vehicle Twist
geoTwistmetry_msgs/msg/
WithCovarianceStamped
geoTwistmetry_msgs/msg/...
Vehicle Pose
Vehicle Pose
geometry_msgs/msg/
PoseWithCovarianceStamped
geometry_msgs/msg/...Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/design/autoware-interfaces/components/images/Map-Bus-ODD-Architecture.drawio.svg b/docs/design/autoware-interfaces/components/images/Map-Bus-ODD-Architecture.drawio.svg new file mode 100644 index 00000000000..c6d679c4802 --- /dev/null +++ b/docs/design/autoware-interfaces/components/images/Map-Bus-ODD-Architecture.drawio.svg @@ -0,0 +1,4 @@ + + + +
Map Server
Map Server
Lanelet2 Map Marker
Lanelet2 Map Marker
visualization_msgs/msg/MarkerArray
visualization_msgs/msg/MarkerArray
Pointcloud Map
Pointcloud Map
sensor_msgs/msg/PointCloud2
sensor_msgs/msg/PointCloud2
Lanelet2 Map
Lanelet2 Map
autoware_auto_mapping_msgs/msg/
HADMapBin
autoware_auto_mapping_msgs/msg/...
Localization
Localization
Planning
Planning
Vehicle Kinematic State
Vehicle Kinematic State
nav_msg/msg/Odometry
nav_msg/msg/Odometry
Trajectory
Trajectory
autoware_auto_planning_msgs/msg/
Trajectory
autoware_auto_planning_msgs/msg/...
3D object Predictions
3D object Predictions
autoware_auto_perception_msgs/msg/
PredictedObjects
autoware_auto_perception_msgs/msg/...
Perception
Perception
Traffic Light Response
Traffic Light ResponseText is not SVG - cannot display \ No newline at end of file diff --git a/docs/design/autoware-interfaces/components/index.md b/docs/design/autoware-interfaces/components/index.md index d3170ab4fdc..3c0550cff93 100644 --- a/docs/design/autoware-interfaces/components/index.md +++ b/docs/design/autoware-interfaces/components/index.md @@ -3,3 +3,5 @@ !!! warning Under Construction + +See [here](../index.md) for an overview. diff --git a/docs/design/autoware-interfaces/components/localization.md b/docs/design/autoware-interfaces/components/localization.md new file mode 100644 index 00000000000..3c50e2b1eb2 --- /dev/null +++ b/docs/design/autoware-interfaces/components/localization.md @@ -0,0 +1,152 @@ +# Localization + +![Node diagram](images/Localization-Bus-ODD-Architecture.drawio.svg) + +## Inputs + +### Pointcloud Map + +Environment map created with point cloud, published by the map server. + +- sensor_msgs/msg/PointCloud2 + +A 3d point cloud map is used for LiDAR-based localization in Autoware. + +### Manual Initial Pose + +Start pose of ego, published by the user interface. + +- geometry_msgs/msg/PoseWithCovarianceStamped + - std_msgs/msg/Header header + - geometry_msgs/msg/PoseWithCovariance pose + - geometry_msgs/msg/Pose pose + - geometry_msgs/msg/Point position + - geometry_msg/msg/Quaternion orientation + - double[36] covariance + +### 3D-LiDAR Scanning + +LiDAR scanning for NDT matching, published by the LiDAR sensor. + +- sensor_msgs/msg/PointCloud2 + +The raw 3D-LiDAR data needs to be processed by the [point cloud pre-processing modules](../../autoware-architecture/sensing/data-types/point-cloud.md) before being used for localization. + +### Automatic Initial pose + +Start pose of ego, calculated from INS(Inertial navigation sensor) sensing data. + +- geometry_msgs/msg/PoseWithCovarianceStamped + - std_msgs/msg/Header header + - geometry_msgs/msg/PoseWithCovariance pose + - geometry_msgs/msg/Pose pose + - geometry_msgs/msg/Point position + - geometry_msg/msg/Quaternion orientation + - double[36] covariance + +When the initial pose is not set manually, the message can be used for automatic pose initialization. + +Current Geographic coordinate of the ego, published by the GNSS sensor. + +- sensor_msgs/msg/NavSatFix + - std_msgs/msg/Header header + - sensor_msgs/msg/NavSatStatus status + - double latitude + - double longitude + - double altitude + - double[9] position_covariance + - unit8 position_covariance_type + +Current orientation of the ego, published by the GNSS-INS. + +- autoware_sensing_msgs/msg/GnssInsOrientationStamped + - std_msgs/Header header + - autoware_sensing_msgs/msg/GnssInsOrientation orientation + - geometry_msgs/Quaternion orientation + - float32 rmse_rotation_x + - float32 rmse_rotation_y + - float32 rmse_rotation_z + +### IMU Data + +Current orientation, angular velocity and linear acceleration of ego, calculated from IMU sensing data. + +- sensor_msgs/msg/Imu + - std_msgs/msg/Header header + - geometry_msgs/msg/Quaternion orientation + - double[9] orientation_covariance + - geometry_msgs/msg/Vector3 angular_velocity + - double[9] angular_velocity_covariance + - geometry_msgs/msg/Vector3 linear_acceleration + - double[9] linear_acceleration_covariance + +### Vehicle Velocity Status + +Current velocity of the ego vehicle, published by the vehicle interface. + +- autoware_auto_vehicle_msgs/msg/VelocityReport + - std_msgs/msg/Header header; + - float longitudinal_velocity; + - float lateral_velocity; + - float heading_rate; + +Before the velocity input localization interface, module `vehicle_velocity_converter` converts message type `autoware_auto_vehicle_msgs/msg/VelocityReport` to `geometry_msgs/msg/TwistWithCovarianceStamped`. + +## Outputs + +### Vehicle pose + +Current pose of ego, calculated from localization interface. + +- geometry_msgs/msg/PoseWithCovarianceStamped + - std_msgs/msg/Header header + - geometry_msg/PoseWithCovariance pose + - geometry_msgs/msg/Pose pose + - geometry_msgs/msg/Point position + - geometry_msgs/msg/Quaternion orientation + - double[36] covariance + +### Vehicle velocity + +Current velocity of ego, calculated from localization interface. + +- geometry_msgs/msg/TwistWithCovarianceStamped + - std_msgs/msg/Header header + - geometry_msg/TwistWithCovariance twist + - geometry_msgs/msg/Twist twist + - geometry_msgs/msg/Vector3 linear + - geometry_msgs/msg/Vector3 angular + - double[36] covariance + +### Vehicle acceleration + +Current acceleration of ego, calculated from localization interface. + +- geometry_msgs/msg/AccelWithCovarianceStamped + - std_msgs/msg/Header header + - geometry_msg/AccelWithCovariance accel + - geometry_msgs/msg/Accel accel + - geometry_msgs/msg/Vector3 linear + - geometry_msgs/msg/Vector3 angular + - double[36] covariance + +### Vehicle kinematic state + +Current pose, velocity and acceleration of ego, calculated from localization interface. + +**Note:** Kinematic state contains pose, velocity and acceleration. In the future, [pose](#vehicle-pose), [velocity](#vehicle-velocity) and [acceleration](#vehicle-acceleration) will not be used as output for localization. + +- autoware_msgs/autoware_localization_msgs/msg/KinematicState + - std_msgs/msg/Header header + - string child_frame_id + - geometry_msgs/PoseWithCovariance pose_with_covariance + - geometry_msgs/TwistWithCovariance twist_with_covariance + - geometry_msgs/AccelWithCovariance accel_with_covariance + +The message will be subscribed by the planning and control module. + +### Localization Accuracy + +Diagnostics information that indicates if the localization module works properly. + +TBD. diff --git a/docs/design/autoware-interfaces/components/map.md b/docs/design/autoware-interfaces/components/map.md new file mode 100644 index 00000000000..578981ad963 --- /dev/null +++ b/docs/design/autoware-interfaces/components/map.md @@ -0,0 +1,42 @@ +# Map + +![Node diagram](./images/Map-Bus-ODD-Architecture.drawio.svg) + +## Overview + +Autoware relies on high-definition point cloud maps and vector maps of the driving environment to perform various tasks. Before launching Autoware, you need to load the pre-created map files. + +## Inputs + +- Point cloud maps (`.pcd`) +- Lanelet2 maps (`.osm`) + +Refer to [Creating maps](../../../how-to-guides/integrating-autoware/creating-maps/index.md) on how to create maps. + +## Outputs + +### Point cloud map + +It loads point cloud files and publishes the maps to the other Autoware nodes in various configurations. Currently, it supports the following types: + +- Raw point cloud map (sensor_msgs/msg/PointCloud2) +- Downsampled point cloud map (sensor_msgs/msg/PointCloud2) +- Partial point cloud map loading via ROS service (autoware_map_msgs/srv/GetPartialPointCloudMap) +- Differential point cloud map loading via ROS service (autoware_map_msgs/srv/GetDifferentialPointCloudMap) + +### Lanelet2 map + +It loads a Lanelet2 file and publishes the map data as `autoware_auto_mapping_msgs/msg/HADMapBin` message. The lan/lon coordinates are projected onto the MGRS coordinates. + +- autoware_auto_mapping_msgs/msg/HADMapBin + - std_msgs/Header header + - string version_map_format + - string version_map + - string name_map + - uint8[] data + +### Lanelet2 map visualization + +Visualize `autoware_auto_mapping_msgs/HADMapBin` messages in `Rviz`. + +- visualization_msgs/msg/MarkerArray diff --git a/docs/how-to-guides/.pages b/docs/how-to-guides/.pages index e57340ad3a1..e4f75c009f9 100644 --- a/docs/how-to-guides/.pages +++ b/docs/how-to-guides/.pages @@ -1,13 +1,4 @@ nav: - index.md - - advanced-usage-of-colcon.md - - creating-maps-for-autoware - - determining-component-dependencies.md - - integrating-autoware-with-your-vehicle.md - - integrating-autoware-with-a-diff-drive-vehicle.md - - running-autoware-without-cuda.md - - calibrating-your-sensors.md - - evaluating-controller-performance.md - - debug-autoware.md - - add-a-custom-ros-message.md - - fixing-dependent-package-versions.md + - Integrating Autoware: integrating-autoware + - others diff --git a/docs/how-to-guides/creating-maps-for-autoware.md b/docs/how-to-guides/creating-maps-for-autoware.md deleted file mode 100644 index 2dd313c55b7..00000000000 --- a/docs/how-to-guides/creating-maps-for-autoware.md +++ /dev/null @@ -1,80 +0,0 @@ -# Creating maps for Autoware - -Autoware relies on high-definition point cloud maps and vector maps of the driving environment to perform various tasks such as localization, route planning, traffic light detection, and predicting the trajectories of pedestrians and other vehicles. - -The specifications for point cloud and vector maps required by Autoware are given below, along with examples of both open-source and proprietary software that you can use to create them. - -## Point cloud maps - -A 3D point cloud map is primarily used for LiDAR-based localization in Autoware. In order to determine the current position and orientation of the vehicle, a live scan captured from one or more LiDAR units is matched against a pre-generated 3D point cloud map. Therefore, an accurate point cloud map is crucial for good localization results. - -### Point cloud map specifications - -- It must cover the entire operational area of the vehicle and should include an additional buffer zone of at least 200 m in all directions. -- It must be saved using the [PCD (Point Cloud Data) file format](https://pointclouds.org/documentation/tutorials/pcd_file_format.html), but can be a single PCD file or divided into multiple PCD files. -- Each point in the map must contain X, Y, and Z coordinates. -- An intensity or RGB value for each point may be optionally included. -- Its file size must be smaller than 1 GB, [as per the current ROS message size limit](https://github.com/ros/ros_comm/issues/902). -- Its resolution should be at least 0.2 m to yield reliable localization results. -- It can be in either local or global coordinates, but must be in global coordinates (georeferenced) to use GNSS data for localization. - -!!! note - - Three global coordinate systems are supported by Autoware, including [Military Grid Reference System (MGRS)](https://en.wikipedia.org/wiki/Military_Grid_Reference_System), [Universal Transverse Mercator (UTM)](https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system), and [Japan Rectangular Coordinate System](https://ja.wikipedia.org/wiki/%E5%B9%B3%E9%9D%A2%E7%9B%B4%E8%A7%92%E5%BA%A7%E6%A8%99%E7%B3%BB). - However, MGRS is a preferred coordinate system for georeferenced maps. - In a map with MGRS coordinate system, the X and Y coordinates of each point represent the point's location within the 100,000-meter square, while the Z coordinate represents the point's elevation. - -### Creating a point cloud map - -Traditionally, a Mobile Mapping System (MMS) is used in order to create highly accurate large-scale point cloud maps. However, since a MMS requires high-end sensors for precise positioning, its operational cost can be very expensive and may not be suitable for a relatively small driving environment. Alternatively, a Simultaneous Localization And Mapping (SLAM) algorithm can be used to create a point cloud map from recorded LiDAR scans. - -Commonly used open-source SLAM implementations are [lidarslam-ros2](https://github.com/rsasaki0109/lidarslam_ros2) (LiDAR, IMU\*) and [LIO-SAM](https://github.com/TixiaoShan/LIO-SAM/tree/ros2) (LiDAR, IMU, GNSS). The required sensor data for each algorithm is specified in the parentheses, where an asterisk (\*) indicates that such sensor data is optional. For supported LiDAR models, please check the Github repository of each algorithm. While these ROS 2-based SLAM implementations can be easily installed and used directly on the same machine that runs Autoware, it is important to note that they may not be as well-tested or as mature as ROS 1-based alternatives. - -The notable open-source SLAM implementations that are based on ROS 1 include [hdl-graph-slam](https://github.com/koide3/hdl_graph_slam) (LiDAR, IMU\*, GNSS\*), [LeGO-LOAM](https://github.com/facontidavide/LeGO-LOAM-BOR) (LiDAR, IMU\*), [LeGO-LOAM-BOR](https://github.com/RobustFieldAutonomyLab/LeGO-LOAM) (LiDAR), and [LIO-SAM](https://github.com/TixiaoShan/LIO-SAM) (LiDAR, IMU, GNSS). -Most of these algorithms already have a built-in loop-closure and pose graph optimization. However, if the built-in, automatic loop-closure fails or does not work correctly, you can use [Interactive SLAM](https://github.com/SMRT-AIST/interactive_slam) to adjust and optimize a pose graph manually. - -Since Autoware is based on ROS 2, it could be problematic if you want to install ROS 1-based SLAM implementations on the same machine. To avoid this problem, you can use [Docker](https://www.docker.com/) or simply install them on a different machine. Another problem is the ROSBAG version; these SLAM implementations require ROSBAG 1 instead of ROSBAG 2 used by Autoware. For the ROSBAG version problem, you may use this [stand-alone converter](https://gitlab.com/MapIV/rosbags) to convert a ROSBAG 2 file to a ROSBAG 1 file and vice versa. - -If you prefer proprietary software that is easy to use, you can try a fully automatic mapping tool from [MAP IV, Inc.](https://www.map4.jp/), [_MapIV Engine_](https://www.map4.jp/map4_engine_en). They currently provide a trial license for Autoware users free of charge. - -## Vector maps - -A vector map contains highly accurate information about a road network, lane geometry, and traffic lights. It is required for route planning, traffic light detection, and predicting the trajectories of other vehicles and pedestrians. - -### Vector map specifications - -- It must cover the entire operational area of the vehicle and should include an additional buffer zone of at least 200 m in all directions. -- It must be in [Lanelet2](https://github.com/fzi-forschungszentrum-informatik/Lanelet2) format, with [additional modifications required by Autoware](https://github.com/autowarefoundation/autoware_common/blob/main/tmp/lanelet2_extension/docs/lanelet2_format_extension.md). -- It must contain the shape and position information of lanes, traffic lights, stop lines, crosswalks, parking spaces, and parking lots. -- Each lanelet in the map must contain information regarding its right of way, speed limit, traffic direction, associated traffic lights, stop lines, and traffic signs. -- Except at the beginning or end of a road, each lanelet in the map must be correctly connected to its predecessor, successors, left neighbor, and right neighbor. - -### Creating a vector map - -The easiest way to create an Autoware-compatible vector map is to use [Vector Map Builder](https://tools.tier4.jp/feature/vector_map_builder_ll2/), a free web-based tool provided by [TIER IV, Inc.](https://www.tier4.jp/). -Vector Map Builder allows you to create lanes and add additional regulatory elements such as stop signs or traffic lights using a point cloud map as a reference. - -For open-source software options, [MapToolbox](https://github.com/autocore-ai/MapToolbox) is a plugin for [Unity](https://unity.com/) specifically designed to create Lanelet2 maps for Autoware. -Although [JOSM](https://josm.openstreetmap.de/) is another open-source tool that can be used to create Lanelet2 maps, be aware that a number of modifications must be done manually to make the map compatible with Autoware. This process can be tedious and time-consuming, so the use of JOSM is not recommended. - -## Autoware-compatible map providers - -If it is not possible to create HD maps yourself, you can use a mapping service from the following Autoware-compatible map providers instead: - -- [MAP IV, Inc.](https://www.map4.jp/) -- [AISAN TECHNOLOGY CO., LTD.](https://www.aisantec.co.jp/) -- [TomTom](https://www.tomtom.com/) - -The table below shows each company's mapping technology and the types of HD maps they support. - -| **Company** | **Mapping technology** | **Available maps** | -| --------------------------------------------------------- | ---------------------- | --------------------------- | -| [MAP IV, Inc.](https://www.map4.jp/) | SLAM | Point cloud and vector maps | -| [AISAN TECHNOLOGY CO., LTD.](https://www.aisantec.co.jp/) | MMS | Point cloud and vector maps | -| [TomTom](https://www.tomtom.com/) | MMS | Vector map\* | - -!!! note - - Maps provided by TomTom use their proprietary AutoStream format, not Lanelet2. - The open-source [AutoStreamForAutoware tool](https://github.com/tomtom-international/AutoStreamForAutoware) can be used to convert an AutoStream map to a Lanelet2 map. - However, the converter is still in its early stages and has some [known limitations](https://github.com/tomtom-international/AutoStreamForAutoware/blob/main/docs/known-issues.md). diff --git a/docs/how-to-guides/creating-maps-for-autoware/index.md b/docs/how-to-guides/creating-maps-for-autoware/index.md deleted file mode 100644 index 2dd313c55b7..00000000000 --- a/docs/how-to-guides/creating-maps-for-autoware/index.md +++ /dev/null @@ -1,80 +0,0 @@ -# Creating maps for Autoware - -Autoware relies on high-definition point cloud maps and vector maps of the driving environment to perform various tasks such as localization, route planning, traffic light detection, and predicting the trajectories of pedestrians and other vehicles. - -The specifications for point cloud and vector maps required by Autoware are given below, along with examples of both open-source and proprietary software that you can use to create them. - -## Point cloud maps - -A 3D point cloud map is primarily used for LiDAR-based localization in Autoware. In order to determine the current position and orientation of the vehicle, a live scan captured from one or more LiDAR units is matched against a pre-generated 3D point cloud map. Therefore, an accurate point cloud map is crucial for good localization results. - -### Point cloud map specifications - -- It must cover the entire operational area of the vehicle and should include an additional buffer zone of at least 200 m in all directions. -- It must be saved using the [PCD (Point Cloud Data) file format](https://pointclouds.org/documentation/tutorials/pcd_file_format.html), but can be a single PCD file or divided into multiple PCD files. -- Each point in the map must contain X, Y, and Z coordinates. -- An intensity or RGB value for each point may be optionally included. -- Its file size must be smaller than 1 GB, [as per the current ROS message size limit](https://github.com/ros/ros_comm/issues/902). -- Its resolution should be at least 0.2 m to yield reliable localization results. -- It can be in either local or global coordinates, but must be in global coordinates (georeferenced) to use GNSS data for localization. - -!!! note - - Three global coordinate systems are supported by Autoware, including [Military Grid Reference System (MGRS)](https://en.wikipedia.org/wiki/Military_Grid_Reference_System), [Universal Transverse Mercator (UTM)](https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system), and [Japan Rectangular Coordinate System](https://ja.wikipedia.org/wiki/%E5%B9%B3%E9%9D%A2%E7%9B%B4%E8%A7%92%E5%BA%A7%E6%A8%99%E7%B3%BB). - However, MGRS is a preferred coordinate system for georeferenced maps. - In a map with MGRS coordinate system, the X and Y coordinates of each point represent the point's location within the 100,000-meter square, while the Z coordinate represents the point's elevation. - -### Creating a point cloud map - -Traditionally, a Mobile Mapping System (MMS) is used in order to create highly accurate large-scale point cloud maps. However, since a MMS requires high-end sensors for precise positioning, its operational cost can be very expensive and may not be suitable for a relatively small driving environment. Alternatively, a Simultaneous Localization And Mapping (SLAM) algorithm can be used to create a point cloud map from recorded LiDAR scans. - -Commonly used open-source SLAM implementations are [lidarslam-ros2](https://github.com/rsasaki0109/lidarslam_ros2) (LiDAR, IMU\*) and [LIO-SAM](https://github.com/TixiaoShan/LIO-SAM/tree/ros2) (LiDAR, IMU, GNSS). The required sensor data for each algorithm is specified in the parentheses, where an asterisk (\*) indicates that such sensor data is optional. For supported LiDAR models, please check the Github repository of each algorithm. While these ROS 2-based SLAM implementations can be easily installed and used directly on the same machine that runs Autoware, it is important to note that they may not be as well-tested or as mature as ROS 1-based alternatives. - -The notable open-source SLAM implementations that are based on ROS 1 include [hdl-graph-slam](https://github.com/koide3/hdl_graph_slam) (LiDAR, IMU\*, GNSS\*), [LeGO-LOAM](https://github.com/facontidavide/LeGO-LOAM-BOR) (LiDAR, IMU\*), [LeGO-LOAM-BOR](https://github.com/RobustFieldAutonomyLab/LeGO-LOAM) (LiDAR), and [LIO-SAM](https://github.com/TixiaoShan/LIO-SAM) (LiDAR, IMU, GNSS). -Most of these algorithms already have a built-in loop-closure and pose graph optimization. However, if the built-in, automatic loop-closure fails or does not work correctly, you can use [Interactive SLAM](https://github.com/SMRT-AIST/interactive_slam) to adjust and optimize a pose graph manually. - -Since Autoware is based on ROS 2, it could be problematic if you want to install ROS 1-based SLAM implementations on the same machine. To avoid this problem, you can use [Docker](https://www.docker.com/) or simply install them on a different machine. Another problem is the ROSBAG version; these SLAM implementations require ROSBAG 1 instead of ROSBAG 2 used by Autoware. For the ROSBAG version problem, you may use this [stand-alone converter](https://gitlab.com/MapIV/rosbags) to convert a ROSBAG 2 file to a ROSBAG 1 file and vice versa. - -If you prefer proprietary software that is easy to use, you can try a fully automatic mapping tool from [MAP IV, Inc.](https://www.map4.jp/), [_MapIV Engine_](https://www.map4.jp/map4_engine_en). They currently provide a trial license for Autoware users free of charge. - -## Vector maps - -A vector map contains highly accurate information about a road network, lane geometry, and traffic lights. It is required for route planning, traffic light detection, and predicting the trajectories of other vehicles and pedestrians. - -### Vector map specifications - -- It must cover the entire operational area of the vehicle and should include an additional buffer zone of at least 200 m in all directions. -- It must be in [Lanelet2](https://github.com/fzi-forschungszentrum-informatik/Lanelet2) format, with [additional modifications required by Autoware](https://github.com/autowarefoundation/autoware_common/blob/main/tmp/lanelet2_extension/docs/lanelet2_format_extension.md). -- It must contain the shape and position information of lanes, traffic lights, stop lines, crosswalks, parking spaces, and parking lots. -- Each lanelet in the map must contain information regarding its right of way, speed limit, traffic direction, associated traffic lights, stop lines, and traffic signs. -- Except at the beginning or end of a road, each lanelet in the map must be correctly connected to its predecessor, successors, left neighbor, and right neighbor. - -### Creating a vector map - -The easiest way to create an Autoware-compatible vector map is to use [Vector Map Builder](https://tools.tier4.jp/feature/vector_map_builder_ll2/), a free web-based tool provided by [TIER IV, Inc.](https://www.tier4.jp/). -Vector Map Builder allows you to create lanes and add additional regulatory elements such as stop signs or traffic lights using a point cloud map as a reference. - -For open-source software options, [MapToolbox](https://github.com/autocore-ai/MapToolbox) is a plugin for [Unity](https://unity.com/) specifically designed to create Lanelet2 maps for Autoware. -Although [JOSM](https://josm.openstreetmap.de/) is another open-source tool that can be used to create Lanelet2 maps, be aware that a number of modifications must be done manually to make the map compatible with Autoware. This process can be tedious and time-consuming, so the use of JOSM is not recommended. - -## Autoware-compatible map providers - -If it is not possible to create HD maps yourself, you can use a mapping service from the following Autoware-compatible map providers instead: - -- [MAP IV, Inc.](https://www.map4.jp/) -- [AISAN TECHNOLOGY CO., LTD.](https://www.aisantec.co.jp/) -- [TomTom](https://www.tomtom.com/) - -The table below shows each company's mapping technology and the types of HD maps they support. - -| **Company** | **Mapping technology** | **Available maps** | -| --------------------------------------------------------- | ---------------------- | --------------------------- | -| [MAP IV, Inc.](https://www.map4.jp/) | SLAM | Point cloud and vector maps | -| [AISAN TECHNOLOGY CO., LTD.](https://www.aisantec.co.jp/) | MMS | Point cloud and vector maps | -| [TomTom](https://www.tomtom.com/) | MMS | Vector map\* | - -!!! note - - Maps provided by TomTom use their proprietary AutoStream format, not Lanelet2. - The open-source [AutoStreamForAutoware tool](https://github.com/tomtom-international/AutoStreamForAutoware) can be used to convert an AutoStream map to a Lanelet2 map. - However, the converter is still in its early stages and has some [known limitations](https://github.com/tomtom-international/AutoStreamForAutoware/blob/main/docs/known-issues.md). diff --git a/docs/how-to-guides/index.md b/docs/how-to-guides/index.md index 43594931ede..8d5aabb0274 100644 --- a/docs/how-to-guides/index.md +++ b/docs/how-to-guides/index.md @@ -1,17 +1,19 @@ # How-to guides -- [Advanced usage of colcon](advanced-usage-of-colcon.md) -- [Creating maps for Autoware](creating-maps-for-autoware/index.md) -- [Determining component dependencies](determining-component-dependencies.md) -- [Integrating Autoware with your vehicle](integrating-autoware-with-your-vehicle.md) -- [Integrating Autoware with a differential drive vehicle](integrating-autoware-with-a-diff-drive-vehicle.md) -- [Running Autoware without CUDA](running-autoware-without-cuda.md) -- [Calibrating your sensors](calibrating-your-sensors.md) -- [Applying Clang-Tidy to ROS packages](applying-clang-tidy-to-ros-packages.md) -- [Evaluating controller performance](evaluating-controller-performance.md) -- [Debug Autoware](debug-autoware.md) -- [Add a custom ROS message](add-a-custom-ros-message.md) -- [Fixing dependent package versions](fixing-dependent-package-versions.md) +## Integrating Autoware + +- [Overview](integrating-autoware/overview.md) + +## Others + +- [Debug Autoware](others/debug-autoware.md) +- [Running Autoware without CUDA](others/running-autoware-without-cuda.md) +- [Fixing dependent package versions](others/fixing-dependent-package-versions.md) +- [Add a custom ROS message](others/add-a-custom-ros-message.md) +- [Determining component dependencies](others/determining-component-dependencies.md) +- [Advanced usage of colcon](others/advanced-usage-of-colcon.md) +- [Applying Clang-Tidy to ROS packages](others/applying-clang-tidy-to-ros-packages.md) +- [Using Eagleye in Autoware](others/eagleye-integration-guide.md) TODO: Write the following contents. diff --git a/docs/how-to-guides/integrating-autoware/.pages b/docs/how-to-guides/integrating-autoware/.pages new file mode 100644 index 00000000000..7b7f62f439f --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/.pages @@ -0,0 +1,8 @@ +nav: + - overview.md + - 1. Creating your Autoware meta repository: creating-your-autoware-meta-repository.md + - 2. Creating vehicle and sensor description: creating-vehicle-and-sensor-description + - 3. Creating vehicle interface: creating-vehicle-interface-package + - 4. Creating maps: creating-maps + - 5. Launch Autoware: launch-autoware.md + - 6. Tuning parameters and performance: tuning-parameters-and-performance diff --git a/docs/how-to-guides/creating-maps-for-autoware/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/.pages similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/.pages rename to docs/how-to-guides/integrating-autoware/creating-maps/.pages diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/index.md new file mode 100644 index 00000000000..415a38b157a --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-maps/index.md @@ -0,0 +1,41 @@ +# Creating maps + +Autoware requires a pointcloud map and a vector map for the vehicle's operating environment. (Check the [map design documentation page](../../../design/autoware-architecture/map/index.md) for the detailed specification). + +This page explains how users can create maps that can be used for Autoware. + +## Creating a point cloud map + +Traditionally, a Mobile Mapping System (MMS) is used in order to create highly accurate large-scale point cloud maps. However, since a MMS requires high-end sensors for precise positioning, its operational cost can be very expensive and may not be suitable for a relatively small driving environment. Alternatively, a Simultaneous Localization And Mapping (SLAM) algorithm can be used to create a point cloud map from recorded LiDAR scans. Some of the useful open-source SLAM implementations are listed in this [page](open-source-slam/index.md). + +If you prefer proprietary software that is easy to use, you can try a fully automatic mapping tool from [MAP IV, Inc.](https://www.map4.jp/), [_MapIV Engine_](https://www.map4.jp/solutions/mapping_localization/map-%e2%85%b3-engine/). They currently provide a trial license for Autoware users free of charge. + +## Creating a vector map + +The easiest way to create an Autoware-compatible vector map is to use [Vector Map Builder](https://tools.tier4.jp/feature/vector_map_builder_ll2/), a free web-based tool provided by [TIER IV, Inc.](https://www.tier4.jp/). +Vector Map Builder allows you to create lanes and add additional regulatory elements such as stop signs or traffic lights using a point cloud map as a reference. + +For open-source software options, [MapToolbox](https://github.com/autocore-ai/MapToolbox) is a plugin for [Unity](https://unity.com/) specifically designed to create Lanelet2 maps for Autoware. +Although [JOSM](https://josm.openstreetmap.de/) is another open-source tool that can be used to create Lanelet2 maps, be aware that a number of modifications must be done manually to make the map compatible with Autoware. This process can be tedious and time-consuming, so the use of JOSM is not recommended. + +## Autoware-compatible map providers + +If it is not possible to create HD maps yourself, you can use a mapping service from the following Autoware-compatible map providers instead: + +- [MAP IV, Inc.](https://www.map4.jp/) +- [AISAN TECHNOLOGY CO., LTD.](https://www.aisantec.co.jp/) +- [TomTom](https://www.tomtom.com/) + +The table below shows each company's mapping technology and the types of HD maps they support. + +| **Company** | **Mapping technology** | **Available maps** | +| --------------------------------------------------------- | ---------------------- | --------------------------- | +| [MAP IV, Inc.](https://www.map4.jp/) | SLAM | Point cloud and vector maps | +| [AISAN TECHNOLOGY CO., LTD.](https://www.aisantec.co.jp/) | MMS | Point cloud and vector maps | +| [TomTom](https://www.tomtom.com/) | MMS | Vector map\* | + +!!! note + + Maps provided by TomTom use their proprietary AutoStream format, not Lanelet2. + The open-source [AutoStreamForAutoware tool](https://github.com/tomtom-international/AutoStreamForAutoware) can be used to convert an AutoStream map to a Lanelet2 map. + However, the converter is still in its early stages and has some [known limitations](https://github.com/tomtom-international/AutoStreamForAutoware/blob/main/docs/known-issues.md). diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/.pages similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/.pages rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/.pages diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-lc/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/.pages similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-lc/.pages rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/.pages diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-lc/images/config_info.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/config_info.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-lc/images/config_info.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/config_info.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-lc/images/extrinsic.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/extrinsic.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-lc/images/extrinsic.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/extrinsic.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-lc/images/fast-lio-lc-output.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/fast-lio-lc-output.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-lc/images/fast-lio-lc-output.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/fast-lio-lc-output.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-lc/images/fastlio_lc_example1.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/fastlio_lc_example1.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-lc/images/fastlio_lc_example1.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/fastlio_lc_example1.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-lc/images/fastlio_lc_example2.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/fastlio_lc_example2.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-lc/images/fastlio_lc_example2.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/fastlio_lc_example2.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-lc/images/launch.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/launch.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-lc/images/launch.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/images/launch.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-lc/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/index.md similarity index 99% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-lc/index.md rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/index.md index ac65e18f6da..eae8bfd74ec 100644 --- a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-lc/index.md +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-lc/index.md @@ -22,7 +22,7 @@ ### Dependencies -- Ubunutu 18.04 +- Ubuntu 18.04 - ROS Melodic - PCL >= 1.8, Follow [PCL Installation](https://pointclouds.org/downloads/#linux). - Eigen >= 3.3.4, Follow [Eigen Installation](http://eigen.tuxfamily.org/index.php?title=Main_Page). diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-slam/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/.pages similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-slam/.pages rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/.pages diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-slam/images/fast_lio_slam.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/fast_lio_slam.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-slam/images/fast_lio_slam.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/fast_lio_slam.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-slam/images/kaist03.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/kaist03.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-slam/images/kaist03.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/kaist03.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-slam/images/riverside02.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/riverside02.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-slam/images/riverside02.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/riverside02.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-slam/images/topic_name.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/topic_name.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-slam/images/topic_name.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/topic_name.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-slam/images/video.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/video.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-slam/images/video.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/images/video.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-slam/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/index.md similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fast-lio-slam/index.md rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fast-lio-slam/index.md diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fd-slam/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/.pages similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fd-slam/.pages rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/.pages diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fd-slam/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/index.md similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/fd-slam/index.md rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/fd-slam/index.md diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/hdl-graph-slam/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/.pages similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/hdl-graph-slam/.pages rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/.pages diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/hdl-graph-slam/images/example_1.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/example_1.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/hdl-graph-slam/images/example_1.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/example_1.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/hdl-graph-slam/images/example_2.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/example_2.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/hdl-graph-slam/images/example_2.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/example_2.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/hdl-graph-slam/images/hdl_400_graph.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/hdl_400_graph.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/hdl-graph-slam/images/hdl_400_graph.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/hdl_400_graph.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/hdl-graph-slam/images/hdl_400_points.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/hdl_400_points.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/hdl-graph-slam/images/hdl_400_points.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/hdl_400_points.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/hdl-graph-slam/images/hdl_graph_slam.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/hdl_graph_slam.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/hdl-graph-slam/images/hdl_graph_slam.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/hdl_graph_slam.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/hdl-graph-slam/images/lidar_topic.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/lidar_topic.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/hdl-graph-slam/images/lidar_topic.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/lidar_topic.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/hdl-graph-slam/images/reg_params.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/reg_params.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/hdl-graph-slam/images/reg_params.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/images/reg_params.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/hdl-graph-slam/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/index.md similarity index 96% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/hdl-graph-slam/index.md rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/index.md index 93581ca25aa..bf294c93a2f 100644 --- a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/hdl-graph-slam/index.md +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/hdl-graph-slam/index.md @@ -123,7 +123,7 @@ rosbag play --clock dataset.bag ## Papers -Kenji Koide, Jun Miura, and Emanuele Menegatti, A Portable 3D LIDAR-based System for Long-term and Wide-area People Behavior Measurement, Advanced Robotic Systems, 2019 [[link]](https://www.researchgate.net/publication/331283709_A_Portable_3D_LIDAR-based_System_for_Long-term_and_Wide-area_People_Behavior_Measurement). +Kenji Koide, Jun Miura, and Emanuele Menegatti, A Portable 3D LIDAR-based System for Long-term and Wide-area People Behavior Measurement, Advanced Robotic Systems, 2019 [[link]](https://www.researchgate.net/publication/331283709_A_portable_three-dimensional_LIDAR-based_system_for_long-term_and_wide-area_people_behavior_measurement). ## Contact diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/ia-lio-slam/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/.pages similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/ia-lio-slam/.pages rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/.pages diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/ia-lio-slam/images/Sejong_tunnel_data.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/Sejong_tunnel_data.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/ia-lio-slam/images/Sejong_tunnel_data.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/Sejong_tunnel_data.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/ia-lio-slam/images/Sejong_tunnel_data_lio_ai_lio.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/Sejong_tunnel_data_lio_ai_lio.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/ia-lio-slam/images/Sejong_tunnel_data_lio_ai_lio.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/Sejong_tunnel_data_lio_ai_lio.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/ia-lio-slam/images/Seq2.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/Seq2.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/ia-lio-slam/images/Seq2.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/Seq2.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/ia-lio-slam/images/config_info.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/config_info.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/ia-lio-slam/images/config_info.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/config_info.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/ia-lio-slam/images/extrinsic.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/extrinsic.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/ia-lio-slam/images/extrinsic.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/extrinsic.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/ia-lio-slam/images/fastlio_lc_example1.gif b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/fastlio_lc_example1.gif similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/ia-lio-slam/images/fastlio_lc_example1.gif rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/fastlio_lc_example1.gif diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/ia-lio-slam/images/fastlio_lc_example2.gif b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/fastlio_lc_example2.gif similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/ia-lio-slam/images/fastlio_lc_example2.gif rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/images/fastlio_lc_example2.gif diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/ia-lio-slam/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/index.md similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/ia-lio-slam/index.md rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/ia-lio-slam/index.md diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/index.md similarity index 77% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/index.md rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/index.md index 7f3f3237828..05ed2066cdc 100644 --- a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/index.md +++ b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/index.md @@ -1,6 +1,20 @@ -# Conclusions +# Available Open Source SLAM -As a conclusion, lidar odometry drifts accumulatively as time goes by and there is solutions to solve that problem such as graph optimization, loop closure and using gps sensor to decrease accumulative drift error. Because of that, a SLAM algorithm should have loop closure feature, graph optimization and should use gps sensor. Additionally, some of the algorithms are using IMU sensor to add another factor to graph for decreasing drift error. While some of the algorithms requires 9-axis IMU sensor strictly, some of them requires only 6-axis IMU sensor or not even using the IMU sensor. Before choosing an algorithm to create maps for Autoware please consider these factors depends on your sensor setup or expected quality of generated map. +This page provides the list of available open source Simultaneous Localization And Mapping (SLAM) implementation that can be used to generete a point cloud (.pcd) map file. + +## Selecting which implementation to use + +Lidar odometry drifts accumulatively as time goes by and there is solutions to solve that problem such as graph optimization, loop closure and using gps sensor to decrease accumulative drift error. Because of that, a SLAM algorithm should have loop closure feature, graph optimization and should use gps sensor. Additionally, some of the algorithms are using IMU sensor to add another factor to graph for decreasing drift error. While some of the algorithms requires 9-axis IMU sensor strictly, some of them requires only 6-axis IMU sensor or not even using the IMU sensor. Before choosing an algorithm to create maps for Autoware please consider these factors depends on your sensor setup or expected quality of generated map. + +## Tips + +Commonly used open-source SLAM implementations are [lidarslam-ros2](https://github.com/rsasaki0109/lidarslam_ros2) (LiDAR, IMU\*) and [LIO-SAM](https://github.com/TixiaoShan/LIO-SAM/tree/ros2) (LiDAR, IMU, GNSS). The required sensor data for each algorithm is specified in the parentheses, where an asterisk (\*) indicates that such sensor data is optional. For supported LiDAR models, please check the Github repository of each algorithm. While these ROS 2-based SLAM implementations can be easily installed and used directly on the same machine that runs Autoware, it is important to note that they may not be as well-tested or as mature as ROS 1-based alternatives. + +The notable open-source SLAM implementations that are based on ROS 1 include [hdl-graph-slam](https://github.com/koide3/hdl_graph_slam) (LiDAR, IMU\*, GNSS\*), [LeGO-LOAM](https://github.com/facontidavide/LeGO-LOAM-BOR) (LiDAR, IMU\*), [LeGO-LOAM-BOR](https://github.com/RobustFieldAutonomyLab/LeGO-LOAM) (LiDAR), and [LIO-SAM](https://github.com/TixiaoShan/LIO-SAM) (LiDAR, IMU, GNSS). + +Most of these algorithms already have a built-in loop-closure and pose graph optimization. However, if the built-in, automatic loop-closure fails or does not work correctly, you can use [Interactive SLAM](https://github.com/SMRT-AIST/interactive_slam) to adjust and optimize a pose graph manually. + +## List of Third Party SLAM Implementations

diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/iscloam/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/.pages similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/iscloam/.pages rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/.pages diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/iscloam/images/00.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/images/00.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/iscloam/images/00.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/images/00.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/iscloam/images/05.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/images/05.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/iscloam/images/05.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/images/05.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/iscloam/images/bag_name.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/images/bag_name.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/iscloam/images/bag_name.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/images/bag_name.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/iscloam/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/index.md similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/iscloam/index.md rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/iscloam/index.md diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lego-loam-bor/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/.pages similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lego-loam-bor/.pages rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/.pages diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lego-loam-bor/images/block.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/block.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lego-loam-bor/images/block.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/block.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lego-loam-bor/images/dataset-demo.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/dataset-demo.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lego-loam-bor/images/dataset-demo.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/dataset-demo.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lego-loam-bor/images/demo.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/demo.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lego-loam-bor/images/demo.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/demo.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lego-loam-bor/images/google-earth.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/google-earth.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lego-loam-bor/images/google-earth.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/google-earth.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lego-loam-bor/images/jackal-label.jpg b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/jackal-label.jpg similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lego-loam-bor/images/jackal-label.jpg rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/jackal-label.jpg diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lego-loam-bor/images/odometry.jpg b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/odometry.jpg similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lego-loam-bor/images/odometry.jpg rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/odometry.jpg diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lego-loam-bor/images/seg-total.jpg b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/seg-total.jpg similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lego-loam-bor/images/seg-total.jpg rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/images/seg-total.jpg diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lego-loam-bor/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/index.md similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lego-loam-bor/index.md rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lego-loam-bor/index.md diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lio-sam/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/.pages similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lio-sam/.pages rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/.pages diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lio-sam/images/pcd-map.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/images/pcd-map.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lio-sam/images/pcd-map.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/images/pcd-map.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lio-sam/images/system.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/images/system.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lio-sam/images/system.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/images/system.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lio-sam/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/index.md similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/lio-sam/index.md rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/lio-sam/index.md diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/optimized-sc-f-loam/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/.pages similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/optimized-sc-f-loam/.pages rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/.pages diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/optimized-sc-f-loam/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/index.md similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/optimized-sc-f-loam/index.md rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/optimized-sc-f-loam/index.md diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-a-loam/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/.pages similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-a-loam/.pages rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/.pages diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-a-loam/images/kitti05.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/images/kitti05.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-a-loam/images/kitti05.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/images/kitti05.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-a-loam/images/loop.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/images/loop.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-a-loam/images/loop.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/images/loop.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-a-loam/images/riverside01.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/images/riverside01.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-a-loam/images/riverside01.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/images/riverside01.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-a-loam/images/scancontext.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/images/scancontext.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-a-loam/images/scancontext.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/images/scancontext.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-a-loam/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/index.md similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-a-loam/index.md rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-a-loam/index.md diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-lego-loam/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/.pages similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-lego-loam/.pages rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/.pages diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-lego-loam/images/DCC.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/DCC.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-lego-loam/images/DCC.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/DCC.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-lego-loam/images/KAIST.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/KAIST.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-lego-loam/images/KAIST.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/KAIST.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-lego-loam/images/Riverside.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/Riverside.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-lego-loam/images/Riverside.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/Riverside.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-lego-loam/images/mulran_merged.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/mulran_merged.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-lego-loam/images/mulran_merged.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/mulran_merged.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-lego-loam/images/output.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/output.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-lego-loam/images/output.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/output.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-lego-loam/images/pangyo.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/pangyo.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-lego-loam/images/pangyo.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/pangyo.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-lego-loam/images/pangyo_merged.png b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/pangyo_merged.png similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-lego-loam/images/pangyo_merged.png rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/images/pangyo_merged.png diff --git a/docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-lego-loam/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/index.md similarity index 100% rename from docs/how-to-guides/creating-maps-for-autoware/open-source-slam/sc-lego-loam/index.md rename to docs/how-to-guides/integrating-autoware/creating-maps/open-source-slam/sc-lego-loam/index.md diff --git a/docs/how-to-guides/calibrating-your-sensors.md b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors.md similarity index 100% rename from docs/how-to-guides/calibrating-your-sensors.md rename to docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/calibrating-sensors.md diff --git a/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/creating-vehicle-and-sensor-description.md b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/creating-vehicle-and-sensor-description.md new file mode 100644 index 00000000000..7587e587b83 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-vehicle-and-sensor-description/creating-vehicle-and-sensor-description.md @@ -0,0 +1,5 @@ +# Creating vehicle and sensor description + +!!! warning + + Under Construction diff --git a/docs/how-to-guides/integrating-autoware/creating-vehicle-interface-package/creating-vehicle-interface-for-ackerman-kinematic-model.md b/docs/how-to-guides/integrating-autoware/creating-vehicle-interface-package/creating-vehicle-interface-for-ackerman-kinematic-model.md new file mode 100644 index 00000000000..6f68e0b2163 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-vehicle-interface-package/creating-vehicle-interface-for-ackerman-kinematic-model.md @@ -0,0 +1,5 @@ +# Creating vehicle interface for ackerman kinematic model + +!!! warning + + Under Construction diff --git a/docs/how-to-guides/integrating-autoware-with-a-diff-drive-vehicle.md b/docs/how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model.md similarity index 95% rename from docs/how-to-guides/integrating-autoware-with-a-diff-drive-vehicle.md rename to docs/how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model.md index 7357d81565e..fd833f3cf50 100644 --- a/docs/how-to-guides/integrating-autoware-with-a-diff-drive-vehicle.md +++ b/docs/how-to-guides/integrating-autoware/creating-vehicle-interface-package/customizing-for-differential-drive-model.md @@ -1,4 +1,4 @@ -# Integrating Autoware with a differential drive vehicle +# Customizing for differential drive vehicle ## 1. Introduction @@ -36,7 +36,7 @@ $$ where $l$ denotes wheel tread. -For information about other factors that need to be considered when creating a `vehicle_interface` package, refer to the [`vehicle_interface` component page](../design/autoware-interfaces/components/vehicle-interface.md). +For information about other factors that need to be considered when creating a `vehicle_interface` package, refer to the [`vehicle_interface` component page](../../../design/autoware-interfaces/components/vehicle-interface.md). ### 2.2 Set an appropriate `wheel_base` diff --git a/docs/how-to-guides/integrating-autoware/creating-your-autoware-meta-repository.md b/docs/how-to-guides/integrating-autoware/creating-your-autoware-meta-repository.md new file mode 100644 index 00000000000..eacfbe35c53 --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/creating-your-autoware-meta-repository.md @@ -0,0 +1,5 @@ +# Creating your Autoware meta repository + +!!! warning + + Under Construction diff --git a/docs/how-to-guides/images/integrating-autoware-with-your-vehicle/autoware-state-panel.png b/docs/how-to-guides/integrating-autoware/images/autoware-state-panel.png similarity index 100% rename from docs/how-to-guides/images/integrating-autoware-with-your-vehicle/autoware-state-panel.png rename to docs/how-to-guides/integrating-autoware/images/autoware-state-panel.png diff --git a/docs/contributing/coding-guidelines/ros-nodes/naming.md b/docs/how-to-guides/integrating-autoware/launch-autoware.md similarity index 66% rename from docs/contributing/coding-guidelines/ros-nodes/naming.md rename to docs/how-to-guides/integrating-autoware/launch-autoware.md index 6873692fef7..7c3aab759c8 100644 --- a/docs/contributing/coding-guidelines/ros-nodes/naming.md +++ b/docs/how-to-guides/integrating-autoware/launch-autoware.md @@ -1,4 +1,4 @@ -# Topic namespaces +# Launch Autoware !!! warning diff --git a/docs/how-to-guides/integrating-autoware-with-your-vehicle.md b/docs/how-to-guides/integrating-autoware/overview.md similarity index 58% rename from docs/how-to-guides/integrating-autoware-with-your-vehicle.md rename to docs/how-to-guides/integrating-autoware/overview.md index da592b14282..0eaec1bb889 100644 --- a/docs/how-to-guides/integrating-autoware-with-your-vehicle.md +++ b/docs/how-to-guides/integrating-autoware/overview.md @@ -1,10 +1,10 @@ -# Integrating Autoware with your vehicle +# Overview -## 1. Prepare your real vehicle hardware +## Requirement: prepare your real vehicle hardware Prerequisites for the vehicle: -- An onboard computer that satisfies the [Autoware installation prerequisites](../installation/autoware/source-installation.md#prerequisites) +- An onboard computer that satisfies the [Autoware installation prerequisites](../../installation/autoware/source-installation.md#prerequisites) - The following devices attached - Drive-by-wire interface - LiDAR @@ -12,24 +12,7 @@ Prerequisites for the vehicle: - Optional: Camera - Optional: GNSS -## 2. Create maps - -You need both a pointcloud map and a vector map in order to use Autoware. - -### Create a pointcloud map - -Use third-party tools such as a LiDAR-based SLAM (Simultaneous Localization And Mapping) package to create a pointcloud map in the `.pcd` format. -Some examples are: - -- [HDL](https://github.com/koide3/hdl_graph_slam) -- [LIO-SAM](https://github.com/TixiaoShan/LIO-SAM) -- [LiDAR-SLAM (ROS 2)](https://github.com/rsasaki0109/lidarslam_ros2) - -### Create vector map - -Use third-party tools such as [TIER IV's Vector Map Builder](https://tools.tier4.jp/) to create a Lanelet2 format `.osm` file. - -## 3. Create your Autoware meta-repository +## 1. Creating your Autoware meta-repository Create your Autoware meta-repository. One easy way is to fork [autowarefoundation/autoware](https://github.com/autowarefoundation/autoware) and clone it. @@ -41,7 +24,7 @@ git clone https://github.com/YOUR_NAME/autoware.git If you set up multiple types of vehicles, adding a suffix like "autoware.vehicle_A" or "autoware.vehicle_B" is recommended. -## 4. Create the description packages of your vehicle +## 2. Creating the your vehicle and sensor description Next, you need to create description packages that define the vehicle and sensor configuration of your vehicle. @@ -106,7 +89,7 @@ Create `launch/sensing.launch.xml` that launches the interfaces of all the senso ros2 launch autoware_launch planning_simulator.launch.xml vehicle_model:=YOUR_VEHICLE sensor_kit:=YOUR_SENSOR_KIT map_path:=/PATH/TO/YOUR/MAP ``` -## 5. Create a `vehicle_interface` package +## 3. Create a `vehicle_interface` package You need to create an interface package for your vehicle. The package is expected to provide the following two functions. @@ -114,16 +97,30 @@ The package is expected to provide the following two functions. 1. Receive command messages from `vehicle_cmd_gate` and drive the vehicle accordingly 2. Send vehicle status information to Autoware -You can find detailed information about the requirements of the `vehicle_interface` package in the [Vehicle Interface design documentation](../design/autoware-interfaces/components/vehicle-interface.md). +You can find detailed information about the requirements of the `vehicle_interface` package in the [Vehicle Interface design documentation](../../design/autoware-interfaces/components/vehicle-interface.md). You can also refer to TIER IV's [pacmod_interface repository](https://github.com/tier4/pacmod_interface) as an example of a vehicle interface package. -## 6. Launch Autoware +## 4. Create maps + +You need both a pointcloud map and a vector map in order to use Autoware. +For more information on map design, please click [here](../../design/autoware-architecture/map/index.md). + +### Create a pointcloud map + +Use third-party tools such as a LiDAR-based SLAM (Simultaneous Localization And Mapping) package to create a pointcloud map in the `.pcd` format. +For more information, please click [here](creating-maps/index.md). + +### Create vector map + +Use third-party tools such as [TIER IV's Vector Map Builder](https://tools.tier4.jp/) to create a Lanelet2 format `.osm` file. + +## 5. Launch Autoware This section briefly explains how to run your vehicle with Autoware. ### Install Autoware -Follow the [installation steps of Autoware](../installation/). +Follow the [installation steps of Autoware](../../installation/). ### Launch Autoware @@ -162,88 +159,10 @@ ros2 topic pub /autoware.YOURS/engage autoware_auto_vehicle_msgs/msg/Engage "eng You can also engage via RViz with "AutowareStatePanel". The panel can be found in `Panels > Add New Panel > tier4_state_rviz_plugin > AutowareStatePanel`. -![Autoware State Panel](images/integrating-autoware-with-your-vehicle/autoware-state-panel.png){: style="height:360px;width:640px"} +![Autoware State Panel](images/autoware-state-panel.png){: style="height:360px;width:640px"} Now the vehicle should drive along the calculated path! -## 7. Tune parameters for your vehicle & environment +## 6. Tune parameters for your vehicle & environment You may need to tune your parameters depending on the domain in which you will operate your vehicle. - -## 8. Customize your own package based on Autoware-msgs / Autoware-package - -In many practical applications, apart from the available nodes / modules of Autoware, you may have the need to create your own packages which communicate with Autoware nodes or utilize some Autoware implementations (such like math methods including A-star, interpolation, mpc algorithm and so on). In this case, you can follow the instructions below to customize your specific package. - -### Package using Autoware-msgs - -Since Autoware is built on ROS (Autoware Universe / Autoware Core on ROS 2), if you have the urge to communicate with other Autoware nodes, then you are supposed to obey the rule of node subscribing / publishing messages via topic in specified message type. For details, refer to the [ROS Tutorial](https://docs.ros.org/en/humble/Tutorials.html). - -If you are already experienced at ROS, then it's simple to do such an extension just like the following example. Here, as mentioned in section 5.1 above, how could vehicle interface package (such as driving-by-wire module) receives the control command? You can do: - -- Put the "autoware_auto_control_msgs" in your project with your own packages together -- Add the "depend" tag in "package.xml" of your package which receives the control command - -```xml -autoware_auto_control_msgs -``` - -- Add message path in "CMakeLists.txt" - -```cmake -find_package(autoware_auto_control_msgs) -``` - -- Include the header file of the message type and start coding - -```cpp -#include -``` - -### Package using Autoware-package - -For the current Autoware Universe (or Autoware Core later) based on ROS 2, the DDS (data distribution service) is applied as the middleware for real-time communication. Thus, it is not necessary for you to use ROS 2 for customization, as long as your platform has the ability to utilize the same DDS middleware to communicate with Autoware nodes. More in details, the extension could be divided into 2 aspects: - -- [Customization in ROS 2](#customization-in-ros-2) - -- [Customization in other platforms](#customization-in-other-platforms) - -#### Customization in ROS 2 - -In this case, the extension is just as simple as above. Here, the package "interpolation" is used as an example: - -- Put the "interpolation" in your project with your own packages together -- Add the "depend" tag in "package.xml" of your package which receives the control command - -```xml -interpolation -``` - -- Add message path in "CMakeLists.txt" - -```cmake -find_package(interpolation) -``` - -- Include the header file of the message type and start coding - -```cpp -#include "interpolation/linear_interpolation.hpp" -``` - -#### Customization in other platforms - -In this case, the compiled package shall be considered as a dynamic link library and could be linked with any project. You can configure the compile options, for example in "CMakeLists.txt": - -```cmake -target_include_directories(${node_name} PRIVATE /autoware/install/interpolation/include) -target_link_directories(${node_name} PRIVATE /autoware/install/interpolation/lib) -target_link_libraries(${node_name} PUBLIC interpolation) -``` - -Remember to replace the "${node_name}" with the correct name. And then you can include the header file and start coding - -```cpp -#include "interpolation/linear_interpolation.hpp" -``` - -If you have any issues or questions, feel free to create an [Autoware Foundation GitHub Discussion](https://github.com/orgs/autowarefoundation/discussions) in the Q&A category! diff --git a/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/.pages b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/.pages new file mode 100644 index 00000000000..9cb01955bdf --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/.pages @@ -0,0 +1,3 @@ +nav: + - evaluating-controller-performance.md + - evaluating-real-time-performance.md diff --git a/docs/how-to-guides/evaluating-controller-performance.md b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance.md similarity index 98% rename from docs/how-to-guides/evaluating-controller-performance.md rename to docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance.md index 82792a58544..50989f798f2 100644 --- a/docs/how-to-guides/evaluating-controller-performance.md +++ b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-controller-performance.md @@ -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/) page. +- If you have any problem with launching Autoware, please see the [tutorials](../../../tutorials/index.md) page. #### 3. Launch the control_performance_analysis package diff --git a/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance.md b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance.md new file mode 100644 index 00000000000..5005973432f --- /dev/null +++ b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/evaluating-real-time-performance.md @@ -0,0 +1,205 @@ +# Evaluating real-time performance + +## Introduction + +Autoware should be real-time system when integrated to a service. Therefore, the response time of each callback should be as small as possible. If Autoware appears to be slow, it is imperative to conduct performance measurements and implement improvements based on the analysis. However, Autoware is a complex software system comprising numerous ROS 2 nodes, potentially complicating the process of identifying bottlenecks. To address this challenge, we will discuss methods for conducting detailed performance measurements for Autoware and provide case studies. It is worth noting that multiple factors can contribute to poor performance, such as scheduling and memory allocation in the OS layer, but our focus in this page will be on user code bottlenecks. The outline of this section is as follows: + +- Performance measurement + - Single node execution + - Prepare separated cores + - Run single node separately + - Measurement and visualization +- Case studies + - Sensing component + - Planning component + +## Performance measurement + +Improvement is impossible without precise measurements. +To measure the performance of the application code, it is essential to eliminate any external influences. +Such influences include interference from the operating system and CPU frequency fluctuations. +Scheduling effects also occur when core resources are shared by multiple threads. +This section outlines a technique for accurately measuring the performance of the application code for a specific node. +Though this section only discusses the case of Linux on Intel CPUs, similar considerations should be made in other environments. + +### Single node execution + +To eliminate the influence of scheduling, the node being measured should operate independently, using the same logic as when the entire Autoware system is running. +To accomplish this, record all input topics of the node to be measured while the whole Autoware system is running. +To achieve this objective, a tool called [`ros2_single_node_replayer`](https://github.com/sykwer/ros2_single_node_replayer) has been prepared. + +Details on how to use the tool can be found in the README. +This tool records the input topics of a specific node during the entire Autoware operation and replays it in a single node with the same logic. +The tool relies on the `ros2 bag record` command, and the recording of service/action is not supported as of ROS 2 Humble, so nodes that use service/action as their main logic may not work well. + +### Prepare separated cores + +Isolated cores running the node to be measured must meet the following conditions. + +- Fix CPU frequency and disable turbo boost +- Minimize timer interruptions +- Offload RCU (Read Copy Update) callback +- Isolate the paired core if hyper-threading enabled + +To fulfill these conditions on Linux, a custom kernel build with the following kernel configurations is required. +You can find many resources to instruct you on how to build a custom Linux kernel (like [this one](https://phoenixnap.com/kb/build-linux-kernel)). +Note that even if full tickless is enabled, timer interrupts are generated for scheduling if more than two tasks exist in one core. + +```text +# Enable CONFIG_NO_HZ_FULL +-> General setup +-> Timers subsystem +-> Timer tick handling (Full dynticks system (tickless)) +(X) Full dynticks system (tickless) + +# Allows RCU callback processing to be offloaded from selected CPUs +# (CONFIG_RCU_NOCB_CPU=y) +-> General setup +-> RCU Subsystem +-*- Offload RCU callback processing from boot-selected CPUs +``` + +Additionally, the kernel boot parameters need to be set as follows. + +```text +GRUB_CMDLINE_LINUX_DEFAULT= + "... isolcpus=2,8 rcu_nocbs=2,8 rcu_nocb_poll nohz_full=2,8 intel_pstate=disable” +``` + +In the above configuration, for example, the node to be measured is assumed to run on core 2, and core 8, which is a hyper-threading pair, is also being isolated. +Appropriate decisions on which cores to run the measurement target and which nodes to isolate need to be made based on the cache and core layout of the measurement machine. +You can easily check if it is properly configured by running `cat /proc/softirqs`. +Since `intel_pstate=disable` is specified in the kernel boot parameter, `userspace` can be specified in the scaling governor. + +```shell +cat /sys/devices/system/cpu/cpu2/cpufreq/scaling_governor // ondemand +sudo sh -c "echo userspace > /sys/devices/system/cpu/cpu2/cpufreq/scaling_governor" +``` + +This allows you to freely set the desired frequency within a defined range. + +```shell +sudo sh -c "echo > /sys/devices/system/cpu/cpu2/cpufreq/scaling_setspeed" +``` + +Turbo Boost needs to be switched off on Intel CPUs, which is often overlooked. + +```shell +sudo sh -c "echo 0 > /sys/devices/system/cpu/cpufreq/boost" +``` + +### Run single node separately + +Following the instructions in the `ros2_single_node_replayer` README, start the node and play the dedicated rosbag created by the tool. +Before playing the rosbag, appropriately set the CPU affinity of the thread on which the node runs, so it is placed on the isolated core prepared. + +```shell +taskset --cpu-list -p +``` + +To avoid interference in the last level cache, minimize the number of other applications running during the measurement. + +### Measurement and visualization + +To visualize the performance of the measurement target, embed code for logging timestamps and performance counter values in the target source code. +To achieve this objective, a tool called [`pmu_analyzer`](https://github.com/sykwer/pmu_analyzer) has been prepared. + +Details on how to use the tool can be found in the README. +This tool can measure the turnaround time of any section in the source code, as well as various performance counters. + +## Case studies + +In this section, we will present several case studies that demonstrate the performance improvements. These examples not only showcase our commitment to enhancing the system's efficiency but also serve as a valuable resource for developers who may face similar challenges in their own projects. The performance improvements discussed here span various components of the Autoware system, including sensing modules and planning modules. There are tendencies for each component regarding which points are becoming bottlenecks. By examining the methods, techniques, and tools employed in these case studies, readers can gain a better understanding of the practical aspects of optimizing complex software systems like Autoware. + +### Sensing component + +First, we will explain the procedure for performance improvement, taking the node `ring_outlier_filter` as an example. +Refer to the [Pull Request](https://github.com/autowarefoundation/autoware.universe/pull/3014) for details. + +The following figure is a time-series plot of the turnaround time of the main processing part of `ring_outlier_filter`, analyzed as described in the "Performance Measurement" section above. + +![ring outlier filter turnaround time](https://raw.githubusercontent.com/autowarefoundation/autoware-documentation/0ad57338ca24b35f0a271c6ae003aa303b3dd4ce/docs/assets/images/ring_outlier_filter_turnaround_time.png) + +The horizontal axis indicates the number of callbacks called (i.e., callback index), and the vertical axis indicates the turnaround time. + +When analyzing the performance of the sensing module from the viewpoint of performance counter, pay attention to `instructions`, `LLC-load-misses`, `LLC-store-misses`, `cache-misses`, and `minor-faults`. + +Analysis of the performance counter shows that the largest fluctuations come from `minor-faults` (i.e., soft page faults), the second largest from `LLC-store-misses` and `LLC-load-misses` (i.e., cache misses in the last level cache), and the slowest fluctuations come from instructions (i.e., message data size fluctuations). +For example, when we plot `minor-faults` on the horizontal axis and turnaround time on the vertical axis, we can see the following dominant proportional relationship. + +![ring outlier filter minor faults](https://raw.githubusercontent.com/autowarefoundation/autoware-documentation/0ad57338ca24b35f0a271c6ae003aa303b3dd4ce/docs/assets/images/ring_outlier_filter_minor_faults.png) + +To achieve zero soft page faults, heap allocations must only be made from areas that have been first touched in advance. +We have developed a library called [`heaphook`](https://github.com/tier4/heaphook) to avoid soft page faults while running Autoware callback. +If you are interested, refer to the [GitHub discussion](https://github.com/orgs/autowarefoundation/discussions/3274) and the [issue](https://github.com/autowarefoundation/autoware/issues/3310). + +To reduce LLC misses, it is necessary to reduce the working set and to use cache-efficient access patterns. + +In the sensing component, which handles large message data such as LiDAR point cloud data, minimizing copying is important. +A callback that takes sensor data message types as input and output should be written in an in-place algorithm as much as possible. +This means that in the following pseudocode, when generating `output_msg` from `input_msg`, it is crucial to avoid using buffers as much as possible to reduce the number of memory copies. + +```cpp +void callback(const PointCloudMsg &input_msg) { + auto output_msg = allocate_msg(output_size); + fill(input_msg, output_msg); + publish(std::move(output_msg)); +} +``` + +To improve cache efficiency, implement an in-place style as much as possible, instead of touching memory areas sporadically. +In ROS applications using PCL, the code shown below is often seen. + +```cpp +void callback(const sensor_msgs::PointCloud2ConstPtr &input_msg) { + pcl::PointCloud::Ptr input_pcl(new pcl::PointCloud); + pcl::fromROSMsg(*input_msg, *input_pcl); + + // Algorithm is described for point cloud type of pcl + pcl::PointCloud::Ptr output_pcl(new pcl::PointCloud); + fill_pcl(*input_pcl, *output_pcl); + + auto output_msg = allocate_msg(output_size); + pcl::toROSMsg(*output_pcl, *output_msg); + publish(std::move(output_msg)); +} +``` + +To use the PCL library, `fromROSMsg()` and `toROSMsg()` are used to perform message type conversion at the beginning and end of the callback. +This is a wasteful copying process and should be avoided. +We should eliminate unnecessary type conversions by removing dependencies on PCL (e.g., ). +For large message types such as map data, there should be only one instance in the entire system in terms of physical memory. + +### Planning component + +First, we will pick up `detection_area` module in `behavior_velocity_planner` node, which tends to have long turnaround time. +We have followed the performance analysis steps above to obtain the following graph. +Axises are the same as the graphs in the sensing case study. + +![detection area turnaround time](https://raw.githubusercontent.com/autowarefoundation/autoware-documentation/36647431080a837a1c8a983faf5045d6524cee66/docs/assets/images/detection_area_turnaround_time.png) + +Using [`pmu_analyzer`](https://github.com/sykwer/pmu_analyzer) tool to further identify the bottleneck, we have found that the following multiple loops were taking up a lot of processing time: + +```cpp +for ( area : detection_areas ) + for ( point : point_clouds ) + if ( boost::geometry::within(point, area) ) + // do something with O(1) +``` + +It checks whether each point cloud is contained in each detection area. +Let `N` be the size of `point_clouds` and `M` be the size of `detection_areas`, then the computational complexity of this program is O(N^2 \* M), since the complexity of `within` is O(N). Here, given that most of the point clouds are located far away from a certain detection area, a certain optimization can be achieved. First, calculate the minimum enclosing circle that completely covers the detection area, and then check whether the points are contained in that circle. Most of the point clouds can be quickly ruled out by this method, we don’t have to call the `within` function in most cases. Below is the pseudocode after optimization. + +```cpp +for ( area : detection_areas ) + circle = calc_minimum_enclosing_circle(area) + for ( point : point_clouds ) + if ( point is in circle ) + if ( boost::geometry::within(point, area) ) + // do something with O(1) +``` + +By using O(N) algorithm for minimum enclosing circle, the computational complexity of this program is reduced to almost O(N \* (N + M)) (note that the exact computational complexity does not really change). +If you are interested, refer to the [Pull Request](https://github.com/autowarefoundation/autoware.universe/pull/2846). + +Similar to this example, in the planning component, we take into consideration thousands to tens of thousands of point clouds, thousands of points in a path representing our own route, and polygons representing obstacles and detection areas in the surroundings, and we repeatedly create paths based on them. Therefore, we access the contents of the point clouds and paths multiple times using for-loops. In most cases, the bottleneck lies in these naive for-loops. Here, understanding Big O notation and reducing the order of computational complexity directly leads to performance improvements. diff --git a/docs/how-to-guides/images/evaluating-controller-performance/controller-monitor.png b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/controller-monitor.png similarity index 100% rename from docs/how-to-guides/images/evaluating-controller-performance/controller-monitor.png rename to docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/controller-monitor.png diff --git a/docs/how-to-guides/images/evaluating-controller-performance/export-cvs.png b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/export-cvs.png similarity index 100% rename from docs/how-to-guides/images/evaluating-controller-performance/export-cvs.png rename to docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/export-cvs.png diff --git a/docs/how-to-guides/images/evaluating-controller-performance/import-data.png b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/import-data.png similarity index 100% rename from docs/how-to-guides/images/evaluating-controller-performance/import-data.png rename to docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/import-data.png diff --git a/docs/how-to-guides/images/evaluating-controller-performance/plot-xy.png b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/plot-xy.png similarity index 100% rename from docs/how-to-guides/images/evaluating-controller-performance/plot-xy.png rename to docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/plot-xy.png diff --git a/docs/how-to-guides/images/evaluating-controller-performance/start-plotjuggler.png b/docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/start-plotjuggler.png similarity index 100% rename from docs/how-to-guides/images/evaluating-controller-performance/start-plotjuggler.png rename to docs/how-to-guides/integrating-autoware/tuning-parameters-and-performance/images/evaluating-controller-performance/start-plotjuggler.png diff --git a/docs/how-to-guides/others/.pages b/docs/how-to-guides/others/.pages new file mode 100644 index 00000000000..1ac1fb2ba08 --- /dev/null +++ b/docs/how-to-guides/others/.pages @@ -0,0 +1 @@ +nav: diff --git a/docs/how-to-guides/add-a-custom-ros-message.md b/docs/how-to-guides/others/add-a-custom-ros-message.md similarity index 100% rename from docs/how-to-guides/add-a-custom-ros-message.md rename to docs/how-to-guides/others/add-a-custom-ros-message.md diff --git a/docs/how-to-guides/advanced-usage-of-colcon.md b/docs/how-to-guides/others/advanced-usage-of-colcon.md similarity index 100% rename from docs/how-to-guides/advanced-usage-of-colcon.md rename to docs/how-to-guides/others/advanced-usage-of-colcon.md diff --git a/docs/how-to-guides/applying-clang-tidy-to-ros-packages.md b/docs/how-to-guides/others/applying-clang-tidy-to-ros-packages.md similarity index 100% rename from docs/how-to-guides/applying-clang-tidy-to-ros-packages.md rename to docs/how-to-guides/others/applying-clang-tidy-to-ros-packages.md diff --git a/docs/how-to-guides/debug-autoware.md b/docs/how-to-guides/others/debug-autoware.md similarity index 77% rename from docs/how-to-guides/debug-autoware.md rename to docs/how-to-guides/others/debug-autoware.md index 2a48f6907ab..73d9ae028ef 100644 --- a/docs/how-to-guides/debug-autoware.md +++ b/docs/how-to-guides/others/debug-autoware.md @@ -4,18 +4,17 @@ This page provides some methods for debugging Autoware. ## Print debug messages -The essential thing for debug is to print the program information clearly, which can quickly judge the program operation and locate the problem. Autoware uses ROS2 logging tool to print debug messages, how to design console logging refer to tutorial [Console logging](../contributing/coding-guidelines/ros-nodes/console-logging.md). +The essential thing for debug is to print the program information clearly, which can quickly judge the program operation and locate the problem. Autoware uses ROS 2 logging tool to print debug messages, how to design console logging refer to tutorial [Console logging](../../contributing/coding-guidelines/ros-nodes/console-logging.md). -## Using ROS2 tools debug Autoware +## Using ROS tools debug Autoware ### Using command line tools -ROS2 includes a suite of command-line tools for introspecting a ROS2 system. The main entry point for the tools is the command `ros2`, which itself has various sub-commands for introspecting and working with nodes, topics, services, and more. How to use the ROS2 command line tool refer to tutorial [CLI tools](http://docs.ros.org/en/galactic/Tutorials/Beginner-CLI-Tools.html). +ROS 2 includes a suite of command-line tools for introspecting a ROS 2 system. The main entry point for the tools is the command `ros2`, which itself has various sub-commands for introspecting and working with nodes, topics, services, and more. How to use the ROS 2 command line tool refer to tutorial [CLI tools](http://docs.ros.org/en/galactic/Tutorials/Beginner-CLI-Tools.html). ### Using rviz2 -Rviz2 is a port of Rviz to ROS2. It provides a graphical interface for users to view their robot, sensor data, maps, and more. You can run Rviz2 tool easily by: -it will open +Rviz2 is a port of Rviz to ROS 2. It provides a graphical interface for users to view their robot, sensor data, maps, and more. You can run Rviz2 tool easily by: ```console rviz2 @@ -109,7 +108,7 @@ For more details, see the following official documentation for [Using ros2doctor ## Using a debugger with breakpoints -Many IDE(e.g. VSCode, CLion) supports debugging C/C++ executable with GBD on linux platform. The following lists some references for using the debugger: +Many IDE(e.g. Visual Studio Code, CLion) supports debugging C/C++ executable with GBD on linux platform. The following lists some references for using the debugger: - - diff --git a/docs/how-to-guides/determining-component-dependencies.md b/docs/how-to-guides/others/determining-component-dependencies.md similarity index 100% rename from docs/how-to-guides/determining-component-dependencies.md rename to docs/how-to-guides/others/determining-component-dependencies.md diff --git a/docs/how-to-guides/others/eagleye-integration-guide.md b/docs/how-to-guides/others/eagleye-integration-guide.md new file mode 100644 index 00000000000..8a4a29b0bae --- /dev/null +++ b/docs/how-to-guides/others/eagleye-integration-guide.md @@ -0,0 +1,128 @@ +# Using Eagleye with Autoware + +This page will show you how to set up [Eagleye](https://github.com/MapIV/eagleye) in order to use it with Autoware. +For the details of the integration proposal, please refer to [this](https://github.com/orgs/autowarefoundation/discussions/3257) Discussion. + +## What is Eagleye? + +Eagleye is an open-source GNSS/IMU-based localizer initially developed by [MAP IV. Inc](https://map4.jp/). It provides a cost-effective alternative to LiDAR and point cloud-based localization by using low-cost GNSS and IMU sensors to provide vehicle position, orientation, and altitude information. By integrating Eagleye into Autoware, users can choose between LiDAR and point cloud-based localization stacks or GNSS/IMU-based Eagleye localizer, depending on their specific needs and operating environment. + +## Architecture + +Eagleye can be utilized in the Autoware localization stack in two ways: + +1. Feed only twist into the EKF localizer. + + ![Eagleye twist integration](images/eagleye-integration-guide/eagleye_twist.drawio.svg) + +2. Feed both twist and pose from Eagleye into the EKF localizer (twist can also be used with regular `gyro_odometry`). + + ![Eagleye pose twist integration](images/eagleye-integration-guide/eagleye_pose_twist.drawio.svg) + +Note that RTK positioning is only required for localization using the Eagleye pose. RTK positioning is not required for twist. + +## Requirements + +GNSS/IMU/vehicle speed is required for Eagleye input. + +### IMU topic + +`sensor_msgs/msg/Imu` are supported for IMU. + +### Vehicle speed topic + +`geometry_msgs/msg/TwistStamped` and `geometry_msgs/msg/TwistWithCovarianceStamped` are supported for the input vehicle speed. + +### GNSS topic + +Eagleye requires latitude/longitude height information and velocity information generated by the GNSS receiver. +Your GNSS ROS driver must publish the following messages: + +- `sensor_msgs/msg/NavSatFix`: This message contains latitude, longitude, and height information. +- `geometry_msgs/msg/TwistWithCovarianceStamped`: This message contains gnss doppler velocity information. + +Eagleye has been tested with the following example GNSS ROS drivers: ublox_gps and septentrio_gnss_driver. The settings needed for each of these drivers are as follows: + +- [ublox_gps](https://github.com/KumarRobotics/ublox/tree/ros2/ublox_gps): This ROS driver publishes `sensor_msgs/msg/NavSatFix` and `geometry_msgs/msg/TwistWithCovarianceStamped` required by Eagleye with default settings. Therefore, no additional settings are required. +- [septentrio_gnss_driver](https://github.com/septentrio-gnss/septentrio_gnss_driver/tree/ros2): Set `publish.navsatfix` and `publish.twist` in the config file [`gnss.yaml`](https://github.com/septentrio-gnss/septentrio_gnss_driver/blob/ros2/config/gnss.yaml#L90) to `true` + +## Eagleye Setup + +### Install dependencies + +Clone the following three packages for Eagleye: + +1. [Eagleye](https://github.com/MapIV/eagleye.git) (autoware-main branch) +2. [RTKLIB ROS Bridge](https://github.com/MapIV/rtklib_ros_bridge.git) (ros2-v0.1.0 branch) +3. [LLH Converter](https://github.com/MapIV/llh_converter.git) (ros2 branch) + +### Modifying Autoware Launch files + +You need to install Eagleye-related packages and change Autoware's launcher. Four files are required in the Autoware localization launcher to run Eagleye: `eagleye_rt.launch.xml`, `eagleye_config.yaml`, `gnss_converter.launch.xml`, and `fix2pose.launch.xml`. + +You must correctly specify input topics for GNSS latitude, longitude, and height information, GNSS speed information, IMU information, and vehicle speed information in the [`eagleye_config.yaml`](https://github.com/MapIV/autoware_launch/blob/3f04a9dd7bc4a4c49d4ec790e3f6b9958ab822da/autoware_launch/config/localization/eagleye_config.param.yaml#L7-L16). + +```yaml +# Topic +twist: + twist_type: 1 # TwistStamped : 0, TwistWithCovarianceStamped: 1 + twist_topic: /sensing/vehicle_velocity_converter/twist_with_covariance +imu_topic: /sensing/imu/tamagawa/imu_raw +gnss: + velocity_source_type: 2 # rtklib_msgs/RtklibNav: 0, nmea_msgs/Sentence: 1, ublox_msgs/NavPVT: 2, geometry_msgs/TwistWithCovarianceStamped: 3 + velocity_source_topic: /sensing/gnss/ublox/navpvt + llh_source_type: 2 # rtklib_msgs/RtklibNav: 0, nmea_msgs/Sentence: 1, sensor_msgs/NavSatFix: 2 + llh_source_topic: /sensing/gnss/ublox/nav_sat_fix +``` + +Also, the frequency of GNSS and IMU must be set in [`eagleye_config.yaml`](https://github.com/MapIV/autoware_launch/blob/3f04a9dd7bc4a4c49d4ec790e3f6b9958ab822da/autoware_launch/config/localization/eagleye_config.param.yaml#L36) + +```yaml +common: + imu_rate: 50 + gnss_rate: 5 +``` + +The basic parameters that do not need to be changed except those mentioned above, i.e., topic names and sensors' frequency, are described below [here](https://github.com/MapIV/eagleye/tree/autoware-main/eagleye_rt/config). +Additionally, the parameters for converting `sensor_msgs/msg/NavSatFix` to `geometry_msgs/msg/PoseWithCovarianceStamped` is listed in [`fix2pose.yaml`](https://github.com/MapIV/eagleye/blob/autoware-main/eagleye_util/fix2pose/launch/fix2pose.xml). + +Please refer to `map4_localization_launch` in the `autoware.universe` package and `map4_localization_component.launch.xml` in `autoware_launch` package for information on how to modify the localization launch. + +Eagleye has a function for position estimation and a function for twist estimation, namely `pose_estimator` and `twist_estimator`, respectively. + +| localization launch | twist estimator | pose estimator | +| ----------------------------------------------------------------- | ----------------------------------- | ----------------------------------- | +| `tier4_localization_launch` | `gyro_odometry` | `ndt_scan_matcher` | +| `map4_localization_launch/eagleye_twist_localization_launch` | `eagleye_rt`(gyro/odom/gnss fusion) | `ndt_scan_matcher` | +| `map4_localization_launch/eagleye_pose_twist_localization_launch` | `eagleye_rt`(gyro/odom/gnss fusion) | `eagleye_rt`(gyro/odom/gnss fusion) | + +In Autoware, you can set the pose estimator to GNSS by setting `pose_estimator_mode:=gnss` in `map4_localization_component.launch.xml` in `autoware_launch` package. +Note that the output position might not appear to be in the point cloud maps if you are using maps that are not properly georeferenced. +In the case of a single GNSS antenna, initial position estimation (dynamic initialization) can take several seconds to complete after starting to run in an environment where GNSS positioning is available. + +Alternatively, the twist estimator can be set to Eagleye and the pose estimator to NDT by specifying `pose_estimator_mode:=lidar` in the same launch file. +Unlike Eagleye position estimation, Eagleye twist estimation first outputs uncorrected raw values when activated, and then outputs corrected twists as soon as static initialization is complete. + +## Executing Launch files + +### Execution command + +Enable Eagleye in Autoware by switching the localization module in autoware.launch.xml and the `pose_estimator_mode` parameter in `map4_localization_component.launch.xml` in `autoware.launch.xml`. + +When using Eagleye, comment out `tier4_localization_component.launch.xml` and start `map4_localization_component.launch.xml` in `autoware.launch.xml`. + +```xml + + + + + +``` + +#### Notes with initialization + +Eagleye requires an initialization process for proper operation. Without initialization, the output for twist will be in the raw value, and the pose data will not be available. + +The first step is static initialization, which involves allowing the Eagleye to remain stationary for approximately 5 seconds after startup to estimate the yaw-rate offset. + +The next step is dynamic initialization, which involves running the Eagleye in a straight line for approximately 30 seconds. This process estimates the scale factor of wheel speed and azimuth angle. Once dynamic initialization is complete, the Eagleye will be able to provide corrected twist and pose data. diff --git a/docs/how-to-guides/fixing-dependent-package-versions.md b/docs/how-to-guides/others/fixing-dependent-package-versions.md similarity index 100% rename from docs/how-to-guides/fixing-dependent-package-versions.md rename to docs/how-to-guides/others/fixing-dependent-package-versions.md diff --git a/docs/how-to-guides/images/determining-component-dependencies/perception_stack_dependencies.png b/docs/how-to-guides/others/images/determining-component-dependencies/perception_stack_dependencies.png similarity index 100% rename from docs/how-to-guides/images/determining-component-dependencies/perception_stack_dependencies.png rename to docs/how-to-guides/others/images/determining-component-dependencies/perception_stack_dependencies.png diff --git a/docs/how-to-guides/others/images/eagleye-integration-guide/eagleye_pose_twist.drawio.svg b/docs/how-to-guides/others/images/eagleye-integration-guide/eagleye_pose_twist.drawio.svg new file mode 100644 index 00000000000..4b0f24f10cf --- /dev/null +++ b/docs/how-to-guides/others/images/eagleye-integration-guide/eagleye_pose_twist.drawio.svg @@ -0,0 +1,4 @@ + + + +
Eagleye
Eagleye
IMU
IMU
EKF
EKF
GNSS
GNSS
Wheel
Odometry
Wheel...
twist with
covariance
twist with...
pose with
covariance
pose with...Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/how-to-guides/others/images/eagleye-integration-guide/eagleye_twist.drawio.svg b/docs/how-to-guides/others/images/eagleye-integration-guide/eagleye_twist.drawio.svg new file mode 100644 index 00000000000..11d6cfa80f8 --- /dev/null +++ b/docs/how-to-guides/others/images/eagleye-integration-guide/eagleye_twist.drawio.svg @@ -0,0 +1,4 @@ + + + +
Eagleye
Eagleye
IMU
IMU
3DLiDAR
3DLiDAR
NDT
NDT
EKF
EKF
GNSS
GNSS
Wheel
Odometry
Wheel...
pose with
covariance
pose with...
twist with
covariance
twist with...Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/how-to-guides/running-autoware-without-cuda.md b/docs/how-to-guides/others/running-autoware-without-cuda.md similarity index 100% rename from docs/how-to-guides/running-autoware-without-cuda.md rename to docs/how-to-guides/others/running-autoware-without-cuda.md diff --git a/docs/installation/autoware/source-installation.md b/docs/installation/autoware/source-installation.md index c3289c96a40..48135006ccd 100644 --- a/docs/installation/autoware/source-installation.md +++ b/docs/installation/autoware/source-installation.md @@ -31,35 +31,35 @@ sudo apt-get -y install git cd autoware ``` -2. You can install the dependencies either manually or using the provided Ansible script. +2. If you are installing Autoware for the first time, you can automatically install the dependencies by using the provided Ansible script. -> Note: Before installing NVIDIA libraries, confirm and agree with the licenses. + ```bash + ./setup-dev-env.sh + ``` -- [CUDA](https://docs.nvidia.com/cuda/eula/index.html) -- [cuDNN](https://docs.nvidia.com/deeplearning/cudnn/sla/index.html) -- [TensorRT](https://docs.nvidia.com/deeplearning/tensorrt/sla/index.html) + If you encounter any build issues, please consult the [Troubleshooting](../../support/troubleshooting.md#build-issues) section for assistance. -### Installing dependencies manually +!!! info -- [Install ROS 2](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/ros2#manual-installation) -- [Install ROS 2 Dev Tools](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/ros2_dev_tools#manual-installation) -- [Install the RMW Implementation](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/rmw_implementation#manual-installation) -- [Install pacmod](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/pacmod#manual-installation) -- [Install Autoware Core dependencies](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/autoware_core#manual-installation) -- [Install Autoware Universe dependencies](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/autoware_universe#manual-installation) -- [Install pre-commit dependencies](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/pre_commit#manual-installation) -- [Install Nvidia CUDA](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/cuda#manual-installation) -- [Install Nvidia cuDNN and TensorRT](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/tensorrt#manual-installation) + Before installing NVIDIA libraries, please ensure that you have reviewed and agreed to the licenses. -### Installing dependencies using Ansible + - [CUDA](https://docs.nvidia.com/cuda/eula/index.html) + - [cuDNN](https://docs.nvidia.com/deeplearning/cudnn/sla/index.html) + - [TensorRT](https://docs.nvidia.com/deeplearning/tensorrt/sla/index.html) -Be very careful with this method. Make sure you read and confirmed all the steps in the Ansible configuration before using it. +!!! note -If you've manually installed the dependencies, you can skip this section. + The following items will be automatically installed. If the ansible script doesn't work or if you already have different versions of dependent libraries installed, please install the following items manually. -```bash -./setup-dev-env.sh -``` + - [Install ROS 2](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/ros2#manual-installation) + - [Install ROS 2 Dev Tools](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/ros2_dev_tools#manual-installation) + - [Install the RMW Implementation](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/rmw_implementation#manual-installation) + - [Install pacmod](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/pacmod#manual-installation) + - [Install Autoware Core dependencies](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/autoware_core#manual-installation) + - [Install Autoware Universe dependencies](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/autoware_universe#manual-installation) + - [Install pre-commit dependencies](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/pre_commit#manual-installation) + - [Install Nvidia CUDA](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/cuda#manual-installation) + - [Install Nvidia cuDNN and TensorRT](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/tensorrt#manual-installation) ## How to set up a workspace diff --git a/docs/installation/index.md b/docs/installation/index.md index f605932ce02..7b99b35577f 100644 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -29,7 +29,7 @@ The Autoware Foundation provides no support on other platforms than those listed > - Camera based object detection > - Traffic light detection and classification -For details of how to enable object detection and traffic light detection/classification without a GPU, refer to the [Running Autoware without CUDA](../how-to-guides/running-autoware-without-cuda.md). +For details of how to enable object detection and traffic light detection/classification without a GPU, refer to the [Running Autoware without CUDA](../how-to-guides/others/running-autoware-without-cuda.md). ## Installing Autoware diff --git a/docs/support/troubleshooting.md b/docs/support/troubleshooting.md index b28d60b0569..d175f418dfd 100644 --- a/docs/support/troubleshooting.md +++ b/docs/support/troubleshooting.md @@ -87,6 +87,19 @@ MAKEFLAGS="-j4" colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=R ``` You can adjust `-j4` to any number based on your system. +For more details, see the [manual page of GNU make](https://www.gnu.org/software/make/manual/make.html#Parallel-Disable). + +By reducing the number of packages built in parallel, you can also reduce the amount of memory used. +In the following example, the number of packages built in parallel is set to 1, and the number of jobs used by `make` is limited to 1. + +```bash +MAKEFLAGS="-j1" colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release --parallel-workers 1 +``` + +!!! note + + By lowering both the number of packages built in parallel and the number of jobs used by `make`, you can reduce the memory usage. + However, this also means that the build process takes longer. ### Errors when using the latest version of Autoware @@ -137,13 +150,14 @@ During building the following issue can occurs pkg_resources.extern.packaging.version.InvalidVersion: Invalid version: '0.23ubuntu1' ``` -The error is due to the fact that since version 66.0.0 `setuptools` enforces the python packages to be +The error is due to the fact that for versions between 66.0.0 and 67.5.0 `setuptools` enforces the python packages to be [PEP-440](https://peps.python.org/pep-0440/) conformant. +Since version 67.5.1 `setuptools` has a [fallback](https://github.com/pypa/setuptools/commit/1640731114734043b8500d211366fc941b741f67) that makes it possible to work with old packages again. -The workaround is to lower the version of `setuptools` to 65 or lower. It can be done using the following command +The solution is to update `setuptools` to the newest version with the following command ```bash -pip install -U setuptools==65.7.0 +pip install --upgrade setuptools ``` ## Docker/rocker issues @@ -200,3 +214,11 @@ If you get the error message `selected interface "{your-interface-name}" is not ```bash sudo ip link set multicast on {your-interface-name} ``` + +### Node performance degradation + +If you notice a decrease in the running performance of a node, such as [issue2597](https://github.com/autowarefoundation/autoware.universe/issues/2597#issuecomment-1491789081), you need to check if your compilation instructions use `Release` or `RelWithDebInfo` tags. If not, recompile the project using the following instructions: + +```bash +colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release +``` diff --git a/docs/tutorials/scenario-simulation/.pages b/docs/tutorials/scenario-simulation/.pages index 17dc0fa6cfb..37ce01897a5 100644 --- a/docs/tutorials/scenario-simulation/.pages +++ b/docs/tutorials/scenario-simulation/.pages @@ -1,3 +1,4 @@ nav: + - index.md - planning-simulation - rosbag-replay-simulation diff --git a/docs/tutorials/scenario-simulation/index.md b/docs/tutorials/scenario-simulation/index.md new file mode 100644 index 00000000000..3b6ba0b02c9 --- /dev/null +++ b/docs/tutorials/scenario-simulation/index.md @@ -0,0 +1,5 @@ +# Scenario simulation + +!!! warning + + Under Construction diff --git a/mkdocs.yaml b/mkdocs.yaml index 984cd726ddd..ff0aae6a9d0 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -3,7 +3,7 @@ site_url: https://tier4.github.io/autoware-documentation repo_url: https://github.com/tier4/autoware-documentation edit_uri: https://github.com/tier4/autoware-documentation/edit/tier4/main/docs/ docs_dir: docs -copyright: Copyright © 2022 TIER IV, Inc. +copyright: Copyright © 2023 TIER IV, Inc. theme: name: material @@ -51,7 +51,7 @@ plugins: - awesome-pages - exclude: regex: - - ^(?!(.*/)?assets/).*\.(?!(.*\.)?md|(.*\.)?svg|(.*\.)?png|(.*\.)?jpg).*$ + - ^(?!(.*/)?assets/).*\.(?!(.*\.)?md|(.*\.)?svg|(.*\.)?png|(.*\.)?gif|(.*\.)?jpg).*$ - ^(.*/)?[^.]*$ - macros - mkdocs-video @@ -64,11 +64,9 @@ markdown_extensions: - attr_list - codehilite: guess_lang: false - - pymdownx.emoji: - emoji_index: !!python/name:materialx.emoji.twemoji - emoji_generator: !!python/name:materialx.emoji.to_svg - fontawesome_markdown - footnotes + - md_in_html - mdx_math - mdx_truly_sane_lists: nested_indent: 2 @@ -77,6 +75,9 @@ markdown_extensions: format: svg - pymdownx.arithmatex - pymdownx.details + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg - pymdownx.highlight - pymdownx.snippets: auto_append: