Merge pull request #726 from javagl/draft-1.1-spec-clarifications

Clarifications for the 1.1 specification

specification/ImplicitTiling/README.adoc

@@ -296,7 +296,7 @@ image::figures/tile-availability.png[Tile Availability]
 [#implicittiling-content-availability]
 ==== Content Availability
 
-Content availability determines which tiles have a content resource. The content resource is located using the `content.uri` template URI. If there are no tiles with a content resource, `tile.content` shall be omitted.
+Content availability determines which tiles have a content resource. The content resource is located using the template URI of the tile content. When the tile has xref:{url-specification}README.adoc#core-tile-content[multiple contents], then there is one content availability bitstream for each content. If there are no tiles with a content resource, then `tile.content` and `tile.contents` shall be omitted.
 
 Content availability has the following restrictions:
 
@@ -402,7 +402,8 @@ Content availability (`contentAvailability`) is an array of content availability
 
 Availability may be represented either as a bitstream or a constant value. `bitstream` is an integer index that identifies the buffer view containing the availability bitstream. `constant` is an integer indicating whether all of the elements are available (`1`) or all are unavailable (`0`). `availableCount` is an integer indicating how many `1` bits exist in the availability bitstream.
 
-Availability bitstreams are packed in binary using the format described in the xref:{url-specification-metadata}README.adoc#metadata-booleans[Booleans] section of the 3D Metadata Specification.
+Availability bitstreams are packed in binary using the format described in the xref:{url-specification-metadata}README.adoc#metadata-booleans[Booleans] section of the 3D Metadata Specification. Trailing bits of availability bitstreams that result from the number of nodes not being divisible by 8 shall be set to 0.
+
 
 [NOTE]
 .Example

specification/Metadata/README.adoc

@@ -70,6 +70,13 @@ Components of a schema are listed below, and implementations may define addition
 
 IDs (`id`) are unique <<metadata-identifiers,identifiers>> for a schema.
 
+[NOTE]
+.Informative
+====
+The schema ID is _required_ for each schema. The main purpose of this ID is to be able to resolve possible ambiguities. The exact mechanism for this disabiguation depends on the client application, and how the access to metadata properties is implemented. But the schema ID makes sure that a compound identifier of the form `<schema-id>.<class-name>.<property-name>` is globally unique, even when the same class name and property name appears in multiple schemas.
+====
+
+
 [#metadata-version]
 ==== Version
 

specification/README.adoc

@@ -145,7 +145,7 @@ The CRS of a tileset may be defined explicitly, as part of the <<core-metadata,t
 
 An additional <<core-tile-transforms,tile transform>> may be applied to transform a tile's local coordinate system to the parent tile's coordinate system.
 
-The <<core-region,region>> bounding volume specifies bounds using a geographic coordinate system (latitude, longitude, height), specifically, https://epsg.org/crs_4979/WGS-84.html[EPSG 4979]. The reference ellipsoid is assumed to be the same as the reference ellipsoid of the tileset.
+The <<core-region,region>> bounding volume specifies bounds using a geographic coordinate system (latitude, longitude, height). Specifically, https://epsg.org/crs_4979/WGS-84.html[EPSG 4979], but with the latitude and longitude given in _radians_ instead of _degrees_. The reference ellipsoid is assumed to be the same as the reference ellipsoid of the tileset.
 
 [#core-concepts]
 == Concepts

specification/schema/Schema/class.property.schema.json

@@ -54,7 +54,7 @@
             ]
         },
         "componentType": {
-            "description": "The datatype of the element's components. Only applicable to `SCALAR`, `VECN`, and `MATN` types.",
+            "description": "The datatype of the element's components. Required for `SCALAR`, `VECN`, and `MATN` types, and disallowed for other types.",
             "anyOf": [
                 {
                     "const": "INT8"
@@ -93,7 +93,7 @@
         },
         "enumType": {
             "type": "string",
-            "description": "Enum ID as declared in the `enums` dictionary. Required when `type` is `ENUM`."
+            "description": "Enum ID as declared in the `enums` dictionary. Required when `type` is `ENUM`. Disallowed when `type` is not `ENUM`"
         },
         "array": {
             "type": "boolean",
@@ -112,19 +112,19 @@
         },
         "offset": {
             "$ref": "definitions.schema.json#/definitions/numericValue",
-            "description": "An offset to apply to property values. Only applicable to `SCALAR`, `VECN`, and `MATN` types when the component type is `FLOAT32` or `FLOAT64`, or when the property is `normalized`."
+            "description": "An offset to apply to property values. Only applicable to `SCALAR`, `VECN`, and `MATN` types when the component type is `FLOAT32` or `FLOAT64`, or when the property is `normalized`. Not applicable to variable-length arrays."
         },
         "scale": {
             "$ref": "definitions.schema.json#/definitions/numericValue",
-            "description": "A scale to apply to property values. Only applicable to `SCALAR`, `VECN`, and `MATN` types when the component type is `FLOAT32` or `FLOAT64`, or when the property is `normalized`."
+            "description": "A scale to apply to property values. Only applicable to `SCALAR`, `VECN`, and `MATN` types when the component type is `FLOAT32` or `FLOAT64`, or when the property is `normalized`. Not applicable to variable-length arrays."
         },
         "max": {
             "$ref": "definitions.schema.json#/definitions/numericValue",
-            "description": "Maximum allowed value for the property. Only applicable to `SCALAR`, `VECN`, and `MATN` types. This is the maximum of all property values, after the transforms based on the `normalized`, `offset`, and `scale` properties have been applied."
+            "description": "Maximum allowed value for the property. Only applicable to `SCALAR`, `VECN`, and `MATN` types. This is the maximum of all property values, after the transforms based on the `normalized`, `offset`, and `scale` properties have been applied. Not applicable to variable-length arrays."
         },
         "min": {
             "$ref": "definitions.schema.json#/definitions/numericValue",
-            "description": "Minimum allowed value for the property. Only applicable to `SCALAR`, `VECN`, and `MATN` types. This is the minimum of all property values, after the transforms based on the `normalized`, `offset`, and `scale` properties have been applied."
+            "description": "Minimum allowed value for the property. Only applicable to `SCALAR`, `VECN`, and `MATN` types. This is the minimum of all property values, after the transforms based on the `normalized`, `offset`, and `scale` properties have been applied. Not applicable to variable-length arrays."
         },
         "required": {
             "type": "boolean",

specification/schema/Statistics/statistics.class.schema.json

@@ -3,7 +3,7 @@
     "$id": "statistics.class.schema.json",
     "title": "Class Statistics",
     "$ref": "rootProperty.schema.json",
-    "description": "Statistics about entities that conform to a class.",
+    "description": "Statistics about entities that conform to a class that was defined in a metadata schema.",
     "properties": {
         "count": {
             "type": "integer",

specification/schema/Statistics/statistics.schema.json

@@ -7,7 +7,7 @@
     "properties": {
         "classes": {
             "type": "object",
-            "description": "A dictionary, where each key corresponds to a class ID in the `classes` dictionary and each value is an object containing statistics about entities that conform to the class.",
+            "description": "A dictionary, where each key corresponds to a class ID in the `classes` dictionary of the metatata schema that was defined for the tileset that contains these statistics. Each value is an object containing statistics about entities that conform to the class.",
             "minProperties": 1,
             "additionalProperties": {
                 "$ref": "statistics.class.schema.json"

specification/schema/boundingVolume.schema.json

@@ -17,7 +17,7 @@
         },
         "region": {
             "type": "array",
-            "description": "An array of six numbers that define a bounding geographic region in EPSG:4979 coordinates with the order [west, south, east, north, minimum height, maximum height]. Longitudes and latitudes are in radians, and heights are in meters above (or below) the WGS84 ellipsoid.",
+            "description": "An array of six numbers that define a bounding geographic region in EPSG:4979 coordinates with the order [west, south, east, north, minimum height, maximum height]. Longitudes and latitudes are in radians. The range for latitudes is [-PI/2,PI/2]. The range for longitudes is [-PI,PI]. The value that is given as the 'south' of the region shall not be larger than the value for the 'north' of the region. The heights are in meters above (or below) the WGS84 ellipsoid. The 'minimum height' shall not be larger than the 'maximum height'.",
             "items": {
                 "type": "number"
             },
@@ -26,7 +26,7 @@
         },
         "sphere": {
             "type": "array",
-            "description": "An array of four numbers that define a bounding sphere. The first three elements define the x, y, and z values for the center of the sphere. The last element (with index 3) defines the radius in meters.",
+            "description": "An array of four numbers that define a bounding sphere. The first three elements define the x, y, and z values for the center of the sphere. The last element (with index 3) defines the radius in meters. The radius shall not be negative.",
             "items": {
                 "type": "number"
             },

specification/schema/properties.schema.json

@@ -7,11 +7,11 @@
     "properties": {
         "maximum": {
             "type": "number",
-            "description": "The maximum value of this property of all the features in the tileset."
+            "description": "The maximum value of this property of all the features in the tileset. The maximum value shall not be larger than the minimum value."
         },
         "minimum": {
             "type": "number",
-            "description": "The minimum value of this property of all the features in the tileset."
+            "description": "The minimum value of this property of all the features in the tileset. The maximum value shall not be larger than the minimum value."
         }
     },
     "required": [

specification/schema/tileset.schema.json

@@ -62,7 +62,7 @@
         },
         "extensionsRequired": {
             "type": "array",
-            "description": "Names of 3D Tiles extensions required to properly load this tileset.",
+            "description": "Names of 3D Tiles extensions required to properly load this tileset. Each element of this array shall also be contained in `extensionsUsed`.",
             "items": {
                 "type": "string"
             },