Skip to content

Commit

Permalink
Update documentation with quick start guide (#109)
Browse files Browse the repository at this point in the history 
Signed-off-by: hoangtungdinh <[email protected]>
  • Loading branch information
@hoangtungdinh
hoangtungdinh committed Jul 30, 2024
1 parent 2e1a530 commit 9830ced
Show file tree
Hide file tree
Showing 4 changed files with 161 additions and 189 deletions.
162 changes: 122 additions & 40 deletions INSTALL.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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: <https://cmake.org/download>)
- 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
Expand All @@ -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:
<https://www.asam.net/standards/detail/opendrive>).

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:
<https://www.asam.net/standards/detail/openscenario>).

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):

Expand Down Expand Up @@ -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 <https://github.com/google/googletest>) |

## 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_**.
10 changes: 3 additions & 7 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
137 changes: 22 additions & 115 deletions doc/manual/using_the_framework.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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.
Loading

0 comments on commit 9830ced

Please sign in to comment.