Merge pull request #360 from AnalyticalGraphicsInc/1.0-revisions

1.0 revisions

Author: lilleyse

CONTRIBUTING.md

@@ -8,7 +8,7 @@ To add any schema or markdown updates to the 3D Tiles Specification PDF, take th
 
 1. Generate a `.docx` file for each section.
     * Run [pandoc](https://pandoc.org/demos.html) to generate a formatted `.docx` file from markdown. Run the following command in the directory that contains the input file to preserve images.
-        * `pandoc ./README.md -o README.docx -f github_markdown`
+        * `pandoc ./README.md -o README.docx -f markdown_github`
     * Generate a `.docx` for each of the following files:
         * `specification/README.md`
         * `specification/TileFormats/BatchTable/README.md`

Q-and-A.md

@@ -1,6 +1,6 @@
 # 3D Tiles Q&A
 
-## Contents 
+## Contents
 
 * [General Q&A](#general-qa)
    * [Is 3D Tiles specific to Cesium?](#is-3d-tiles-specific-to-cesium)
@@ -93,7 +93,7 @@ See [#15](https://github.com/AnalyticalGraphicsInc/3d-tiles/issues/15).
 
 #### How are cracks between tiles with vector data handled?
 
-Unlike 2D, in 3D, we expect adjacent tiles to be from different LODs so, for example, in the distance, lower resolution tiles are used.  Adjacent tiles from different LODs can lead to an artifact called _cracking_ where there are gaps between tiles.  For terrain, this is generally handled by dropping _skirts_ slightly angled outward around each tile to fill the gap.  For 3D buildings, this is handled by extending the tile boundary to fully include buildings on the edge; [see Quadtrees](./specification/README.md#Quadtrees).  For vector data, this is an open research problem that we need to solve.  This could involve boundary-aware simplification or runtime stitching. 
+Unlike 2D, in 3D, we expect adjacent tiles to be from different LODs so, for example, in the distance, lower resolution tiles are used.  Adjacent tiles from different LODs can lead to an artifact called _cracking_ where there are gaps between tiles.  For terrain, this is generally handled by dropping _skirts_ slightly angled outward around each tile to fill the gap.  For 3D buildings, this is handled by extending the tile boundary to fully include buildings on the edge; [see Quadtrees](./specification/README.md#Quadtrees).  For vector data, this is an open research problem that we need to solve.  This could involve boundary-aware simplification or runtime stitching.
 
 #### When using replacement refinement, can multiple children be combined into one request?
 
@@ -113,4 +113,4 @@ See [#11](https://github.com/AnalyticalGraphicsInc/3d-tiles/issues/11).
 
 #### What compressed texture formats does 3D Tiles use?
 
-3D Tiles will support the same texture compression that glTF [will support](https://github.com/KhronosGroup/glTF/issues/59).  In addition, we need to consider how well GPU formats compress compared to, for example, jpeg.  Some desktop game engines stream jpeg, then decompress and recompress to a GPU format in a thread.  The CPU overhead for this approach may be too high for JavaScript and Web Workers.
+3D Tiles will support the same texture compression that glTF [will support](https://github.com/KhronosGroup/glTF/issues/59).  In addition, we need to consider how well GPU formats compress compared to, for example, jpeg.  Some desktop game engines stream jpeg, then decompress and recompress to a GPU format in a thread.  The CPU overhead for this approach may be too high for JavaScript and Web Workers.

specification/README.md

@@ -23,7 +23,6 @@
    * [String conversion](#string-conversions)
    * [Constants](#constants)
    * [Variables](#variables)
-   * [Built-in variables](#built-in-variables)
    * [Built-in functions](#built-in-functions)
    * [Notes](#notes)
 * [Point Cloud](#point-cloud)
@@ -34,6 +33,8 @@
 
 3D Tiles styles provide concise declarative styling of tileset features.  A style defines expressions to evaluate the display of a feature, for example `color` (RGB and translucency) and `show` properties, often based on the feature's properties stored in the tile's [Batch Table](../TileFormats/BatchTable/README.md).
 
+A style may be applied to a tile that doesn't contain features, in which case the tile is treated as an implicit single feature without properties.
+
 While a style may be created for and reference properties of a tileset, a style is independent of a tileset, such that any style can be applied to any tileset.
 
 Styles are defined with JSON and expressions written in a small subset of JavaScript augmented for styling. Additionally, the styling language provides a set of built-in functions to support common math operations.
@@ -633,22 +634,6 @@ ${temperatures.values[0]} === 70
 ${temperatures['values'][0]} === 70 // Same as (temperatures[values])[0] and temperatures.values[0]
 ```
 
-### Built-in variables
-
-The prefix `tiles3d_` is reserved for built-in variables. The following built-in variables are supported by the styling language:
-
-* [`tiles3d_tileset_time`](#tiles3d_tileset_time)
-
-#### tiles3d_tileset_time
-
-Gets the time, in milliseconds, since the tileset was first loaded. This is useful for creating dynamic styles that change with time.
-
-```json
-{
-    "color" : "color() * abs(cos(${Temperature} + ${tiles3d_tileset_time}))"
-}
-```
-
 ### Built-in functions
 
 The following built-in functions are supported by the styling language:
@@ -1260,13 +1245,13 @@ For example:
 > * Evaluation of `isNan` and `isFinite` (GLSL 2.0+ supports `isnan` and `isinf` for these functions respectively)
 > * The types `null` and `undefined`
 > * Strings, including accessing object properties (`color()['r']`) and batch table values
-> * Regular expressions 
+> * Regular expressions
 > * Arrays of lengths other than 2, 3, or 4
 > * Mismatched type comparisons (e.g. `1.0 === false`)
 > * Array index out of bounds
 
 ## File extension and MIME type
- 
+
 Tileset styles use the `.json` extension and the `application/json` mime type.
 
 ## Property reference

specification/Styling/README.md

@@ -13,7 +13,7 @@
 
 ## Overview
 
-A _Batch Table_ contains per-feature application-specific metadata in a tile. These properties may be queried at runtime for declarative styling and application-specific use cases such as populating a UI or issuing a REST API request.  Some example Batch Table properties are building heights, geographic coordinates, and database primary keys.
+A _Batch Table_ is a component of a tile's binary body and contains per-feature application-specific properties in a tile. These properties are queried at runtime for declarative styling and any application-specific use cases such as populating a UI or issuing a REST API request.  Some example Batch Table properties are building heights, geographic coordinates, and database primary keys.
 
 A Batch Table is used by the following tile formats:
 * [Batched 3D Model](../Batched3DModel/README.md) (b3dm)
@@ -49,7 +49,7 @@ Batch Table values can be represented in the JSON header in two different ways:
     * `componentType` is the datatype of components in the attribute. Allowed values are `"BYTE"`, `"UNSIGNED_BYTE"`, `"SHORT"`, `"UNSIGNED_SHORT"`, `"INT"`, `"UNSIGNED_INT"`, `"FLOAT"`, and `"DOUBLE"`.
     * `type` specifies if the property is a scalar or vector. Allowed values are `"SCALAR"`, `"VEC2"`, `"VEC3"`, and `"VEC4"`.
 
-The Batch Table JSON is a `UTF-8` string containing JSON. 
+The Batch Table JSON is a `UTF-8` string containing JSON.
 
 > **Implementation Note:** In JavaScript, the Batch Table JSON can be extracted from an `ArrayBuffer` using the `TextDecoder` JavaScript API and transformed to a JavaScript object with `JSON.parse`.
 
@@ -222,15 +222,15 @@ An object defining the reference to a section of the binary body of the batch ta
 
 Additional properties are allowed.
 
-#### BinaryBodyReference.byteOffset :white_check_mark: 
+#### BinaryBodyReference.byteOffset :white_check_mark:
 
 The offset into the buffer in bytes.
 
 * **Type**: `number`
 * **Required**: Yes
 * **Minimum**: ` >= 0`
 
-#### BinaryBodyReference.componentType :white_check_mark: 
+#### BinaryBodyReference.componentType :white_check_mark:
 
 The datatype of components in the property.
 
@@ -246,7 +246,7 @@ The datatype of components in the property.
    * `"FLOAT"`
    * `"DOUBLE"`
 
-#### BinaryBodyReference.type :white_check_mark: 
+#### BinaryBodyReference.type :white_check_mark:
 
 Specifies if the property is a scalar or vector.
 

specification/TileFormats/BatchTable/README.md

@@ -78,13 +78,13 @@ These semantics define global properties for all features.
 
 ## Batch Table
 
-The _Batch Table_ contains per-model application-specific metadata, indexable by `batchId`, that can be used for [declarative styling](../../Styling/README.md) and application-specific use cases such as populating a UI or issuing a REST API request.  In the binary glTF section, each vertex has an numeric `batchId` attribute in the integer range `[0, number of models in the batch - 1]`.  The `batchId` indicates the model to which the vertex belongs.  This allows models to be batched together and still be identifiable.
+The _Batch Table_ contains per-model application-specific properties, indexable by `batchId`, that can be used for [declarative styling](../../Styling/README.md) and application-specific use cases such as populating a UI or issuing a REST API request.  In the binary glTF section, each vertex has a numeric `batchId` attribute in the integer range `[0, number of models in the batch - 1]`.  The `batchId` indicates the model to which the vertex belongs.  This allows models to be batched together and still be identifiable.
 
 See the [Batch Table](../BatchTable/README.md) reference for more information.
 
 ## Binary glTF
 
-Batched 3D Model uses [glTF 2.0](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0) to embed model data.
+Batched 3D Model embeds [glTF 2.0](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0) containing model geometry and texture information.
 
 The [binary glTF](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0#binary-gltf-layout) immediately follows the Feature Table and Batch Table.  It may embed all of its geometry, texture, and animations, or it may refer to external sources for some or all of these data.
 
@@ -136,7 +136,7 @@ When a Batch Table is present or the `BATCH_LENGTH` property is greater than `0`
 
 ### Coordinate system
 
-By default embedded glTFs use a right handed coordinate system where the _y_-axis is up. For consistency with the _z_-up coordinate system of 3D Tiles, glTFs must be transformed at runtime. See [coordinate reference system](../../README.md#gltf) for more details.
+By default embedded glTFs use a right handed coordinate system where the _y_-axis is up. For consistency with the _z_-up coordinate system of 3D Tiles, glTFs must be transformed at runtime. See [glTF transforms](../../README.md#gltf-transforms) for more details.
 
 Vertex positions may be defined relative-to-center for high-precision rendering, see [Precisions, Precisions](http://help.agi.com/AGIComponents/html/BlogPrecisionsPrecisions.htm). If defined, `RTC_CENTER` specifies the center position that all vertex positions are relative to after the coordinate system transform and glTF node hierarchy transforms have been applied.
 

specification/TileFormats/Batched3DModel/README.md

@@ -12,7 +12,7 @@
 
 ## Overview
 
-A _Feature Table_ describes position and appearance properties for each feature in a tile.  The [Batch Table](../BatchTable/README.md), on the other hand, contains per-feature application-specific metadata not necessarily used for rendering.
+A _Feature Table_ is a component of a tile's binary body and describes position and appearance properties required to render each feature in a tile. The [Batch Table](../BatchTable/README.md), on the other hand, contains per-feature application-specific properties not necessarily used for rendering.
 
 A Feature Table is used by tile formats like [Batched 3D Model](../Batched3DModel/README.md) (b3dm) where each model is a feature, and [Point Cloud](../PointCloud/README.md) (pnts) where each point is a feature.
 
@@ -128,7 +128,7 @@ An object defining the reference to a section of the binary body of the features
 
 Additional properties are allowed.
 
-#### BinaryBodyReference.byteOffset :white_check_mark: 
+#### BinaryBodyReference.byteOffset :white_check_mark:
 
 The offset into the buffer in bytes.
 

specification/TileFormats/FeatureTable/README.md

@@ -118,7 +118,7 @@ Examples using these semantics can be found in the [examples section](#examples)
 
 ### Instance orientation
 
-An instance's orientation is defined by an orthonormal basis created by an `up` and `right` vector. The orientation will be transformed by the [tile transform](../../README.md#tile-transform).
+An instance's orientation is defined by an orthonormal basis created by an `up` and `right` vector. The orientation will be transformed by the [tile transform](../../README.md#tile-transforms).
 
 The `x` vector in the standard basis maps to the `right` vector in the transformed basis, and the `y` vector maps to the `up` vector.
 The `z` vector would map to a `forward` vector, but it is omitted because it will always be the cross product of `right` and `up`.
@@ -246,7 +246,7 @@ Contains metadata organized by `batchId` that can be used for declarative stylin
 
 ## glTF
 
-Instanced 3D Model uses [glTF 2.0](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0) for model data.
+Instanced 3D Model embeds [glTF 2.0](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0) containing model geometry and texture information.
 
 The glTF asset to be instanced is stored after the Feature Table and Batch Table. It may embed all of its geometry, texture, and animations, or it may refer to external sources for some or all of these data.
 
@@ -259,7 +259,8 @@ In either case, `header.gltfByteLength` contains the length of the glTF field in
 
 ### Coordinate system
 
-By default glTFs use a right handed coordinate system where the _y_-axis is up. For consistency with the _z_-up coordinate system of 3D Tiles, glTFs must be transformed at runtime. See [coordinate reference system](../../README.md#gltf) for more details.
+By default glTFs use a right handed coordinate system where the _y_-axis is up. For consistency with the _z_-up coordinate system of 3D Tiles, glTFs must be transformed at runtime. See [glTF transforms
+](../../README.md#gltf-transforms) for more details.
 
 ## File extension and MIME type