.. _program_listing_file_osi-documentation_osi-validation_open-simulation-interface_osi_lane.proto:

Program Listing for File osi_lane.proto
=======================================

|exhale_lsh| :ref:`Return to documentation for file <file_osi-documentation_osi-validation_open-simulation-interface_osi_lane.proto>` (``osi-documentation/osi-validation/open-simulation-interface/osi_lane.proto``)

.. |exhale_lsh| unicode:: U+021B0 .. UPWARDS ARROW WITH TIP LEFTWARDS

.. code-block:: cpp

   syntax = "proto2";
   
   option optimize_for = SPEED;
   
   import "osi_common.proto";
   
   package osi3;
   
   //
   // \brief A lane in the road network.
   //
   // A lane is part of a road and mainly characterized by its center line. It also
   // knows about any adjacent lanes, antecessor and successor lanes.
   // The following images will be referred to by later comments. The lane
   // l4 in image HighwayExit is used  as reference if not mentioned otherwise.
   //
   // <table border=0>
   // <tr>
   // <td>
   // \image html OSI_Highway_Exit.svg "" width=550px
   // <td>
   // \image html OSI_LaneIntersection.svg "" width=550px
   // <tr>
   // <td>
   // \image html OSI_Highway_Exit.jpg "HighwayExit" width=650px
   // <td>
   // \image html OSI_LaneIntersection.jpg "Intersection" width=650px
   // </table>
   //
   // \note In the examples, the symbols l1, l2, ... and lb1, lb2, ...
   // stand for the lane ids and lane boundary ids respectively, i.e. for
   // integers (uint64). The symbols cl1, cl2, ... represent the
   // osi3::Lane::Classification::centerline elements of the lanes with
   // the respective ids.
   //
   message Lane
   {
       // The ID of the lane.
       // Example: l4 (see reference picture HighwayExit).
       //
       // \note Note ID is global unique.
       //
       optional Identifier id = 1;
   
       // The classification of the lane.
       //
       optional Classification classification = 2;
   
       //
       // \brief \c Classification of a lane.
       //
       // <table border = 0>
       // <tr>
       // <td>
       // \anchor HighwayExit
       // \image html OSI_LaneClassification.jpg "HighwayExit" width=800px
       // </td>
       // <td>
       // <table border=0>
       // <tr>
       // <td>
       // <b>
       // \c Classification for lane l4 in image HighwayExit:
       // </b>
       // <tr>
       // <td>
       // \c #type = \c #TYPE_DRIVING
       // <tr>
       // <td>
       // \c #centerline = (cl4_1, cl4_2, cl4_3, cl4_4, cl4_5)
       // <tr>
       // <td>
       // \c #centerline_is_driving_direction = \c true
       // <tr>
       // <td>
       // \c #is_host_vehicle_lane = \c true
       // <tr>
       // <td>
       // \c #left_adjacent_lane_id = l3
       // <tr>
       // <td>
       // \c #right_adjacent_lane_id  = (l5,l6)
       // <tr>
       // <td>
       // \c #left_lane_boundary_id = lb5
       // <tr>
       // <td>
       // \c #right_lane_boundary_id = (lb9, lb6)
       // </table>
       // </td>
       // </tr>
       // <tr>
       // <td>
       // \anchor Intersection
       // \image html OSI_LaneIntersection.jpg "Intersection" width=800px
       // </td>
       // <td>
       // <table border=0>
       // <tr>
       // <td>
       // <b>
       // \c Classification for lane l7 in image Intersection:
       // </b>
       // </td>
       // </tr>
       // <tr>
       // <td>
       // \c #type = \c #TYPE_INTERSECTION
       // </td>
       // </tr>
       // <tr>
       // <td>
       // \c #is_host_vehicle_lane = \c false
       // </td>
       // </tr>
       // <tr>
       // <td>
       // \c #free_lane_boundary_id = lb11
       // </td>
       // </tr>
       // <tr>
       // <td>
       // <border = 0>
       // <tr>
       // <td>
       // \c #lane_pairing = (
       // <td>
       // (l2,l1), (l2,l3), (l2,l5),
       // <tr>
       // <td>
       // <td>
       // (l4,l1), (l4,l3), (l4,l5),
       // <tr>
       // <td>
       // <td>
       // (l6,l1), (l6,l3), (l6,l5) )
       // </table>
       // </td>
       // </tr>
       // </table>
       // </td>
       // </tr>
       // </table>
       //
       // \note In the examples, the symbols l1, l2, ... and lb1, lb2, ...
       // stand for the lane ids and lane boundary ids respectively, i.e. for
       // integers (uint64). The symbols cl1, cl2, ... represent the
       // osi3::Lane::Classification::centerline elements of the lanes with
       // the respective ids. The symbols cl1_1, cl1_2, ... stand for
       // \c #osi3::Vector3d elements.
       //
       message Classification
       {
           // The type of the lane.
           //
           // Example: For l4 in image \ref HighwayExit the \c #type is \c
           // #TYPE_DRIVING.
           //
           optional Type type = 1;
   
           // Indicates that the host vehicle travels on this particular lane.
           // The host vehicle may travel on more than one lane at once. This does
           // also apply for the \c CanditateLane in the \c DetectedLane .
           //
           optional bool is_host_vehicle_lane = 2;
   
           // The lane's center line (as a list of segments).
           //
           // The centerline describes the middle of the lane.
           //
           // \image html OSI_LaneCenterline.svg "Centerline" width=500px
           //
           // Example: In image \ref HighwayExit,
           // the centerline of lane l4 (black line) is given by
           // (cl4_1, cl4_2, cl4_3, cl4_4, cl4_5).
           //
           // \attention The points describing the center line might be set at
           // arbitrary distances. When the points are pairwise linearly connected,
           // the lateral distance to the real ideal line (as used by the
           // simulation environment internally) must not exceed 5cm. As shown in
           // the following image:
           //
           // \image html line_approximation_error.svg "Approximation error"
           // Approximation error green line.
           //
           // \note The center line is the line that a typical vehicle follows more
           // or less (depending on the situation, a little more to the left or
           // right of the center line). The intended direction of travel on the
           // lane is given by the direction defined by the sequence of points
           // forming the \c #centerline w.r.t. \c
           // #centerline_is_driving_direction.
           //
           // \note The \c #centerline is defined only for \c #type =
           // \c #TYPE_DRIVING and if exactly one or no \c #lane_pairing pair
           // exists.
           //
           // \note Intersections and non-driving lanes do not have a center line.
           // A vehicle must calculate this individually and depending on the
           // situation.
           //
           repeated Vector3d centerline = 3;
   
           // Definition of the intended driving direction.
           //
           // Defined and used for driving lanes.
           // \c true means driving direction is according to ascending storage
           // order of center line points. \c false means driving direction is
           // according to descending storage order of center line points.
           //
           // Example: \c #centerline_is_driving_direction = \c true for lane l4
           // and \c #centerline_is_driving_direction = \c false for lane l2 in
           // image \ref HighwayExit .
           //
           // \note The \c #centerline_is_driving_direction is defined for \c #type
           // = \c #TYPE_DRIVING .
           //
           optional bool centerline_is_driving_direction = 4;
   
           // List of IDs of all lane segments that are directly adjacent to the
           // lane on the left side (w.r.t. intended driving direction). Note that
           // lengths of lane segments are not synchronized and therefore there are
           // multiple adjacent segments if there is a split/merge point in the
           // adjacent lane.
           //
           // Example: The lane l3 is the only left adjacent lane for lane l4
           // in image \ref HighwayExit.
           //
           // \note The \c #left_adjacent_lane_id is undefined for \c #type =
           // \c #TYPE_INTERSECTION .
           //
           // \note OSI uses singular instead of plural for repeated field names.
           //
           repeated Identifier left_adjacent_lane_id = 5;
   
           // List of IDs of all lane segments that are directly adjacent to the
           // lane on the right side (w.r.t. intended driving direction). Note that
           // lengths of lane segments are not synchronized and therefore there are
           // multiple adjacent segments if there is a split/merge point in the
           // adjacent lane.
           //
           // Example: \c #right_adjacent_lane_id = (l5, l6)
           // for lane l4 in image \ref HighwayExit.
           //
           // \note The \c #right_adjacent_lane_id is undefined for \c #type =
           // \c #TYPE_INTERSECTION .
           //
           // \note OSI uses singular instead of plural for repeated field names.
           //
           repeated Identifier right_adjacent_lane_id = 6;
   
           // The antecessor/successor lane pairings of this lane. There can be
           // multiple pairings with the same antecessor and different successor
           // lanes and vice versa. The antecessor lanes end in the same point that
           // this lane starts from. The successor lanes start in the same point
           // that this lane ends in.
           //
           // Example: See image \ref Intersection.
           //
           // \note OSI uses singular instead of plural for repeated field names.
           //
           repeated LanePairing lane_pairing = 7;
   
           // The right adjacent lane boundaries \c #right_lane_boundary_id may
           // only be shared with/as the left adjacent lane boundaries \c
           // #left_lane_boundary_id of the nearest right adjacent lane \c
           // #right_adjacent_lane_id.
           //
           // Example: \c #right_lane_boundary_id =
           // (lb9, lb6) for reference lane l4 in image \ref HighwayExit.
           //
           // \note Empty for intersections.
           //
           // \note The \c #right_lane_boundary_id is undefined for \c #type =
           // \c #TYPE_INTERSECTION .
           //
           // \note OSI uses singular instead of plural for repeated field names.
           //
           repeated Identifier right_lane_boundary_id = 8;
   
           // The left adjacent lane boundaries \c #left_lane_boundary_id may only
           // be shared with/as the right adjacent lane boundaries \c
           // #right_lane_boundary_id of the nearest left adjacent lane \c
           // #left_adjacent_lane_id.
           //
           // Example: \c #left_lane_boundary_id = lb5 for lane l4 in image \ref
           // HighwayExit.
           //
           // \note Empty for intersections.
           //
           // \note The \c #left_lane_boundary_id is undefined for \c #type =
           // \c #TYPE_INTERSECTION .
           //
           // \note OSI uses singular instead of plural for repeated field names.
           //
           repeated Identifier left_lane_boundary_id = 9;
   
           // The free boundaries which have no/unknown assignment to left/right.
           //
           // Example: \c #free_lane_boundary_id = lb11 for lane l7 in image \ref
           // Intersection.
           //
           // \note \c Lane with \c #type = \c #TYPE_INTERSECTION use only free
           // lane boundaries.
           //
           // \note OSI uses singular instead of plural for repeated field names.
           //
           repeated Identifier free_lane_boundary_id = 10;
   
           // The condition of the lane, e.g. influenced by weather.
           //
           optional RoadCondition road_condition = 11;
   
           // Definition of available lane types.
           //
           enum Type
           {
               // Lane of unknown type (must not be used in ground truth).
               //
               TYPE_UNKNOWN = 0;
   
               // Any other type of lane.
               //
               TYPE_OTHER = 1;
   
               // A normal lane.
               // Example: Lanes with IDs l1, l2, l3, l4 and l6 in image \ref
               // HighwayExit.
               //
               TYPE_DRIVING = 2;
   
               // A road where driving is normally not permitted.
               // Example: Lane with ID l5 in image \ref HighwayExit.
               //
               TYPE_NONDRIVING = 3;
   
               // An intersection as a lane.
               // Example: Lane with ID l7 in image \ref Intersection.
               //
               // \image html OSI_X-Junction.svg "" width=600px
               //
               TYPE_INTERSECTION = 4;
           }
   
           //
           // \brief The condition of the road surface.
           //
           message RoadCondition
           {
               // The temperature of the roads surface in Kelvin.
               //
               // Unit: [K]
               //
               optional double surface_temperature = 1;
   
               // The height of the water film on top of the surface in mm.
               //
               // Unit: [mm]
               //
               optional double surface_water_film = 2;
   
               // The temperature where the water on top of the surface would start
               // to freeze or dew in Kelvin.
               //
               // Unit: [K]
               //
               optional double surface_freezing_point = 3;
   
               // The percentage of ice covering the road.
               //
               // Unit: [%]
               //
               optional double surface_ice = 4;
   
               // The coefficient representing the roughness or unevenness of the
               // road. International Roughness Index (IRI) [1] values range from 0
               // = smooth ground (equivalent to driving on a plate of glass) up to
               // >
               // 20 mm/m (a very rough road).
               //
               // Estimated value ranges (IRI):
               // 0.0 [mm/m] absolutely perfect evenness
               // 0.3 -  1.8 [mm/m] airport runways and superhighways
               // 1.4 -  3.4 [mm/m] new pavements
               // 2.2 -  5.7 [mm/m] older pavements
               // 3.2 -  9.8 [mm/m] maintained unpaved roads
               // 4.0 - 11.0 [mm/m] damaged pavements
               // 8.0 - >
               // 20 [mm/m] rough unpaved roads
               //
               // Speed of normal use (IRI):
               // 30 [km/h] - 20   [mm/m]
               // 50 [km/h] - 14.5 [mm/m]
               // 60 [km/h] - 10.0 [mm/m]
               // 80 [km/h] -  8.5 [mm/m]
               // 100 [km/h] -  3.4 [mm/m]
               //
               // Road conditions (IRI);
               // 15 [mm/m] erosion gulleys and deep depressions
               // 11 [mm/m] frequent shallow depressions, some deep
               // 9 [mm/m] frequent minor depressions
               // 5 [mm/m] surface imperfections
               //
               // Unit: [mm/m]
               //
               // \par References:
               // - [1] SAYERS, M.W.; KARAMIHAS, S.M. Little Book of Profiling,
               // University of Michigan Transportation Research Institute, 1998.
               //
               optional double surface_roughness = 5;
   
               // The surface texture or fine roughness
               //
               // Whereas the IRI-based roughness or unevenness measure only takes
               // into account road wavelengths around 0.5m - 100m, the surface
               // texture or fine roughness [2] measures only wavelengths below
               // 0.5m. It is given as the standard height deviation of fine
               // roughness
               //
               // Unit: [m]
               //
               // \par References:
               // - [1] SAYERS, M.W.; KARAMIHAS, S.M. Little Book of Profiling,
               // University of Michigan Transportation Research Institute, 1998.
               // - [2] SCHNEIDER, R.: Modellierung der Wellenausbreitung fuer
               // ein bildgebendes Kfz-Radar, Dissertation, Universitaet Karlsruhe,
               // Mai 1998.
               //
               optional double surface_texture = 6;
           }
   
           // \brief The lane ID pairings of antecessor and successor lanes.
           //
           // <table border = 0>
           // <tr>
           // <td>
           // \image html OSI_LaneIntersection.svg "" width=600px
           // </td>
           // <td>
           // <table border=0>
           // <tr>
           // <td>
           // <b>
           // \c LanePairing for lane l7:
           // </b>
           // </td>
           // </tr>
           // <tr>
           // <td>
           // <table border = 0>
           // <tr>
           // <td>
           // (l2,l1), (l2,l3), (l2,l5),
           // <tr>
           // <td>
           // (l4,l1), (l4,l3), (l4,l5),
           // <tr>
           // <td>
           // (l6,l1), (l6,l3), (l6,l5)
           // </table>
           // </td>
           // </tr>
           // </table>
           // </td>
           // </tr>
           // </table>
           //
           // \note In the example, the symbols l1, l2, ... stand for the
           // respective lane ids, i.e. for integers (uint64). The symbols cl1,
           // cl2, ... represent the osi3::Lane::Classification::centerline
           // elements of the lanes with the respective ids.
           //
           message LanePairing
           {
               // The antecessor lane ID.
               //
               optional Identifier antecessor_lane_id = 1;
   
               // The successor lane ID.
               //
               optional Identifier successor_lane_id = 2;
           }
       }
   }
   
   //
   // \brief A lane boundary defining the border of a lane.
   //
   // The left and right lane boundary define the width of the lane. Additionally,
   // free markings can be defined, e.g. at construction sites. Free markings
   // across multiple lanes may be defined multiple times for all affected lanes.
   //
   // \image html OSI_LaneBoundary.svg "LaneBoundary" width=800px
   //
   // \note In the example, the symbols l1, l2, ... and lb1, lb2, ...
   // stand for the lane ids and lane boundary ids respectively, i.e. for
   // integers (uint64). The symbols bp2_{i+1}, bp2_{i}, bp2_{i-1} stand
   // for \c #osi3::LaneBoundary::BoundaryPoint elements.
   //
   message LaneBoundary
   {
       // The ID of the lane boundary.
       //
       optional Identifier id = 1;
   
       // The list of individual points defining the location of the lane boundary
       // (as a list of segments).
       //
       // Since a \c BoundaryPoint is part of a sequence, only the position
       // attribute has to be set for each instance. All other values will be
       // reused from the previous \c BoundaryPoint in the sequence or set to
       // default values if there is none or it was never set.
       //
       // \image html OSI_LaneBoundary.svg "" width=800px
       //
       // Example: The boundary_line of the \c LaneBoundary with id lb2 is given by
       // (bp2_1, ..., bp2_{i-1}, bp2_{i}, bp2_{i+1}, ...).
       //
       // \note For dashed lines, one \c BoundaryPoint has to be at the start and
       // another at the end of each dashed line segment. The first
       // \c BoundaryPoint defines the beginning of the first dashed lane marking.
       // The last \c BoundaryPoint defines the end of the last dashed lane
       // marking. For example, the area between the second and third
       // \c BoundaryPoint has no lane marking, and so on.
       // \note For Botts' dots lines, one \c BoundaryPoint position has to define
       // each Botts' dot.
       //
       // \attention For \c BoundaryPoint the same rule for the approximation
       // error applies as for \c Lane::Classification::centerline.
       //
       repeated BoundaryPoint boundary_line = 2;
   
       // The classification of the lane boundary.
       //
       optional Classification classification = 3;
   
       //
       // \brief A single point of a lane boundary.
       //
       // \image html OSI_LaneBoundary.svg "" width=800px
       //
       // The lane boundary point bp2_{i} is one of the points of lane boundary
       // lb2.
       //
       // \note In the example, the symbols l1, l2, ... and lb1, lb2, ...
       // stand for the lane ids and lane boundary ids respectively, i.e. for
       // integers (uint64). The symbols bp2_{i+1}, bp2_{i}, bp2_{i-1} stand
       // for \c #osi3::LaneBoundary::BoundaryPoint elements.
       //
       message BoundaryPoint
       {
           // The position of the \c BoundaryPoint.
           //
           optional Vector3d position = 1;
   
           // The overall width of the lane boundary at the position of the
           // \c BoundaryPoint .
           // Used for lines forming lane markings.
           //
           // \image html OSI_LaneBoundaryWidth.svg "" width=600px
           //
           // \note Field need not be set if it is defined previous.
           // See \c LaneBoundary.
           //
           optional double width = 2;
   
           // The overall height of the lane boundary at the position of the
           // \c BoundaryPoint .
           // Used for guard rails, curbstone, or similar.
           //
           // \image html OSI_LaneBoundaryHeight.svg "" width=600px
           //
           // \note Field need not be set if it is previously defined.
           // See \c LaneBoundary .
           //
           optional double height = 3;
       }
   
       //
       // \brief \c Classification of a lane boundary.
       //
       // <table border = 0>
       // <tr>
       // <td>
       // <table border=0>
       // <tr>
       // <td>
       // <b>
       // Image Intersection
       // </b>
       // <tr>
       // <td>
       // <tr>
       // <td>
       // \c Classification for lane boundaries lb2 and lb9:
       // </td>
       // </tr>
       // <tr>
       // <td>
       // <table border = 0>
       // <tr>
       // <td>
       // \c #type = #TYPE_DASHED_LINE
       // <tr>
       // <td>
       // \c #color = #COLOR_WHITE
       // <tr>
       // </table>
       // </td>
       // </tr>
       // <tr>
       // <td>
       // \c Classification for lane boundaries lb1, lb3, lb4, lb7, lb8, lb10,
       // lb11, lb12 and lb14:
       // </td>
       // </tr>
       // <tr>
       // <td>
       // <table border = 0>
       // <tr>
       // <td>
       // \c #type = #TYPE_SOLID_LINE
       // <tr>
       // <td>
       // \c #color = #COLOR_WHITE
       // <tr>
       // </table>
       // </td>
       // </tr>
       // <tr>
       // <td>
       // \c Classification for lane boundaries lb5, lb6 and lb13:
       // </td>
       // </tr>
       // <tr>
       // <td>
       // <table border = 0>
       // <tr>
       // <td>
       // \c #type = #TYPE_CURB
       // </table>
       // </td>
       // </tr>
       // </table>
       // </td>
       // <td>
       // <table border=0>
       // <tr>
       // <td>
       // \image html OSI_LaneIntersection.svg "" width=500px
       // </td>
       // <tr>
       // <td>
       // \image html OSI_LaneBoundaryClassification.jpg "" width=600px
       // </td>
       // </table>
       // </td>
       // </tr>
       // </table>
       //
       // \note In the example, the symbols l1, l2, ... and lb1, lb2, ...
       // stand for the lane ids and lane boundary ids respectively, i.e. for
       // integers (uint64). The symbols cl1, cl2, ... represent the
       // osi3::Lane::Classification::centerline elements of the lanes with
       // the respective ids.
       //
       message Classification
       {
           // The type of the lane boundary.
           //
           optional Type type = 1;
   
           // The color of the lane boundary in case of lane markings.
           //
           optional Color color = 2;
   
           // The ids of \c StationaryObject which limit the corresponding lane.
           // This field must be set if the \c #type is set to
           // \c #TYPE_STRUCTURE
           //
           repeated Identifier limiting_structure_id = 3;
   
           // The lane boundary type.
           // There is no special representation for double lines, e.g. solid /
           // solid or dashed / solid. In such cases, each lane will define its own
           // side of the lane boundary.
           //
           enum Type
           {
               // The type of lane boundary is unknown. Value must not be used in
               // ground truth.
               //
               TYPE_UNKNOWN = 0;
   
               // Unspecified but known type of lane boundary.
               // Consider proposing an additional type if using TYPE_OTHER.
               //
               TYPE_OTHER = 1;
   
               // An invisible lane boundary (e.g. unmarked part of a dashed line).
               //
               TYPE_NO_LINE = 2;
   
               // A solid line at the lane boundary.
               //
               TYPE_SOLID_LINE = 3;
   
               // A dashed line at the lane boundary.
               //
               TYPE_DASHED_LINE = 4;
   
               // A lane boundary consisting of Botts' dots (multiple Botts dots).
               //
               TYPE_BOTTS_DOTS = 5;
   
               // A lane boundary formed by the road's edge.
               // The road edge is the end of the (paved) road surface.
               //
               TYPE_ROAD_EDGE = 6;
   
               // A lane boundary formed by a snow edge that may be on the road
               // surface.
               //
               TYPE_SNOW_EDGE = 7;
   
               // A lane boundary covered by grass.
               //
               TYPE_GRASS_EDGE = 8;
   
               // A lane boundary covered by gravel.
               //
               TYPE_GRAVEL_EDGE = 9;
   
               // A lane boundary covered by soil.
               //
               TYPE_SOIL_EDGE = 10;
   
               // A guard rail.
               //
               TYPE_GUARD_RAIL = 11;
   
               // A curb.
               //
               TYPE_CURB = 12;
   
               // A structure (e.g. building or tunnel wall).
               //
               TYPE_STRUCTURE = 13;
           }
   
           // The color of the lane boundary in case of a lane markings.
           // Lane markings that alternate in color must be represented by
           // individual \c LaneBoundary segments.
           //
           enum Color
           {
               // Color of marking is unknown. Value must not be used in ground
               // truth.
               //
               COLOR_UNKNOWN = 0;
   
               // Other (unspecified but known) color.
               //
               COLOR_OTHER = 1;
   
               // Marking without color. Used to represent logical boundaries
               // without actual physical markings at the respective position.
               // Value may be used in ground truth only.
               //
               COLOR_NONE = 2;
   
               // Marking with white color.
               //
               COLOR_WHITE = 3;
   
               // Marking with yellow / orange-yellow color.
               //
               COLOR_YELLOW = 4;
   
               // Marking with red color
               //
               COLOR_RED = 5;
   
               // Marking with blue color.
               //
               COLOR_BLUE = 6;
   
               // Marking with green color;
               //
               COLOR_GREEN = 7;
   
               // Marking with violet color.
               //
               COLOR_VIOLET = 8;
           }
       }
   }