Add Extras to 3DTile and 3DTileset

Apps/SampleData/Cesium3DTiles/Tilesets/Tileset/tileset.json

@@ -3,6 +3,9 @@
     "version": "1.0",
     "tilesetVersion": "1.2.3"
   },
+  "extras": {
+    "name": "Sample Tileset"
+  },
   "properties": {
     "id": {
       "minimum": 0,
@@ -79,6 +82,9 @@
         "geometricError": 0,
         "content": {
           "uri": "lr.b3dm"
+        },
+        "extras": {
+          "id": "Special Tile"
         }
       },
       {

CHANGES.md

@@ -14,6 +14,7 @@ Change Log
 * Added `GeocoderViewModel.destinationFound` for specifying a function that is called upon a successful geocode.  The default behavior is to fly to the destination found by the geocoder. [#6915](https://github.com/AnalyticalGraphicsInc/cesium/pull/6915)
 * Added optional `width` and `height` to `Scene.drillPick` for specifying a search area.
 * Added `Cesium3DTileset.root` for getting the root tile of a tileset. [#6944](https://github.com/AnalyticalGraphicsInc/cesium/pull/6944)
+* Added `Cesium3DTileset.extras` and `Cesium3DTile.extras` for getting application specific metadata from 3D Tiles. [#6974](https://github.com/AnalyticalGraphicsInc/cesium/pull/6974)
 * Added `heightReference` to `BoxGraphics`, `CylinderGraphics` and `EllipsoidGraphics`, which can be used to clamp these entity types to terrain [#6932](https://github.com/AnalyticalGraphicsInc/cesium/pull/6932)
 
 ##### Fixes :wrench:

Source/Scene/Cesium3DTile.js

@@ -88,7 +88,7 @@ define([
         var contentHeader = header.content;
 
         /**
-         * The local transform of this tile
+         * The local transform of this tile.
          * @type {Matrix4}
          */
         this.transform = defined(header.transform) ? Matrix4.unpack(header.transform) : Matrix4.clone(Matrix4.IDENTITY);
@@ -100,7 +100,7 @@ define([
         this._initialTransform = Matrix4.multiply(parentInitialTransform, this.transform, new Matrix4());
 
         /**
-         * The final computed transform of this tile
+         * The final computed transform of this tile.
          * @type {Matrix4}
          * @readonly
          */
@@ -429,6 +429,22 @@ define([
             }
         },
 
+        /**
+         * Returns the <code>extras</code> property in the tileset JSON for this tile, which contains application specific metadata.
+         * Returns <code>undefined</code> if <code>extras</code> does not exist.
+         *
+         * @memberof Cesium3DTile.prototype
+         *
+         * @type {*}
+         * @readonly
+         * @see {@link https://github.com/AnalyticalGraphicsInc/3d-tiles/tree/master/specification#specifying-extensions-and-application-specific-extras|Extras in the 3D Tiles specification.}
+         */
+        extras : {
+            get : function() {
+                return this._header.extras;
+            }
+        },
+
         /**
          * Gets or sets the tile's highlight color.
          *

Source/Scene/Cesium3DTileset.js

@@ -181,6 +181,7 @@ define([
         this._selectedTilesToStyle = [];
         this._loadTimestamp = undefined;
         this._timeSinceLoad = 0.0;
+        this._extras = undefined;
 
         this._cullWithChildrenBounds = defaultValue(options.cullWithChildrenBounds, true);
         this._allTilesAdditive = true;
@@ -710,6 +711,7 @@ define([
                 that._geometricError = tilesetJson.geometricError;
                 that._extensionsUsed = tilesetJson.extensionsUsed;
                 that._gltfUpAxis = gltfUpAxis;
+                that._extras = tilesetJson.extras;
                 that._readyPromise.resolve(that);
             }).otherwise(function(error) {
                 that._readyPromise.reject(error);
@@ -1237,6 +1239,31 @@ define([
             get : function() {
                 return this._ellipsoid;
             }
+        },
+
+        /**
+         * Returns the <code>extras</code> property at the top-level of the tileset JSON, which contains application specific metadata.
+         * Returns <code>undefined</code> if <code>extras</code> does not exist.
+         *
+         * @memberof Cesium3DTileset.prototype
+         *
+         * @exception {DeveloperError} The tileset is not loaded.  Use Cesium3DTileset.readyPromise or wait for Cesium3DTileset.ready to be true.
+         *
+         * @type {*}
+         * @readonly
+         *
+         * @see {@link https://github.com/AnalyticalGraphicsInc/3d-tiles/tree/master/specification#specifying-extensions-and-application-specific-extras|Extras in the 3D Tiles specification.}
+         */
+        extras : {
+            get : function() {
+                //>>includeStart('debug', pragmas.debug);
+                if (!this.ready) {
+                    throw new DeveloperError('The tileset is not loaded.  Use Cesium3DTileset.readyPromise or wait for Cesium3DTileset.ready to be true.');
+                }
+                //>>includeEnd('debug');
+
+                return this._extras;
+            }
         }
     });
 

Specs/Data/Cesium3DTiles/Tilesets/Tileset/tileset.json

@@ -3,6 +3,9 @@
     "version": "1.0",
     "tilesetVersion": "1.2.3"
   },
+  "extras": {
+    "name": "Sample Tileset"
+  },
   "properties": {
     "id": {
       "minimum": 0,
@@ -79,6 +82,9 @@
         "geometricError": 0,
         "content": {
           "uri": "lr.b3dm"
+        },
+        "extras": {
+          "id": "Special Tile"
         }
       },
       {

Specs/Scene/Cesium3DTilesetSpec.js

@@ -2,6 +2,7 @@ defineSuite([
         'Scene/Cesium3DTileset',
         'Core/Cartesian3',
         'Core/Color',
+        'Core/defined',
         'Core/CullingVolume',
         'Core/getAbsoluteUri',
         'Core/getStringFromTypedArray',
@@ -32,6 +33,7 @@ defineSuite([
         Cesium3DTileset,
         Cartesian3,
         Color,
+        defined,
         CullingVolume,
         getAbsoluteUri,
         getStringFromTypedArray,
@@ -356,6 +358,24 @@ defineSuite([
         });
     });
 
+    it('loads tileset with extras', function() {
+        return Cesium3DTilesTester.loadTileset(scene, tilesetUrl).then(function(tileset) {
+            expect(tileset.extras).toEqual({ 'name': 'Sample Tileset' });
+            expect(tileset.root.extras).toBeUndefined();
+
+            var length = tileset.root.children.length;
+            var taggedChildren = 0;
+            for (var i = 0; i < length; ++i) {
+                if (defined(tileset.root.children[i].extras)) {
+                    expect(tileset.root.children[i].extras).toEqual({ 'id': 'Special Tile' });
+                    ++taggedChildren;
+                }
+            }
+
+            expect(taggedChildren).toEqual(1);
+        });
+    });
+
     it('gets root tile', function() {
         var tileset = scene.primitives.add(new Cesium3DTileset({
             url : tilesetUrl
@@ -423,6 +443,15 @@ defineSuite([
         }).toThrowDeveloperError();
     });
 
+    it('throws when getting extras and tileset is not ready', function() {
+        var tileset = new Cesium3DTileset({
+            url : tilesetUrl
+        });
+        expect(function() {
+            return tileset.extras;
+        }).toThrowDeveloperError();
+    });
+
     it('requests tile with invalid magic', function() {
         var invalidMagicBuffer = Cesium3DTilesTester.generateBatchedTileBuffer({
             magic : [120, 120, 120, 120]