@vcmap/core 5.0.0-rc.0

package/src/vcs/vcm/util/layerCollection.js

@@ -0,0 +1,216 @@
+import IndexedCollection from './indexedCollection.js';
+import ExclusiveManager from './exclusiveManager.js';
+import LayerState from '../layer/layerState.js';
+import VcsEvent from '../event/vcsEvent.js';
+
+/**
+ * A collection of layers. Manages rendering order and layer exclusivity. Emits state changes for convenience. Passed to
+ * {@link Map} for layers available to said map. Layers must have unique names.
+ * @class
+ * @export
+ * @api
+ * @extends {IndexedCollection<import("@vcmap/core").Layer>}}
+ */
+// ignored do to static issues, see https://github.com/microsoft/TypeScript/issues/4628
+// @ts-ignore
+class LayerCollection extends IndexedCollection {
+  /**
+   * Creates a LayerCollection from an iterable of layers, such as an Array.
+   * @param {Iterable<import("@vcmap/core").Layer>} iterable
+   * @returns {LayerCollection}
+   * @override
+   * @api
+   */
+  static from(iterable) {
+    const collection = new LayerCollection();
+
+    if (iterable) {
+      // eslint-disable-next-line no-restricted-syntax
+      for (const layer of iterable) {
+        collection.add(layer);
+      }
+    }
+    return collection;
+  }
+
+  constructor() {
+    super();
+
+    /**
+     * Array of layer event listeners
+     * @type {Object<string, Array<Function>>}
+     * @private
+     */
+    this._layerEventListeners = {};
+
+    /**
+     * A symbol to describe the local z index of a layer. The local z index must not equal the layers z index, but is
+     * always consistent in comparison to the neighbouring layers. If a layer is moved other then by z index, the collection
+     * ensures consistency by setting a new local z index if needed.
+     * @type {symbol}
+     * @private
+     */
+    this._zIndexSymbol = Symbol('zIndex');
+
+    /**
+     * Event raised, when a layer of this collection changes its state. Passed the layer.
+     * @type {VcsEvent<import("@vcmap/core").Layer>}
+     * @api
+     */
+    this.stateChanged = new VcsEvent();
+
+    /**
+     * The exclusive manager for this collection. Layers within this collection are automatically added and tracked.
+     * @type {ExclusiveManager}
+     * @api
+     */
+    this.exclusiveManager = new ExclusiveManager();
+  }
+
+  /**
+   * @param {import("@vcmap/core").Layer} layer
+   * @private
+   */
+  _listenToLayerEvents(layer) {
+    const stateListener = layer.stateChanged.addEventListener((state) => {
+      if (state === LayerState.ACTIVE) {
+        this.exclusiveManager.handleLayerActivated(layer);
+      }
+      this.stateChanged.raiseEvent(layer);
+    });
+
+    const zIndexListener = layer.zIndexChanged.addEventListener(() => {
+      this._zIndexChanged(layer);
+    });
+
+    const exclusiveGroupsListener = layer.exclusiveGroupsChanged.addEventListener(() => {
+      this.exclusiveManager.handleExclusiveGroupsChanged(layer);
+    });
+
+    const listeners = [stateListener, zIndexListener, exclusiveGroupsListener];
+    if (/** @type {SplitLayer} */ (layer).splitDirectionChanged) {
+      listeners.push(/** @type {SplitLayer} */ (layer).splitDirectionChanged.addEventListener(() => {
+        this.exclusiveManager.handleSplitDirectionChanged(layer);
+      }));
+    }
+    this._layerEventListeners[layer.name] = listeners;
+  }
+
+  /**
+   * Determines the location in the array before the first entry with a higher local z index or null if there is no such position
+   * @param {number} zIndex
+   * @returns {number|null}
+   * @private
+   */
+  _findZIndexPosition(zIndex) {
+    const usedIndex = this._array.findIndex(l => l[this._zIndexSymbol] > zIndex);
+    return usedIndex > -1 ? usedIndex : null;
+  }
+
+  /**
+   * This is callback for a layers zIndex changed. It reevaluates the array given the new zIndex
+   * an moves the specified layer to its new location determined by findeZIndexPosition or the end of the array failing that.
+   * @param {import("@vcmap/core").Layer} layer
+   * @private
+   */
+  _zIndexChanged(layer) {
+    const currentIndex = this.indexOf(layer);
+    if (currentIndex > -1) {
+      const increased = layer[this._zIndexSymbol] < layer.zIndex;
+      layer[this._zIndexSymbol] = layer.zIndex;
+      let zIndexPosition = this._findZIndexPosition(layer.zIndex);
+      if (increased && zIndexPosition > 0) {
+        zIndexPosition -= 1; // remove self from count
+      }
+      zIndexPosition = zIndexPosition != null ? zIndexPosition : this._array.length - 1;
+      this._move(layer, currentIndex, zIndexPosition);
+      this._ensureLocalZIndex(layer);
+    }
+  }
+
+  /**
+   * Ensures the local z index is consisten with the neighbours of a given layer.
+   * e.g. the layer on elower must have a lower or equal zIndex
+   * and the one higher a higher or equal zIndex.
+   * @param {import("@vcmap/core").Layer} layer
+   * @private
+   */
+  _ensureLocalZIndex(layer) {
+    const currentIndex = this.indexOf(layer);
+    if (currentIndex > 0) {
+      const below = this._array[currentIndex - 1][this._zIndexSymbol];
+      if (below > layer[this._zIndexSymbol]) {
+        layer[this._zIndexSymbol] = below;
+      }
+    }
+
+    if (currentIndex < this._array.length - 1) {
+      const above = this._array[currentIndex + 1][this._zIndexSymbol];
+      if (above < layer[this._zIndexSymbol]) {
+        layer[this._zIndexSymbol] = above;
+      }
+    }
+  }
+
+  /**
+   * Adds a layer to the collection. Can optionally be passed an index at which to insert the layer.
+   * @param {import("@vcmap/core").Layer} layer
+   * @param {number=} index
+   * @returns {number|null} returns the layer index or null, if the layers name is not unique
+   * @api
+   */
+  add(layer, index) {
+    let usedIndex = index;
+    if (index == null) {
+      usedIndex = this._findZIndexPosition(layer.zIndex);
+    }
+    const insertedAt = super.add(layer, usedIndex);
+    if (insertedAt != null) {
+      layer[this._zIndexSymbol] = layer.zIndex;
+      this._ensureLocalZIndex(layer);
+      this._listenToLayerEvents(layer);
+      this.exclusiveManager.registerLayer(layer);
+    }
+    return insertedAt;
+  }
+
+  /**
+   * Removes a layer from the collection.
+   * @param {import("@vcmap/core").Layer} layer
+   * @api
+   */
+  remove(layer) {
+    if (this._layerEventListeners[layer.name]) {
+      this._layerEventListeners[layer.name].forEach((cb) => { cb(); });
+      delete this._layerEventListeners[layer.name];
+    }
+    delete layer[this._zIndexSymbol];
+    this.exclusiveManager.unregisterLayer(layer);
+    super.remove(layer);
+  }
+
+  clear() {
+    Object.values(this._layerEventListeners)
+      .flat()
+      .forEach((r) => { r(); });
+    this._array.forEach((l) => {
+      delete l[this._zIndexSymbol];
+    });
+
+    this.exclusiveManager.clear();
+    this._layerEventListeners = {};
+    super.clear();
+  }
+
+  destroy() {
+    Object.values(this._layerEventListeners)
+      .flat()
+      .forEach((r) => { r(); });
+
+    this._layerEventListeners = {};
+    this.exclusiveManager.destroy();
+    super.destroy();
+  }
+}
+
+export default LayerCollection;

package/src/vcs/vcm/util/locale.js

@@ -0,0 +1,53 @@
+import VcsEvent from '../event/vcsEvent.js';
+
+/**
+ * @type {VcsEvent<string>}
+ */
+let localeChangedEvent;
+
+/**
+ * @returns {VcsEvent<string>}
+ */
+export function getLocaleChangedEvent() {
+  if (!localeChangedEvent) {
+    localeChangedEvent = new VcsEvent();
+  }
+  return localeChangedEvent;
+}
+
+/**
+ * returns the default browserLocale, if not possible 'en'
+ * @returns {string}
+ */
+export function detectBrowserLocale() {
+  if (navigator.language) {
+    const lang = navigator.language;
+    return lang.substring(0, 2);
+  }
+  return 'en';
+}
+
+/**
+ * @type {string}
+ */
+let currentLocale;
+
+/**
+ * @returns {string}
+ */
+export function getCurrentLocale() {
+  if (!currentLocale) {
+    currentLocale = detectBrowserLocale();
+  }
+  return currentLocale;
+}
+
+/**
+ * @param {string} value
+ */
+export function setCurrentLocale(value) {
+  if (typeof value === 'string') {
+    currentLocale = value;
+    getLocaleChangedEvent().raiseEvent(value);
+  }
+}

package/src/vcs/vcm/util/mapCollection.js

@@ -0,0 +1,363 @@
+import { checkMaybe } from '@vcsuite/check';
+import { getLogger } from '@vcsuite/logger';
+import VcsEvent from '../event/vcsEvent.js';
+import Collection from './collection.js';
+import EventHandler from '../interaction/eventHandler.js';
+import LayerCollection from './layerCollection.js';
+import ClippingObjectManager from './clipping/clippingObjectManager.js';
+import SplitScreen from './splitScreen.js';
+
+/**
+ * @typedef {Object} MapCollectionInitializationError
+ * @property {Error} error
+ * @property {import("@vcmap/core").VcsMap} map
+ */
+
+/**
+ * @param {import("@vcmap/core").CesiumMap} cesiumMap
+ * @param {import("@vcmap/core").Openlayers} olMap
+ * @returns {Promise<void>}
+ */
+async function setCesiumToOLViewpoint(cesiumMap, olMap) {
+  const viewPoint = cesiumMap.getViewPointSync();
+  const northDownVp = viewPoint.clone();
+  northDownVp.heading = 0;
+  northDownVp.pitch = -90;
+  if (viewPoint && !viewPoint.equals(northDownVp)) {
+    if (olMap.fixedNorthOrientation) {
+      viewPoint.heading = 0;
+    }
+
+    viewPoint.pitch = -90;
+    viewPoint.animate = true;
+    viewPoint.duration = 1;
+
+    if (viewPoint.groundPosition) {
+      viewPoint.cameraPosition = null;
+    }
+
+    await cesiumMap.gotoViewPoint(viewPoint);
+  }
+}
+
+/**
+ * @class
+ * @export
+ * @extends {Collection<import("@vcmap/core").VcsMap>}}
+ */
+// ignored do to static issues, see https://github.com/microsoft/TypeScript/issues/4628
+// @ts-ignore
+class MapCollection extends Collection {
+  /**
+   * Creates a LayerCollection from an iterable of layers, such as an Array.
+   * @param {Iterable<import("@vcmap/core").VcsMap>} iterable
+   * @returns {MapCollection}
+   * @override
+   * @api
+   */
+  static from(iterable) {
+    const collection = new MapCollection();
+
+    if (iterable) {
+      // eslint-disable-next-line no-restricted-syntax
+      for (const map of iterable) {
+        collection.add(map);
+      }
+    }
+    return collection;
+  }
+
+  constructor() {
+    super();
+
+    /**
+     * @type {import("@vcmap/core").VcsMap}
+     * @private
+     */
+    this._activeMap = null;
+
+    /**
+     *
+     * @type {HTMLElement}
+     * @private
+     */
+    this._target = null;
+
+    /**
+     * The map pointer event handler. The EventHandler is shared amongst all maps within the collection.
+     * @type {EventHandler}
+     * @api
+     */
+    this.eventHandler = new EventHandler();
+
+    /**
+     * Collection of layers shared amongst the maps within this collection,
+     * layers will be rendered if supported on the currently active map.
+     * @type {LayerCollection}
+     * @api
+     */
+    this.layerCollection = new LayerCollection();
+
+    /**
+     * Called, if a map fails to initialize. The map causing the error will be removed from the collection.
+     * @type {VcsEvent<MapCollectionInitializationError>}
+     * @api
+     */
+    this.initializeError = new VcsEvent();
+
+    /**
+     * Called, when a map (typically an oblique map) cannot show the current viewpoint. Is passed
+     * the map which cannot show the current viewpoint.
+     * @type {VcsEvent<import("@vcmap/core").VcsMap>}
+     * @api
+     */
+    this.fallbackMapActivated = new VcsEvent();
+
+    /**
+     * Called, when a map is activated. Is passed the activated map.
+     * @type {VcsEvent<import("@vcmap/core").VcsMap>}
+     * @api
+     */
+    this.mapActivated = new VcsEvent();
+
+    /**
+     * Manages the clipping object for the maps in this collection.
+     * @type {ClippingObjectManager}
+     * @api
+     */
+    this.clippingObjectManager = new ClippingObjectManager(this.layerCollection);
+
+    /**
+     * @type {SplitScreen}
+     */
+    this.splitScreen = new SplitScreen(this.clippingObjectManager);
+
+    /**
+     * @type {Array<Function>}
+     * @private
+     */
+    this._mapPointerListeners = [];
+  }
+
+  /**
+   * The currently active map
+   * @type {import("@vcmap/core").VcsMap}
+   * @api
+   * @readonly
+   */
+  get activeMap() { return this._activeMap; }
+
+  /**
+   * The currently set HTML element in which to render the maps
+   * @type {HTMLElement|null}
+   * @api
+   * @readonly
+   */
+  get target() {
+    return this._target;
+  }
+
+  /**
+   * Adds a map to the collection. This will set the collections target, {@link SplitScreen}
+   * and the collections {@link LayerCollection} on the map.
+   * It will add map event listeners and pass them to the event handler of this collection.
+   * @param {import("@vcmap/core").VcsMap} map
+   * @returns {number|null}
+   */
+  add(map) {
+    const added = super.add(map);
+    if (added !== null) {
+      this._mapPointerListeners
+        .push(map.pointerInteractionEvent.addEventListener(this.eventHandler.handleMapEvent.bind(this.eventHandler)));
+      map.layerCollection = this.layerCollection;
+      map.splitScreen = this.splitScreen;
+      map.setTarget(this._target);
+    }
+    return added;
+  }
+
+  /**
+   * Removes the map from the collection. Will also set splitScreen & target to null and an empty layerCollection on the map,
+   * if the map is currently part of the collection.
+   * @param {import("@vcmap/core").VcsMap} map
+   */
+  remove(map) {
+    if (this.has(map)) {
+      map.setTarget(null);
+      map.splitScreen = null;
+      map.layerCollection = new LayerCollection();
+    }
+    super.remove(map);
+    if (this._activeMap === map) {
+      this._activeMap = null;
+    }
+  }
+
+  /**
+   * @private
+   */
+  _setActiveMapCSSClass() {
+    if (this._target && this._activeMap) {
+      const mapClassName = this._activeMap.className.split('.').pop();
+      this._target.classList.add(mapClassName);
+    }
+  }
+
+  /**
+   * Set the target for these maps.
+   * @param {(string|HTMLElement)} target
+   * @api
+   */
+  setTarget(target) {
+    checkMaybe(target, [String, HTMLElement]);
+
+    this._target = typeof target === 'string' ? document.getElementById(target) : target;
+    this._array.forEach((map) => {
+      map.setTarget(this._target);
+    });
+
+    this._setActiveMapCSSClass();
+  }
+
+  /**
+   * @param {import("@vcmap/core").VcsMap} map
+   * @returns {null|import("@vcmap/core").VcsMap}
+   * @private
+   */
+  _getFallbackMap(map) {
+    const { fallbackMap } = map;
+    if (fallbackMap) {
+      const fMap = this.getByKey(fallbackMap);
+      if (fMap && fMap !== map) {
+        return fMap;
+      } else {
+        getLogger().warning(`the fallback map with the name: ${fallbackMap} is missconfigured`);
+      }
+    }
+    return null;
+  }
+
+  /**
+   * @param {import("@vcmap/core").VcsMap} map
+   * @returns {null|import("@vcmap/core").VcsMap}
+   * @private
+   */
+  _getFallbackMapOrDefault(map) {
+    const fallbackMap = this._getFallbackMap(map);
+    return fallbackMap ||
+      this.getByType('vcs.vcm.maps.Openlayers')[0] ||
+      this._array[0];
+  }
+
+  /**
+   * Sets the active map. This will 1. get the current viewpoint of an acitve map (if one is set) 2.
+   * determine that the map to be activated can show this viewpoint or has no fallback map set and 3.
+   * activates the map 4. calls gotoViewpoint with the previous maps viewpoint
+   * @param {string} mapName
+   * @returns {Promise<void>}
+   */
+  async setActiveMap(mapName) {
+    const map = this.getByKey(mapName);
+    if (!map) {
+      getLogger('vcs.vcm.util.MapCollection').warning(`could not find map with name ${mapName}`);
+      return Promise.resolve();
+    }
+
+    if (
+      this._activeMap &&
+      this._activeMap.className === 'vcs.vcm.maps.Cesium' &&
+      map.className === 'vcs.vcm.maps.Openlayers'
+    ) {
+      await setCesiumToOLViewpoint(
+        /** @type {import("@vcmap/core").CesiumMap} */ (this._activeMap),
+        /** @type {import("@vcmap/core").Openlayers} */ (map),
+      );
+    }
+
+    try {
+      await map.initialize();
+    } catch (error) { // typically unsupported webGL and cesium map
+      getLogger('vcs.vcm.util.MapCollection').error(error);
+      this.remove(map);
+      const fallbackMap = this._getFallbackMapOrDefault(map);
+      this.initializeError.raiseEvent({
+        map,
+        error,
+      });
+      if (fallbackMap) {
+        this.fallbackMapActivated.raiseEvent(map);
+        return this.setActiveMap(fallbackMap.name);
+      }
+      throw new Error('cannot activate a single map');
+    }
+
+    let viewpoint;
+    if (this._activeMap) {
+      if (this._activeMap === map) {
+        return map.activate();
+      }
+
+      viewpoint = await this._activeMap.getViewPoint();
+      const canShow = await map.canShowViewpoint(viewpoint);
+      if (!canShow) {
+        const fallbackMap = this._getFallbackMap(map);
+        if (fallbackMap) {
+          this.fallbackMapActivated.raiseEvent(map);
+          return this.setActiveMap(fallbackMap.name);
+        }
+      }
+      this._activeMap.deactivate();
+      if (this._target) {
+        const mapClassName = this._activeMap.className.split('.').pop();
+        this._target.classList.remove(mapClassName);
+      }
+    }
+
+    this._activeMap = map;
+    await this._activeMap.activate();
+    this._setActiveMapCSSClass();
+
+    if (viewpoint) {
+      await this._activeMap.gotoViewPoint(viewpoint);
+    }
+
+    this.clippingObjectManager.mapActivated(map);
+    this.splitScreen.mapActivated(map);
+    this.mapActivated.raiseEvent(map);
+    return Promise.resolve();
+  }
+
+  /**
+   * Returns all maps of a specified type
+   * @param {string} type
+   * @returns {Array<import("@vcmap/core").VcsMap>}
+   * @api
+   */
+  getByType(type) {
+    return this._array.filter(m => m.className === type);
+  }
+
+  /**
+   * @inheritDoc
+   */
+  destroy() {
+    super.destroy();
+    [...this.layerCollection].forEach((l) => { l.destroy(); });
+    this.layerCollection.destroy();
+    this.eventHandler.destroy();
+    this.mapActivated.destroy();
+    this.clippingObjectManager.destroy();
+    this.clippingObjectManager = null;
+    this.splitScreen.destroy();
+    this.splitScreen = null;
+    this.fallbackMapActivated.destroy();
+    this.initializeError.destroy();
+
+    this._mapPointerListeners.forEach((cb) => { cb(); });
+    this._mapPointerListeners = [];
+
+    this._target = null;
+  }
+}
+
+export default MapCollection;

package/src/vcs/vcm/util/math.js

@@ -0,0 +1,71 @@
+import { Math as CesiumMath, Cartesian3 } from '@vcmap/cesium';
+
+/**
+ * returns a new coordinate ([lon, lat] in degrees) from a distance, bearing and starting coordinate
+ * @param {Array.<number>} coord [lon, lat] in degrees
+ * @param {number} d distance in m to new coordinate
+ * @param {number} brng bearing in degrees ( 0 == north, 90° == east)
+ * @returns {Array.<number>};
+ */
+export function coordinateAtDistance(coord, d, brng) {
+  const R = 6371000;
+  const brngRadians = CesiumMath.toRadians(brng);
+  const lat1 = CesiumMath.toRadians(coord[1]);
+  const lon1 = CesiumMath.toRadians(coord[0]);
+  const lat2 = Math.asin((Math.sin(lat1) * Math.cos(d / R)) +
+    (Math.cos(lat1) * Math.sin(d / R) * Math.cos(brngRadians)));
+  const lon2 = lon1 + Math.atan2(
+    Math.sin(brngRadians) * Math.sin(d / R) * Math.cos(lat1),
+    Math.cos(d / R) - (Math.sin(lat1) * Math.sin(lat2)),
+  );
+  return [parseFloat(CesiumMath.toDegrees(lon2).toFixed(5)), parseFloat(CesiumMath.toDegrees(lat2).toFixed(5))];
+}
+
+
+/**
+ * returns the initial bearing in degrees (0-360) between two coordinates
+ * @param {Array.<number>} coords1 [lon, lat] in degrees
+ * @param {Array.<number>} coords2 [lon, lat] in degrees
+ * @returns {number};
+ */
+export function initialBearingBetweenCoords(coords1, coords2) {
+  // long
+  const l1 = CesiumMath.toRadians(coords1[0]);
+  // lat
+  const f1 = CesiumMath.toRadians(coords1[1]);
+  // long
+  const l2 = CesiumMath.toRadians(coords2[0]);
+  // lat
+  const f2 = CesiumMath.toRadians(coords2[1]);
+
+  const y = Math.sin(l2 - l1) * Math.cos(f2);
+  const x = (Math.cos(f1) * Math.sin(f2)) - (Math.sin(f1) * Math.cos(f2) * Math.cos(l2 - l1));
+  let brng = CesiumMath.toDegrees(Math.atan2(y, x));
+  brng = (brng + 360) % 360;
+  return brng;
+}
+
+
+/**
+ * returns distance between two coordinates
+ * @param {import("ol/coordinate").Coordinate} point0
+ * @param {import("ol/coordinate").Coordinate} point1
+ * @returns {number}
+ */
+export function cartesian2DDistance(point0, point1) {
+  const distX = point0[0] - point1[0];
+  const distY = point0[1] - point1[1];
+  return Math.sqrt((distX ** 2) + (distY ** 2));
+}
+
+/**
+ * @param {import("ol/coordinate").Coordinate} p1
+ * @param {import("ol/coordinate").Coordinate} p2
+ * @returns {number}
+ */
+export function cartesian3DDistance(p1, p2) {
+  const point0 = Cartesian3.fromElements(p1[0], p1[1], p1[2]);
+  const point1 = Cartesian3.fromElements(p2[0], p2[1], p2[2]);
+  return Cartesian3.distance(point0, point1);
+}
+