Documentation

README.rst

@@ -4,12 +4,15 @@ Road Generation Tool for Basic OpenDRIVE Road Networks
 .. image:: https://camo.githubusercontent.com/83d3746e5881c1867665223424263d8e604df233d0a11aae0813e0414d433943/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667
 
 
-.. inclusion-marker
+
 
 
 About
 -----
 
+.. inclusion-marker
+
+
 Simulation is a valuable building block for the verification and
 validation of automated driving functions (ADF). When simulating urban
 driving scenarios, simulation maps are one important component. Often,
@@ -46,22 +49,43 @@ tool.
 
 Fig.1: Possible workflow for the presend road variation tool.
 
+Documentation
+-------------
+
+If you want to include the library in a project, a simple but well designed C++ reference
+`documentation <https://ika-rwth-aachen.github.io/RoadGeneration/index.html>`__ is provided.
+The input file format specification can be found `here <https://ika-rwth-aachen.github.io/RoadGeneration/inputdoc.html>`_.
+
+Variation tool
+--------------
+
+The Variation tool is used to generate a variety of different scenarios
+based on the same general road network. A template file is provided to
+specify variables as well as the general road network structure. A more
+thorough documentation can be found in the `variation
+subdirectory <variation/>`__.
+
+
+
 Repository Overview
 -------------------
 
 This repository provides a tool for the generation of road networks.
 Here, the main folders are named:
 
 -  ``doc``: Resources for documentation
--  ``io``: Sample input files
+-  ``examples``: Examlpe and Template files that showcase minimal working inputs
 -  ``src``: Source code
--  ``test``: Test files and their desired OpenDRIVE outputs
+-  ``test``: Test file .xml and .xodr pairs
 -  ``xml``: Contains the XSD validation files
 -  ``variation``: Python based variation tool for the road generator
 
 Installation
 ------------
 
+Road Generation
+~~~~~~~~~~~~~~~
+
 The following **requirements** have to be satisfied:
 
 -  ``C++11``
@@ -73,36 +97,47 @@ The following **requirements** have to be satisfied:
 
 .. code:: bash
 
-   # Clone Repository and open main folder
-   git clone git@github.com:ika-rwth-aachen/RoadGeneration.git
-   cd RoadGeneration
+ # Clone Repository and open main folder
+ git clone git@github.com:ika-rwth-aachen/RoadGeneration.git
+ cd RoadGeneration
 
 A build script for Linux systems is provided and can be executed from
 the root directory with
 
 .. code:: bash
 
-   sh buildScript.sh
+ sh buildScript.sh
 
 Alternatively you can **build the project manually**:
 
 1. Install `XercesC <https://xerces.apache.org/xerces-c>`_ via a
-   package manager, e.g.:
+ package manager, e.g.:
 
 .. code:: bash
 
-    $ sudo apt install libxerces-c-dev
+  $ sudo apt install libxerces-c-dev
 
 2. Build the Road-generation tool with standard cmake commands, e.g.:
 
 .. code:: bash
 
-    $ mkdir -p build && cd build && cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../bin ..
-    $ cmake --build .
+  $ mkdir -p build && cd build && cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../bin ..
+  $ cmake --build .
 
 *Note:* In principal, it is possible to compile and use the tool in
 Windows operating systems. However, this is experimental.
 
+Variation tool
+~~~~~~~~~~~~~~
+
+You can run the code from the ``variation`` subfolder, however, the
+variation tool can be installed system wide by using the install script
+in the root directory.
+
+.. code:: bash
+
+ sh install-variation.sh
+
 Usage
 -----
 
@@ -115,41 +150,12 @@ The compiled application can be called from the root folder:
 This generates the output OpenDRIVE file next to the input file. The
 provided input file is checked against ``input.xsd``. Analogous the
 output file is checked against the ``output.xsd`` file which specifies
-the openDRIVE 1.5 standard. For a list of all parameters use the help
-flag of the tool.
+the openDRIVE standard. For a list of all parameters use:
 
 .. code:: bash
 
    ./road-generation_executable -h
 
-Documentation
--------------
-
-A simple but well designed C++ reference
-`documentation <https://ika-rwth-aachen.github.io/RoadGeneration/index.html>`__
-is provided.
-
-Variation tool
---------------
-
-The Variation tool is used to generate a variety of different scenarios
-based on the same general road network. A template file is provided to
-specify variables as well as the general road network structure. A more
-thorough documentation can be found in the `variation
-subdirectory <variation/>`__.
-
-.. _installation-1:
-
-Installation
-~~~~~~~~~~~~
-
-You can run the code from the ``variation`` subfolder, however, the
-variation tool can be installed system wide by using the install script
-in the root directory.
-
-.. code:: bash
-
-   sh install-variation.sh
 
 Licenses
 --------

docs/doc.rst

@@ -1,8 +1,8 @@
 ***************
-Documentation
+Class Reference
 ***************
 
-This is the documentation for the Road Generation tool.
+This is the class reference for the Road Generation tool.
 
 interface.h
 ==============

docs/index.rst

@@ -4,10 +4,21 @@
    contain the root `toctree` directive.
 
 
-Welcome to Road's documentation!
-================================
 
-.. include:: ../README.rst
+Road Generation Documentation
+=============================
+
+Welcome to the documentation for `Road Generation <https://github.com/ika-rwth-aachen/RoadGeneration>`_! If you intend to use the tool, please follow the `Installation instructions <https://ika-rwth-aachen.github.io/RoadGeneration/readmelink.html#installation>`_.
+If you have questions about the input format, it is recommended to refer to the `Input Documentation <https://ika-rwth-aachen.github.io/RoadGeneration/inputdoc.html>`_. 
+
+Content
+^^^^^^^
+
+#. `Road Generation <https://ika-rwth-aachen.github.io/RoadGeneration/readmelink.html#>`_
+#. `Variation Tool Documentation <https://ika-rwth-aachen.github.io/RoadGeneration/variationlink.html>`_
+#. `Input Documentation <https://ika-rwth-aachen.github.io/RoadGeneration/inputdoc.html>`_  
+
+
 
 .. toctree::
     :maxdepth: 3
@@ -17,8 +28,6 @@ Welcome to Road's documentation!
     Road Generation <readmelink>
     Variation <variationlink>
 
-* :ref:`genindex`
-* :ref:`search`
 
 .. toctree::
     :maxdepth: 3

docs/inputdoc.rst

@@ -1,4 +1,4 @@
-Input file format
+Input File Format
 =================
 
 This section explains the input format and provides examples for basic usecases. Furthermore a variety of template files can be found in `io/Templates`. If the input `xsd` scheme was subject to change, this documentation needs to be updated.
@@ -708,6 +708,7 @@ SegmentLink
     fromPos, string , 'start' 'end' , specifies if the fromSegment should be linked at its beginning or end , yes
     toPos, string , 'start' 'end' , specifies if the toSegment should be linked at its beginning or end , yes
 
+
 Key points
 ^^^^^^^^^^
 
@@ -716,8 +717,12 @@ Key points
 * Segments have a seperate namespace from Roads, i.e. multiple roads with the ID 1 can exist under differen segments
 
 
-Example
-'''''''
+Examples
+''''''''
+
+You can find a example of the linking tag, as well as a minimal working example below.
+
+**Example linking**
 
 .. code-block:: xml
 
@@ -730,6 +735,39 @@ Example
     </links>
 
 
+**Complete input file**
+
+.. figure:: _static/link.png
+    :class: align-right
+    :width: 470
+
+.. code-block:: xml
+
+    <roadNetwork xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../xml/input.xsd">
+        <segments>
+        <connectingRoad id="1">
+                <road id="1" classification="main" >	
+                    <referenceLine>
+                        <line length="100"/>
+                    </referenceLine>
+                </road>
+            </connectingRoad>
+            <connectingRoad id="2">
+                <road id="1" classification="main" >	
+                <referenceLine>
+                        <spiral length="100"  Rs="-150" Re="0"/>
+                    </referenceLine>
+                </road>
+            </connectingRoad>
+
+        </segments>
+
+        <links refId="1" hdgOffset="0.0" xOffset="0" yOffset="0">
+            <segmentLink fromSegment="1" toSegment="2" fromRoad="1" toRoad="1" fromPos="end" toPos="start" />
+        </links>
+
+    </roadNetwork>
+
 CloseRoads
 ----------
 
@@ -750,6 +788,10 @@ To smoothly close open connections, roads and their respective linkage informati
 Example
 '''''''
 
+Below is an example of the close road tag and a minimal working example.
+
+**Example linking**
+
 .. code-block:: xml
 
     <closeRoads>
@@ -759,3 +801,88 @@ Example
             <segmentLink fromSegment="7" toSegment="1" fromRoad="4" toRoad="1" fromPos="end" toPos="start" />
             <segmentLink fromSegment="7" toSegment="7" fromRoad="2" toRoad="3" fromPos="end" toPos="end" />
     </closeRoads>
+
+
+**Complete input file**
+
+.. figure:: _static/close.png
+    :class: align-right
+    :width: 470
+
+.. code-block:: xml
+
+    <roadNetwork xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../xml/input.xsd">
+        <segments>
+        <connectingRoad id="1">
+                <road id="1" classification="main" >	
+                    <referenceLine>
+                        <line length="100"/>
+                    </referenceLine>
+                </road>
+            </connectingRoad>
+            <connectingRoad id="2">
+                <road id="1" classification="main" >	
+                <referenceLine>
+                        <spiral length="100"  Rs="-150" Re="0"/>
+                    </referenceLine>
+                </road>
+            </connectingRoad>
+        </segments>
+        <links refId="1" hdgOffset="0.0" xOffset="0" yOffset="0">
+            <segmentLink fromSegment="1" toSegment="2" fromRoad="1" toRoad="1" fromPos="end" toPos="start" />
+        </links>
+        <closeRoads>
+            <segmentLink fromSegment="2" toSegment="1" fromRoad="1" toRoad="1" fromPos="end" toPos="start" />
+        </closeRoads>
+    </roadNetwork>
+
+
+Elevation
+----------
+
+Elevation is not currently supported in the road generation tool. However, the input format does support it for connecting roads.
+
+
+elevationProfile
+''''''''''''''''''
+
+An elevation profile can be specified for each connecting road segment with an `elevationPoint` tag. A simple ramp or slope can be achieved by specifying the attributes listed below. The `heightDifference` is relative to the height of the segment start (at `s=0`).
+
+.. csv-table::
+    :widths: 100 100 100 100 50
+
+    **Name** , **Type** , **Range** , **Description** , **Required**
+    startRadius , double , positive , radius of curvature at the start of segment, yes
+    heightDifference , double , all , relative end height of segment , yes
+    endRadius , double , positive  , radius of curvature at the end of segment , yes
+
+
+elevationPoint
+''''''''''''''''
+
+If a more complex height profile is required, additional elevation points can be specified with the `elevationPoint` tag. Elevation points are specified relative to the height of the segment start (at `s=0`).
+
+.. csv-table::
+    :widths: 100 100 100 100 50
+
+    **Name** , **Type** , **Range** , **Description** , **Required**
+    s , double , positive , s offset of the elevation point, yes
+    height , double , all , height of elevation point , yes
+    R , double , positive  , radius of curvature on elevation point , yes
+
+
+
+**Example elevation profile**
+
+.. code-block:: xml
+
+    <connectingRoad id="1">
+        <road id="1" classification="main" >	
+            <referenceLine>
+                    <line length="100"/>
+            </referenceLine>
+            <elevationProfile startRadius="20" heightDifference="20" endRadius="15"> 
+                <elevationPoint s="40" height="-10" R="10" />
+            </elevationProfile>
+        </road>
+    </connectingRoad>

variation/README.rst

@@ -5,8 +5,7 @@ Variation Tool
 
 
 The variation tool makes use of the road-generation library and
-generates several variations of an OpenDRIVE road network that is
-provided by a template file. The main goal was to create an easy to use
+generates several variations of an OpenDRIVE road network. A special template file is provided to set the parameters of the variation. The main goal was to create an easy to use
 syntax while allowing the user to specify constraints for the output
 scenarios.