Vector Tiles

Styling/README.md

@@ -25,6 +25,7 @@ Example: Creating a color ramp based on building height.
 * Tom Fili, [@CesiumFili](https://twitter.com/CesiumFili)
 * Sean Lilley, [@lilleyse](https://github.com/lilleyse)
 * Patrick Cozzi, [@pjcozzi](https://twitter.com/pjcozzi)
+* Dan Bagnell, [@bagnell](https://github.com/bagnell)
 
 Contents:
 
@@ -51,6 +52,7 @@ Contents:
    * [Notes](#notes)
 * [Batch Table Hierarchy](#batch-table-hierarchy)
 * [Point Cloud](#point-cloud)
+* [Vector Data](#vector-data)
 * [File Extension](#file-extension)
 * [MIME Type](#mime-type)
 * [Acknowledgments](#acknowledgments)
@@ -254,7 +256,7 @@ The following types are supported:
 * `vec4`
 * `RegExp`
 
-All of the types except `vec2`, `vec3`, `vec4`, and `RegExp` have the same syntax and runtime behavior as JavaScript.  `vec2`, `vec3`, and `vec4` are derived from GLSL vectors and behave similarly to JavaScript `Object` (see the [Vector section](#vector)).  Colors derive from [CSS3 Colors](https://www.w3.org/TR/css3-color/) and are implemented as `vec4`. `RegExp` is derived from JavaScript and described in the [RegExp section](#regexp).
+All of the types except `vec2`, `vec3`, `vec4`, and `RegExp` have the same syntax and runtime behavior as JavaScript.  `vec2`, `vec3`, and `vec4` are derived from GLSL vectors and behave similarly to JavaScript `Object` (see the [Vector section](#vector)).  Colors derive from [CSS3 Colors](https://www.w3.org/TR/css3-color/) and are implemented as `vec4`. Fonts derive from [CSS3 Fonts](https://www.w3.org/TR/css-fonts-3/) and are implemented as `String`. RegExp` is derived from JavaScript and described in the [RegExp section](#regexp).
 
 Example expressions for different types include the following:
 * `true`, `false`
@@ -268,6 +270,7 @@ Example expressions for different types include the following:
 * `vec4(1.0, 2.0, 3.0, 4.0)`
 * `color('#00FFFF')`
 * `regExp('^Chest'))`
+* `"30px sans-serif"`
 
 #### Number
 
@@ -1344,6 +1347,65 @@ For example:
 
 **TODO : add note about GLSL implementations requires strict type comparisons among other things: https://github.com/AnalyticalGraphicsInc/3d-tiles/issues/140**
 
+## Vector Data
+
+A [Vector Tile](../TileFormats/VectorData/README.md) is a collection of vector features such as points, polygons, and polylines. Vector features can be styled similar to other features with `color` and `show`. Points have several other styling options:
+
+**TODO : generate these tables from the JSON schema**
+
+The following style properties apply to geometry features in vector tiles:
+
+| Style | Type | Description | Default |
+| --- | --- | --- | --- |
+| `show` | `Boolean` | Whether or not to show the feature. | `true` |
+| `color` | `vec4` | The color of the feature. | `color('#FFFFFF')` |
+
+The following style properties apply to point features in vector tiles:
+
+| Style | Type | Description | Default |
+| --- | --- | --- | --- |
+| `show` | `Boolean` | Whether or not to show the feature. | `true` |
+| `pointSize` | `Number` | The size of the point in pixels. `pointSize` is ignored when `image` is defined. | `8.0` |
+| `pointColor` | `vec4` | The color of the point. `pointColor` is ignored when `image` is defined. | `color('#FFFFFF')` |
+| `pointOutlineColor` | `vec4` | The color of the point outline. `pointOutlineColor` is ignored when `image` is defined. | `color('#000000')` |
+| `pointOutlineWidth` | `Number` | The width, in pixels, of the point outline. `pointOutlineWidth` is ignored when `image` is defined. | `0.0` |
+| `labelText` | `String` | The text to display for the point. | `undefined` |
+| `labelColor` | `vec4` | The color of the label. This is ignored when `labelText` is undefined. | `color('#FFFFFF')` |
+| `labelStyle` | `Number` | The label style: **fill** (`0`), **outline** (`1`), or **both** (`2`). This is ignored when `labelText` is undefined. | `0` |
+| `labelOutlineColor` | `vec` | The color of the text outline. This is ignored when `labelText` is undefined. | `color('#FFFFFF')` |
+| `labelOutlineWidth` | `Number` | The width of the text outline. This is ignored when `labelText` is undefined. | `1.0` |
+| `font` | `String` | The font of the displayed text. This is ignored when `labelText` is undefined. | `"30px sans-serif"` |
+| `backgroundColor` | `vec4` | The label background color. This is ignored when `labelText` is undefined. | `rgba(42, 42, 42, 0.8)` |
+| `backgroundPadding` | `vec2` | The background padding, in pixels, of this label.  The `x` value controls horizontal padding, and the `y` value controls vertical padding. This is ignored when `labelText` is undefined. | `vec2(7, 5)` |
+| `backgroundEnabled` | `Boolean` | Whether or not to display the label background. This is ignored when `labelText` is undefined. | `false` |
+| `scaleByDistance` | `vec4` | Sets near and far scaling properties of a feature based on the features's distance from the camera. A feature's scale will interpolate between the `y` and `w` values while the camera distance falls within the upper and lower bounds of the specified `x` and `z` value. Outside of these ranges, the features's scale remains clamped to the nearest bound.  If undefined, `scaleByDistance` will be disabled. | `undefined` |
+| `translucencyByDistance` | `vec4` | Sets near and far translucency properties of a feature based on the feature's distance from the camera. A feature's translucency will interpolate between the `y` and `w` while the camera distance falls within the upper and lower bounds of the specified `x` and `z`. Outside of these ranges the feature's translucency remains clamped to the nearest bound.  If undefined, `translucencyByDistance` will be disabled. | `undefined` |
+| `distanceDisplayCondition` | `vec2` | Sets the condition specifying at what distance from the camera that this feature will be displayed. The `x` value is the smallest distance in the interval where the feature is visible. The `y` value is the largest distance in the interval where the object is visible. If undefined, `distanceDisplayCondition` will be disabled. | `undefined` |
+| `heightOffset` | `Number` | The distance, in meters, to offset the height. This is ignored if the valuse is less than or equal to zero. | `0.0` |
+| `anchorLineEnabled` | `Boolean` | Whether or not to display a line from the feature to the point on terrain. This is ignored unless `heightOffset` is greater than zero. | `false` |
+| `anchorLineColor` | `vec4` | The color of the line from the feature to terrain. This is ignored unless `heightOffset` is greater than 0.0. | `color('#FFFFFF')` |
+| `image` | `String` | A URL to an image or a data URI to be displayed instead of a point. | `undefined` |
+| `disableDepthTestDistance` | `Number` | The distance where depth testing for a point will be disabled. | `undefined` |
+| `origin` | `Number` | The horizontal origin of the point: **center** (`0`), **left** (`1`), or **right** (`-1`). | `0` |
+| `labelOrigin` | The horizontal origin of the label: **center** (`0`), **left** (`1`), or **right** (`-1`). This is ignored when `labelText` is undefined. | `0` |
+
+For example:
+
+```json
+{
+    "labelText" : "${DISPLAY_TEXT}",
+    "labelColor" : "color('#FFFF00')",
+    "labelStyle" : "2",
+    "image" : "'http://example.com/url/to/image.jpg'",
+    "origin" : "1",
+    "labelOrigin" : "-1"
+}
+```
+
+| Fill | Outline | Fill and Outline |
+| --- | --- | --- |
+| ![](figures/label_fill.jpg) | ![](figures/label_outline.jpg) | ![](figures/label_fill_outline.jpg) |
+
 ## File Extension
 
 TBA

Styling/schema/style.vec2Expression.schema.json

@@ -0,0 +1,7 @@
+{
+  "$schema" : "http://json-schema.org/draft-04/schema",
+  "id" : "style.vec2Expression.schema.json",
+  "title" : "vec2 expression",
+  "type" : "string",
+  "description" : "3D Tiles style expression that evaluates to a vec2."
+}

Styling/schema/style.vec4Expression.schema.json

@@ -0,0 +1,7 @@
+{
+  "$schema" : "http://json-schema.org/draft-04/schema",
+  "id" : "style.vec4Expression.schema.json",
+  "title" : "vec4 expression",
+  "type" : "string",
+  "description" : "3D Tiles style expression that evaluates to a vec4."
+}

Styling/schema/vctr.style.schema.json

@@ -0,0 +1,243 @@
+{
+  "$schema" : "http://json-schema.org/draft-04/schema",
+  "id" : "vctr.style.schema.json",
+  "title" : "Vector Style",
+  "type" : "object",
+  "description" : "A 3D Tiles style with additional properties for vector data.",
+  "allOf" : [{
+    "$ref" : "style.schema.json"
+  }, {
+    "properties" : {
+      "show" : {
+        "oneOf" : [{
+          "$ref" : "style.booleanExpression.schema.json"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "If a feature should be shown.",
+        "default" : "true"
+      },
+      "pointSize" : {
+        "oneOf" : [{
+          "$ref" : "style.numberExpression.schema.json"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "The size of points in pixels.",
+        "default" : 8.0
+      },
+      "pointColor" : {
+        "oneOf" : [{
+          "$ref" : "style.colorExpression.schema.json"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "The color of the point.",
+        "default" : "Color('#FFFFFF')"
+      },
+      "pointOutlineColor" : {
+        "oneOf" : [{
+          "$ref" : "style.colorExpression.schema.json"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "The color of the point outline.",
+        "default" : "Color('#000000')"
+      },
+      "pointOutlineWidth" : {
+        "oneOf" : [{
+          "$ref" : "style.numberExpression.schema.json"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "The width, in pixels, of the point outline.",
+        "default" : 0.0
+      },
+      "labelText" : {
+        "oneOf" : [{
+          "type" : "string"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "The label text to display.",
+        "default" : "Undefined"
+      },
+      "labelColor" : {
+        "oneOf" : [{
+          "$ref" : "style.colorExpression.schema.json"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "The color of the label.",
+        "default" : "Color('#FFFFFF')"
+      },
+      "labelStyle" : {
+        "oneOf" : [{
+          "$ref" : "style.numberExpression.schema.json"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "The label style: fill (0), outline (1), or both (2).",
+        "default" : 0
+      },
+      "labelOutlineColor" : {
+        "oneOf" : [{
+          "$ref" : "style.colorExpression.schema.json"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "The color of the text outline.",
+        "default" : "Color('#FFFFFF')"
+      },
+      "labelOutlineWidth" : {
+        "oneOf" : [{
+          "$ref" : "style.numberExpression.schema.json"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "The width of the text outline.",
+        "default" : 1.0
+      },
+      "font" : {
+        "oneOf" : [{
+          "type" : "string"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "The font of the displayed text.",
+        "default" : "'30px sans-serif'"
+      },
+      "backgroundColor" : {
+        "oneOf" : [{
+          "$ref" : "style.colorExpression.schema.json"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "The label background color.",
+        "default" : "rgba(42, 42, 42, 0.8)"
+      },
+      "backgroundPadding" : {
+        "oneOf" : [{
+          "$ref" : "style.vec2Expression.schema.json"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "The background padding, in pixels, of this label.  The `x` value controls horizontal padding, and the `y` value controls vertical padding.",
+        "default" : "vec2(7, 5)"
+      },
+      "backgroundEnabled" : {
+        "oneOf" : [{
+          "$ref" : "style.booleanExpression.schema.json"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "Whether or not to display the label background.",
+        "default" : "false"
+      },
+      "scaleByDistance" : {
+        "oneOf" : [{
+          "$ref" : "style.vec4Expression.schema.json"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "Sets near and far scaling properties of a feature based on the features's distance from the camera. A feature's scale will interpolate between the `y` and `w` values while the camera distance falls within the upper and lower bounds of the specified `x` and `z` value. Outside of these ranges, the features's scale remains clamped to the nearest bound.  If undefined, `scaleByDistance` will be disabled.",
+        "default" : "Undefined"
+      },
+      "translucencyByDistance" : {
+        "oneOf" : [{
+          "$ref" : "style.vec4Expression.schema.json"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "Sets near and far translucency properties of a feature based on the feature's distance from the camera. A feature's translucency will interpolate between the `y` and `w` while the camera distance falls within the upper and lower bounds of the specified `x` and `z`. Outside of these ranges the feature's translucency remains clamped to the nearest bound.  If undefined, `translucencyByDistance` will be disabled.",
+        "default" : "Undefined"
+      },
+      "distanceDisplayCondition" : {
+        "oneOf" : [{
+          "$ref" : "style.vec2Expression.schema.json"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "Sets the condition specifying at what distance from the camera that this feature will be displayed. The `x` value is the smallest distance in the interval where the feature is visible. The `y` value is the largest distance in the interval where the object is visible. If undefined, `distanceDisplayCondition` will be disabled.",
+        "default" : "Undefined"
+      },
+      "heightOffset" : {
+        "oneOf" : [{
+          "$ref" : "style.numberExpression.schema.json"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "The distance, in meters, to offset the height. This is ignored if the valuse is less than or equal to zero.",
+        "default" : 0.0
+      },
+      "anchorLineEnabled" : {
+        "oneOf" : [{
+          "$ref" : "style.booleanExpression.schema.json"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "Whether or not to display a line from the feature to the point on terrain. This is ignored unless `heightOffset` is greater than zero.",
+        "default" : "false"
+      },
+      "anchorLineColor" : {
+        "oneOf" : [{
+          "$ref" : "style.colorExpression.schema.json"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "The color of the line from the feature to terrain. This is ignored unless `heightOffset` is greater than 0.0.",
+        "default" : "Color('#FFFFFF)"
+      },
+      "image" : {
+        "oneOf" : [{
+          "type" : "string"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "A URL to an image or a data URI to be displayed instead of a point.",
+        "default" : "Undefined"
+      },
+      "disableDepthTestDistance" : {
+        "oneOf" : [{
+          "$ref" : "style.numberExpression.schema.json"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "The distance from that camera at which the depth test will be disabled.",
+        "default" : "Undefined"
+      },
+      "origin" : {
+        "oneOf" : [{
+          "$ref" : "style.numberExpression.schema.json"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "The horizontal origin of the point: center ('0'), left ('1'), or right ('-1').",
+        "default" : "0"
+      },
+      "labelOrigin" : {
+        "oneOf" : [{
+          "$ref" : "style.numberExpression.schema.json"
+        }, {
+          "$ref" : "style.condition.schema.json"
+        }],
+        "description" : "The horizontal origin of the label: center ('0'), left ('1'), or right ('-1').",
+        "default" : "0"
+      }
+    },
+    "dependencies" : {
+      "labelText" : [
+        "labelStyle",
+        "labelColor",
+        "labelOutlineColor",
+        "labelOutlineWidth",
+        "labelOrigin",
+        "font",
+        "backgroundColor",
+        "backgroundPadding",
+        "backgroundEnabled"
+      ]
+    }
+  }],
+  "additionalProperties" : false
+}