syntax = "proto2";

option optimize_for = SPEED;

import "osi_common.proto";
import "osi_trafficsign.proto";

package osi3;

//
// \brief A road surface marking.
//
// \image html OSI_RoadMarking.svg
//
// The figure shows two STOP road markings. STOP \c
// RoadMarking::Classification::type == \c
// RoadMarking::Classification::TYPE_TEXTUAL_TRAFFIC_SIGN is marked, STOP \c
// RoadMarking::Classification::type == \c
// RoadMarking::Classification::TYPE_SYMBOLIC_TRAFFIC_SIGN is not marked.
//
// All coordinates and orientations are relative to the global ground truth
// coordinate system.
//
// Lane markings are excluded and defined as \c LaneBoundary messages
// as part of \c Lane.

//
message RoadMarking
{
    // The ID of the road marking.
    //
    // \rules
    // is_set
    // \endrules
    //
    optional Identifier id = 1;

    // The base parameters of the road marking.
    //
    // The orientation of the bounding box \c #base
    // \c BaseStationary::orientation is defined as follows:
    // The z-axis of the \c BaseStationary::orientation is the vector from the
    // 'bottom' to the 'top' of the road marking's (i.e. painted traffic sign)
    // 2D image area.
    // (Normally it is in the ground truth xy-plain.)
    // The x-axis of the \c BaseStationary::orientation is the view normal of
    // the road marking's 2D image area.
    // Normally this x-axis points to the sky.
    //
    // \note If a valid unidirectional road marking is assigned to the host
    // vehicle's current lane and the driving direction of the latter roughly
    // matches the z-axis of the \c #base \c BaseStationary::orientation then
    // the road marking is of relevance to (i.e. in effect for) the host
    // vehicle.
    //
    optional BaseStationary base = 2;

    // The classification data for the road marking.
    //
    optional Classification classification = 3;

    // Optional external reference to the road-marking source.
    //
    // The external reference points to the source of the surface marking, if it
    // is derived from one or more objects or external references. An example
    // here is the reference to the signal defined in a OpenDRIVE map.
    //
    // For example, to reference a signal defined in an OpenDRIVE map
    // the items should be set as follows:
    // * reference = URI to map, can remain empty if identical with definition
    //               in \c GroundTruth::map_reference
    // * type = "net.asam.opendrive"
    // * identifier[0] = id of t_road_signals_signal
    //
    // \note With OpenDRIVE, surface markings can also be defined as objects.
    //       In this case, the associated object is usually referenced within
    //       OpenDRIVE using the reference t_road_signals_signal_reference.
    //       An additional reference to the object is therefore not necessary.
    //
    // \note For non-ASAM Standards, it is implementation-specific how
    //       source_reference is resolved.
    //
    // \note The value has to be repeated, because one lane segment may be
    //       derived from more than one origin segment. Multiple sources
    //       may be added as reference as well, for example, a map and sensors.
    //
    repeated ExternalReference source_reference = 4;

    // The visual color of the material of the road marking.
    //
    // \note This does not represent the semantic classification but the visual
    // appearance. For semantic classification of the road marking use the color
    // field in \c Classification.
    //
    optional ColorDescription color_description = 5;

    //
    // \brief \c Classification data for a road surface marking.
    //
    message Classification
    {
        // The type of the road marking.
        //
        optional Type type = 1;

        // Traffic sign as road marking (color image, monochrome image or
        // character string).
        //
        // \note Field is set if ( \c #type == \c #TYPE_PAINTED_TRAFFIC_SIGN or
        // \c #TYPE_SYMBOLIC_TRAFFIC_SIGN or \c #TYPE_TEXTUAL_TRAFFIC_SIGN ).
        //
        // \note Field need not be set (or set to \c #TYPE_OTHER)
        // if road marking type (\c #type) does not require it.
        //
        // \attention Deprecated: A revision is planned for version 4.0.0 to
        // replace the type enum with a more semantically defined enumeration,
        // with the exact sign specification being relegated to the newly
        // introduced 4-tupel traffic sign catalog specification as used in
        // <a href="https://releases.asam.net/OpenDRIVE/1.6.0/ASAM_OpenDRIVE_BS_V1-6-0.html#_signals">OpenDRIVE</a>.
        //
        // \rules
        // check_if this.type is_greater_than_or_equal_to 2 else do_check is_set
        // check_if this.type is_less_than_or_equal_to 4 else do_check is_set
        // \endrules
        //
        optional TrafficSign.MainSign.Classification.Type traffic_main_sign_type = 2;

        // The semantic monochrome color of the road marking.
        //
        // \note The color types represent the semantic color classification of
        // road markings only. They do not represent an actual visual appearance.

        // \note Field need not be set (or set to \c #COLOR_OTHER)
        // if road marking type does not require it (e.g. for \c #type ==
        // \c #TYPE_PAINTED_TRAFFIC_SIGN).
        //
        // \rules
        // check_if this.type is_equal_to 2 else do_check is_set
        // check_if this.monochrome_color is_equal_to 1 else do_check is_set
        // \endrules
        //
        optional Color monochrome_color = 3;

        // Additional value associated with the road marking, e.g. value of the
        // speed limit.
        //
        // \note Field need not be set if road marking type does not require it.
        //
        // \note OSI 3 uses \c #value_text and not \c TrafficSignValue for
        // simple chars.
        //
        optional TrafficSignValue value = 4;

        // Additional text value as road marking, e.g. BUS, TAXI etc.
        //
        // \note Field need not be set if road marking type does not require it.
        //
        optional string value_text = 5;

        // The ID(s) of the lane(s) that the road marking is assigned to.
        // May be multiple if the road marking goes across multiple lanes.
        //
        // \note OSI uses singular instead of plural for repeated field names.
        //
        // \rules
        // refers_to: Lane
        // \endrules
        //
        repeated Identifier assigned_lane_id = 6;

        // Boolean flag to indicate that the road marking is taken out of service.
        // This can be achieved by visibly crossing the road marking with stripes,
        // or completely covering a road marking making it not visible.
        //
        // \image html OSI_RoadMaking_is_out_of_service.jpg width=800px
        //
        optional bool is_out_of_service = 7;

        // Country specification of the traffic sign catalog specification
        // that identifies the actual traffic sign. This is part of the
        // 4-tupel traffic sign catalog specification as used in
        // <a href="https://releases.asam.net/OpenDRIVE/1.6.0/ASAM_OpenDRIVE_BS_V1-6-0.html#_signals">OpenDRIVE</a>.
        //
        // Country is specified using the ISO 3166-1, alpha-2 code
        // https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2, or the
        // special OpenDRIVE country for generic signs.<br>
        //
        // \rules
        // check_if this.type is_greater_than_or_equal_to 2 else do_check is_set
        // check_if this.type is_less_than_or_equal_to 4 else do_check is_set
        // \endrules
        //
        optional string country = 8;

        // Revision specification of the traffic sign catalog specification
        // that identifies the actual traffic sign. This is part of the
        // 4-tupel traffic sign catalog specification as used in
        // <a href="https://releases.asam.net/OpenDRIVE/1.6.0/ASAM_OpenDRIVE_BS_V1-6-0.html#_signals">OpenDRIVE</a>.
        //
        // The year the traffic rules came into force. <br>
        // e.g. "2017"
        //
        // \note Field is set if ( \c #type == \c #TYPE_PAINTED_TRAFFIC_SIGN or
        // \c #TYPE_SYMBOLIC_TRAFFIC_SIGN or \c #TYPE_TEXTUAL_TRAFFIC_SIGN ).
        //
        // \note Field need not be set (or set to \c #TYPE_OTHER)
        // if road marking type (\c #type) does not require it.
        //
        // \rules
        // check_if this.type is_greater_than_or_equal_to 2 else do_check is_set
        // check_if this.type is_less_than_or_equal_to 4 else do_check is_set
        // \endrules
        //
        optional string country_revision = 9;

        // Code specification of the traffic sign catalog specification
        // that identifies the actual traffic sign. This is part of the
        // 4-tupel traffic sign catalog specification as used in
        // <a href="https://releases.asam.net/OpenDRIVE/1.6.0/ASAM_OpenDRIVE_BS_V1-6-0.html#_signals">OpenDRIVE</a>.
        //
        // Code identifier according to country and country revision,
        // corresponds to the type field of OpenDRIVE. <br>
        // code is only unique in combination with #country and #country_revision.  <br>
        // e.g. http://www.vzkat.de/2017/VzKat.htm
        //
        // \note Field is set if ( \c #type == \c #TYPE_PAINTED_TRAFFIC_SIGN or
        // \c #TYPE_SYMBOLIC_TRAFFIC_SIGN or \c #TYPE_TEXTUAL_TRAFFIC_SIGN ).
        //
        // \note Field need not be set (or set to \c #TYPE_OTHER)
        // if road marking type (\c #type) does not require it.
        //
        // \rules
        // check_if this.type is_greater_than_or_equal_to 2 else do_check is_set
        // check_if this.type is_less_than_or_equal_to 4 else do_check is_set
        // \endrules
        //
        optional string code = 10;

        // Sub-code specification of the traffic sign catalog specification
        // that identifies the actual traffic sign. This is part of the
        // 4-tupel traffic sign catalog specification as used in
        // <a href="https://releases.asam.net/OpenDRIVE/1.6.0/ASAM_OpenDRIVE_BS_V1-6-0.html#_signals">OpenDRIVE</a>.
        //
        // Sub-code identifier according to country, country revision and code,
        // corresponds to the subtype field of OpenDRIVE. <br>
        // sub_code is only unique in combination with #country, #country_revision,
        // and #code.  <br>
        // e.g. http://www.vzkat.de/2017/VzKat.htm
        //
        // \note Field is set if ( \c #type == \c #TYPE_PAINTED_TRAFFIC_SIGN or
        // \c #TYPE_SYMBOLIC_TRAFFIC_SIGN or \c #TYPE_TEXTUAL_TRAFFIC_SIGN ).
        //
        // \note Field need not be set (or set to \c #TYPE_OTHER)
        // if road marking type (\c #type) does not require it.
        //
        // \rules
        // check_if this.type is_greater_than_or_equal_to 2 else do_check is_set
        // check_if this.type is_less_than_or_equal_to 4 else do_check is_set
        // \endrules
        //
        optional string sub_code = 11;

        // Assignment of this object to logical lanes.
        //
        // \note OSI uses singular instead of plural for repeated field names.
        //
        repeated LogicalLaneAssignment logical_lane_assignment = 12;

        // Definition of road marking types.
        //
        enum Type
        {
            // Type of road marking is unknown (must not be used in ground
            // truth).
            //
            TYPE_UNKNOWN = 0;

            // Other (unspecified but known) type of road marking.
            //
            TYPE_OTHER = 1;

            // Paint on the road surface indicating a color image of a traffic
            // sign.
            //
            TYPE_PAINTED_TRAFFIC_SIGN = 2;

            // Paint on the road surface indicating a monochrome logical symbol
            // of a traffic sign (e.g. digits 50 as start of speed limit 50 or
            // stop line for stop sign).
            //
            TYPE_SYMBOLIC_TRAFFIC_SIGN = 3;

            // Paint on the road surface as a character string (e.g. BUS as bus
            // only lane).
            //
            TYPE_TEXTUAL_TRAFFIC_SIGN = 4;

            // Paint on the road surface indicating a generic symbol.
            //
            TYPE_GENERIC_SYMBOL = 5;

            // Paint on the road surface indicating a generic line.
            //
            TYPE_GENERIC_LINE = 6;

            // Paint on the road surface indicating a generic character string.
            //
            TYPE_GENERIC_TEXT = 7;
        }

        // Definition of semantic road marking colors
        //
        // \note The color types represent the semantic classification of
        // road markings only. They do not represent an actual visual appearance.
        //
        enum Color
        {
            // Color of road marking is unknown (must not be used in ground
            // truth).
            //
            COLOR_UNKNOWN = 0;

            // Marking with another (unspecified but known) color.
            //
            COLOR_OTHER = 1;

            // Marking with white color.
            //
            COLOR_WHITE = 2;

            // Marking with yellow / orange-yellow color.
            //
            COLOR_YELLOW = 3;

            // Marking with blue color.
            //
            COLOR_BLUE = 5;

            // Marking with red color.
            //
            COLOR_RED = 6;

            // Marking with green color.
            //
            COLOR_GREEN = 7;

            // Marking with violet color.
            //
            COLOR_VIOLET = 8;

            // Marking with orange color.
            //
            COLOR_ORANGE = 9;
        }
    }
}
