Custom DataSource【译】

原文链接及内容

原文链接：https://sandcastle.cesium.com/?src=Custom%20DataSource.html&label=All

效果如下图所示：

示例代码如下：

/**
 * 此类是自定义数据源(custom DataSource)的示例。
 * 它加载 Google WebGL Globe (https://github.com/dataarts/webgl-globe) 定义的 JSON 数据。
 * 
 * @alias WebGLGlobeDataSource
 * @constructor
 *
 * @param {string} [name] 此数据源的名称。如果未定义，则将从 URL 中获取名称。
 *
 * @example 使用示例如下：
 * const dataSource = new Cesium.WebGLGlobeDataSource();
 * dataSource.loadUrl('sample.json');
 * viewer.dataSources.add(dataSource);
 */
function WebGLGlobeDataSource(name) {
  //所有公共配置都定义为 ES5 属性，这些只是“私有”变量及其默认值。
  this._name = name;
  this._changed = new Cesium.Event();
  this._error = new Cesium.Event();
  this._isLoading = false;
  this._loading = new Cesium.Event();
  this._entityCollection = new Cesium.EntityCollection();
  this._seriesNames = [];
  this._seriesToDisplay = undefined;
  this._heightScale = 10000000;
  this._entityCluster = new Cesium.EntityCluster();
}

Object.defineProperties(WebGLGlobeDataSource.prototype, {
  //所有 DataSource 实例必须实现以下属性

  /**
   * 获取此实例的可读名称。
   * @memberof WebGLGlobeDataSource.prototype
   * @type {String}
   */
  name: {
    get: function () {
      return this._name;
    },
  },
  /**
   * 由于 WebGL 地球 JSON 不是时间动态的，因此此属性始终为 undefined。
   * @memberof WebGLGlobeDataSource.prototype
   * @type {DataSourceClock}
   */
  clock: {
    value: undefined,
    writable: false,
  },
  /**
   * 获取 Entity 实例的集合。
   * @memberof WebGLGlobeDataSource.prototype
   * @type {EntityCollection}
   */
  entities: {
    get: function () {
      return this._entityCollection;
    },
  },
  /**
   * 获取一个值，指示数据源当前是否正在加载数据。
   * @memberof WebGLGlobeDataSource.prototype
   * @type {Boolean}
   */
  isLoading: {
    get: function () {
      return this._isLoading;
    },
  },
  /**
   * 获取一个事件，当底层数据发生变化时会触发该事件。
   * @memberof WebGLGlobeDataSource.prototype
   * @type {Event}
   */
  changedEvent: {
    get: function () {
      return this._changed;
    },
  },
  /**
   * 获取一个事件，该事件将在处理过程中遇到错误时触发。
   * @memberof WebGLGlobeDataSource.prototype
   * @type {Event}
   */
  errorEvent: {
    get: function () {
      return this._error;
    },
  },
  /**
   * 获取一个事件，该事件将在数据源开始或停止加载时触发。
   * @memberof WebGLGlobeDataSource.prototype
   * @type {Event}
   */
  loadingEvent: {
    get: function () {
      return this._loading;
    },
  },

  //这些属性仅适用于此数据源。

  /**
   * 获取系列名称数组。
   * @memberof WebGLGlobeDataSource.prototype
   * @type {string[]}
   */
  seriesNames: {
    get: function () {
      return this._seriesNames;
    },
  },
  /**
   * 获取或设置要显示的系列名称。WebGL JSON 设计为一次仅查看一个系列。有效值在 seriesNames 属性中定义。
   * @memberof WebGLGlobeDataSource.prototype
   * @type {String}
   */
  seriesToDisplay: {
    get: function () {
      return this._seriesToDisplay;
    },
    set: function (value) {
      this._seriesToDisplay = value;

      //遍历所有实体，如果它们属于当前系列，则将它们的 show 属性设置为 true。
      const collection = this._entityCollection;
      const entities = collection.values;
      collection.suspendEvents();
      for (let i = 0; i < entities.length; i++) {
        const entity = entities[i];
        entity.show = value === entity.seriesName;
      }
      collection.resumeEvents();
    },
  },
  /**
   * 获取或设置应用于每条线的高度的比例因子。
   * @memberof WebGLGlobeDataSource.prototype
   * @type {Number}
   */
  heightScale: {
    get: function () {
      return this._heightScale;
    },
    set: function (value) {
      if (value <= 0) {
        throw new Cesium.DeveloperError("值必须大于 0");
      }
      this._heightScale = value;
    },
  },
  /**
   * 获取是否应显示此数据源。
   * @memberof WebGLGlobeDataSource.prototype
   * @type {Boolean}
   */
  show: {
    get: function () {
      return this._entityCollection;
    },
    set: function (value) {
      this._entityCollection = value;
    },
  },
  /**
   * 获取或设置此数据源的聚类选项。该对象可以在多个数据源之间共享。
   * @memberof WebGLGlobeDataSource.prototype
   * @type {EntityCluster}
   */
  clustering: {
    get: function () {
      return this._entityCluster;
    },
    set: function (value) {
      if (!Cesium.defined(value)) {
        throw new Cesium.DeveloperError("value must be defined.");
      }
      this._entityCluster = value;
    },
  },
});

/**
 * 在提供的 URL 处异步加载 GeoJSON，替换任何现有数据。
 * @param {object} url 要处理的 URL。
 * @returns {Promise} 一个 Promise，该 Promise 将在加载 GeoJSON 时解析。
 */
WebGLGlobeDataSource.prototype.loadUrl = function (url) {
  if (!Cesium.defined(url)) {
    throw new Cesium.DeveloperError("url is required.");
  }

  //根据 URL 创建名称
  const name = Cesium.getFilenameFromUri(url);

  //如果名称与当前名称不同，请设置名称。
  if (this._name !== name) {
    this._name = name;
    this._changed.raiseEvent(this);
  }

  //将 URL 加载到 json 对象中，然后使用`load`函数处理。
  const that = this;
  return Cesium.Resource.fetchJson(url)
    .then(function (json) {
      return that.load(json, url);
    })
    .catch(function (error) {
      /**
       * 否则将在处理 Promise 期间捕获任何错误或异常。
       * 当这种情况发生时，我们将触发 error 事件并拒绝 Promise。
       */
      this._setLoading(false);
      that._error.raiseEvent(that, error);
      return Promise.reject(error);
    });
};

/**
 * 加载提供的数据，替换任何现有数据。
 * @param {Array} data 要处理的对象。
 */
WebGLGlobeDataSource.prototype.load = function (data) {
  //>>includeStart('debug', pragmas.debug);
  if (!Cesium.defined(data)) {
    throw new Cesium.DeveloperError("data is required.");
  }
  //>>includeEnd('debug');

  //清除可能已存在的任何数据。
  this._setLoading(true);
  this._seriesNames.length = 0;
  this._seriesToDisplay = undefined;

  const heightScale = this.heightScale;
  const entities = this._entityCollection;

  /**
   * 在对大量实体进行更改时，需要暂停事件处理。
   * 这会将事件批量处理为最少数量的函数调用，
   * 并在处理结束时统一触发（即调用 resumeEvents 时）。
   */
  entities.suspendEvents();
  entities.removeAll();

  /**
   * WebGL Globe JSON 是一个系列数组，其中每个系列本身是一个包含两个元素的数组，
   * 第一个元素包含系列名称，第二个元素是一个重复的纬度、经度、高度值数组。
   * 
   * 这里有一个更直观的例子。
   * [["series1",[latitude, longitude, height, ... ]
   *  ["series2",[latitude, longitude, height, ... ]]
   */
  // 遍历每个系列(series)
  for (let x = 0; x < data.length; x++) {
    const series = data[x];
    const seriesName = series[0];
    const coordinates = series[1];

    //将系列名称添加到可能的值列表中。
    this._seriesNames.push(seriesName);

    // 默认将第一个系列设为可见系列
    const show = x === 0;
    if (show) {
      this._seriesToDisplay = seriesName;
    }

    //现在遍历系列中的每个坐标，并从数据中创建实体。
    for (let i = 0; i < coordinates.length; i += 3) {
      const latitude = coordinates[i];
      const longitude = coordinates[i + 1];
      const height = coordinates[i + 2];

      //忽略高度为零的线。
      if (height === 0) {
        continue;
      }

      const color = Cesium.Color.fromHsl(0.6 - height * 0.5, 1.0, 0.5);
      const surfacePosition = Cesium.Cartesian3.fromDegrees(
        longitude,
        latitude,
        0,
      );
      const heightPosition = Cesium.Cartesian3.fromDegrees(
        longitude,
        latitude,
        height * heightScale,
      );

      //WebGL Globe 仅包含线，因此这是我们创建的唯一图形。
      const polyline = new Cesium.PolylineGraphics();
      polyline.material = new Cesium.ColorMaterialProperty(color);
      polyline.width = new Cesium.ConstantProperty(2);
      polyline.arcType = new Cesium.ConstantProperty(Cesium.ArcType.NONE);
      polyline.positions = new Cesium.ConstantProperty([
        surfacePosition,
        heightPosition,
      ]);

      //多段线实例本身需要依附于某个实体。
      const entity = new Cesium.Entity({
        id: `${seriesName} index ${i.toString()}`,
        show: show,
        polyline: polyline,
        seriesName: seriesName, //自定义属性，用于指示系列名称
      });

      //将实体添加到集合中。
      entities.add(entity);
    }
  }

  //所有数据处理完成后，调用 resumeEvents 方法并触发 changed 事件。
  entities.resumeEvents();
  this._changed.raiseEvent(this);
  this._setLoading(false);
};

WebGLGlobeDataSource.prototype._setLoading = function (isLoading) {
  if (this._isLoading !== isLoading) {
    this._isLoading = isLoading;
    this._loading.raiseEvent(this, isLoading);
  }
};

//现在我们已经定义了自己的 DataSource，我们可以使用它来加载任何格式化为 WebGL Globe 的 JSON 数据。
const dataSource = new WebGLGlobeDataSource();
dataSource.loadUrl("../SampleData/population909500.json").then(function () {
  //初始加载完成后，创建按钮让用户切换不同的系列。这里是切换不同年份的数据
  function createSeriesSetter(seriesName) {
    return function () {
      dataSource.seriesToDisplay = seriesName;
    };
  }

  for (let i = 0; i < dataSource.seriesNames.length; i++) {
    const seriesName = dataSource.seriesNames[i];
    Sandcastle.addToolbarButton(seriesName, createSeriesSetter(seriesName));
  }
});

//创建一个Viewer实例对象，并添加自定义数据源(DataSource)对象。
const viewer = new Cesium.Viewer("cesiumContainer", {
  geocoder: false,
  sceneModePicker: false,
  homeButton: false,
  navigationHelpButton: false,
  navigationInstructionsInitiallyVisible: false,
  fullscreenButton: false,
  selectionIndicator: false,
  skyBox: false,
  timeline: false,
  animation: false,
  shouldAnimate: true,
  baseLayerPicker: false,
});
viewer.cesiumWidget.creditContainer.style.display = "none";
viewer.clock.shouldAnimate = false;
viewer.dataSources.add(dataSource);