autoware_lanelet2_map_validator

autoware_lanelet2_map_validator is a tool to validate Lanelet2 maps to ensure that Autoware can work properly with it.

This validation tool is an extension of lanelet2_validation so that Autoware specific rules can be applied. As you can see from the codes in the src/validators directory, the group of validators belong to this tool inherits the lanelet::validation::MapValidator class from the original lanelet2_validation. Therefore, we believe that reading the source code of the lanelet2_validation will help you understand this tool better.

Note that this validator is still on construction that there are only a few rules and a template to define those rules.

The official Autoware requirements for lanelet2 maps are described in Vector Map creation requirement specifications (in Autoware Documentation).

Design concept

The autoware_lanelet2_map_validator is designed to validate .osm map files by using and extending the lanelet2_validation package for Autoware.

autoware_lanelet2_map_validator takes the lanelet2 map (.osm file) and requirement set (JSON file, optional) as the input, and output validation results to the console.

If a requirement set is given, autoware_lanelet2_map_validator also outputs validation results reflecting the input requirement set. See “Run with a requirement set” for further information, “Input file” to understand the input format, and “Output file” to understand the output format.

How to use

Basically, you can use the following command to execute autoware_lanelet2_map_validator. However, note that autoware_lanelet2_map_validator is a ROS/rclcpp free tool, so you can just run the built executable whatever way.

ros2 run autoware_lanelet2_map_validator autoware_lanelet2_map_validator

Run ALL validators

You can use autoware_lanelet2_map_validator with the following command. This will run all validators including the default built-in validators in the lanelet2_validation.

ros2 run autoware_lanelet2_map_validator autoware_lanelet2_map_validator --map_file <absolute_or_relative_path/to_your/lanelet2_map.osm> --projector mgrs

Run a specific validator

autoware_lanelet2_map_validator consists of multiple small validators in order to realize complex requirements with a combination of them. If you want to call a few validators, you can select them with the --validator, -v option.

ros2 run autoware_lanelet2_map_validator autoware_lanelet2_map_validator --map_file path/to_your/lanelet2_map.osm --projector mgrs --validator mapping.traffic_light.missing_regulatory_elements

You can get a list of available validators with the --print option. (-p is for --projector)

ros2 run autoware_lanelet2_map_validator autoware_lanelet2_map_validator --print

Run with a requirement set

autoware_lanelet2_map_validator can manage to run a group of validators by a list of validator names. autoware_lanelet2_map_validator will scan through the input JSON file given by the --input_requirements, -i option, and output the validation results to the directory given by the --output_directory, -o option. The output filename will be lanelet2_validation_results.json.

ros2 run autoware_lanelet2_map_validator autoware_lanelet2_map_validator --map_file <absolute_or_relative_path/to_your/lanelet2_map.osm> --projector mgrs --input_requirements <absolute_or_relative_path_to_autoware_requirement_set.json> --output_directory ./

(Short version)

ros2 run autoware_lanelet2_map_validator autoware_lanelet2_map_validator -m <absolute_or_relative_path/to_your/lanelet2_map.osm> -p mgrs -i <absolute_or_relative_path_to_autoware_requirement_set.json> -o ./

Input file

The JSON file input should follow the structure like this example.

{
  "requirements": [
    {
      "id": "vm-02-02",
      "validators": [
        {
          "name": "mapping.stop_line.missing_regulatory_elements"
        }
      ]
    },
    {
      "id": "vm-04-01",
      "validators": [
        {
          "name": "mapping.crosswalk.missing_regulatory_elements"
        },
        {
          "name": "mapping.crosswalk.regulatory_element_details",
          "prerequisites": [
            {
              "name": "mapping.crosswalk.missing_regulatory_elements"
            }
          ]
        }
      ]
    },
    {
      "id": "vm-05-01",
      "validators": [
        {
          "name": "mapping.traffic_light.missing_regulatory_elements"
        },
        {
          "name": "mapping.traffic_light.regulatory_element_details",
          "prerequisites": [
            {
              "name": "mapping.traffic_light.missing_regulatory_elements"
            }
          ]
        }
      ]
    }
  ]
}

• MUST have a single requirements field.
• The requirements field MUST be a list of requirements. A requirement MUST have
  • id : The id of the requirement. Its name is arbitrary.
  • validators : A list of validators that structures the requirement.
    • A validator MUST be given with its name on the name field.
    • The name list of available validators can be obtained from the --print option.
    • You can add a list of prerequisites to each validator. Then, the validator will only be run when the prerequisites pass the validation.
    • In the prerequisites field, you can add forgive_warnings: true in order to run the validator even if the prerequisites output warning issues. (Error issues from prerequisites will still skip the validation.). Note that NOT writing the forgive_warnings field and writing forgive_warnings: false means the same.
• The user can write any other field (like version) besides requirements.

Output file

When the input_requirements is thrown to autoware_lanelet2_map_validator, it will output a lanelet2_validation_results.json file which looks like the following example.

{
  "requirements": [
    {
      "id": "vm-02-02",
      "passed": true,
      "validators": [
        {
          "name": "mapping.stop_line.missing_regulatory_elements",
          "passed": true
        }
      ]
    },
    {
      "id": "vm-04-01",
      "passed": false,
      "validators": [
        {
          "issues": [
            {
              "id": 163,
              "issue_code": "Crosswalk.MissingRegulatoryElements-001",
              "message": "No regulatory element refers to this crosswalk.",
              "primitive": "lanelet",
              "severity": "Error"
            },
            {
              "id": 164,
              "issue_code": "Crosswalk.MissingRegulatoryElements-001",
              "message": "No regulatory element refers to this crosswalk.",
              "primitive": "lanelet",
              "severity": "Error"
            },
            {
              "id": 165,
              "issue_code": "Crosswalk.MissingRegulatoryElements-001",
              "message": "No regulatory element refers to this crosswalk.",
              "primitive": "lanelet",
              "severity": "Error"
            },
            {
              "id": 166,
              "issue_code": "Crosswalk.MissingRegulatoryElements-001",
              "message": "No regulatory element refers to this crosswalk.",
              "primitive": "lanelet",
              "severity": "Error"
            }
          ],
          "name": "mapping.crosswalk.missing_regulatory_elements",
          "passed": false
        },
        {
          "issues": [
            {
              "id": 0,
              "issue_code": "General.PrerequisitesFailure-001",
              "message": "Prerequisites didn't pass",
              "primitive": "primitive",
              "severity": "Error"
            }
          ],
          "name": "mapping.crosswalk.regulatory_element_details",
          "passed": false,
          "prerequisites": [
            {
              "name": "mapping.crosswalk.missing_regulatory_elements"
            }
          ]
        }
      ]
    },
    {
      "id": "vm-05-01",
      "passed": false,
      "validators": [
        {
          "name": "mapping.traffic_light.missing_regulatory_elements",
          "passed": true
        },
        {
          "issues": [
            {
              "id": 9896,
              "issue_code": "TrafficLight.MissingRegulatoryElements-001",
              "message": "Regulatory element of traffic light must have a stop line(ref_line).",
              "primitive": "regulatory element",
              "severity": "Error"
            },
            {
              "id": 9918,
              "issue_code": "TrafficLight.MissingRegulatoryElements-001",
              "message": "Regulatory element of traffic light must have a stop line(ref_line).",
              "primitive": "regulatory element",
              "severity": "Error"
            },
            {
              "id": 9838,
              "issue_code": "TrafficLight.MissingRegulatoryElements-001",
              "message": "Regulatory element of traffic light must have a stop line(ref_line).",
              "primitive": "regulatory element",
              "severity": "Error"
            },
            {
              "id": 9874,
              "issue_code": "TrafficLight.MissingRegulatoryElements-001",
              "message": "Regulatory element of traffic light must have a stop line(ref_line).",
              "primitive": "regulatory element",
              "severity": "Error"
            }
          ],
          "name": "mapping.traffic_light.regulatory_element_details",
          "passed": false,
          "prerequisites": [
            {
              "name": "mapping.traffic_light.missing_regulatory_elements"
            }
          ]
        }
      ]
    }
  ]
}

• lanelet2_validation_results.json inherits the JSON file of input_requirements and add results to it.
  • So additional input information not related to this validator also remains in the output.
• autoware_lanelet2_map_validator adds a boolean passed field to each requirement. If all validators of the requirement have been passed, the passed field of the requirement will be true (false if not).
• The passed field is also given to each validator. If the validator found any issues the passed field will turn to be false (true if not), and adds an issues field which is a list of issues found. Each issue contains information of severity, primitive, id, message and issue_code.

Available command options

Available validators

Since there will be hundreds of validators in the future, the documents for each validator should categorized in the docs file. The directory structure should be the same to that of the src/validators directory.

Stop Line

• mapping.stop_line.missing_regulatory_elements

Traffic Light

• mapping.traffic_light.missing_regulatory_elements
• mapping.traffic_light.regulatory_element_details

Crosswalk

• mapping.crosswalk.missing_regulatory_elements
• mapping.crosswalk.regulatory_element_details

How to add a new validator

If you want to contribute to autoware_lanelet2_map_validator, please check out the how_to_contribute first.

Relationship between requirements and validators

This is a table describing the correspondence between the validators that each requirement consists of. The “Validators” column will be blank if it hasn’t be implemented.

Changelog for package autoware_lanelet2_map_validator

0.2.0 (2025-03-24)

0.1.0 (2025-01-28)

• unify version to 0.0.0
• feat(lanelet2_map_validator): check local coordinates declaration (#194)
  • Implement mapping.lane.local_coordinates_declaration
  • Added test for mapping.lane.local_coordinates_declaration

  * Added documents for mapping.lane.local_coordinates_declaration ---------

• feat(lanelet2_map_validator): add validator to check whether intersection lanelets have valid turn_direction tags (#186)
  • Added validator which checks the "turn_direction" tag in intersection_areas
  • Added test code for mapping.intersection.turn_direction_tagging
  • Added document for mapping.intersection.turn_direction_tagging
  • Added mapping.intersection.turn_direction_tagging to autoware_requirement_set.json
  • Fixed spelling errors

  * Removed crosswalk boundaries from test map ---------

• docs(lanelet2_map_validator): update README (#193)
  • Updated document
  • Added explanation about issue_code
  • Removed back ticks in the title

  * Fixed spelling issues ---------

• fix(lanelet2_map_validator): restore missing intersection lane and removed unnecessary linestrings from intersection test maps (#188)
  • Restore missing linestring 197 and lanelet 49

  * Removed crosswalk remainings from intersection category test maps ---------

• docs(autoware_lanelet2_map_validator): update usage (#191)
• feat(lanelet2_map_validator): generation script for new validators (#180)
  • temporary commit
  • Added python script
  • Finished except docs
  • Added documents related stuff
  • Moved stuff to templates
  • Revised files to suit the current directory
  • Added arguments
  • Added prints
  • added #include <string> to test code
  • Fixed typo
  • Write explanation of create_new_validator.py
  • Added back slashes to example command

  * Enable the generation script to be run by [ros2 run]{.title-ref} ---------

• chore(lanelet2_map_validator): automate test code compilation and categorize test codes (#183)
  • Categorize test codes

  * Rewrite CMakeLists.txt so that contributors doesn't have to write the test code name in it ---------

• feat(autoware_lanelet_map_validator): add dangling reference checker to non existing intersection_area (#177)
• chore: sync files (#11) Co-authored-by: github-actions <<github-actions@github.com>> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]\@users.noreply.github.com>
• feat(lanelet2_map_validator): check whether intersection_area satisfies vm-03-08 (#171)
  • Create the framework for intersection_area_validity.
  • Made is_valid checker in intersection_area_validity
  • Split and create a new validator intersection_area_segement_type.
  • Completed intersection_area_segment_type
  • Added [vm-03-08]{.title-ref} to autoware_requirement_set.json
  • Added [vm-03-08]{.title-ref} to autoware_requirement_set.json
  • Added documents for intersection_area validators
  • Added [intersection_area]{.title-ref} type polygons to sample_map.osm
  • Added test codes
  • Fixed spelling error
  • Removed original bbox calculation and use the one in the Lanelet2 library

  * Added explanation of functions ---------

• docs(lanelet2_map_validator): add a new document how_to_contribute.md (#170)
  • Added a document how_to_contribute.md to lanelet2_map_validator
  • Added information about CMakeLists in tests.
  • Added figure illustrating the input output
  • Add a link to how_to_contribute.md to README.md
  • Fixed spelling and grammar mistakes
  • Fixed some sentences
  • Fixed spelling errors
  • Fixed link URLs
  • Quit using .. to direct to README.md

  * Fixed link mistakes ---------

• Fixed issue that invalid prerequisites are not reflected to the results (#169)
• feat(lanelet2_map_validator): add validator to check traffic light facing (#165)
  • Added valdiator missing_referrers_for_traffic_lights
  • Added validator traffic_light_facing
  • Added traffic_light_facing and missing_referrers_for_traffic_lights
  • Added new validators to README.md
  • Added test codes for traffic_light_facing and missing_referrers_for_traffic_lights
  • feat(lanelet2_map_validator): added issue codes (#163)
  • Added issue code processing
  • Revised tests for json processing
  • Added issue codes for missing_regulatory_elements_for_crosswalks
  • Added issue codes for regulatory_element_details_for_crosswalks
  • Added issue codes for missing_regulatory_elements_for_stop_lines
  • Added issue codes for missing_regulatory_elements_for_traffic_lights
  • Added issue codes for regulatory_element_details_for_traffic_lights
  • Added issue codes to docs
  • Change issue_code_prefix to append_issue_code_prefix

  * Fixed merging mistake --------- * Changed to append_issue_code_prefix. Added test for TrafficLight.CorrectFacing-001

  • Rearrange code structure
  • Fixed spelling mistakes
  • Fixed traffic_light_facing_procedure.svg
  • Fixed mistakes in document
  • Refine algorithm in traffic_light_facing.cpp
  • Shorten the data collection process, and updated the procedure svg
  • Use findUsages in missing_referrers_for_traffic_lights

  * Update map/autoware_lanelet2_map_validator/docs/traffic_light/missing_referrers_for_traffic_lights.md Co-authored-by: Mamoru Sobue <<hilo.soblin@gmail.com>>

  • style(pre-commit): autofix

  * Quit stocking all lanelets to collect traffic light regulatory elements ---------Co-authored-by: Mamoru Sobue <<hilo.soblin@gmail.com>> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]\@users.noreply.github.com>

• feat(lanelet2_map_validator): added issue codes (#163)
  • Added issue code processing
  • Revised tests for json processing
  • Added issue codes for missing_regulatory_elements_for_crosswalks
  • Added issue codes for regulatory_element_details_for_crosswalks
  • Added issue codes for missing_regulatory_elements_for_stop_lines
  • Added issue codes for missing_regulatory_elements_for_traffic_lights
  • Added issue codes for regulatory_element_details_for_traffic_lights
  • Added issue codes to docs
  • Change issue_code_prefix to append_issue_code_prefix

  * Fixed merging mistake ---------

• feat(lanelet2_map_validator): add test codes for existing validators (#150) * Added small maps for testing. Added test codes using these maps. * Rearrange architecture of test directory. Added regulatory_elements_details_for_crosswalks test
  • Removed old test programs
  • Removed test_regulatory_elements_details.cpp
  • Revised test (TestRegulatoryElementDetailsForTrafficLights, MissingRefers) to look into the loading errors
  • Added sample_map for testing a normal map
  • Reflect PR comments
  • Fixed detection area in sample_map.osm

  * Added autoware namespace to test codes ---------

• refactor(lalenet2_map_validator): divide map loading process (#153)
• refactor(lanelet2_map_validator): move custom implementation to lanelet::autoware::validation (#152)
• fix(lanelet2_map_validator): change validation order in regulatory_elements_details (#151)
  • Changed the order to validate in regulatory_element_details

  * Revised test code ---------

• Removed redundant appendIssues (#148)
• feat(autoware_lanelet2_map_validator): allow prerequisites attribute for input (#147) * Added prerequisites tag to input. Moved process_requirements to validation.cpp
  • Added prerequisites to autoware_requirement_set.json
  • Redefine ValidatorInfo
  • Changed check_prerequisite_completion not to read the json_data
  • Added two tests CreateValidationQueueNoCycles CreateValidationQueueWithCycles
  • Added test CheckPrerequisiteCompletionSuccess CheckPrerequisiteCompletionFailure
  • Change how to load json files in tests.
  • Added test DescriptUnusedValidatorsToJson and SummarizeValidatorResults
  • Revised README.md to the current status
  • Fixed typo and unknown words
  • Reflect PR comments

  * Fixed typo ---------

• refactor(lanelet2_map_validator): move headers to include/ (#144)
• chore(autoware_lanelet2_map_validator): add requirement vm-02-02 to autoware_requirement_set (#143)
  • Add Sobue-san as maintainer of autoware_lanelet2_map_validator
  • Added maintainers to autoware_lanelet2_map_validator
  • Added vm-02-02 to autoware_requirement_set.json
  • Fixed error of autoware_lanelet2_map_validator template

  * Detect stop lines that are referred as [refers]{.title-ref} role. ---------

• chore(autoware_lanelet2_map_validator): add maintainers (#141)
  • Add Sobue-san as maintainer of autoware_lanelet2_map_validator

  * Added maintainers to autoware_lanelet2_map_validator ---------

• feat(autoware_lanelet2_map_validator): introduce autoware_lanelet2_map_validator (#118)
  • introduce autoware_lanelet2_map_validator to autoware_tools
  • wrote description a little to README.md
  • style(pre-commit): autofix

  * Restore commented out parts. Removed rclcpp which is unused.

  • style(pre-commit): autofix

  * Separate validation rules to samller pieces. Added validation template * Split the validation code into smaller pieces. Added yaml input/output for a set of validations

  • Fixed test codes to use the separated codes
  • Removed unused code which are already divided to smaller codes.
  • Rename new_main.cpp to main.cpp
  • style(pre-commit): autofix
  • Wrote detailed README.md
  • Fixed commit mistake

  * Renew input command option to [-i]{.title-ref} from [-r]{.title-ref}. Fixed mistakes in README.md

  • style(pre-commit): autofix
  • Fixed long to uint64_t
  • Fixed spelling
  • style(pre-commit): autofix
  • Fixed typo
  • Split long lines in the code
  • style(pre-commit): autofix

  * Changed the entire structure. Fixed pre-commit.ci related errors.

  • style(pre-commit): autofix
  • Fixed pre-commit.ci related stuff

  * Write more details about the relationship to lanelet2_validation. Rewrite misleading examples.

  • Added figure of the architecture
  • Change the input/output to JSON
  • Revised architecture image of autoware_lanelet2_map_validator
  • fixed typo
  • Renew year numbers
  • Fixed dependency
  • Fixed pointed out issues

  * Improve error handling Refactor code style * Avoid clang format Delete unused variables * Removed redundant process. Restrict input/output format.

  • Added approaches to the documents
  • Fixed typo
  • Removed catch and improve io error handling

  * Fixed grammatical error. Fixed explanation of issues

  • Added stop_line validator to the table in the main README.md

  * Renamed lib to common. Refined CMakeLists.txt

  • Removed redundant under score
  • Removed redundant underscore again

  * Changed years. Removed redundant else statement. Removed debug comments * Removed underscore from test_regulatory_element_details.cpp ---------Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]\@users.noreply.github.com>

• Contributors: Mamoru Sobue, TaikiYamada4, Yutaka Kondo, awf-autoware-bot[bot]