Rail Horizon is a ROS2 Node which provides train map foresight (an excerpt of digital map data) by processing mission profile, map regions and coupled localization data. The train map foresight is provided in a form of a ROS Message called RailHorizonStamped, containing the map data in a local sensor coordinate system and global coordinate system.
First clone the project (ssh recommended) and in case of ssh add some replacement patterns, so submodules will be converted to ssh:
git config --global url."git@github.com:".insteadOf "https://github.com/"Then initialize all submodules recursively:
git submodule update --init --recursiveDependencies (Recommended: Ubuntu 22.04):
- ROS2 Humble
- Python:
sudo apt install python - Boost:
sudo apt install libboost-all-dev - Proj:
sudo apt install libproj-dev - Protobuf (Map Service):
sudo apt install libprotobuf-dev protobuf-compiler - Curl (Map Service):
sudo apt install libcurl4-openssl-dev
You should also create the underlay, which is the underlying workspace with ROS2 Tools available. It behaves similarly to a virtual environment and allows having multiple ROS2 versions installed on the system and use a specific one for each project. The underlay can be created automatically for every terminal session or manually at the beginning of a new session like this:
source /opt/ros/humble/setup.bashCheck if all dependencies are available with:
rosdep install -i --from-path src --rosdistro humble -ySome environment variables need to be set for the map service:
export RMW_IMPLEMENTATION=rmw_fastrtps_cpp
export PERSISTENT_STORAGE_ROOT_DIR=~/documents/maps
export DB_MAP_VERSION=63
export DB_MAP_ENDPOINT=DBMC
export DB_MAP_CATALOG=validate.s4r2.oss.4- They can be set for a terminal session, loaded automatically in
~/.bashrc(Don't forget to source the file:source ~/.bashrc) or globally for all sessions and users inetc/environment(Syntax is different)
Use colcon build to build the project. Some variables are specified, which are needed for the projects. As in CMake, they only have to specified once for each build directory as they are cached:
export CMAKE_BUILD_PARALLEL_LEVEL=10
colcon build --base-paths src --cmake-args -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=ON --event-handlers console_cohesion+ --packages-up-to dsd_rail_horizon-DCMAKE_EXPORT_COMPILE_COMMANDS=ONis optional. It generates a compilation database for tooling. For instance, clang-tidy needs it, which is run as a pre-commit.-G Ninjacan optionally be added to the--cmake-args. If theninjabuild system is installed on the system, it can be used instead of make. Builds usually are a lot faster then.
After the build, you should source the install folder:
source ./install/local_setup.bashCurrently, Rail Horizon supports one map region of interest (roi) which is given in the parameters.yaml configuration file. Rail Horizon can be run with the config file specified on the command line.
ros2 run dsd_rail_horizon dsd_rail_horizon --ros-args --params-file ./install/dsd_rail_horizon/config/dsd_rail_horizon/parameters.yamlRun all tests:
ctest --test-dir build/dsd_rail_horizon --output-on-failureRun all C++ unit tests:
ctest --test-dir build/dsd_rail_horizon -L "UnitTests" --output-on-failureRun all Python integration tests:
ctest --test-dir build/dsd_rail_horizon -L "IntegrationTests" --output-on-failureGenerate coverage report with:
gcovr --exclude-unreachable-branches --exclude-throw-branches -r . --filter src/ --exclude '.*tests/' --html --html-details -o build/coverage.htmlThe generated file build/coverage.html contains the report.
Dependencies:
- pre-commit ^3.2:
sudo apt install pre-commit - clang-format ^14.0:
sudo apt install clang-format(or:pipx install clang-format) - clang-tidy ^14.0:
sudo apt install clang-tidy - include-what-you-use ^0.17 (optional, see below):
sudo apt install iwyu
We use pre-commit to enforce usage of tools such as clang-format on commit. This ensures that tools such as clang-format are run on a commit, and thus keeps our repository consistent and makes review easier.
Install all the hooks with:
pre-commit installPre-commit will be then automatically run on changed files in a commit. Additionally, it can also be run manually against all files with:
pre-commit run --all-filesThe tool include-what-you-use can help to find the right includes. This makes dependencies obvious and avoids transitive includes, which are bad practice. The setup of the tool is more involved and additionally the output of the tool is not yet perfect and requires tweaking. For these reasons, the tool should be run only manually after other changes have been committed, and the output should be carefully reviewed.
As include-what-you-use is basically built on top of some specific clang version, the development header should be installed:
sudo apt install libclang-common-13-dev- The clang version can be found out with
strings /usr/bin/iwyu | grep LLVM. On Ubuntu 22.04 this givesLLVM_13.
The tool can be run as a manual pre-commit job:
pre-commit run --hook-stage manual include-what-you-use --all-files- Note: This will also automatically apply clang format to fix the order of includes
The configuration of the command line arguments can be found in tools/iwyu_precommit.py. Additionally, we use mostly automatically generated mapping files. If iwyu suggest using the wrong header (for instance some internal header file, which is not supposed to be used) then likely adjustments need to be made to the mapping file. In this case, make the appropriate changes to tools/generate_mappings.py. The mappings will be automatically created by the precommit in build/iwyu_mappings.
Additionally, some pragmas can be used as well to fix the output. Or changes can be manually overwritten.
This project is compliant with the REUSE Specification Version 3.0
Copyright DB Netz AG, licensed under Apache 2.0 (see full text in LICENSES/Apache-2.0.txt)
Dot-files, cmake-files and config-files are licensed under CC0-1.0 (see full text in LICENSES/CC0-1.0.txt)
