@cesium/engine 10.1.0 → 11.1.0

package/Source/Scene/Model/Extensions/Gpm/CorrelationGroup.js

@@ -0,0 +1,81 @@
+import Check from "../../../../Core/Check.js";
+
+/**
+ * @typedef {object} CorrelationGroup.ConstructorOptions
+ *
+ * Initialization options for the CorrelationGroup constructor
+ *
+ * @property {boolean[]} groupFlags Array of 3 booleans indicating if
+ * parameters delta-x delta-y delta-z used in the correlation group
+ * @property {Cartesian3} rotationThetas Rotations in milliradians
+ * about X, Y, Z axes, respectively
+ * @property {Spdcf[]} params Array of `Spdcf` (Strictly Positive-Definite
+ * Correlation Function) parameters, for the U, V, W directions, respectively
+ */
+
+/**
+ * Metadata identifying parameters using same correlation modeling and
+ * associated correlation parameters.
+ *
+ * This reflects the `correlationGroup` definition of the
+ * {@link https://nsgreg.nga.mil/csmwg.jsp|NGA_gpm_local} glTF extension.
+ *
+ * @constructor
+ * @param {CorrelationGroup.ConstructorOptions} options An object describing initialization options
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ */
+function CorrelationGroup(options) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.object("options.groupFlags", options.groupFlags);
+  Check.typeOf.object("options.rotationThetas", options.rotationThetas);
+  Check.typeOf.object("options.params", options.params);
+  //>>includeEnd('debug');
+
+  this._groupFlags = options.groupFlags;
+  this._rotationThetas = options.rotationThetas;
+  this._params = options.params;
+}
+
+Object.defineProperties(CorrelationGroup.prototype, {
+  /**
+   * Array of 3 booleans indicating if parameters delta-x delta-y delta-z
+   * used in the correlation group
+   *
+   * @memberof CorrelationGroup.prototype
+   * @type {boolean[]}
+   * @readonly
+   */
+  groupFlags: {
+    get: function () {
+      return this._groupFlags;
+    },
+  },
+
+  /**
+   * Rotations in milliradians about X, Y, Z axes, respectively
+   *
+   * @memberof CorrelationGroup.prototype
+   * @type {Cartesian3}
+   * @readonly
+   */
+  rotationThetas: {
+    get: function () {
+      return this._rotationThetas;
+    },
+  },
+
+  /**
+   * Array of 3 sets of SPDCF parameters, for the U, V, W directions, respectively
+   *
+   * @memberof CorrelationGroup.prototype
+   * @type {Spdcf[]}
+   * @readonly
+   */
+  params: {
+    get: function () {
+      return this._params;
+    },
+  },
+});
+
+export default CorrelationGroup;

package/Source/Scene/Model/Extensions/Gpm/GltfGpmLoader.js

@@ -0,0 +1,248 @@
+import Cartesian3 from "../../../../Core/Cartesian3.js";
+import Check from "../../../../Core/Check.js";
+import Matrix3 from "../../../../Core/Matrix3.js";
+import RuntimeError from "../../../../Core/RuntimeError.js";
+import AnchorPointDirect from "./AnchorPointDirect.js";
+import AnchorPointIndirect from "./AnchorPointIndirect.js";
+import CorrelationGroup from "./CorrelationGroup.js";
+import GltfGpmLocal from "./GltfGpmLocal.js";
+import Spdcf from "./Spdcf.js";
+import StorageType from "./StorageType.js";
+
+/**
+ * Loads glTF NGA_gpm_local from the root of a glTF object
+ *
+ * @alias GltfGpmLoader
+ * @constructor
+ *
+ * @param {object} options Object with the following properties:
+ * @param {object} options.gltf The glTF JSON.
+ * @param {string} [options.extension] The <code>NGA_gpm_local</code> extension object.
+ *
+ * @private
+ */
+function GltfGpmLoader() {}
+
+/**
+ * Creates a Matrix3 that describes a covariance matrix (which is
+ * symmetric) from the array containing the upper triangle, in
+ * column-major order.
+ *
+ * @param {number[]} array The input array
+ * @returns {Matrix3} The Matrix3
+ */
+function createCovarianceMatrixFromUpperTriangle(array) {
+  const covarianceMatrix = new Matrix3(
+    array[0],
+    array[1],
+    array[3],
+    array[1],
+    array[2],
+    array[4],
+    array[3],
+    array[4],
+    array[5],
+  );
+  return covarianceMatrix;
+}
+
+/**
+ * Creates an `AnchorPointDirect` from the given JSON representation
+ *
+ * @param {object} anchorPointDirectJson The input JSON
+ * @returns {AnchorPointDirect} The direct anchor point
+ */
+function createAnchorPointDirect(anchorPointDirectJson) {
+  const position = Cartesian3.fromArray(
+    anchorPointDirectJson.position,
+    0,
+    new Cartesian3(),
+  );
+  const adjustmentParams = Cartesian3.fromArray(
+    anchorPointDirectJson.adjustmentParams,
+    0,
+    new Cartesian3(),
+  );
+  const anchorPointDirect = new AnchorPointDirect({
+    position: position,
+    adjustmentParams: adjustmentParams,
+  });
+  return anchorPointDirect;
+}
+
+/**
+ * Creates an `AnchorPointIndirect` from the given JSON representation
+ *
+ * @param {object} anchorPointIndirectJson The input JSON
+ * @returns {AnchorPointIndirect} The indirect anchor point
+ */
+function createAnchorPointIndirect(anchorPointIndirectJson) {
+  const position = Cartesian3.fromArray(
+    anchorPointIndirectJson.position,
+    0,
+    new Cartesian3(),
+  );
+  const adjustmentParams = Cartesian3.fromArray(
+    anchorPointIndirectJson.adjustmentParams,
+    0,
+    new Cartesian3(),
+  );
+  const covarianceMatrix = createCovarianceMatrixFromUpperTriangle(
+    anchorPointIndirectJson.covarianceMatrix,
+  );
+  const anchorPointIndirect = new AnchorPointIndirect({
+    position: position,
+    adjustmentParams: adjustmentParams,
+    covarianceMatrix: covarianceMatrix,
+  });
+  return anchorPointIndirect;
+}
+
+/**
+ * Creates a `CorrelationGroup` from the given JSON representation
+ *
+ * @param {object} correlationGroupJson The input JSON
+ * @returns {CorrelationGroup} The correlation group
+ */
+function createCorrelationGroup(correlationGroupJson) {
+  const groupFlags = correlationGroupJson.groupFlags;
+  const rotationThetas = Cartesian3.fromArray(
+    correlationGroupJson.rotationThetas,
+    0,
+    new Cartesian3(),
+  );
+  const params = [];
+  for (const paramJson of correlationGroupJson.params) {
+    const param = new Spdcf({
+      A: paramJson.A,
+      alpha: paramJson.alpha,
+      beta: paramJson.beta,
+      T: paramJson.T,
+    });
+    params.push(param);
+  }
+  const correlationGroup = new CorrelationGroup({
+    groupFlags: groupFlags,
+    rotationThetas: rotationThetas,
+    params: params,
+  });
+  return correlationGroup;
+}
+
+/**
+ * Loads the GPM data from the given JSON that was found as the
+ * `NGA_gpm_local` extension object in the root of the glTF.
+ *
+ * @param {object} gltfGpmLocalJson The extension object
+ * @returns {GltfGpmLocal} The parsed object
+ * @throws RuntimeError When the given object contains invalid storage types.
+ * @private
+ */
+GltfGpmLoader.load = function (gltfGpmLocalJson) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.object("gltfGpmLocalJson", gltfGpmLocalJson);
+  //>>includeEnd('debug');
+
+  const storageType = gltfGpmLocalJson.storageType;
+  if (storageType === StorageType.Direct) {
+    return GltfGpmLoader.loadDirect(gltfGpmLocalJson);
+  }
+  if (storageType === StorageType.Indirect) {
+    return GltfGpmLoader.loadIndirect(gltfGpmLocalJson);
+  }
+  throw new RuntimeError(
+    `Invalid storage type in NGA_gpm_local - expected 'Direct' or 'Indirect', but found ${storageType}`,
+  );
+};
+
+/**
+ * Loads the GPM data from the given JSON that was found as the
+ * `NGA_gpm_local` extension object in the root of the glTF,
+ * assuming that the `storageType` of the given object is
+ * `StorageType.Direct`.
+ *
+ * @param {object} gltfGpmLocalJson The extension object
+ * @returns {GltfGpmLocal} The parsed object
+ * @private
+ */
+GltfGpmLoader.loadDirect = function (gltfGpmLocalJson) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.object("gltfGpmLocalJson", gltfGpmLocalJson);
+  Check.typeOf.object(
+    "gltfGpmLocalJson.anchorPointsDirect",
+    gltfGpmLocalJson.anchorPointsDirect,
+  );
+  Check.typeOf.object(
+    "gltfGpmLocalJson.covarianceDirectUpperTriangle",
+    gltfGpmLocalJson.covarianceDirectUpperTriangle,
+  );
+  //>>includeEnd('debug');
+
+  const anchorPointsDirect = [];
+  const anchorPointsDirectJson = gltfGpmLocalJson.anchorPointsDirect;
+  for (const anchorPointDirectJson of anchorPointsDirectJson) {
+    const anchorPointDirect = createAnchorPointDirect(anchorPointDirectJson);
+    anchorPointsDirect.push(anchorPointDirect);
+  }
+  const covarianceDirect = createCovarianceMatrixFromUpperTriangle(
+    gltfGpmLocalJson.covarianceDirectUpperTriangle,
+  );
+
+  const gltfGpmLocal = new GltfGpmLocal({
+    storageType: StorageType.Direct,
+    anchorPointsDirect: anchorPointsDirect,
+    covarianceDirect: covarianceDirect,
+  });
+  return gltfGpmLocal;
+};
+
+/**
+ * Loads the GPM data from the given JSON that was found as the
+ * `NGA_gpm_local` extension object in the root of the glTF,
+ * assuming that the `storageType` of the given object is
+ * `StorageType.Indirect`.
+ *
+ * @param {object} gltfGpmLocalJson The extension object
+ * @returns {GltfGpmLocal} The parsed object
+ * @private
+ */
+GltfGpmLoader.loadIndirect = function (gltfGpmLocalJson) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.object("gltfGpmLocalJson", gltfGpmLocalJson);
+  Check.typeOf.object(
+    "gltfGpmLocalJson.anchorPointsIndirect",
+    gltfGpmLocalJson.anchorPointsIndirect,
+  );
+  Check.typeOf.object(
+    "gltfGpmLocalJson.intraTileCorrelationGroups",
+    gltfGpmLocalJson.intraTileCorrelationGroups,
+  );
+  //>>includeEnd('debug');
+
+  const anchorPointsIndirect = [];
+  const anchorPointsIndirectJson = gltfGpmLocalJson.anchorPointsIndirect;
+  for (const anchorPointIndirectJson of anchorPointsIndirectJson) {
+    const anchorPointIndirect = createAnchorPointIndirect(
+      anchorPointIndirectJson,
+    );
+    anchorPointsIndirect.push(anchorPointIndirect);
+  }
+
+  const intraTileCorrelationGroupsJson =
+    gltfGpmLocalJson.intraTileCorrelationGroups;
+  const intraTileCorrelationGroups = [];
+
+  for (const correlationGroupJson of intraTileCorrelationGroupsJson) {
+    const correlationGroup = createCorrelationGroup(correlationGroupJson);
+    intraTileCorrelationGroups.push(correlationGroup);
+  }
+
+  const gltfGpmLocal = new GltfGpmLocal({
+    storageType: StorageType.Indirect,
+    anchorPointsIndirect: anchorPointsIndirect,
+    intraTileCorrelationGroups: intraTileCorrelationGroups,
+  });
+  return gltfGpmLocal;
+};
+
+export default GltfGpmLoader;

package/Source/Scene/Model/Extensions/Gpm/GltfGpmLocal.js

@@ -0,0 +1,179 @@
+import defined from "../../../../Core/defined.js";
+import Check from "../../../../Core/Check.js";
+import RuntimeError from "../../../../Core/RuntimeError.js";
+import StorageType from "./StorageType.js";
+
+/**
+ * @typedef {object} GltfGpmLocal.ConstructorOptions
+ *
+ * Initialization options for the GltfGpmLocal constructor
+ *
+ * @property {string} storageType The storage type.
+ * This must be one of the `StorageType` constants, i.e. `Direct` or `Indirect`.
+ * @property {AnchorPointIndirect[]|undefined} [anchorPointsIndirect] The indirect anchor points.
+ * This must be present if and only if the storage type is `Indirect`.
+ * @property {CorrelationGroup[]|undefined} [intraTileCorrelationGroups] The intra-tile correlation groups.
+ * This must be present if and only if the storage type is `Indirect`.
+ * @property {AnchorPointDirect[]|undefined} [anchorPointsDirect] The direct anchor points.
+ * This must be present if and only if the storage type is `Direct`.
+ * @property {Matrix3|undefined} [covarianceDirect] The covariance of anchor point parameters.
+ * This must be present if and only if the storage type is `Direct`.
+ */
+
+/**
+ * The GPM metadata for a Ground-Space Indirect implementation stored
+ * locally (i.e. a tile and/or leaf node).
+ *
+ * This reflects the root extension object of the {@link https://nsgreg.nga.mil/csmwg.jsp|NGA_gpm_local}
+ * glTF extension. When a model that contains this extension was loaded,
+ * then an object of this type can be obtained by calling
+ * ```
+ * const gltfGpmLocal = model.getExtension("NGA_gpm_local");
+ * ```
+ *
+ * The storage type determines the presence of the optional properties:
+ * <ul>
+ *  <li>
+ *   When the storage type is `StorageType.Indirect`, then the
+ *   `anchorPointsIndirect` and `intraTileCorrelationGroups`
+ *   are present.
+ *  </li>
+ *  <li>
+ *   When the storage type is `StorageType.Direct`, then the
+ *   `anchorPointsDirect` and `covarianceDirect` are present.
+ *  </li>
+ * </ul>
+ *
+ * @constructor
+ * @param {GltfGpmLocal.ConstructorOptions} options An object describing initialization options
+ *
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ */
+function GltfGpmLocal(options) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.string("options.storageType", options.storageType);
+  //>>includeEnd('debug');
+
+  this._storageType = options.storageType;
+  this._anchorPointsIndirect = options.anchorPointsIndirect;
+  this._anchorPointsDirect = options.anchorPointsDirect;
+  this._intraTileCorrelationGroups = options.intraTileCorrelationGroups;
+  this._covarianceDirect = options.covarianceDirect;
+
+  //>>includeStart('debug', pragmas.debug);
+  if (this.storageType === StorageType.Indirect) {
+    if (!defined(this.anchorPointsIndirect)) {
+      throw new RuntimeError(
+        "The anchorPointsIndirect are required for 'Indirect' storage",
+      );
+    }
+    if (!defined(this.intraTileCorrelationGroups)) {
+      throw new RuntimeError(
+        "The intraTileCorrelationGroups are required for 'Indirect' storage",
+      );
+    }
+    if (defined(this.anchorPointsDirect)) {
+      throw new RuntimeError(
+        "The anchorPointsDirect must be omitted for 'Indirect' storage",
+      );
+    }
+    if (defined(this.covarianceDirect)) {
+      throw new RuntimeError(
+        "The covarianceDirect must be omitted for 'Indirect' storage",
+      );
+    }
+  } else {
+    // Direct storage
+    if (!defined(this.anchorPointsDirect)) {
+      throw new RuntimeError(
+        "The anchorPointsDirect are required for 'Direct' storage",
+      );
+    }
+    if (!defined(this.covarianceDirect)) {
+      throw new RuntimeError(
+        "The covarianceDirect is required for 'Direct' storage",
+      );
+    }
+    if (defined(this.anchorPointsIndirect)) {
+      throw new RuntimeError(
+        "The anchorPointsIndirect must be omitted for 'Direct' storage",
+      );
+    }
+    if (defined(this.intraTileCorrelationGroups)) {
+      throw new RuntimeError(
+        "The intraTileCorrelationGroups must be omitted for 'Direct' storage",
+      );
+    }
+  }
+  //>>includeEnd('debug');
+}
+
+Object.defineProperties(GltfGpmLocal.prototype, {
+  /**
+   * Specifies if covariance storage is indirect or direct.
+   *
+   * @memberof GltfGpmLocal.prototype
+   * @type {StorageType}
+   * @readonly
+   */
+  storageType: {
+    get: function () {
+      return this._storageType;
+    },
+  },
+
+  /**
+   * Array of stored indirect anchor points
+   *
+   * @memberof GltfGpmLocal.prototype
+   * @type {AnchorPointIndirect[]|undefined}
+   * @readonly
+   */
+  anchorPointsIndirect: {
+    get: function () {
+      return this._anchorPointsIndirect;
+    },
+  },
+
+  /**
+   * Array of stored direct anchor points
+   *
+   * @memberof GltfGpmLocal.prototype
+   * @type {AnchorPointDirect[]|undefined}
+   * @readonly
+   */
+  anchorPointsDirect: {
+    get: function () {
+      return this._anchorPointsDirect;
+    },
+  },
+
+  /**
+   * Metadata identifying parameters using same correlation modeling and
+   * associated correlation parameters
+   *
+   * @memberof GltfGpmLocal.prototype
+   * @type {CorrelationGroup[]|undefined}
+   * @readonly
+   */
+  intraTileCorrelationGroups: {
+    get: function () {
+      return this._intraTileCorrelationGroups;
+    },
+  },
+
+  /**
+   * The full covariance of anchor point parameters
+   *
+   * @memberof GltfGpmLocal.prototype
+   * @type {Matrix3|undefined}
+   * @readonly
+   */
+  covarianceDirect: {
+    get: function () {
+      return this._covarianceDirect;
+    },
+  },
+});
+
+export default GltfGpmLocal;