@vcmap/viewshed 3.0.5 → 4.0.0

package/src/{viewshed.js → viewshed.ts}

@@ -1,4 +1,10 @@
+import type { CesiumMap, VcsObjectOptions } from '@vcmap/core';
 import { VcsEvent, VcsObject } from '@vcmap/core';
+import type {
+  Scene,
+  PerspectiveFrustum,
+  HeadingPitchRollValues,
+} from '@vcmap-cesium/engine';
 import {
   Camera,
   Cartesian3,
@@ -8,45 +14,44 @@ import {
 } from '@vcmap-cesium/engine';
 import { check } from '@vcsuite/check';
 import { parseEnumValue } from '@vcsuite/parsers';
+import type { Coordinate } from 'ol/coordinate.js';
 import ViewshedCameraPrimitive from './viewshedPrimitive.js';
 
-/**
- * @enum {string}
- * @property {string} CONE A cone Viewshed, that can be used for visibility analysis.
- * @property {string} THREESIXTY A 360 degree Viewshed, that can be used for sensor analysis.
- */
-export const ViewshedTypes = {
-  CONE: 'cone',
-  THREESIXTY: '360',
-};
+export enum ViewshedTypes {
+  /** A cone Viewshed, that can be used for visibility analysis. */
+  CONE = 'cone',
+  /** A 360 degree Viewshed, that can be used for sensor analysis. */
+  THREESIXTY = '360',
+}
 
-/**
- * @typedef {Object} ShadowFrustumOptions
- * @property {number} fov The angle of the field of view (FOV), in radians.
- * @property {number} aspectRatio The aspect ratio of the frustum's width to it's height.
- * @property {number} near The distance of the near plane.
- * @property {number} far The distance of the far plane.
- */
+type ShadowFrustumOptions = {
+  /** The angle of the field of view (FOV), in radians. */
+  fov: number;
+  /** The aspect ratio of the frustum's width to its height. */
+  aspectRatio: number;
+  /** The distance of the near plane. */
+  near: number;
+  /** The distance of the far plane. */
+  far: number;
+};
 
-/**
- * @typedef {Object} ColorOptions
- * @property {string=} [visibleColor] CSS color string of the visible parts of the shadow map
- * @property {string=} [shadowColor] CSS color string of the hidden parts of the shadow map
- */
+export type ColorOptions = {
+  /** CSS color string of the visible parts of the shadow map */
+  visibleColor?: string;
+  /** CSS color string of the hidden parts of the shadow map */
+  shadowColor?: string;
+};
 
 /**
  * Creates camera and sets frustum options and orientation.
- * @param {import("@vcmap-cesium/engine").Scene} scene
- * @param {ShadowFrustumOptions} frustumOptions
- * @returns {import("@vcmap-cesium/engine").Camera}
  */
-function createShadowCamera(scene, frustumOptions) {
+function createShadowCamera(
+  scene: Scene,
+  frustumOptions: ShadowFrustumOptions,
+): Camera {
   const camera = new Camera(scene);
 
-  const perspectiveFrustum =
-    /** @type {import("@vcmap-cesium/engine").PerspectiveFrustum} */ (
-      camera.frustum
-    );
+  const perspectiveFrustum = camera.frustum as PerspectiveFrustum;
   perspectiveFrustum.fov = frustumOptions.fov;
   perspectiveFrustum.near = frustumOptions.near;
   perspectiveFrustum.aspectRatio = frustumOptions.aspectRatio;
@@ -55,165 +60,139 @@ function createShadowCamera(scene, frustumOptions) {
   return camera;
 }
 
-/**
- * @typedef {Object} ViewshedSpecificOptions
- * @property {ViewshedTypes} viewshedType Whether the viewshed has a spot light with limited field of view (cone) or a point light with 360° coverage (360).
- * @property {import("ol/coordinate").Coordinate=} [position] The position of the viewshed. Height offset is added to Z value of position to determine actual height of viewshed.
- * @property {ShadowFrustumOptions} [frustumOptions] The frustum options with far, near, fov and aspect ratio.
- * @property {import("@vcmap-cesium/engine").HeadingPitchRollValues} [orientation] The values for heading and pitch. Roll is ignored.
- * @property {ColorOptions} [colorOptions] The colors of the visible and the hidden areas.
- * @property {boolean} [showPrimitive=false] Whether the viewsheds primitve should be shown.
- * @property {number} [heightOffset=0] Height offset. Is added to Z value of position.
- * @typedef {import("@vcmap/core").VcsObjectOptions & ViewshedSpecificOptions} ViewshedOptions
- */
+type ViewshedSpecificOptions = {
+  /** Whether the viewshed has a spot light with limited field of view (cone) or a point light with 360° coverage (360). */
+  viewshedType: ViewshedTypes;
+  /** The position of the viewshed. Height offset is added to Z value of position to determine actual height of viewshed. */
+  position?: Coordinate;
+  /** The frustum options with far, near, fov and aspect ratio. */
+  frustumOptions?: ShadowFrustumOptions;
+  /** The values for heading and pitch. Roll is ignored. */
+  orientation?: HeadingPitchRollValues;
+  /** The colors of the visible and the hidden areas. */
+  colorOptions?: ColorOptions;
+  /** Whether the viewsheds primitve should be shown. */
+  showPrimitive?: boolean;
+  /** Height offset. Is added to Z value of position. */
+  heightOffset?: number;
+};
+
+type ViewshedDefaultOptions = VcsObjectOptions &
+  Required<
+    Pick<
+      ViewshedOptions,
+      'colorOptions' | 'frustumOptions' | 'orientation' | 'position'
+    >
+  > & { colorOptions: Required<ColorOptions> };
+
+export type ViewshedOptions = VcsObjectOptions & ViewshedSpecificOptions;
 
 /**
  * Viewshed class consists of a Cesium Shadow map and a primitive. Since there can only be one ShadowMap for each Scene, only one viewshed instance at a time is possible.
  */
 export default class Viewshed extends VcsObject {
-  static get className() {
+  static get className(): string {
     return 'Viewshed';
   }
 
-  /**
-   * Returns the default viewshed options.
-   * @returns {{frustum: ShadowFrustumOptions, shadowColor: string, visibleColor: string, orientation: import("@vcmap-cesium/engine").HeadingPitchRollValues, position: import("ol/coordinate").Coordinate}}
-   */
-  static getDefaultOptions() {
+  static getDefaultOptions(): ViewshedDefaultOptions {
     return {
-      frustum: {
+      colorOptions: { shadowColor: '#3333331A', visibleColor: '#FF990080' },
+      frustumOptions: {
         fov: CesiumMath.PI / 3,
         near: 1.0,
         aspectRatio: 1.0,
         far: 300,
       },
-      shadowColor: '#3333331A',
-      visibleColor: '#FF990080',
-      orientation: {
-        heading: 0,
-        pitch: 0,
-        roll: 0,
-      },
+      orientation: { heading: 0, pitch: 0, roll: 0 },
       position: [0, 0, 0],
     };
   }
 
   static MIN_DISTANCE = 10;
 
+  private _cesiumMap: CesiumMap | null = null;
+
+  private _shadowCamera: Camera | null = null;
+
+  private _scene: Scene | null = null;
+
+  private _frustumOptions: ShadowFrustumOptions;
+
+  private _headingPitchRollValues: HeadingPitchRollValues;
+
   /**
-   * @param {ViewshedOptions} options The options for the viewshed.
+   * The viewsheds position, excluding height offset, in lat/lon degrees.
    */
-  constructor(options) {
+  private _position: Coordinate;
+
+  private _viewshedType: ViewshedTypes;
+
+  private _colors: { visibleColor: Color; shadowColor: Color };
+
+  private _heightOffset: number;
+
+  private _shadowMap: ShadowMap | null = null;
+
+  private _primitive: ViewshedCameraPrimitive | null = null;
+
+  private _showPrimitive: boolean;
+
+  private _positionChanged = new VcsEvent<number[]>();
+
+  private _active = false;
+
+  constructor(options: ViewshedOptions) {
     super(options);
-    /**
-     * @type {import("@vcmap/core").CesiumMap | null}
-     * @private
-     */
-    this._cesiumMap = null;
-    /**
-     * @type {import("@vcmap-cesium/engine").Camera | null}
-     * @private
-     */
-    this._shadowCamera = null;
-    /**
-     * @type {import("@vcmap-cesium/engine").Scene | null}
-     * @private
-     */
-    this._scene = null;
-
-    /**
-     * @type {ShadowFrustumOptions}
-     * @private
-     */
+
     this._frustumOptions = {
       fov:
-        options.frustumOptions?.fov || Viewshed.getDefaultOptions().frustum.fov,
+        options.frustumOptions?.fov ||
+        Viewshed.getDefaultOptions().frustumOptions.fov,
       far:
-        options.frustumOptions?.far || Viewshed.getDefaultOptions().frustum.far,
+        options.frustumOptions?.far ||
+        Viewshed.getDefaultOptions().frustumOptions.far,
       near:
         options.frustumOptions?.near ||
-        Viewshed.getDefaultOptions().frustum.near,
+        Viewshed.getDefaultOptions().frustumOptions.near,
       aspectRatio:
         options.frustumOptions?.aspectRatio ||
-        Viewshed.getDefaultOptions().frustum.aspectRatio,
+        Viewshed.getDefaultOptions().frustumOptions.aspectRatio,
     };
 
-    /**
-     * @type {import("@vcmap-cesium/engine").HeadingPitchRollValues}
-     * @private
-     */
     this._headingPitchRollValues = options.orientation || {
       ...Viewshed.getDefaultOptions().orientation,
     };
 
-    /**
-     * The viewsheds position, excluding height offset, in lat/lon degrees.
-     * @type {import("ol/coordinate.js").Coordinate}
-     * @private
-     */
     this._position = options.position || Viewshed.getDefaultOptions().position;
 
-    /**
-     * @type {ViewshedTypes}
-     * @private
-     */
-    this._viewshedType = parseEnumValue(options.viewshedType, ViewshedTypes);
-    /**
-     * @type {{visibleColor: import("@vcmap-cesium/engine").Color, shadowColor: import("@vcmap-cesium/engine").Color}}
-     * @private
-     */
+    this._viewshedType = parseEnumValue(
+      options.viewshedType,
+      ViewshedTypes,
+      ViewshedTypes.CONE,
+    );
+
     this._colors = {
       visibleColor: Color.fromCssColorString(
         options.colorOptions?.visibleColor ||
-          Viewshed.getDefaultOptions().visibleColor,
+          Viewshed.getDefaultOptions().colorOptions.visibleColor,
       ),
       shadowColor: Color.fromCssColorString(
         options.colorOptions?.shadowColor ||
-          Viewshed.getDefaultOptions().shadowColor,
+          Viewshed.getDefaultOptions().colorOptions.shadowColor,
       ),
     };
 
-    /**
-     * @type {number}
-     * @private
-     */
     this._heightOffset = options.heightOffset || 0;
 
-    /**
-     * @type {import("@vcmap-cesium/engine").ShadowMap | null}
-     * @private
-     */
-    this._shadowMap = null;
-
-    /**
-     * @type {ViewshedCameraPrimitive | null}
-     * @private
-     */
-    this._primitive = null;
-    /**
-     * @type {boolean}
-     * @private
-     */
     this._showPrimitive = !!options.showPrimitive;
-
-    /**
-     * @type {import("@vcmap/core").VcsEvent<number[]>}
-     * @private
-     */
-    this._positionChanged = new VcsEvent();
-
-    /**
-     * @type {boolean}
-     * @private
-     */
-    this._active = false;
   }
 
   /**
    * Sets a new position for the shadow map. If no shadow map was created yet, due to missing position, this method triggers the creation of a shadow map.
-   * @param {import("ol/coordinate").Coordinate} coords The new positions coordinates in degrees
+   * @param coords The new positions coordinates in degrees
    */
-  set position(coords) {
+  set position(coords: Coordinate) {
     check(coords, [Number]);
     this._position = coords;
     if (this._shadowCamera) {
@@ -230,25 +209,25 @@ export default class Viewshed extends VcsObject {
   }
 
   /**
-   * @returns {import("ol/coordinate").Coordinate} The current position of the viewshed source.
+   * @returns The current position of the viewshed source.
    */
-  get position() {
+  get position(): Coordinate {
     return [...this._position];
   }
 
   /**
    * Getter for Event that is triggered each time the position is changed.
-   * @returns {import("@vcmap/core").VcsEvent<number[]>} The new position
+   * @returns The new position
    */
-  get positionChanged() {
+  get positionChanged(): VcsEvent<number[]> {
     return this._positionChanged;
   }
 
   /**
    * Sets the height offset of the viewshed.
-   * @param {number} value the offset that is added to the position height.
+   * @param value the offset that is added to the position height.
    */
-  set heightOffset(value) {
+  set heightOffset(value: number) {
     this._heightOffset = value;
     if (this._shadowCamera) {
       this._shadowCamera.position = Cartesian3.fromDegrees(
@@ -260,19 +239,15 @@ export default class Viewshed extends VcsObject {
     }
   }
 
-  /**
-   * Getter for height offset.
-   * @returns {number}
-   */
-  get heightOffset() {
+  get heightOffset(): number {
     return this._heightOffset;
   }
 
   /**
    * Sets the reach of the viewshed.
-   * @param {number} value The distance in meters.
+   * @param value The distance in meters.
    */
-  set distance(value) {
+  set distance(value: number) {
     this._frustumOptions.far =
       value > Viewshed.MIN_DISTANCE ? value : Viewshed.MIN_DISTANCE;
     if (this._shadowCamera) {
@@ -288,22 +263,21 @@ export default class Viewshed extends VcsObject {
 
   /**
    * Returns the reach of the viewshed.
-   * @returns {number} The distance in meters.
+   * @returns The distance in meters.
    */
-  get distance() {
+  get distance(): number {
     return this._frustumOptions.far;
   }
 
   /**
    * Sets the field of view of a cone viewshed. Does not have a impact on 360 viewshed.
-   * @param {number} value The field of view in degrees.
+   * @param value The field of view in degrees.
    */
-  set fov(value) {
+  set fov(value: number) {
     this._frustumOptions.fov = value * CesiumMath.RADIANS_PER_DEGREE;
     if (this._shadowCamera) {
-      /** @type {import("@vcmap-cesium/engine").PerspectiveFrustum} */ (
-        this._shadowCamera.frustum
-      ).fov = value * CesiumMath.RADIANS_PER_DEGREE;
+      (this._shadowCamera.frustum as PerspectiveFrustum).fov =
+        value * CesiumMath.RADIANS_PER_DEGREE;
       if (this._viewshedType === ViewshedTypes.CONE) {
         this._updateShadowMap();
         this._updatePrimitive();
@@ -313,17 +287,17 @@ export default class Viewshed extends VcsObject {
 
   /**
    * Returns the field of view.
-   * @returns {number} The field of view in degrees.
+   * @returns The field of view in degrees.
    */
-  get fov() {
+  get fov(): number {
     return this._frustumOptions.fov * CesiumMath.DEGREES_PER_RADIAN;
   }
 
   /**
    * Sets the heading of a cone viewshed. Does not have impact on 360 viewshed.
-   * @param {number} value Heading in degrees.
+   * @param value Heading in degrees.
    */
-  set heading(value) {
+  set heading(value: number) {
     this._headingPitchRollValues.heading =
       value * CesiumMath.RADIANS_PER_DEGREE;
     if (this._shadowCamera) {
@@ -340,19 +314,17 @@ export default class Viewshed extends VcsObject {
     }
   }
 
-  /**
-   * Getter for the heading of a cone viewshed.
-   * @returns {number} The heading in degress.
-   */
-  get heading() {
-    return this._headingPitchRollValues.heading * CesiumMath.DEGREES_PER_RADIAN;
+  get heading(): number {
+    return (
+      this._headingPitchRollValues.heading! * CesiumMath.DEGREES_PER_RADIAN
+    );
   }
 
   /**
    * Sets the pitch of a cone viewshed. 0 is horizontal. Does not have impact on 360 viewshed.
-   * @param {number} value The pitch in degrees.
+   * @param value The pitch in degrees.
    */
-  set pitch(value) {
+  set pitch(value: number) {
     this._headingPitchRollValues.pitch = value * CesiumMath.RADIANS_PER_DEGREE;
     if (this._shadowCamera) {
       const amount =
@@ -364,53 +336,42 @@ export default class Viewshed extends VcsObject {
     }
   }
 
-  /**
-   * Getter for the pitch of a cone viewshed.
-   * @returns {number} The pitch in degrees.
-   */
-  get pitch() {
-    return this._headingPitchRollValues.pitch * CesiumMath.DEGREES_PER_RADIAN;
+  get pitch(): number {
+    return this._headingPitchRollValues.pitch! * CesiumMath.DEGREES_PER_RADIAN;
   }
 
   /**
    * Sets whether the primitive of the viewshed should be shown or not.
-   * @param {boolean} value
+   * @param value
    */
-  set showPrimitive(value) {
+  set showPrimitive(value: boolean) {
     this._showPrimitive = value;
     this._updatePrimitive();
   }
 
   /**
    * Gets if the primitive of the viewshed is shown or not.
-   * @returns {boolean}
    */
-  get showPrimitive() {
+  get showPrimitive(): boolean {
     return this._showPrimitive;
   }
 
-  /**
-   * Returns the type of the Viewshed.
-   * @returns {ViewshedTypes}
-   */
-  get type() {
+  get type(): ViewshedTypes {
     return this._viewshedType;
   }
 
-  /**
-   * @returns {ShadowMap|null}
-   */
-  get shadowMap() {
+  get shadowMap(): ShadowMap | null {
     return this._shadowMap;
   }
 
   /**
    * Deactivates the viewshed by removing primitive and removing shadowMap.
    */
-  deactivate() {
+  deactivate(): void {
     if (this._active) {
       this._removePrimitive();
-      this._shadowMap.enabled = false;
+      this._shadowMap!.enabled = false;
+      // @ts-expect-error - ShadowMap destroy method exists but is not in type definitions
       this._shadowMap?.destroy();
       this._shadowCamera = null;
       this._scene = null;
@@ -422,9 +383,9 @@ export default class Viewshed extends VcsObject {
 
   /**
    * Activates viewshed.
-   * @param {import("@vcmap/core").CesiumMap} cesiumMap The cesium map to which the shadow map of the viewshed is applied to.
+   * @param The cesium map to which the shadow map of the viewshed is applied to.
    */
-  activate(cesiumMap) {
+  activate(cesiumMap: CesiumMap): void {
     if (!this._active) {
       this._active = true;
     }
@@ -452,7 +413,7 @@ export default class Viewshed extends VcsObject {
   /**
    * Updates the shadow map by creating a new one and applying all the current parameters.
    */
-  _updateShadowMap() {
+  private _updateShadowMap(): void {
     if (
       !this._active ||
       !this._shadowCamera ||
@@ -462,10 +423,10 @@ export default class Viewshed extends VcsObject {
       return;
     }
 
+    // @ts-expect-error - ShadowMap destroy method exists but is not in type definitions
     this._shadowMap?.destroy();
-    // @ts-ignore
+    // @ts-expect-error - does not accept parameters
     this._shadowMap = new ShadowMap({
-      // @ts-ignore
       context: this._scene.context,
       lightCamera: this._shadowCamera,
       enabled: true,
@@ -481,7 +442,7 @@ export default class Viewshed extends VcsObject {
     this._cesiumMap.setShadowMap(this._shadowMap);
   }
 
-  _removePrimitive() {
+  private _removePrimitive(): void {
     if (this._primitive && !this._primitive.isDestroyed()) {
       this._scene?.primitives.remove(this._primitive);
       this._primitive.destroy();
@@ -489,11 +450,11 @@ export default class Viewshed extends VcsObject {
     }
   }
 
-  _updatePrimitive() {
+  private _updatePrimitive(): void {
     if (this._showPrimitive && this._active && this._scene) {
       this._removePrimitive();
       this._primitive = new ViewshedCameraPrimitive({
-        camera: this._shadowCamera,
+        camera: this._shadowCamera!,
         allowPicking: false,
         spot: this._viewshedType === ViewshedTypes.CONE,
       });
@@ -505,9 +466,9 @@ export default class Viewshed extends VcsObject {
 
   /**
    * Sets distance and, in case of cone viewsheds, also heading and pitch. Only works when viewshed is **active**.
-   * @param {number[]} target Point to calculate distance, heading and pitch from.
+   * @param target Point to calculate distance, heading and pitch from.
    */
-  lookAt(target) {
+  lookAt(target: number[]): void {
     if (!this._shadowCamera) {
       return;
     }
@@ -542,9 +503,8 @@ export default class Viewshed extends VcsObject {
 
   /**
    * Returns an object with all the settings of a viewshed instance.
-   * @returns {ViewshedOptions}
    */
-  toJSON() {
+  toJSON(): ViewshedOptions {
     return {
       ...super.toJSON(),
       viewshedType: this.type,
@@ -560,10 +520,7 @@ export default class Viewshed extends VcsObject {
     };
   }
 
-  /**
-   * Destroys the viewshed.
-   */
-  destroy() {
+  destroy(): void {
     const cesiumMap = this._cesiumMap;
     const shadowMap = this._shadowMap;
     this.deactivate();