diff --git a/autoware_lanelet2_extension/docs/extra_regulatory_elements.md b/autoware_lanelet2_extension/docs/extra_regulatory_elements.md index 036c96e..34e9e50 100644 --- a/autoware_lanelet2_extension/docs/extra_regulatory_elements.md +++ b/autoware_lanelet2_extension/docs/extra_regulatory_elements.md @@ -1,5 +1,22 @@ # Extra Regulatory Elements +## Right Of Way + +Users must add `right_of_way` tag to intersection lanes, namely lanes with `turn_direction` attribute. Below image illustrates how to set yield lanes(orange) for the ego lane(blue). + +![RightOfWay tagging](right_of_way.drawio.svg) + +Basically intersection lanes which are: + +- left/right turn +- straight and on the side of priority sign + +need this tag to know which lanes in their `conflicting lanes` can be ignored for object detection. + +left/right turning lane is often conflicting with lanes whose traffic lights are red when its traffic light is green, so **at least** those lanes should be registered as yield lanes. + +If ego car is going straight the intersection when the traffic light is green, then it does not need to care other lanes because it has the highest priority. But if the traffic lights do not exist and ego lane is on the side of priority road, then yield lanes should be set to explicitly ignore part of conflicting lanes. + ## Detection Area This regulatory element specifies region of interest which vehicle must pay attention whenever it is driving along the associated lanelet. When there are any obstacle in the detection area, vehicle must stop at specified stopline. @@ -148,6 +165,148 @@ An example annotation of speed_bump: ``` +## Crosswalk + +Original Lanelet2 format only requires `subtype=crosswalk` tag to be specified in the corresponding lanelet. However, Autoware requires a regulatory element to be defined on top of that in order to: + +- explicitly define the relevant driving lanes even in 3D environment +- optionally define stop lines associated with the crosswalk +- enable accurate definition of complex polygons for crosswalk + +For the details, refer to this [GitHub discussion](https://github.com/orgs/autowarefoundation/discussions/3036). +Crosswalk regulatory element can be tied to `ref_line`, `crosswalk_polygon` and `refers`. + +![crosswalk_regulatory elements](crosswalk_regulatory_element.svg) + +- `ref_line`: Stop line for the crosswalk. +- `crosswalk_polygon`: Accurate area of the crosswalk. +- `refers`: Lanelet that indicates the moving direction of crosswalk users. + +_An example:_ + +```xml + + + + + + + +``` + +### Traffic Lights for Crosswalks + +It can define not only traffic lights for vehicles but also for crosswalk users by using regulatory element. In this case, the crosswalk lanelet needs to refer the traffic light regulatory element. + +![crosswalk_traffic_light](crosswalk_traffic_light.svg) + +_An example:_ + +```xml + + + + + + + + +... + + + + + + + + +... + + + + + + + + + + + + +``` + +### Safety Slow Down for Crosswalks + +If you wish ego vehicle to slow down to a certain speed from a certain distance while passing over a +certain crosswalk _even though there are no target objects around it_, you can add following tags to +the crosswalk definition on lanelet2 map: + +- `safety_slow_down_speed` **[m/s]**: The speed you want ego vehicle to drive at while passing over + the crosswalk +- `safety_slow_down_distance` **[m]**: The distance between front bumper of ego vehicle and + closest point to the crosswalk when ego vehicle slows down and drives at specified speed + +_An example:_ + +```xml + + + + + + + + +``` + +## No Stopping Area + +The area with `no_stopping_area` tag can be used to prohibit even a few seconds of stopping, even for traffic jams or at traffic lights. +The ref_line can be set arbitrarily, and the ego-vehicle should stop at this line if it cannot pass through the area. + +_An example:_ + +```xml + + + + + + + + + + + + + + + +``` + +## No Parking Area + +The area with `no_parking_area` tag can be used to prohibit parking. Stopping for a few seconds is allowed in this area. + +_An example:_ + +```xml + + + + + + + + + + + + + + +``` + ## Bus Stop Area The `BusStopArea` regulatory element can be used to specify the available space for bus-like vehicles to stop at a bus stop. The regulatory element should refer to a polygon with the `bus_stop_area` type and should be referred by the `road` or `road_shoulder` subtype lanelets that overlaps with the target `bus_stop_area` polygon. diff --git a/autoware_lanelet2_extension/docs/lanelet2_format_extension.md b/autoware_lanelet2_extension/docs/lanelet2_format_extension.md index b684d39..9bd38d4 100644 --- a/autoware_lanelet2_extension/docs/lanelet2_format_extension.md +++ b/autoware_lanelet2_extension/docs/lanelet2_format_extension.md @@ -10,15 +10,42 @@ Users may use `autoware_lanelet2_validation` [node](../README.md#nodes) to check The following is the extra format added for Autoware: - [extra regulatory elements](extra_regulatory_elements.md) + - Right Of Way - Detection Area - Road Marking - - Bus Stop Area + - Speed Bump + - Crosswalk + - No Stopping Area + - No Parking Area + - Bus Stoop Area - [extra lanelet subtype](extra_lanelet_subtypes.md) - Roadside Lane + - Road Shoulder + - Pedestrian Lane - Bicycle Lane +Note that each `extra_regulatory_elements` and `extra_lanelet_subtypes` should faithfully represent the real world map primitives as-is for realizing appropriate behavior on public roads. Although they are not necessarily mandatory for running minimal Autoware, each ODD requires different set of `extra_regulatory_elements` and `extra_lanelet_subtypes` respectively. + +[Autoware Vector Map Requirements](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-architecture/map/map-requirements/vector-map-requirements-overview/) provides more details and guidelines for how to create the Lanelet2 maps without ambiguity while avoiding unintended behaviors due to invalid Lanelet2 map settings. + ## Mandatory Tags +### Meta Info + +Users may add the `MetaInfo` element to their OSM file to indicate format version and map version of their OSM file. This information is not meant to influence Autoware vehicle's behavior, but is published as ROS message so that developers could know which map was used from ROSBAG log files. MetaInfo elements exists in the same hierarchy with `node`, `way`, and `relation` elements, otherwise JOSM wouldn't be able to load the file correctly. + +Here is an example of MetaInfo in osm file: + +```xml + + + + ... + ... + ... + +``` + ### Elevation Tags Elevation("ele") information for points(`node`) is optional in default Lanelet2 format. @@ -79,43 +106,10 @@ Here is an example of osm syntax for lanelets in intersections. ``` -### Right Of Way - -Users must add `right_of_way` tag to intersection lanes, namely lanes with `turn_direction` attribute. Below image illustrates how to set yield lanes(orange) for the ego lane(blue). - -![RightOfWay tagging](right_of_way.drawio.svg) - -Basically intersection lanes which are: - -- left/right turn -- straight and on the side of priority sign - -need this tag to know which lanes in their `conflicting lanes` can be ignored for object detection. - -left/right turning lane is often conflicting with lanes whose traffic lights are red when its traffic light is green, so **at least** those lanes should be registered as yield lanes. - -If ego car is going straight the intersection when the traffic light is green, then it does not need to care other lanes because it has the highest priority. But if the traffic lights do not exist and ego lane is on the side of priority road, then yield lanes should be set to explicitly ignore part of conflicting lanes. - ## Optional Taggings Following tags are optional tags that you may want to add depending on how you want to use your map in Autoware. -### Meta Info - -Users may add the `MetaInfo` element to their OSM file to indicate format version and map version of their OSM file. This information is not meant to influence Autoware vehicle's behavior, but is published as ROS message so that developers could know which map was used from ROSBAG log files. MetaInfo elements exists in the same hierarchy with `node`, `way`, and `relation` elements, otherwise JOSM wouldn't be able to load the file correctly. - -Here is an example of MetaInfo in osm file: - -```xml - - - - ... - ... - ... - -``` - ### Local Coordinate Expression Sometimes users might want to create Lanelet2 maps that are not georeferenced. @@ -204,99 +198,25 @@ The following illustrates how light_bulbs are registered to traffic_light regula ``` -### Crosswalk - -Original Lanelet2 format only requires `subtype=crosswalk` tag to be specified in the corresponding lanelet. However, Autoware requires a regulatory element to be defined on top of that in order to: - -- explicitly define the relevant driving lanes even in 3D environment -- optionally define stop lines associated with the crosswalk -- enable accurate definition of complex polygons for crosswalk - -For the details, refer to this [GitHub discussion](https://github.com/orgs/autowarefoundation/discussions/3036). -Crosswalk regulatory element can be tied to `ref_line`, `crosswalk_polygon` and `refers`. - -![crosswalk_regulatory elements](crosswalk_regulatory_element.svg) - -- `ref_line`: Stop line for the crosswalk. -- `crosswalk_polygon`: Accurate area of the crosswalk. -- `refers`: Lanelet that indicates the moving direction of crosswalk users. - -_An example:_ - -```xml - - - - - - - -``` - -### Traffic Lights for Crosswalks - -It can define not only traffic lights for vehicles but also for crosswalk users by using regulatory element. In this case, the crosswalk lanelet needs to refer the traffic light regulatory element. - -![crosswalk_traffic_light](crosswalk_traffic_light.svg) - -_An example:_ - -```xml - - - - - - - - -... - - - - - - - - -... - - - - - - - - - - - - -``` +### Centerline -### Safety Slow Down for Crosswalks +Note that the following explanation is not related to the Lanelet2 map format but how the Autoware handles the centerline in the Lanelet2 map. -If you wish ego vehicle to slow down to a certain speed from a certain distance while passing over a -certain crosswalk _even though there are no target objects around it_, you can add following tags to -the crosswalk definition on lanelet2 map: +Centerline is defined in Lanelet2 to guide the vehicle. By explicitly setting the centerline in the Lanelet2 map, the ego's planned path follows the centerline. +However, based on the current Autoware's usage of the centerline, there are several limitations. -- `safety_slow_down_speed` **[m/s]**: The speed you want ego vehicle to drive at while passing over - the crosswalk -- `safety_slow_down_distance` **[m]**: The distance between front bumper of ego vehicle and - closest point to the crosswalk when ego vehicle slows down and drives at specified speed +- The object's predicted path also follows the centerline. + - This may adversely affect the decision making of planning modules since the centerline is supposed to be used only by the ego's path planning. +- The coordinate transformation on the lane's frenet frame cannot be calculated correctly. +- For example, when the lateral distance between the actual road's centerline and a parked vehicle is calculated, actually the result will be the lateral distance between the (explicit) centerline and the vehicle. -_An example:_ +To solve above limitations, the `overwriteLaneletsCenterlineWithWaypoints` was implemented in addition to `overwriteLaneletsCenterline` where the centerline in all the lanes is calculated. -```xml - - - - - - - - -``` +- `overwriteLaneletsCenterlineWithWaypoints` + - The (explicit) centerline in the Lanelet2 map is converted to the new `waypoints` tag. This `waypoints` is only applied to the ego's path planning. + - Therefore, the above limitations can be solved, but the Autoware's usage of the centerline may be hard to understand. +- `overwriteLaneletsCenterline` + - The (explicit) centerline in the Lanelet2 map is used as it is. Easy to understand the Autoware's usage of the centerline, but we still have above limitations. ### No Obstacle Segmentation Area @@ -342,54 +262,6 @@ _An example:_ ``` -### No Stopping Area - -The area with `no_stopping_area` tag can be used to prohibit even a few seconds of stopping, even for traffic jams or at traffic lights. -The ref_line can be set arbitrarily, and the ego-vehicle should stop at this line if it cannot pass through the area. - -_An example:_ - -```xml - - - - - - - - - - - - - - - -``` - -### No Parking Area - -The area with `no_parking_area` tag can be used to prohibit parking. Stopping for a few seconds is allowed in this area. - -_An example:_ - -```xml - - - - - - - - - - - - - - -``` - ### No Drivable Lane A no drivable lane is a lanelet or more that are out of operation design domain (ODD), i.e., the vehicle **must not** drive autonomously in this/these lanelet/s. @@ -481,23 +353,3 @@ _An example:_ ... ``` - -### Centerline - -Note that the following explanation is not related to the Lanelet2 map format but how the Autoware handles the centerline in the Lanelet2 map. - -Centerline is defined in Lanelet2 to guide the vehicle. By explicitly setting the centerline in the Lanelet2 map, the ego's planned path follows the centerline. -However, based on the current Autoware's usage of the centerline, there are several limitations. - -- The object's predicted path also follows the centerline. - - This may adversely affect the decision making of planning modules since the centerline is supposed to be used only by the ego's path planning. -- The coordinate transformation on the lane's frenet frame cannot be calculated correctly. - - For example, when the lateral distance between the actual road's centerline and a parked vehicle is calculated, actually the result will be the lateral distance between the (explicit) centerline and the vehicle. - -To solve above limitations, the `overwriteLaneletsCenterlineWithWaypoints` was implemented in addition to `overwriteLaneletsCenterline` where the centerline in all the lanes is calculated. - -- `overwriteLaneletsCenterlineWithWaypoints` - - The (explicit) centerline in the Lanelet2 map is converted to the new `waypoints` tag. This `waypoints` is only applied to the ego's path planning. - - Therefore, the above limitations can be solved, but the Autoware's usage of the centerline may be hard to understand. -- `overwriteLaneletsCenterline` - - The (explicit) centerline in the Lanelet2 map is used as it is. Easy to understand the Autoware's usage of the centerline, but we still have above limitations.