diff --git a/doc/images/class_structure.png b/doc/images/class_structure.png new file mode 100644 index 0000000000000000000000000000000000000000..65808d93bb759be387143a62e5aaa94ac967451f Binary files /dev/null and b/doc/images/class_structure.png differ diff --git a/doc/images/lanes.png b/doc/images/lanes.png new file mode 100644 index 0000000000000000000000000000000000000000..5e60a62f0c49f9e5b10b145cde7fbf792ee42cab Binary files /dev/null and b/doc/images/lanes.png differ diff --git a/doc/images/lanes_junction.png b/doc/images/lanes_junction.png new file mode 100644 index 0000000000000000000000000000000000000000..1059d4e886139e3f17e8baf26449d4fc0745a46a Binary files /dev/null and b/doc/images/lanes_junction.png differ diff --git a/doc/images/links.png b/doc/images/links.png new file mode 100644 index 0000000000000000000000000000000000000000..6ba0503f4f996a1f6c3f2c06514cac70f1c6d77b Binary files /dev/null and b/doc/images/links.png differ diff --git a/doc/images/original_road.png b/doc/images/original_road.png new file mode 100644 index 0000000000000000000000000000000000000000..7364d237f67541d0f25475bd5bd60c5b97aaea8c Binary files /dev/null and b/doc/images/original_road.png differ diff --git a/doc/images/ref_system_lanes.png b/doc/images/ref_system_lanes.png new file mode 100644 index 0000000000000000000000000000000000000000..596940da24a0c15b26ef61e2feecab5182a55629 Binary files /dev/null and b/doc/images/ref_system_lanes.png differ diff --git a/doc/images/ref_system_road_nodes.png b/doc/images/ref_system_road_nodes.png new file mode 100644 index 0000000000000000000000000000000000000000..abbc7a5b5234bb4d879a12f25244bd8c2da18856 Binary files /dev/null and b/doc/images/ref_system_road_nodes.png differ diff --git a/doc/images/ref_system_road_segments.png b/doc/images/ref_system_road_segments.png new file mode 100644 index 0000000000000000000000000000000000000000..76a11654f3866c5dcde9985797be37436446f60d Binary files /dev/null and b/doc/images/ref_system_road_segments.png differ diff --git a/doc/images/road_nodes.png b/doc/images/road_nodes.png new file mode 100644 index 0000000000000000000000000000000000000000..c525748e517ad31aff57cb4c0a2232820b4c6daf Binary files /dev/null and b/doc/images/road_nodes.png differ diff --git a/doc/images/road_segments.png b/doc/images/road_segments.png new file mode 100644 index 0000000000000000000000000000000000000000..7597c7fadad952329a6f7c62578d541b75881ff9 Binary files /dev/null and b/doc/images/road_segments.png differ diff --git a/doc/images/road_segments_junction.png b/doc/images/road_segments_junction.png new file mode 100644 index 0000000000000000000000000000000000000000..ca423383d864dc0291bc58b47ef7b09291b9d0f1 Binary files /dev/null and b/doc/images/road_segments_junction.png differ diff --git a/doc/images/road_structure.png b/doc/images/road_structure.png new file mode 100644 index 0000000000000000000000000000000000000000..d9156b80ae9cf04185a34d204493151655fdf88b Binary files /dev/null and b/doc/images/road_structure.png differ diff --git a/doc/opendrive.md b/doc/opendrive.md new file mode 100644 index 0000000000000000000000000000000000000000..955fd598775b844f05c59907ec7967a5deefde3c --- /dev/null +++ b/doc/opendrive.md @@ -0,0 +1,67 @@ +Opendrive parser +================ + +## Description + +This library is a set of C++ classes that represent the [Opendrive description](https://www.asam.net/standards/detail/opendrive/) of a road. + +The main object is the [COpendriveRoad](opendrive_road.md) which describes the whole road as a set of [COpendriveRoadSegment](opendrive_road_segment.md) objects. + +The [COpendriveRoadSegment](opendrive_road_segment.md) describes a uniform segment of the road (that is, one in which the number of lanes at each side remains the same) and includes the connectivity with other road segments. Each of the lanes on a road segment is descrived as a [COpendriveLane](opendrive_lane.md) object. The road segments also includes information on the traffic signals [COpendriveSignals](opendrive_signals.md) and obstacles [COpendriveObjects](opendrive_objects.md) belonging to it. + +The [COpendriveLane](opendrive_lane.md) object describes a single lane of a road segment and its connectivity with any previous or next lanes on different segments, or adjacent lanes on the same side in the same segment. Each lane is descrived as a set of [COpendriveRoadNode](opendrive_road_node.md) objects. + +The [COpendriveRoadNode](opendrive_road_node.md) objects are placed at the locations where the lane starts or places where the geometry changes, and include the connectivity with other adjacent road nodes. Each Link with other road nodes is unidirectional and is described by a [COpendriveLink](opendrive_link.md) object. + +The [COpendriveLink](opendrive_link.md) objects include all the geometry information associated with the connection. In this case the geometry is describes as a [G2 spline](../doc/g2_spline.md). + +The road nodes and the links between them describe the road as a directed graph. + +### Class structure + +The next diagram shows the basic class structure. + +<img src="images/class_structure.png" alt="Class structure of the opendrive library" width="1058" height="595"> + +In this diagram, arrows indicate direct use of one class by another one, which coincides with the previous description. However, the COpendriveRoad class is the only one than handles (creates and destroys) COpendriveRoadSegment, OpendriveLane or OpendriveRoadNode objects (solid arrows), and the other classes use only references to those objects (dotted arrows). Lines with a triangle indicates inheritance. + +## Common features + +Some features common to all these classes are: + +* Set of common parameters to modify the road representation. All these parameters can only be modified through the main COpendriveRoad object, and can be modified at any time. Keep in mind however, that once the road description has been loaded and the internal geometry generated, the computational cost of changing these parameters can be high, so it is recommended to set these values before loading the road description. These parameters are: + + * **resolution**: this is the minimum distance between two consecutive points in any road geometry. + * **scale**: this is a scale factor that is applied to scale up or down the road description withou actually modifying the internal geometry information. + * **min_road_length**: this is the minimum length of a road segment to be included when the opendrive file is loaded. Any road segment shorter than this value will be ignored. + +* The *<<* operator is overloaded to display human readable information about the road structure. + +* The public API is intended to provide access to all the important information of each of the road elements, but without being able to modify them. + +## Example road + +The road shown in the next figure will be used to complete the description of all classes with an example. The opendrive road descrption can be downloaded [here](). + +<img src="images/original_road.png" alt="Opendrive road description used as an example" width="814" height="594"> + +The dotted lines represent the limits of adjacent road segments. Each road segment include its name and the opendrive segment identifier (in parenthesis). The name of the two road junctions are also displayed but the name of each junction road is omitted for clarity. The name of the road junctions follows the next format: + +``` +<junction_name>_<origin_road_id>_<origin_lane_id>_<target_road_id>_<target_lane_id> +``` + +## Important +This is a work in progess and may suffer some changes and updates, although the general + +## How to use it + +* Create a COpendriveRoad object. +* Set the desired resolution, scale and minimum road length. +* Import the Opendrive description file using the *load()* function. +* Retrieve the desired information using the *get_\*()* public functions. + +This library provides several examples to demonstrate its use in some simple cases: + +* Load a road description and shown the road description on screen () +* Laad a road description and show the \ No newline at end of file diff --git a/doc/opendrive_lane.md b/doc/opendrive_lane.md new file mode 100644 index 0000000000000000000000000000000000000000..1114b21e047f8f26abed8019ff3498e4b3a7b23c --- /dev/null +++ b/doc/opendrive_lane.md @@ -0,0 +1,45 @@ +COpendriveLane +============== + +## Description + +This class describes a single lane of a road segment and its connectivity. In general, each lane is connected to a set of previous and next lanes, and for road segments with multiple lanes on each side, they are also connected to the adjacent lanes (lanes at opposite sides of a road segment are not considered adjacent). + +The next two images show (as transparent green boxes) the set of COpendriveLane's defined for the example road presented in [here](). + +<img src="images/lanes.png" alt="COpendriveLane objects created for the example road" width="647" height="547"> + +<img src="images/lanes_junction.png" alt="COpendriveLane objects created for a junction of the example road" width="622" height="457"> + +Each lane is assigned an index when it is created which depends only on the order in which they are imported from the Opendrive file (black number in the middle of the green boxes in the previous image). The lanes are also identified in the same way that Opendrive identifies them: negative integers values are used to identify rigth lanes, and positive values to identify left lanes. These values increase (for left lanes) or decrease (for right lanes) the further they are from the center lane of the segment (value in parenthesis in the previous images). + +The second image shows a detail of the COpendriveLane objects created for lower junction (juntion0). The upper junction (juntion1) is equivalent. + +## Main features + +The main features of this class are: + +* The lane is defined in the direction of the traffic. That is, right lanes have the same heading as the road segment, but left lanes have opposite heading, starting at the end of the roas segmetn and endint at the start. +* Provides access to all the road nodes of the lane defined as [COpendriveRoadNode](). The road nodes can be accessed by two different ways: + * **by index**: which is an arbitray number assigned when the road is loaded. + * **by the closest position**: in this case when the position of interest is known (i.e. the position of the car, an obstacle, etc...), it is possible to get the road node which is closest to this +* It is also possible to find the closest position (or positions) to the road independently of the road element where it belongs. +* Provides connectivity information of each lane with its neightbours. The connecting lanes can only be accessed by identifier. +* Provides a referecne to the parent road segment [COpendriveRoadSegment](). +* Funcions per retornar punts de la corva (pose i curvatura) en funció de la distà ncia. +* The road marks to the left and right sides of the road are imported from the Opendrive file. + +For further details on the implementation of these features check the doxygen API documentation. + +## Reference systems + +At this point it is important to pay some attention to the reference systems used by lanes and how the closest points and distances are computed. + +In this case, the origin of the reference system is placed at the center of the lane, at the beginning of the lane. For right lanes this means the origin is placed at the beginning of the road segment, and for left lanes it means that the origin is at the end of the road segment. The positive x axis (in red) is pointing toward the segment and the positive y axis (in green) is always pointing to the left (the positive z axis would be up). The next figure shows the reference system for left and right lanes for two road segment (a straight segment on the left and a curve segment on the right). + +<img src="images/ref_system_lanes.png" alt="Definition of the reference system used for COpendriveLane objects" width="989" height="369"> + +When finding the closest point to a lane, the desired position of interest (yellow points in the previous image) is projected (closest distance) to the geometry that describes the center of the lane (light red points in the previous image labeled R or L). If the imaginary line between the position of interest and its projection into the segment is not orthogonal to the lane geometry, it is considered that the point of interest does not belong to the lane, and therefore, the closest point does not exist. + +In case the closest point exist, its distance is always computed from the origin of the reference system of the lane, following the path defined by the lane geometry (center of the lane) as shown in the previous image. + diff --git a/doc/opendrive_link.md b/doc/opendrive_link.md new file mode 100644 index 0000000000000000000000000000000000000000..63d7f14c69a1ff2a3bce10cd1c9e40dd1bf38567 --- /dev/null +++ b/doc/opendrive_link.md @@ -0,0 +1,31 @@ +OpendriveLink +============= + +## Description + +This class describes the connection between two road nodes. This connection is defined in a single direction which coincides with the traffic direction. + +The next image shows (as solid arrows) the set of COpendriveLink's defined for the example road presented in [here](). + +<img src="images/links.png" alt="COpendriveRoadNode objects created for the example road" width="607" height="544"> + +This class encodes the geometry as [G2 Spline](). + +Links are created between a road node and: + +* the next road node on the same lane and road segment (if any). +* the previous road node on the same lane and road segment (if any). +* the next road node on the adjacent lane (left or right) and the same road segment (if any). +* the previous road node on the adjacent lane (left or right) and the same road segment (if any). +* the first or last road node on connecting lanes and road segment. + +## Main features + +The main features of this class are: + +* Provides the reference to the parent lane [COpendriveLane]() and parent road segment [COpendriveRoadSegment](). +* Provides the reference to the starting and ending COpendriveRoadNode objects. +* It is possible to generate the actual path defined by the internal geometry. +* It is possible to find the closest position to the link geometry. + +For further details on the implementation of these features check the doxygen API documentation. \ No newline at end of file diff --git a/doc/opendrive_road.md b/doc/opendrive_road.md new file mode 100644 index 0000000000000000000000000000000000000000..1e9dfe0b036f3af710dfa13cf4f8a761b7cc5ce4 --- /dev/null +++ b/doc/opendrive_road.md @@ -0,0 +1,41 @@ +COpendriveRoad +============== + +## Description + +This class describes the whole road as a set of [COpendriveRoadSegment](opendrive_road_segment.md) objects. This class handles the creation and destruction of all road elements (road segments, lanes and road node) when the opendrive file is loaded. Once loaded, it is possible to access all the elements and information of the road, but its impossible to modify it. + +## Main features + +The main features of this class are: + +* Load the Opendrive description from a file. At the moment the only supported Opendrive version is the 1.4. +* Provides access to all the road segments of the road defined as [COpendriveRoadSegment](opendrive_road_segment.md) objects. The road segments can be accessed by several different ways: + * **by index**: which is an arbitray number assigned when the road is loaded and coincides with the order in which the road segments are described in the Opendrive file. This approach may be usefull to cycle through all the segment to gather global information. + * **by id**: which is the numerical identifier assigned in the Opendrive file. + * **by name**: which is the string identifier assigned in the Opendrive file. + * **by the closest position**: in this case when the position of interest is known (i.e. the position of the car, an obstacle, etc...), it is possible to get the road segment which is closest to this position. It is possible to get the index of the road segment of interest or a reference to it. +* Provides access to all the road lanes of the road defined as [COpendriveLane](opendrive_lane.md) objects. The road lanes can be accessed by two different ways: + * **by index**: which is an arbitray number assigned when the road is loaded. This approach may be usefull to cycle through all the lanes to gather global information. + * **by the closest position**: in this case when the position of interest is known (i.e. the position of the car, an obstacle, etc...), it is possible to get the road lane which is closest to this position. It is possible to get the index of the road lane of interest or a reference to it. +* Provides access to all the road nodes of the road defined as [COpendriveRoadNode](opendrive_road_node.md) objects. The road nodes can be accessed by two different ways: + * **by index**: which is an arbitray number assigned when the road is loaded. This approach may be usefull to cycle through all the lanes to gather global information. + * **by the closest position**: in this case when the position of interest is known (i.e. the position of the car, an obstacle, etc...), it is possible to get the road node which is closest to this position. It is possible to get the index of the road node of interest or a reference to it. +* It is also possible to find the closest position (or positions) to the road independently of the road element where it belongs. In this case, a maximum distance parameter can be set to collect more than one candidate. +* It is possible to generate a new road object as a subset of the original road, which are completelly independenat from each other (that is ....). There exist three possible ways to generate a subroad: + * **by copy**: in this case the new road is just a copy of the original one. + * **by path**: in this case the new road only has the road elements that include a set of road nodes (a path). This method generates a road with a single track. + * **by distance**: in this case the new road only has the road elements that are inside a range from a given position, following the direction of the traffic (that is ....). This method only works with road with a single track. + +For further details on the implementation of these features check the doxygen API documentation. + +## Unsupported Opendrive features + +Not all features of the Opendrive standrad are supported by the current implementation. The limitations are listed next: + +* Each road segment can have only one lane section, which implies that the number of left and right lanes is the same for all the segment. +* Each lane must have the same width for each segment. + + + +* They all have a parameter to indicate the desired heading tolerance when searching for the closest element. diff --git a/doc/opendrive_road_node.md b/doc/opendrive_road_node.md new file mode 100644 index 0000000000000000000000000000000000000000..621df2b7f38a397e682eb9e3385ee5685af8dc49 --- /dev/null +++ b/doc/opendrive_road_node.md @@ -0,0 +1,52 @@ +COpendriveRoadNode +================== + +## Description + +This class describes singular points on the road, at which they are located. These points are: + +* The start position of each lane. +* The position where the geometry changes. + +The next image shows (as red dots) the set of COpendriveRoadNodes's defined for the example road presented in [here](). + +<img src="images/road_nodes.png" alt="COpendriveRoadNode objects created for the example road" width="647" height="547"> + +Each road node is assigned an index when it is created which depends only on the order in which they are imported from the Opendrive file (black number in the middle of the red dot in the previous image). + +A single road node can belong to multiple lanes on different segment. This is the case of junction roads where a single lane can be connected to multiple lanes. Therefore each road node can have multiple parents. Parents are identified by: + +* reference to the parent lane. +* reference to the parent road segment. + +Simlitar to lanes, each road node can be connected to one or more previous or next road nodes, either on the same lane or on connecting lanes. When there exist adjacent lanes, the road nodes are also connected to the previous and next road nodes on the adjacent lanes. Each connection to other road nodes is unidirectional and is made through a [COpendriveLink]() object. + +## Main features + +The main features of this class are: + +* Provides access to all the road node parents, both the lane and the road segment. The parents can only be accessed by index. +* Provides access to all the link connecting the road node with others. These links can be accessed in several ways: + * **by_index**: which is an arbitray number assigned when the links are created. + * **by connecting node**: + * **by the closest position**: +* It is also possible to find the closest position (or positions) to the road node independently of the road element where it belongs. In this case, *only_lanes*. + +For further details on the implementation of these features check the doxygen API documentation. + +## Reference systems + +At this point it is important to pay some attention to the reference systems used by road nodes and how the closest points and distances are computed. + +In this case, the origin of the reference system is placed at the position of the road node itself. The positive x axis (in red) is pointing toward the traffic direction and the positive y axis (in green) is always pointing to the left (the positive z axis would be up). + +The next figure shows the reference system for the road nodes in a junction. + +<img src="images/ref_system_road_nodes.png" alt="Definition of the reference system used for COpendriveRoadNode objects" width="642" height="356"> + +When finding the closest point to a road node, the desired position of interest (yellow points in the previous image) is projected (closest distance) to the geometry that describes the links between the node and all connected road nodes (light red points in the previous image labeled N\<node\>\<link\>). If the imaginary line between the position of interest and its projection into the link is not orthogonal to the link geometry, it is considered that the point of interest does not belong to the lane, and therefore, the closest point does not exist. + +As shown in the previous image, if the node has multiple links starting at it, there will exist a closest point for each one. + +In case the closest point exist, its distance is always computed from the position of the road node, following the path defined by the link geometry as shown in the previous image. + diff --git a/doc/opendrive_road_segment.md b/doc/opendrive_road_segment.md new file mode 100644 index 0000000000000000000000000000000000000000..4f4b9a71f304ac91de3a0eae2815ce3c156d6543 --- /dev/null +++ b/doc/opendrive_road_segment.md @@ -0,0 +1,64 @@ +COpendriveRoadSegment +===================== + +## Description + +This class describes a segment of the road in which the number of lanes at each side remains constant. In general, each road segment is connected to the adjacent road segments, but since the roads have to possible directions, the concept of next and previous is only defined when the side of the road is selected. + +The next two images show (as transparent blue boxes) the set of COpendriveRoadSegments defined for the example road presented in [here](). + +<img src="images/road_segments.png" alt="COpendriveRoadSegment objects created for the example road" width="606" height="549"> + +<img src="images/road_segments_junction.png" alt="COpendriveRoadSegment objects created for a junction of the example road" width="582" height="501"> + +Each road segment is assigned an index when it is created which depends only on the order in which they are imported from the Opendrive file (black number in the middle of the blue boxes in the previous image). A part from this index, each road can also be identified by the Opendrive identifier and name. + +The second image shows a detail of the COpendriveRoadSegment objects created for lower junction (juntion0). The upper junction (juntion1) is equivalent. In this case the junction roads have a single right lane, so 6 road segments are necessary to connect the 3 roads. + +The connectivity between all road segments is extracted from the following Opendrive information, so it is very important that this information is valid, otherwise, the process of loading the Opendrive description file may file or generate an undesired road. + +* Road link predecessor +* Road Link successor +* Junction connection +* Junction connection laneLink. + +The last two points are only necessary for junction roads. + +## Main features + +The main features of this class are: + +* The geometry of each road segment is described in two different ways. + * as a set of [Opendrive geometry classes](), directly imported from the Opendrive file. + * as a set of [G2 Splines](), generated from the opendrive geometric information. This representation if usefull when searching for the closest road elements or positions. +* Provides access to all the lanes of the road segment defined as [COpendriveLane]() objects. The segment lanes can be accessed by two different ways: + * **by id**: in this case the lanes are identified in the same way that Opendrive identifies them: negative integers values are used to identify rigth lanes, and positive values to identify left lanes. These values increase (for left lanes) or decrease (for right lanes) the further they are from the center of the segment. + * **by the closest position**: in this case when the position of interest is known (i.e. the position of the car, an obstacle, etc...), it is possible to get the road segment lane which is closest to this position. It is possible to get the identifier of the road segment lane of interest or a reference to it. +* Provides access to all the road segment nodes of the road defined as [COpendriveRoadNode]() objects. The road nodes can be accessed by two different ways: + * **by index**: which is an arbitray number assigned when the road is loaded. + * **by the closest position**: in this case when the position of interest is known (i.e. the position of the car, an obstacle, etc...), it is possible to get the road node which is closest to this position. It is possible to get the index of the road node of interest or a reference to it. +* It is also possible to find the closest position (or positions) to the road independently of the road element where it belongs. +* Provides connectivity information of each road segment with its neightbours. The connecting road segments can be accessed in two different ways: + * **by index**: which is an arbitray number assigned when the road is loaded. + * **previous** or **next**: in this case only the previous or next segment or segments are accessed, depending on the side of the road of interest. +* Provides access to all the traffic signs belonging to the road segment defined as [COpendriveSignals]() objects. In this case it is only possible to access them by index. +* Provides access to all the obstacles belonging to the road segment defined as [COpendriveObjects]() objects. In this case it is only possible to access them by index. +* Funcions per retornar punts de la corva en funció de la distà ncia +* Provides a reference to the parent road [COpendriveRoad]() object. + +For further details on the implementation of these features check the doxygen API documentation. + +## Reference systems + +At this point it is important to pay some attention to the reference system used by road segments and how the closest points and distances are computed. + +In this case, the origin of the reference system is placed at the center lane (middle of the road segment) at one of its edges. The positive x axis (in red) is pointing toward the segment and the positive y axis (in green) is always pointing to the left (the positive z axis would be up). The next figure shows the reference system of two road segment (a straight segment on the left and a curve segment on the right). + +<img src="images/ref_system_road_segments.png" alt="Definition of the reference system used for COpendriveRoadSegment objects" width="1019" height="421"> + +The left an right lanes are defined with respect to this reference frame for each road segment, so it is possible that left lanes of one segment connect to right lanes of another one, depending on the definition of their reference systems. This definitions coincides with the one used by Opendrive. + +When finding the closest point to a road segment, the desired position of interest (yellow points in the previous image) is projected (closest distance) to the geometry that describes the center lane of the segment (light red point in the previous image labeled S). If the imaginary line between the position of interest and its projection into the segment is not orthogonal to the segment geometry, it is considered that the point of interest does not belong to the road segment, and therefore, the closest point does not exist. + +In case the closest point exist, its distance is always computed from the origin of the reference system of the road segment, following the path defined by the road segment geometry (center of the road segment) as shown in the previous image. +