Adds 3DTILES_tile_metadata extension

CesiumGS · Sep 22, 2020 · d397abe · d397abe
1 parent 230b39d
commit d397abe
Show file tree

Hide file tree

Showing 4 changed files with 337 additions and 0 deletions.
diff --git a/extensions/3DTILES_tile_metadata/README.md b/extensions/3DTILES_tile_metadata/README.md
@@ -0,0 +1,202 @@
+# 3DTILES_tile_metadata
+
+## Contributors
+
+* Sam Suhag, Cesium
+* Sean Lilley, Cesium
+
+## Status
+
+Draft
+
+## Dependencies
+
+Written against the 3D Tiles 1.0 spec. This extension depends on [`3DTILES_binary_buffers`](https://github.com/CesiumGS/3d-tiles/blob/3DTILES_binary_buffers/extensions/3DTILES_binary_buffers/README.md) for storage of the binary data.
+
+## Contents
+
+  - [Overview](#overview)
+  - [Optional vs. Required](#optional-vs-required)
+  - [Schema Updates](#schema-updates)
+  - [Examples](#examples)
+
+## Overview
+
+This extension enables storage of per-tile metadata in external binary buffers.
+
+Tile metadata is indexed based on a pre-order depth-first traversal starting at `root`.
+
+When using the [`3DTILES_implicit_tiling`](https://github.com/CesiumGS/3d-tiles/blob/3DTILES_implicit_tiling/extensions/3DTILES_implicit_tiling/README.md) extension, the tile metadata is indexed according to the implicit tree traversal.
+
+## Optional vs. Required
+
+This extension is optional, meaning it should be placed in the tileset JSON top-level `extensionsUsed` list, but not in the `extensionsRequired` list.
+
+## Schema Updates
+
+`3DTILES_tile_metadata` is a property of the top-level `extensions` object that defines property types and property arrays for tile metadata. Property arrays are stored in [Apache Arrow Columnar Format 1.0](https://arrow.apache.org/docs/format/Columnar.html).
+
+There are currently no built-in semantics for property types.
+
+The full JSON schema can be found in [tileset.3DTILES_tile_metadata.schema.json](schema/tileset.3DTILES_tile_metadata.schema.json).
+
+## Examples
+
+```json
+{
+  "asset": {
+    "version": "1.0"
+  },
+  "extensionsUsed": ["3DTILES_tile_metadata", "3DTILES_binary_buffers"],
+  "extensions": {
+    "3DTILES_tile_metadata": {
+      "properties": [
+        {
+          "name": "Revision date",
+          "semantic": "_REVISION_DATE",
+          "valueType": "STRING"
+        },
+        {
+          "name": "Horizon occlusion point",
+          "semantic": "_HORIZON_OCCLUSION_POINT",
+          "valueType": "FLOAT64",
+          "elementType": "ARRAY",
+          "valuesPerElement": 3
+        }
+      ],
+      "arraysLengths": 5,
+      "propertyArrays": [
+        {
+          "bufferView": 0,
+          "offsetBufferView": 1
+        },
+        {
+          "bufferView": 2
+        }
+      ]
+    },
+    "3DTILES_binary_buffers": {
+      "bufferViews": [
+        {
+          "buffer": 0,
+          "byteOffset": 0,
+          "byteLength": 40
+        },
+        {
+          "buffer": 0,
+          "byteOffset": 40,
+          "byteLength": 24
+        }
+        {
+          "buffer": 0,
+          "byteOffset": 64,
+          "byteLength": 120
+        }
+      ],
+      "buffers": [
+        {
+          "uri": "external.bin",
+          "byteLength": 184
+        }
+      ],
+      "extras": {
+        "draftVersion": "0.0.0"
+      }
+    }
+  },
+  "geometricError": 240,
+  "root": {
+    "boundingVolume": {
+      "region": [
+        -1.3197209591796106,
+        0.6988424218,
+        -1.3196390408203893,
+        0.6989055782,
+        0,
+        88
+      ]
+    },
+    "geometricError": 70,
+    "refine": "ADD",
+    "content": {
+      "uri": "parent.b3dm",
+      "boundingVolume": {
+        "region": [
+          -1.3197004795898053,
+          0.6988582109,
+          -1.3196595204101946,
+          0.6988897891,
+          0,
+          88
+        ]
+      }
+    },
+    "children": [
+      {
+        "boundingVolume": {
+          "region": [
+            -1.3197209591796106,
+            0.6988424218,
+            -1.31968,
+            0.698874,
+            0,
+            20
+          ]
+        },
+        "geometricError": 0,
+        "content": {
+          "uri": "ll.b3dm"
+        }
+      },
+      {
+        "boundingVolume": {
+          "region": [
+            -1.31968,
+            0.6988424218,
+            -1.3196390408203893,
+            0.698874,
+            0,
+            20
+          ]
+        },
+        "geometricError": 0,
+        "content": {
+          "uri": "lr.b3dm"
+        }
+      },
+      {
+        "boundingVolume": {
+          "region": [
+            -1.31968,
+            0.698874,
+            -1.3196390408203893,
+            0.6989055782,
+            0,
+            20
+          ]
+        },
+        "geometricError": 0,
+        "content": {
+          "uri": "ur.b3dm"
+        }
+      },
+      {
+        "boundingVolume": {
+          "region": [
+            -1.3197209591796106,
+            0.698874,
+            -1.31968,
+            0.6989055782,
+            0,
+            20
+          ]
+        },
+        "geometricError": 0,
+        "content": {
+          "uri": "ul.b3dm"
+        }
+      }
+    ]
+  }
+}
+```
diff --git a/extensions/3DTILES_tile_metadata/schema/property.schema.json b/extensions/3DTILES_tile_metadata/schema/property.schema.json
@@ -0,0 +1,72 @@
+{
+    "$schema": "http://json-schema.org/draft-04/schema",
+    "title": "Property type",
+    "type": "object",
+    "description": "A property type.",
+    "properties": {
+        "name": {
+            "type": "string",
+            "minLength" : 1,
+            "description": "The name of the property, e.g. for display purposes. The string is UTF-8 encoded."
+        },
+        "semantic": {
+            "type": "string",
+            "minLength" : 1,
+            "description": "Identifies a property with a well-known meaning. The string is UTF-8 encoded."
+        },
+        "valueType": {
+            "type": "string",
+            "enum": ["BOOLEAN", "INT8", "UINT8", "INT16", "UINT16", "INT32", "UINT32", "INT64", "UINT64", "FLOAT16", "FLOAT32", "FLOAT64", "STRING", "BINARY"],
+            "description": "The value type of each element. `STRING` values are UTF-8 encoded."
+        },
+        "valueByteLength": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "A fixed-size byte length for `STRING` and `BINARY` values. When omitted, values are variable-size."
+        },
+        "elementType": {
+            "type": "string",
+            "enum": ["SINGLE", "ARRAY", "VARIABLE_SIZE_ARRAY"],
+            "default": "SINGLE",
+            "description": "The element type. This value must be `SINGLE` when `valueType` is `STRING` or `BINARY`."
+        },
+        "valuesPerElement": {
+            "type": "integer",
+            "minimum": 1,
+            "default": 1,
+            "description": "The number of values per element for `ARRAY` elements."
+        },
+        "normalized": {
+            "type": "boolean",
+            "description": "Specifies whether integer values should be normalized.",
+            "default": false
+        },
+        "max": {
+            "type": "array",
+            "description": "Maximum allowed values for property data. Only applicable for fixed-size numeric element types (`SCALAR` and `ARRAY`). Both `min` and `max` arrays have the same length. The length is determined by `valuesPerElement`. `normalized` property has no effect on array values: they always correspond to the integer values.",
+            "items": {
+                "type": "number"
+            },
+            "minItems": 1
+        },
+        "min": {
+            "type": "array",
+            "description": "Minimum allowed values for property data. Only applicable for fixed-size numeric element types (`SCALAR` and `ARRAY`). Both `min` and `max` arrays have the same length. The length is determined by `valuesPerElement`. `normalized` property has no effect on array values: they always correspond to the integer values.",
+            "items": {
+                "type": "number"
+            },
+            "minItems": 1
+        },
+        "extensions": {
+            "$ref": "extension.schema.json"
+        },
+        "extras" : {
+            "$ref": "extras.schema.json"
+        }
+    },
+    "dependencies": {
+        "valuesPerElement": [ "elementType" ]
+    },
+    "required": [ "name", "valueType"]
+  }
+
diff --git a/extensions/3DTILES_tile_metadata/schema/propertyArray.schema.json b/extensions/3DTILES_tile_metadata/schema/propertyArray.schema.json
@@ -0,0 +1,26 @@
+{
+    "$schema": "http://json-schema.org/draft-04/schema",
+    "title": "Property array",
+    "type": "object",
+    "description": "A property array containing tile data.",
+    "properties": {
+        "bufferView": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "The index of the `bufferView` containing values encoded in Apache Arrow Columnar Format 1.0 according to the property type."
+        },
+        "offsetsBufferView": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "The index of the `bufferView` containing offsets to values. Required for variable-size strings, variable-size binary values, and variable-size arrays. The offsets buffer contains `arrayLengths + 1` signed integers (32-bit or 64-bit), which encode the start position of each element in the values buffer. The string byte length, binary value byte length, or element array length is computed using the difference between the current offset and the subsequent offset. See Apache Arrow Columnar Format 1.0 for more details."
+        },
+        "extensions": {
+            "$ref": "extension.schema.json"
+        },
+        "extras" : {
+            "$ref": "extras.schema.json"
+        }
+    },
+    "required": [ "bufferView" ]
+  }
+
diff --git a/extensions/3DTILES_tile_metadata/schema/tileset.3DTILES_tile_metadata.schema.json b/extensions/3DTILES_tile_metadata/schema/tileset.3DTILES_tile_metadata.schema.json
@@ -0,0 +1,37 @@
+{
+    "$schema": "http://json-schema.org/draft-04/schema",
+    "title": "3DTILES_tile_metadata extension",
+    "type": "object",
+    "description": "3D Tiles extension that enables storage of per-tile metadata.",
+    "properties": {
+        "properties": {
+            "type": "array",
+            "description": "An array of property types.",
+            "items": {
+                "$ref": "property.schema.json"
+            },
+            "minItems": 1
+        },
+        "arrayLengths": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "The number of elements in each of the property arrays. Equal to the number of tiles in this tileset JSON."
+        },
+        "propertyArrays": {
+            "type": "array",
+            "description": "An array of property arrays containing tile data. Elements in `propertyArrays` have a one-to-one correspondence to elements in `properties`.",
+            "items": {
+                "$ref": "propertyArray.schema.json"
+            },
+            "minItems": 1
+        },
+        "extensions": {
+            "$ref": "extension.schema.json"
+        },
+        "extras" : {
+            "$ref": "extras.schema.json"
+        }
+    },
+    "required": [ "properties", "arrayLengths", "propertyArrays" ]
+  }
+