@hztxi/cesium-engine 25.0.6 → 26.2.1

package/Source/Scene/Camera.js

@@ -3,6 +3,7 @@ import Cartesian2 from "../Core/Cartesian2.js";
 import Cartesian3 from "../Core/Cartesian3.js";
 import Cartesian4 from "../Core/Cartesian4.js";
 import Cartographic from "../Core/Cartographic.js";
+import Check from "../Core/Check.js";
 import Frozen from "../Core/Frozen.js";
 import defined from "../Core/defined.js";
 import DeveloperError from "../Core/DeveloperError.js";
@@ -26,6 +27,7 @@ import Ray from "../Core/Ray.js";
 import Rectangle from "../Core/Rectangle.js";
 import Transforms from "../Core/Transforms.js";
 import CameraFlightPath from "./CameraFlightPath.js";
+import ColumbusWorlds from "./ColumbusWorlds.js";
 import MapMode2D from "./MapMode2D.js";
 import SceneMode from "./SceneMode.js";
 
@@ -537,6 +539,18 @@ function convertTransformForColumbusView(camera) {
     camera._transform,
     camera._actualTransform,
   );
+
+  if (camera._scene.columbusRepeatWorlds === true) {
+    // Columbus repeat worlds: anchor the converted reference frame on the
+    // world copy nearest the camera (element [13] is the translation's
+    // map-u component in the column-major matrix) so the frame, and offsets
+    // within it, stay continuous with the camera's current copy.
+    camera._actualTransform[13] = ColumbusWorlds.nearestWorldU(
+      camera._positionWC.y,
+      camera._actualTransform[13],
+      camera._projection,
+    );
+  }
 }
 
 const scratchCartographic = new Cartographic();
@@ -752,6 +766,18 @@ function updateMembers(camera) {
       }
 
       camera._projection.unproject(positionENU, camera._positionCartographic);
+
+      if (
+        (mode === SceneMode.SCENE2D || mode === SceneMode.COLUMBUS_VIEW) &&
+        camera._scene.columbusRepeatWorlds === true
+      ) {
+        // Repeat worlds: the camera may sit on any world copy, which unprojects
+        // to a longitude outside [-180°, 180°]; wrap it so rectangle
+        // containment checks see the equivalent primary point.
+        camera._positionCartographic.longitude = CesiumMath.negativePiToPi(
+          camera._positionCartographic.longitude,
+        );
+      }
     }
   }
 
@@ -1315,6 +1341,15 @@ function setViewCV(camera, position, hpr, convert) {
       );
       position = projection.project(cartographic, scratchSetViewCartesian);
     }
+    if (camera._scene.columbusRepeatWorlds === true) {
+      // Columbus repeat worlds: keep the view continuous with the camera's
+      // current world copy instead of snapping back to the primary world.
+      position.x = ColumbusWorlds.nearestWorldU(
+        camera.positionWC.y,
+        position.x,
+        camera._projection,
+      );
+    }
     Cartesian3.clone(position, camera.position);
   }
   hpr.heading = hpr.heading - CesiumMath.PI_OVER_TWO;
@@ -1353,6 +1388,16 @@ function setView2D(camera, position, hpr, convert) {
 
     Cartesian2.clone(position, camera.position);
 
+    if (camera._scene.columbusRepeatWorlds === true) {
+      // Repeat worlds: keep the destination on the camera's current world copy
+      // instead of snapping the view back to the primary world.
+      camera.position.x = ColumbusWorlds.nearestWorldU(
+        camera.positionWC.y,
+        camera.position.x,
+        camera._projection,
+      );
+    }
+
     const newLeft = -position.z * 0.5;
     const newRight = -newLeft;
 
@@ -2356,7 +2401,7 @@ const scratchLookAtHeadingPitchRangeQuaternion1 = new Quaternion();
 const scratchLookAtHeadingPitchRangeQuaternion2 = new Quaternion();
 const scratchHeadingPitchRangeMatrix3 = new Matrix3();
 
-function offsetFromHeadingPitchRange(heading, pitch, range) {
+function offsetFromHeadingPitchRange(heading, pitch, range, result) {
   pitch = CesiumMath.clamp(
     pitch,
     -CesiumMath.PI_OVER_TWO,
@@ -2380,10 +2425,7 @@ function offsetFromHeadingPitchRange(heading, pitch, range) {
     scratchHeadingPitchRangeMatrix3,
   );
 
-  const offset = Cartesian3.clone(
-    Cartesian3.UNIT_X,
-    scratchLookAtHeadingPitchRangeOffset,
-  );
+  const offset = Cartesian3.clone(Cartesian3.UNIT_X, result);
   Matrix3.multiplyByVector(rotMatrix, offset, offset);
   Cartesian3.negate(offset, offset);
   Cartesian3.multiplyByScalar(offset, range, offset);
@@ -2441,6 +2483,7 @@ Camera.prototype.lookAtTransform = function (transform, offset) {
       offset.heading,
       offset.pitch,
       offset.range,
+      scratchLookAtHeadingPitchRangeOffset,
     );
   } else {
     cartesianOffset = offset;
@@ -2492,6 +2535,72 @@ Camera.prototype.lookAtTransform = function (transform, offset) {
   this._adjustOrthographicFrustum(true);
 };
 
+const scratchLookAtWorldPositionTransform = new Matrix4();
+const scratchLookAtWorldPositionDirection = new Cartesian3();
+const scratchLookAtWorldPositionWorldUp = new Cartesian3();
+const scratchLookAtWorldPositionRight = new Cartesian3();
+
+/**
+ * Sets the camera orientation to look at a target position in world coordinates. The camera's up vector will be oriented to the world up vector at the target position.
+ * If the camera is at the target position, the camera will be oriented to the world up vector at the target position.
+ * @param {Cartesian3} target The target position in world coordinates.
+ * @param {Ellipsoid} [ellipsoid=Ellipsoid.default] The ellipsoid to use for determining the world up.
+ */
+Camera.prototype.lookAtWorldPosition = function (
+  target,
+  ellipsoid = Ellipsoid.default,
+) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.object("target", target);
+  Check.typeOf.object("ellipsoid", ellipsoid);
+  //>>includeEnd('debug');
+
+  const transform = Matrix4.clone(
+    this._transform,
+    scratchLookAtWorldPositionTransform,
+  );
+
+  this._setTransform(Matrix4.IDENTITY);
+
+  // Get direction to look at target
+  let direction = Cartesian3.subtract(
+    target,
+    this.positionWC,
+    scratchLookAtWorldPositionDirection,
+  );
+
+  // If the camera is at the target position, we can't look at it, but we should still continue to re-orient the camera to the world up vector at the target position.
+  if (Cartesian3.magnitudeSquared(direction) < CesiumMath.EPSILON8) {
+    direction = Cartesian3.clone(
+      this.directionWC,
+      scratchLookAtWorldPositionDirection,
+    );
+  }
+
+  direction = Cartesian3.normalize(direction, this.direction);
+
+  // Orient the camera to the world up vector at the target position
+  const worldUp = ellipsoid.geodeticSurfaceNormal(
+    target,
+    scratchLookAtWorldPositionWorldUp,
+  );
+
+  let right = Cartesian3.cross(
+    direction,
+    worldUp,
+    scratchLookAtWorldPositionRight,
+  );
+  if (Cartesian3.magnitudeSquared(right) < CesiumMath.EPSILON8) {
+    right = Cartesian3.clone(this.rightWC, scratchLookAtWorldPositionRight);
+  }
+  Cartesian3.normalize(right, this.right);
+
+  const up = Cartesian3.cross(right, direction, this.up);
+  Cartesian3.normalize(up, this.up);
+
+  this._setTransform(transform);
+};
+
 const viewRectangle3DCartographic1 = new Cartographic();
 const viewRectangle3DCartographic2 = new Cartographic();
 const viewRectangle3DNorthEast = new Cartesian3();
@@ -2874,13 +2983,19 @@ function pickMapColumbusView(camera, windowPosition, projection, result) {
 
   if (
     cart.latitude < -CesiumMath.PI_OVER_TWO ||
-    cart.latitude > CesiumMath.PI_OVER_TWO ||
-    cart.longitude < -Math.PI ||
-    cart.longitude > Math.PI
+    cart.latitude > CesiumMath.PI_OVER_TWO
   ) {
     return undefined;
   }
 
+  // The longitude may fall outside [-PI, PI] when Columbus repeat worlds are
+  // enabled and the picked point is on a translated world copy. Accept it:
+  // the returned ECEF position is the equivalent primary-world point, so
+  // picks on world copies succeed instead of returning undefined. Callers
+  // that need to know which copy was picked should use
+  // Globe.pickWorldCoordinates or Scene.pickPosition, which operate in scene
+  // (map-plane) world coordinates.
+
   return projection.ellipsoid.cartographicToCartesian(cart, result);
 }
 
@@ -3190,6 +3305,19 @@ function createAnimationCV(camera, duration) {
 
   position = camera.cameraToWorldCoordinatesPoint(camera.position, posScratch);
 
+  if (camera._scene.columbusRepeatWorlds === true) {
+    // Columbus repeat worlds: the camera may sit on any world copy; wrapping
+    // its map-u coordinate into the primary world is visually identical (the
+    // map repeats) and keeps the bounds checks below meaningful.
+    const worldWidth = ColumbusWorlds.getWorldWidth(camera._projection);
+    position.y =
+      CesiumMath.mod(position.y + worldWidth * 0.5, worldWidth) -
+      worldWidth * 0.5;
+    center.y =
+      CesiumMath.mod(center.y + worldWidth * 0.5, worldWidth) -
+      worldWidth * 0.5;
+  }
+
   const tanPhi = Math.tan(camera.frustum.fovy * 0.5);
   const tanTheta = camera.frustum.aspectRatio * tanPhi;
   const distToC = Cartesian3.magnitude(
@@ -3621,6 +3749,7 @@ Camera.prototype.flyToBoundingSphere = function (boundingSphere, options) {
       offset.heading,
       offset.pitch,
       offset.range,
+      scratchflyToBoundingSphereDestination,
     );
   }
 

package/Source/Scene/CameraEventAggregator.js

@@ -8,12 +8,29 @@ import ScreenSpaceEventHandler from "../Core/ScreenSpaceEventHandler.js";
 import ScreenSpaceEventType from "../Core/ScreenSpaceEventType.js";
 import CameraEventType from "./CameraEventType.js";
 
-function getKey(type, modifier) {
-  let key = `${type}`;
-  if (defined(modifier)) {
-    key += `+${modifier}`;
+const keyboardModifierCombinations = [
+  KeyboardEventModifier.SHIFT,
+  KeyboardEventModifier.CTRL,
+  KeyboardEventModifier.ALT,
+  [KeyboardEventModifier.SHIFT, KeyboardEventModifier.CTRL],
+  [KeyboardEventModifier.SHIFT, KeyboardEventModifier.ALT],
+  [KeyboardEventModifier.CTRL, KeyboardEventModifier.ALT],
+  [
+    KeyboardEventModifier.SHIFT,
+    KeyboardEventModifier.CTRL,
+    KeyboardEventModifier.ALT,
+  ],
+];
+
+function getKey(type, modifiers) {
+  if (!defined(modifiers)) {
+    return `${type}`;
   }
-  return key;
+
+  const modifierList = Array.isArray(modifiers)
+    ? modifiers.toSorted()
+    : [modifiers];
+  return `${type}+${modifierList.join("+")}`;
 }
 
 function clonePinchMovement(pinchMovement, result) {
@@ -219,7 +236,7 @@ function listenMouseButtonDownUp(aggregator, modifier, type) {
   aggregator._eventHandler.setInputAction(
     function () {
       cancelMouseDownAction(getKey(type, undefined), aggregator);
-      for (const modifier of Object.values(KeyboardEventModifier)) {
+      for (const modifier of keyboardModifierCombinations) {
         const cancelKey = getKey(type, modifier);
         cancelMouseDownAction(cancelKey, aggregator);
       }
@@ -382,18 +399,13 @@ function CameraEventAggregator(canvas) {
   listenMouseButtonDownUp(this, undefined, CameraEventType.MIDDLE_DRAG);
   listenMouseMove(this, undefined);
 
-  for (const modifierName in KeyboardEventModifier) {
-    if (KeyboardEventModifier.hasOwnProperty(modifierName)) {
-      const modifier = KeyboardEventModifier[modifierName];
-      if (defined(modifier)) {
-        listenToWheel(this, modifier);
-        listenToPinch(this, modifier, canvas);
-        listenMouseButtonDownUp(this, modifier, CameraEventType.LEFT_DRAG);
-        listenMouseButtonDownUp(this, modifier, CameraEventType.RIGHT_DRAG);
-        listenMouseButtonDownUp(this, modifier, CameraEventType.MIDDLE_DRAG);
-        listenMouseMove(this, modifier);
-      }
-    }
+  for (const modifiers of keyboardModifierCombinations) {
+    listenToWheel(this, modifiers);
+    listenToPinch(this, modifiers, canvas);
+    listenMouseButtonDownUp(this, modifiers, CameraEventType.LEFT_DRAG);
+    listenMouseButtonDownUp(this, modifiers, CameraEventType.RIGHT_DRAG);
+    listenMouseButtonDownUp(this, modifiers, CameraEventType.MIDDLE_DRAG);
+    listenMouseMove(this, modifiers);
   }
 }
 

package/Source/Scene/CameraFlightPath.js

@@ -8,6 +8,7 @@ import EasingFunction from "../Core/EasingFunction.js";
 import CesiumMath from "../Core/Math.js";
 import PerspectiveFrustum from "../Core/PerspectiveFrustum.js";
 import PerspectiveOffCenterFrustum from "../Core/PerspectiveOffCenterFrustum.js";
+import ColumbusWorlds from "./ColumbusWorlds.js";
 import SceneMode from "./SceneMode.js";
 
 /**
@@ -436,6 +437,22 @@ CameraFlightPath.createTween = function (scene, options) {
   }
 
   const camera = scene.camera;
+
+  if (
+    (mode === SceneMode.SCENE2D || mode === SceneMode.COLUMBUS_VIEW) &&
+    scene.columbusRepeatWorlds === true
+  ) {
+    // Repeat worlds: fly to the copy of the destination nearest the camera's
+    // current copy so the flight pans locally instead of crossing a full
+    // world. In local (u, v, h) coordinates, u is the x component.
+    scratchDestination.x = ColumbusWorlds.nearestWorldU(
+      camera.position.x,
+      destination.x,
+      projection,
+    );
+    destination = scratchDestination;
+  }
+
   const transform = options.endTransform;
   if (defined(transform)) {
     camera._setTransform(transform);

package/Source/Scene/Cesium3DTile.js

@@ -503,6 +503,7 @@ function Cesium3DTile(tileset, baseResource, header, parent) {
   this._selectedFrame = 0;
   this._wasSelectedLastFrame = false;
   this._requestedFrame = 0;
+  this._desiredFrame = 0;
   this._ancestorWithContent = undefined;
   this._ancestorWithContentAvailable = undefined;
   this._refines = false;
@@ -944,13 +945,34 @@ Cesium3DTile.prototype.getScreenSpaceError = function (
     error = geometricError / pixelSize;
   } else {
     // Avoid divide by zero when viewer is inside the tile
-    const distance = Math.max(this._distanceToCamera, CesiumMath.EPSILON7);
+    const tileDistance = Math.max(this._distanceToCamera, CesiumMath.EPSILON7);
     const sseDenominator = frustum.sseDenominator;
-    error = (geometricError * height) / (distance * sseDenominator);
+    error = (geometricError * height) / (tileDistance * sseDenominator);
+    const uniformLevel = tileset._uniformLevelState;
+    if (uniformLevel.active) {
+      const referenceDistance = Math.max(
+        uniformLevel.referenceDistance,
+        CesiumMath.EPSILON7,
+      );
+      const uniformError =
+        (geometricError * height) / (referenceDistance * sseDenominator);
+      const cappedUniformError = CesiumMath.clamp(
+        uniformError,
+        error / uniformLevel.coarsenFactor,
+        error * uniformLevel.deviationFactor,
+      );
+      error += (cappedUniformError - error) * uniformLevel.engage;
+    }
     if (tileset.dynamicScreenSpaceError) {
       const density = tileset._dynamicScreenSpaceErrorComputedDensity;
       const factor = tileset.dynamicScreenSpaceErrorFactor;
-      const dynamicError = CesiumMath.fog(distance, density) * factor;
+      let dynamicError = CesiumMath.fog(tileDistance, density) * factor;
+      if (uniformLevel.active) {
+        const uniformDynamicError =
+          CesiumMath.fog(uniformLevel.referenceDistance, density) * factor;
+        dynamicError +=
+          (uniformDynamicError - dynamicError) * uniformLevel.engage;
+      }
       error -= dynamicError;
     }
   }
@@ -1232,6 +1254,16 @@ async function processArrayBuffer(
       return;
     }
 
+    if (isEmptyTile(tile, error)) {
+      if (expired) {
+        tile.expireDate = undefined;
+      }
+      tile._content = new Empty3DTileContent(tileset, tile);
+      markTileAsEmptyContent(tile);
+      tile._contentState = Cesium3DTileContentState.PROCESSING;
+      return tile._content;
+    }
+
     tile._contentState = Cesium3DTileContentState.FAILED;
     throw error;
   }
@@ -1256,6 +1288,7 @@ async function processArrayBuffer(
 
     if (tile.isDestroyed()) {
       // Tile is unloaded before the content can process
+      destroyUnattachedContent(content);
       return;
     }
 
@@ -1264,6 +1297,9 @@ async function processArrayBuffer(
     }
 
     tile._content = content;
+    if (content instanceof Empty3DTileContent) {
+      markTileAsEmptyContent(tile);
+    }
     tile._contentState = Cesium3DTileContentState.PROCESSING;
 
     return content;
@@ -1316,6 +1352,49 @@ function requestSingleContent(tile) {
   return processArrayBuffer(tile, tileset, request, expired, promise);
 }
 
+/**
+ * Determines whether a tile load error should be interpreted as "no content"
+ * (empty tile) rather than a true failure. A missing tile policy specifies
+ * HTTP Status Codes to be interpreted as "no content", allowing tiles to be
+ * statically hosted without generating and serving unnecessary content for
+ * empty tiles.
+ * @ignore
+ */
+function isEmptyTile(tile, error) {
+  const tileset = tile._tileset;
+  const policy = tileset?._runtimeContentCodec?.missingTilePolicy;
+  if (!defined(policy)) {
+    return false;
+  }
+
+  if (!defined(error.statusCode)) {
+    return false;
+  }
+  return policy.statusCodes.includes(error.statusCode);
+}
+
+function markTileAsEmptyContent(tile) {
+  // These flags are mutable instance state initialized in the constructor.
+  tile.hasEmptyContent = true;
+  tile.hasRenderableContent = false;
+}
+
+/**
+ * Releases content that was constructed but never attached to its tile, which
+ * happens when the tile is destroyed while the payload is still decoding. Some
+ * content types register themselves with shared owners during construction, so
+ * dropping the reference alone would leak.
+ * @param {Cesium3DTileContent|undefined} content
+ * @private
+ */
+function destroyUnattachedContent(content) {
+  if (defined(content) && !content.isDestroyed()) {
+    content.destroy();
+  }
+}
+
+Cesium3DTile._isEmptyTile = isEmptyTile;
+
 /**
  * Given a downloaded content payload, construct a {@link Cesium3DTileContent}.
  * <p>
@@ -1328,10 +1407,29 @@ function requestSingleContent(tile) {
  * @private
  */
 async function makeContent(tile, arrayBuffer) {
+  const tileset = tile._tileset;
+  const codec = tileset?._runtimeContentCodec;
+  // Runtime codecs own leaf payloads. Implicit placeholder tiles first load a
+  // subtree JSON/binary payload, which must continue through normal dispatch
+  // so it can expand into the codec's derived content tiles.
+  if (
+    !defined(tile.implicitTileset) &&
+    defined(codec) &&
+    typeof codec.createContent === "function"
+  ) {
+    const content = await Promise.resolve(
+      codec.createContent(tileset, tile, tile._contentResource, arrayBuffer),
+    );
+    if (tile.isDestroyed()) {
+      destroyUnattachedContent(content);
+      return;
+    }
+    return content;
+  }
+
   const preprocessed = preprocess3DTileContent(arrayBuffer);
 
   // Vector and Geometry tile rendering do not support the skip LOD optimization.
-  const tileset = tile._tileset;
   tileset._disableSkipLevelOfDetail =
     tileset._disableSkipLevelOfDetail ||
     preprocessed.contentType === Cesium3DTileContentType.GEOMETRY ||