segment.proto

package opentraffic.osmlr;

message Segment {

  // road classes are based on OpenStreetMap usage of the "highway" tag.
  // each value of the enumeration corresponds to one value of the tag,
  // except for ClassServiceOther, which is used for service and other roads.
  enum RoadClass {
    ClassMotorway = 0;
    ClassTrunk = 1;
    ClassPrimary = 2;
    ClassSecondary = 3;
    ClassTertiary = 4;
    ClassUnclassified = 5;
    ClassResidential = 6;
    ClassServiceOther = 7;
  }

  // form of way describes the physical attributes of the road.
  enum FormOfWay {
    // use FowUndefined if you do not know what physical attributes the road
    // has.
    FowUndefined = 0;

    // use FowMotorway for motorways.
    FowMotorway = 1;

    // use FowMultipleCarriageway for multiple carriageway roads. that is, when
    // there are separate OSM ways for each direction of travel.
    FowMultipleCarriageway = 2;

    // use FowSingleCarriageway for other roads.
    FowSingleCarriageway = 3;

    // use FowRoundabout for roundabouts
    FowRoundabout = 4;

    // use FowTrafficSquare for roads which enclose an area, but which are not
    // roundabouts
    FowTrafficSquare = 5;

    // use FowSlipRoad for slip roads, ramps and other links.
    FowSlipRoad = 6;

    // use FowOther for roads which do not match any of the above definitions,
    // but for which the form of way is known.
    FowOther = 7;
  }

  message LatLng {
    // lat & lng in EPSG:4326 multiplied by 10^7 and rounded to the nearest
    // integer. this gives a precision of about 1.1cm (7/16ths of an inch)
    // worst case at the equator.
    optional sfixed32 lat = 1;
    optional sfixed32 lng = 2;
  }

  // a segment consists of multiple LocationReferences, each of which describes
  // the road at a particular reference coordinate, or properties of the road
  // between the current LocationReference and the next.
  //
  // the first and last LocationReference reference coordinates will usually be at
  // "true" intersections, which are intersections where there are multiple
  // paths through the intersection. This excludes "false" intersections where
  // two roads cross, but there are not multiple paths, such as overpasses,
  // bridges, changes of road name or properties.
  //
  //          ___
  //  |      /   \        _4---5--
  // -1-----2     \    __/     |
  //  |            3__/        |
  //
  // in the example above, the Segment consists of 5 LocationReferences,
  // numbered 1-5. locations 1 & 5 are at true intersections with other roads
  // and 2, 3 & 4 are intermediate LocationReferences inserted due to the length
  // of the road.
  //
  // Occasionally, a LocationReference can be inserted along a road (i.e., not at 
  // a true intersection) to break long road segments into multiple OSMLR
  // segments. 
  //
  message LocationReference {
    // the reference coordinate.
    optional LatLng coord = 1;

    // bearing in degrees clockwise from true north between 0 and 359 - will
    // generally fit in a couple of bytes varint.
    //
    // the bearing should be calculated toward a point 20m along the road from
    // the reference coordinate towards the next LocationReference. if this is
    // the final LocationReference, then omit the bearing.
    //
    // each LocationReference, of which there may be several in this Segment,
    // except for the last must have a bearing calculated from the reference
    // coordinate of this LocationReference.
    optional uint32 bear = 2;

    // road class at the reference coordinate.
    optional RoadClass start_frc = 3;

    // form of way at the reference coordinate.
    optional FormOfWay start_fow = 4;

    // lowest road class (most important road) between the start coordinate
    // and the next LocationReference.
    optional RoadClass least_frc = 5;

    // length in meters, rounded to the nearest meter. the maximum allowed
    // length is 15km, but most segments will be much shorter, so a varint
    // representation makes sense.
    //
    // if the length between successive LocationReferences is more than 15km
    // then you MUST insert an intermediate LocationReference.
    optional uint32 length = 6;

    // Is this LRP at a node/intersection (true) or along a road (false)?
    // This hint can be useful wen associating OSMLR to routing graphs
    optional bool at_node = 7;
  }

  // a segment is a list of at least two LocationReferences.
  //
  // all but the last LocationReference must contain a full set of data for
  // each field, but the final one should consist of only a reference
  // coordinate. any other information on the final LocationReference may be
  // ignored.
  //
  // a segment with only a single LocationReference is invalid and may be
  // ignored.
  repeated LocationReference lrps = 1;
}