@vcmap/core 5.0.0-rc.0

package/src/vcs/vcm/layer/dataSource.js

@@ -0,0 +1,259 @@
+import { EntityCollection } from '@vcmap/cesium';
+import Layer from './layer.js';
+import CesiumMap from '../maps/cesium.js';
+import DataSourceCesium from './cesium/dataSourceCesium.js';
+import { vcsLayerName } from './layerSymbols.js';
+import FeatureVisibility, { FeatureVisibilityAction } from './featureVisibility.js';
+import { getGlobalHider } from './globalHider.js';
+import { VcsClassRegistry } from '../classRegistry.js';
+
+/**
+ * @typedef {LayerOptions} DataSourceOptions
+ * @property {Object|undefined} genericFeatureProperties
+ * @api
+ */
+
+/**
+ * @typedef {Object} DataSourcePickedObject
+ * @property {import("@vcmap/cesium").Entity} id
+ * @property {ClickPosition} clickedPosition
+ * @property {Object} attributes
+ */
+
+/**
+ * @typedef {LayerImplementationOptions} DataSourceImplementationOptions
+ * @property {import("@vcmap/cesium").EntityCollection} entities
+ * @property {import("@vcmap/cesium").DataSourceClock|undefined} clock
+ * @api
+ */
+
+/**
+ * Represents a layer of Cesium.Entity
+ * @class
+ * @export
+ * @extends {Layer}
+ * @api stable
+ */
+class DataSource extends Layer {
+  static get className() { return 'vcs.vcm.layer.DataSource'; }
+
+  /**
+   * @returns {DataSourceOptions}
+   */
+  static getDefaultOptions() {
+    return {
+      ...Layer.getDefaultOptions(),
+      genericFeatureProperties: {},
+    };
+  }
+
+  /**
+   * @param {DataSourceOptions} options
+   */
+  constructor(options) {
+    super(options);
+    const defaultOptions = DataSource.getDefaultOptions();
+    /**
+     * The entities of this layer. Use the `addEntity` API to add Enitities to ensure interoperability with vcm interfaces
+     * @type {import("@vcmap/cesium").EntityCollection}
+     * @api
+     */
+    this.entities = new EntityCollection();
+    /**
+     * @type {import("@vcmap/cesium").DataSourceClock|undefined}
+     */
+    this.clock = undefined;
+    /**
+     * @type {Object}
+     * @private
+     */
+    this._genericFeatureProperties = options.genericFeatureProperties || defaultOptions.genericFeatureProperties;
+
+    /**
+     * The feature visibility of this layer. NOTE: Entities cannot be highlighted at this moment.
+     * @type {FeatureVisibility}
+     * @api
+     */
+    this.featureVisibility = new FeatureVisibility();
+    /**
+     * @type {Array<Function>}
+     * @private
+     */
+    this._featureVisibilityListeners = [];
+
+    this._supportedMaps = [
+      CesiumMap.className,
+    ];
+  }
+
+  /**
+   * Sets up listeners for featureVisibility and global hider
+   * @private
+   */
+  _setUpFeatureVisibility() {
+    const globalHider = getGlobalHider();
+    this._featureVisibilityListeners = [
+      this.featureVisibility.changed.addEventListener(({ action, ids }) => {
+        if (action === FeatureVisibilityAction.HIDE) {
+          ids.forEach((id) => {
+            const entity = this.entities.getById(id);
+            if (entity) {
+              this.featureVisibility.addHiddenFeature(id, entity);
+            }
+          });
+        } // highlight is _possible_ but very tricky with all the possible entity values with potential materials
+      }),
+      globalHider.changed.addEventListener(({ action, ids }) => {
+        if (action === FeatureVisibilityAction.HIDE) {
+          ids.forEach((id) => {
+            const entity = this.entities.getById(id);
+            if (entity) {
+              globalHider.addFeature(id, entity);
+            }
+          });
+        }
+      }),
+      this.entities.collectionChanged.addEventListener((c, added) => {
+        added.forEach((entity) => {
+          if (this.featureVisibility.hiddenObjects[entity.id]) {
+            this.featureVisibility.addHiddenFeature(entity.id, entity);
+          }
+
+          if (globalHider.hiddenObjects[entity.id]) {
+            globalHider.addFeature(entity.id, entity);
+          }
+        });
+      }),
+    ];
+  }
+
+  /**
+   * @inheritDoc
+   * @returns {Promise<void>}
+   */
+  initialize() {
+    if (!this.initialized) {
+      this._setUpFeatureVisibility();
+    }
+    return super.initialize();
+  }
+
+  /**
+   * @returns {DataSourceImplementationOptions}
+   */
+  getImplementationOptions() {
+    return {
+      ...super.getImplementationOptions(),
+      entities: this.entities,
+      clock: this.clock,
+    };
+  }
+
+  /**
+   * @param {CesiumMap} map
+   * @returns {Array<DataSourceCesium>}
+   */
+  createImplementationsForMap(map) {
+    if (map instanceof CesiumMap) {
+      return [new DataSourceCesium(map, this.getImplementationOptions())];
+    }
+    return [];
+  }
+
+  /**
+   * adds an entity
+   * @param {import("@vcmap/cesium").Entity.ConstructorOptions|import("@vcmap/cesium").Entity} options - Cesium Entity options or the entity
+   * @param {?Object=} attributes - a set of properties, typically used for rendering a balloon
+   * @param {boolean=} allowPicking - whether to override the layers allowPicking setting for this entity
+   * @returns {null|string} the entities id
+   * @api stable
+   */
+  addEntity(options, attributes, allowPicking) {
+    const entity = this.entities.add(options);
+    entity[vcsLayerName] = this.name;
+    entity.attributes = attributes;
+    entity.allowPicking = allowPicking;
+    return entity.id;
+  }
+
+  /**
+   * Zooms to an entity with the given id
+   * @param {string} id
+   * @api stable
+   */
+  flyToEntity(id) {
+    this.getImplementations().forEach((impl) => {
+      /** @type {DataSourceCesium} */ (impl).flyToEntity(id);
+    });
+  }
+
+  /**
+   * Removes an entity from this layer by id
+   * @param {string} id
+   * @api
+   */
+  removeEntityById(id) {
+    this.entities.removeById(id);
+  }
+
+  /**
+   * @param {DataSourcePickedObject} object
+   * @returns {?Object}
+   */
+  objectClickedHandler(object) {
+    if (this.allowPicking && object.id.allowPicking !== false) {
+      const model = object.id;
+      const { id } = model;
+      // @ts-ignore
+      model.clickedPosition = object.clickedPosition;
+      return {
+        id,
+        feature: object,
+      };
+    }
+    return null;
+  }
+
+  /**
+   * @param {DataSourcePickedObject} object
+   * @returns {GenericFeature}
+   */
+  getGenericFeatureFromClickedObject(object) {
+    const attributes = { ...this._genericFeatureProperties, ...object.attributes || {} };
+    return {
+      layerName: this.name,
+      layerClass: this.className,
+      attributes,
+      longitude: object.clickedPosition.longitude,
+      latitude: object.clickedPosition.latitude,
+      height: object.clickedPosition.height,
+      relativeToGround: false,
+    };
+  }
+
+  /**
+   * @inheritDoc
+   * @returns {DataSourceOptions}
+   */
+  getConfigObject() {
+    const config = /** @type {DataSourceOptions} */ (super.getConfigObject());
+    if (Object.keys(this._genericFeatureProperties).length > 0) {
+      config.genericFeatureProperties = { ...this._genericFeatureProperties };
+    }
+    return config;
+  }
+
+  /**
+   * @inheritDoc
+   */
+  destroy() {
+    this.entities.removeAll();
+    this._featureVisibilityListeners.forEach((cb) => { cb(); });
+    this._featureVisibilityListeners = [];
+    this.featureVisibility.destroy();
+    super.destroy();
+  }
+}
+
+VcsClassRegistry.registerClass(DataSource.className, DataSource);
+export default DataSource;

package/src/vcs/vcm/layer/featureLayer.js

@@ -0,0 +1,261 @@
+import Style from 'ol/style/Style.js';
+
+import { check } from '@vcsuite/check';
+import { parseInteger } from '@vcsuite/parsers';
+import Layer from './layer.js';
+import StyleItem, { referenceableStyleSymbol } from '../util/style/styleItem.js';
+import VectorStyleItem from '../util/style/vectorStyleItem.js';
+import FeatureVisibility from './featureVisibility.js';
+import { getStyleOrDefaultStyle } from '../util/style/styleFactory.js';
+import VcsEvent from '../event/vcsEvent.js';
+import { styleCollection } from '../globalCollections.js';
+import { VcsClassRegistry } from '../classRegistry.js';
+
+/**
+ * @typedef {LayerOptions} FeatureLayerOptions
+ * @property {DeclarativeStyleItemOptions|VectorStyleItemOptions|import("@vcmap/core").StyleItem|string|undefined} style
+ * @property {string|undefined} activeStyleName - vcs:undocumented
+ * @property {Object|undefined} genericFeatureProperties - properties to add to generic features, eg for display in the balloon
+ * @property {number} [balloonHeightOffset=10]
+ * @property {FeatureVisibility|undefined} featureVisibility - vcs:undocumented
+ * @api
+ */
+
+/**
+ * @typedef {LayerImplementationOptions} FeatureLayerImplementationOptions
+ * @property {FeatureVisibility} featureVisibility
+ * @property {import("@vcmap/core").StyleItem} style
+ * @api
+ */
+
+/**
+ * Event called on a layers <b>styleChanged</b> property, when a layers style changes, with the following parameters.
+ * @typedef {Object} FeatureLayer.StyleChangedEvent
+ * @property {import("@vcmap/core").StyleItem} newStyle
+ * @property {import("@vcmap/core").StyleItem|undefined} oldStyle
+ * @api
+ */
+
+/**
+ * @typedef {import("@vcmap/core").LayerImplementation<import("@vcmap/core").VcsMap>} FeatureLayerImplementation
+ * @property {function(import("@vcmap/core").StyleItem, boolean=):void} updateStyle
+ */
+
+/**
+ * Base class for all layers representing features, e.g. Vector, Buildings, POIs
+ * @class
+ * @abstract
+ * @extends {Layer}
+ * @export
+ * @api
+ */
+class FeatureLayer extends Layer {
+  /** @type {string} */
+  static get className() { return 'vcs.vcm.layer.FeatureLayer'; }
+
+  /**
+   * @returns {FeatureLayerOptions}
+   */
+  static getDefaultOptions() {
+    return {
+      ...Layer.getDefaultOptions(),
+      style: undefined,
+      balloonHeightOffset: 10,
+      genericFeatureProperties: {},
+    };
+  }
+
+  /**
+   * @param {FeatureLayerOptions} options
+   */
+  constructor(options) {
+    super(options);
+    const defaultOptions = FeatureLayer.getDefaultOptions();
+
+    /**
+     * @type {import("@vcmap/core").StyleItem}
+     * @private
+     */
+    this._style = this.getStyleOrDefaultStyle(options.activeStyleName || options.style);
+    /**
+     * @type {import("@vcmap/core").StyleItem}
+     * @private
+     */
+    this._defaultStyle = this._style;
+    /**
+     * An event, called when the style of the layer changes. Is passed the new style item as its value.
+     * @type {VcsEvent<import("@vcmap/core").StyleItem>}
+     * @api
+     */
+    this.styleChanged = new VcsEvent();
+    /**
+     * @type {Object}
+     * @private
+     */
+    this._genericFeatureProperties = options.genericFeatureProperties || defaultOptions.genericFeatureProperties;
+
+    /**
+     * a height offset for rendering of a balloon for a feature of this layer.
+     * @type {number}
+     * @api
+     */
+    this.balloonHeightOffset = parseInteger(options.balloonHeightOffset, defaultOptions.balloonHeightOffset);
+
+    /**
+     * FeatureVisibility tracks the highlighting and hiding of features on this layer
+     * @type {FeatureVisibility}
+     */
+    this.featureVisibility = options.featureVisibility || new FeatureVisibility();
+  }
+
+  /**
+   * The style the layer had at construction
+   * @type {import("@vcmap/core").StyleItem}
+   * @api
+   * @readonly
+   */
+  get defaultStyle() {
+    return this._defaultStyle;
+  }
+
+  /**
+   * style, use setStyle to change
+   * @api
+   * @type {import("@vcmap/core").StyleItem}
+   * @readonly
+   */
+  get style() {
+    return this._style;
+  }
+
+  /**
+   * Generic properties to be added to each feature. Use assignGenericFeatureProperties to change them.
+   * @type {Object}
+   * @readonly
+   */
+  get genericFeatureProperties() {
+    return this._genericFeatureProperties;
+  }
+
+  /**
+   * @returns {FeatureLayerImplementationOptions}
+   */
+  getImplementationOptions() {
+    return {
+      ...super.getImplementationOptions(),
+      featureVisibility: this.featureVisibility,
+      style: this.style,
+    };
+  }
+
+  /**
+   * @param {Object|import("ol").Feature<import("ol/geom/Geometry").default>|import("@vcmap/cesium").Cesium3DTilePointFeature|import("@vcmap/cesium").Cesium3DTileFeature|DataSourcePickedObject} object
+   * @returns {?Object}
+   */
+  // eslint-disable-next-line no-unused-vars,class-methods-use-this
+  objectClickedHandler(object) { // XXX remove after event implementation
+    return null;
+  }
+
+  /**
+   * This is called by the selectBehavior to create generic features from clicked objects
+   * needs to be implemented by each layer which has clickable objects
+   * @param {Object|VectorClickedObject|import("ol").Feature<import("ol/geom/Geometry").default>} object
+   * @returns {GenericFeature}
+   */
+  // eslint-disable-next-line no-unused-vars
+  getGenericFeatureFromClickedObject(object) { // XXX remove after event implementation
+    this.getLogger().warning('This method should be implemented by any specific layers');
+    return null;
+  }
+
+  /**
+   * Set properties, which are always added to the generic object, eg. for use in balloons
+   * @param {Object} properties
+   * @api
+   */
+  assignGenericFeatureProperties(properties) {
+    check(properties, Object);
+    Object.assign(this._genericFeatureProperties, properties);
+  }
+
+  /**
+   * @param {(Reference|DeclarativeStyleItemOptions|VectorStyleItemOptions|import("@vcmap/core").StyleItem|string)=} styleOptions
+   * @param {(import("@vcmap/core").VectorStyleItem|import("@vcmap/core").DeclarativeStyleItem)=} defaultStyle
+   * @returns {import("@vcmap/core").StyleItem}
+   */
+  // eslint-disable-next-line class-methods-use-this
+  getStyleOrDefaultStyle(styleOptions, defaultStyle) {
+    return getStyleOrDefaultStyle(styleOptions, defaultStyle);
+  }
+
+  /**
+   * Sets the style based on a styleName on a layer
+   * @param {string|import("ol/style/Style").default|import("ol/style/Style").StyleFunction|import("@vcmap/core").StyleItem} style
+   * @param {boolean=} silent
+   * @api
+   */
+  setStyle(style, silent) {
+    check(style, [Style, StyleItem, Function, String]);
+
+    if (typeof style === 'string') {
+      const styleItem = styleCollection.getByKey(style);
+      if (!styleItem) {
+        this.getLogger().warning(`could not find style with name ${style}`);
+        return;
+      }
+      this._style = styleItem;
+    } else if (style instanceof StyleItem) {
+      this._style = style;
+    } else {
+      this._style = new VectorStyleItem({});
+      this._style.style = /** @type {import("ol/style/Style").default} */ (style);
+    }
+    this.getImplementations()
+      .forEach((impl) => {
+        /** @type {FeatureLayerImplementation} */ (impl).updateStyle(this._style, silent);
+      });
+    this.styleChanged.raiseEvent(this._style);
+  }
+
+  /**
+   * Clears the style of this layer
+   * @api stable
+   */
+  clearStyle() {
+    this.setStyle(this.defaultStyle);
+  }
+
+  /**
+   * @returns {FeatureLayerOptions}
+   */
+  getConfigObject() {
+    const config = /** @type {FeatureLayerOptions} */ (super.getConfigObject());
+    if (!this.getStyleOrDefaultStyle().equals(this._style)) {
+      if (this._style[referenceableStyleSymbol]) {
+        config.style = this.style.getReference();
+      } else {
+        config.style = this.style.getOptions();
+      }
+    }
+
+    if (Object.keys(this._genericFeatureProperties).length > 0) {
+      config.genericFeatureProperties = { ...this._genericFeatureProperties };
+    }
+    return config;
+  }
+
+  /**
+   * @inheritDoc
+   */
+  destroy() {
+    if (this.featureVisibility) {
+      this.featureVisibility.destroy();
+    }
+    this.styleChanged.destroy();
+    super.destroy();
+  }
+}
+
+VcsClassRegistry.registerClass(FeatureLayer.className, FeatureLayer);
+export default FeatureLayer;