syntax = "proto2";

option optimize_for = SPEED;

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

package osi3;

//
// \brief A traffic sign in the environment as detected by the sensor.
//
// \image html OSI_DetectedSign.svg
//
// The parent frame of a detected traffic sign is the virtual sensor coordinate
// system.
//
// \note The virtual sensor coordinate system is relative to the vehicle coordinate
// system which has its origin in the center of the rear axle of the ego
// vehicle. This means if virtual sensor mounting position and orientation are
// set to (0,0,0) the virtual sensor coordinate system coincides with the
// vehicle coordinate system.
//
message DetectedTrafficSign
{
    // Common information of one detected item.
    //
    optional DetectedItemHeader header = 1;

    // The main sign as detected by the sensor.
    //
    optional DetectedMainSign main_sign = 2;

    // A list of additional supplementary sign(s) as detected by the sensor.
    //
    repeated DetectedSupplementarySign supplementary_sign = 3;

    //
    // \brief Candidates for a detected main sign as estimated by the sensor.
    //
    // \image html OSI_DetectedMainSign.svg
    //
    message DetectedMainSign
    {
        // A list of candidates for this traffic sign as estimated by the
        // sensor.
        //
        // \note OSI uses singular instead of plural for repeated field names.
        //
        repeated CandidateMainSign candidate = 1;

        // The base parameters of the traffic sign.
        //
        // The orientation of the bounding box \c #base
        // ( \c BaseStationary::orientation ) is defined as follows:
        //
        // The z-axis of the given \c BaseStationary::orientation is the vector
        // from the bottom to the top of the traffic sign's 2D image plate.
        // (Normally it is equal to the ground truth z-axis.)
        //
        // The x-axis of the given \c BaseStationary::orientation is view
        // normal of the traffic sign's image.
        //
        // This x-axis points from the traffic sign's image in the direction
        // from where a 'viewer' could see the traffic sign image.
        //
        optional BaseStationary base = 2;

        // The root mean squared error of the base parameters of the detected
        // traffic sign. \c TrafficSign::MainSign::base has to be identical for
        // all \c #candidate traffic signs.
        //
        optional BaseStationary base_rmse = 3;

        // The estimated geometry of the traffic sign.
        //
        optional Geometry geometry = 4;

        //
        // \brief A candidate for a detected main sign as estimated by the
        // sensor.
        //
        message CandidateMainSign
        {
            // The estimated probability that this candidate is the true value.
            //
            // \note The sum of all \c #probability must be one. This
            // probability is given under the condition of \c
            // DetectedItemHeader::existence_probability.
            //
            // \rules
            // is_less_than_or_equal_to: 1
            // is_greater_than_or_equal_to: 0
            // \endrules
            //
            optional double probability = 1;

            // The classification of one main sign that defines this candidate.
            //
            // \note IDs, which are referenced in this message, usually
            // reference to \c DetectedXXX::tracking_id IDs.
            //
            optional TrafficSign.MainSign.Classification classification = 2;
        }

        // Definition of traffic sign geometries.
        //
        enum Geometry
        {
            // Geometry of the traffic sign is unknown (must not be used in
            // ground truth).
            //
            GEOMETRY_UNKNOWN = 0;

            // Geometry of the traffic sign is unspecified (but known).
            //
            GEOMETRY_OTHER = 1;

            // Traffic sign has a circular geometry. (0 corners)
            //
            GEOMETRY_CIRCLE = 2;

            // Traffic sign has a triangular geometry pointing to the top. (3
            // corners)
            //
            GEOMETRY_TRIANGLE_TOP = 3;

            // Traffic sign has a triangular geometry pointing down. (3 corners)
            //
            GEOMETRY_TRIANGLE_DOWN = 4;

            // Traffic sign has a square geometry. (4 corners)
            //
            GEOMETRY_SQUARE = 5;

            // Traffic sign that has a pole geometry. (height is bigger than
            // width e.g. pole indicating highways exit in xx m). (4 corners)
            //
            GEOMETRY_POLE = 6;

            // Traffic sign has a rectangle geometry. (width is bigger than
            // height e.g. one-way) (4 corners)
            //
            GEOMETRY_RECTANGLE = 7;

            // Traffic sign that has an oversize rectangle geometry. (4 corners)
            // E.g. direction plates on highway or city signs.
            //
            GEOMETRY_PLATE = 8;

            // Traffic sign has a diamond geometry. (4 corners)
            //
            GEOMETRY_DIAMOND = 9;

            // Traffic sign has a geometry of an arrow pointing to the left. (5
            // corners)
            //
            GEOMETRY_ARROW_LEFT = 10;

            // Traffic sign has a geometry of an arrow pointing to the right. (5
            // corners)
            //
            GEOMETRY_ARROW_RIGHT = 11;

            // Traffic sign has an octagon geometry. (8 corners)
            //
            GEOMETRY_OCTAGON = 12;
        }
    }

    //
    // \brief Candidates for all detected supplementary signs of one traffic
    // sign as estimated by the sensor.
    //
    // \image html OSI_DetectedSupplementarySign.svg
    //
    message DetectedSupplementarySign
    {
        // The definition of one of more supplementary signs that together
        // define this candidate.
        //
        // \note OSI uses singular instead of plural for repeated field names.
        //
        repeated CandidateSupplementarySign candidate = 1;

        // The base parameters of the supplementary traffic sign.
        //
        // The orientation of the bounding box \c SupplementarySign::base
        // ( \c BaseStationary::orientation ) is defined as follows:
        // The z-axis of the given \c BaseStationary::orientation is the vector
        // from the bottom to the top of the supplementary traffic sign's 2D
        // image plate. (Normally it is equal to the ground truth z-axis.) The
        // x-axis of the given \c BaseStationary::orientation is view normal of
        // the supplementary traffic sign's image. This x-axis points from the
        // supplementary traffic sign's image in the direction from where a
        // 'viewer' could see the supplementary traffic sign image.
        //
        optional BaseStationary base = 2;

        // The root mean squared error of the base parameters of the detected
        // supplementary traffic sign. \c #candidate
        // \c TrafficSign::SupplementarySign::base has to be identical for all
        // \c #candidate supplementary traffic signs.
        //
        optional BaseStationary base_rmse = 3;

        //
        // \brief A candidate for a detected supplementary sign as estimated by
        // the sensor.
        //
        message CandidateSupplementarySign
        {
            // The estimated probability that this candidate is the true value.
            //
            // \note The sum of all \c #probability must be one. This
            // probability is given under the condition of \c
            // DetectedItemHeader::existence_probability.
            //
            // \rules
            // is_less_than_or_equal_to: 1
            // is_greater_than_or_equal_to: 0
            // \endrules
            //
            optional double probability = 1;

            // The classification of one of more supplementary signs that
            // together define this candidate.
            //
            // \note IDs, which are referenced in this message, usually
            // reference to \c DetectedXXX::tracking_id IDs.
            //
            optional TrafficSign.SupplementarySign.Classification
                classification = 2;
        }
    }
}
