@cesium/engine 25.0.0 → 26.0.0

package/Source/Scene/Implicit3DTileContent.js

@@ -27,219 +27,225 @@ import BoundingVolumeSemantics from "./BoundingVolumeSemantics.js";
  * </p>
  * This object is normally not instantiated directly, use {@link Implicit3DTileContent.fromSubtreeJson}.
  *
- * @alias Implicit3DTileContent
- * @constructor
- *
- * @param {Cesium3DTileset} tileset The tileset this content belongs to
- * @param {Cesium3DTile} tile The tile this content belongs to.
- * @param {Resource} resource The resource for the tileset
- * @param {object} [json] The JSON object containing the subtree. Mutually exclusive with arrayBuffer.
- * @param {ArrayBuffer} [arrayBuffer] The array buffer that stores the content payload. Mutually exclusive with json.
- * @param {number} [byteOffset=0] The offset into the array buffer, if one was provided
- *
- * @exception {DeveloperError} One of json and arrayBuffer must be defined.
- *
+ * @implements Cesium3DTileContent
  * @private
  * @experimental This feature is using part of the 3D Tiles spec that is not final and is subject to change without Cesium's standard deprecation policy.
  */
-function Implicit3DTileContent(tileset, tile, resource) {
-  //>>includeStart('debug', pragmas.debug);
-  Check.defined("tile.implicitTileset", tile.implicitTileset);
-  Check.defined("tile.implicitCoordinates", tile.implicitCoordinates);
-  //>>includeEnd('debug');
-
-  const implicitTileset = tile.implicitTileset;
-  const implicitCoordinates = tile.implicitCoordinates;
-
-  this._implicitTileset = implicitTileset;
-  this._implicitCoordinates = implicitCoordinates;
-  this._implicitSubtree = undefined;
-  this._tileset = tileset;
-  this._tile = tile;
-  this._resource = resource;
-
-  this._metadata = undefined;
-
-  this.featurePropertiesDirty = false;
-  this._group = undefined;
-
-  const templateValues = implicitCoordinates.getTemplateValues();
-  const subtreeResource = implicitTileset.subtreeUriTemplate.getDerivedResource(
-    {
-      templateValues: templateValues,
-    },
-  );
-  this._url = subtreeResource.getUrlComponent(true);
-
-  this._ready = false;
-}
+class Implicit3DTileContent {
+  /**
+   * @param {Cesium3DTileset} tileset The tileset this content belongs to
+   * @param {Cesium3DTile} tile The tile this content belongs to.
+   * @param {Resource} resource The resource for the tileset
+   * @param {object} [json] The JSON object containing the subtree. Mutually exclusive with arrayBuffer.
+   * @param {ArrayBuffer} [arrayBuffer] The array buffer that stores the content payload. Mutually exclusive with json.
+   * @param {number} [byteOffset=0] The offset into the array buffer, if one was provided
+   *
+   * @exception {DeveloperError} One of json and arrayBuffer must be defined.
+   */
+  constructor(tileset, tile, resource) {
+    //>>includeStart('debug', pragmas.debug);
+    Check.defined("tile.implicitTileset", tile.implicitTileset);
+    Check.defined("tile.implicitCoordinates", tile.implicitCoordinates);
+    //>>includeEnd('debug');
+
+    const implicitTileset = tile.implicitTileset;
+    const implicitCoordinates = tile.implicitCoordinates;
+
+    this._implicitTileset = implicitTileset;
+    this._implicitCoordinates = implicitCoordinates;
+    this._implicitSubtree = undefined;
+    this._tileset = tileset;
+    this._tile = tile;
+    this._resource = resource;
+
+    this._metadata = undefined;
+
+    this.featurePropertiesDirty = false;
+    this._group = undefined;
+
+    const templateValues = implicitCoordinates.getTemplateValues();
+    const subtreeResource =
+      implicitTileset.subtreeUriTemplate.getDerivedResource({
+        templateValues: templateValues,
+      });
+    this._url = subtreeResource.getUrlComponent(true);
+
+    this._ready = false;
+  }
 
-Object.defineProperties(Implicit3DTileContent.prototype, {
-  featuresLength: {
-    get: function () {
-      return 0;
-    },
-  },
+  get featuresLength() {
+    return 0;
+  }
 
-  pointsLength: {
-    get: function () {
-      return 0;
-    },
-  },
+  get pointsLength() {
+    return 0;
+  }
 
-  trianglesLength: {
-    get: function () {
-      return 0;
-    },
-  },
+  get trianglesLength() {
+    return 0;
+  }
 
-  geometryByteLength: {
-    get: function () {
-      return 0;
-    },
-  },
+  get geometryByteLength() {
+    return 0;
+  }
 
-  texturesByteLength: {
-    get: function () {
-      return 0;
-    },
-  },
+  get texturesByteLength() {
+    return 0;
+  }
 
-  batchTableByteLength: {
-    get: function () {
-      return 0;
-    },
-  },
+  get batchTableByteLength() {
+    return 0;
+  }
 
-  innerContents: {
-    get: function () {
-      return undefined;
-    },
-  },
+  get innerContents() {
+    return undefined;
+  }
 
   /**
    * Returns true when the tile's content is ready to render; otherwise false
    *
-   * @memberof Implicit3DTileContent.prototype
    *
    * @type {boolean}
    * @readonly
    * @private
    */
-  ready: {
-    get: function () {
-      return this._ready;
-    },
-  },
+  get ready() {
+    return this._ready;
+  }
 
-  tileset: {
-    get: function () {
-      return this._tileset;
-    },
-  },
+  get tileset() {
+    return this._tileset;
+  }
 
-  tile: {
-    get: function () {
-      return this._tile;
-    },
-  },
+  get tile() {
+    return this._tile;
+  }
 
-  url: {
-    get: function () {
-      return this._url;
-    },
-  },
+  get url() {
+    return this._url;
+  }
 
   /**
    * Part of the {@link Cesium3DTileContent} interface. <code>Implicit3DTileContent</code>
    * always returns <code>undefined</code>. Only transcoded tiles have content metadata.
-   * @memberof Implicit3DTileContent.prototype
    * @private
    */
-  metadata: {
-    get: function () {
-      return undefined;
-    },
-    set: function () {
-      //>>includeStart('debug', pragmas.debug);
-      throw new DeveloperError("Implicit3DTileContent cannot have metadata");
-      //>>includeEnd('debug');
-    },
-  },
-
-  batchTable: {
-    get: function () {
-      return undefined;
-    },
-  },
+  get metadata() {
+    return undefined;
+  }
 
-  group: {
-    get: function () {
-      return this._group;
-    },
-    set: function (value) {
-      this._group = value;
-    },
-  },
-});
+  set metadata(_) {
+    //>>includeStart('debug', pragmas.debug);
+    throw new DeveloperError("Implicit3DTileContent cannot have metadata");
+    //>>includeEnd('debug');
+  }
 
-/**
- * Initialize the implicit content by parsing the subtree resource and setting
- * up a promise chain to expand the immediate subtree.
- *
- * @param {Cesium3DTileset} tileset The tileset this content belongs to
- * @param {Cesium3DTile} tile The tile this content belongs to.
- * @param {Resource} resource The resource for the tileset
- * @param {object} [json] The JSON containing the subtree. Mutually exclusive with arrayBuffer.
- * @param {ArrayBuffer} [arrayBuffer] The ArrayBuffer containing a subtree binary. Mutually exclusive with json.
- * @param {number} [byteOffset=0] The byte offset into the arrayBuffer
- * @return {Promise<Implicit3DTileContent>}
- *
- * @exception {DeveloperError} One of json and arrayBuffer must be defined.
- *
- * @private
- */
-Implicit3DTileContent.fromSubtreeJson = async function (
-  tileset,
-  tile,
-  resource,
-  json,
-  arrayBuffer,
-  byteOffset,
-) {
-  //>>includeStart('debug', pragmas.debug);
-  Check.defined("tile.implicitTileset", tile.implicitTileset);
-  Check.defined("tile.implicitCoordinates", tile.implicitCoordinates);
-  if (defined(json) === defined(arrayBuffer)) {
-    throw new DeveloperError("One of json and arrayBuffer must be defined.");
+  get batchTable() {
+    return undefined;
   }
-  //>>includeEnd('debug');
 
-  byteOffset = byteOffset ?? 0;
-  let uint8Array;
-  if (defined(arrayBuffer)) {
-    uint8Array = new Uint8Array(arrayBuffer, byteOffset);
+  get group() {
+    return this._group;
   }
 
-  const implicitTileset = tile.implicitTileset;
-  const implicitCoordinates = tile.implicitCoordinates;
+  set group(value) {
+    this._group = value;
+  }
 
-  const subtree = await ImplicitSubtree.fromSubtreeJson(
+  /**
+   * Initialize the implicit content by parsing the subtree resource and setting
+   * up a promise chain to expand the immediate subtree.
+   *
+   * @param {Cesium3DTileset} tileset The tileset this content belongs to
+   * @param {Cesium3DTile} tile The tile this content belongs to.
+   * @param {Resource} resource The resource for the tileset
+   * @param {object} [json] The JSON containing the subtree. Mutually exclusive with arrayBuffer.
+   * @param {ArrayBuffer} [arrayBuffer] The ArrayBuffer containing a subtree binary. Mutually exclusive with json.
+   * @param {number} [byteOffset=0] The byte offset into the arrayBuffer
+   * @return {Promise<Implicit3DTileContent>}
+   *
+   * @exception {DeveloperError} One of json and arrayBuffer must be defined.
+   *
+   * @private
+   */
+  static async fromSubtreeJson(
+    tileset,
+    tile,
     resource,
     json,
-    uint8Array,
-    implicitTileset,
-    implicitCoordinates,
-  );
+    arrayBuffer,
+    byteOffset,
+  ) {
+    //>>includeStart('debug', pragmas.debug);
+    Check.defined("tile.implicitTileset", tile.implicitTileset);
+    Check.defined("tile.implicitCoordinates", tile.implicitCoordinates);
+    if (defined(json) === defined(arrayBuffer)) {
+      throw new DeveloperError("One of json and arrayBuffer must be defined.");
+    }
+    //>>includeEnd('debug');
+
+    byteOffset = byteOffset ?? 0;
+    let uint8Array;
+    if (defined(arrayBuffer)) {
+      uint8Array = new Uint8Array(arrayBuffer, byteOffset);
+    }
+
+    const implicitTileset = tile.implicitTileset;
+    const implicitCoordinates = tile.implicitCoordinates;
+
+    const subtree = await ImplicitSubtree.fromSubtreeJson(
+      resource,
+      json,
+      uint8Array,
+      implicitTileset,
+      implicitCoordinates,
+    );
+
+    const content = new Implicit3DTileContent(tileset, tile, resource);
 
-  const content = new Implicit3DTileContent(tileset, tile, resource);
+    content._implicitSubtree = subtree;
+    expandSubtree(content, subtree);
+    content._ready = true;
 
-  content._implicitSubtree = subtree;
-  expandSubtree(content, subtree);
-  content._ready = true;
+    return content;
+  }
 
-  return content;
-};
+  /**
+   * Part of the {@link Cesium3DTileContent} interface.  <code>Implicit3DTileContent</code>
+   * always returns <code>false</code> since a tile of this type does not have any features.
+   * @private
+   */
+  hasProperty(batchId, name) {
+    return false;
+  }
+
+  /**
+   * Part of the {@link Cesium3DTileContent} interface.  <code>Implicit3DTileContent</code>
+   * always returns <code>undefined</code> since a tile of this type does not have any features.
+   * @private
+   */
+  getFeature(batchId) {
+    return undefined;
+  }
+
+  applyDebugSettings(enabled, color) {}
+  applyStyle(style) {}
+  update(tileset, frameState) {}
+
+  pick(ray, frameState, result) {
+    return undefined;
+  }
+
+  isDestroyed() {
+    return false;
+  }
+
+  destroy() {
+    this._implicitSubtree =
+      this._implicitSubtree && this._implicitSubtree.destroy();
+    return destroyObject(this);
+  }
+}
 
 /**
  * Expand a single subtree placeholder tile. This transcodes the subtree into
@@ -1157,47 +1163,6 @@ function makeTile(content, baseResource, tileJson, parentTile) {
   return new Cesium3DTile(content._tileset, baseResource, tileJson, parentTile);
 }
 
-/**
- * Part of the {@link Cesium3DTileContent} interface.  <code>Implicit3DTileContent</code>
- * always returns <code>false</code> since a tile of this type does not have any features.
- * @private
- */
-Implicit3DTileContent.prototype.hasProperty = function (batchId, name) {
-  return false;
-};
-
-/**
- * Part of the {@link Cesium3DTileContent} interface.  <code>Implicit3DTileContent</code>
- * always returns <code>undefined</code> since a tile of this type does not have any features.
- * @private
- */
-Implicit3DTileContent.prototype.getFeature = function (batchId) {
-  return undefined;
-};
-
-Implicit3DTileContent.prototype.applyDebugSettings = function (
-  enabled,
-  color,
-) {};
-
-Implicit3DTileContent.prototype.applyStyle = function (style) {};
-
-Implicit3DTileContent.prototype.update = function (tileset, frameState) {};
-
-Implicit3DTileContent.prototype.pick = function (ray, frameState, result) {
-  return undefined;
-};
-
-Implicit3DTileContent.prototype.isDestroyed = function () {
-  return false;
-};
-
-Implicit3DTileContent.prototype.destroy = function () {
-  this._implicitSubtree =
-    this._implicitSubtree && this._implicitSubtree.destroy();
-  return destroyObject(this);
-};
-
 // Exposed for testing
 Implicit3DTileContent._deriveBoundingBox = deriveBoundingBox;
 Implicit3DTileContent._deriveBoundingRegion = deriveBoundingRegion;

package/Source/Scene/MVTDataProvider.js

@@ -0,0 +1,147 @@
+// @ts-check
+
+import Axis from "./Axis.js";
+import Empty3DTileContent from "./Empty3DTileContent.js";
+import RuntimeError from "../Core/RuntimeError.js";
+import UrlTemplate3DTilesDataProvider from "./UrlTemplate3DTilesDataProvider.js";
+import VectorGltf3DTileContent from "./VectorGltf3DTileContent.js";
+import buildVectorGltfFromMVT from "./buildVectorGltfFromMVT.js";
+import decodeMVT from "./decodeMVT.js";
+import oneTimeWarning from "../Core/oneTimeWarning.js";
+import defined from "../Core/defined.js";
+
+/** @import Cesium3DTile from "./Cesium3DTile.js"; */
+/** @import Cesium3DTileset from "./Cesium3DTileset.js"; */
+/** @import Rectangle from "../Core/Rectangle.js"; */
+/** @import Resource from "../Core/Resource.js"; */
+
+/**
+ * A Mapbox Vector Tiles (MVT) data provider. Loads .mvt or .pbf tiles, converting tiles
+ * dynamically (at runtime) into 3D Tiles.
+ *
+ * <div class="notice">
+ * This object is normally not instantiated directly, use {@link MVTDataProvider.fromUrl}.
+ * </div>
+ *
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ */
+class MVTDataProvider extends UrlTemplate3DTilesDataProvider {
+  /**
+   * Creates an MVTDataProvider from the specified URL template and options.
+   *
+   * @param {Resource|string} url URL template, containing {z}, {x}, and {y} placeholders.
+   * @param {object} [options] Provider options.
+   * @param {number} [options.minZoom=0] Minimum zoom level represented in the generated tileset.
+   * @param {number} [options.maxZoom=14] Maximum zoom level represented in the generated tileset.
+   * @param {Rectangle} [options.extent] Optional geographic extent in radians to constrain the generated tile tree.
+   * @param {string} [options.featureIdProperty] MVT property name to use as feature ID.
+   */
+  static async fromUrl(url, options) {
+    return /** @type {Promise<MVTDataProvider>} */ (
+      super.fromUrl(url, options)
+    );
+  }
+
+  /**
+   * @returns {object}
+   * @protected
+   * @ignore
+   */
+  _createTilesetLoadOptions() {
+    return {
+      skipLevelOfDetail: false,
+      enablePick: true,
+      featureIdLabel: "featureId_0",
+      instanceFeatureIdLabel: "instanceFeatureId_0",
+    };
+  }
+
+  /**
+   * @param {Cesium3DTileset} tileset
+   * @protected
+   * @ignore
+   */
+  _configureTileset(tileset) {
+    tileset._modelUpAxis = Axis.Z;
+    tileset._modelForwardAxis = Axis.X;
+  }
+
+  /**
+   * @returns {object}
+   * @protected
+   * @ignore
+   */
+  _createCodec() {
+    const featureIdProperty = this._featureIdProperty;
+    return {
+      contentType: "mvt",
+      missingTilePolicy: { statusCodes: [404, 204] },
+
+      /**
+       * @param {Cesium3DTileset} tileset
+       * @param {Cesium3DTile} tile
+       * @param {Resource} resource
+       * @param {ArrayBuffer} arrayBuffer
+       * @ignore
+       */
+      createContent: async (tileset, tile, resource, arrayBuffer) => {
+        const decodedTile = decodeMVT(arrayBuffer);
+        const tileCoordinates = parseTileCoordinates(
+          resource.getUrlComponent(true),
+        );
+        const glb = buildVectorGltfFromMVT(decodedTile, tileCoordinates, {
+          featureIdProperty: featureIdProperty,
+        });
+        if (!defined(glb)) {
+          if (!hasAnyDecodedFeatures(decodedTile)) {
+            return new Empty3DTileContent(tileset, tile);
+          }
+          throw new RuntimeError(
+            "Decoded MVT tile did not produce vector glTF content.",
+          );
+        }
+        return VectorGltf3DTileContent.fromGltf(tileset, tile, resource, glb);
+      },
+    };
+  }
+}
+
+/**
+ * @param {string} url
+ * @returns {{tileZ:number, tileX:number, tileY:number}}
+ * @ignore
+ */
+function parseTileCoordinates(url) {
+  const match = url.match(/\/(\d+)\/(\d+)\/(\d+)(?:\.[^/?#]+)?(?:[?#]|$)/i);
+  if (!match) {
+    oneTimeWarning(
+      "MVTDataProvider.parseTileCoordinates",
+      `MVT tile URL did not match /{z}/{x}/{y} pattern. Falling back to z/x/y = 0/0/0. URL: ${url}`,
+    );
+    return { tileZ: 0, tileX: 0, tileY: 0 };
+  }
+  return {
+    tileZ: parseInt(match[1], 10),
+    tileX: parseInt(match[2], 10),
+    tileY: parseInt(match[3], 10),
+  };
+}
+
+/**
+ * @param {{layers:Array<{features:Array<*>}>}} decodedTile
+ * @returns {boolean}
+ * @ignore
+ */
+function hasAnyDecodedFeatures(decodedTile) {
+  const layers = decodedTile.layers;
+  for (let i = 0; i < layers.length; i++) {
+    if (layers[i].features.length > 0) {
+      return true;
+    }
+  }
+  return false;
+}
+
+MVTDataProvider._parseTileCoordinates = parseTileCoordinates;
+
+export default MVTDataProvider;