/*
 * Copyright (C) 2019 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

syntax = "proto3";

package android.car.cluster.navigation;

option java_package = "android.car.cluster.navigation";
option java_outer_classname = "NavigationState";

// A reference to an image. This consists of a 'content://' style URI plus
// attributes describing the image.
//
// Sizing: The aspect ratio of the image is given in aspect_ratio.
//         When requesting the image using this URI a 'w' and 'h' parameter
//         must be added to the URI parameter list to request an image size.
//         There is no guarantee that the specific size requested will actually
//         be returned, however.
// Margins: The referenced image does not have internal margins.
// Format: Content URI must reference a file with MIME type
//         'image/png', 'image/jpeg' or 'image/bmp'.
// Color: Images can be either "tintable" or not. A "tintable" image is such
// that
//        all its content is defined in its alpha channel, while its color
//        (all other channels) can be altered without losing information
//        (e.g. icons). A non "tintable" images contains information in all its
//        channels (e.g. photos).
// Caching: Given the same image reference and the same requested size,
//          it is assumed that the exact same image will always be returned.
//          This means that it should be safe to cache an image once requested
//          the first time, using this image reference plus requested size as
//          key, for as long as needed.
message ImageReference {
  // A URI defining the location that the image can be retrieved from.
  //
  // When requesting the image from this URI, a desired image size must be
  // specified by editing the parameter list to add the following two
  // parameters:
  //   w: width desired maximum width (must be greater than 0)
  //   h: height desired maximum height (must be greater than 0)
  //
  // For example, if the `content_uri` is
  // `content://some.package.name/some/path`, then the request must be:
  // `content://some.package.name/some/path?w=<width>&h=<height>` (with <width>
  // and <height> replaced with the requested values).
  //
  // Note that the resulting image is not guaranteed to match the requested
  // size.
  string content_uri = 1;

  // The aspect ratio of the image, being width divided by height.
  double aspect_ratio = 2;

  // Indicates whether this image is "tintable" or not.
  // An image is "tintable" when all its content is defined in its
  // alpha-channel, designed to be colorized
  // (e.g. using android.graphics.PorterDuff.Mode#SRC_ATOP image composition).
  bool is_tintable = 3;
}

// Distance along the planned route between relevant points in the navigation
message Distance {
  // Possible units used to display this distance.
  enum Unit {
    // Display unit is unknown, no distance information should be displayed.
    UNKNOWN = 0;
    METERS = 1;
    KILOMETERS = 2;
    MILES = 3;
    FEET = 4;
    YARDS = 5;
  }

  // The distance in meters.
  int32 meters = 1;

  // The distance measured in the unit indicated at `display_units`, already
  // internationalized and ready for display, or empty if no distance value was
  // provided. If empty, the distance shouldn’t be displayed to the driver.
  //
  // This distance is for display only (it might be a rounded representation of
  // the actual distance) and must match the distance displayed anywhere else
  // in the vehicle.
  //
  // For example, a distance of 1200 meters in ES_es locale could be
  // represented with `display_value` of "1,2" and `display_units` of
  // KILOMETERS.
  string display_value = 2;

  // The distance unit that should be used to display the distance value
  // (adjusted to the current user's locale and/or location). This matches the
  // unit used in `display_value`.
  Unit display_units = 3;
}

// Information about a maneuver that the driver will be required to perform.
message Maneuver {
  // Next ID: 57
  enum Type {
    // Maneuver type is unknown, no maneuver information should be displayed.
    UNKNOWN = 0;

    // Starting point of the navigation (e.g. "Start driving on Main St.")
    DEPART = 1;

    // No turn, but the street name changes (e.g. "Continue on Main St.")
    NAME_CHANGE = 2;

    // No turn, from 0 (included) to 10 (excluded) degrees. Used when we just
    // wish to say "Keep left". Note that this is used in contrast to STRAIGHT
    // for disambiguating cases where there is more than one option to go into
    // the same general direction.
    KEEP_LEFT = 3;
    // No turn, from 0 (included) to 10 (excluded) degrees. Used when we just
    // wish to say "Keep right". Note that this is used in contrast to STRAIGHT
    // for disambiguating cases where there is more than one option to go into
    // the same general direction.
    KEEP_RIGHT = 4;

    // Slight left turn at an intersection, from 10 (included) to 45 (excluded)
    // degrees.
    TURN_SLIGHT_LEFT = 5;
    // Slight right turn at an intersection, from 10 (included) to 45 (excluded)
    // degrees.
    TURN_SLIGHT_RIGHT = 6;

    // Regular left turn at an intersection, from 45 (included) to 135
    // (excluded) degrees.
    TURN_NORMAL_LEFT = 7;
    // Regular right turn at an intersection, from 45 (included) to 135
    // (excluded) degrees.
    TURN_NORMAL_RIGHT = 8;

    // Sharp left turn at an intersection, from 135 (included) to 175 (excluded)
    // degrees.
    TURN_SHARP_LEFT = 9;
    // Sharp right turn at an intersection, from 135 (included) to 175
    // (excluded) degrees.
    TURN_SHARP_RIGHT = 10;

    // A left turn onto the opposite side of the same street, from 175
    // (included) to 180 (included) degrees.
    U_TURN_LEFT = 11;
    // A right turn onto the opposite side of the same street, from 175
    // (included) to 180 (included) degrees.
    U_TURN_RIGHT = 12;

    // A slight left turn to enter a turnpike or freeway. See TURN_SLIGHT_LEFT
    // for the definition of slight.
    ON_RAMP_SLIGHT_LEFT = 13;
    // A slight right turn to enter a turnpike or freeway. See TURN_SLIGHT_RIGHT
    // for the definition of slight.
    ON_RAMP_SLIGHT_RIGHT = 14;
    // A normal left turn to enter a turnpike or freeway. See TURN_NORMAL_LEFT
    // for the definition of normal.
    ON_RAMP_NORMAL_LEFT = 15;
    // A normal right turn to enter a turnpike or freeway. See TURN_NORMAL_RIGHT
    // for the definition of normal.
    ON_RAMP_NORMAL_RIGHT = 16;
    // A sharp left turn to enter a turnpike or freeway. See TURN_SHARP_LEFT
    // for the definition of sharp.
    ON_RAMP_SHARP_LEFT = 17;
    // A sharp right turn to enter a turnpike or freeway. See TURN_SHARP_RIGHT
    // for the definition of sharp.
    ON_RAMP_SHARP_RIGHT = 18;
    // A left u-turn to enter a turnpike or freeway. See U_TURN_LEFT for the
    // definition of u-turn.
    ON_RAMP_U_TURN_LEFT = 19;
    // A right u-turn to enter a turnpike or freeway. See U_TURN_RIGHT for the
    // definition of u-turn.
    ON_RAMP_U_TURN_RIGHT = 20;

    // A slight left turn to exit a turnpike or freeway. See TURN_SLIGHT_LEFT
    // for the definition of slight.
    OFF_RAMP_SLIGHT_LEFT = 21;
    // A slight right turn to exit a turnpike or freeway. See TURN_SLIGHT_RIGHT
    // for the definition of slight.
    OFF_RAMP_SLIGHT_RIGHT = 22;
    // A left turn to exit a turnpike or freeway. See TURN_NORMAL_LEFT
    // for the definition of normal.
    OFF_RAMP_NORMAL_LEFT = 23;
    // A right turn to exit a turnpike or freeway. See TURN_NORMAL_RIGHT
    // for the definition of normal.
    OFF_RAMP_NORMAL_RIGHT = 24;

    // Road diverges (e.g. "Keep left at the fork").
    FORK_LEFT = 25;
    // Road diverges (e.g. "Keep right at the fork").
    FORK_RIGHT = 26;

    // Current road joins another (e.g. "Merge right onto Main St.").
    MERGE_LEFT = 27;
    // Current road joins another (e.g. "Merge left onto Main St.").
    MERGE_RIGHT = 28;
    // Current road joins another (e.g. "Merge onto Main St.").
    MERGE_SIDE_UNSPECIFIED = 54;

    // Roundabout entrance on which the current road ends (e.g. "Enter the
    // roundabout").
    ROUNDABOUT_ENTER = 29;

    // Used when leaving a roundabout when the step starts in it (e.g. "Exit
    // the roundabout").
    ROUNDABOUT_EXIT = 30;

    // Entrance and exit (e.g. "At the roundabout, take Nth exit") on a
    // clockwise roundabout (as seen from above, typical for left-hand drive
    // countries).
    ROUNDABOUT_ENTER_AND_EXIT_CW = 55;
    // Entrance and sharp right turn exit (e.g. "At the roundabout, take Nth
    // exit") on a clockwise roundabout (as seen from above, typical for
    // left-hand drive countries). See TURN_SHARP_RIGHT for the definition of
    // sharp.
    ROUNDABOUT_ENTER_AND_EXIT_CW_SHARP_RIGHT = 31;
    // Entrance and regular right turn exit (e.g. "At the roundabout, take Nth
    // exit") on a clockwise roundabout (as seen from above, typical for
    // left-hand drive countries). See TURN_NORMAL_RIGHT for the definition of
    // normal.
    ROUNDABOUT_ENTER_AND_EXIT_CW_NORMAL_RIGHT = 32;
    // Entrance and slight right turn exit (e.g. "At the roundabout, take Nth
    // exit") on a clockwise roundabout (as seen from above, typical for
    // left-hand drive countries). See TURN_SLIGHT_RIGHT for the definition of
    // slight.
    ROUNDABOUT_ENTER_AND_EXIT_CW_SLIGHT_RIGHT = 33;
    // Entrance and straight exit (e.g. "At the roundabout, take Nth exit") on a
    // clockwise roundabout (as seen from above, typical for left-hand drive
    // countries).
    ROUNDABOUT_ENTER_AND_EXIT_CW_STRAIGHT = 34;
    // Entrance and sharp left turn exit (e.g. "At the roundabout, take Nth
    // exit") on a clockwise roundabout (as seen from above, typical for
    // left-hand drive countries). See TURN_SHARP_LEFT for the definition of
    // sharp.
    ROUNDABOUT_ENTER_AND_EXIT_CW_SHARP_LEFT = 35;
    // Entrance and regular left turn exit (e.g. "At the roundabout, take Nth
    // exit") on a clockwise roundabout (as seen from above, typical for
    // left-hand drive countries). See TURN_NORMAL_LEFT for the definition of
    // normal.
    ROUNDABOUT_ENTER_AND_EXIT_CW_NORMAL_LEFT = 36;
    // Entrance and slight left turn exit (e.g. "At the roundabout, take Nth
    // exit") on a clockwise roundabout (as seen from above, typical for
    // left-hand drive countries). See TURN_SLIGHT_LEFT for the definition of
    // slight.
    ROUNDABOUT_ENTER_AND_EXIT_CW_SLIGHT_LEFT = 37;
    // Entrance and u-turn exit (e.g. "At the roundabout, take Nth exit") on a
    // clockwise roundabout (as seen from above, typical for left-hand drive
    // countries).
    ROUNDABOUT_ENTER_AND_EXIT_CW_U_TURN = 38;

    // Entrance and exit (e.g. "At the roundabout, take Nth exit") on a
    // counter-clockwise roundabout (as seen from above, typical for right-hand
    // drive countries).
    ROUNDABOUT_ENTER_AND_EXIT_CCW = 56;
    // Entrance and sharp right turn exit (e.g. "At the roundabout, take Nth
    // exit") on a counter-clockwise roundabout (as seen from above, typical for
    // right-hand drive countries). See TURN_SHARP_RIGHT for the definition of
    // sharp.
    ROUNDABOUT_ENTER_AND_EXIT_CCW_SHARP_RIGHT = 39;
    // Entrance and regular right turn exit (e.g. "At the roundabout, take Nth
    // exit") on a counter-clockwise roundabout (as seen from above, typical for
    // right-hand drive countries). See TURN_NORMAL_RIGHT for the definition of
    // normal.
    ROUNDABOUT_ENTER_AND_EXIT_CCW_NORMAL_RIGHT = 40;
    // Entrance and slight right turn exit (e.g. "At the roundabout, take Nth
    // exit") on a counter-clockwise roundabout (as seen from above, typical for
    // right-hand drive countries). See TURN_SLIGHT_RIGHT for the definition of
    // slight.
    ROUNDABOUT_ENTER_AND_EXIT_CCW_SLIGHT_RIGHT = 41;
    // Entrance and straight exit (e.g. "At the roundabout, take Nth exit") on a
    // counter-clockwise roundabout (as seen from above, typical for right-hand
    // drive countries).
    ROUNDABOUT_ENTER_AND_EXIT_CCW_STRAIGHT = 42;
    // Entrance and sharp left turn exit (e.g. "At the roundabout, take Nth
    // exit") on a counter-clockwise roundabout (as seen from above, typical for
    // right-hand drive countries). See TURN_SHARP_LEFT for the definition of
    // sharp.
    ROUNDABOUT_ENTER_AND_EXIT_CCW_SHARP_LEFT = 43;
    // Entrance and regular left turn exit (e.g. "At the roundabout, take Nth
    // exit") on a counter-clockwise roundabout (as seen from above, typical for
    // right-hand drive countries). See TURN_NORMAL_LEFT for the definition of
    // normal.
    ROUNDABOUT_ENTER_AND_EXIT_CCW_NORMAL_LEFT = 44;
    // Entrance and slight left turn exit (e.g. "At the roundabout, take Nth
    // exit") on a counter-clockwise roundabout (as seen from above, typical for
    // right-hand drive countries). See TURN_SLIGHT_LEFT for the definition of
    // slight.
    ROUNDABOUT_ENTER_AND_EXIT_CCW_SLIGHT_LEFT = 45;
    // Entrance and u-turn exit (e.g. "At the roundabout, take Nth exit") on a
    // counter-clockwise roundabout (as seen from above, typical for right-hand
    // drive countries).
    ROUNDABOUT_ENTER_AND_EXIT_CCW_U_TURN = 46;

    // Driver should steer straight.
    STRAIGHT = 47;

    // Drive towards a boat ferry for vehicles (e.g. "Take the ferry").
    FERRY_BOAT = 48;

    // Drive towards a train ferry for vehicles (e.g. "Take the train").
    FERRY_TRAIN = 49;

    // Arrival to a destination where the direction is unknown.
    DESTINATION = 50;

    // Arrival to a destination located straight ahead.
    DESTINATION_STRAIGHT = 51;
    // Arrival to a destination located on the left side of the road.
    DESTINATION_LEFT = 52;
    // Arrival to a destination located on the right side of the road.
    DESTINATION_RIGHT = 53;
  }

  // Extended set of maneuver types.
  // Added in Android T.
  // Next ID: 11
  enum TypeV2 {
    // Maneuver type is unknown, no maneuver information should be displayed.
    UNKNOWN_V2 = 0;

    // Roundabout entrance on which the current road ends (e.g. "Enter the
    // roundabout") for a clockwise roundabout (as seen from above, typical for
    // left-hand drive countries).
    ROUNDABOUT_ENTER_CW = 1;

    // Used when leaving a roundabout when the step starts in it (e.g. "Exit the
    // roundabout") for a clockwise roundabout (as seen from above, typical for
    // left-hand drive countries).
    ROUNDABOUT_EXIT_CW = 2;

    // Roundabout entrance on which the current road ends (e.g. "Enter the
    // roundabout") for a counter-clockwise roundabout (as seen from above,
    // typical for right-hand drive countries).
    ROUNDABOUT_ENTER_CCW = 3;

    // Used when leaving a roundabout when the step starts in it (e.g. "Exit the
    // roundabout") for a counter-clockwise roundabout (as seen from above,
    // typical for right-hand drive countries).
    ROUNDABOUT_EXIT_CCW = 4;

    // Entrance and exit (e.g. "At the roundabout, take Nth exit") on a
    // clockwise roundabout (as seen from above, typical for left-hand drive
    // countries).
    ROUNDABOUT_ENTER_AND_EXIT_CW_WITH_ANGLE = 5;

    // Entrance and exit (e.g. "At the roundabout, take Nth exit") on a
    // counter-clockwise roundabout (as seen from above, typical for right-hand
    // drive countries).
    ROUNDABOUT_ENTER_AND_EXIT_CCW_WITH_ANGLE = 6;

    // Drive towards a boat ferry for vehicles (e.g. "Take the ferry").Used when
    // the ferry entrance is to the left.
    FERRY_BOAT_LEFT = 7;

    // Drive towards a boat ferry for vehicles (e.g. "Take the ferry"). Used
    // when the ferry entrance is to the right.
    FERRY_BOAT_RIGHT = 8;

    // Drive towards a train ferry for vehicles (e.g. "Take the train"). Used
    // when the ferry entrance is to the left.
    FERRY_TRAIN_LEFT = 9;

    // Drive towards a train ferry for vehicles (e.g. "Take the train"). Used
    // when the ferry entrance is to the right.
    FERRY_TRAIN_RIGHT = 10;
  }

  // The type of the maneuver.
  Type type = 1;

  // The most accurate representation of the type of a maneuver. If this field
  // is populated, then this field should be used for the type of the maneuver.
  // For example, if Maneuver#type_v2=ROUNDABOUT_ENTER_CW and
  // Maneuver#type=ROUNDABOUT_ENTER, the value to be used for the type should be
  // ROUNDABOUT_ENTER_CW. If this field is UNKNOWN_V2 then the value to be used
  // for the type can be found in Maneuver#type.
  // Added in Android T.
  TypeV2 type_v2 = 4;

  // The roundabout exit number, starting from 1 to designate the first exit
  // after joining the roundabout, and increasing in circulation order.
  // Only relevant if type is ROUNDABOUT_EXIT or any variation of
  // ROUNDABOUT_ENTER_AND_EXIT.
  //
  // For example, if the driver is joining a counter-clockwise roundabout
  // with 4 exits, then the exit to the right would be exit #1, the one
  // straight ahead would be exit #2, the one to the left would be exit #3
  // and the one used by the driver to join the roundabout would be exit #4.
  int32 roundabout_exit_number = 2;

  // A reference to an image representing this maneuver,
  // or not present if image representation is not available.
  ImageReference icon = 3;

  // Angle describing the turn needed to perform to exit a roundabout, used for
  // ROUNDABOUT_ENTER_AND_EXIT_*_WITH_ANGLE maneuver types. It can take a value
  // from 0 (excluded) to 360 (included) where the entry point is at 0
  // incrementing in a clockwise/counter-clockwise fashion depending on the
  // rotational driving direction in the roundabout. For example, in a
  // counter-clockwise roundabout, if you exit by making a right turn the angle
  // is 90 degrees, if you exit driving straight the angle is 180 degrees, if
  // you exit by making a left turn the angle is 270 degrees and if you make a U
  // turn the angle is 360 degrees. In a clockwise roundabout the values are
  // mirrored i.e. if you exit by making a left turn the angle is 90 degrees, if
  // you exit driving straight the angle is 180 degrees, if you exit by making a
  // right turn the angle is 270 degrees and if you make a U turn the angle is
  // 360 degrees.
  //           180                                     180
  //            |                                       |
  //            |                                       |
  //           / \                                     / \
  // 270 <----|   |----> 90                   90 <----|   |----> 270
  //           \ /                                     \ /
  //            |                                       |
  //            |                                       |
  //          0, 360                                  0, 360
  // Counter-clockwise roundabout              Clockwise roundabout
  //
  // The values can be more granular depending on the layout of the roundabout.
  // Added in Android T.
  int32 roundabout_exit_angle_degrees = 5;
}

// Configuration of a single lane of a road at a particular point in the
// navigation. It describes all possible directions the driver could go
// from this lane, and indicates which directions the driver could take
// to stay on the navigation route.
message Lane {
  // One of the possible directions a driver can go when using a particular
  // lane at a particular step in the navigation. This defines the icon(s)
  // that must be combined to display a lane configuration to the user.
  message LaneDirection {
    enum Shape {
      // The shape is unknown, in which case no lane information should be
      // shown.
      UNKNOWN = 0;

      // No turn.
      STRAIGHT = 1;

      // Slight left turn, from 10 (included) to 45 (excluded) degrees.
      SLIGHT_LEFT = 2;

      // Slight right turn, from 10 (included) to 45 (excluded) degrees.
      SLIGHT_RIGHT = 3;

      // Regular left turn, from 45 (included) to 135 (excluded) degrees.
      NORMAL_LEFT = 4;

      // Regular right turn, from 45 (included) to 135 (excluded) degrees.
      NORMAL_RIGHT = 5;

      // Sharp left turn, from 135 (included) to 175 (excluded) degrees.
      SHARP_LEFT = 6;

      // Sharp right turn, from 135 (included) to 175 (excluded) degrees.
      SHARP_RIGHT = 7;

      // A left turn onto the opposite side of the same street, from 175
      // (included) to 180 (included) degrees
      U_TURN_LEFT = 8;

      // A right turn onto the opposite side of the same street, from 175
      // (included) to 180 (included) degrees
      U_TURN_RIGHT = 9;
    }

    // The shape of this lane direction.
    Shape shape = 1;

    // True if this is a valid direction the driver can take in order to stay
    // in the navigation route, or false if it will take the drive off the
    // navigation route.
    bool is_highlighted = 2;
  }

  // The possible directions a driver can take from this lane.
  repeated LaneDirection lane_directions = 1;
}

// An instruction to a user to perform an action during their drive composed of
// a sequence of graphic elements (e.g. text, images) to be displayed
// one after another.
//
// Each sequence will have a plain text representation in `alternate_text`
// and in the case of the absence of a rich representation,
// the sequence of elements in `elements` may be left empty.
// The textual representation may also be used as a fallback for when the
// elements fail to render.
message Cue {
  // One item in the sequence that makes up a Cue,
  // a sequence of graphic elements that can be displayed one after another.
  //
  // A CueElement can contain text, a graphic element, or both.
  // The text of a CueElement with an image reference should be representative
  // of the image.
  //
  // The image should be rendered if possible instead of the
  // text. Otherwise, `CueElement.text` should be used as a fallback.
  //
  // If rendering fails and the text is empty, then no elements in the sequence
  // should be rendered and `Cue.alternate_text` must be used instead.
  //
  // New graphic elements might be added in the future. If such elements are
  // unknown to the OEM rendering service, they will be delivered as text.
  message CueElement {
    // The textual representation of this element.
    //
    // If image is provided, then this is used as a fallback in the case of
    // render failures, otherwise this is the string to be used when rendering
    // this element.
    string text = 1;

    // An image representing this element. This representation should be used
    // over the textual representation whenever possible.
    //
    // In case of failure to render, `text` should be shown instead. If
    // rendering fails and text is empty, then no elements should be shown and
    // instead the `alternate_text` should be shown.
    ImageReference image = 2;
  }

  // The sequence of graphic elements.
  //
  // If no rich cue representation is available,
  // the list may be empty and `alternate_text` should be used as a fallback.
  // Spacing between the elements is provided, and rendering services should
  // not attempt to add their own spacing between the CueElement objects.
  repeated CueElement elements = 1;

  // The plain-text string representing the content of this Cue.
  string alternate_text = 2;
}

// An action that the driver should take in order to remain on the current
// navigation route.
//
// For example: turning onto a street, taking a highway exit and merging onto
// a different highway, continuing straight through a roundabout, etc.
message Step {
  // The distance from the current position to the point where
  // this navigation step should be executed.
  Distance distance = 1;

  // The maneuver to be performed on this step,
  // or not present if this step doesn't involve a maneuver.
  Maneuver maneuver = 2;

  // The configuration of road lanes at the point where the driver should
  // execute this step, or an empty list if lane configuration metadata
  // is not available. Lane configurations are listed from left to right.
  repeated Lane lanes = 3;

  // An image representing the lane configuration at this point in the
  // navigation, or not present if the lanes configuration image was not
  // provided. The image, if provided, is expected to contain:
  //   - A representation of all lanes, one next to the other in a single row.
  //   - For each lane, a set of arrows, representing each possible driving
  //     direction (e.g. straight, left turn, etc.) within such lane.
  //   - Each of such driving directions that would keep the driver within
  //     the navigation route should be highlighted.
  // Lane configuration images are expected to be displayed in a canvas
  // with fixed height and variable width.
  ImageReference lanes_image = 4;

  // Auxiliary instructions on how to complete this navigation step,
  // described as a Cue object containing a sequence of texts
  // (e.g. "onto ", "Wallaby way") and images (e.g. road badge of a highway).
  // Separators, such as spaces, should be provided in the sequence.
  // If space is not enough to display the complete content of this Cue
  // instance, the beginning of these instructions must be displayed,
  // cutting as much from the end as needed to fit.
  Cue cue = 5;

  // Indicates whether this step is about to be executed.
  bool is_imminent = 6;

  // The name of the road on which the driver will be after completing the
  // maneuver in the step. This is a subset of the field Cue. The field Cue
  // contains more information and is preferred to be used.
  // Added in Android T.
  Road road = 8;

  // The time when the action being taken in the current step is estimated to be
  // finished. At this time the next step is estimated to start (if there is
  // one). This value is not set if it cannot be predicted, was not provided or
  // is unknown.
  // Added in Android T.
  Timestamp estimated_time_at_end_of_step = 9;
}

// An object representing a latitude/longitude pair. This is expressed as a pair
// of doubles representing degrees latitude and degrees longitude. Unless
// specified otherwise, this must conform to the WGS84 standard
// (http://www.unoosa.org/pdf/icg/2012/template/WGS_84.pdf) Values must be
// within normalized ranges.
//
// Copied from:
// https://github.com/googleapis/googleapis/blob/master/google/type/latlng.proto
message LatLng {
  // The latitude in degrees. It must be in the range [-90.0, +90.0].
  double latitude = 1;
  // The longitude in degrees. It must be in the range [-180.0, +180.0].
  double longitude = 2;
}

// A Timestamp represents a point in time independent of any time zone
// or calendar, represented as seconds and fractions of seconds at
// nanosecond resolution in UTC Epoch time. It is encoded using the
// Proleptic Gregorian Calendar which extends the Gregorian calendar
// backwards to year one. It is encoded assuming all minutes are 60
// seconds long, i.e. leap seconds are "smeared" so that no leap second
// table is needed for interpretation. Range is from
// 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.
// By restricting to that range, we ensure that we can convert to
// and from  RFC 3339 date strings.
// See
// [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt).
//
// This is a subset of
// https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/timestamp.proto
message Timestamp {
  // Reserved fields
  reserved 2;

  // Represents seconds of UTC time since Unix epoch
  // 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to
  // 9999-12-31T23:59:59Z inclusive.
  int64 seconds = 1;
}

// Final or intermediate stop in a navigation route.
message Destination {
  // Congestion level on the way to a destination,
  // compared to ideal driving conditions.
  enum Traffic {
    // Traffic information is not available
    UNKNOWN = 0;

    // High amount of traffic
    HIGH = 1;

    // Intermediate amount of traffic
    MEDIUM = 2;

    // Traffic level close to free flow
    LOW = 3;
  }

  // The name of the destination (formatted for the current user's locale),
  // or empty if destination name is unknown.
  string title = 1;

  // The address of the destination (formatted for the current user's locale),
  // or empty if there is no address associated with this destination
  string address = 2;

  // The travel distance along the route from the current position to this
  // destination, or not set if distance was not provided or is unknown.
  Distance distance = 3;

  // The estimated time at arrival at this destination,
  // or not set if it was not provided or is unknown.
  Timestamp estimated_time_at_arrival = 4;

  // The timezone at destination (for example, ‘Europe/Paris’)
  string zone_id = 5;

  // The geo-location of this destination,
  // or not set if not provided or unknown.
  LatLng location = 6;

  // The congestion level on the route to this destination,
  // compared to to ideal driving conditions.
  Traffic traffic = 7;

  // The estimated duration between now and arrival, formatted for desired
  // rounding (formatted for the current user's locale). For example, a
  // duration of seven minutes and 15 seconds could be set here as "7 min".
  string formatted_duration_until_arrival = 8;

  // The estimated time at arrival at this destination, value is localized e.g.,
  // “3:45 pm PST”. The purpose of using a string is so the HU can display a
  // value that matches what the navigation app might be presenting on different
  // screens (for consistency among car screens). If HUs do not want to display
  // the pre-formatted string, the field "Destination#estimated_time_at_arrival"
  // which is a Timestamp can be used. This value is not set if it was not
  // provided or is unknown.
  // Added in Android T.
  string formatted_estimated_time_at_arrival = 9;
}

// The description for a road.
message Road {
  // Name of the road, for example "Main St" or "101-S".
  string name = 1;
}

// Navigation state data to be displayed on the instrument cluster of a car.
// This is composed of:
//   - a list of destinations
//   - the immediate step or steps in order to drive towards those destinations
message NavigationStateProto {
  // The navigation steps, in order of execution.
  // It is up to the third-party navigation app to decide how many steps in
  // advance will be provided (and need not be truncated by an upcoming
  // destination).
  repeated Step steps = 1;

  // The destinations and intermediate stops in the navigation,
  // sorted in the order in which the driver will arrive to them.
  repeated Destination destinations = 2;

  // The current road being driven, may not be set if the road
  // being driven is unknown. This indicates where the driver is at the moment.
  Road current_road = 3;

  enum ServiceStatus {
    // Service status is not known or an unknown value is specified.
    SERVICE_STATUS_UNSPECIFIED = 0;

    // Default service status,
    // indicating that navigation state data is valid and up-to-date.
    NORMAL = 1;

    // New navigation information is being fetched, and an updated navigation
    // state will be provided soon. OEM rendering services can use this signal
    // to display a progress indicator to the user.
    REROUTING = 2;
  }

  // Current status of the navigation.
  ServiceStatus service_status = 4;
}