Update glTF extensions

Author: lilleyse

extensions/2.0/Vendor/EXT_instance_features/README.md

@@ -17,11 +17,15 @@ Draft
 
 ## Dependencies
 
-Written against the glTF 2.0 specification. It depends on the [`EXT_mesh_gpu_instancing`](../EXT_mesh_gpu_instancing) extension. Each node that is extended with `EXT_instance_features` must also define an `EXT_mesh_gpu_instancing` extension object, and is invalid without this dependency.
+Written against the glTF 2.0 specification. Depends on the [`EXT_mesh_gpu_instancing`](../EXT_mesh_gpu_instancing) extension. Each node that is extended with `EXT_instance_features` must also define an `EXT_mesh_gpu_instancing` extension object, and is invalid without this dependency.
+
+## Optional vs. Required
+
+This extension is optional, meaning it should be placed in the `extensionsUsed` list, but not in the `extensionsRequired` list.
 
 ## Overview
 
-In most realtime 3D contexts, performance requirements demand minimizing the number of nodes and meshes in an asset. These requirements compete with interactivity, as applications may wish to merge static objects while still supporting interaction or inspection on those objects. A common performance optimizations is GPU instancing, using the `EXT_mesh_gpu_instancing` extension. But this does not allow to uniquely identify the instances that are created during rendering. 
+In most realtime 3D contexts, performance requirements demand minimizing the number of nodes and meshes in an asset. These requirements compete with interactivity, as applications may wish to merge static objects while still supporting interaction or inspection on those objects. A common performance optimizations is GPU instancing, using the `EXT_mesh_gpu_instancing` extension. But this does not allow uniquely identifying the instances that are created during rendering. 
 
 This extension defines a means of associating GPU instances that are created using the `EXT_mesh_gpu_instancing` extension with unique identifiers. These allow identifying the GPU instances as individual _features_, and are therefore referred to as _feature IDs_. These feature IDs are similar to the concept that is introduced in the [`EXT_mesh_features`](../EXT_mesh_features) extension. But instead of defining the feature IDs based on vertex attributes, the feature IDs are here defined using instance attributes. 
 
@@ -31,7 +35,7 @@ This extension defines a means of associating GPU instances that are created usi
 
 Feature IDs may be assigned to individual GPU instances using an instance attribute, or generated implicitly by instance index.
 
-When the feature ID definition does not refer to an instance attribute, then the feature IDs that are assigned to the instances are equal to their index, in the range [0, count), where `count` is the `count` of the instance attribute accessors. When the feature ID definition refers to an instance attribute, then this attribute contains `count` feature ID values. Note that these values do not necessarily have to be distinct; this makes it possible to define _groups_ of instances that share the same identifier. 
+When the feature ID definition does not refer to an instance attribute, then the feature IDs that are assigned to the instances are equal to their index, in the range `[0, count)`, where `count` is the `count` of the instance attribute accessors. When the feature ID definition refers to an instance attribute, then this attribute contains `count` feature ID values. Note that these values do not necessarily have to be distinct; this makes it possible to define _groups_ of instances that share the same identifier.
 
 > **Example:** A node defining instances of mesh `0`, with each instance having a feature ID in the `_FEATURE_ID_0` instance attribute.
 >
@@ -61,15 +65,57 @@ When the feature ID definition does not refer to an instance attribute, then the
 > }
 > ```
 
-## Optional vs. Required
+A feature ID set may also include the following properties:
 
-This extension is optional, meaning it should be placed in the `extensionsUsed` list, but not in the `extensionsRequired` list.
+* `nullFeatureId`: a value that indicates that a certain instance is not considered to be an identifiable object
+* `label`: an alphanumeric string used to identify feature ID sets across different glTF nodes
+* `propertyTable`: the index of a property table in the [`EXT_structural_metadata`](../EXT_structural_metadata/) extension
+
+> **Example:** A more complex example with two feature ID sets. The first feature ID set groups instanced trees into forests. The tree with feature ID `2` matches the `nullFeatureId` and therefore does not belong to a forest feature. The second feature ID set (feature ID values not shown) is defined implicitly based on instance index, and identifies individual trees. Each feature ID set refers to a property table that contains metadata about the features.
+>
+> ![Feature ID by instance](figures/trees.png)
+>
+> ```jsonc
+> {
+>   "nodes": [
+>     {
+>       "mesh": 0,
+>       "extensions": {
+>         "EXT_mesh_gpu_instancing": {
+>           "attributes": {
+>             "TRANSLATION": 0,
+>             "ROTATION": 1,
+>             "SCALE": 2,
+>             "_FEATURE_ID_0": 3
+>           },
+>         },
+>         "EXT_instance_features": {
+>           "featureIds": [
+>             {
+>               "nullFeatureId": 2,
+>               "featureCount": 2,
+>               "attribute": 0,
+>               "propertyTable": 0,
+>               "label": "Forests"
+>             },
+>             {
+>               "featureCount": 9,
+>               "propertyTable": 1,
+>               "label": "Trees"
+>             }
+>           ]
+>         }
+>       }
+>     }
+>   ]
+> }
+> ```
 
 ## Schema
 
 * [node.EXT_instance_features.schema.json](./schema/node.EXT_instance_features.schema.json)
 
 ## Revision History
 
-This extension was originally part of a the `EXT_mesh_features` proposal extension. The revision history of this extension can be found in the [common revision history of the 3D Tiles Next extensions](https://github.com/CesiumGS/3d-tiles/blob/main/next/REVISION_HISTORY.md).
+This extension was originally part of the `EXT_mesh_features` extension. The revision history of this extension can be found in the [common revision history of the 3D Tiles Next extensions](https://github.com/CesiumGS/3d-tiles/blob/main/next/REVISION_HISTORY.md).
 

extensions/2.0/Vendor/EXT_instance_features/figures/trees.png

@@ -47,7 +47,7 @@ The feature ID set may also include a `label`, an alphanumeric string used to id
 
 Feature IDs can be associated with parts of a model in one of three ways:
 
-* **Feature ID by Vertex:** Feature IDs that are stored as vertex attribute, using a standard glTF accessor. The `featureId.attribute` refers to this accessor, and allows defining feature IDs for each individual vertex.
+* **Feature ID by Vertex:** Feature IDs that are stored as a vertex attribute, using a standard glTF accessor. The `featureId.attribute` refers to this accessor, and allows defining feature IDs for each individual vertex.
 * **Feature ID by Texture Coordinates:** Feature IDs that are stored in the channels of a standard glTF texture. The `featureId.texture` refers to this texture, and allows defining feature IDs for regions on the surface of a mesh.
 * **Feature ID by Index**: Feature IDs that are assigned implicitly to the vertices. In this case, the feature ID is given by the index of the vertex.
 
@@ -89,8 +89,7 @@ Per-vertex feature IDs can be used to identify individual objects that have been
 >         "EXT_mesh_features": {
 >           "featureIds": [{
 >             "featureCount": 2,
->             "attribute": 0,
->             "label": "buildings"
+>             "attribute": 0
 >           }]
 >         }
 >       }
@@ -105,7 +104,7 @@ Per-vertex feature IDs can be used to identify individual objects that have been
 
 Feature ID textures classify the pixels of an image into different features. Some use cases include image segmentation or marking regions on a map. Often per-texel feature IDs provide finer granularity than per-vertex feature IDs, as in the example below.
 
-> **Example:** A building facade, represented by a single quad. The primitive's `baseColorTexture` displays the visible appearance of the building, and its feature ID texture identifies regions of the quad (door, roof, window) as distinct features. Texels assigned `nullFeatureId` do not belong to a feature. Both textures use the same texture coordinates, `TEXCOORD_0`, in this example.
+> **Example:** A building facade, represented by a single quad. The primitive's `baseColorTexture` displays the visible appearance of the building, and its feature ID texture identifies regions of the quad (door, roof, window) as distinct features. Both textures use the same texture coordinates, `TEXCOORD_0`, in this example. Texels assigned `nullFeatureId` do not belong to a feature. 
 >
 > <img src="figures/feature-id-by-texture.png"  alt="Feature ID Texture" width="800">
 >
@@ -122,13 +121,13 @@ Feature ID textures classify the pixels of an image into different features. Som
 >       "extensions": {
 >         "EXT_mesh_features": {
 >           "featureIds": [{
+>             "nullFeatureId": 0,
 >             "featureCount": 3,    
 >             "texture" : {
 >               "index": 0, 
 >               "texCoord": 0, 
 >               "channels": [0]
->             },
->             "nullFeatureId": 0,
+>             }
 >           }]
 >         }
 >       }
@@ -142,23 +141,23 @@ The `texture` object of a `featureId` extends the glTF [`textureInfo`](../../../
 The values from the selected channels are treated as unsigned 8 bit integers, and represent the bytes of the actual feature ID, in little-endian order. 
 
 > **Example:** 
-> If a `featureID.texture` defines `"channels": [0, 1]`, then the actual feature ID can be computed as `id = channel[0] | (channel[1] << 8);`. 
-> If a `featureID.texture` defines `"channels": [1, 0, 2]`, then the actual feature ID can be computed as `id = channel[1] | (channel[0] << 8) | (channel[2] << 16);`.
+> If a `featureID.texture` defines `"channels": [0, 1]`, then the actual feature ID can be computed as `id = channel[0] | (channel[1] << 8)`. 
+> If a `featureID.texture` defines `"channels": [1, 0, 2]`, then the actual feature ID can be computed as `id = channel[1] | (channel[0] << 8) | (channel[2] << 16)`.
 
 Texture filtering must be `9728` (NEAREST), or undefined, for any texture object referenced as a feature ID texture. Texture values must be encoded with a linear transfer function.
 
 #### Feature ID by Index
 
-When both `featureId.attribute` and `featureId.texture` are undefined,then the feature ID value for each vertex is given implicitly, via the index of the vertex. In this case, the `featureCount` must match the number of vertices of the mesh primitive. 
+When both `featureId.attribute` and `featureId.texture` are undefined, then the feature ID value for each vertex is given implicitly, via the index of the vertex. In this case, the `featureCount` must match the number of vertices of the mesh primitive. 
 
 
 ### Using Feature IDs
 
-The feature ID sets that are associated with mesh primitives can be accessed by client applications, and be used to look up addition information that is associated with these features. Two possible ways of associating features with additional information are presented here.
+The feature ID sets that are associated with mesh primitives can be accessed by client applications, and can be used to look up addition information that is associated with these features. Two possible ways of associating features with additional information are presented here.
 
 #### Referencing Property Tables with Feature IDs
 
-When combined with the `EXT_structural_metadata` extension, feature ID sets can be associated with property tables. A property table maps each feature ID to a set of values that are associated with the respective feature. The feature ID in this case serves as an _index_ for the row of the table. The index of the property table that a certain set of feature IDs is associated with is stored in the `propertyTable` of the feature ID set definition.
+When combined with the [`EXT_structural_metadata`](../EXT_structural_metadata/) extension, feature ID sets can be associated with property tables. A property table maps each feature ID to a set of values that are associated with the respective feature. The feature ID in this case serves as an _index_ for the row of the table. The index of the property table that a certain set of feature IDs is associated with is stored in the `propertyTable` of the feature ID set definition.
 
 > **Example:** This example assumes that an array of property tables is defined in the asset, using the `EXT_structural_metadata` extension. The example shows a primitive with multiple feature ID sets. The first one uses a feature ID texture that contains 4 different features. The second one is defined via a vertex attribute, and defines 2 different features. The first ID set is associated with the property table with index 1. The second one is associated with the property table with index 0. 
 >
@@ -174,12 +173,14 @@ When combined with the `EXT_structural_metadata` extension, feature ID sets can
 >           "texCoord": 0, 
 >           "channels": [0]
 >         }, 
->         "propertyTable": 1
+>         "propertyTable": 1,
+>         "label": "classification"
 >       },
 >       {
 >         "featureCount": 2,
 >         "attribute": 0,
->         "propertyTable": 0
+>         "propertyTable": 0,
+>         "label": "components"
 >       }
 >     ]
 >   }

extensions/2.0/Vendor/EXT_mesh_features/README.md

@@ -38,7 +38,6 @@ Written against the glTF 2.0 specification.
   - [Property Tables](#property-tables)
   - [Property Attributes](#property-attributes)
   - [Property Textures](#property-textures)
-    - [Property Texture Data Storage](#property-texture-data-storage)
 - [Binary Data Storage](#binary-data-storage)
 - [Optional vs. Required](#optional-vs-required)
 - [Schema](#schema-1)
@@ -75,7 +74,7 @@ A schema may be embedded in the extension directly or referenced externally with
 >   "extensions": {
 >     "EXT_structural_metadata": {
 >       "schema": {
->         "id": "schema-001",
+>         "id": "schema_001",
 >         "name": "Schema 001",
 >         "description": "An example schema.",
 >         "version": "3.5.1",
@@ -179,7 +178,7 @@ Set of categorical types, defined as `(name, value)` pairs. Enum properties use
 
 Enums are defined as entries in the `schema.enums` dictionary, indexed by an enum ID. Enum IDs must be alphanumeric identifiers matching the regular expression `^[a-zA-Z_][a-zA-Z0-9_]*$`.
 
-> **Example:** A "Species" enum defining types of trees. An "Unspecified" enum value is optional, but when provided as the `noData` value for a property (see: [3D Metadata → No Data Values](https://github.com/CesiumGS/3d-tiles/tree/main/specification/Metadata#required-properties-and-no-data-values)) may be helpful to identify missing data.
+> **Example:** A "Species" enum defining types of trees. An "Unspecified" enum value is optional, but when provided as the `noData` value for a property (see: [3D Metadata → No Data Values](https://github.com/CesiumGS/3d-tiles/tree/main/specification/Metadata#required-properties-no-data-values-and-default-values)) may be helpful to identify missing data.
 >
 > ```jsonc
 > {
@@ -217,13 +216,13 @@ Enum values are defined as entries in the `enum.values` array. Duplicate names o
 
 The classes defined in the schema are templates describing the data types and meanings of properties. An instance of such a metadata class is referred to as a _metadata entity_, and can be created from a set of values that conform to the structure of the class. This extension defines different ways of storing large amounts of property values inside a glTF asset, in compact binary forms: 
 
-- **Property Tables** store property values as parallel arrays in a column-based binary layout, using standard glTF buffer views. These tables can be accessed with a row index, and allow associating complex, structured metadata with arbitrary types with entities of a glTF asset on different levels of granularity.
-- **Property Attributes** are a way of storing metadata as vertex attributes, using standard glTF accessors. They can be used to associate certain forms of metadata with vertices of a mesh primitive. 
+- **Property Tables** store property values as parallel arrays in a column-based binary layout, using standard glTF buffer views. These tables can be accessed with a row index, and allow associating complex, structural metadata with arbitrary types with entities of a glTF asset on different levels of granularity.
+- **Property Attributes** associate vertex attributes of a mesh primitive with a particular metadata class. 
 - **Property Textures** store property values in channels of a texture, suitable for very high-frequency data mapped to less-detailed 3D surfaces. 
 
-The following sections describe these storage formats in more detail.
+Each storage type refers to a metadata class, and contains a dictionary of `properties`. Each of these properties corresponds to one property of the metadata class and defines how the actual property data is stored. These property storage definitions may override the [`minimum` and `maximum` values](https://github.com/CesiumGS/3d-tiles/tree/main/specification/Metadata#minimum-and-maximum-values) and the [`offset` and `scale`](https://github.com/CesiumGS/3d-tiles/tree/main/specification/Metadata#offset-and-scale) from the property definition in the class, to account for the actual range of values that is stored for each property.
 
-Each storage type refers to a metadata class, and contains a dictionary of `properties`. Each of these properties corresponds to one property of the metadata class. Each of these properties define the way how the actual property data is stored. These property storage definitions allow to override the [`minimum` and `maximum` values](https://github.com/CesiumGS/3d-tiles/tree/main/specification/Metadata#minimum-and-maximum-values) and the [`offset` and `scale`](https://github.com/CesiumGS/3d-tiles/tree/main/specification/Metadata#offset-and-scale) from the property definition in the class, to account for the actual range of values that is stored for each property.
+The following sections describe these storage formats in more detail.
 
 ### Property Tables
 
@@ -253,14 +252,13 @@ The property table may provide value arrays for only a subset of the properties
 >         "count": 10,
 >         "properties": {
 >           "species": {
->             "values": 2,
->             "stringOffsets": 3
+>             "values": 0,
 >           },
 >           "age": {
 >             "values": 1
 >           },
 >           "height": {
->             "values": 0
+>             "values": 2
 >           },
 >           // "diameter" is not required and has been omitted from this table.
 >         }
@@ -272,7 +270,7 @@ The property table may provide value arrays for only a subset of the properties
 
 Property arrays are stored in glTF buffer views and use the binary encoding defined in the [Binary Table Format](https://github.com/CesiumGS/3d-tiles/tree/main/specification/Metadata#binary-table-format) section of the [3D Metadata Specification](https://github.com/CesiumGS/3d-tiles/tree/main/specification/Metadata).
 
-As in the core glTF specification, values of NaN, +Infinity, and -Infinity are never allowed.
+As in the core glTF specification, values of `NaN`, `+Infinity`, and `-Infinity` are never allowed.
 
 Each buffer view `byteOffset` must be aligned to a multiple of its component size.
 
@@ -282,7 +280,7 @@ Each buffer view `byteOffset` must be aligned to a multiple of its component siz
 
 *Defined in [propertyAttribute.schema.json](./schema/propertyAttribute.schema.json).*
 
-Property attributes provide a mechanism to store property values for each vertex of a mesh primitive directly as vertex attributes. They refer to a certain class from the schema definition, via their `class` property, and contain a `properties` dictionary that defines a set of properties that conform to this class. Each property refers to an attribute that may be stored in a mesh primitive. 
+Property attributes associate vertex attributes of a mesh primitive with a metadata class. They refer to a certain class from the schema definition via their `class` property, and contain a `properties` dictionary that defines a set of properties that conform to this class. Each property refers to an attribute that may be stored in a mesh primitive. 
 
 The property types that are supported via property attributes are therefore restricted to the types that are supported by standard glTF accessors. These types are a strict subset of the types that are supported with the schema definitions in this extension.
 
@@ -485,6 +483,7 @@ Texture filtering must be `9728` (NEAREST), `9729` (LINEAR), or undefined, for a
 >   ]
 > }
 
+<!-- omit in toc -->
 #### Property Texture Data Storage
 
 Multiple channels of a property texture can be used to represent individual bytes of larger data types. The values from the selected channels represent the bytes of the actual property value, in little-endian order.
@@ -502,8 +501,8 @@ Certain property types cannot be encoded in property textures. For example, vari
 > uint8 byte1 = rgba[channels[1]];
 > uint8 byte2 = rgba[channels[2]];
 > uint8 byte3 = rgba[channels[3]];
-> int32 rawBits = byte0 | (byte1 << 8) | (byte2 << 16) | (byte3 << 24);
-> float32 value = intBitsToFloat(rawBits);
+> uint32 rawBits = byte0 | (byte1 << 8) | (byte2 << 16) | (byte3 << 24);
+> float32 value = uintBitsToFloat(rawBits);
 > ```
 > 
 > If a property has the type `VEC2` with `UIN16` components, or an array with a fixed length of 2 and `UINT16` components, then the respective property can be represented with 4 channels as well: