diff --git a/INSTALL.md b/INSTALL.md index bf565dc7..e351f4c6 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -8,15 +8,16 @@ with this file, You can obtain one at https://mozilla.org/MPL/2.0/. # How-to Build and Install -The ASAM Quality Checker Framework runs on Linux and Windows. +The ASAM Quality Checker Framework runs on Linux and Windows. The framework consists of both C++ and Python components. ## Toolchain - GCC 7.5 or newer compiler under Linux or Visual Studio 16 2019 or newer compiler under Windows -- CMake 3.16 or newer (get it here: ) +- CMake 3.16 or newer +- Python 3.10 or newer (otherwise, Conda can be used to install Python 3.10 or newer) -## 3rd Party Dependencies +## 3rd Party Dependencies for C++ Components - Xerces-C++ - Qt 5 @@ -25,51 +26,44 @@ The ASAM Quality Checker Framework runs on Linux and Windows. Links to download the sources and the tested versions can be found in the [license information appendix](licenses/readme.md). -## 3rd Party Data File Dependencies +On Linux, toolchain and 3rd party dependencies can be installed as follows (example for Ubuntu 22.04). -- ASAM OpenDRIVE XML Schema files (*.xsd) (request download here: - ). - - Currently supported versions are: - - 1.1 - - 1.2 - - 1.3D - - 1.4H - - 1.5M - - 1.6.1 - - 1.7.0 - -- ASAM OpenSCENARIO XML Schema files (*.xsd) (request download here: - ). - - Currently supported versions are: - - 0.9.1 - - 1.0.0 - - 1.1.0 - -The XSD files are required for the basic test of validating the formal -correctness of a OpenDRIVE or OpenSCENARIO file. All ASAM files are free of -charge and require only a valid email address to enable the download. - -## Preparation - -Before we can proceed to build and install the software, we need to setup all -3rd party dependencies. Download, build and install the above listed. - -After the download of at least one ASAM OpenDRIVE and one ASAM OpenSCENARIO -specification the XSD files from the archives need to be placed in some -arbitrary folders. Older versions have only a single XSD file, whereas newer -versions have multiple files. Nevertheless, extract all XSD files into an empty -folder. After a successful installation of the ASAM Quality Checker Framework -this folder can be deleted. +```bash +apt update && apt install -y \ + g++ \ + g++-10 \ + make \ + build-essential \ + cmake \ + libgtest-dev \ + qtbase5-dev \ + libqt5xmlpatterns5-dev \ + libxerces-c-dev \ + pkg-config \ + python3.10-venv \ + git +``` -## Build +## Build C++ components - Use CMakeLists.txt within the main directory as source directory - Do not forget to set `CMAKE_INSTALL_PREFIX` - Do not forget to set `CMAKE_BUILD_TYPE` if using CMake generator `Unix Makefiles` +For Linux, an example CMake call to build the framework +looks like this (call from the repository root): + +```bash +cmake -G "Unix Makefiles" -B./build -S . \ + -DCMAKE_INSTALL_PREFIX="/home/$(whoami)/qc-build" \ + -DENABLE_FUNCTIONAL_TESTS=ON -DXERCES_ROOT="/usr" \ + -DQt5_DIR="/usr/lib/x86_64-linux-gnu/cmake/Qt5/" \ + -DQt5XmlPatterns_DIR="/usr/lib/x86_64-linux-gnu/cmake/Qt5XmlPatterns/" +cmake --build ./build --target install --config Release -j4 +cmake --install ./build +``` + For Windows Visual Studio 16 2019 an example CMake call to build the framework looks like this (call from the repository root): @@ -106,3 +100,91 @@ With the following CMake values: | Name | Value | Description | Remarks | | ---- | ----- | ----------- | ------- | | ENABLE_FUNCTIONAL_TESTS | ON/OFF | choose whether the tests were created in the building process of the libraries or not | dependency to a valid gtest package needed (see ) | + +## Setup Virtual Environment for Python Components + +Virtual environment for Python components can be setup with both [virtualenv](https://docs.python.org/3/library/venv.html) (if Python 3.10 or newer is available on your computer) and [Conda](https://docs.anaconda.com/miniconda/) (if Python 3.10 or newer is not available on your computer). + +Using Virtualenv: + +```bash +python3 -m venv runtime-venv +source runtime-venv/bin/activate +python3 -m pip install --no-cache-dir -r runtime/requirements.txt +``` + +Using Conda: + +```bash +conda create -y -n runtime-venv python=3.10 +conda activate runtime-venv +python3 -m pip install --no-cache-dir -r runtime/requirements.txt +``` + +## Install ASAM Checker Bundles + +Standard ASAM Checker Bundles are implemented in Python. It is recommended to use virtual environment to setup standard ASAM Checker Bundles. Both [virtualenv](https://docs.python.org/3/library/venv.html) and [Conda](https://docs.anaconda.com/miniconda/) can be used to setup the virtual environment. + +### Using virtualenv + +#### ASAM OpenDrive Checker Bundle + +```bash +git clone --single-branch --branch develop https://github.com/asam-ev/qc-opendrive.git +python3 -m venv opendrive-venv +source opendrive-venv/bin/activate +python3 -m pip install --no-cache-dir -r qc-opendrive/requirements.txt +``` + +#### ASAM OpenScenario XML Checker Bundle + +```bash +git clone --single-branch --branch develop https://github.com/asam-ev/qc-openscenarioxml.git +python3 -m venv openscenario-venv +source openscenario-venv/bin/activate +python3 -m pip install --no-cache-dir -r qc-openscenarioxml/requirements.txt +``` + +#### ASAM OTX Checker Bundle + +```bash +git clone --single-branch --branch develop https://github.com/asam-ev/qc-otx.git +python3 -m venv otx-venv +source otx-venv/bin/activate +python3 -m pip install --no-cache-dir -r qc-otx/requirements.txt +``` + +### Using Conda + +#### ASAM OpenDrive Checker Bundle + +```bash +git clone --single-branch --branch develop https://github.com/asam-ev/qc-opendrive.git +conda create -y -n opendrive-venv python=3.10 +conda activate opendrive-venv +python3 -m pip install --no-cache-dir -r qc-opendrive/requirements.txt +``` + +#### ASAM OpenScenario XML Checker Bundle + +```bash +git clone --single-branch --branch develop https://github.com/asam-ev/qc-openscenarioxml.git +conda create -y -n openscenario-venv python=3.10 +conda activate openscenario-venv +python3 -m pip install --no-cache-dir -r qc-openscenarioxml/requirements.txt +``` + +#### ASAM OTX Checker Bundle + +```bash +git clone --single-branch --branch develop https://github.com/asam-ev/qc-otx.git +conda create -y -n otx-venv python=3.10 +conda activate otx-venv +python3 -m pip install --no-cache-dir -r qc-otx/requirements.txt +``` + +## Register ASAM Checker Bundles + +Both standard ASAM Checker Bundles and custom Checker Bundles must be registered with the framework before they can be used. + +**_Placeholder explaining how to register checker bundles with the framework using the manifest file_**. diff --git a/README.md b/README.md index 352c7f14..02ba1c09 100644 --- a/README.md +++ b/README.md @@ -80,15 +80,11 @@ A [Docker-based demo pipeline](demo_pipeline/README.md) is provided to help user of the framework, as well as the [OpenDrive](https://github.com/asam-ev/qc-opendrive/tree/develop) and [OpenScenario XML](https://github.com/asam-ev/qc-openscenarioxml/tree/develop) checker bundles. -## Build the framework locally +## Build and run the framework locally -As the framework is still under development, it is not recommended to build -it locally. A complete build instruction will be available in the near future. +Follow the [build instructions](INSTALL.md) to install the framework on your machine. -The software can be build for Windows and Linux. Currently there are no -pre-built binaries available for the framework. Follow the [build -instructions](INSTALL.md) to create a runnable binary on your machine. -[Examples](examples) are provided in this repository. +Follow the [run instructions](doc/manual/using_the_framework.md) to run the Checker Bundles using the framework on your machine. # How to Contribute diff --git a/doc/manual/using_the_framework.md b/doc/manual/using_the_framework.md index 9b74f1f4..92ba4156 100644 --- a/doc/manual/using_the_framework.md +++ b/doc/manual/using_the_framework.md @@ -6,85 +6,29 @@ Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/. --> -# **_This document is under construction. The information in this document does not reflect the current state of the framework._** - # Using the ASAM Quality Checker Framework -## Configuration - -### Introduction - -The following documentation refers to the Windows installation. The ASAM -Quality Checker Framework core is available for other platforms as well. See -[the Linux paragraph](#linux) for usage instructions under Linux. - -For starting the configuration GUI and the framework just start - -- `ConfigGUI.exe` - -in the `bin` directory of your installation. Per default, -`DefaultXodrConfiguration.xml` is loaded by the application. You are free to -replace this configuration by a different one. Depending on your use case, you -will find the following pre defined configurations: - -- `DefaultXodrConfiguration.xml` which can be used to check OpenDRIVE -- `DefaultXoscConfiguration.xml` which can be used to check OpenSCENARIO - -You can open a configuration, by simply dropping the XML on the executable. - -![Config GUI](images/config_gui.png) - -From there the CheckerBundle and ReportModuls can be selected and their -parameter can be set. Special parameters are the global parameters - -- `XodrFile` -- `XoscFile` - -on the top of the configuration GUI. These parameters define the OpenDRIVE file -and/or the OpenSCENARIO file which should be checked. All global parameters are -passed to all CheckerBundles. When defining a XoscFile the XodrFile will be -automatically retrieved, if an OpenDRIVE file reference is defined in the -scenario. Both parameters are stored as absolute file paths currently. - -### Loading/Executing Configurations - -The loaded configuration is shown on the left side of the GUI. The right side -shows the output of each executable in sequence. - -To open an existing configuration, use the menu **File→Open** or start the -ConfigGUI.exe with the configuration as a command line argument. - -The configuration can be started with the big arrow button. The first step in -the execution is a **CleanUp**, where the old temporary files are deleted. -After that, all configured CheckerBundles are executed as configured. The shown -order in the configuration is also the order of it's execution. As a final step -before calling the report modules, the result pooling is called automatically -to store the checker results in one result file. +## Create Configuration File -### Changing/Saving Configurations +Create a [configuration file](file_formats.md) to use the framework, following [the predefined configuration file schema](https://github.com/asam-ev/qc-framework/blob/develop/doc/schema/config_format.xsd). -The configuration can be modified in the GUI with the context menu. Just press -the right mouse button to add, remove or change the order of the modules. It's -also possible to modify the parameters of the CheckerBundles. Within the menu -**File → Save** or **File → SaveAs** can be used to write the configuration to -a file. This is necessary before executing the CheckerBundles for the first -time. +Example configuration files for running the official Checker Bundles for ASAM OpenDrive, OpenScenario XML and OTX can be found in [the templates folder](https://github.com/asam-ev/qc-framework/tree/develop/demo_pipeline/templates). -If you want to create a configuration from scratch use the menu **File →New**. +## Run the Checker Bundles -Own CheckerBundles and the ReportModules have to follow the specification in -[CheckerBundle/ReportModule Meta Model](writing_user_defined_modules.md). If -they use this mechanisms then the framework is able to include their output in -the toolchain. +The Checker Bundles can be run using the [runtime component](../../runtime/README.md). -### Export Log Files +```bash +source runtime-venv/bin/activate +python3 runtime/runtime/runtime.py \ + --config "PATH_TO_YOUR_CONFIG_FILE" \ + --install_dir "qc-build/bin" \ + --schema_dir "doc/schema" +``` -To export the log from the right side of the GUI, you can use the menu entry -**Console->Save** to store the output in one file. +**_Note: The above runtime execution will change after Manifest file is supported. E.g., schema_dir, install_dir will be removed._** -## Available Checker Bundles - -- [SchemaChecker](schema_checker.md) +The output of the runtime components are the `.xqar` [result files](file_formats.md) and any other output files from the specified report modules in the configuration file, such as `.txt` files for the text report module. If the ReportGUI is specified, the Report GUI will open. ## Reporting @@ -96,7 +40,7 @@ specification can be found on the page [File formats](file_formats.md). The ASAM Quality Checker Framework contains the following report modules: - TextReport - generating a human readable text file with all issues -- ReportGUI (Windows only) +- ReportGUI ### Using the ReportGUI @@ -119,52 +63,15 @@ documentation](viewer_interface.md) for details. ## Add Self Implemented CheckerBundles and ReportModules -You can add your own CheckerBundles and ReportModules to the configuration. -Just add the executables with the graphical user interface. +You can add your own CheckerBundles and ReportModules to the framework. +Just add the executables to the folder where the framework executables are installed. +This will make the executables available to the runtime component. +In our example above, the folder is `qc-build/bin`. -![Add CheckerBundle](images/add_checker_bundle.png) +**_Note: The above instruction will change after the Manifest file is supported._** -This will call the executable, which generates a file in the defined Result -Format (XQAR) without any issues. The Config GUI extracts the included Checkers -and their parameters from there. +Executables for Checker Bundles written in any programming languages can be created using +bash script, even for intepreted languages like Python. Requirements for your own CheckerBundle can be found in the [User defined modules](writing_user_defined_modules.md) documentation. - -## Automation and Deployment - -There are several ways for automating the checking process - -Open user interface and load the `DefaultConfiguration.xml` - - > ConfigGUI.exe - -Open user interface and load a specified configuration - - > ConfigGUI.exe myConfiguration.xml - -Open user interface, load the specified configuration and run the process -without user input - - > ConfigGUI.exe myConfiguration.xml -autostart - -Open the application with `myConfiguration.xml` and a given XODR, which is -under test. Autostart enables the automatic mode - - > ConfigGUI.exe -config myConfiguration.xml -xodr myTrack.xodr [-autostart] - -Open the application with `myConfiguration.xml` and a given XOSC, which is -under test. Autostart enables the automatic mode - - > ConfigGUI.exe -config myConfiguration.xml -xosc myScenario.xosc -autostart - -The easiest way is to adapt and use the two delivered batch scripts -`CheckXodr.bat` and `CheckXosc.bat`. They automate the complete process and -execute all delivered CheckerBundles, create a text based report and open the -ReportGUI for filtering the results. - -## Linux - -You can use the shell scripts `CheckXodr.sh` and `CheckXosc.sh` in combination -with a self-written configuration file for execution and generation of a -textual report. diff --git a/doc/manual/writing_user_defined_modules.md b/doc/manual/writing_user_defined_modules.md index e1a78f80..37d2ac47 100644 --- a/doc/manual/writing_user_defined_modules.md +++ b/doc/manual/writing_user_defined_modules.md @@ -23,6 +23,11 @@ it should print a short help how to use it. **Note:** The [Python Base Library](https://github.com/asam-ev/qc-baselib-py) and the [C++ Base Library](cpp_base_library.md) help to read and write the file formats. +Example Checker Bundles using the Python Base Library can be found on the following repositories: +* https://github.com/asam-ev/qc-openscenarioxml +* https://github.com/asam-ev/qc-opendrive +* https://github.com/asam-ev/qc-otx + ### Run One Single CheckerBundle Based on a Configuration Your CheckerBundle should accept a xml file containing its configuration parameters. @@ -31,28 +36,20 @@ All **modules which follow this convention are a part of the framework** and > checker_bundle_exe configuration.xml -### Determine Checkers and Parameters - -If the CheckerBundle executable is called with the command line argument -`--defaultConfig`, it should write a report file (.xqar, see Base library for -details) containing all checkers with their parameters and no issues. Each -parameter should contain default values. The name of the file has to -corresponds to the executable name (myCheckerBundle.exe should write -myCheckerBundle.xqar). - - > checker_bundle_exe --defaultConfig +**Note:** Any Checker Bundle can have an executable using Bash script, even if the Checker Bundle is implemented in intepreted languages like Python. ### Check a Single File With One Single CheckerBundle -A CheckerBundle can be called with one command line parameter and optional -parameter settings. The first parameter defines the file which should be -checked. The additional options are specific for the CheckerBundle and not -defined here. As in the previous cases the CheckerBundle should write in the -current directory an (.xqar) file with the same name as the executable. +A CheckerBundle can be called with one command line parameter. +The first parameter defines the configuration file. +The CheckerBundle should write in the current directory an (.xqar) +file with the same name as the executable. + +**_Note: The above instruction will change after the Manifest file is supported._** This approach is used when testing only one CheckerBundle. - > checker_bundle_exe track.xodr [-o1 -o2 ...] + > checker_bundle_exe config.xml ## ReportModules @@ -62,17 +59,7 @@ This approach is used when testing only one CheckerBundle. - Your own module shall visualize the results based on the result format - Your module shall take a module configuration, based on the configuration format. -- Your module shall provide a default configuration by the parameter - {{--defaultConfig}} - The executable needs execution rights and its location should be the bin folder (see [File Formats](file_formats.md) for configuration details) -### Determine Configurations for ReportModules - -If a ReportModule executable is called with the command line argument -`--defaultConfig`, it should write a configuration file (.xml) containing all -the parameters. Each parameter should contain default values. The name of the -file has to corresponds to the executable name (myReportModule.exe should write -myReportModule.xml). - - > report_module_exe --defaultConfig +Here is [an example ReportModule implemented in Python](https://github.com/asam-ev/qc-baselib-py/tree/develop/examples/report_module_text).