vector_tile.proto

package open_vector_tile;

option optimize_for = LITE_RUNTIME;

// This is a modified version of the Mapbox Vector Tile specification
// To show how the two specifications coexist, we're using the same
// protobuffer definition.

message Tile {
  // GeomType is described in section 4.3.4 of the specification
  enum GeomType {
    // should never be used.
    UNKNOWN = 0;
    // can be a point or a multipoint
    POINT = 1;
    // can be a line or a multilinestring
    LINESTRING = 2;
    // can be a polygon or a multipolygon
    POLYGON = 3;
  }

  // Variant type encoding
  // The use of values is described in section 4.1 of the specification
  message Value {
    // Exactly one of these values must be present in a valid message
    optional string string_value = 1;
    optional float float_value = 2;
    optional double double_value = 3;
    optional int64 int_value = 4;
    optional uint64 uint_value = 5;
    optional sint64 sint_value = 6;
    optional bool bool_value = 7;
    // potential extensions
    extensions 8 to max;
  }

  // Features are described in section 4.2 of the specification
  message MapboxFeature {
    optional uint64 id = 1 [ default = 0 ];
    // Tags of this feature are encoded as repeated pairs of
    // integers.
    // A detailed description of tags is located in sections
    // 4.2 and 4.4 of the specification
    repeated uint32 tags = 2 [ packed = true ];
    // The type of geometry stored in this feature.
    optional GeomType type = 3 [ default = UNKNOWN ];
    // Contains a stream of commands and parameters (vertices).
    // A detailed description on geometry encoding is located in 
    // section 4.3 of the specification.
    repeated uint32 geometry = 4 [ packed = true ];
  }

  // Features are described in section 4.2 of the specification
  message OpenFlatFeature {
    optional uint64 id = 15 [ default = 0 ];
    // Tags of this feature are encoded as repeated pairs of
    // integers.
    // A detailed description of tags is located in sections
    // 4.2 and 4.4 of the specification
    repeated uint32 tags = 1 [ packed = true ];
    // The type of geometry stored in this feature.
    optional GeomType type = 2 [ default = UNKNOWN ];
    // Contains a stream of commands and parameters (vertices).
    // A detailed description on geometry encoding is located in 
    // section 4.3 of the specification.
    repeated uint32 geometry = 3 [ packed = true ];
    // 
    repeated uint32 indices = 4 [ packed = true ];
    //
    repeated uint32 tessellation = 5 [ packed = true ];
  }

  // Layers are described in section 4.1 of the mapbox specification
  message MapboxLayer {
    // Any compliant implementation must first read the version
    // number encoded in this message and choose the correct
    // implementation for this version number before proceeding to
    // decode other parts of this message.
    required uint32 version = 15 [ default = 1 ];
    // The name of the layer
    required string name = 1;
    // The actual features in this tile.
    repeated MapboxFeature features = 2;
    // Dictionary encoding for keys
    repeated string keys = 3;
    // Dictionary encoding for values
    repeated Value values = 4;
    // The extent of the layer
    required uint32 extent = 5;
    // potential extensions
    extensions 16 to max;
  }

  // Layers are described in section 4.1 of the specification
  // See https://github.com/mapbox/vector-tile-spec
  message OpenFlatLayer {
    // Any compliant implementation must first read the version
    // number encoded in this message and choose the correct
    // implementation for this version number before proceeding to
    // decode other parts of this message.
    required uint32 version = 15 [ default = 1 ];
    // The name of the layer
    required string name = 1;
    // The actual features in this tile.
    repeated OpenFlatFeature features = 2;
    // Dictionary encoding for keys
    repeated string keys = 3;
    // Dictionary encoding for values
    repeated Value values = 4;
    // Although this is an "optional" field it is required by the specification.
    // See https://github.com/mapbox/vector-tile-spec/issues/47
    optional uint32 extent = 5 [ default = 4096 ];
    // potential extensions
    extensions 16 to max;
  }

  // See #43-vector-layer
  message OpenLayer {
    required uint32 version = 1;
    // The index pointing to the where in the column cache's "string" column
    // the name of the layer is stored
    required uint32 name = 2;
    // The encoded extent. MUST be one of 512, 1024, 2048, 4096, or 8192.
    // These are encoded as 0, 1, 2, 3, 4 respectively.
    required uint32 extent = 3;
    // TODO: Get the correct section.
    // encoded features. Learn how to read features in section 4.2
    repeated bytes feature = 4;
    // potential extensions
    extensions 16 to max;
  }

  message ColumnCache {
    repeated string string = 1; 
    repeated uint64 u64 = 2;
    repeated int64 i64 = 3;
    repeated float f32 = 4;
    //  64-bit relative numbers
    repeated double f64 = 5;
    // points: encoded Point[]
    repeated bytes points = 6;
    // points3D: encoded Point3D[]
    repeated bytes points3D = 7;
    // indices: encoded uint32[]
    repeated bytes indices = 8;
    // shapes: encoded uint32[]
    repeated bytes shapes = 9;
    // bbox: encoded BBOX or BBOX3D
    repeated bytes bbox = 10;
    // potential extensions
    extensions 16 to max;
  }

  // See 4.6 Grid Layer #46-grid-layer in the spec
  message GridLayer {
    // The extent of the layer
    required uint32 extent = 1;
    required uint32 size = 2;
    required float min = 3;
    required float max = 4;
    repeated bytes data = 5;
    required string name = 6;
  }

  // GeomType is described in section 4.3.4 of the specification
  enum ImageType {
    PNG = 0;
    JPG = 1;
    WEBP = 2;
    GIF = 3;
    AVIF = 4;
    SVG = 5;
    BMP = 6;
    RAW = 7;
    OTHER = 8;
  }

  // See 4.7 Image Layer (#47-image-layer) in the spec
  message ImageLayer {
    // enum representing the image type
    required ImageType type = 1;
    required uint32 width = 2;
    required uint32 height = 3;
    required bytes image = 4;
    required string name = 5;
  }

  // The Open S2 Flat Tile Specification
  repeated OpenFlatLayer open_flat_layers = 1;
  // The Mapbox Vector Tile Specification
  repeated MapboxLayer mapbox_layers = 3;
  // The Open Vector Tile Specification
  repeated OpenLayer open_layers = 4;
  // Note: required if using the Open Vector Tile Specification
  optional ColumnCache column_cache = 5;
  // Grided data
  repeated GridLayer grids = 6;
  // Image data
  repeated ImageLayer images = 7;
  // potential extensions
  extensions 16 to 8191;
}