Merge pull request #111 from asam-ev/2024-07-30

Improve report GUI, demo pipeline, documentation and add ci report module

.github/workflows/build-and-push-demo-pipeline.yaml

@@ -6,6 +6,7 @@ on:
 
 jobs:
   build-and-push-demo:
+    if: github.repository_owner == 'asam-ev'
     runs-on: ubuntu-22.04
 
     permissions:

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: <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
@@ -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):
 
@@ -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_**.

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
 

demo_pipeline/configuration_generator.py

@@ -8,6 +8,7 @@
 
 XODR_TEMPLATE_PATH = "/app/demo_pipeline/templates/xodr_template.xml"
 XOSC_TEMPLATE_PATH = "/app/demo_pipeline/templates/xosc_template.xml"
+OTX_TEMPLATE_PATH = "/app/demo_pipeline/templates/otx_template.xml"
 GENERATED_CONFIG_PATH = "/tmp/generated_config"
 
 
@@ -33,7 +34,9 @@ def main():
     os.makedirs(GENERATED_CONFIG_PATH, exist_ok=True)
 
     if not os.path.isfile(full_input_path):
-        print("No file specified as input. Please provide xosc or xodr file. Exiting...")
+        print(
+            "No file specified as input. Please provide xosc, xodr or otx file. Exiting..."
+        )
         return
 
     print("Input file: ", full_input_path)
@@ -55,6 +58,14 @@ def main():
             full_input_path,
             os.path.join(GENERATED_CONFIG_PATH, "config.xml"),
         )
+    elif input_file_extension == ".otx":
+        print("OTX selected")
+        update_param_value(
+            OTX_TEMPLATE_PATH,
+            "OtxFile",
+            full_input_path,
+            os.path.join(GENERATED_CONFIG_PATH, "config.xml"),
+        )
     else:
         print(f"Error in input file extension. Unrecognized {input_file_extension}")
         return

demo_pipeline/otxBundle

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+# Copyright 2024, ASAM e.V.
+# This Source Code Form is subject to the terms of the Mozilla
+# 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/.
+readonly CONFIG_FILE=$1
+
+source /app/otx-venv/bin/activate
+cd /app/qc-otx
+python main.py -c $CONFIG_FILE
+cp *.xqar /app/framework/bin/

demo_pipeline/run_pipeline.sh

@@ -7,8 +7,7 @@ python3 /app/demo_pipeline/configuration_generator.py
 
 python3 /app/framework/runtime/runtime/runtime.py \
     --config "/tmp/generated_config/config.xml" \
-    --install_dir "/app/framework/bin" \
-    --schema_dir "/app/framework/doc/schema"
+    --install_dir "/app/framework/bin"
 
 mkdir -p /out/qc-result-$INPUT_FILENAME
 cp /app/framework/bin/*.xqar /out/qc-result-$INPUT_FILENAME

demo_pipeline/templates/otx_template.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<Config>
+
+    <Param name="OtxFile" value="test.otx" />
+
+    <CheckerBundle application="otxBundle">
+        <Param name="resultFile" value="otx_bundle_report.xqar" />
+        <Checker checkerId="basic_otx" maxLevel="1" minLevel="3" />
+        <Checker checkerId="data_type_otx" maxLevel="1" minLevel="3" />
+    </CheckerBundle>
+
+    <ReportModule application="TextReport">
+        <Param name="strInputFile" value="Result.xqar" />
+        <Param name="strReportFile" value="Report.txt" />
+    </ReportModule>
+
+</Config>

demo_pipeline/templates/xodr_template.xml

@@ -6,6 +6,7 @@
     <CheckerBundle application="xodrBundle">
         <Param name="resultFile" value="xodr_bundle_report.xqar" />
         <Checker checkerId="semantic_xodr" maxLevel="1" minLevel="3" />
+        <Checker checkerId="geometry_xodr" maxLevel="1" minLevel="3" />
     </CheckerBundle>
 
     <ReportModule application="TextReport">

demo_pipeline/templates/xosc_template.xml

@@ -5,6 +5,11 @@
 
     <CheckerBundle application="xoscBundle">
         <Param name="resultFile" value="xosc_bundle_report.xqar" />
+        <Checker checkerId="basic_xosc" maxLevel="1" minLevel="3" />
+        <Checker checkerId="schema_xosc" maxLevel="1" minLevel="3" />
+        <Checker checkerId="data_type_xosc" maxLevel="1" minLevel="3" />
+        <Checker checkerId="parameters_xosc" maxLevel="1" minLevel="3" />
+        <Checker checkerId="reference_xosc" maxLevel="1" minLevel="3" />
         <Checker checkerId="schema_xosc" maxLevel="1" minLevel="3" />
     </CheckerBundle>