syntax = "proto2";

option optimize_for = SPEED;

import "osi_version.proto";
import "osi_common.proto";
import "osi_detectedtrafficsign.proto";
import "osi_detectedtrafficlight.proto";
import "osi_detectedroadmarking.proto";
import "osi_detectedlane.proto";
import "osi_detectedobject.proto";
import "osi_detectedoccupant.proto";
import "osi_sensorview.proto";
import "osi_featuredata.proto";
import "osi_logicaldetectiondata.proto";

package osi3;

//
// \brief The header attributes of each detected entity.
//
message DetectedEntityHeader
{
    // Time stamp at which the measurement was taken (not the time at which it
    // was processed or at which it is transmitted) in the global synchronized
    // time.
    //
    // \note See \c SensorData::timestamp and \c
    // SensorData::last_measurement_time for detailed discussions on the
    // semantics of time-related fields.
    //
    optional Timestamp measurement_time = 1;

    // Continuous up counter to identify the cycle.
    //
    optional uint64 cycle_counter = 2;

    // Data Qualifier expresses to what extent the content of this event can be
    // relied on.
    //
    optional DataQualifier data_qualifier = 3;

    //
    // Data qualifier communicates the overall availability of the
    // interface.
    //
    enum DataQualifier
    {
        // Unknown (must not be used in ground truth).
        //
        DATA_QUALIFIER_UNKNOWN = 0;

        // Other (unspecified but known).
        //
        DATA_QUALIFIER_OTHER = 1;

        // Data is available.
        //
        DATA_QUALIFIER_AVAILABLE = 2;

        // Reduced data is available.
        //
        DATA_QUALIFIER_AVAILABLE_REDUCED = 3;

        // Data is not available.
        //
        DATA_QUALIFIER_NOT_AVAILABLE = 4;

        // Sensor is blind.
        //
        DATA_QUALIFIER_BLINDNESS = 5;

        // Sensor temporary available.
        //
        DATA_QUALIFIER_TEMPORARY_AVAILABLE = 6;
    }
}

//
// \brief The sensor information derived from \c GroundTruth and processed by
// sensor-models.
//
// The sensor information is supposed to imitate the output of real sensors.
// All information regarding the environment is given with respect to
// the virtual sensor coordinate system specified in
// \c SensorData::mounting_position, except for feature data, which is given
// with respect to the physical sensor coordinate system specified in the
// corresponding physical sensor's coordinate system.
//
// When simulating multiple distinct sensors, each sensor can produce an
// individual copy of the \c SensorData interface. This allows an independent
// treatment of the sensors.
//
// Sensor fusion models can consolidate multiple \c SensorData interfaces into
// one consolidated \c SensorData interface.  This can happen either in
// separate logical models, consuming and producing \c SensorData interfaces,
// or it can happen as part of a combined sensor/logical model, that consumes
// \c SensorView interfaces and directly produces one consolidated \c SensorData
// output.
//
message SensorData
{
    // The interface version used by the sender.
    //
    // \rules
    // is_set
    // \endrules
    //
    optional InterfaceVersion version = 1;

    // The timestamp of the sensor data. Zero time is arbitrary but must be
    // identical for all messages. Zero time does not need to coincide with
    // the unix epoch. Recommended is the starting time point of the
    // simulation.
    //
    // \note This is the point in time that the sensor data message becomes
    // available to the rest of the system (i.e. the driving functions), so
    // it corresponds with the sending time and thus takes the latency of
    // internal processing of the sensor into account. Latencies of bus
    // communications, etc., that occur after the sensor output have to be
    // applied on top of this, if needed.
    //
    // The time that the actual measurement was performed (which will usually
    // correspond with the timestamp of the \c GroundTruth the sensor model
    // processed to arrive at these results) can be found in the additional
    // field \c SensorData::last_measurement_time.
    //
    // For an ideal zero latency sensor the two timestamps would be the same
    // and would correspond with the timestamp from the current \c GroundTruth
    // message.
    //
    // For a sensor model that does not know its own internal latencies (e.g.
    // a dumb sensor with no internal time concept), the two timestamps might
    // also be identical, but delayed from the \c GroundTruth timestamp.
    //
    // \rules
    // is_set
    // \endrules
    //
    optional Timestamp timestamp = 2;

    // The sensors estimated location of the host vehicle
    //
    // \note This value is only set by sensors that are able to
    // provide an own estimation of the host vehicle location.
    // \note Note that dimension and base_polygon need not be set.
    // \note The parent frame of \c host_vehicle_location is the sensor frame.
    //
    optional BaseMoving host_vehicle_location = 3;

    // The sensors estimated location error of the host vehicle
    //
    // \note This value is only set by sensors that are able to
    // provide an own estimation of the host vehicle location.
    // \note Note that dimension and base_polygon need not be set.
    // \note The parent frame of \c host_vehicle_location_rmse is the sensor
    // frame.
    //
    optional BaseMoving host_vehicle_location_rmse = 4;

    // The ID of the sensor at host vehicle's mounting_position.
    //
    // This is the ID of the virtual sensor, to be used in its detected
    // object output; it is distinct from the IDs of its physical detectors,
    // which are used in the detected features.
    //
    // \rules
    // is_set
    // \endrules
    //
    optional Identifier sensor_id = 5;

    // The virtual mounting position of the sensor (origin and orientation
    // of the sensor coordinate system) given in vehicle coordinates [1].
    // The virtual position pertains to the sensor as a whole, regardless
    // of the actual position of individual physical detectors, and governs
    // the sensor-relative coordinates in detected objects of the sensor
    // as a whole.  Individual features detected by individual physical
    // detectors are governed by the actual physical mounting positions
    // of the detectors, as indicated in the technology-specific sub-views
    // and sub-view configurations.
    //
    // \arg \b x-direction of sensor coordinate system: sensor viewing direction
    // \arg \b z-direction of sensor coordinate system: sensor (up)
    // \arg \b y-direction of sensor coordinate system: perpendicular to x and z
    // right hand system
    //
    // \par Reference:
    // [1] DIN Deutsches Institut fuer Normung e. V. (2013). <em>DIN ISO 8855 Strassenfahrzeuge - Fahrzeugdynamik und Fahrverhalten - Begriffe</em>. (DIN ISO 8855:2013-11). Berlin, Germany.
    //
    // \note This field is usually static during the simulation.
    // \note The origin of vehicle's coordinate system in world frame is
    // ( \c MovingObject::base . \c BaseMoving::position +
    // Inverse_Rotation_yaw_pitch_roll( \c MovingObject::base . \c
    // BaseMoving::orientation) * \c
    // MovingObject::VehicleAttributes::bbcenter_to_rear) . The orientation of
    // the vehicle's coordinate system is equal to the orientation of the
    // vehicle's bounding box \c MovingObject::base . \c
    // BaseMoving::orientation.
    //
    // \rules
    // is_set
    // \endrules
    //
    optional MountingPosition mounting_position = 6;

    // The root mean squared error of the mounting position.
    //
    optional MountingPosition mounting_position_rmse = 7;

    // Sensor view w.r.t. the sensor coordinate system
    //
    // This provides a copy of the \c SensorView data received by the sensor
    // for reference purposes.  For complex sensors or logic models this
    // can be multiple copies.
    //
    repeated SensorView sensor_view = 8;

    // The timestamp of the last real-world measurement (e.g. GT input) that
    // this set of sensor data takes into account. This in effect is the last
    // time instance of reality the measurements correspond to. See field
    // \c SensorData::timestamp for a detailed discussion. This value is also
    // the upper bound to the \c DetectedEntityHeader::measurement_time and the
    // feature data \c SensorDetectionHeader::measurement_time fields.
    //
    optional Timestamp last_measurement_time = 9;

    // General information about the \c DetectedStationaryObject .
    //
    optional DetectedEntityHeader stationary_object_header = 10;

    // The list of stationary objects (e.g. landmarks) detected by the sensor.
    //
    repeated DetectedStationaryObject stationary_object = 11;

    // General information about the \c DetectedMovingObject .
    //
    optional DetectedEntityHeader moving_object_header = 12;

    // The list of moving objects detected by the sensor as perceived by
    // the sensor.
    //
    repeated DetectedMovingObject moving_object = 13;

    // General information about the \c DetectedTrafficSign .
    //
    optional DetectedEntityHeader traffic_sign_header = 14;

    // The list of traffic signs detected by the sensor.
    //
    repeated DetectedTrafficSign traffic_sign = 15;

    // General information about the \c DetectedTrafficLight .
    //
    optional DetectedEntityHeader traffic_light_header = 16;

    // The list of traffic lights detected by the sensor.
    //
    repeated DetectedTrafficLight traffic_light = 17;

    // General information about the \c DetectedRoadMarking .
    //
    optional DetectedEntityHeader road_marking_header = 18;

    // The list of road markings detected by the sensor.
    // This excludes lane boundary markings.
    //
    repeated DetectedRoadMarking road_marking = 19;

    // General information about the \c DetectedLaneBoundary .
    //
    optional DetectedEntityHeader lane_boundary_header = 20;

    // The list of lane boundary markings detected by the sensor.
    //
    repeated DetectedLaneBoundary lane_boundary = 21;

    // General information about the \c DetectedLane .
    //
    optional DetectedEntityHeader lane_header = 22;

    // The list of lanes detected by the sensor
    //
    repeated DetectedLane lane = 23;

    // General information about the \c DetectedOccupant .
    //
    optional DetectedEntityHeader occupant_header = 24;

    // The list of occupants of the host vehicle
    //
    repeated DetectedOccupant occupant = 25;

    // Low level feature data interface.
    //
    // Low Level feature data is optionally provided by sensor models that
    // model sensors giving access to this low level data, i.e. data prior to
    // object hypothesis and tracking.
    //
    optional FeatureData feature_data = 26;

    // Logical detection data interface.
    //
    // Logical detection data are provided by a transformation
    // (and optional sensor fusion)
    // performed by a sensor model or a logical model
    // that fuses multiple sensors and/or sensor types
    // into a single reference frame
    // of the so called logical/virtual sensor.
    // Therefore, all information is given with respect to
    // the reference frame of the logical/virtual sensor
    // \c SensorView::mounting_position (e.g. center of rear axle of the ego car)
    // in cartesian coordinates.
    //
    optional LogicalDetectionData logical_detection_data = 27;

    //
    // \brief Virtual detection area of a sensor
    //
    // The virtual detection area describes the nominal area the sensor is capable of covering
    // in its current operating mode, without taking occlusion or other statistical effects into account.
    // This information can be used for visualization or other development purposes as a rough guide
    // to nominal sensor performance.
    //
    // It is described by a set of polygons in cartesian coordinates as a pragmatic approximation for
    // the rough shapes expected.
    //
    message VirtualDetectionArea
    {
        // List of polygons. Each polygon represents a surface of the virtual detection area
        // and is given with respect to the virtual sensor coordinate system.
        //
        repeated Polygon3d polygon = 1;
    }

    // Virtual detection area of the sensor
    //
    optional VirtualDetectionArea virtual_detection_area = 28;

    // The system time of the modeled source of the sensor data, given
    // in UTC (Unix Epoch timestamp).
    //
    // The system time can be used to transmit the internal time of the
    // simulated component that supplies the sensor data, which might
    // not coincide with the simulation time as transmitted in the
    // timestamp field. Example use cases include recorded data traces
    // or the simulation of time synchronization mechanisms and errors.
    //
    optional Timestamp system_time = 29;
}
