From b7941e5611c5336c857e8c0a90a4a3d2b302c738 Mon Sep 17 00:00:00 2001 From: Dane Springmeyer Date: Mon, 28 Jul 2014 09:58:39 -0700 Subject: [PATCH] add changelog + move changes from #3/#17 into new version --- 1.0.0/vector_tile.proto | 26 +++++------ 1.0.1/README.md | 73 +++++++++++++++++++++++++++++++ 1.0.1/vector_tile.proto | 97 +++++++++++++++++++++++++++++++++++++++++ CHANGELOG.md | 9 ++++ 4 files changed, 192 insertions(+), 13 deletions(-) create mode 100644 1.0.1/README.md create mode 100644 1.0.1/vector_tile.proto create mode 100644 CHANGELOG.md diff --git a/1.0.0/vector_tile.proto b/1.0.0/vector_tile.proto index 0c97516..a7229f9 100644 --- a/1.0.0/vector_tile.proto +++ b/1.0.0/vector_tile.proto @@ -4,16 +4,16 @@ package mapnik.vector; option optimize_for = LITE_RUNTIME; -message Tile { +message tile { enum GeomType { - UNKNOWN = 0; - POINT = 1; - LINESTRING = 2; - POLYGON = 3; + Unknown = 0; + Point = 1; + LineString = 2; + Polygon = 3; } // Variant type encoding - message Value { + message value { // Exactly one of these values may be present in a valid message optional string string_value = 1; optional float float_value = 2; @@ -26,8 +26,8 @@ message Tile { extensions 8 to max; } - message Feature { - optional uint64 id = 1 [ default = 0 ]; + message feature { + optional uint64 id = 1; // Tags of this feature. Even numbered values refer to the nth // value in the keys list on the tile message, odd numbered @@ -36,7 +36,7 @@ message Tile { repeated uint32 tags = 2 [ packed = true ]; // The type of geometry stored in this feature. - optional GeomType type = 3 [ default = UNKNOWN ]; + optional GeomType type = 3 [ default = Unknown ]; // Contains a stream of commands and parameters (vertices). The // repeat count is shifted to the left by 3 bits. This means @@ -67,7 +67,7 @@ message Tile { repeated uint32 geometry = 4 [ packed = true ]; } - message Layer { + message layer { // 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 @@ -77,13 +77,13 @@ message Tile { required string name = 1; // The actual features in this tile. - repeated Feature features = 2; + repeated feature features = 2; // Dictionary encoding for keys repeated string keys = 3; // Dictionary encoding for values - repeated Value values = 4; + repeated value values = 4; // The bounding box in this tile spans from 0..4095 units optional uint32 extent = 5 [ default = 4096 ]; @@ -91,7 +91,7 @@ message Tile { extensions 16 to max; } - repeated Layer layers = 3; + repeated layer layers = 3; extensions 16 to 8191; } diff --git a/1.0.1/README.md b/1.0.1/README.md new file mode 100644 index 0000000..ce53cad --- /dev/null +++ b/1.0.1/README.md @@ -0,0 +1,73 @@ +# vector-tile-spec + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", +"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in +this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). + +## 1. Purpose + +This specification attempts to create a standard for encoding of tiled geospatial data that can be shared across clients. + +## 2. File format + +The vector tile encoding scheme encodes vector data for a tile in a space efficient manner. It is designed to be used in browsers or serverside applications for fast rendering or lookups of feature data. + +Vector Tiles use [Google Protocol buffers](https://developers.google.com/protocol-buffers/) as a container format. It is exclusively geared towards square pixel tiles in [Spherical Mercator projection](http://wiki.openstreetmap.org/wiki/Mercator). + +## 3. Internal structure + +A vector tile can consist of one or more named layers and containing one or more features. + +Features contain an id, attributes, and geometries: either point, linestring, or polygon. + +Geometries are stored as an a single array of integers that represent an command,x,y stream (where command is a rendering command like move_to or line_to). Commands are encoded only when they change. Geometries are clipped, reprojected into spherical mercator, converted to screen coordinates, and [delta](http://en.wikipedia.org/wiki/Delta_encoding) and [zigzag](https://developers.google.com/protocol-buffers/docs/encoding#types) encoded. + +Feature attributes are encoded as key:value pairs which are dictionary encoded at the layer level for compact storage of any repeated keys or values. Values use [variant](https://developers.google.com/protocol-buffers/docs/encoding#varints) type encoding supporting both unicode strings, boolean values, and various integer and floating point types. + +For example, a GeoJSON feature like: + +```json +{ + "type": "FeatureCollection", + "features": [ + { + "geometry": { + "type": "Point", + "coordinates": [ + -8247861.1000836585, + 4970241.327215323 + ] + }, + "type": "Feature", + "properties": { + "hello": "world" + } + } + ] +} +``` + +Would be structured like: + +```js +layers { + name: "points" + features { + id: 1 + tags: 0 + tags: 0 + type: Point + geometry: 9 + geometry: 2410 + geometry: 3080 + } + keys: "hello" + values { + string_value: "world" + } + extent: 4096 + version: 2 +} +``` + +The complete and authoritative details on encoding are part of the code comments for the [vector tile protobuf schema document](vector_tile.proto). diff --git a/1.0.1/vector_tile.proto b/1.0.1/vector_tile.proto new file mode 100644 index 0000000..0c97516 --- /dev/null +++ b/1.0.1/vector_tile.proto @@ -0,0 +1,97 @@ +// Protocol Version 1 + +package mapnik.vector; + +option optimize_for = LITE_RUNTIME; + +message Tile { + enum GeomType { + UNKNOWN = 0; + POINT = 1; + LINESTRING = 2; + POLYGON = 3; + } + + // Variant type encoding + message Value { + // Exactly one of these values may 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; + + extensions 8 to max; + } + + message Feature { + optional uint64 id = 1 [ default = 0 ]; + + // Tags of this feature. Even numbered values refer to the nth + // value in the keys list on the tile message, odd numbered + // values refer to the nth value in the values list on the tile + // message. + 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). The + // repeat count is shifted to the left by 3 bits. This means + // that the command has 3 bits (0-7). The repeat count + // indicates how often this command is to be repeated. Defined + // commands are: + // - MoveTo: 1 (2 parameters follow) + // - LineTo: 2 (2 parameters follow) + // - ClosePath: 7 (no parameters follow) + // + // Commands are encoded as uint32 varints. Vertex parameters + // are encoded as deltas to the previous position and, as they + // may be negative, are further "zigzag" encoded as unsigned + // 32-bit ints: + // + // n = (n << 1) ^ (n >> 31) + // + // Ex.: MoveTo(3, 6), LineTo(8, 12), LineTo(20, 34), ClosePath + // Encoded as: [ 9 6 12 18 10 12 24 44 15 ] + // == command type 7 (ClosePath), length 1 + // ===== relative LineTo(+12, +22) == LineTo(20, 34) + // === relative LineTo(+5, +6) == LineTo(8, 12) + // == [00010 010] = command type 2 (LineTo), length 2 + // === relative MoveTo(+3, +6) + // == [00001 001] = command type 1 (MoveTo), length 1 + // + // The original position is (0,0). + repeated uint32 geometry = 4 [ packed = true ]; + } + + message Layer { + // 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 ]; + + required string name = 1; + + // The actual features in this tile. + repeated Feature features = 2; + + // Dictionary encoding for keys + repeated string keys = 3; + + // Dictionary encoding for values + repeated Value values = 4; + + // The bounding box in this tile spans from 0..4095 units + optional uint32 extent = 5 [ default = 4096 ]; + + extensions 16 to max; + } + + repeated Layer layers = 3; + + extensions 16 to 8191; +} diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..305971c --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,9 @@ +## Vector Tile Spec Changelog + +### 1.0.1 + + - Used TitleCase and UPPERCASE in `vector_tile.proto` to match Protobuf style guide (#3) + +### 1.0.0 + + - First release \ No newline at end of file