@cesium/engine 3.0.2 → 5.0.0

package/Source/Core/PolygonGeometryLibrary.js

@@ -13,8 +13,11 @@ import GeometryAttribute from "./GeometryAttribute.js";
 import GeometryAttributes from "./GeometryAttributes.js";
 import GeometryPipeline from "./GeometryPipeline.js";
 import IndexDatatype from "./IndexDatatype.js";
+import IntersectionTests from "./IntersectionTests.js";
 import CesiumMath from "./Math.js";
 import Matrix3 from "./Matrix3.js";
+import Plane from "./Plane.js";
+import PolygonHierarchy from "./PolygonHierarchy.js";
 import PolygonPipeline from "./PolygonPipeline.js";
 import PrimitiveType from "./PrimitiveType.js";
 import Quaternion from "./Quaternion.js";
@@ -466,12 +469,294 @@ PolygonGeometryLibrary.polygonOutlinesFromHierarchy = function (
   return polygons;
 };
 
+const scratchRhumbIntersection = new Cartographic();
+function computeEquatorIntersectionRhumb(start, end, ellipsoid) {
+  const c0 = ellipsoid.cartesianToCartographic(start, scratchCartographic0);
+  const c1 = ellipsoid.cartesianToCartographic(end, scratchCartographic1);
+
+  if (Math.sign(c0.latitude) === Math.sign(c1.latitude)) {
+    return;
+  }
+
+  scratchRhumbLine.setEndPoints(c0, c1);
+
+  const intersection = scratchRhumbLine.findIntersectionWithLatitude(
+    0,
+    scratchRhumbIntersection
+  );
+
+  if (!defined(intersection)) {
+    return;
+  }
+
+  let minLongitude = Math.min(c0.longitude, c1.longitude);
+  let maxLongitude = Math.max(c0.longitude, c1.longitude);
+
+  if (Math.abs(maxLongitude - minLongitude) > CesiumMath.PI) {
+    // Crosses IDL, flip min and max
+    const swap = minLongitude;
+    minLongitude = maxLongitude;
+    maxLongitude = swap;
+  }
+
+  if (
+    intersection.longitude < minLongitude ||
+    intersection.longitude > maxLongitude
+  ) {
+    return;
+  }
+
+  return ellipsoid.cartographicToCartesian(intersection);
+}
+
+function computeEquatorIntersection(start, end, ellipsoid, arcType) {
+  if (arcType === ArcType.RHUMB) {
+    return computeEquatorIntersectionRhumb(start, end, ellipsoid);
+  }
+
+  const intersection = IntersectionTests.lineSegmentPlane(
+    start,
+    end,
+    Plane.ORIGIN_XY_PLANE
+  );
+
+  if (!defined(intersection)) {
+    return;
+  }
+
+  return ellipsoid.scaleToGeodeticSurface(intersection, intersection);
+}
+
+const scratchCartographic = new Cartographic();
+function computeEdgesOnPlane(positions, ellipsoid, arcType) {
+  const edgesOnPlane = [];
+  let startPoint,
+    endPoint,
+    type,
+    next,
+    intersection,
+    i = 0;
+  while (i < positions.length) {
+    startPoint = positions[i];
+    endPoint = positions[(i + 1) % positions.length];
+
+    type = CesiumMath.sign(startPoint.z);
+    next = CesiumMath.sign(endPoint.z);
+
+    const getLongitude = (position) => {
+      const cartographic = ellipsoid.cartesianToCartographic(
+        position,
+        scratchCartographic
+      );
+      return cartographic.longitude;
+    };
+
+    if (type === 0) {
+      // The start position is on the split
+      edgesOnPlane.push({
+        position: i,
+        type: type,
+        visited: false,
+        next: next,
+        theta: getLongitude(startPoint),
+      });
+    } else if (next !== 0) {
+      intersection = computeEquatorIntersection(
+        startPoint,
+        endPoint,
+        ellipsoid,
+        arcType
+      );
+
+      ++i;
+      if (!defined(intersection)) {
+        // The line segment is entirely above or below
+        continue;
+      }
+
+      // The line segment passed through
+      positions.splice(i, 0, intersection);
+      edgesOnPlane.push({
+        position: i,
+        type: type,
+        visited: false,
+        next: next,
+        theta: getLongitude(intersection),
+      });
+    }
+
+    ++i;
+  }
+
+  return edgesOnPlane;
+}
+
+function wirePolygon(
+  polygons,
+  polygonIndex,
+  positions,
+  edgesOnPlane,
+  toDelete,
+  startIndex,
+  abovePlane
+) {
+  const polygon = [];
+  let i = startIndex;
+  const getMatchingEdge = (i) => (edge) => edge.position === i;
+  const polygonsToWire = [];
+  do {
+    const position = positions[i];
+    polygon.push(position);
+
+    const edgeIndex = edgesOnPlane.findIndex(getMatchingEdge(i));
+    const edge = edgesOnPlane[edgeIndex];
+    if (!defined(edge)) {
+      // The current segment does not intersect
+      ++i;
+      continue;
+    }
+
+    const { visited: hasBeenVisited, type, next } = edge;
+    edge.visited = true;
+
+    if (type === 0) {
+      if (next === 0) {
+        // Special case where we'll need to backtrack along the edge
+        const previousEdge = edgesOnPlane[edgeIndex - (abovePlane ? 1 : -1)];
+        if (previousEdge?.position === i + 1) {
+          previousEdge.visited = true;
+        } else {
+          ++i;
+          continue;
+        }
+      }
+
+      // Special case where 3 polygons meet
+      if (
+        (!hasBeenVisited && abovePlane && next > 0) ||
+        (startIndex === i && !abovePlane && next < 0)
+      ) {
+        ++i;
+        continue;
+      }
+    }
+
+    const followEdge = abovePlane ? type >= 0 : type <= 0;
+    if (!followEdge) {
+      ++i;
+      continue;
+    }
+
+    if (!hasBeenVisited) {
+      // Wire another polygon starting at this position on the other side of the edge
+      polygonsToWire.push(i);
+    }
+
+    // Continue counter-clockwise to the next edge
+    const nextEdgeIndex = edgeIndex + (abovePlane ? 1 : -1);
+    const nextEdge = edgesOnPlane[nextEdgeIndex];
+    if (!defined(nextEdge)) {
+      ++i;
+      continue;
+    }
+
+    i = nextEdge.position;
+  } while (
+    i < positions.length &&
+    i >= 0 &&
+    i !== startIndex &&
+    polygon.length < positions.length
+  );
+
+  polygons.splice(polygonIndex, toDelete, polygon);
+
+  for (const index of polygonsToWire) {
+    polygonIndex = wirePolygon(
+      polygons,
+      ++polygonIndex,
+      positions,
+      edgesOnPlane,
+      0,
+      index,
+      !abovePlane
+    );
+  }
+
+  return polygonIndex;
+}
+
+/**
+ * Splits an array of polygons, defined as a list of Cartesian3 positions in counter-clockwise winding order, along the equator.
+ *
+ * @param {Array<Cartesian3[]>} outerRings An array of polygons, defined as a list of Cartesian3 positions in counter-clockwise winding order.
+ * @param {Ellipsoid} ellipsoid The ellipsoid to be used as a reference.
+ * @param {ArcType} arcType The type of line the polygon edges must follow. Valid options are {@link ArcType.GEODESIC} and {@link ArcType.RHUMB}.
+ * @param {Array<Cartesian3[]>} [result] An array of split polygons.
+ *
+ * @returns {Array<Cartesian3[]>} An array of split polygons.
+ */
+PolygonGeometryLibrary.splitPolygonsOnEquator = function (
+  outerRings,
+  ellipsoid,
+  arcType,
+  result
+) {
+  if (!defined(result)) {
+    result = [];
+  }
+
+  result.splice(0, 0, ...outerRings);
+  result.length = outerRings.length;
+
+  let currentPolygon = 0;
+  while (currentPolygon < result.length) {
+    // Adapted from https://www.sciencedirect.com/science/article/abs/pii/B9780125434577500589#:~:text=If%20the%20plane%20intersects%20the,tree%20and%20polygon%20intersection%20libraries
+    const outerRing = result[currentPolygon];
+    const positions = outerRing.slice();
+
+    if (outerRing.length < 3) {
+      result[currentPolygon] = positions;
+      ++currentPolygon;
+      continue;
+    }
+
+    // Step 1: Get all edges which intersect the split line, splciing any found intersections points into the list of positions
+    const edgesOnPlane = computeEdgesOnPlane(positions, ellipsoid, arcType);
+    // If nothing intersected (no point were added), or there is only a single point on the plane, use the original polygon
+    if (positions.length === outerRing.length || edgesOnPlane.length <= 1) {
+      result[currentPolygon] = positions;
+      ++currentPolygon;
+      continue;
+    }
+
+    // Step 2: Sort the edges along the split line by the distance between their starting points and the starting point of the split line.
+    edgesOnPlane.sort((a, b) => {
+      return a.theta - b.theta;
+    });
+
+    // Step 3: Rewire polygons, splicing each polygon into the array of results
+    const north = positions[0].z >= 0.0;
+    currentPolygon = wirePolygon(
+      result,
+      currentPolygon,
+      positions,
+      edgesOnPlane,
+      1,
+      0,
+      north
+    );
+  }
+
+  return result;
+};
+
 PolygonGeometryLibrary.polygonsFromHierarchy = function (
   polygonHierarchy,
   keepDuplicates,
   projectPointsTo2D,
   scaleToEllipsoidSurface,
-  ellipsoid
+  ellipsoid,
+  splitPolygons
 ) {
   // create from a polygon hierarchy
   // Algorithm adapted from http://www.geometrictools.com/Documentation/TriangulationByEarClipping.pdf
@@ -481,6 +766,8 @@ PolygonGeometryLibrary.polygonsFromHierarchy = function (
   const queue = new Queue();
   queue.enqueue(polygonHierarchy);
 
+  let split = defined(splitPolygons);
+
   while (queue.length !== 0) {
     const outerNode = queue.dequeue();
     let outerRing = outerNode.positions;
@@ -520,6 +807,20 @@ PolygonGeometryLibrary.polygonsFromHierarchy = function (
       outerRing = outerRing.slice().reverse();
     }
 
+    if (split) {
+      split = false;
+      let polygons = [outerRing];
+      polygons = splitPolygons(polygons, polygons);
+
+      if (polygons.length > 1) {
+        for (const positions of polygons) {
+          queue.enqueue(new PolygonHierarchy(positions, holes));
+        }
+
+        continue;
+      }
+    }
+
     let positions = outerRing.slice();
     const numChildren = defined(holes) ? holes.length : 0;
     const polygonHoles = [];

package/Source/Core/Stereographic.js

@@ -0,0 +1,247 @@
+import Cartesian2 from "./Cartesian2.js";
+import Cartesian3 from "./Cartesian3.js";
+import Cartographic from "./Cartographic.js";
+import Check from "./Check.js";
+import defined from "./defined.js";
+import Ellipsoid from "./Ellipsoid.js";
+import EllipsoidTangentPlane from "./EllipsoidTangentPlane.js";
+import IntersectionTests from "./IntersectionTests.js";
+import CesiumMath from "./Math.js";
+import Ray from "./Ray.js";
+
+/**
+ * Represents a point in stereographic coordinates, which can be obtained by projecting a cartesian coordinate from one pole onto a tangent plane at the other pole.
+ * The stereographic projection faithfully represents the relative directions of all great circles passing through its center point.
+ * To faithfully represents angles everywhere, this is a conformal projection, which means points are projected onto an arbrary sphere.
+ * @param {Cartesian2} [position] The steroegraphic coordinates.
+ * @param {EllipseGeometry} [tangentPlane] The tangent plane onto which the point was projected.
+ */
+function Stereographic(position, tangentPlane) {
+  this.position = position;
+  if (!defined(this.position)) {
+    this.position = new Cartesian2();
+  }
+
+  this.tangentPlane = tangentPlane;
+  if (!defined(this.tangentPlane)) {
+    this.tangentPlane = Stereographic.NORTH_POLE_TANGENT_PLANE;
+  }
+}
+
+Object.defineProperties(Stereographic.prototype, {
+  /**
+   * Gets the ellipsoid.
+   * @memberof Stereographic.prototype
+   * @type {Ellipsoid}
+   */
+  ellipsoid: {
+    get: function () {
+      return this.tangentPlane.ellipsoid;
+    },
+  },
+
+  /**
+   * Gets the x coordinate
+   * @memberof Stereographic.prototype
+   * @type {number}
+   */
+  x: {
+    get: function () {
+      return this.position.x;
+    },
+  },
+
+  /**
+   * Gets the y coordinate
+   * @memberof Stereographic.prototype
+   * @type {number}
+   */
+  y: {
+    get: function () {
+      return this.position.y;
+    },
+  },
+
+  /**
+   * Computes the conformal latitude, or the ellipsoidal latitude projected onto an arbitrary sphere.
+   * @memberof Stereographic.prototype
+   * @type {number}
+   */
+  conformalLatitude: {
+    get: function () {
+      const r = Cartesian2.magnitude(this.position);
+      const d = 2 * this.ellipsoid.maximumRadius;
+      const sign = this.tangentPlane.plane.normal.z;
+      return sign * (CesiumMath.PI_OVER_TWO - 2 * Math.atan2(r, d));
+    },
+  },
+
+  /**
+   * Computes the longitude
+   * @memberof Stereographic.prototype
+   * @type {number}
+   */
+  longitude: {
+    get: function () {
+      let longitude = CesiumMath.PI_OVER_TWO + Math.atan2(this.y, this.x);
+      if (longitude > Math.PI) {
+        longitude -= CesiumMath.TWO_PI;
+      }
+
+      return longitude;
+    },
+  },
+});
+
+const scratchCartographic = new Cartographic();
+const scratchCartesian = new Cartesian3();
+
+/**
+ * Computes the latitude based on an ellipsoid.
+ *
+ * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid on which to compute the longitude.
+ * @returns {number} The latitude
+ */
+Stereographic.prototype.getLatitude = function (ellipsoid) {
+  if (!defined(ellipsoid)) {
+    ellipsoid = Ellipsoid.WGS84;
+  }
+
+  scratchCartographic.latitude = this.conformalLatitude;
+  scratchCartographic.longitude = this.longitude;
+  scratchCartographic.height = 0.0;
+  const cartesian = this.ellipsoid.cartographicToCartesian(
+    scratchCartographic,
+    scratchCartesian
+  );
+  ellipsoid.cartesianToCartographic(cartesian, scratchCartographic);
+  return scratchCartographic.latitude;
+};
+
+const scratchProjectPointOntoPlaneRay = new Ray();
+const scratchProjectPointOntoPlaneRayDirection = new Cartesian3();
+const scratchProjectPointOntoPlaneCartesian3 = new Cartesian3();
+
+/**
+ * Computes the projection of the provided 3D position onto the 2D polar plane, radially outward from the provided origin.
+ *
+ * @param {Cartesian3} cartesian The point to project.
+ * @param {Stereographic} [result] The object onto which to store the result.
+ * @returns {Sterographic} The modified result parameter or a new Sterographic instance if none was provided.
+ */
+Stereographic.fromCartesian = function (cartesian, result) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.defined("cartesian", cartesian);
+  //>>includeEnd('debug');
+
+  const sign = CesiumMath.signNotZero(cartesian.z);
+  let tangentPlane = Stereographic.NORTH_POLE_TANGENT_PLANE;
+  let origin = Stereographic.SOUTH_POLE;
+  if (sign < 0) {
+    tangentPlane = Stereographic.SOUTH_POLE_TANGENT_PLANE;
+    origin = Stereographic.NORTH_POLE;
+  }
+
+  const ray = scratchProjectPointOntoPlaneRay;
+  ray.origin = tangentPlane.ellipsoid.scaleToGeocentricSurface(
+    cartesian,
+    ray.origin
+  );
+  ray.direction = Cartesian3.subtract(
+    ray.origin,
+    origin,
+    scratchProjectPointOntoPlaneRayDirection
+  );
+  Cartesian3.normalize(ray.direction, ray.direction);
+
+  const intersectionPoint = IntersectionTests.rayPlane(
+    ray,
+    tangentPlane.plane,
+    scratchProjectPointOntoPlaneCartesian3
+  );
+  const v = Cartesian3.subtract(intersectionPoint, origin, intersectionPoint);
+  const x = Cartesian3.dot(tangentPlane.xAxis, v);
+  const y = sign * Cartesian3.dot(tangentPlane.yAxis, v);
+
+  if (!defined(result)) {
+    return new Stereographic(new Cartesian2(x, y), tangentPlane);
+  }
+
+  result.position = new Cartesian2(x, y);
+  result.tangentPlane = tangentPlane;
+  return result;
+};
+
+/**
+ * Computes the projection of the provided 3D positions onto the 2D polar plane, radially outward from the provided origin.
+ *
+ * @param {Cartesian3[]} cartesians The points to project.
+ * @param {Stereographic[]} [result] The object onto which to store the result.
+ * @returns {Sterographic[]} The modified result parameter or a new Sterographic instance if none was provided.
+ */
+Stereographic.fromCartesianArray = function (cartesians, result) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.defined("cartesians", cartesians);
+  //>>includeEnd('debug');
+
+  const length = cartesians.length;
+  if (!defined(result)) {
+    result = new Array(length);
+  } else {
+    result.length = length;
+  }
+  for (let i = 0; i < length; i++) {
+    result[i] = Stereographic.fromCartesian(cartesians[i], result[i]);
+  }
+  return result;
+};
+
+/**
+ * Duplicates a Stereographic instance.
+ *
+ * @param {Stereographic} stereographic The Stereographic to duplicate.
+ * @param {Stereographic} [result] The object onto which to store the result.
+ * @returns {Stereographic} The modified result parameter or a new Stereographic instance if one was not provided. (Returns undefined if stereographic is undefined)
+ */
+Stereographic.clone = function (stereographic, result) {
+  if (!defined(stereographic)) {
+    return undefined;
+  }
+  if (!defined(result)) {
+    return new Stereographic(
+      stereographic.position,
+      stereographic.tangentPlane
+    );
+  }
+
+  result.position = stereographic.position;
+  result.tangentPlane = stereographic.tangentPlane;
+
+  return result;
+};
+
+/**
+ * An Ellipsoid instance initialized to radii of (0.5, 0.5, 0.5).
+ *
+ * @type {Stereographic}
+ * @constant
+ */
+Stereographic.HALF_UNIT_SPHERE = Object.freeze(new Ellipsoid(0.5, 0.5, 0.5));
+
+Stereographic.NORTH_POLE = Object.freeze(new Cartesian3(0.0, 0.0, 0.5));
+Stereographic.SOUTH_POLE = Object.freeze(new Cartesian3(0.0, 0.0, -0.5));
+
+Stereographic.NORTH_POLE_TANGENT_PLANE = Object.freeze(
+  new EllipsoidTangentPlane(
+    Stereographic.NORTH_POLE,
+    Stereographic.HALF_UNIT_SPHERE
+  )
+);
+Stereographic.SOUTH_POLE_TANGENT_PLANE = Object.freeze(
+  new EllipsoidTangentPlane(
+    Stereographic.SOUTH_POLE,
+    Stereographic.HALF_UNIT_SPHERE
+  )
+);
+
+export default Stereographic;