osi_groundtruth.proto

syntax = "proto2";

option optimize_for = SPEED;

import "osi_version.proto";
import "osi_common.proto";
import "osi_environment.proto";
import "osi_trafficsign.proto";
import "osi_trafficlight.proto";
import "osi_roadmarking.proto";
import "osi_lane.proto";
import "osi_logicallane.proto";
import "osi_referenceline.proto";
import "osi_object.proto";
import "osi_occupant.proto";

package osi3;

//
// \brief The ground truth information from the simulation environment.
//
// This ground truth information is supposed to describe the whole simulated
// environment around any simulated vehicle. For each simulated host vehicle
// (there may be one or multiple), define an area around the vehicle which
// is greater than the combined field of views (FOV) of all obstructed sensors
// in the vehicle. The ground truth data is supposed to describe the convex
// hull of all such areas w.r.t. a global simulation coordinate system.
//
// The simulation coordinate system may change during the simulation if and
// only if all coordinates w.r.t. this coordinate system are also changed.
//
// The data has to be sent at a rate defined by the receiving partner. When
// sending, values with default values might be left default in order to improve
// performance.
//
// To provide a complete interface, all fields of all contained messages must be
// properly set unless specifically stated in the field's definition that the
// field may remain unset.
//
// In enums (e.g. types) the unknown (first / default) value is not allowed to
// be used in the ground truth interface.
//
// \image html OSI_GroundTruth.svg "Ground Truth"
//
message GroundTruth
{
    // The interface version used by the sender (i.e. the simulation
    // environment).
    //
    // \rules
    // is_set
    // \endrules
    //
    optional InterfaceVersion version = 1;

    // The data timestamp of the simulation environment. The zero time point is
    // arbitrary but must be identical for all messages.
    // Recommendation: Zero time point for start point of the simulation.
    //
    // \note Zero time point does not need to coincide with the UNIX epoch.
    //
    // \note For ground truth data this timestamp coincides both with the
    // notional simulation time the data applies to and the time it was sent
    // (there is no inherent latency for ground truth data, as opposed to
    // sensor data).
    //
    // \rules
    // is_set
    // \endrules
    //
    optional Timestamp timestamp = 2;

    // The ID of the host vehicle object referencing to \c MovingObject .
    //
    // \note This ID has to be filled and is not optional!
    //
    // \rules
    // refers_to: MovingObject
    // is_set
    // \endrules
    //
    optional Identifier host_vehicle_id = 3;

    // The list of stationary objects (excluding traffic signs and traffic
    // lights).
    //
    repeated StationaryObject stationary_object = 4;

    // The list of all other moving objects including all (host) vehicles.
    //
    repeated MovingObject moving_object = 5;

    // The list of traffic signs.
    //
    repeated TrafficSign traffic_sign = 6;

    // The list of traffic lights.
    //
    repeated TrafficLight traffic_light = 7;

    // The list of road surface markings (lane markings are excluded and
    // defined as \c LaneBoundary).
    //
    repeated RoadMarking road_marking = 8;

    // The list of lane boundaries.
    //
    repeated LaneBoundary lane_boundary = 9;

    // The list of lanes forming a road network.
    //
    repeated Lane lane = 10;

    // The list of passengers in the (host) vehicle(s).
    //
    repeated Occupant occupant = 11;

    // Conditions of the environment.
    //
    optional EnvironmentalConditions environmental_conditions = 12;

    // The ISO country code in 3 digit numeric format according to:
    // ISO Code 3166/1 [1].
    // E.g. Germany = 276, USA = 840.
    //
    // \par Reference:
    // [1] ISO International Organization for Standardization. (2013). <em>ISO 3166-1 Codes for the representation of names of countries and their subdivisions - Part 1: Country codes</em>. (ISO 3166-1:2013). Geneva, Switzerland.
    //
    // \rules
    // is_iso_country_code
    // \endrules
    //
    optional uint32 country_code = 13;

    // Projection string that allows to transform all coordinates in GroundTruth
    // into a different cartographic projection after the \c proj_frame_offset
    // has been applied.
    //
    // The string follows the PROJ rules for projections [1].
    //
    // \par Reference:
    // [1] PROJ contributors. (2019). <em>PROJ coordinate transformation software library</em>. Open Source Geospatial Foundation. Retrieved January 25, 2019, from https://proj.org/usage/projections.html
    //
    optional string proj_string = 14;

    // Opaque reference of a map.
    //
    // \note Origin and orientation of the map have to coincide with the
    // inertial coordinate frame of the ground truth.
    //
    // \note It is implementation-specific how map_reference is resolved.
    //
    optional string map_reference = 15;

    // Opaque reference of an associated 3D model.
    //
    // The model covers the static parts of the environment that are not
    // provided as individual models referenced from ground truth objects
    // like moving or stationary objects.
    //
    // \note Origin and orientation of the model have to coincide with the
    // inertial coordinate frame of the ground truth.
    //
    // \note It is implementation-specific how model_references are resolved to
    // 3d models. The parts the world model contains are also implementation-specific.
    // For example, the world model can either contain street geometries or
    // derives street geometries automatically from a map reference.
    //
    optional string model_reference = 16;

    // Reference lines used by LogicalLane
    //
    repeated ReferenceLine reference_line = 17;

    // Logical lane boundaries used by LogicalLane
    //
    repeated LogicalLaneBoundary logical_lane_boundary = 18;

    // Logical lanes used e.g. by traffic agents
    //
    repeated LogicalLane logical_lane = 19;

    // Coordinate frame offset to be used for PROJ transformations.
    //
    optional ProjFrameOffset proj_frame_offset = 20;

    //
    // \brief Coordinate frame offset to transform from OSI's global coordinate
    // system to a coordinate reference system to be used for given PROJ
    // transformations.
    //
    // If an offset is defined, always apply the \c proj_frame_offset on
    // global OSI coordinates before applying any transformations defined in
    // \c proj_string.
    //
    // To apply the offset, global coordinates are first translated by the given
    // positional offset (x,y,z). Then, the yaw angle is used to rotate around
    // the new origin.
    //
    // The offset is applied on global OSI coordinates using an affine
    // transformation with rotation around z-axis:
    //
    // xWorld = xOSI * cos(yaw) - yOSI * sin(yaw) + xOffset
    //
    // yWorld = xOSI * sin(yaw) + yOSI * cos(yaw) + yOffset
    //
    // zWorld = zOSI + zOffset
    //
    //
    // If no yaw is provided (recommended), the formulas simplify to:
    //
    // xWorld = xOSI + xOffset
    //
    // yWorld = yOSI + yOffset
    //
    // zWorld = zOSI + zOffset
    //
    message ProjFrameOffset
    {
        // Positional offset for relocation of the coordinate frame.
        //
        optional Vector3d position = 1;

        // Yaw/heading angle for re-orientation of the coordinate frame around
        // the z-axis.
        //
        optional double yaw = 2;
    }

}