@vcmap/core 5.0.2 → 5.1.0-rc.1

package/src/util/flight/flightAnchor.ts

@@ -0,0 +1,195 @@
+import { check, is, maybe, PatternFor } from '@vcsuite/check';
+import { v4 as uuidv4 } from 'uuid';
+import type { Feature as GeojsonFeature, Point as GeojsonPoint } from 'geojson';
+import { type Coordinate, equals as coordinateEquals } from 'ol/coordinate.js';
+import VcsEvent from '../../vcsEvent.js';
+import Viewpoint from '../viewpoint.js';
+
+type FlightAnchorFeatureProperties = {
+  heading: number;
+  pitch: number;
+  roll: number;
+  duration: number;
+  title?: string;
+};
+
+export type FlightAnchorGeojsonFeature = GeojsonFeature<
+  GeojsonPoint,
+  FlightAnchorFeatureProperties
+>;
+
+export type FlightAnchor = FlightAnchorFeatureProperties & {
+  readonly changed: VcsEvent<void>;
+  readonly name: string;
+  coordinate: Coordinate;
+  destroy(): void;
+};
+
+type FlightAnchorOptions = Omit<FlightAnchor, 'changed' | 'destroy'>;
+
+const flightAnchorOptionsPattern: PatternFor<FlightAnchorOptions> = {
+  name: String,
+  coordinate: [Number],
+  heading: Number,
+  pitch: Number,
+  roll: Number,
+  duration: Number,
+  title: maybe(String),
+};
+
+function isOptions(options: unknown): options is FlightAnchorOptions {
+  return (
+    is(options, flightAnchorOptionsPattern) && options.coordinate.length === 3
+  );
+}
+
+function fromOptions(options: FlightAnchorOptions): FlightAnchor {
+  check(options, flightAnchorOptionsPattern);
+
+  const changed = new VcsEvent<void>();
+  const { name } = options;
+  let { title, heading, pitch, roll, coordinate, duration } = options;
+  coordinate = coordinate.slice();
+
+  return {
+    get changed(): VcsEvent<void> {
+      return changed;
+    },
+    get name(): string {
+      return name;
+    },
+    get coordinate(): Coordinate {
+      return coordinate;
+    },
+    set coordinate(value: Coordinate) {
+      check(value, [Number]);
+      check(value.length, 3);
+
+      if (!coordinateEquals(coordinate, value)) {
+        coordinate = value.slice();
+        changed.raiseEvent();
+      }
+    },
+    get heading(): number {
+      return heading;
+    },
+    set heading(value: number) {
+      check(value, Number);
+      if (heading !== value) {
+        heading = value;
+        changed.raiseEvent();
+      }
+    },
+    get pitch(): number {
+      return pitch;
+    },
+    set pitch(value: number) {
+      check(value, Number);
+      if (pitch !== value) {
+        pitch = value;
+        changed.raiseEvent();
+      }
+    },
+    get roll(): number {
+      return roll;
+    },
+    set roll(value: number) {
+      check(value, Number);
+      if (roll !== value) {
+        roll = value;
+        changed.raiseEvent();
+      }
+    },
+    get duration(): number {
+      return duration;
+    },
+    set duration(value: number) {
+      check(value, Number);
+      if (duration !== value) {
+        duration = value;
+        changed.raiseEvent();
+      }
+    },
+    get title(): string | undefined {
+      return title;
+    },
+    set title(value: string | undefined) {
+      check(value, maybe(String));
+
+      if (title !== value) {
+        title = value;
+        changed.raiseEvent();
+      }
+    },
+    destroy(): void {
+      changed.destroy();
+    },
+  };
+}
+
+export function anchorFromViewpoint(
+  viewpoint: Viewpoint,
+): FlightAnchor | undefined {
+  if (!viewpoint.cameraPosition) {
+    return undefined;
+  }
+
+  return fromOptions({
+    ...viewpoint,
+    coordinate: viewpoint.cameraPosition,
+    duration: viewpoint.duration ?? 1,
+    title: viewpoint.properties.title as string | undefined,
+  });
+}
+
+export function anchorFromGeojsonFeature(
+  feature: FlightAnchorGeojsonFeature,
+): FlightAnchor | undefined {
+  const options = {
+    ...feature.properties,
+    name: String(feature.id) || uuidv4(),
+    coordinate: feature.geometry.coordinates,
+  };
+  if (isOptions(options)) {
+    return fromOptions(options);
+  }
+  return undefined;
+}
+
+export function anchorToViewpoint(anchor: FlightAnchor): Viewpoint {
+  return new Viewpoint({
+    name: anchor.name,
+    cameraPosition: anchor.coordinate.slice(),
+    heading: anchor.heading,
+    pitch: anchor.pitch,
+    roll: anchor.roll,
+    duration: anchor.duration,
+    properties: {
+      title: anchor.title,
+    },
+  });
+}
+
+export function anchorToGeojsonFeature(
+  anchor: FlightAnchor,
+): FlightAnchorGeojsonFeature {
+  const properties: FlightAnchorFeatureProperties = {
+    heading: anchor.heading,
+    pitch: anchor.pitch,
+    roll: anchor.roll,
+    duration: anchor.duration,
+  };
+  if (anchor.title) {
+    properties.title = anchor.title;
+  }
+
+  return {
+    type: 'Feature',
+    id: anchor.name,
+    geometry: {
+      type: 'Point',
+      coordinates: anchor.coordinate.slice(),
+    },
+    properties,
+  };
+}

package/src/util/flight/flightCollection.ts

@@ -0,0 +1,78 @@
+import Collection from '../collection.js';
+import { createFlightPlayer, FlightPlayer } from './flightPlayer.js';
+import VcsEvent from '../../vcsEvent.js';
+import FlightInstance from './flightInstance.js';
+import type VcsApp from '../../vcsApp.js';
+
+/**
+ * A collection of flights. Provides playFlight API, which returns a FlightPlayer.
+ * Emits playerChanged event, whenever another flight is played.
+ */
+class FlightCollection extends Collection<FlightInstance> {
+  private readonly _app: VcsApp;
+
+  private _player: FlightPlayer | undefined;
+
+  playerChanged: VcsEvent<FlightPlayer | undefined>;
+
+  private _playerDestroyedListener: () => void;
+
+  constructor(app: VcsApp) {
+    super();
+
+    this._app = app;
+    this._player = undefined;
+    this.playerChanged = new VcsEvent<FlightPlayer | undefined>();
+    this._playerDestroyedListener = (): void => {};
+  }
+
+  get player(): FlightPlayer | undefined {
+    return this._player;
+  }
+
+  remove(item: FlightInstance): void {
+    if (this._player?.flightInstanceName === item.name) {
+      this._player.stop();
+      this._player.destroy();
+    }
+    super.remove(item);
+  }
+
+  /**
+   * Creates a FlightPlayer for a flight instance, if not already existing for provided instance
+   * @param flight
+   */
+  async setPlayerForFlight(
+    flight: FlightInstance,
+  ): Promise<FlightPlayer | undefined> {
+    if (this._player?.flightInstanceName === flight.name) {
+      return this._player;
+    } else if (this._player) {
+      this._playerDestroyedListener();
+      this._player.stop();
+      this._player.destroy();
+    }
+    this._player = await createFlightPlayer(flight, this._app);
+    this.playerChanged.raiseEvent(this._player);
+    this._playerDestroyedListener = this._player.destroyed.addEventListener(
+      () => {
+        this._player = undefined;
+        this.playerChanged.raiseEvent(undefined);
+      },
+    );
+    return this._player;
+  }
+
+  destroy(): void {
+    if (this._player) {
+      this._player.stop();
+      this._player.destroy();
+      this._player = undefined;
+    }
+    this.playerChanged.destroy();
+    this._playerDestroyedListener();
+    super.destroy();
+  }
+}
+
+export default FlightCollection;

package/src/util/flight/flightHelpers.ts

@@ -0,0 +1,208 @@
+import {
+  HeadingPitchRoll,
+  Cartesian3,
+  Quaternion,
+  CatmullRomSpline,
+  LinearSpline,
+  QuaternionSpline,
+  Cartographic,
+  Math as CesiumMath,
+} from '@vcmap-cesium/engine';
+import type {
+  FeatureCollection,
+  Point as GeojsonPoint,
+  LineString as GeojsonLineString,
+} from 'geojson';
+import type { Coordinate } from 'ol/coordinate.js';
+import type {
+  // eslint-disable-next-line import/no-named-default
+  default as FlightInstance,
+  FlightInstanceMeta,
+  FlightInstanceOptions,
+} from './flightInstance.js';
+import { vcsMetaVersion } from '../../layer/vectorProperties.js';
+import { FlightAnchorGeojsonFeature } from './flightAnchor.js';
+
+/**
+ * exports a flight as GeoJson FeatureCollection
+ * {Object} vcsMeta.flightOptions: flight settings
+ * {Array} feature: viewpoints
+ *
+ * @param flightInstance
+ */
+export function exportFlightAsGeoJson(
+  flightInstance: FlightInstance,
+): FeatureCollection<GeojsonPoint> {
+  const options = flightInstance.toJSON();
+  const flightOptions: FlightInstanceMeta = {};
+  if (options.loop != null) {
+    flightOptions.loop = options.loop;
+  }
+  if (options.interpolation != null) {
+    flightOptions.interpolation = options.interpolation;
+  }
+  if (options.multiplier != null) {
+    flightOptions.multiplier = options.multiplier;
+  }
+
+  return {
+    type: 'FeatureCollection',
+    features: options.anchors ?? [],
+    vcsMeta: {
+      version: vcsMetaVersion,
+      flightOptions: options,
+    },
+  };
+}
+
+export function getSplineAndTimesForInstance(flightInstance: FlightInstance): {
+  destinationSpline: CatmullRomSpline | LinearSpline;
+  quaternionSpline: QuaternionSpline;
+  times: number[];
+} {
+  const { loop, anchors } = flightInstance;
+  const anchorsArray = [...anchors];
+  const length = loop ? anchors.size + 1 : anchors.size;
+  const points = new Array(length) as Cartesian3[];
+  const quaternions = new Array(length) as Quaternion[];
+  const times = new Array(length) as number[];
+
+  anchorsArray.forEach((anchor, index) => {
+    points[index] = Cartesian3.fromDegrees(
+      anchor.coordinate[0],
+      anchor.coordinate[1],
+      anchor.coordinate[2],
+    );
+    quaternions[index] = Quaternion.fromHeadingPitchRoll(
+      HeadingPitchRoll.fromDegrees(anchor.heading, anchor.pitch, anchor.roll),
+    );
+
+    if (index > 0) {
+      let previousDuration = anchorsArray[index - 1].duration;
+      if (!previousDuration) {
+        previousDuration =
+          Cartesian3.distance(points[index - 1], points[index]) / 300 || 1;
+      }
+      times[index] = times[index - 1] + previousDuration;
+    } else {
+      times[index] = 0;
+    }
+  });
+
+  if (loop) {
+    points[length - 1] = Cartesian3.fromDegrees(
+      anchorsArray[0].coordinate[0],
+      anchorsArray[0].coordinate[1],
+      anchorsArray[0].coordinate[2],
+    );
+    quaternions[length - 1] = Quaternion.fromHeadingPitchRoll(
+      HeadingPitchRoll.fromDegrees(
+        anchorsArray[0].heading,
+        anchorsArray[0].pitch,
+        anchorsArray[0].roll,
+      ),
+    );
+
+    let loopDuration = anchorsArray[length - 2].duration;
+    if (!loopDuration) {
+      loopDuration =
+        Cartesian3.distance(points[length - 2], points[length - 1]) / 300 || 1;
+    }
+    times[length - 1] = times[length - 2] + loopDuration;
+  }
+
+  const destinationSpline =
+    flightInstance.interpolation === 'spline'
+      ? new CatmullRomSpline({ times, points })
+      : new LinearSpline({ times, points });
+  const quaternionSpline = new QuaternionSpline({ times, points: quaternions });
+
+  return {
+    destinationSpline,
+    quaternionSpline,
+    times,
+  };
+}
+
+export function getFlightPathCoordinatesFromInstance(
+  flightInstance: FlightInstance,
+): Coordinate[] {
+  const pathCoordinates: Coordinate[] = [];
+
+  if (flightInstance.interpolation === 'spline') {
+    const { destinationSpline, times } =
+      getSplineAndTimesForInstance(flightInstance);
+    const scratchCartographic = new Cartographic();
+    const addCoordinateFromTime = (time: number): void => {
+      Cartographic.fromCartesian(
+        destinationSpline.evaluate(time) as Cartesian3,
+        undefined,
+        scratchCartographic,
+      );
+      pathCoordinates.push([
+        CesiumMath.toDegrees(scratchCartographic.longitude),
+        CesiumMath.toDegrees(scratchCartographic.latitude),
+        scratchCartographic.height,
+      ]);
+    };
+    const endTime = times[times.length - 1];
+    const step = endTime / 0.2 > 500 ? endTime / 500 : 0.2;
+    for (let i = 0; i < endTime; i += step) {
+      addCoordinateFromTime(i);
+    }
+    addCoordinateFromTime(endTime);
+  } else {
+    for (const anchor of flightInstance.anchors) {
+      pathCoordinates.push(anchor.coordinate);
+    }
+
+    if (flightInstance.loop) {
+      pathCoordinates.push(pathCoordinates[0]);
+    }
+  }
+
+  return pathCoordinates;
+}
+
+export function exportFlightPathAsGeoJson(
+  flightInstance: FlightInstance,
+): FeatureCollection<GeojsonLineString> {
+  const coordinates = getFlightPathCoordinatesFromInstance(flightInstance);
+
+  return {
+    type: 'FeatureCollection',
+    features: [
+      {
+        type: 'Feature',
+        geometry: {
+          type: 'LineString',
+          coordinates,
+        },
+        properties: {},
+      },
+    ],
+  };
+}
+
+/**
+ * parses source and creates a flight Object
+ * @param {Object} collection GeoJSON
+ * containing:
+ * {Object} vcsMeta containing flightOptions
+ * {Array} features anchors of flightInstance
+ * @returns
+ */
+export function parseFlightOptionsFromGeoJson(
+  collection: FeatureCollection<
+    GeojsonPoint,
+    FlightAnchorGeojsonFeature['properties']
+  >,
+): FlightInstanceOptions {
+  const flightOptions: Partial<FlightInstanceOptions> =
+    collection.vcsMeta && collection.vcsMeta.flightOptions
+      ? collection.vcsMeta.flightOptions
+      : {};
+
+  flightOptions.anchors = collection.features;
+  return flightOptions;
+}

package/src/util/flight/flightInstance.ts

@@ -0,0 +1,240 @@
+import type { FeatureCollection, Point as GeojsonPoint } from 'geojson';
+import { parseBoolean, parseNumber } from '@vcsuite/parsers';
+import { check, oneOf } from '@vcsuite/check';
+import VcsObject, { VcsObjectOptions } from '../../vcsObject.js';
+import VcsEvent from '../../vcsEvent.js';
+import { parseFlightOptionsFromGeoJson } from './flightHelpers.js';
+import { requestJson } from '../fetch.js';
+import {
+  FlightAnchor,
+  anchorFromGeojsonFeature,
+  anchorToGeojsonFeature,
+  FlightAnchorGeojsonFeature,
+} from './flightAnchor.js';
+import IndexedCollection from '../indexedCollection.js';
+import { destroyCollection } from '../../vcsModuleHelpers.js';
+
+export type FlightInterpolation = 'spline' | 'linear';
+
+export type FlightInstanceMeta = VcsObjectOptions & {
+  multiplier?: number;
+  interpolation?: FlightInterpolation;
+  loop?: boolean;
+};
+
+export type FlightInstanceOptions = FlightInstanceMeta & {
+  anchors?: FlightAnchorGeojsonFeature[];
+  url?: string;
+};
+
+class FlightInstance extends VcsObject {
+  static get className(): string {
+    return 'FlightInstance';
+  }
+
+  anchors: IndexedCollection<FlightAnchor>;
+
+  private _multiplier: number;
+
+  private _loop: boolean;
+
+  private _interpolation: FlightInterpolation;
+
+  /**
+   * Raised when anchors are added, removed, moved or changed
+   */
+  anchorsChanged = new VcsEvent<void>();
+
+  /**
+   * Raised when multiplier, loop or interpolation changes.
+   */
+  propertyChanged = new VcsEvent<'multiplier' | 'loop' | 'interpolation'>();
+
+  private readonly _url: string | undefined;
+
+  private _readyPromise: Promise<void> | null = null;
+
+  private _anchorListeners: Map<string, () => void> = new Map();
+
+  static getDefaultOptions(): FlightInstanceOptions {
+    return {
+      multiplier: 1,
+      loop: false,
+      interpolation: 'spline',
+      anchors: [],
+    };
+  }
+
+  constructor(options: FlightInstanceOptions) {
+    super(options);
+
+    const defaultOptions = FlightInstance.getDefaultOptions();
+    const anchorsArray = (options.anchors ?? defaultOptions.anchors!)
+      .map(anchorFromGeojsonFeature)
+      .filter((a): a is FlightAnchor => !!a);
+
+    this.anchors = IndexedCollection.from(anchorsArray);
+
+    this._multiplier = parseNumber(
+      options.multiplier,
+      defaultOptions.multiplier,
+    );
+
+    this._loop = parseBoolean(options.loop, defaultOptions.loop);
+
+    this._interpolation =
+      options.interpolation || defaultOptions.interpolation!;
+
+    this.anchorsChanged = new VcsEvent();
+
+    this._url = options.url;
+  }
+
+  get initialized(): boolean {
+    return !!this._readyPromise;
+  }
+
+  get multiplier(): number {
+    return this._multiplier;
+  }
+
+  set multiplier(value: number) {
+    check(value, Number);
+
+    if (this._multiplier !== value) {
+      this._multiplier = value;
+      this.propertyChanged.raiseEvent('multiplier');
+    }
+  }
+
+  /**
+   * Whether this flight represents a circular flight path or not
+   */
+  get loop(): boolean {
+    return this._loop;
+  }
+
+  set loop(value: boolean) {
+    check(value, Boolean);
+
+    if (this._loop !== value) {
+      this._loop = value;
+      this.propertyChanged.raiseEvent('loop');
+    }
+  }
+
+  get interpolation(): FlightInterpolation {
+    return this._interpolation;
+  }
+
+  set interpolation(value: FlightInterpolation) {
+    check(value, oneOf('linear', 'spline'));
+
+    if (this._interpolation !== value) {
+      this._interpolation = value;
+      this.propertyChanged.raiseEvent('interpolation');
+    }
+  }
+
+  initialize(): Promise<void> {
+    if (!this._readyPromise) {
+      if (this._url) {
+        this._readyPromise = requestJson<
+          FeatureCollection<
+            GeojsonPoint,
+            FlightAnchorGeojsonFeature['properties']
+          >
+        >(this._url).then((collection) => {
+          const instance = parseFlightOptionsFromGeoJson(collection);
+          (instance.anchors ?? [])
+            .map(anchorFromGeojsonFeature)
+            .filter((a): a is FlightAnchor => !!a)
+            .forEach((anchor) => this.anchors.add(anchor));
+          this._multiplier = instance.multiplier ?? this._multiplier;
+          this._loop = instance.loop ?? this._loop;
+          this._interpolation = instance.interpolation ?? this._interpolation;
+        });
+      } else {
+        this._readyPromise = Promise.resolve();
+      }
+      for (const anchor of this.anchors) {
+        this._anchorListeners.set(
+          anchor.name,
+          anchor.changed.addEventListener(() => {
+            this.anchorsChanged.raiseEvent();
+          }),
+        );
+      }
+
+      this.anchors.added.addEventListener((anchor) => {
+        this._anchorListeners.set(
+          anchor.name,
+          anchor.changed.addEventListener(() => {
+            this.anchorsChanged.raiseEvent();
+          }),
+        );
+        this.anchorsChanged.raiseEvent();
+      });
+
+      this.anchors.removed.addEventListener((anchor) => {
+        this._anchorListeners.get(anchor.name)?.();
+        this._anchorListeners.delete(anchor.name);
+        this.anchorsChanged.raiseEvent();
+      });
+
+      this.anchors.moved.addEventListener(() => {
+        this.anchorsChanged.raiseEvent();
+      });
+    }
+
+    return this._readyPromise;
+  }
+
+  /**
+   * checks if this flightInstance is valid. To be valid, a flight must have at least 2 anchors.
+   * @returns
+   */
+  isValid(): boolean {
+    return this.anchors.size >= 2;
+  }
+
+  /**
+   * returns an options object for this flight. if this flight was configured via an URL, only the url will be configured.
+   * @returns
+   */
+  toJSON(): FlightInstanceOptions {
+    const config = super.toJSON() as FlightInstanceOptions;
+
+    if (this._url) {
+      config.url = this._url;
+      return config;
+    }
+
+    const defaultOptions = FlightInstance.getDefaultOptions();
+    if (this._multiplier !== defaultOptions.multiplier) {
+      config.multiplier = this._multiplier;
+    }
+
+    if (this._loop !== defaultOptions.loop) {
+      config.loop = this._loop;
+    }
+
+    if (this._interpolation !== defaultOptions.interpolation) {
+      config.interpolation = this._interpolation;
+    }
+
+    if (this.anchors.size > 0) {
+      config.anchors = [...this.anchors].map(anchorToGeojsonFeature);
+    }
+    return config;
+  }
+
+  destroy(): void {
+    this.anchorsChanged.destroy();
+    destroyCollection(this.anchors);
+    this._anchorListeners.clear();
+    super.destroy();
+  }
+}
+
+export default FlightInstance;