@cesium/engine 0.1.0

package/Source/Core/sampleTerrain.js

@@ -0,0 +1,257 @@
+import Check from "./Check.js";
+
+/**
+ * Initiates a terrain height query for an array of {@link Cartographic} positions by
+ * requesting tiles from a terrain provider, sampling, and interpolating.  The interpolation
+ * matches the triangles used to render the terrain at the specified level.  The query
+ * happens asynchronously, so this function returns a promise that is resolved when
+ * the query completes.  Each point height is modified in place.  If a height can not be
+ * determined because no terrain data is available for the specified level at that location,
+ * or another error occurs, the height is set to undefined.  As is typical of the
+ * {@link Cartographic} type, the supplied height is a height above the reference ellipsoid
+ * (such as {@link Ellipsoid.WGS84}) rather than an altitude above mean sea level.  In other
+ * words, it will not necessarily be 0.0 if sampled in the ocean. This function needs the
+ * terrain level of detail as input, if you need to get the altitude of the terrain as precisely
+ * as possible (i.e. with maximum level of detail) use {@link sampleTerrainMostDetailed}.
+ *
+ * @function sampleTerrain
+ *
+ * @param {TerrainProvider} terrainProvider The terrain provider from which to query heights.
+ * @param {Number} level The terrain level-of-detail from which to query terrain heights.
+ * @param {Cartographic[]} positions The positions to update with terrain heights.
+ * @returns {Promise.<Cartographic[]>} A promise that resolves to the provided list of positions when terrain the query has completed.
+ *
+ * @see sampleTerrainMostDetailed
+ *
+ * @example
+ * // Query the terrain height of two Cartographic positions
+ * const terrainProvider = Cesium.createWorldTerrain();
+ * const positions = [
+ *     Cesium.Cartographic.fromDegrees(86.925145, 27.988257),
+ *     Cesium.Cartographic.fromDegrees(87.0, 28.0)
+ * ];
+ * const promise = Cesium.sampleTerrain(terrainProvider, 11, positions);
+ * Promise.resolve(promise).then(function(updatedPositions) {
+ *     // positions[0].height and positions[1].height have been updated.
+ *     // updatedPositions is just a reference to positions.
+ * });
+ */
+function sampleTerrain(terrainProvider, level, positions) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.object("terrainProvider", terrainProvider);
+  Check.typeOf.number("level", level);
+  Check.defined("positions", positions);
+  //>>includeEnd('debug');
+
+  return terrainProvider.readyPromise.then(function () {
+    return doSampling(terrainProvider, level, positions);
+  });
+}
+
+/**
+ * @param {Array.<Object>} tileRequests The mutated list of requests, the first one will be attempted
+ * @param {Array.<Promise<void>>} results The list to put the result promises into
+ * @returns {boolean} true if the request was made, and we are okay to attempt the next item immediately,
+ *  or false if we were throttled and should wait awhile before retrying.
+ *
+ * @private
+ */
+function attemptConsumeNextQueueItem(tileRequests, results) {
+  const tileRequest = tileRequests[0];
+  const requestPromise = tileRequest.terrainProvider.requestTileGeometry(
+    tileRequest.x,
+    tileRequest.y,
+    tileRequest.level
+  );
+
+  if (!requestPromise) {
+    // getting back undefined instead of a promise indicates we should retry a bit later
+    return false;
+  }
+
+  const promise = requestPromise
+    .then(createInterpolateFunction(tileRequest))
+    .catch(createMarkFailedFunction(tileRequest));
+
+  // remove the request we've just done from the queue
+  //  and add its promise result to the result list
+  tileRequests.shift();
+  results.push(promise);
+
+  // indicate we should synchronously attempt the next request as well
+  return true;
+}
+
+/**
+ * Wrap window.setTimeout in a Promise
+ * @param {number} ms
+ * @private
+ */
+function delay(ms) {
+  return new Promise(function (res) {
+    setTimeout(res, ms);
+  });
+}
+
+/**
+ * Recursively consumes all the tileRequests until the list has been emptied
+ *  and a Promise of each result has been put into the results list
+ * @param {Array.<Object>} tileRequests The list of requests desired to be made
+ * @param {Array.<Promise<void>>} results The list to put all the result promises into
+ * @returns {Promise<void>} A promise which resolves once all requests have been started
+ *
+ * @private
+ */
+function drainTileRequestQueue(tileRequests, results) {
+  // nothing left to do
+  if (!tileRequests.length) {
+    return Promise.resolve();
+  }
+
+  // consume an item from the queue, which will
+  //  mutate the request and result lists, and return true if we should
+  //  immediately attempt to consume the next item as well
+  const success = attemptConsumeNextQueueItem(tileRequests, results);
+  if (success) {
+    return drainTileRequestQueue(tileRequests, results);
+  }
+
+  // wait a small fixed amount of time first, before retrying the same request again
+  return delay(100).then(() => {
+    return drainTileRequestQueue(tileRequests, results);
+  });
+}
+
+function doSampling(terrainProvider, level, positions) {
+  const tilingScheme = terrainProvider.tilingScheme;
+
+  let i;
+
+  // Sort points into a set of tiles
+  const tileRequests = []; // Result will be an Array as it's easier to work with
+  const tileRequestSet = {}; // A unique set
+  for (i = 0; i < positions.length; ++i) {
+    const xy = tilingScheme.positionToTileXY(positions[i], level);
+    const key = xy.toString();
+
+    if (!tileRequestSet.hasOwnProperty(key)) {
+      // When tile is requested for the first time
+      const value = {
+        x: xy.x,
+        y: xy.y,
+        level: level,
+        tilingScheme: tilingScheme,
+        terrainProvider: terrainProvider,
+        positions: [],
+      };
+      tileRequestSet[key] = value;
+      tileRequests.push(value);
+    }
+
+    // Now append to array of points for the tile
+    tileRequestSet[key].positions.push(positions[i]);
+  }
+
+  // create our list of result promises to be filled
+  const tilePromises = [];
+  return drainTileRequestQueue(tileRequests, tilePromises).then(function () {
+    // now all the required requests have been started
+    //  we just wait for them all to finish
+    return Promise.all(tilePromises).then(function () {
+      return positions;
+    });
+  });
+}
+
+/**
+ * Calls {@link TerrainData#interpolateHeight} on a given {@link TerrainData} for a given {@link Cartographic} and
+ *  will assign the height property if the return value is not undefined.
+ *
+ * If the return value is false; it's suggesting that you should call {@link TerrainData#createMesh} first.
+ * @param {Cartographic} position The position to interpolate for and assign the height value to
+ * @param {TerrainData} terrainData
+ * @param {Rectangle} rectangle
+ * @returns {Boolean} If the height was actually interpolated and assigned
+ * @private
+ */
+function interpolateAndAssignHeight(position, terrainData, rectangle) {
+  const height = terrainData.interpolateHeight(
+    rectangle,
+    position.longitude,
+    position.latitude
+  );
+  if (height === undefined) {
+    // if height comes back as undefined, it may implicitly mean the terrain data
+    //  requires us to call TerrainData.createMesh() first (ArcGIS requires this in particular)
+    //  so we'll return false and do that next!
+    return false;
+  }
+  position.height = height;
+  return true;
+}
+
+function createInterpolateFunction(tileRequest) {
+  const tilePositions = tileRequest.positions;
+  const rectangle = tileRequest.tilingScheme.tileXYToRectangle(
+    tileRequest.x,
+    tileRequest.y,
+    tileRequest.level
+  );
+  return function (terrainData) {
+    let isMeshRequired = false;
+    for (let i = 0; i < tilePositions.length; ++i) {
+      const position = tilePositions[i];
+      const isHeightAssigned = interpolateAndAssignHeight(
+        position,
+        terrainData,
+        rectangle
+      );
+      // we've found a position which returned undefined - hinting to us
+      //  that we probably need to create a mesh for this terrain data.
+      // so break out of this loop and create the mesh - then we'll interpolate all the heights again
+      if (!isHeightAssigned) {
+        isMeshRequired = true;
+        break;
+      }
+    }
+
+    if (!isMeshRequired) {
+      // all position heights were interpolated - we don't need the mesh
+      return Promise.resolve();
+    }
+
+    // create the mesh - and interpolate all the positions again
+    // note: terrain exaggeration is not passed in - we are only interested in the raw data
+    return terrainData
+      .createMesh({
+        tilingScheme: tileRequest.tilingScheme,
+        x: tileRequest.x,
+        y: tileRequest.y,
+        level: tileRequest.level,
+        // don't throttle this mesh creation because we've asked to sample these points;
+        //  so sample them! We don't care how many tiles that is!
+        throttle: false,
+      })
+      .then(function () {
+        // mesh has been created - so go through every position (maybe again)
+        //  and re-interpolate the heights - presumably using the mesh this time
+        for (let i = 0; i < tilePositions.length; ++i) {
+          const position = tilePositions[i];
+          // if it doesn't work this time - that's fine, we tried.
+          interpolateAndAssignHeight(position, terrainData, rectangle);
+        }
+      });
+  };
+}
+
+function createMarkFailedFunction(tileRequest) {
+  const tilePositions = tileRequest.positions;
+  return function () {
+    for (let i = 0; i < tilePositions.length; ++i) {
+      const position = tilePositions[i];
+      position.height = undefined;
+    }
+  };
+}
+
+export default sampleTerrain;

package/Source/Core/sampleTerrainMostDetailed.js

@@ -0,0 +1,117 @@
+import Cartesian2 from "./Cartesian2.js";
+import defined from "./defined.js";
+import DeveloperError from "./DeveloperError.js";
+import sampleTerrain from "./sampleTerrain.js";
+
+const scratchCartesian2 = new Cartesian2();
+
+/**
+ * Initiates a sampleTerrain() request at the maximum available tile level for a terrain dataset.
+ *
+ * @function sampleTerrainMostDetailed
+ *
+ * @param {TerrainProvider} terrainProvider The terrain provider from which to query heights.
+ * @param {Cartographic[]} positions The positions to update with terrain heights.
+ * @returns {Promise.<Cartographic[]>} A promise that resolves to the provided list of positions when terrain the query has completed.  This
+ *                                     promise will reject if the terrain provider's `availability` property is undefined.
+ *
+ * @example
+ * // Query the terrain height of two Cartographic positions
+ * const terrainProvider = Cesium.createWorldTerrain();
+ * const positions = [
+ *     Cesium.Cartographic.fromDegrees(86.925145, 27.988257),
+ *     Cesium.Cartographic.fromDegrees(87.0, 28.0)
+ * ];
+ * const promise = Cesium.sampleTerrainMostDetailed(terrainProvider, positions);
+ * Promise.resolve(promise).then(function(updatedPositions) {
+ *     // positions[0].height and positions[1].height have been updated.
+ *     // updatedPositions is just a reference to positions.
+ * });
+ */
+function sampleTerrainMostDetailed(terrainProvider, positions) {
+  //>>includeStart('debug', pragmas.debug);
+  if (!defined(terrainProvider)) {
+    throw new DeveloperError("terrainProvider is required.");
+  }
+  if (!defined(positions)) {
+    throw new DeveloperError("positions is required.");
+  }
+  //>>includeEnd('debug');
+
+  return terrainProvider.readyPromise.then(function () {
+    const byLevel = [];
+    const maxLevels = [];
+
+    const availability = terrainProvider.availability;
+
+    //>>includeStart('debug', pragmas.debug);
+    if (!defined(availability)) {
+      throw new DeveloperError(
+        "sampleTerrainMostDetailed requires a terrain provider that has tile availability."
+      );
+    }
+    //>>includeEnd('debug');
+
+    const promises = [];
+    for (let i = 0; i < positions.length; ++i) {
+      const position = positions[i];
+      const maxLevel = availability.computeMaximumLevelAtPosition(position);
+      maxLevels[i] = maxLevel;
+      if (maxLevel === 0) {
+        // This is a special case where we have a parent terrain and we are requesting
+        // heights from an area that isn't covered by the top level terrain at all.
+        // This will essentially trigger the loading of the parent terrains root tile
+        terrainProvider.tilingScheme.positionToTileXY(
+          position,
+          1,
+          scratchCartesian2
+        );
+        const promise = terrainProvider.loadTileDataAvailability(
+          scratchCartesian2.x,
+          scratchCartesian2.y,
+          1
+        );
+        if (defined(promise)) {
+          promises.push(promise);
+        }
+      }
+
+      let atLevel = byLevel[maxLevel];
+      if (!defined(atLevel)) {
+        byLevel[maxLevel] = atLevel = [];
+      }
+      atLevel.push(position);
+    }
+
+    return Promise.all(promises)
+      .then(function () {
+        return Promise.all(
+          byLevel.map(function (positionsAtLevel, index) {
+            if (defined(positionsAtLevel)) {
+              return sampleTerrain(terrainProvider, index, positionsAtLevel);
+            }
+          })
+        );
+      })
+      .then(function () {
+        const changedPositions = [];
+        for (let i = 0; i < positions.length; ++i) {
+          const position = positions[i];
+          const maxLevel = availability.computeMaximumLevelAtPosition(position);
+
+          if (maxLevel !== maxLevels[i]) {
+            // Now that we loaded the max availability, a higher level has become available
+            changedPositions.push(position);
+          }
+        }
+
+        if (changedPositions.length > 0) {
+          return sampleTerrainMostDetailed(terrainProvider, changedPositions);
+        }
+      })
+      .then(function () {
+        return positions;
+      });
+  });
+}
+export default sampleTerrainMostDetailed;

package/Source/Core/scaleToGeodeticSurface.js

@@ -0,0 +1,147 @@
+import Cartesian3 from "./Cartesian3.js";
+import defined from "./defined.js";
+import DeveloperError from "./DeveloperError.js";
+import CesiumMath from "./Math.js";
+
+const scaleToGeodeticSurfaceIntersection = new Cartesian3();
+const scaleToGeodeticSurfaceGradient = new Cartesian3();
+
+/**
+ * Scales the provided Cartesian position along the geodetic surface normal
+ * so that it is on the surface of this ellipsoid.  If the position is
+ * at the center of the ellipsoid, this function returns undefined.
+ *
+ * @param {Cartesian3} cartesian The Cartesian position to scale.
+ * @param {Cartesian3} oneOverRadii One over radii of the ellipsoid.
+ * @param {Cartesian3} oneOverRadiiSquared One over radii squared of the ellipsoid.
+ * @param {Number} centerToleranceSquared Tolerance for closeness to the center.
+ * @param {Cartesian3} [result] The object onto which to store the result.
+ * @returns {Cartesian3} The modified result parameter, a new Cartesian3 instance if none was provided, or undefined if the position is at the center.
+ *
+ * @function scaleToGeodeticSurface
+ *
+ * @private
+ */
+function scaleToGeodeticSurface(
+  cartesian,
+  oneOverRadii,
+  oneOverRadiiSquared,
+  centerToleranceSquared,
+  result
+) {
+  //>>includeStart('debug', pragmas.debug);
+  if (!defined(cartesian)) {
+    throw new DeveloperError("cartesian is required.");
+  }
+  if (!defined(oneOverRadii)) {
+    throw new DeveloperError("oneOverRadii is required.");
+  }
+  if (!defined(oneOverRadiiSquared)) {
+    throw new DeveloperError("oneOverRadiiSquared is required.");
+  }
+  if (!defined(centerToleranceSquared)) {
+    throw new DeveloperError("centerToleranceSquared is required.");
+  }
+  //>>includeEnd('debug');
+
+  const positionX = cartesian.x;
+  const positionY = cartesian.y;
+  const positionZ = cartesian.z;
+
+  const oneOverRadiiX = oneOverRadii.x;
+  const oneOverRadiiY = oneOverRadii.y;
+  const oneOverRadiiZ = oneOverRadii.z;
+
+  const x2 = positionX * positionX * oneOverRadiiX * oneOverRadiiX;
+  const y2 = positionY * positionY * oneOverRadiiY * oneOverRadiiY;
+  const z2 = positionZ * positionZ * oneOverRadiiZ * oneOverRadiiZ;
+
+  // Compute the squared ellipsoid norm.
+  const squaredNorm = x2 + y2 + z2;
+  const ratio = Math.sqrt(1.0 / squaredNorm);
+
+  // As an initial approximation, assume that the radial intersection is the projection point.
+  const intersection = Cartesian3.multiplyByScalar(
+    cartesian,
+    ratio,
+    scaleToGeodeticSurfaceIntersection
+  );
+
+  // If the position is near the center, the iteration will not converge.
+  if (squaredNorm < centerToleranceSquared) {
+    return !isFinite(ratio)
+      ? undefined
+      : Cartesian3.clone(intersection, result);
+  }
+
+  const oneOverRadiiSquaredX = oneOverRadiiSquared.x;
+  const oneOverRadiiSquaredY = oneOverRadiiSquared.y;
+  const oneOverRadiiSquaredZ = oneOverRadiiSquared.z;
+
+  // Use the gradient at the intersection point in place of the true unit normal.
+  // The difference in magnitude will be absorbed in the multiplier.
+  const gradient = scaleToGeodeticSurfaceGradient;
+  gradient.x = intersection.x * oneOverRadiiSquaredX * 2.0;
+  gradient.y = intersection.y * oneOverRadiiSquaredY * 2.0;
+  gradient.z = intersection.z * oneOverRadiiSquaredZ * 2.0;
+
+  // Compute the initial guess at the normal vector multiplier, lambda.
+  let lambda =
+    ((1.0 - ratio) * Cartesian3.magnitude(cartesian)) /
+    (0.5 * Cartesian3.magnitude(gradient));
+  let correction = 0.0;
+
+  let func;
+  let denominator;
+  let xMultiplier;
+  let yMultiplier;
+  let zMultiplier;
+  let xMultiplier2;
+  let yMultiplier2;
+  let zMultiplier2;
+  let xMultiplier3;
+  let yMultiplier3;
+  let zMultiplier3;
+
+  do {
+    lambda -= correction;
+
+    xMultiplier = 1.0 / (1.0 + lambda * oneOverRadiiSquaredX);
+    yMultiplier = 1.0 / (1.0 + lambda * oneOverRadiiSquaredY);
+    zMultiplier = 1.0 / (1.0 + lambda * oneOverRadiiSquaredZ);
+
+    xMultiplier2 = xMultiplier * xMultiplier;
+    yMultiplier2 = yMultiplier * yMultiplier;
+    zMultiplier2 = zMultiplier * zMultiplier;
+
+    xMultiplier3 = xMultiplier2 * xMultiplier;
+    yMultiplier3 = yMultiplier2 * yMultiplier;
+    zMultiplier3 = zMultiplier2 * zMultiplier;
+
+    func = x2 * xMultiplier2 + y2 * yMultiplier2 + z2 * zMultiplier2 - 1.0;
+
+    // "denominator" here refers to the use of this expression in the velocity and acceleration
+    // computations in the sections to follow.
+    denominator =
+      x2 * xMultiplier3 * oneOverRadiiSquaredX +
+      y2 * yMultiplier3 * oneOverRadiiSquaredY +
+      z2 * zMultiplier3 * oneOverRadiiSquaredZ;
+
+    const derivative = -2.0 * denominator;
+
+    correction = func / derivative;
+  } while (Math.abs(func) > CesiumMath.EPSILON12);
+
+  if (!defined(result)) {
+    return new Cartesian3(
+      positionX * xMultiplier,
+      positionY * yMultiplier,
+      positionZ * zMultiplier
+    );
+  }
+  result.x = positionX * xMultiplier;
+  result.y = positionY * yMultiplier;
+  result.z = positionZ * zMultiplier;
+  return result;
+}
+export default scaleToGeodeticSurface;

package/Source/Core/subdivideArray.js

@@ -0,0 +1,35 @@
+import defined from "./defined.js";
+import DeveloperError from "./DeveloperError.js";
+
+/**
+ * Subdivides an array into a number of smaller, equal sized arrays.
+ *
+ * @function subdivideArray
+ *
+ * @param {Array} array The array to divide.
+ * @param {Number} numberOfArrays The number of arrays to divide the provided array into.
+ *
+ * @exception {DeveloperError} numberOfArrays must be greater than 0.
+ */
+function subdivideArray(array, numberOfArrays) {
+  //>>includeStart('debug', pragmas.debug);
+  if (!defined(array)) {
+    throw new DeveloperError("array is required.");
+  }
+
+  if (!defined(numberOfArrays) || numberOfArrays < 1) {
+    throw new DeveloperError("numberOfArrays must be greater than 0.");
+  }
+  //>>includeEnd('debug');
+
+  const result = [];
+  const len = array.length;
+  let i = 0;
+  while (i < len) {
+    const size = Math.ceil((len - i) / numberOfArrays--);
+    result.push(array.slice(i, i + size));
+    i += size;
+  }
+  return result;
+}
+export default subdivideArray;

package/Source/Core/webGLConstantToGlslType.js

@@ -0,0 +1,25 @@
+import WebGLConstants from "./WebGLConstants.js";
+
+function webGLConstantToGlslType(webGLValue) {
+  switch (webGLValue) {
+    case WebGLConstants.FLOAT:
+      return "float";
+    case WebGLConstants.FLOAT_VEC2:
+      return "vec2";
+    case WebGLConstants.FLOAT_VEC3:
+      return "vec3";
+    case WebGLConstants.FLOAT_VEC4:
+      return "vec4";
+    case WebGLConstants.FLOAT_MAT2:
+      return "mat2";
+    case WebGLConstants.FLOAT_MAT3:
+      return "mat3";
+    case WebGLConstants.FLOAT_MAT4:
+      return "mat4";
+    case WebGLConstants.SAMPLER_2D:
+      return "sampler2D";
+    case WebGLConstants.BOOL:
+      return "bool";
+  }
+}
+export default webGLConstantToGlslType;

package/Source/Core/wrapFunction.js

@@ -0,0 +1,26 @@
+import DeveloperError from "./DeveloperError.js";
+
+/**
+ * Wraps a function on the provided objects with another function called in the
+ * object's context so that the new function is always called immediately
+ * before the old one.
+ *
+ * @private
+ */
+function wrapFunction(obj, oldFunction, newFunction) {
+  //>>includeStart('debug', pragmas.debug);
+  if (typeof oldFunction !== "function") {
+    throw new DeveloperError("oldFunction is required to be a function.");
+  }
+
+  if (typeof newFunction !== "function") {
+    throw new DeveloperError("oldFunction is required to be a function.");
+  }
+  //>>includeEnd('debug');
+
+  return function () {
+    newFunction.apply(obj, arguments);
+    oldFunction.apply(obj, arguments);
+  };
+}
+export default wrapFunction;