Skip to content

Latest commit

 

History

History
116 lines (91 loc) · 10.9 KB

README.md

File metadata and controls

116 lines (91 loc) · 10.9 KB

Capability-Based Routing Example

This is an example project for the CapBasedRouting library. Please make sure that you understand the concept of BSSD before you continue. If you are not yet familiar with the BSSD framework, check it out here: GitLab GitHub

About this example

This example is taken directly from Lippert and Winner: Capability-Based Routes for Development, Testing and Operation of Safe Automated Vehicles. Please read this work since it explains everything you need to know about this example.

In the example we use a map of the city of Darmstadt in Germany. Our goal is to find the shortest route that an automated vehicle with given proof sets of driving capabilities (DC) can drive considering the driving requirements of the related road sections. To do this, besides the usual Lanelet2 routing procedure, we need to provide the following information/ data:

  • Map: Map file in Lanelet2 format extended with BSSD data
  • Optional adapted file loader class for handling BSSD map errors or missing data (see also here)
  • Proof sets of driving capabilities: json-file(s) with information about the proofed driving capabilities

    Note In this example we use only reservation capabilities according to p. 11, Table 1 from Lippert and Winner. We added also a section for boundary capabilities to demonstrate how the proof sets can be extended.

  • Optional adapted matching cost class to read out or print data for selected events (see also here)

You find the main function of the example with helpful comments in the example.cpp file. Feel free to play around with different settings, especially with different proof sets of the driving capabilities.

Note If you just want to derive the driving requirements you can end the main function with building the routing graph. Within this step, all the matching activities happen including the cost calculation with integrated requirement derivation. Use the routing events to get the results (e.g. print).

Below you will find additional information about building the example, how to handle errors while loading a map and how to use routing events. Please check out the library's detailed commented .h and .cpp files for more information.

Building the example

1. Configure the project with cmake

Note Make sure to replace the following parts of the following command to suite your environment:

  • <build-type>: Debug, Release, RelWithDebInfo, MinSizeRel
  • <path-to-gcc>: Path to C compiler
  • <path-to-g++>: Path to C++ compiler
  • <path-to-project-folder>
  • <path-to-build-folder>
  • <generator-to-use>: Commonly used: ninja
cmake -DCMAKE_BUILD_TYPE:STRING=<build-type> -DCMAKE_C_COMPILER:FILEPATH=<path-to-gcc> -DCMAKE_CXX_COMPILER:FILEPATH=<path-to-g++> -S<path-to-project-folder> -B<path-to-build-folder> -G <generator-to-use>

An example for the previous command would be something similar to:

Warning The following command is an example. It will not run on your machine without adjustments.

cmake -DCMAKE_BUILD_TYPE:STRING=Debug -DCMAKE_C_COMPILER:FILEPATH=/usr/bin/gcc -DCMAKE_CXX_COMPILER:FILEPATH=/usr/bin/g++ -S/home/user_name/dev/capability-based-routing -B/home/user_name/dev/capability-based-routing/build -G Ninja

During the configuration CMake will automatically fetch the required dependencies and setup everything necessary for building the project and the example executable.

2. Building the Example executable

Note Make sure to replace the following parts of the following command to suite your environment:

  • <path-to-build-folder>: This should be the same as the one provided to the previous command
  • <build-type>: Debug, Release, RelWithDebInfo, MinSizeRel
cmake --build <path-to-build-folder> --config <build-type> --target capability-based-routing-example --

After running the previous command CMake should compile and link the library and the example. The executable can then be found in the build directory provided in the arguments.

3. Running the example

Note To keep the example simple the paths to some requirements such as the map file and the proofs where hardcoded as relative paths to the executable. Therefor the following folder structure is required for the example to function:

project_folder/
├── build/
│     ├── capability-based-routing-example
│     ...
├── example
│     ├── maps/
│     │     └── DA_City_network_Lanelet2_BSSD.osm
│     ├── proofs/
|     |     ├── DC_reserv_1.json
|     |     ├── DC_reserv_2.json
|     |     ├── DC_reserv_3.json
|     |     └── DC_reserv_4.json
│     ...
...

Navigate to the build folder:

Note Make sure to replace <path-to-build-folder> with the path to your build folder.

cd <path-to-build-folder>

Run the example:

./capability-based-routing-example

The results should be printed to the terminal for inspection.

Map Loading

Use the FileLoader class to load BSSD from your map. The loader will also check your map for errors and report them. If your map is not valid, the loader will throw an exception. You can handle these exceptions by overriding the exception handler functions to patch your map on the fly. Check out how it's done in the ExampleFileLoader.h file.

Error Handler

Function Description Parameters
missingTagHandler Gets called if a expected tag is missing in a relation.
  • capbasedrouting::loader::Relation &rel: The associated relation
  • const std::string &missingTag: The missing tag
invalidTagValueHandler Gets called if a tag contains a unexpected value.
  • capbasedrouting::loader::Relation &rel: The associated relation
  • const std::string &missingTag: The missing tag
  • const std::string &val: The invalid value
missingRoleHandler Gets called if a expected role is missing in a relation.
  • capbasedrouting::loader::Relation &rel: The associated relation
  • const std::string &role: The missing role name
uniqueRoleRedefinitionHandler Gets called if a unique role is defined two or more times inside a relation.
  • capbasedrouting::loader::Relation &rel: The associated relation
  • std::list<lanelet::Id> &ids: A List of all duplicate role ids
  • const std::string &role: The role name
undefinedMemberReferenceHandler Gets called if a member reference is not defined or malformed inside the map.
  • capbasedrouting::loader::Relation &rel: The associated relation
  • const std::string &role: The role name
  • The missing or malformed reference

Routing Events

While calculating the route, the CapBasedRouting library will emit events. To access those events inherit from the MatchingCost class and override the desired functions. Check out how it's done in the MyOwnCost.h file.

Event Types

Function Description Parameters
transitionEvent Will be called everytime a transition between two BehaviorSpaces is checked.
  • capbasedrouting::bssd::BehaviorSpace *from
  • capbasedrouting::bssd::BehaviorSpace *to
matchingCriteriaEvent Will be called everytime a MatchingCriteria is calculated for a transition between two BehaviorSpaces.
  • capbasedrouting::matching::MatchingCriteria &mc
matchEvent Will be called if a MatchingCriteria satisfies a proof.
  • capbasedrouting::bssd::BehaviorSpace *from
  • capbasedrouting::bssd::BehaviorSpace *to
  • capbasedrouting::matching::MatchingCriteria &mc
  • capbasedrouting::matching::MatchingCriteriaProof &mcp
failedMatchingEvent Will be called if there is no match between a MatchingCriteria and all available proofs.
  • capbasedrouting::bssd::BehaviorSpace *from
  • capbasedrouting::bssd::BehaviorSpace *to
  • capbasedrouting::matching::MatchingCriteria &mc
transitionSuccessEvent Will be called if all calculated MatchingCriteria of a transition satisfied at least one proof and the transition is valid.
  • capbasedrouting::bssd::BehaviorSpace *from
  • capbasedrouting::bssd::BehaviorSpace *to