diff --git a/doc/opendrive_road_node.md b/doc/opendrive_road_node.md index 621df2b7f38a397e682eb9e3385ee5685af8dc49..cbfc8101cd1b639a36feb43b3ddf8d408cce783f 100644 --- a/doc/opendrive_road_node.md +++ b/doc/opendrive_road_node.md @@ -6,20 +6,22 @@ COpendriveRoadNode 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 position where the geometry of the lane 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). +Each road node is assigned a unique 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). This index may only change when a new sub-road is generated, in which case the road nodes in the new road are re-indexed. -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: +A single road node can belong to multiple lanes on different segments. This is the case of junctions where multiple road segments are connected together. In the previous image, road node 22 belongs to two different road segments, one connecting to road node 2 and the other with road node 20. The same happens for road nodes 23 to 27 in the previous image. -* reference to the parent lane. -* reference to the parent road segment. +Therefore each road node can have multiple parents, which are identified by: -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. +* A reference to the parent lane [COpendriveLane](opendrive_lane.md) object. +* A reference to the parent road segment [COpendriveRoadSEgment](opendrive_road_segment.md) object. + +Similar 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 @@ -27,26 +29,29 @@ 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*. + * **by_index**: which is an arbitrary number assigned when the links are created. In this case both links starting and ending at the desired road node can be accessed. + * **by connecting node**: provides access to the link that connects the desired road node with another one. In this case, only links starting at the road node can be accessed. + * **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 link which is closest to this position. +* It is possible to find the closest position to the road node independently of the road element where it belongs. +* It is possible to get a set of poses that are closer to a given pose than a given distance threshold, independently of the road element where they belongs. +* In case of unexpected errors, this class throws an instance of CException. All other errors are reported to the user. For further details on the implementation of these features check the doxygen API documentation. -## Reference systems +## Closest links, poses and node distances -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. +At this point it is important to pay some attention to how the closest links, poses and node 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. +The next image shows an example of how the closest poses are computed, as well as the reference systems, in a road junction. -<img src="images/ref_system_road_nodes.png" alt="Definition of the reference system used for COpendriveRoadNode objects" width="642" height="356"> +<img src="images/ref_system_road_nodes.png" alt="Closest poses and node distances computation for road nodes" width="655" height="385"> -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. +The closest link to a given pose is the one starting at the desired node and with the smallest euclidean distance to the given pose. In the example shown in the previous image, the closest link is the one connecting nodes 24 and 1. -As shown in the previous image, if the node has multiple links starting at it, there will exist a closest point for each one. +The closest poses for a road node are computed by first finding the closest link starting at the desired node, and then computing their closest poses. See the [COpendriveLink](opendrive_link.md) class documentation for more details on how the closest poses are computed. In the example shown in the previous image, the poses closer than a given threshold (dotted red circle in the previous image) are L24_1, L24_2 and L23_1, but the closest one is L24_1 (L24_2 and L23_1 are a little further away). -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. +The **node distance** is always computed form the starting node and is equivalent to the link distance of the closest link. See the [COpendriveLink](opendrive_link.md) class documentation for more details on how the link distances are computed. Do not confuse this distance with the closest euclidean distance between the point of interest and the closest point belonging to the link. +In road segments with more than one lane on the same side, the *only_lanes* parameter will limit the search for closest links, poses and distances to the link belonging to a lane, ignoring the ones connecting adjacent lanes.