Merge pull request #10260 from thw0rted/kml-optional-camera

Don't require KMLDataSource canvas+camera
CesiumGS · Apr 6, 2022 · 41fc35d · 41fc35d
2 parents cdb7283 + cfb0525
commit 41fc35d
Show file tree

Hide file tree

Showing 4 changed files with 93 additions and 81 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -4,6 +4,7 @@
 
 ##### Additions :tada:
 
+- `KmlDataSource` now exposes the `camera` and `canvas` properties, which are used to provide information about the state of the Viewer when making network requests for a [Link](https://developers.google.com/kml/documentation/kmlreference#link). Passing these values in the constructor is now optional.
 - Added support for morph targets in `ModelExperimental`. [#10271](https://github.com/CesiumGS/cesium/pull/10271)
 
 ##### Fixes :wrench:

diff --git a/Source/.eslintrc.json b/Source/.eslintrc.json
@@ -1,7 +1,7 @@
 {
     "root": true,
     "extends": [
-        "../Tools/eslint-config-cesium/browser.js", 
+        "../Tools/eslint-config-cesium/browser.js",
         "prettier",
         "plugin:es/restrict-to-es5"
     ],
@@ -15,6 +15,7 @@
         "es/no-typed-arrays": "off",
         "es/no-block-scoped-variables": "off",
         "es/no-template-literals": "off",
-        "es/no-promise": "off"
+        "es/no-promise": "off",
+        "es/no-object-assign": "off"
     }
 }
diff --git a/Source/DataSources/KmlDataSource.js b/Source/DataSources/KmlDataSource.js
@@ -906,8 +906,8 @@ function getIconHref(
     const ellipsoid = dataSource._ellipsoid;
     processNetworkLinkQueryString(
       hrefResource,
-      dataSource._camera,
-      dataSource._canvas,
+      dataSource.camera,
+      dataSource.canvas,
       viewBoundScale,
       dataSource._lastCameraView.bbox,
       ellipsoid
@@ -3110,8 +3110,8 @@ function processNetworkLink(dataSource, node, processingData, deferredLoading) {
         const ellipsoid = dataSource._ellipsoid;
         processNetworkLinkQueryString(
           href,
-          dataSource._camera,
-          dataSource._canvas,
+          dataSource.camera,
+          dataSource.canvas,
           viewBoundScale,
           dataSource._lastCameraView.bbox,
           ellipsoid
@@ -3234,7 +3234,7 @@ function processNetworkLink(dataSource, node, processingData, deferredLoading) {
                   "KML - refreshMode of onExpire requires the NetworkLinkControl to have an expires element"
                 );
               }
-            } else if (dataSource._camera) {
+            } else if (defined(dataSource.camera)) {
               // Only allow onStop refreshes if we have a camera
               networkLinkInfo.refreshMode = RefreshMode.STOP;
               networkLinkInfo.time = defaultValue(
@@ -3244,7 +3244,7 @@ function processNetworkLink(dataSource, node, processingData, deferredLoading) {
             } else {
               oneTimeWarning(
                 "kml-refrehMode-onStop-noCamera",
-                "A NetworkLink with viewRefreshMode=onStop requires a camera be passed in when creating the KmlDataSource"
+                "A NetworkLink with viewRefreshMode=onStop requires the `camera` property to be defined."
               );
             }
 
@@ -3530,20 +3530,37 @@ function load(dataSource, entityCollection, data, options) {
     });
 }
 
+// NOTE: LoadOptions properties are repeated in ConstructorOptions because some
+// tooling does not support "base types" for @typedef.  Remove if/when
+// https://github.com/microsoft/TypeScript/issues/20077 and/or
+// https://github.com/jsdoc/jsdoc/issues/1199 actually get resolved
 /**
  * @typedef {Object} KmlDataSource.LoadOptions
  *
  * Initialization options for the `load` method.
  *
- * @property {Camera} camera The camera that is used for viewRefreshModes and sending camera properties to network links.
- * @property {HTMLCanvasElement} canvas The canvas that is used for sending viewer properties to network links.
  * @property {String} [sourceUri] Overrides the url to use for resolving relative links and other KML network features.
  * @property {Boolean} [clampToGround=false] true if we want the geometry features (Polygons, LineStrings and LinearRings) clamped to the ground.
  * @property {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The global ellipsoid used for geographical calculations.
- * @property {Credit|String} [credit] A credit for the data source, which is displayed on the canvas.
  * @property {Element|String} [screenOverlayContainer] A container for ScreenOverlay images.
  */
 
+/**
+ * @typedef {Object} KmlDataSource.ConstructorOptions
+ *
+ * Options for constructing a new KmlDataSource, or calling the static `load` method.
+ *
+ * @property {Camera} [camera] The camera that is used for viewRefreshModes and sending camera properties to network links.
+ * @property {HTMLCanvasElement} [canvas] The canvas that is used for sending viewer properties to network links.
+ * @property {Credit|String} [credit] A credit for the data source, which is displayed on the canvas.
+ *
+ * @property {String} [sourceUri] Overrides the url to use for resolving relative links and other KML network features.
+ * @property {Boolean} [clampToGround=false] true if we want the geometry features (Polygons, LineStrings and LinearRings) clamped to the ground.
+ * @property {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The global ellipsoid used for geographical calculations.
+ * @property {Element|String} [screenOverlayContainer] A container for ScreenOverlay images.
+
+*/
+
 /**
  * A {@link DataSource} which processes Keyhole Markup Language 2.2 (KML).
  * <p>
@@ -3562,11 +3579,7 @@ function load(dataSource, entityCollection, data, options) {
  * @alias KmlDataSource
  * @constructor
  *
- * @param {Object} options An object with the following properties:
- * @param {Camera} options.camera The camera that is used for viewRefreshModes and sending camera properties to network links.
- * @param {HTMLCanvasElement} options.canvas The canvas that is used for sending viewer properties to network links.
- * @param {Ellipsoid} [options.ellipsoid=Ellipsoid.WGS84] The global ellipsoid used for geographical calculations.
- * @param {Credit|String} [options.credit] A credit for the data source, which is displayed on the canvas.
+ * @param {KmlDataSource.ConstructorOptions} [options] Object describing initialization options
  *
  * @see {@link http://www.opengeospatial.org/standards/kml/|Open Geospatial Consortium KML Standard}
  * @see {@link https://developers.google.com/kml/|Google KML Documentation}
@@ -3587,15 +3600,6 @@ function KmlDataSource(options) {
   const camera = options.camera;
   const canvas = options.canvas;
 
-  //>>includeStart('debug', pragmas.debug);
-  if (!defined(camera)) {
-    throw new DeveloperError("options.camera is required.");
-  }
-  if (!defined(canvas)) {
-    throw new DeveloperError("options.canvas is required.");
-  }
-  //>>includeEnd('debug');
-
   this._changed = new Event();
   this._error = new Event();
   this._loading = new Event();
@@ -3610,8 +3614,24 @@ function KmlDataSource(options) {
   this._networkLinks = new AssociativeArray();
   this._entityCluster = new EntityCluster();
 
-  this._canvas = canvas;
-  this._camera = camera;
+  /**
+   * The current size of this Canvas will be used to populate the Link parameters
+   * for client height and width.
+   *
+   * @type {HTMLCanvasElement | undefined}
+   */
+  this.canvas = canvas;
+
+  /**
+   * The position and orientation of this {@link Camera} will be used to
+   * populate various camera parameters when making network requests.
+   * Camera movement will determine when to trigger NetworkLink refresh if
+   * <code>viewRefreshMode</code> is <code>onStop</code>.
+   *
+   * @type {Camera | undefined}
+   */
+  this.camera = camera;
+
   this._lastCameraView = {
     position: defined(camera) ? Cartesian3.clone(camera.positionWC) : undefined,
     direction: defined(camera)
@@ -3644,7 +3664,7 @@ function KmlDataSource(options) {
  * Creates a Promise to a new instance loaded with the provided KML data.
  *
  * @param {Resource|String|Document|Blob} data A url, parsed KML document, or Blob containing binary KMZ data or a parsed KML document.
- * @param {KmlDataSource.LoadOptions} [options] An object specifying configuration options
+ * @param {KmlDataSource.ConstructorOptions} [options] An object specifying configuration options
  *
  * @returns {Promise.<KmlDataSource>} A promise that will resolve to a new KmlDataSource instance once the KML is loaded.
  */
@@ -3813,11 +3833,7 @@ Object.defineProperties(KmlDataSource.prototype, {
  * Asynchronously loads the provided KML data, replacing any existing data.
  *
  * @param {Resource|String|Document|Blob} data A url, parsed KML document, or Blob containing binary KMZ data or a parsed KML document.
- * @param {Object} [options] An object with the following properties:
- * @param {Resource|String} [options.sourceUri] Overrides the url to use for resolving relative links and other KML network features.
- * @param {Boolean} [options.clampToGround=false] true if we want the geometry features (Polygons, LineStrings and LinearRings) clamped to the ground. If true, lines will use corridors so use Entity.corridor instead of Entity.polyline.
- * @param {Ellipsoid} [options.ellipsoid=Ellipsoid.WGS84] The global ellipsoid used for geographical calculations.
- * @param {Element|String} [options.screenOverlayContainer] A container for ScreenOverlay images.
+ * @param {KmlDataSource.LoadOptions} [options] An object specifying configuration options
  *
  * @returns {Promise.<KmlDataSource>} A promise that will resolve to this instances once the KML is loaded.
  */
@@ -4118,7 +4134,7 @@ KmlDataSource.prototype.update = function (time) {
 
   let cameraViewUpdate = false;
   const lastCameraView = this._lastCameraView;
-  const camera = this._camera;
+  const camera = this.camera;
   if (
     defined(camera) &&
     !(
@@ -4187,8 +4203,8 @@ KmlDataSource.prototype.update = function (time) {
         const ellipsoid = defaultValue(that._ellipsoid, Ellipsoid.WGS84);
         processNetworkLinkQueryString(
           href,
-          that._camera,
-          that._canvas,
+          that.camera,
+          that.canvas,
           networkLink.viewBoundScale,
           lastCameraView.bbox,
           ellipsoid