@cesium/engine 7.0.0 → 8.0.0

package/Source/Scene/I3SDataProvider.js

@@ -57,6 +57,8 @@ import Resource from "../Core/Resource.js";
 import RuntimeError from "../Core/RuntimeError.js";
 import WebMercatorProjection from "../Core/WebMercatorProjection.js";
 import I3SLayer from "./I3SLayer.js";
+import I3SStatistics from "./I3SStatistics.js";
+import I3SSublayer from "./I3SSublayer.js";
 import Lerc from "lerc";
 import Rectangle from "../Core/Rectangle.js";
 
@@ -68,8 +70,30 @@ import Rectangle from "../Core/Rectangle.js";
  * @property {string} [name] The name of the I3S dataset.
  * @property {boolean} [show=true] Determines if the dataset will be shown.
  * @property {ArcGISTiledElevationTerrainProvider|Promise<ArcGISTiledElevationTerrainProvider>} [geoidTiledTerrainProvider] Tiled elevation provider describing an Earth Gravitational Model. If defined, geometry will be shifted based on the offsets given by this provider. Required to position I3S data sets with gravity-related height at the correct location.
- * @property {boolean} [traceFetches=false] Debug option. When true, log a message whenever an I3S tile is fetched.
  * @property {Cesium3DTileset.ConstructorOptions} [cesium3dTilesetOptions] Object containing options to pass to an internally created {@link Cesium3DTileset}. See {@link Cesium3DTileset} for list of valid properties. All options can be used with the exception of <code>url</code> and <code>show</code> which are overridden by values from I3SDataProvider.
+ * @property {boolean} [showFeatures=false] Determines if the features will be shown.
+ * @property {boolean} [adjustMaterialAlphaMode=false] The option to adjust the alpha mode of the material based on the transparency of the vertex color. When <code>true</code>, the alpha mode of the material (if not defined) will be set to BLEND for geometry with any transparency in the color vertex attribute.
+ * @property {boolean} [applySymbology=false] Determines if the I3S symbology will be parsed and applied for the layers.
+ * @property {boolean} [calculateNormals=false] Determines if the flat normals will be generated for I3S geometry without normals.
+ *
+ * @example
+ * // Increase LOD by reducing SSE
+ * const cesium3dTilesetOptions = {
+ *   maximumScreenSpaceError: 1,
+ * };
+ * const i3sOptions = {
+ *   cesium3dTilesetOptions: cesium3dTilesetOptions,
+ * };
+ *
+ * @example
+ * // Set a custom outline color to replace the color defined in I3S symbology
+ * const cesium3dTilesetOptions = {
+ *   outlineColor: Cesium.Color.BLUE,
+ * };
+ * const i3sOptions = {
+ *   cesium3dTilesetOptions: cesium3dTilesetOptions,
+ *   applySymbology: true,
+ * };
  */
 
 /**
@@ -122,7 +146,13 @@ function I3SDataProvider(options) {
   this._name = options.name;
   this._show = defaultValue(options.show, true);
   this._geoidTiledTerrainProvider = options.geoidTiledTerrainProvider;
-  this._traceFetches = defaultValue(options.traceFetches, false);
+  this._showFeatures = defaultValue(options.showFeatures, false);
+  this._adjustMaterialAlphaMode = defaultValue(
+    options.adjustMaterialAlphaMode,
+    false
+  );
+  this._applySymbology = defaultValue(options.applySymbology, false);
+  this._calculateNormals = defaultValue(options.calculateNormals, false);
 
   this._cesium3dTilesetOptions = defaultValue(
     options.cesium3dTilesetOptions,
@@ -130,12 +160,15 @@ function I3SDataProvider(options) {
   );
 
   this._layers = [];
+  this._sublayers = [];
   this._data = undefined;
   this._extent = undefined;
   this._geoidDataPromise = undefined;
   this._geoidDataList = undefined;
   this._decoderTaskProcessor = undefined;
   this._taskProcessorReadyPromise = undefined;
+  this._attributeStatistics = [];
+  this._layersExtent = [];
 }
 
 Object.defineProperties(I3SDataProvider.prototype, {
@@ -165,33 +198,15 @@ Object.defineProperties(I3SDataProvider.prototype, {
       Check.defined("value", value);
       //>>includeEnd('debug');
 
-      this._show = value;
-      for (let i = 0; i < this._layers.length; i++) {
-        if (defined(this._layers[i]._tileset)) {
-          this._layers[i]._tileset.show = this._show;
+      if (this._show !== value) {
+        this._show = value;
+        for (let i = 0; i < this._layers.length; i++) {
+          this._layers[i]._updateVisibility();
         }
       }
     },
   },
 
-  /**
-   * Gets or sets debugging and tracing of I3S fetches.
-   * @memberof I3SDataProvider.prototype
-   * @type {boolean}
-   */
-  traceFetches: {
-    get: function () {
-      return this._traceFetches;
-    },
-    set: function (value) {
-      //>>includeStart('debug', pragmas.debug);
-      Check.defined("value", value);
-      //>>includeEnd('debug');
-
-      this._traceFetches = value;
-    },
-  },
-
   /**
    * The terrain provider referencing the GEOID service to be used for orthometric to ellipsoidal conversion.
    * @memberof I3SDataProvider.prototype
@@ -216,6 +231,18 @@ Object.defineProperties(I3SDataProvider.prototype, {
     },
   },
 
+  /**
+   * Gets the collection of building sublayers.
+   * @memberof I3SDataProvider.prototype
+   * @type {I3SSublayer[]}
+   * @readonly
+   */
+  sublayers: {
+    get: function () {
+      return this._sublayers;
+    },
+  },
+
   /**
    * Gets the I3S data for this object.
    * @memberof I3SDataProvider.prototype
@@ -251,6 +278,54 @@ Object.defineProperties(I3SDataProvider.prototype, {
       return this._resource;
     },
   },
+
+  /**
+   * Determines if the features will be shown.
+   * @memberof I3SDataProvider.prototype
+   * @type {boolean}
+   * @readonly
+   */
+  showFeatures: {
+    get: function () {
+      return this._showFeatures;
+    },
+  },
+
+  /**
+   * Determines if the alpha mode of the material will be adjusted depending on the color vertex attribute.
+   * @memberof I3SDataProvider.prototype
+   * @type {boolean}
+   * @readonly
+   */
+  adjustMaterialAlphaMode: {
+    get: function () {
+      return this._adjustMaterialAlphaMode;
+    },
+  },
+
+  /**
+   * Determines if the I3S symbology will be parsed and applied for the layers.
+   * @memberof I3SDataProvider.prototype
+   * @type {boolean}
+   * @readonly
+   */
+  applySymbology: {
+    get: function () {
+      return this._applySymbology;
+    },
+  },
+
+  /**
+   * Determines if the flat normals will be generated for I3S geometry without normals.
+   * @memberof I3SDataProvider.prototype
+   * @type {boolean}
+   * @readonly
+   */
+  calculateNormals: {
+    get: function () {
+      return this._calculateNormals;
+    },
+  },
 });
 
 /**
@@ -335,6 +410,101 @@ I3SDataProvider.prototype.updateForPass = function (frameState, passState) {
   }
 };
 
+function buildLayerUrl(provider, layerId) {
+  const dataProviderUrl = provider.resource.getUrlComponent();
+
+  let layerUrl = "";
+  if (dataProviderUrl.match(/layers\/\d/)) {
+    layerUrl = `${dataProviderUrl}`.replace(/\/+$/, "");
+  } else {
+    // Add '/' to url if needed + `$layers/${layerId}/` if tilesetUrl not already in ../layers/[id] format
+    layerUrl = `${dataProviderUrl}`
+      .replace(/\/?$/, "/")
+      .concat(`layers/${layerId}`);
+  }
+  return layerUrl;
+}
+
+async function addLayers(provider, data, options) {
+  if (data.layerType === "Building") {
+    if (!defined(options.showFeatures)) {
+      // The Building Scene Layer requires features to be shown to support filtering
+      provider._showFeatures = true;
+    }
+    if (!defined(options.adjustMaterialAlphaMode)) {
+      // The Building Scene Layer enables transparency by default
+      provider._adjustMaterialAlphaMode = true;
+    }
+    if (!defined(options.applySymbology)) {
+      // The Building Scene Layer applies symbology by default
+      provider._applySymbology = true;
+    }
+    if (!defined(options.calculateNormals)) {
+      // The Building Scene Layer calculates flat normals by default
+      provider._calculateNormals = true;
+    }
+
+    const buildingLayerUrl = buildLayerUrl(provider, data.id);
+    if (defined(data.sublayers)) {
+      const promises = [];
+      for (let i = 0; i < data.sublayers.length; i++) {
+        const promise = I3SSublayer._fromData(
+          provider,
+          buildingLayerUrl,
+          data.sublayers[i],
+          provider
+        );
+        promises.push(promise);
+      }
+      const sublayers = await Promise.all(promises);
+      for (let i = 0; i < sublayers.length; i++) {
+        const sublayer = sublayers[i];
+        provider._sublayers.push(sublayer);
+        provider._layers.push(...sublayer._i3sLayers);
+      }
+    }
+
+    if (defined(data.statisticsHRef)) {
+      const uri = buildingLayerUrl.concat(`/${data.statisticsHRef}`);
+      const statistics = new I3SStatistics(provider, uri);
+      await statistics.load();
+      provider._attributeStatistics.push(statistics);
+    }
+
+    if (defined(data.fullExtent)) {
+      const extent = Rectangle.fromDegrees(
+        data.fullExtent.xmin,
+        data.fullExtent.ymin,
+        data.fullExtent.xmax,
+        data.fullExtent.ymax
+      );
+      provider._layersExtent.push(extent);
+    }
+  } else if (
+    data.layerType === "3DObject" ||
+    data.layerType === "IntegratedMesh"
+  ) {
+    if (
+      !defined(options.calculateNormals) &&
+      !defined(data.textureSetDefinitions)
+    ) {
+      // I3S Layers without textures should calculate flat normals by default
+      provider._calculateNormals = true;
+    }
+
+    const newLayer = new I3SLayer(provider, data, provider);
+    provider._layers.push(newLayer);
+    if (defined(newLayer._extent)) {
+      provider._layersExtent.push(newLayer._extent);
+    }
+  } else {
+    // Filter other scene layer types out
+    console.log(
+      `${data.layerType} layer ${data.name} is skipped as not supported.`
+    );
+  }
+}
+
 /**
  * Creates an I3SDataProvider. Currently supported I3S versions are 1.6 and
  * 1.7/1.8 (OGC I3S 1.2).
@@ -375,6 +545,8 @@ I3SDataProvider.fromUrl = async function (url, options) {
   options = defaultValue(options, defaultValue.EMPTY_OBJECT);
 
   const resource = Resource.createIfNeeded(url);
+  // Set a query parameter for json to avoid failure on html pages
+  resource.setQueryParameters({ f: "pjson" }, true);
   const data = await I3SDataProvider.loadJson(resource);
 
   const provider = new I3SDataProvider(options);
@@ -383,17 +555,14 @@ I3SDataProvider.fromUrl = async function (url, options) {
 
   // Success
   if (defined(data.layers)) {
+    const promises = [];
     for (let layerIndex = 0; layerIndex < data.layers.length; layerIndex++) {
-      const newLayer = new I3SLayer(
-        provider,
-        data.layers[layerIndex],
-        layerIndex
-      );
-      provider._layers.push(newLayer);
+      const promise = addLayers(provider, data.layers[layerIndex], options);
+      promises.push(promise);
     }
+    await Promise.all(promises);
   } else {
-    const newLayer = new I3SLayer(provider, data, data.id);
-    provider._layers.push(newLayer);
+    await addLayers(provider, data, options);
   }
 
   provider._computeExtent();
@@ -421,14 +590,9 @@ I3SDataProvider._fetchJson = function (resource) {
  * @private
  *
  * @param {Resource} resource The JSON resource to request
- * @param {boolean} [trace=false] Log the resource
  * @returns {Promise<object>} The fetched data
  */
-I3SDataProvider.loadJson = async function (resource, trace) {
-  if (trace) {
-    console.log("I3S FETCH:", resource.url);
-  }
-
+I3SDataProvider.loadJson = async function (resource) {
   const data = await I3SDataProvider._fetchJson(resource);
   if (defined(data.error)) {
     console.error("Failed to fetch I3S ", resource.url);
@@ -450,11 +614,20 @@ I3SDataProvider.loadJson = async function (resource, trace) {
 /**
  * @private
  */
-I3SDataProvider.prototype._loadBinary = function (resource) {
-  if (this._traceFetches) {
-    console.log("I3S FETCH:", resource.url);
+I3SDataProvider.prototype._loadBinary = async function (resource) {
+  const buffer = await resource.fetchArrayBuffer();
+  if (buffer.byteLength > 0) {
+    // Check if we have a JSON response with 404
+    const array = new Uint8Array(buffer);
+    if (array[0] === "{".charCodeAt(0)) {
+      const textContent = new TextDecoder();
+      const str = textContent.decode(buffer);
+      if (str.includes("404")) {
+        throw new RuntimeError(`Failed to load binary: ${resource.url}`);
+      }
+    }
   }
-  return resource.fetchArrayBuffer();
+  return buffer;
 };
 
 /**
@@ -593,9 +766,6 @@ async function loadGeoidData(provider) {
   const geoidTerrainProvider = provider._geoidTiledTerrainProvider;
 
   if (!defined(geoidTerrainProvider)) {
-    console.log(
-      "No Geoid Terrain service provided - no geoid conversion will be performed."
-    );
     return;
   }
 
@@ -631,18 +801,65 @@ I3SDataProvider.prototype._computeExtent = function () {
   let rectangle;
 
   // Compute the extent from all layers
-  for (let layerIndex = 0; layerIndex < this._layers.length; layerIndex++) {
-    if (defined(this._layers[layerIndex]._extent)) {
-      const layerExtent = this._layers[layerIndex]._extent;
-      if (!defined(rectangle)) {
-        rectangle = Rectangle.clone(layerExtent);
-      } else {
-        Rectangle.union(rectangle, layerExtent, rectangle);
-      }
+  for (
+    let layerIndex = 0;
+    layerIndex < this._layersExtent.length;
+    layerIndex++
+  ) {
+    const layerExtent = this._layersExtent[layerIndex];
+    if (!defined(rectangle)) {
+      rectangle = Rectangle.clone(layerExtent);
+    } else {
+      Rectangle.union(rectangle, layerExtent, rectangle);
     }
   }
 
   this._extent = rectangle;
 };
 
+/**
+ * Returns the collection of names for all available attributes
+ * @returns {string[]} The collection of attribute names
+ */
+I3SDataProvider.prototype.getAttributeNames = function () {
+  const attributes = [];
+  for (let i = 0; i < this._attributeStatistics.length; ++i) {
+    attributes.push(...this._attributeStatistics[i].names);
+  }
+  return attributes;
+};
+
+/**
+ * Returns the collection of values for the attribute with the given name
+ * @param {string} name The attribute name
+ * @returns {string[]} The collection of attribute values
+ */
+I3SDataProvider.prototype.getAttributeValues = function (name) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.defined("name", name);
+  //>>includeEnd('debug');
+
+  for (let i = 0; i < this._attributeStatistics.length; ++i) {
+    const values = this._attributeStatistics[i]._getValues(name);
+    if (defined(values)) {
+      return values;
+    }
+  }
+  return [];
+};
+
+/**
+ * Filters the drawn elements of a scene to specific attribute names and values
+ * @param {I3SNode.AttributeFilter[]} [filters=[]] The collection of attribute filters
+ * @returns {Promise<void>} A promise that is resolved when the filter is applied
+ */
+I3SDataProvider.prototype.filterByAttributes = function (filters) {
+  const promises = [];
+  for (let i = 0; i < this._layers.length; i++) {
+    const promise = this._layers[i].filterByAttributes(filters);
+    promises.push(promise);
+  }
+  return Promise.all(promises);
+};
+
 export default I3SDataProvider;

package/Source/Scene/I3SDecoder.js

@@ -45,6 +45,7 @@ async function initializeDecoder() {
  * @param {Object} defaultGeometrySchema Schema to use during decoding
  * @param {I3SGeometry} geometryData The draco encoded geometry data
  * @param {Array} [featureData] The draco encoded feature data
+ * @param {Object} [symbologyData] The rendering symbology to apply
  * @returns Promise<undefined|object> Returns a promise which resolves to the glTF result, or undefined if the task cannot be scheduled this frame.
  *
  * @exception {RuntimeError} I3S decoder could not be initialized.
@@ -53,7 +54,8 @@ I3SDecoder.decode = async function (
   url,
   defaultGeometrySchema,
   geometryData,
-  featureData
+  featureData,
+  symbologyData
 ) {
   //>>includeStart('debug', pragmas.debug);
   Check.typeOf.string("url", url);
@@ -118,6 +120,11 @@ I3SDecoder.decode = async function (
       cartographicCenter: cartographicCenter,
       cartesianCenter: cartesianCenter,
       parentRotation: parentRotation,
+      enableFeatures: geometryData._dataProvider.showFeatures,
+      splitGeometryByColorTransparency:
+        geometryData._dataProvider.adjustMaterialAlphaMode,
+      symbologyData: symbologyData,
+      calculateNormals: geometryData._dataProvider.calculateNormals,
     };
 
     return taskProcessor.scheduleTask(payload);

package/Source/Scene/I3SFeature.js

@@ -50,14 +50,11 @@ Object.defineProperties(I3SFeature.prototype, {
 
 /**
  * Loads the content.
- * @returns {Promise} A promise that is resolved when the data of the I3S feature is loaded
+ * @returns {Promise<object>} A promise that is resolved when the data of the I3S feature is loaded
  * @private
  */
 I3SFeature.prototype.load = async function () {
-  this._data = await I3SDataProvider.loadJson(
-    this._resource,
-    this._dataProvider._traceFetches
-  );
+  this._data = await I3SDataProvider.loadJson(this._resource);
   return this._data;
 };
 

package/Source/Scene/I3SField.js

@@ -1,4 +1,5 @@
 import defined from "../Core/defined.js";
+import RuntimeError from "../Core/RuntimeError.js";
 
 /**
  * This class implements an I3S Field which is custom data attached
@@ -12,6 +13,7 @@ function I3SField(parent, storageInfo) {
   this._storageInfo = storageInfo;
   this._parent = parent;
   this._dataProvider = parent._dataProvider;
+  this._loadPromise = undefined;
   const uri = `attributes/${storageInfo.key}/0`;
 
   if (defined(this._parent._nodeIndex)) {
@@ -54,9 +56,16 @@ Object.defineProperties(I3SField.prototype, {
    */
   values: {
     get: function () {
-      return defined(this._values) && defined(this._values.attributeValues)
-        ? this._values.attributeValues
-        : [];
+      if (defined(this._values)) {
+        // attribute data can be stored either as values or as object identifiers
+        if (defined(this._values.attributeValues)) {
+          return this._values.attributeValues;
+        }
+        if (defined(this._values.objectIds)) {
+          return this._values.objectIds;
+        }
+      }
+      return [];
     },
   },
   /**
@@ -92,40 +101,37 @@ function getNumericTypeSize(type) {
   return 0;
 }
 
+function getValueTypeSize(type) {
+  if (type === "String") {
+    return 1;
+  }
+  return getNumericTypeSize(type);
+}
+
+async function load(field) {
+  const data = await field._dataProvider._loadBinary(field._resource);
+  const dataView = new DataView(data);
+  field._data = data;
+  field._validateHeader(dataView);
+  const headerSize = field._parseHeader(dataView);
+  const offset = field._getBodyOffset(headerSize);
+  field._validateBody(dataView, offset);
+  field._parseBody(dataView, offset);
+}
+
 /**
  * Loads the content.
  * @returns {Promise<void>} A promise that is resolved when the field data is loaded
  */
 I3SField.prototype.load = function () {
-  const that = this;
-  return this._dataProvider._loadBinary(this._resource).then(function (data) {
-    // Check if we have a 404
-    const dataView = new DataView(data);
-    let success = true;
-    if (dataView.getUint8(0) === "{".charCodeAt(0)) {
-      const textContent = new TextDecoder();
-      const str = textContent.decode(data);
-      if (str.includes("404")) {
-        success = false;
-        console.error(`Failed to load: ${that.resource.url}`);
-      }
-    }
-
-    if (success) {
-      that._data = data;
-      let offset = that._parseHeader(dataView);
-
-      const valueSize = getNumericTypeSize(
-        that._storageInfo.attributeValues.valueType
-      );
-      if (valueSize > 0) {
-        // Values will be padded to align the addresses with the data size
-        offset = Math.ceil(offset / valueSize) * valueSize;
-      }
+  if (defined(this._loadPromise)) {
+    return this._loadPromise;
+  }
 
-      that._parseBody(dataView, offset);
-    }
+  this._loadPromise = load(this).catch(function (error) {
+    console.error(error);
   });
+  return this._loadPromise;
 };
 
 /**
@@ -217,7 +223,9 @@ I3SField.prototype._parseBody = function (dataView, offset) {
     itemIndex < this._storageInfo.ordering.length;
     itemIndex++
   ) {
-    const item = this._storageInfo.ordering[itemIndex];
+    const orderingValue = this._storageInfo.ordering[itemIndex];
+    // all strings in the ordering array correspond to the property name, except ObjectIds
+    const item = orderingValue === "ObjectIds" ? "objectIds" : orderingValue;
     const desc = this._storageInfo[item];
     if (defined(desc)) {
       this._values[item] = [];
@@ -252,4 +260,101 @@ I3SField.prototype._parseBody = function (dataView, offset) {
   }
 };
 
+/**
+ * @private
+ */
+I3SField.prototype._getBodyOffset = function (headerSize) {
+  let valueSize = 0;
+  if (defined(this._storageInfo.attributeValues)) {
+    valueSize = getNumericTypeSize(this._storageInfo.attributeValues.valueType);
+  } else if (defined(this._storageInfo.objectIds)) {
+    valueSize = getNumericTypeSize(this._storageInfo.objectIds.valueType);
+  }
+  if (valueSize > 0) {
+    // Values will be padded to align the addresses with the data size
+    return Math.ceil(headerSize / valueSize) * valueSize;
+  }
+  return headerSize;
+};
+
+/**
+ * @private
+ */
+I3SField.prototype._validateHeader = function (dataView) {
+  let headerSize = 0;
+  for (
+    let itemIndex = 0;
+    itemIndex < this._storageInfo.header.length;
+    itemIndex++
+  ) {
+    const item = this._storageInfo.header[itemIndex];
+    headerSize += getValueTypeSize(item.valueType);
+  }
+  if (dataView.byteLength < headerSize) {
+    throw new RuntimeError(
+      `Invalid attribute buffer size (field: ${this.name}, header: ${headerSize}, actual: ${dataView.byteLength})`
+    );
+  }
+};
+
+/**
+ * @private
+ */
+I3SField.prototype._validateBody = function (dataView, offset) {
+  if (!defined(this._header.count)) {
+    throw new RuntimeError(
+      `Invalid attribute buffer (field: ${this.name}, count is missing)`
+    );
+  }
+  let attributeByteCountsOffset;
+  for (
+    let itemIndex = 0;
+    itemIndex < this._storageInfo.ordering.length &&
+    offset < dataView.byteLength;
+    itemIndex++
+  ) {
+    const orderingValue = this._storageInfo.ordering[itemIndex];
+    // all strings in the ordering array correspond to the property name, except ObjectIds
+    const item = orderingValue === "ObjectIds" ? "objectIds" : orderingValue;
+    const desc = this._storageInfo[item];
+    if (defined(desc)) {
+      if (desc.valueType !== "String") {
+        if (item === "attributeByteCounts") {
+          attributeByteCountsOffset = offset;
+        }
+        const valueSize = getNumericTypeSize(desc.valueType);
+        offset += valueSize * this._header.count;
+      } else {
+        if (!defined(attributeByteCountsOffset)) {
+          throw new RuntimeError(
+            `Invalid attribute buffer (field: ${this.name}, attributeByteCounts is missing)`
+          );
+        }
+        for (
+          let index = 0;
+          index < this._header.count && offset < dataView.byteLength;
+          ++index
+        ) {
+          const parsedValue = this._parseValue(
+            dataView,
+            this._storageInfo.attributeByteCounts.valueType,
+            attributeByteCountsOffset
+          );
+          offset += parsedValue.value;
+          attributeByteCountsOffset = parsedValue.offset;
+        }
+      }
+    } else {
+      throw new RuntimeError(
+        `Invalid attribute buffer (field: ${this.name}, ${item} is missing)`
+      );
+    }
+  }
+  if (dataView.byteLength < offset) {
+    throw new RuntimeError(
+      `Invalid attribute buffer size (field: ${this.name}, expected: ${offset}, actual: ${dataView.byteLength})`
+    );
+  }
+};
+
 export default I3SField;