@cesium/engine 11.0.0 → 12.0.0

package/Source/Widget/CesiumWidget.js

@@ -1,13 +1,26 @@
+import BoundingSphere from "../Core/BoundingSphere.js";
 import Cartesian3 from "../Core/Cartesian3.js";
+import Cartographic from "../Core/Cartographic.js";
 import Clock from "../Core/Clock.js";
 import defaultValue from "../Core/defaultValue.js";
 import defined from "../Core/defined.js";
 import destroyObject from "../Core/destroyObject.js";
 import DeveloperError from "../Core/DeveloperError.js";
 import Ellipsoid from "../Core/Ellipsoid.js";
+import Event from "../Core/Event.js";
+import EventHelper from "../Core/EventHelper.js";
 import FeatureDetection from "../Core/FeatureDetection.js";
 import formatError from "../Core/formatError.js";
+import HeadingPitchRange from "../Core/HeadingPitchRange.js";
+import Matrix4 from "../Core/Matrix4.js";
+import BoundingSphereState from "../DataSources/BoundingSphereState.js";
+import DataSourceCollection from "../DataSources/DataSourceCollection.js";
+import DataSourceDisplay from "../DataSources/DataSourceDisplay.js";
+import EntityView from "../DataSources/EntityView.js";
 import getElement from "../DataSources/getElement.js";
+import Property from "../DataSources/Property.js";
+import Cesium3DTileset from "../Scene/Cesium3DTileset.js";
+import computeFlyToLocationForRectangle from "../Scene/computeFlyToLocationForRectangle.js";
 import Globe from "../Scene/Globe.js";
 import ImageryLayer from "../Scene/ImageryLayer.js";
 import Moon from "../Scene/Moon.js";
@@ -18,6 +31,17 @@ import ShadowMode from "../Scene/ShadowMode.js";
 import SkyAtmosphere from "../Scene/SkyAtmosphere.js";
 import SkyBox from "../Scene/SkyBox.js";
 import Sun from "../Scene/Sun.js";
+import TimeDynamicPointCloud from "../Scene/TimeDynamicPointCloud.js";
+import VoxelPrimitive from "../Scene/VoxelPrimitive.js";
+
+function trackDataSourceClock(clock, dataSource) {
+  if (defined(dataSource)) {
+    const dataSourceClock = dataSource.clock;
+    if (defined(dataSourceClock)) {
+      dataSourceClock.getValue(clock);
+    }
+  }
+}
 
 function startRenderLoop(widget) {
   widget._renderLoopRunning = true;
@@ -118,6 +142,7 @@ function configureCameraFrustum(widget) {
  * @param {Element|string} container The DOM element or ID that will contain the widget.
  * @param {object} [options] Object with the following properties:
  * @param {Clock} [options.clock=new Clock()] The clock to use to control current time.
+ * @param {boolean} [options.shouldAnimate=false] <code>true</code> if the clock should attempt to advance simulation time by default, <code>false</code> otherwise.
  * @param {Ellipsoid} [options.ellipsoid=Ellipsoid.default] The default ellipsoid.
  * @param {ImageryLayer|false} [options.baseLayer=ImageryLayer.fromWorldImagery()] The bottommost imagery layer applied to the globe. If set to <code>false</code>, no imagery provider will be added.
  * @param {TerrainProvider} [options.terrainProvider=new EllipsoidTerrainProvider(options.ellipsoid)] The terrain provider.
@@ -133,14 +158,17 @@ function configureCameraFrustum(widget) {
  * @param {boolean} [options.useBrowserRecommendedResolution=true] If true, render at the browser's recommended resolution and ignore <code>window.devicePixelRatio</code>.
  * @param {number} [options.targetFrameRate] The target frame rate when using the default render loop.
  * @param {boolean} [options.showRenderLoopErrors=true] If true, this widget will automatically display an HTML panel to the user containing the error, if a render loop error occurs.
+ * @param {boolean} [options.automaticallyTrackDataSourceClocks=true] If true, this widget will automatically track the clock settings of newly added DataSources, updating if the DataSource's clock changes.  Set this to false if you want to configure the clock independently.
  * @param {ContextOptions} [options.contextOptions] Context and WebGL creation properties passed to {@link Scene}.
  * @param {Element|string} [options.creditContainer] The DOM element or ID that will contain the {@link CreditDisplay}.  If not specified, the credits are added
  *        to the bottom of the widget itself.
  * @param {Element|string} [options.creditViewport] The DOM element or ID that will contain the credit pop up created by the {@link CreditDisplay}.  If not specified, it will appear over the widget itself.
+ * @param {DataSourceCollection} [options.dataSources=new DataSourceCollection()] The collection of data sources visualized by the widget.  If this parameter is provided,
+ *                               the instance is assumed to be owned by the caller and will not be destroyed when the widget is destroyed.
  * @param {boolean} [options.shadows=false] Determines if shadows are cast by light sources.
  * @param {ShadowMode} [options.terrainShadows=ShadowMode.RECEIVE_ONLY] Determines if the terrain casts or receives shadows from light sources.
  * @param {MapMode2D} [options.mapMode2D=MapMode2D.INFINITE_SCROLL] Determines if the 2D map is rotatable or can be scrolled infinitely in the horizontal direction.
- * @param {boolean} [options.blurActiveElementOnCanvasFocus=true] If true, the active element will blur when the viewer's canvas is clicked. Setting this to false is useful for cases when the canvas is clicked only for retrieving position or an entity data without actually meaning to set the canvas to be the active element.
+ * @param {boolean} [options.blurActiveElementOnCanvasFocus=true] If true, the active element will blur when the widget's canvas is clicked. Setting this to false is useful for cases when the canvas is clicked only for retrieving position or an entity data without actually meaning to set the canvas to be the active element.
  * @param {boolean} [options.requestRenderMode=false] If true, rendering a frame will only occur when needed as determined by changes within the scene. Enabling improves performance of the application, but requires using {@link Scene#requestRender} to render a new frame explicitly in this mode. This will be necessary in many cases after making changes to the scene in other parts of the API. See {@link https://cesium.com/blog/2018/01/24/cesium-scene-rendering-performance/|Improving Performance with Explicit Rendering}.
  * @param {number} [options.maximumRenderTimeChange=0.0] If requestRenderMode is true, this value defines the maximum change in simulation time allowed before a render is requested. See {@link https://cesium.com/blog/2018/01/24/cesium-scene-rendering-performance/|Improving Performance with Explicit Rendering}.
  * @param {number} [options.msaaSamples=4] If provided, this value controls the rate of multisample antialiasing. Typical multisampling rates are 2, 4, and sometimes 8 samples per pixel. Higher sampling rates of MSAA may impact performance in exchange for improved visual quality. This value only applies to WebGL2 contexts that support multisample render targets. Set to 1 to disable MSAA.
@@ -192,7 +220,8 @@ function CesiumWidget(container, options) {
   container.appendChild(element);
 
   const canvas = document.createElement("canvas");
-  const supportsImageRenderingPixelated = FeatureDetection.supportsImageRenderingPixelated();
+  const supportsImageRenderingPixelated =
+    FeatureDetection.supportsImageRenderingPixelated();
   this._supportsImageRenderingPixelated = supportsImageRenderingPixelated;
   if (supportsImageRenderingPixelated) {
     canvas.style.imageRendering = FeatureDetection.imageRenderingValue();
@@ -221,7 +250,7 @@ function CesiumWidget(container, options) {
 
   const blurActiveElementOnCanvasFocus = defaultValue(
     options.blurActiveElementOnCanvasFocus,
-    true
+    true,
   );
 
   if (blurActiveElementOnCanvasFocus) {
@@ -247,7 +276,7 @@ function CesiumWidget(container, options) {
 
   const useBrowserRecommendedResolution = defaultValue(
     options.useBrowserRecommendedResolution,
-    true
+    true,
   );
 
   this._element = element;
@@ -265,8 +294,23 @@ function CesiumWidget(container, options) {
   this._resolutionScale = 1.0;
   this._useBrowserRecommendedResolution = useBrowserRecommendedResolution;
   this._forceResize = false;
+  this._entityView = undefined;
+  this._clockTrackedDataSource = undefined;
+  this._trackedEntity = undefined;
+  this._needTrackedEntityUpdate = false;
+  this._zoomIsFlight = false;
+  this._zoomTarget = undefined;
+  this._zoomPromise = undefined;
+  this._zoomOptions = undefined;
+  this._trackedEntityChanged = new Event();
+  this._allowDataSourcesToSuspendAnimation = true;
+
   this._clock = defined(options.clock) ? options.clock : new Clock();
 
+  if (defined(options.shouldAnimate)) {
+    this._clock.shouldAnimate = options.shouldAnimate;
+  }
+
   configureCanvasSize(this);
 
   try {
@@ -303,7 +347,7 @@ function CesiumWidget(container, options) {
       scene.globe = globe;
       scene.globe.shadows = defaultValue(
         options.terrainShadows,
-        ShadowMode.RECEIVE_ONLY
+        ShadowMode.RECEIVE_ONLY,
       );
     }
 
@@ -348,7 +392,7 @@ function CesiumWidget(container, options) {
       //>>includeStart('debug', pragmas.debug);
       if (defined(options.terrainProvider)) {
         throw new DeveloperError(
-          "Specify either options.terrainProvider or options.terrain."
+          "Specify either options.terrainProvider or options.terrain.",
         );
       }
       //>>includeEnd('debug')
@@ -370,7 +414,7 @@ function CesiumWidget(container, options) {
     this._useDefaultRenderLoop = undefined;
     this.useDefaultRenderLoop = defaultValue(
       options.useDefaultRenderLoop,
-      true
+      true,
     );
 
     this._targetFrameRate = undefined;
@@ -387,6 +431,71 @@ function CesiumWidget(container, options) {
       }
     };
     scene.renderError.addEventListener(this._onRenderError);
+
+    let dataSourceCollection = options.dataSources;
+    let destroyDataSourceCollection = false;
+    if (!defined(dataSourceCollection)) {
+      dataSourceCollection = new DataSourceCollection();
+      destroyDataSourceCollection = true;
+    }
+
+    const dataSourceDisplay = new DataSourceDisplay({
+      scene: scene,
+      dataSourceCollection: dataSourceCollection,
+    });
+
+    const eventHelper = new EventHelper();
+    this._dataSourceChangedListeners = {};
+    this._automaticallyTrackDataSourceClocks =
+      options.automaticallyTrackDataSourceClocks ?? true;
+
+    this._dataSourceCollection = dataSourceCollection;
+    this._destroyDataSourceCollection = destroyDataSourceCollection;
+    this._dataSourceDisplay = dataSourceDisplay;
+    this._eventHelper = eventHelper;
+    this._canAnimateUpdateCallback = this._updateCanAnimate;
+
+    eventHelper.add(this._clock.onTick, CesiumWidget.prototype._onTick, this);
+    eventHelper.add(
+      scene.morphStart,
+      CesiumWidget.prototype._clearTrackedObject,
+      this,
+    );
+
+    //Listen to data source events in order to track clock changes.
+    eventHelper.add(
+      dataSourceCollection.dataSourceAdded,
+      CesiumWidget.prototype._onDataSourceAdded,
+      this,
+    );
+    eventHelper.add(
+      dataSourceCollection.dataSourceRemoved,
+      CesiumWidget.prototype._onDataSourceRemoved,
+      this,
+    );
+
+    eventHelper.add(scene.postRender, CesiumWidget.prototype._postRender, this);
+
+    // We need to subscribe to the data sources and collections so that we can clear the
+    // tracked object when it is removed from the scene.
+    // Subscribe to current data sources
+    const dataSourceLength = dataSourceCollection.length;
+    for (let i = 0; i < dataSourceLength; i++) {
+      this._dataSourceAdded(dataSourceCollection, dataSourceCollection.get(i));
+    }
+    this._dataSourceAdded(undefined, dataSourceDisplay.defaultDataSource);
+
+    // Hook up events so that we can subscribe to future sources.
+    eventHelper.add(
+      dataSourceCollection.dataSourceAdded,
+      CesiumWidget.prototype._dataSourceAdded,
+      this,
+    );
+    eventHelper.add(
+      dataSourceCollection.dataSourceRemoved,
+      CesiumWidget.prototype._dataSourceRemoved,
+      this,
+    );
   } catch (error) {
     if (showRenderLoopErrors) {
       const title = "Error constructing CesiumWidget.";
@@ -504,6 +613,43 @@ Object.defineProperties(CesiumWidget.prototype, {
     },
   },
 
+  /**
+   * Gets the display used for {@link DataSource} visualization.
+   * @memberof CesiumWidget.prototype
+   * @type {DataSourceDisplay}
+   * @readonly
+   */
+  dataSourceDisplay: {
+    get: function () {
+      return this._dataSourceDisplay;
+    },
+  },
+
+  /**
+   * Gets the collection of entities not tied to a particular data source.
+   * This is a shortcut to [dataSourceDisplay.defaultDataSource.entities]{@link CesiumWidget#dataSourceDisplay}.
+   * @memberof CesiumWidget.prototype
+   * @type {EntityCollection}
+   * @readonly
+   */
+  entities: {
+    get: function () {
+      return this._dataSourceDisplay.defaultDataSource.entities;
+    },
+  },
+
+  /**
+   * Gets the set of {@link DataSource} instances to be visualized.
+   * @memberof CesiumWidget.prototype
+   * @type {DataSourceCollection}
+   * @readonly
+   */
+  dataSources: {
+    get: function () {
+      return this._dataSourceCollection;
+    },
+  },
+
   /**
    * Gets the camera.
    * @memberof CesiumWidget.prototype
@@ -573,7 +719,7 @@ Object.defineProperties(CesiumWidget.prototype, {
       //>>includeStart('debug', pragmas.debug);
       if (value <= 0) {
         throw new DeveloperError(
-          "targetFrameRate must be greater than 0, or undefined."
+          "targetFrameRate must be greater than 0, or undefined.",
         );
       }
       //>>includeEnd('debug');
@@ -661,6 +807,104 @@ Object.defineProperties(CesiumWidget.prototype, {
       }
     },
   },
+
+  /**
+   * Gets or sets whether or not data sources can temporarily pause
+   * animation in order to avoid showing an incomplete picture to the user.
+   * For example, if asynchronous primitives are being processed in the
+   * background, the clock will not advance until the geometry is ready.
+   *
+   * @memberof CesiumWidget.prototype
+   *
+   * @type {boolean}
+   */
+  allowDataSourcesToSuspendAnimation: {
+    get: function () {
+      return this._allowDataSourcesToSuspendAnimation;
+    },
+    set: function (value) {
+      this._allowDataSourcesToSuspendAnimation = value;
+    },
+  },
+
+  /**
+   * Gets or sets the Entity instance currently being tracked by the camera.
+   * @memberof CesiumWidget.prototype
+   * @type {Entity | undefined}
+   */
+  trackedEntity: {
+    get: function () {
+      return this._trackedEntity;
+    },
+    set: function (value) {
+      if (this._trackedEntity !== value) {
+        this._trackedEntity = value;
+
+        //Cancel any pending zoom
+        cancelZoom(this);
+
+        const scene = this.scene;
+        const sceneMode = scene.mode;
+
+        //Stop tracking
+        if (!defined(value) || !defined(value.position)) {
+          this._needTrackedEntityUpdate = false;
+          if (
+            sceneMode === SceneMode.COLUMBUS_VIEW ||
+            sceneMode === SceneMode.SCENE2D
+          ) {
+            scene.screenSpaceCameraController.enableTranslate = true;
+          }
+
+          if (
+            sceneMode === SceneMode.COLUMBUS_VIEW ||
+            sceneMode === SceneMode.SCENE3D
+          ) {
+            scene.screenSpaceCameraController.enableTilt = true;
+          }
+
+          this._entityView = undefined;
+          this.camera.lookAtTransform(Matrix4.IDENTITY);
+        } else {
+          //We can't start tracking immediately, so we set a flag and start tracking
+          //when the bounding sphere is ready (most likely next frame).
+          this._needTrackedEntityUpdate = true;
+        }
+
+        this._trackedEntityChanged.raiseEvent(value);
+        this.scene.requestRender();
+      }
+    },
+  },
+
+  /**
+   * Gets the event that is raised when the tracked entity changes.
+   * @memberof CesiumWidget.prototype
+   * @type {Event}
+   * @readonly
+   */
+  trackedEntityChanged: {
+    get: function () {
+      return this._trackedEntityChanged;
+    },
+  },
+
+  /**
+   * Gets or sets the data source to track with the widget's clock.
+   * @memberof CesiumWidget.prototype
+   * @type {DataSource}
+   */
+  clockTrackedDataSource: {
+    get: function () {
+      return this._clockTrackedDataSource;
+    },
+    set: function (value) {
+      if (this._clockTrackedDataSource !== value) {
+        this._clockTrackedDataSource = value;
+        trackDataSourceClock(this.clock, value);
+      }
+    },
+  },
 });
 
 /**
@@ -693,7 +937,7 @@ CesiumWidget.prototype.showErrorPanel = function (title, message, error) {
   function resizeCallback() {
     errorPanelScroller.style.maxHeight = `${Math.max(
       Math.round(element.clientHeight * 0.9 - 100),
-      30
+      30,
     )}px`;
   }
   resizeCallback();
@@ -784,12 +1028,29 @@ CesiumWidget.prototype.isDestroyed = function () {
  * removing the widget from layout.
  */
 CesiumWidget.prototype.destroy = function () {
+  // Unsubscribe from data sources
+  const dataSources = this.dataSources;
+  const dataSourceLength = dataSources.length;
+  for (let i = 0; i < dataSourceLength; i++) {
+    this._dataSourceRemoved(dataSources, dataSources.get(i));
+  }
+  this._dataSourceRemoved(undefined, this._dataSourceDisplay.defaultDataSource);
+
+  this._dataSourceDisplay = this._dataSourceDisplay.destroy();
+
   if (defined(this._scene)) {
     this._scene.renderError.removeEventListener(this._onRenderError);
     this._scene = this._scene.destroy();
   }
   this._container.removeChild(this._element);
   this._creditContainer.removeChild(this._innerCreditContainer);
+
+  this._eventHelper.removeAll();
+
+  if (this._destroyDataSourceCollection) {
+    this._dataSourceCollection = this._dataSourceCollection.destroy();
+  }
+
   destroyObject(this);
 };
 
@@ -829,4 +1090,519 @@ CesiumWidget.prototype.render = function () {
     this._clock.tick();
   }
 };
+
+/**
+ * @private
+ */
+CesiumWidget.prototype._dataSourceAdded = function (
+  dataSourceCollection,
+  dataSource,
+) {
+  const entityCollection = dataSource.entities;
+  entityCollection.collectionChanged.addEventListener(
+    CesiumWidget.prototype._onEntityCollectionChanged,
+    this,
+  );
+};
+
+/**
+ * @private
+ */
+CesiumWidget.prototype._dataSourceRemoved = function (
+  dataSourceCollection,
+  dataSource,
+) {
+  const entityCollection = dataSource.entities;
+  entityCollection.collectionChanged.removeEventListener(
+    CesiumWidget.prototype._onEntityCollectionChanged,
+    this,
+  );
+
+  if (defined(this.trackedEntity)) {
+    if (
+      entityCollection.getById(this.trackedEntity.id) === this.trackedEntity
+    ) {
+      this.trackedEntity = undefined;
+    }
+  }
+};
+
+/**
+ * @private
+ */
+CesiumWidget.prototype._updateCanAnimate = function (isUpdated) {
+  this._clock.canAnimate = isUpdated;
+};
+
+const boundingSphereScratch = new BoundingSphere();
+
+/**
+ * @private
+ */
+CesiumWidget.prototype._onTick = function (clock) {
+  const time = clock.currentTime;
+
+  const isUpdated = this._dataSourceDisplay.update(time);
+  if (this._allowDataSourcesToSuspendAnimation) {
+    this._canAnimateUpdateCallback(isUpdated);
+  }
+
+  const entityView = this._entityView;
+  if (defined(entityView)) {
+    const trackedEntity = this._trackedEntity;
+    const trackedState = this._dataSourceDisplay.getBoundingSphere(
+      trackedEntity,
+      true,
+      boundingSphereScratch,
+    );
+    if (trackedState === BoundingSphereState.DONE) {
+      entityView.update(time, boundingSphereScratch);
+    }
+  }
+};
+
+/**
+ * @private
+ */
+CesiumWidget.prototype._onEntityCollectionChanged = function (
+  collection,
+  added,
+  removed,
+) {
+  const length = removed.length;
+  for (let i = 0; i < length; i++) {
+    const removedObject = removed[i];
+    if (this.trackedEntity === removedObject) {
+      this.trackedEntity = undefined;
+    }
+  }
+};
+
+/**
+ * @private
+ */
+CesiumWidget.prototype._clearTrackedObject = function () {
+  this.trackedEntity = undefined;
+};
+
+/**
+ * @private
+ */
+CesiumWidget.prototype._onDataSourceChanged = function (dataSource) {
+  if (this.clockTrackedDataSource === dataSource) {
+    trackDataSourceClock(this.clock, dataSource);
+  }
+};
+
+/**
+ * @private
+ */
+CesiumWidget.prototype._onDataSourceAdded = function (
+  dataSourceCollection,
+  dataSource,
+) {
+  if (this._automaticallyTrackDataSourceClocks) {
+    this.clockTrackedDataSource = dataSource;
+  }
+  const id = dataSource.entities.id;
+  const removalFunc = this._eventHelper.add(
+    dataSource.changedEvent,
+    CesiumWidget.prototype._onDataSourceChanged,
+    this,
+  );
+  this._dataSourceChangedListeners[id] = removalFunc;
+};
+
+/**
+ * @private
+ */
+CesiumWidget.prototype._onDataSourceRemoved = function (
+  dataSourceCollection,
+  dataSource,
+) {
+  const resetClock = this.clockTrackedDataSource === dataSource;
+  const id = dataSource.entities.id;
+  this._dataSourceChangedListeners[id]();
+  this._dataSourceChangedListeners[id] = undefined;
+  if (resetClock) {
+    const numDataSources = dataSourceCollection.length;
+    if (this._automaticallyTrackDataSourceClocks && numDataSources > 0) {
+      this.clockTrackedDataSource = dataSourceCollection.get(
+        numDataSources - 1,
+      );
+    } else {
+      this.clockTrackedDataSource = undefined;
+    }
+  }
+};
+
+/**
+ * Asynchronously sets the camera to view the provided entity, entities, or data source.
+ * If the data source is still in the process of loading or the visualization is otherwise still loading,
+ * this method waits for the data to be ready before performing the zoom.
+ *
+ * <p>The offset is heading/pitch/range in the local east-north-up reference frame centered at the center of the bounding sphere.
+ * The heading and the pitch angles are defined in the local east-north-up reference frame.
+ * The heading is the angle from y axis and increasing towards the x axis. Pitch is the rotation from the xy-plane. Positive pitch
+ * angles are above the plane. Negative pitch angles are below the plane. The range is the distance from the center. If the range is
+ * zero, a range will be computed such that the whole bounding sphere is visible.</p>
+ *
+ * <p>In 2D, there must be a top down view. The camera will be placed above the target looking down. The height above the
+ * target will be the range. The heading will be determined from the offset. If the heading cannot be
+ * determined from the offset, the heading will be north.</p>
+ *
+ * @param {Entity|Entity[]|EntityCollection|DataSource|ImageryLayer|Cesium3DTileset|TimeDynamicPointCloud|Promise<Entity|Entity[]|EntityCollection|DataSource|ImageryLayer|Cesium3DTileset|TimeDynamicPointCloud|VoxelPrimitive>} target The entity, array of entities, entity collection, data source, Cesium3DTileset, point cloud, or imagery layer to view. You can also pass a promise that resolves to one of the previously mentioned types.
+ * @param {HeadingPitchRange} [offset] The offset from the center of the entity in the local east-north-up reference frame.
+ * @returns {Promise<boolean>} A Promise that resolves to true if the zoom was successful or false if the target is not currently visualized in the scene or the zoom was cancelled.
+ */
+CesiumWidget.prototype.zoomTo = function (target, offset) {
+  const options = {
+    offset: offset,
+  };
+  return zoomToOrFly(this, target, options, false);
+};
+
+/**
+ * Flies the camera to the provided entity, entities, or data source.
+ * If the data source is still in the process of loading or the visualization is otherwise still loading,
+ * this method waits for the data to be ready before performing the flight.
+ *
+ * <p>The offset is heading/pitch/range in the local east-north-up reference frame centered at the center of the bounding sphere.
+ * The heading and the pitch angles are defined in the local east-north-up reference frame.
+ * The heading is the angle from y axis and increasing towards the x axis. Pitch is the rotation from the xy-plane. Positive pitch
+ * angles are above the plane. Negative pitch angles are below the plane. The range is the distance from the center. If the range is
+ * zero, a range will be computed such that the whole bounding sphere is visible.</p>
+ *
+ * <p>In 2D, there must be a top down view. The camera will be placed above the target looking down. The height above the
+ * target will be the range. The heading will be determined from the offset. If the heading cannot be
+ * determined from the offset, the heading will be north.</p>
+ *
+ * @param {Entity|Entity[]|EntityCollection|DataSource|ImageryLayer|Cesium3DTileset|TimeDynamicPointCloud|Promise<Entity|Entity[]|EntityCollection|DataSource|ImageryLayer|Cesium3DTileset|TimeDynamicPointCloud|VoxelPrimitive>} target The entity, array of entities, entity collection, data source, Cesium3DTileset, point cloud, or imagery layer to view. You can also pass a promise that resolves to one of the previously mentioned types.
+ * @param {object} [options] Object with the following properties:
+ * @param {number} [options.duration=3.0] The duration of the flight in seconds.
+ * @param {number} [options.maximumHeight] The maximum height at the peak of the flight.
+ * @param {HeadingPitchRange} [options.offset] The offset from the target in the local east-north-up reference frame centered at the target.
+ * @returns {Promise<boolean>} A Promise that resolves to true if the flight was successful or false if the target is not currently visualized in the scene or the flight was cancelled. //TODO: Cleanup entity mentions
+ */
+CesiumWidget.prototype.flyTo = function (target, options) {
+  return zoomToOrFly(this, target, options, true);
+};
+
+function zoomToOrFly(that, zoomTarget, options, isFlight) {
+  //>>includeStart('debug', pragmas.debug);
+  if (!defined(zoomTarget)) {
+    throw new DeveloperError("zoomTarget is required.");
+  }
+  //>>includeEnd('debug');
+
+  cancelZoom(that);
+
+  //We can't actually perform the zoom until all visualization is ready and
+  //bounding spheres have been computed.  Therefore we create and return
+  //a deferred which will be resolved as part of the post-render step in the
+  //frame that actually performs the zoom.
+  const zoomPromise = new Promise((resolve) => {
+    that._completeZoom = function (value) {
+      resolve(value);
+    };
+  });
+  that._zoomPromise = zoomPromise;
+  that._zoomIsFlight = isFlight;
+  that._zoomOptions = options;
+
+  Promise.resolve(zoomTarget).then(function (zoomTarget) {
+    //Only perform the zoom if it wasn't cancelled before the promise resolved.
+    if (that._zoomPromise !== zoomPromise) {
+      return;
+    }
+
+    //If the zoom target is a rectangular imagery in an ImageLayer
+    if (zoomTarget instanceof ImageryLayer) {
+      let rectanglePromise;
+
+      if (defined(zoomTarget.imageryProvider)) {
+        rectanglePromise = Promise.resolve(zoomTarget.getImageryRectangle());
+      } else {
+        rectanglePromise = new Promise((resolve) => {
+          const removeListener = zoomTarget.readyEvent.addEventListener(() => {
+            removeListener();
+            resolve(zoomTarget.getImageryRectangle());
+          });
+        });
+      }
+      rectanglePromise
+        .then(function (rectangle) {
+          return computeFlyToLocationForRectangle(rectangle, that.scene);
+        })
+        .then(function (position) {
+          //Only perform the zoom if it wasn't cancelled before the promise was resolved
+          if (that._zoomPromise === zoomPromise) {
+            that._zoomTarget = position;
+          }
+        });
+      return;
+    }
+
+    if (
+      zoomTarget instanceof Cesium3DTileset ||
+      zoomTarget instanceof TimeDynamicPointCloud ||
+      zoomTarget instanceof VoxelPrimitive
+    ) {
+      that._zoomTarget = zoomTarget;
+      return;
+    }
+
+    //If the zoom target is a data source, and it's in the middle of loading, wait for it to finish loading.
+    if (zoomTarget.isLoading && defined(zoomTarget.loadingEvent)) {
+      const removeEvent = zoomTarget.loadingEvent.addEventListener(function () {
+        removeEvent();
+
+        //Only perform the zoom if it wasn't cancelled before the data source finished.
+        if (that._zoomPromise === zoomPromise) {
+          that._zoomTarget = zoomTarget.entities.values.slice(0);
+        }
+      });
+      return;
+    }
+
+    //Zoom target is already an array, just copy it and return.
+    if (Array.isArray(zoomTarget)) {
+      that._zoomTarget = zoomTarget.slice(0);
+      return;
+    }
+
+    //If zoomTarget is an EntityCollection, this will retrieve the array
+    zoomTarget = zoomTarget.values ?? zoomTarget;
+
+    //If zoomTarget is a DataSource, this will retrieve the array.
+    if (defined(zoomTarget.entities)) {
+      zoomTarget = zoomTarget.entities.values;
+    }
+
+    //Zoom target is already an array, just copy it and return.
+    if (Array.isArray(zoomTarget)) {
+      that._zoomTarget = zoomTarget.slice(0);
+    } else {
+      //Single entity
+      that._zoomTarget = [zoomTarget];
+    }
+  });
+
+  that.scene.requestRender();
+  return zoomPromise;
+}
+
+function clearZoom(widget) {
+  widget._zoomPromise = undefined;
+  widget._zoomTarget = undefined;
+  widget._zoomOptions = undefined;
+}
+
+function cancelZoom(widget) {
+  const zoomPromise = widget._zoomPromise;
+  if (defined(zoomPromise)) {
+    clearZoom(widget);
+    widget._completeZoom(false);
+  }
+}
+
+/**
+ * @private
+ */
+CesiumWidget.prototype._postRender = function () {
+  updateZoomTarget(this);
+  updateTrackedEntity(this);
+};
+
+function updateZoomTarget(widget) {
+  const target = widget._zoomTarget;
+  if (!defined(target) || widget.scene.mode === SceneMode.MORPHING) {
+    return;
+  }
+
+  const scene = widget.scene;
+  const camera = scene.camera;
+  const zoomOptions = widget._zoomOptions ?? {};
+  let options;
+  function zoomToBoundingSphere(boundingSphere) {
+    // If offset was originally undefined then give it base value instead of empty object
+    if (!defined(zoomOptions.offset)) {
+      zoomOptions.offset = new HeadingPitchRange(
+        0.0,
+        -0.5,
+        boundingSphere.radius,
+      );
+    }
+
+    options = {
+      offset: zoomOptions.offset,
+      duration: zoomOptions.duration,
+      maximumHeight: zoomOptions.maximumHeight,
+      complete: function () {
+        widget._completeZoom(true);
+      },
+      cancel: function () {
+        widget._completeZoom(false);
+      },
+    };
+
+    if (widget._zoomIsFlight) {
+      camera.flyToBoundingSphere(target.boundingSphere, options);
+    } else {
+      camera.viewBoundingSphere(boundingSphere, zoomOptions.offset);
+      camera.lookAtTransform(Matrix4.IDENTITY);
+
+      // Finish the promise
+      widget._completeZoom(true);
+    }
+
+    clearZoom(widget);
+  }
+
+  if (target instanceof TimeDynamicPointCloud) {
+    if (defined(target.boundingSphere)) {
+      zoomToBoundingSphere(target.boundingSphere);
+      return;
+    }
+
+    // Otherwise, the first "frame" needs to have been rendered
+    const removeEventListener = target.frameChanged.addEventListener(
+      function (timeDynamicPointCloud) {
+        zoomToBoundingSphere(timeDynamicPointCloud.boundingSphere);
+        removeEventListener();
+      },
+    );
+    return;
+  }
+
+  if (target instanceof Cesium3DTileset || target instanceof VoxelPrimitive) {
+    zoomToBoundingSphere(target.boundingSphere);
+    return;
+  }
+
+  // If zoomTarget was an ImageryLayer
+  if (target instanceof Cartographic) {
+    options = {
+      destination: scene.ellipsoid.cartographicToCartesian(target),
+      duration: zoomOptions.duration,
+      maximumHeight: zoomOptions.maximumHeight,
+      complete: function () {
+        widget._completeZoom(true);
+      },
+      cancel: function () {
+        widget._completeZoom(false);
+      },
+    };
+
+    if (widget._zoomIsFlight) {
+      camera.flyTo(options);
+    } else {
+      camera.setView(options);
+      widget._completeZoom(true);
+    }
+    clearZoom(widget);
+    return;
+  }
+
+  const entities = target;
+
+  const boundingSpheres = [];
+  for (let i = 0, len = entities.length; i < len; i++) {
+    const state = widget._dataSourceDisplay.getBoundingSphere(
+      entities[i],
+      false,
+      boundingSphereScratch,
+    );
+
+    if (state === BoundingSphereState.PENDING) {
+      return;
+    } else if (state !== BoundingSphereState.FAILED) {
+      boundingSpheres.push(BoundingSphere.clone(boundingSphereScratch));
+    }
+  }
+
+  if (boundingSpheres.length === 0) {
+    cancelZoom(widget);
+    return;
+  }
+
+  // Stop tracking the current entity.
+  widget.trackedEntity = undefined;
+
+  const boundingSphere = BoundingSphere.fromBoundingSpheres(boundingSpheres);
+
+  if (!widget._zoomIsFlight) {
+    camera.viewBoundingSphere(boundingSphere, zoomOptions.offset);
+    camera.lookAtTransform(Matrix4.IDENTITY);
+    clearZoom(widget);
+    widget._completeZoom(true);
+  } else {
+    clearZoom(widget);
+    camera.flyToBoundingSphere(boundingSphere, {
+      duration: zoomOptions.duration,
+      maximumHeight: zoomOptions.maximumHeight,
+      complete: function () {
+        widget._completeZoom(true);
+      },
+      cancel: function () {
+        widget._completeZoom(false);
+      },
+      offset: zoomOptions.offset,
+    });
+  }
+}
+
+function updateTrackedEntity(widget) {
+  if (!widget._needTrackedEntityUpdate) {
+    return;
+  }
+
+  const trackedEntity = widget._trackedEntity;
+  const currentTime = widget.clock.currentTime;
+
+  //Verify we have a current position at this time. This is only triggered if a position
+  //has become undefined after trackedEntity is set but before the boundingSphere has been
+  //computed. In this case, we will track the entity once it comes back into existence.
+  const currentPosition = Property.getValueOrUndefined(
+    trackedEntity.position,
+    currentTime,
+  );
+
+  if (!defined(currentPosition)) {
+    return;
+  }
+
+  const scene = widget.scene;
+
+  const state = widget._dataSourceDisplay.getBoundingSphere(
+    trackedEntity,
+    false,
+    boundingSphereScratch,
+  );
+  if (state === BoundingSphereState.PENDING) {
+    return;
+  }
+
+  const sceneMode = scene.mode;
+  if (
+    sceneMode === SceneMode.COLUMBUS_VIEW ||
+    sceneMode === SceneMode.SCENE2D
+  ) {
+    scene.screenSpaceCameraController.enableTranslate = false;
+  }
+
+  if (
+    sceneMode === SceneMode.COLUMBUS_VIEW ||
+    sceneMode === SceneMode.SCENE3D
+  ) {
+    scene.screenSpaceCameraController.enableTilt = false;
+  }
+
+  const bs =
+    state !== BoundingSphereState.FAILED ? boundingSphereScratch : undefined;
+  widget._entityView = new EntityView(trackedEntity, scene, scene.ellipsoid);
+  widget._entityView.update(currentTime, bs);
+  widget._needTrackedEntityUpdate = false;
+}
+
 export default CesiumWidget;