add changelog + move changes from #3/#17 into new version

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,21 +77,21 @@ 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 ];
 
                 extensions 16 to max;
         }
 
-        repeated Layer layers = 3;
+        repeated layer layers = 3;
 
         extensions 16 to 8191;
 }

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).

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;
+}

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