@vcmap/core 5.0.0-rc.8 → 5.0.0

package/src/map/mapState.ts

@@ -0,0 +1,11 @@
+/**
+ * The state of a map.
+ * State machine: inactive <-> loading -> active -> inactive
+ */
+enum MapState {
+  INACTIVE = 1,
+  ACTIVE = 2,
+  LOADING = 4,
+}
+
+export default MapState;

package/src/map/{obliqueMap.js → obliqueMap.ts}

@@ -1,51 +1,56 @@
 import { boundingExtent, containsXY } from 'ol/extent.js';
 import { getTransform, transform, transformExtent } from 'ol/proj.js';
+import { Map as OLMap } from 'ol';
+import type { Coordinate } from 'ol/coordinate.js';
+
 import { check } from '@vcsuite/check';
 import { parseBoolean, parseNumber } from '@vcsuite/parsers';
 import Extent from '../util/extent.js';
 import { mercatorProjection, wgs84Projection } from '../util/projection.js';
-import { getResolutionOptions, getZoom } from '../layer/oblique/obliqueHelpers.js';
-import ViewPoint from '../util/viewpoint.js';
+import {
+  getResolutionOptions,
+  getZoom,
+} from '../layer/oblique/obliqueHelpers.js';
+import Viewpoint from '../util/viewpoint.js';
 import BaseOLMap from './baseOLMap.js';
-import VcsMap from './vcsMap.js';
+import VcsMap, { VcsMapOptions } from './vcsMap.js';
 import VcsEvent from '../vcsEvent.js';
-import { ObliqueViewDirection as ViewDirection } from '../oblique/obliqueViewDirection.js';
-import ObliqueProvider from '../oblique/obliqueProvider.js';
+import {
+  ObliqueViewDirection,
+  ObliqueViewDirection as ViewDirection,
+} from '../oblique/obliqueViewDirection.js';
+import ObliqueProvider, {
+  ObliqueProviderMapChangeEventType,
+} from '../oblique/obliqueProvider.js';
 import ObliqueCollection from '../oblique/obliqueCollection.js';
 import { transformFromImage } from '../oblique/helpers.js';
-import { VcsClassRegistry } from '../classRegistry.js';
+import { mapClassRegistry } from '../classRegistry.js';
 import DefaultObliqueCollection from '../oblique/defaultObliqueCollection.js';
+import type ObliqueImage from '../oblique/obliqueImage.js';
 
-/**
- * @typedef {Object} ObliqueClickParameters
- * @property {import("ol/pixel").Pixel} pixel
- * @property {boolean|undefined} estimate
- * @api stable
- */
-
-/**
- * @typedef {VcsMapOptions} ObliqueOptions
- * @property {boolean} [changeOnMoveEnd=false]
- * @property {number} [switchThreshold=0]
- * @property {boolean} [switchOnEdge=true]
- * @api
- */
+export type ObliqueOptions = VcsMapOptions & {
+  changeOnMoveEnd?: boolean;
+  switchThreshold?: number;
+  switchOnEdge?: boolean;
+};
 
-const defaultHeadings = {
+const defaultHeadings: Record<ViewDirection, number> = {
   [ViewDirection.NORTH]: 0,
   [ViewDirection.EAST]: 90,
   [ViewDirection.SOUTH]: 180,
   [ViewDirection.WEST]: 270,
+  [ViewDirection.NADIR]: 0,
 };
 
 const defaultCollection = new DefaultObliqueCollection();
 
 /**
  * returns the direction which matches the heading of the viewpoint
- * @param {ViewPoint} viewpoint
- * @returns {import("@vcmap/core").ObliqueViewDirection}
+ * @param  viewpoint
  */
-export function getViewDirectionFromViewPoint(viewpoint) {
+export function getViewDirectionFromViewpoint(
+  viewpoint: Viewpoint,
+): ObliqueViewDirection {
   const { heading } = viewpoint;
   let direction = ViewDirection.NORTH;
   if (heading >= 45 && heading < 135) {
@@ -58,35 +63,40 @@ export function getViewDirectionFromViewPoint(viewpoint) {
   return direction;
 }
 
-/**
- * @param {ViewPoint} viewpoint
- * @returns {import("ol/coordinate").Coordinate}
- * @private
- */
-export function getMercatorViewpointCenter(viewpoint) {
-  const gpWGS84 = viewpoint.groundPosition || viewpoint.cameraPosition;
-  return transform(
-    gpWGS84,
-    wgs84Projection.proj,
-    mercatorProjection.proj,
-  );
+export function getMercatorViewpointCenter(viewpoint: Viewpoint): Coordinate {
+  const gpWGS84 = viewpoint.groundPosition ??
+    viewpoint.cameraPosition ?? [0, 0, 0];
+  return transform(gpWGS84, wgs84Projection.proj, mercatorProjection.proj);
 }
 
 /**
- * ObliqueMap Map Class (2D map with oblique imagery)
- *
- * @class
- * @export
- * @extends {BaseOLMap}
- * @api stable
+ * @group Map
  */
 class ObliqueMap extends BaseOLMap {
-  static get className() { return 'ObliqueMap'; }
+  static get className(): string {
+    return 'ObliqueMap';
+  }
+
+  private _loadingCollection: ObliqueCollection | null;
+
+  private _mapChangeEvent: ObliqueProviderMapChangeEventType;
+
+  private _switchThreshold: number;
+
+  private _switchEnabled: boolean;
 
   /**
-   * @returns {ObliqueOptions}
+   * An event raise, when the collection changes. Is passed the collection as its only argument.
    */
-  static getDefaultOptions() {
+  collectionChanged: VcsEvent<ObliqueCollection>;
+
+  private _activeCollectionDestroyedListener: () => void;
+
+  private _obliqueProvider: ObliqueProvider | null = null;
+
+  initializedPromise: Promise<void> | null = null;
+
+  static getDefaultOptions(): ObliqueOptions {
     return {
       ...VcsMap.getDefaultOptions(),
       changeOnMoveEnd: false,
@@ -95,62 +105,45 @@ class ObliqueMap extends BaseOLMap {
     };
   }
 
-  constructor(options) {
+  constructor(options: ObliqueOptions) {
     super(options);
     const defaultOptions = ObliqueMap.getDefaultOptions();
-    /**
-     * @type  {ObliqueCollection|null}
-     * @private
-     */
     this._loadingCollection = null;
 
-    /**
-     * @type {string}
-     * @private
-     */
     this._mapChangeEvent = options.changeOnMoveEnd ? 'moveend' : 'postrender';
 
-    /** @type {number} */
-    this._switchThreshold = parseNumber(options.switchThreshold, defaultOptions.switchThreshold);
+    this._switchThreshold = parseNumber(
+      options.switchThreshold,
+      defaultOptions.switchThreshold,
+    );
     if (this._switchThreshold > 1) {
       this._switchThreshold = 0.2;
     } else if (this._switchThreshold < 0) {
       this._switchThreshold = 0;
     }
 
-    /**
-     * @type {boolean}
-     * @private
-     */
-    this._switchEnabled = parseBoolean(options.switchOnEdge, defaultOptions.switchOnEdge);
-
-    /**
-     * An event raise, when the collection changes. Is passed the collection as its only argument.
-     * @type {VcsEvent<ObliqueCollection>}
-     * @api
-     */
+    this._switchEnabled = parseBoolean(
+      options.switchOnEdge,
+      defaultOptions.switchOnEdge,
+    );
+
     this.collectionChanged = new VcsEvent();
-    /**
-     * @type {function():void}
-     * @private
-     */
-    this._activeCollectionDestroyedListener = () => {};
+
+    this._activeCollectionDestroyedListener = (): void => {};
   }
 
   /**
    * Whether the post render handler should switch on image edge. Setting
    * this to false will suspend all post render handler switches.
-   * @type {boolean}
-   * @api
    */
-  get switchEnabled() {
+  get switchEnabled(): boolean {
     return this._switchEnabled;
   }
 
   /**
-   * @param {boolean} switchEnabled
+   * @param  switchEnabled
    */
-  set switchEnabled(switchEnabled) {
+  set switchEnabled(switchEnabled: boolean) {
     this._switchEnabled = switchEnabled;
     if (this._obliqueProvider) {
       this._obliqueProvider.switchEnabled = switchEnabled;
@@ -161,17 +154,15 @@ class ObliqueMap extends BaseOLMap {
    * Threshold from 0 to 1 to define when to start switching to other images. Where 0 indicates
    * to only switch, when the view center is outside of the image and 1 to always switch. 0.2 would start switching
    * if the view center is within the outer 20% of the image.
-   * @type {number}
-   * @api
    */
-  get switchThreshold() {
+  get switchThreshold(): number {
     return this._switchThreshold;
   }
 
   /**
-   * @param {number} threshold
+   * @param  threshold
    */
-  set switchThreshold(threshold) {
+  set switchThreshold(threshold: number) {
     check(threshold, Number);
     this._switchThreshold = threshold;
     if (this._switchThreshold > 1) {
@@ -185,21 +176,12 @@ class ObliqueMap extends BaseOLMap {
     }
   }
 
-  /**
-   * @type {string}
-   */
-  get mapChangeEvent() {
-    return this._mapChangeEvent;
-  }
-
-  /**
-   * @returns {Promise<void>}
-   */
-  async initialize() {
+  async initialize(): Promise<void> {
     if (!this.initializedPromise) {
-      this.initializedPromise = super.initialize()
+      this.initializedPromise = super
+        .initialize()
         .then(async () => {
-          this._obliqueProvider = new ObliqueProvider(this.olMap);
+          this._obliqueProvider = new ObliqueProvider(this.olMap as OLMap);
           this.mapChangeEvent = this._mapChangeEvent;
           this.switchThreshold = this._switchThreshold;
           this.switchEnabled = this._switchEnabled;
@@ -218,99 +200,84 @@ class ObliqueMap extends BaseOLMap {
     await this.initializedPromise;
   }
 
-  /**
-   * @param {string} eventType
-   */
-  set mapChangeEvent(eventType) {
+  get mapChangeEvent(): ObliqueProviderMapChangeEventType {
+    return this._mapChangeEvent;
+  }
+
+  set mapChangeEvent(eventType: ObliqueProviderMapChangeEventType) {
     check(eventType, String);
+
     this._mapChangeEvent = eventType;
     if (this._obliqueProvider) {
       this._obliqueProvider.mapChangeEvent = eventType;
     }
   }
 
-  /**
-   * @type {ObliqueCollection}
-   * @readonly
-   * @api
-   */
-  get collection() { return this._obliqueProvider.collection; }
+  get collection(): ObliqueCollection | null {
+    return this._obliqueProvider?.collection ?? null;
+  }
 
-  /**
-   * @type {import("@vcmap/core").VcsEvent<import("@vcmap/core").ObliqueImage>}
-   * @readonly
-   * @api
-   */
-  get imageChanged() {
-    return this._obliqueProvider ? this._obliqueProvider.imageChanged : null;
+  get imageChanged(): VcsEvent<ObliqueImage> | null {
+    return this._obliqueProvider?.imageChanged ?? null;
   }
 
-  /**
-   * @type {import("@vcmap/core").ObliqueImage|null}
-   * @api
-   * @readonly
-   */
-  get currentImage() {
-    return this._obliqueProvider ? this._obliqueProvider.currentImage : null;
+  get currentImage(): ObliqueImage | null {
+    return this._obliqueProvider?.currentImage ?? null;
   }
 
-  /**
-   * @param {ViewPoint} viewpoint
-   * @returns {Promise<boolean>}
-   * @api
-   */
-  async canShowViewpoint(viewpoint) {
+  async canShowViewpoint(viewpoint: Viewpoint): Promise<boolean> {
     await this.initialize();
     if (this.collection) {
-      const viewDirection = getViewDirectionFromViewPoint(viewpoint);
+      const viewDirection = getViewDirectionFromViewpoint(viewpoint);
       const mercatorCoordinates = getMercatorViewpointCenter(viewpoint);
-      return this.collection.hasImageAtCoordinate(mercatorCoordinates, viewDirection);
+      return this.collection.hasImageAtCoordinate(
+        mercatorCoordinates,
+        viewDirection,
+      );
     }
     return false;
   }
 
-  /**
-   * @inheritDoc
-   * @returns {Promise<void>}
-   */
-  async activate() {
+  async activate(): Promise<void> {
     await super.activate();
     if (this.active) {
-      this._obliqueProvider.activate();
+      this._obliqueProvider?.activate?.();
     }
   }
 
-  /**
-   * @returns {Extent}
-   */
-  getExtentOfCurrentImage() {
+  getExtentOfCurrentImage(): Extent {
     const image = this.currentImage;
     if (image) {
       const coords = boundingExtent(image.groundCoordinates);
       return new Extent({
-        coordinates: transformExtent(coords, image.meta.projection.proj, mercatorProjection.proj),
+        coordinates: transformExtent(
+          coords,
+          image.meta.projection.proj,
+          mercatorProjection.proj,
+        ),
         projection: mercatorProjection.toJSON(),
       });
     }
     return new Extent({
-      coordinates: [-18924313.4349, -15538711.0963, 18924313.4349, 15538711.0963],
+      coordinates: [
+        -18924313.4349, -15538711.0963, 18924313.4349, 15538711.0963,
+      ],
       projection: mercatorProjection.toJSON(),
     });
   }
 
-  deactivate() {
+  deactivate(): void {
     super.deactivate();
-    this._obliqueProvider.deactivate();
+    this._obliqueProvider?.deactivate?.();
   }
 
   /**
    * Sets a new oblique collection
-   * @param {ObliqueCollection} obliqueCollection
-   * @param {ViewPoint=} viewpoint
-   * @returns {Promise<void>}
-   * @api
    */
-  async setCollection(obliqueCollection, viewpoint) {
+  async setCollection(
+    obliqueCollection: ObliqueCollection,
+    viewpoint?: Viewpoint,
+  ): Promise<void> {
     check(obliqueCollection, ObliqueCollection);
 
     if (this.movementDisabled) {
@@ -331,109 +298,111 @@ class ObliqueMap extends BaseOLMap {
 
   /**
    * Sets a new oblique collection
-   * @param {ObliqueCollection} obliqueCollection
-   * @param {ViewPoint=} viewpoint
-   * @returns {Promise<void>}
-   * @private
    */
-  async _setCollection(obliqueCollection, viewpoint) {
+  private async _setCollection(
+    obliqueCollection: ObliqueCollection,
+    viewpoint?: Viewpoint,
+  ): Promise<void> {
     this._loadingCollection = obliqueCollection;
     this._activeCollectionDestroyedListener();
-    this._activeCollectionDestroyedListener = obliqueCollection.destroyed.addEventListener(() => {
-      this._setCollection(defaultCollection);
-    });
+    this._activeCollectionDestroyedListener =
+      obliqueCollection.destroyed.addEventListener(() => {
+        // eslint-disable-next-line no-void
+        void this._setCollection(defaultCollection);
+      });
     await obliqueCollection.load();
-    const vp = viewpoint || await this.getViewPoint();
+    const vp = viewpoint || (await this.getViewpoint());
     if (this._loadingCollection !== obliqueCollection) {
       return;
     }
-    this._obliqueProvider.setCollection(obliqueCollection);
+    this._obliqueProvider?.setCollection(obliqueCollection);
     this.collectionChanged.raiseEvent(obliqueCollection);
     if (vp) {
-      await this.gotoViewPoint(vp);
+      await this.gotoViewpoint(vp);
     }
   }
 
   /**
    * Sets an image by its name on the map
-   * @param {string} imageName
-   * @param {import("ol/coordinate").Coordinate=} optCenter
-   * @returns {Promise<void>}
-   * @api
    */
-  async setImageByName(imageName, optCenter) {
+  async setImageByName(
+    imageName: string,
+    optCenter?: Coordinate,
+  ): Promise<void> {
     if (this.movementDisabled || !this.initializedPromise) {
       return;
     }
     await this.initializedPromise;
-    const image = this._obliqueProvider.collection.getImageByName(imageName);
+    const image = this._obliqueProvider?.collection?.getImageByName(imageName);
     if (image) {
-      await this._obliqueProvider.setImage(image, optCenter);
+      await this._obliqueProvider!.setImage(image, optCenter);
     }
   }
 
-  /**
-   * @returns {Promise<ViewPoint|null>}
-   * @inheritDoc
-   */
-  async getViewPoint() {
+  async getViewpoint(): Promise<Viewpoint | null> {
     const image = this.currentImage;
     if (!image) {
       return null;
     }
     // if we dont have an image, we may not have a map, thus two if clauses
-    const viewCenter = this.olMap.getView().getCenter();
+    const viewCenter = this.olMap!.getView().getCenter();
     if (!viewCenter) {
       return null;
     }
 
     const transformationOptions = { dataProjection: wgs84Projection };
-    const { coords } = await transformFromImage(image, viewCenter, transformationOptions);
+    const { coords } = await transformFromImage(
+      image,
+      viewCenter,
+      transformationOptions,
+    );
     return this._computeViewpointInternal(coords);
   }
 
-  /**
-   * @inheritDoc
-   * @returns {ViewPoint|null}
-   */
-  getViewPointSync() {
+  getViewpointSync(): Viewpoint | null {
     const image = this.currentImage;
     if (!image) {
       return null;
     }
 
-    const gpImageCoordinates = this.olMap.getView().getCenter();
+    const gpImageCoordinates = this.olMap!.getView().getCenter();
     if (!gpImageCoordinates) {
       return null;
     }
 
-    const gpInternalProjection = image.transformImage2RealWorld(gpImageCoordinates, image.averageHeight);
-
-    const transfrom = getTransform(image.meta.projection.proj, wgs84Projection.proj);
-    // getText can return a rich Text Array<string> We do not support this at the moment.
-    const gpWGS84 = transfrom(gpInternalProjection.slice(0, 2), undefined, undefined);
+    const gpInternalProjection = image.transformImage2RealWorld(
+      gpImageCoordinates,
+      image.averageHeight,
+    );
+
+    const transfrom = getTransform(
+      image.meta.projection.proj,
+      wgs84Projection.proj,
+    );
+    // getText can return a rich Text string[] We do not support this at the moment.
+    const gpWGS84 = transfrom(
+      gpInternalProjection.slice(0, 2),
+      undefined,
+      undefined,
+    );
     return this._computeViewpointInternal(gpWGS84);
   }
 
-  /**
-   * @param {import("ol/coordinate").Coordinate} groundPosition
-   * @returns {ViewPoint}
-   * @private
-   */
-  _computeViewpointInternal(groundPosition) {
-    const image = this.currentImage;
-    const { size, fovy, metersPerUnit } = getResolutionOptions(this.olMap, image);
+  private _computeViewpointInternal(groundPosition: Coordinate): Viewpoint {
+    const image = this.currentImage as ObliqueImage;
+    const map = this.olMap as OLMap;
+    const { size, fovy, metersPerUnit } = getResolutionOptions(map, image);
 
-    const view = this.olMap.getView();
+    const view = map.getView();
     const resolution = view.getResolution() || 1;
     const visibleMapUnits = resolution * size.height;
     const visibleMeters = visibleMapUnits * metersPerUnit;
-    const height = Math.abs((visibleMeters / 2) / Math.tan(fovy / 2));
+    const height = Math.abs(visibleMeters / 2 / Math.tan(fovy / 2));
 
     const avgHeight = groundPosition[2] || image.averageHeight;
     const cameraHeight = height + avgHeight;
 
-    return new ViewPoint({
+    return new Viewpoint({
       cameraPosition: [groundPosition[0], groundPosition[1], cameraHeight],
       groundPosition,
       heading: defaultHeadings[image.viewDirection],
@@ -443,54 +412,53 @@ class ObliqueMap extends BaseOLMap {
     });
   }
 
-  /**
-   * @param {ViewPoint} viewpoint
-   * @returns {Promise<void>}
-   * @inheritDoc
-   */
-  async gotoViewPoint(viewpoint) {
-    if (this.movementDisabled || !this._obliqueProvider || !viewpoint.isValid()) {
+  async gotoViewpoint(viewpoint: Viewpoint): Promise<void> {
+    if (
+      this.movementDisabled ||
+      !this.olMap ||
+      !this._obliqueProvider ||
+      !viewpoint.isValid()
+    ) {
       return;
     }
 
-    const viewDirection = getViewDirectionFromViewPoint(viewpoint);
+    const viewDirection = getViewDirectionFromViewpoint(viewpoint);
     const mercatorCoordinates = getMercatorViewpointCenter(viewpoint);
     const { distance } = viewpoint;
     await this._obliqueProvider.setView(mercatorCoordinates, viewDirection);
     if (this._obliqueProvider.currentImage) {
-      const zoom = getZoom(this.olMap, this._obliqueProvider.currentImage, distance);
+      const zoom = getZoom(
+        this.olMap,
+        this._obliqueProvider.currentImage,
+        distance as number,
+      );
       this.olMap.getView().setZoom(zoom);
     }
   }
 
-  /**
-   * @param {import("ol/coordinate").Coordinate} coords in WGS84 degrees
-   * @returns {boolean}
-   * @api
-   */
-  pointIsVisible(coords) {
+  pointIsVisible(coords: Coordinate): boolean {
     const image = this.currentImage;
     if (!image || !this.active) {
       return false;
     }
-    const view = this.olMap.getView();
-    const extent = view.calculateExtent(this.olMap.getSize());
+    const view = this.olMap!.getView();
+    const extent = view.calculateExtent(this.olMap!.getSize());
     const bl = image.transformImage2RealWorld([extent[0], extent[1]]);
     const ur = image.transformImage2RealWorld([extent[2], extent[3]]);
     const bbox = [bl[0], bl[1], ur[0], ur[1]];
-    const transformedBbox = transformExtent(bbox, image.meta.projection.proj, wgs84Projection.proj);
+    const transformedBbox = transformExtent(
+      bbox,
+      image.meta.projection.proj,
+      wgs84Projection.proj,
+    );
     return containsXY(transformedBbox, coords[0], coords[1]);
   }
 
-  /**
-   * @returns {ObliqueOptions}
-   * @api
-   */
-  toJSON() {
-    const config = /** @type {ObliqueOptions} */ (super.toJSON());
+  toJSON(): ObliqueOptions {
+    const config: ObliqueOptions = super.toJSON();
     const defaultOptions = ObliqueMap.getDefaultOptions();
 
-    if (this.mapChangeEvent === 'movened') {
+    if (this.mapChangeEvent === 'moveend') {
       config.changeOnMoveEnd = true;
     }
 
@@ -505,10 +473,7 @@ class ObliqueMap extends BaseOLMap {
     return config;
   }
 
-  /**
-   * @api
-   */
-  destroy() {
+  destroy(): void {
     if (this._obliqueProvider) {
       this._obliqueProvider.destroy();
     }
@@ -518,5 +483,5 @@ class ObliqueMap extends BaseOLMap {
   }
 }
 
-VcsClassRegistry.registerClass(ObliqueMap.className, ObliqueMap);
+mapClassRegistry.registerClass(ObliqueMap.className, ObliqueMap);
 export default ObliqueMap;