diff --git a/doc/manual/checker_library.md b/doc/manual/checker_library.md index 9404f56e..6a7121a5 100644 --- a/doc/manual/checker_library.md +++ b/doc/manual/checker_library.md @@ -57,8 +57,10 @@ rule._ ### Check Characteristics -- A check should addresses exactly one rule. In reality, a check can address - several rules, or several checks might be necessary to check a certain rule. +- A check should address exactly one rule, + unless there is a strong reason not to. In exceptional cases, + a check may address multiple rules, or multiple checks may be + required to check a particular rule. - Each check shall have a minimum of two example input files. The first demonstrating a rule violation and the second showcasing a successful rule validation. diff --git a/examples/esmini_viewer/README.md b/doc/manual/esmini_viewer_plugin.md similarity index 50% rename from examples/esmini_viewer/README.md rename to doc/manual/esmini_viewer_plugin.md index 910fea58..45f3cf0f 100644 --- a/examples/esmini_viewer/README.md +++ b/doc/manual/esmini_viewer_plugin.md @@ -1,50 +1,52 @@ # Esmini viewer plugin -The esmini plugin is a plugin to open esmini simulator to visualize an input OpenDRIVE file +The esmini plugin is a plugin to open the [esmini simulator](https://esmini.github.io/) and visualize an input OpenDRIVE file. For each issue that contain the corresponding inertial positions, the viewer will highlight where the issue is located on the OpenDrive map. -The plugin depends on esminiLib API. More information about the API can be found on the [official documentation](https://esmini.github.io/#_esmini_lib_programming) +![example_esmini_viewer_map](images/example_esmini_map.png) + +The plugin depends on the esminiLib API. More information about the API can be found in the [official documentation](https://esmini.github.io/#_esmini_lib_programming). ## Installation -After building the framework, a new plugin will be shown in the `File` dropdown menu of the ReportGUI application +After building the framework, a new plugin will be shown in the `File` dropdown menu of the ReportGUI application. + +![esmini_viewer](images/esmini_viewer.png) -The plugin depends on a single file, the esminiLib library that is included in each [esmini release](https://github.com/esmini/esmini/releases). +Before using the plugin, the esminiLib shared object file that is included in each [esmini release](https://github.com/esmini/esmini/releases) must be downloaded. -- If you are working on windows, the library you will need is `esminiLib.dll` +- If you are working on Windows, the library file is `esminiLib.dll` -- If you are working on Linux, the library is `libesminiLib.so` +- If you are working on Linux, the library file is `libesminiLib.so` -The library file needs to be downloaded on user local computer. +The library file must be downloaded to the user's local computer. -Then, the application searches for the library file following this approach: +The application searches for the library file following this approach: -1. Check if library file is present in the folder pointed by the `ESMINI_LIB_PATH` environment variable -2. Check if library file is present in the folder where the `ReportGUI` executable is present +1. Check if the library file exists in the folder pointed to by the `ESMINI_LIB_PATH` environment variable. +2. Check if the library file is present in the folder where the `ReportGUI' executable is present. So in order to use the plugin you can either: -- Define the ESMINI_LIB_PATH environment variable to where you downloaded the library file from esmini +- Define the `ESMINI_LIB_PATH` environment variable to where you downloaded the library file from esmini e.g. ``` export ESMINI_LIB_PATH=/home/user/Downloads/esmini-demo/bin ``` -- Copy the library file to the location where ReportGUI application is present +- Or, copy the library file to the location where ReportGUI application is present e.g. ``` cp /home/user/Downloads/esmini-demo/bin/libesminiLib.so ~/qc-build/bin/ ``` - - ## Additional information #### Which OpenDRIVE file to render -In order to establish which openDRIVE file to render in esmini, the plugin reads the `InputFile`` param from currently shown result file: +In order to establish which OpenDRIVE file to render in esmini, the plugin reads the `InputFile` param from the result file: - If it is an OTX file, ignore it - If it is an XODR file, wrap it in a simple and empty xosc file @@ -61,3 +63,5 @@ The plugin uses the following function from esminiLib: - [`SE_ReportObjectPosXYH`](https://github.com/esmini/esmini/blob/master/EnvironmentSimulator/Libraries/esminiLib/esminiLib.cpp#L1191): used to move the camera at specified location - [`SE_Step`](https://github.com/esmini/esmini/blob/master/EnvironmentSimulator/Libraries/esminiLib/esminiLib.cpp#L955): used to allow the esmini player to advance - [`SE_Close`](https://github.com/esmini/esmini/blob/master/EnvironmentSimulator/Libraries/esminiLib/esminiLib.cpp#L939): used to close the esmini player + +The plugin was tested with [esmini 2.38.3](https://github.com/esmini/esmini/releases/tag/v2.38.3). \ No newline at end of file diff --git a/doc/manual/images/esmini_viewer.png b/doc/manual/images/esmini_viewer.png new file mode 100644 index 00000000..a9f951c7 Binary files /dev/null and b/doc/manual/images/esmini_viewer.png differ diff --git a/doc/manual/images/example_esmini_map.png b/doc/manual/images/example_esmini_map.png new file mode 100644 index 00000000..470d64e9 Binary files /dev/null and b/doc/manual/images/example_esmini_map.png differ diff --git a/doc/manual/using_the_framework.md b/doc/manual/using_the_framework.md index 4dc4f2e4..a414e5e7 100644 --- a/doc/manual/using_the_framework.md +++ b/doc/manual/using_the_framework.md @@ -49,10 +49,13 @@ a valid FileLocation. Additionally it is possible to link issues that correspond to a 3D error with a viewer application. A 3D error is an error in the 3D model of the road network. -It gets marked with a little icon in the left part of the ReportGUI window. -This viewer is not part of the Open Source distributution of the ASAM Quality -Checker Framework framework, but we provide a binding mechanism which let's you -provide your own implementation. Please refer to [the + +A viewer application based on the [esmini simulator](https://esmini.github.io/) is +provided together with the ASAM Quality Checker Framework. Please refer to the +[esmini viewer plugin](esmini_viewer_plugin.md) installation guide for details. + +The ASAM Quality Checker Framework also provide a binding mechanism which lets you +provide your own integration to third-party viewer application. Please refer to [the documentation](viewer_interface.md) for details. ## Add Self Implemented CheckerBundles and ReportModules diff --git a/doc/manual/viewer_interface.md b/doc/manual/viewer_interface.md index fb0887e5..b771ed26 100644 --- a/doc/manual/viewer_interface.md +++ b/doc/manual/viewer_interface.md @@ -64,3 +64,7 @@ you open the GUI, it looks like in the image above and you can start the viewer from the File menu. Click on issues that represent a 3D error and find the function calls inside the console window. Your own viewer interface implementation can use this information to show the error in 3D. + +A fully functioned viewer based on the [esmini simulator](https://esmini.github.io/) +is also provided as part of the ASAM Quality Checker Framework. Please refer to +the [esmini viewer plugin](esmini_viewer_plugin.md) for details.