diff --git a/map/autoware_lanelet2_map_validator/README.md b/map/autoware_lanelet2_map_validator/README.md index 60991d58..4e73033b 100644 --- a/map/autoware_lanelet2_map_validator/README.md +++ b/map/autoware_lanelet2_map_validator/README.md @@ -287,6 +287,10 @@ The directory structure should be the same to that of the `src/validators` direc - [mapping.crosswalk.missing_regulatory_elements](./docs/crosswalk/missing_regulatory_elements_for_crosswalk.md) - [mapping.crosswalk.regulatory_element_details](./docs/crosswalk/regulatory_element_details_for_crosswalks.md) +## How to add a new validator + +If you want to contribute to `autoware_lanelet2_map_validator`, please check out the [how_to_contribute](./docs/how_to_contribute.md) first. + ## Relationship between requirements and validators This is a table describing the correspondence between the validators that each requirement consists of. diff --git a/map/autoware_lanelet2_map_validator/docs/how_to_contribute.md b/map/autoware_lanelet2_map_validator/docs/how_to_contribute.md new file mode 100644 index 00000000..8f097c10 --- /dev/null +++ b/map/autoware_lanelet2_map_validator/docs/how_to_contribute.md @@ -0,0 +1,120 @@ +# How to contribute to `autoware_lanelet2_map_validator` + +Your contribution is welcome to achieve a broad view of validation for lanelet2 maps. +This document gives you the instructions on how to add a validator to `autoware_lanelet2_map_validator`. +Please take a look at the [Design Concept](#design-concept) and follow the [Contribution Guide](#contribution-guide). + +## Design Concept + +The main goal of `autoware_lanelet2_map_validator` is to validate whether the lanelet2 map matches the vector map requirements for Autoware. +`autoware_lanelet2_map_validator` achieves this by running a list of small validators. +In other words, each vector map requirement will be validated by one or more validators. +It is recommended to keep validators small and they don't have to be unique to a specific requirement so that we can broaden the expression of map requirements. (It doesn't mean that a validator should output only one kind of error!) + +The list of small validators will be defined as a JSON file (see [`autoware_requirement_set.json`](https://github.com/autowarefoundation/autoware_tools/blob/main/map/autoware_lanelet2_map_validator/autoware_requirement_set.json) for an example), and the output will also be a JSON file that appends validation results to a copy of the input. See [How to use `autoware_lanelet2_map_validator`](https://github.com/autowarefoundation/autoware_tools/tree/main/map/autoware_lanelet2_map_validator#how-to-use) for further information about how the input and output are processed. + +![autoware_lanelet2_map_validator_input_and_output](../media/autoware_lanelet2_map_validator_io.svg) + +Please note that the validators are categorized according to [the vector map requirements written in the Autoware Documentation](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-architecture/map/map-requirements/vector-map-requirements-overview/). If there are any suggestions for new categories please let the pull request (PR) reviewers know. The available categories as of now are + +- Lane +- Stop line +- Intersection +- Traffic light +- Crosswalk +- Area +- Others + +## Contribution Guide + +This section is aimed at contributors who want to add their own validators. If you want to change the core process of `autoware_lanelet2_map_validator`, please open a PR and discuss it with the maintainers. + +### 1. Implement your validator + + + +`autoware_lanelet2_map_validator` is based on the [Lanelet2 library provided by fzi-forschungszentrum-informatik](https://github.com/fzi-forschungszentrum-informatik/Lanelet2). + + + +Contributors are encouraged to make their validators by following the class structure shown in [`validator_template.cpp`](https://github.com/autowarefoundation/autoware_tools/blob/main/map/autoware_lanelet2_map_validator/src/validators/validator_template.cpp) and [`validator_template.hpp`](https://github.com/autowarefoundation/autoware_tools/blob/main/map/autoware_lanelet2_map_validator/src/validators/validator_template.hpp). Looking at other implementations may also be helpful. + +#### Restrictions for path structure + +- The source file (`.cpp`) must belong to `src/validators/\/` +- Avoid source file names that are the same as those in other categories. +- The header file (`.hpp`) must belong to `src/include/lanelet2_map_validator/validators/\/` +- Currently, there are no naming rules for source and header files, but the pair of source and header files should have the same name. + +#### Restrictions for validator class implementation + +- Define the name of the validator in the header file (`.hpp` file). + - The name must follow the structure `aaa.bbb.ccc` + - The first part (`aaa`) must be either `mapping`, `routing` or `rule` + - The second part (`bbb`) should be either `general`, `lane`, `stop_line`, `intersection`, `traffic_light`, `crosswalk`, `area`, `others`. + - The third part can be anything, as long as it is not hard to recognize the validator's feature. + - The issue code of the validator will be generated from this name. It removes the first part of the name, converts it to upper camel case, and adds a number for classification. (e. g. `Bbb.Ccc-001`) +- Write your implementation in the `operator()` function that outputs an [Issues (a.k.a vector\) object](https://github.com/fzi-forschungszentrum-informatik/Lanelet2/blob/master/lanelet2_validation/include/lanelet2_validation/Issue.h). Not all of the implementation has to be written in the operator; you can privately define and use functions in your validator class. +- Since `autoware_lanelet2_map_validator` outputs issue codes, please add an issue code prefix with square brackets on top of your issue message. + - You may use the `append_issue_code_prefix` function to generate the issue code prefix. + - Even if the validator only detects a single type of issue, please include the number `001` to your issue code. + - The issue code must correspond to the issue message one-to-one. +- Currently, there are no rules to decide the severity of the issue. If you're not confident about your severity decisions please discuss them with your PR reviewers. +- Other coding rules are mentioned in the [Autoware Documentation](https://autowarefoundation.github.io/autoware-documentation/main/contributing/). However, this coding rule doesn't hold if it conflicts with the Lanelet2 library. + +### 2. Write a test code + +Contributors must also provide test codes to ensure your validator is working properly and be able to be tested again when changes occur to the validator in the future. + +#### Restrictions for path structure + +- The source code (`.cpp`) must belong to `test/src/`. + - The test codes are not categorized because there are few codes, but they might be categorized in the future. +- The source code name should be `test_.cpp` +- The maps (`.osm`) for testing must belong to `test/data/map/\/` +- The JSON files (`.json`) for testing must belong to `test/data/json/` + +#### Restrictions for test code implementation + +- Tests should be executable by `colcon test`. It is strongly recommended to use the [gtest (googletest) format](https://github.com/google/googletest). +- If possible, the `MapValidationTester` class may be useful to inherit common map loading process. +- The test code must contain the following. + - A test function that checks whether the validator is available. + - A test function for each unique issue the validator can detect. It is recommended to create a small lanelet2 map for each unique issue. + - In this test, please also check that the issue code is emitted as expected. + - A test function ensuring that no issues occur when validating `test/data/map/sample_map.osm`. If `sample_map.osm` violates the validation or doesn't contain the primitive to validate, please fix or add the primitives to it. +- Add the test code to `CMakeLists.txt` using the `add_validation_test` function. + - Currently, this part must be added to CMakeLists.txt manually. Automation is expected in the future. + +### 3. Test the entire validator + +Please check that the `autoware_lanelet2_map_validator` works perfectly. + +1. Execute `colcon test --packages-select autoware_lanelet2_map_validator --event-handlers console_cohesion+` and confirm that all tests pass. +2. Execute the following command and confirm that no issues appear. + +```bash +ros2 run autoware_lanelet2_map_validator autoware_lanelet2_map_validator -p mgrs -m -i -o ./ +``` + +### 4. Write a document + +Contributors must provide documentation to explain what the validator can do. +The document must explain the following. + +- The validator's name +- Feature of the validator +- The source code where the validator is implemented +- A table of issues that the validator can detect. The following details are required. + - Issue Code + - Message + - Severity + - Primitive + - Description of the issue + - Approach to fix the issue + +In addition, add a link of the document to the table [Relationship between requirements and validators](https://github.com/autowarefoundation/autoware_tools/tree/main/map/autoware_lanelet2_map_validator#relationship-between-requirements-and-validators) in the main `README.md` to let the users know which map requirement your validator relates with. + +### 5. Submit a pull request + +Submit a pull request to the [autowarefoundation/autoware_tools](https://github.com/autowarefoundation/autoware_tools) repository. diff --git a/map/autoware_lanelet2_map_validator/media/autoware_lanelet2_map_validator_io.svg b/map/autoware_lanelet2_map_validator/media/autoware_lanelet2_map_validator_io.svg new file mode 100644 index 00000000..5d9f36cc --- /dev/null +++ b/map/autoware_lanelet2_map_validator/media/autoware_lanelet2_map_validator_io.svg @@ -0,0 +1,385 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+ + [vm-02-02] + +
+
+
+
    +
  • mapping.stop_line.missing_regulatory_element
    • +
+
+ + [vm-04-01] + +
+
    +
  • mapping.traffic_light.missing_regulatory_elements
    • +
  • mapping.traffic_light.missing_referrers
    • +
  • mapping.traffic_light.regulatory_element_details
    • +
+
+ + [vm-04-02] + +
+
+
    +
  • mapping.traffic_light.correct_facing
    • +
+
+ ... and so on +
+
+
+
+
+
+
+
+ + + + + + + + + + + + + + +
+
+
+ + autoware_requirement_set.json + +
+
+
+ + + + + + + + + + + + + + +
+
+
+ + ID for the map requirement + +
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ autoware_lanelet2_map_validator +
+
+
+ + + + + + + + + + + + + + + + + + + + + + +
+
+
+ + validation_target_map.osm + +
+
+
+ + + + + + + + + + + + + + + + +
+
+
+ + lanelet2_validation_results.json + +
+
+
+ + + + + + + + + + + + + + + + + + + + + +
+
+
+ A validator is deployed for each map requirement +
+
+
+ + + + + + + + + + + + + + +
+
+
+ ... or a group of validators can be allocated to a requirement if there are many things to validate +
+
+
+ + + + + + + + + + + + + + + +