Merge pull request #302 from slchow/copyedit

Copyedit

CONTRIBUTING.md

@@ -5,7 +5,7 @@ As we add more tile formats, 3D Tiles needs to stay consistent.
 ## Terminology
 
 * Tiles are composed of `sections` such as `header` and `body`.  Sections are composed of `fields` such as `magic` and `version`.
-* "Feature" - indicates one model in a batch of models (b3dm), one instance in a collection of instances (i3dm), one point in a point cloud (pnts), one polygon in a vector tile (vctr), etc.
+* "Feature" - indicates one model in a batch of models (`b3dm`), one instance in a collection of instances (`i3dm`), one point in a point cloud (`pnts`), one polygon in a vector tile (`vctr`), etc.
 
 ## Fields
 

Styling/schema/style.condition.schema.json

@@ -3,7 +3,7 @@
     "id" : "style.condition.schema.json",
     "title" : "condition",
     "type" : "object",
-    "description" : "A series of conditions evaluated in order like a series of if...else statements that result in an expression being evaluated.",
+    "description" : "A series of conditions evaluated in order, like a series of if...else statements that result in an expression being evaluated.",
     "properties" : {
         "conditions" : {
             "type" : "array",
@@ -17,7 +17,7 @@
                 "minItems" : 2,
                 "maxItems" : 2
             },
-            "description" : "A series of boolean conditions evaluated in order.  For the first one that evaluates to true, its value, the 'result', (which is also an expression) is evaluated and returned.  Result expressions must all be the same type.  If no condition evaluates to true, the result is `undefined`.  When conditions is `undefined`, `null`, or an empty object, the result is `undefined`."
+            "description" : "A series of boolean conditions evaluated in order.  For the first one that evaluates to true, its value, the 'result' (which is also an expression), is evaluated and returned.  Result expressions must all be the same type.  If no condition evaluates to true, the result is `undefined`.  When conditions are `undefined`, `null`, or an empty object, the result is `undefined`."
         }
     },
     "additionalProperties" : false

TileFormats/Batched3DModel/README.md

@@ -6,19 +6,31 @@
 * Tom Fili, [@CesiumFili](https://twitter.com/CesiumFili)
 * Sean Lilley, [@lilleyse](https://github.com/lilleyse)
 
+## Contents
+
+* [Overview](#overview)
+* [Layout](#layout)
+* [Header](#header)
+* [Feature Table](#feature-table)
+	* [Semantics](#semantics)
+		* [Feature semantics](#feature-semantics)
+		* [Global semantics](#global-semantics)
+* [Batch Table](#batch-table)
+* [Binary glTF](#binary-gltf)
+* [File extension](#file-extension)
+* [MIME type](#mime-type)
+
 ## Overview
 
 _Batched 3D Model_ allows offline batching of heterogeneous 3D models, such as different buildings in a city, for efficient streaming to a web client for rendering and interaction.  Efficiency comes from transferring multiple models in a single request and rendering them in the least number of WebGL draw calls necessary.  Using the core 3D Tiles spec language, each model is a _feature_.
 
-Per-model properties, such as IDs, enable individual models to be identified and updated at runtime, e.g., show/hide, highlight color, etc. Properties may be used, for example, to query a web service to access metadata, such as passing a building's ID to get its address. Or a property might be referenced on-the-fly for changing a model's appearance, e.g., changing highlight color based on a property value.
+Per-model properties, such as IDs, enable individual models to be identified and updated at runtime, e.g., show/hide, highlight color, etc. Properties may be used, for example, to query a web service to access metadata, such as passing a building's ID to get its address. Or a property might be referenced on the fly for changing a model's appearance, e.g., changing highlight color based on a property value.
 
 Batched 3D Model, or just the _batch_, is a binary blob in little endian accessed in JavaScript as an `ArrayBuffer`.
 
 ## Layout
 
-A tile is composed of two sections: a header immediately followed by a body.
-
-**Figure 1**: Batched 3D Model layout (dashes indicate optional fields).
+A tile is composed of two sections: a header immediately followed by a body. The following figure shows the Batched 3D Model layout (dashes indicate optional fields):
 
 ![](figures/layout.png)
 
@@ -31,14 +43,14 @@ The 28-byte header contains the following fields:
 | `magic` | 4-byte ANSI string | `"b3dm"`.  This can be used to identify the arraybuffer as a Batched 3D Model tile. |
 | `version` | `uint32` | The version of the Batched 3D Model format. It is currently `1`. |
 | `byteLength` | `uint32` | The length of the entire tile, including the header, in bytes. |
-| `featureTableJSONByteLength` | `uint32` | The length of the feature table JSON section in bytes. Zero indicates there is no feature table. |
-| `featureTableBinaryByteLength` | `uint32` | The length of the feature table binary section in bytes. If `featureTableJSONByteLength` is zero, this will also be zero. |
-| `batchTableJSONByteLength` | `uint32` | The length of the batch table JSON section in bytes. Zero indicates there is no batch table. |
-| `batchTableBinaryByteLength` | `uint32` | The length of the batch table binary section in bytes. If `batchTableJSONByteLength` is zero, this will also be zero. |
+| `featureTableJSONByteLength` | `uint32` | The length of the Feature Table JSON section in bytes. Zero indicates there is no Feature Table. |
+| `featureTableBinaryByteLength` | `uint32` | The length of the Feature Table binary section in bytes. If `featureTableJSONByteLength` is zero, this will also be zero. |
+| `batchTableJSONByteLength` | `uint32` | The length of the Batch Table JSON section in bytes. Zero indicates there is no Batch Table. |
+| `batchTableBinaryByteLength` | `uint32` | The length of the Batch Table binary section in bytes. If `batchTableJSONByteLength` is zero, this will also be zero. |
 
 If `featureTableJSONByteLength` equals zero, the tile does not need to be rendered.
 
-The body section immediately follows the header section, and is composed of three fields: `Feature Table`, `Batch Table` and `Binary glTF`.
+The body section immediately follows the header section, and is composed of three fields: `Feature Table`, `Batch Table`, and `Binary glTF`.
 
 Code for reading the header can be found in
 [Batched3DModelTileContent](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Source/Scene/Batched3DModel3DTileContent.js)
@@ -49,15 +61,15 @@ in the Cesium implementation of 3D Tiles.
 Contains values for `b3dm` semantics.
 More information is available in the [Feature Table specification](../FeatureTable/README.md).
 
-The `b3dm` Feature Table JSON Schema is defined in [b3dm.featureTable.schema.json](../../schema/b3dm.featureTable.schema.json).
+The `b3dm` Feature Table JSON schema is defined in [b3dm.featureTable.schema.json](../../schema/b3dm.featureTable.schema.json).
 
 ### Semantics
 
-#### Feature Semantics
+#### Feature semantics
 
 There are currently no per-feature semantics.
 
-#### Global Semantics
+#### Global semantics
 
 These semantics define global properties for all features.
 
@@ -67,15 +79,15 @@ 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 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 metadata, indexable by `batchId`, that can be used for declarative styling 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.
 
 See the [Batch Table](../BatchTable/README.md) reference for more information.
 
 ## Binary glTF
 
 [glTF](https://www.khronos.org/gltf) is the runtime asset format for WebGL.  [Binary glTF](https://github.com/KhronosGroup/glTF/tree/master/extensions/Khronos/KHR_binary_glTF) is an extension defining a binary container for glTF.  Batched 3D Model uses glTF 1.0 with the [KHR_binary_glTF](https://github.com/KhronosGroup/glTF/tree/master/extensions/Khronos/KHR_binary_glTF) extension.
 
-The binary glTF 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.
+The binary glTF 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.
 
 The glTF asset must be 8-byte aligned so that glTF's byte-alignment guarantees are met. This can be done by padding the Feature Table or Batch Table if they are present.
 
@@ -85,7 +97,7 @@ batchId:  [0,   0,   0,   ..., 1,   1,   1,   ..., 2,   2,   2,   ...]
 position: [xyz, xyz, xyz, ..., xyz, xyz, xyz, ..., xyz, xyz, xyz, ...]
 normal:   [xyz, xyz, xyz, ..., xyz, xyz, xyz, ..., xyz, xyz, xyz, ...]
 ```
-Vertices do not need to be ordered by `batchId` so the following is also OK:
+Vertices do not need to be ordered by `batchId`, so the following is also OK:
 ```
 batchId:  [0,   1,   2,   ..., 2,   1,   0,   ..., 1,   2,   0,   ...]
 position: [xyz, xyz, xyz, ..., xyz, xyz, xyz, ..., xyz, xyz, xyz, ...]
@@ -121,13 +133,13 @@ When a Batch Table is present or the `BATCH_LENGTH` property is greater than `0`
 
 Although not strictly required, clients may find the glTF [CESIUM_RTC](https://github.com/KhronosGroup/glTF/tree/master/extensions/1.0/Vendor/CESIUM_RTC) extension useful for high-precision rendering.
 
-## File Extension
+## File extension
 
 `.b3dm`
 
 The file extension is optional. Valid implementations ignore it and identify a content's format by the `magic` field in its header.
 
-## MIME Type
+## MIME type
 
 _TODO, [#60](https://github.com/AnalyticalGraphicsInc/3d-tiles/issues/60)_
 

TileFormats/Composite/README.md

@@ -5,6 +5,17 @@
 * Sean Lilley, [@lilleyse](https://github.com/lilleyse)
 * Patrick Cozzi, [@pjcozzi](https://twitter.com/pjcozzi)
 
+## Contents
+
+* [Overview](#overview)
+* [Layout](#layout)
+* [Header](#header)
+* [Inner tiles](#inner-tiles)
+* [File extension](#file-extension)
+* [MIME type](#mime-type)
+* [Acknowledgments](#acknowledgments)
+* [Resources](#resources)
+
 ## Overview
 
 The _Composite_ tile format enables concatenating tiles of different formats into one tile.
@@ -17,7 +28,7 @@ A Composite is a binary blob in little endian accessed in JavaScript as an `Arra
 
 ## Layout
 
-**Figure 1**: Composite layout (dashes indicate optional fields).
+Composite layout (dashes indicate optional fields):
 
 ![](figures/layout.png)
 
@@ -34,13 +45,13 @@ The 16-byte header section contains the following fields:
 
 _TODO: code example reading header_
 
-## Inner Tiles
+## Inner tiles
 
-Inner tile fields are stored tightly packed immediately following the header section. No additional header is added on top of the tiles' preexisting headers (eg, b3dm or i3dm headers). However, the following information describes general characteristics of the existing contents of relevant files' headers to explain common information which a composite tile reader might exploit to find the boundaries of the inner tiles.
+Inner tile fields are stored tightly packed immediately following the header section. No additional header is added on top of the tiles' preexisting headers, e.g., b3dm or i3dm headers. However, the following information describes general characteristics of the existing contents of relevant files' headers to explain common information that a Composite tile reader might exploit to find the boundaries of the inner tiles:
 
 * Each tile starts with a 4-byte ANSI string, `magic`, that can be used to determine the tile format for further parsing.  See the [main 3D Tiles spec](../../README.md) for a list of tile formats.  Composite tiles can contain Composite tiles.
 * Each tile's header contains a `uint32` `byteLength`, which defines the length of the inner tile, including its header, in bytes.  This can be used to traverse the inner tiles.
-* For any tile format's version 1, the first 12-bytes of all tiles is the following fields:
+* For any tile format's version 1, the first 12 bytes of all tiles is the following fields:
 
 |Field name|Data type|Description|
 |----------|---------|-----------|
@@ -50,13 +61,13 @@ Inner tile fields are stored tightly packed immediately following the header sec
 
 Refer to the spec for each tile format for more details.
 
-## File Extension
+## File extension
 
 `.cmpt`
 
 The file extension is optional. Valid implementations ignore it and identify a content's format by the `magic` field in its header.
 
-## MIME Type
+## MIME type
 
 _TODO, [#60](https://github.com/AnalyticalGraphicsInc/3d-tiles/issues/60)_
 

TileFormats/FeatureTable/README.md

@@ -7,6 +7,14 @@
 * Dan Bagnell, [@bagnell](https://github.com/bagnell)
 * Patrick Cozzi, [@pjcozzi](https://twitter.com/pjcozzi)
 
+## Contents
+
+* [Overview](#overview)
+* [Layout](#layout)
+   * [JSON header](#json-header)
+   * [Binary body](#binary-body)
+* [Implementation notes](#implementation-notes)
+
 ## 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.
@@ -17,45 +25,41 @@ A Feature Table is used by the following tile formats:
 * [Point Cloud](../PointCloud/README.md) (pnts) - each point is a feature.
 * [Vector](../VectorData/README.md) (vctr) - each point/polyline/polygon is a feature.
 
-Per-feature properties are defined using tile-format-specific semantics defined in each tile format's specification.  For example, in _Instanced 3D Model_, `SCALE_NON_UNIFORM` defines the non-uniform scale applied to each 3D model instance.
+Per-feature properties are defined using tile format-specific semantics defined in each tile format's specification.  For example, for _Instanced 3D Model_, `SCALE_NON_UNIFORM` defines the non-uniform scale applied to each 3D model instance.
 
 ## Layout
 
-A Feature Table is composed of two parts: a JSON header and an optional binary body. The JSON property names are tile-format-specific semantics, and their values can either be defined directly in the JSON, or refer to sections in the binary body.  It is more efficient to store long numeric arrays in the binary body.
-
-**Figure 1**: Feature Table layout
+A Feature Table is composed of two parts: a JSON header and an optional binary body. The JSON property names are tile format-specific semantics, and their values can either be defined directly in the JSON, or refer to sections in the binary body.  It is more efficient to store long numeric arrays in the binary body. The following figure shows the Feature Table layout:
 
 ![feature table layout](figures/feature-table-layout.png)
 
 When a tile format includes a Feature Table, the Feature Table immediately follows the tile's header.  The header will also contain `featureTableJSONByteLength` and `featureTableBinaryByteLength` `uint32` fields, which can be used to extract each respective part of the Feature Table.
 
 Code for reading the Feature Table can be found in [Cesium3DTileFeatureTable.js](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Source/Scene/Cesium3DTileFeatureTable.js) in the Cesium implementation of 3D Tiles.
 
-## JSON Header
+### JSON header
 
-Feature Table values can be represented in the JSON header in three different ways.
+Feature Table values can be represented in the JSON header in three different ways:
 
-1. A single value or object. (e.g. `"INSTANCES_LENGTH" : 4`)
-  * This is used for global semantics like `"INSTANCES_LENGTH"`, which defines the number of model instances in an Instanced 3D Model tile.
-2. An array of values. (e.g. `"POSITION" : [1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0]`)
+1. A single value or object, e.g., `"INSTANCES_LENGTH" : 4`.
+   * This is used for global semantics like `"INSTANCES_LENGTH"`, which defines the number of model instances in an Instanced 3D Model tile.
+2. An array of values, e.g., `"POSITION" : [1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0]`.
    * This is used for per-feature semantics like `"POSITION"` in Instanced 3D Model.  Above, each `POSITION` refers to a `float32[3]` data type so there are three features: `Feature 0's position`=`(1.0, 0.0, 0.0)`, `Feature 1's position`=`(0.0, 1.0, 0.0)`, `Feature 2's position`=`(0.0, 0.0, 1.0)`.
-3. A reference to data in the binary body, denoted by an object with a `byteOffset` property. (e.g. `"SCALE" : { "byteOffset" : 24}`).
+3. A reference to data in the binary body, denoted by an object with a `byteOffset` property, e.g., `"SCALE" : { "byteOffset" : 24}`.
    * `byteOffset` is a zero-based offset relative to the start of the binary body.
-   * The semantic defines the allowed data type, e.g., when `"POSITION"` in Instanced Model refers to the binary body, the component type is `FLOAT` and the number of components is `3`.
-   * Some semantics allow for overriding the implicit `componentType`. These cases are specified in each tile format. (e.g. `"BATCH_ID" : { "byteOffset" : 24, "componentType" : "UNSIGNED_BYTE"}`).
+   * The semantic defines the allowed data type, e.g., when `"POSITION"` in Instanced 3D Model refers to the binary body, the component type is `FLOAT` and the number of components is `3`.
+   * Some semantics allow for overriding the implicit `componentType`. These cases are specified in each tile format, e.g., `"BATCH_ID" : { "byteOffset" : 24, "componentType" : "UNSIGNED_BYTE"}`.
 The only valid properties in the JSON header are the defined semantics by the tile format.  Application-specific data should be stored in the Batch Table.
 
-JSON Schema Feature Table definitions can be found in [featureTable.schema.json](../../schema/featureTable.schema.json).
-
-## Binary Body
+JSON schema Feature Table definitions can be found in [featureTable.schema.json](../../schema/featureTable.schema.json).
 
-When the JSON header includes a reference to the binary, the provided `byteOffset` is used to index into the data. 
+### Binary body
 
-**Figure 2**: Indexing into the Feature Table binary body
+When the JSON header includes a reference to the binary, the provided `byteOffset` is used to index into the data. The following figure shows indexing into the Feature Table binary body:
 
 ![feature table binary index](figures/feature-table-binary-index.png)
 
-Values can be retrieved using the number of features, `featuresLength`, the desired feature id, `featureId`, and the data type (component type and number of components) for the feature semantic.
+Values can be retrieved using the number of features, `featuresLength`; the desired feature id, `featureId`; and the data type (component type and number of components) for the feature semantic.
 
 For example, using the `POSITION` semantic, which has a `float32[3]` data type:
 
@@ -66,7 +70,7 @@ var positionArray = new Float32Array(featureTableBinary.buffer, byteOffset, feat
 var position = positionArray.subarray(featureId * 3, featureId * 3 + 3); // Using subarray creates a view into the array, and not a new array.
 ```
 
-## Implementation Notes
+## Implementation notes
 
 In JavaScript, a `TypedArray` cannot be created on data unless it is byte-aligned to the data type.
 For example, a `Float32Array` must be stored in memory such that its data begins on a byte multiple of four since each `float` contains four bytes.