@vcmap/core 5.0.0-rc.8 → 5.0.0

package/src/util/clipping/{clippingPlaneHelper.js → clippingPlaneHelper.ts}

@@ -10,50 +10,68 @@ import {
   JulianDate,
   Cesium3DTileset,
   Globe,
-} from '@vcmap/cesium';
+  type Camera,
+} from '@vcmap-cesium/engine';
+import type { Coordinate } from 'ol/coordinate.js';
+import type { Geometry } from 'ol/geom.js';
 import Feature from 'ol/Feature.js';
 import LineString from 'ol/geom/LineString.js';
 import { offset } from 'ol/sphere.js';
-import GeometryLayout from 'ol/geom/GeometryLayout.js';
 import Polygon from 'ol/geom/Polygon.js';
-
 import { check, checkMaybe } from '@vcsuite/check';
-import Projection, { mercatorProjection, wgs84Projection } from '../projection.js';
+import Projection, {
+  mercatorProjection,
+  wgs84Projection,
+} from '../projection.js';
 import Extent3D from '../featureconverter/extent3D.js';
-import { enforceEndingVertex, enforceRightHand, getFlatCoordinatesFromGeometry } from '../geometryHelpers.js';
+import {
+  enforceEndingVertex,
+  enforceRightHand,
+  getFlatCoordinatesFromGeometry,
+} from '../geometryHelpers.js';
+import { mercatorToCartesian } from '../math.js';
 
 /**
  * Options to the define how Cesium.ClippingPlanes are created from a ol.Feature.
- * @typedef {Object} CreationOptions
- * @property {boolean|undefined} reverse - specify the clip direction. If true, everything outside the clippingPlaneCollection should be cut off
- * @property {boolean|undefined} createVerticalPlanes - specify whether to create the vertical clipping planes
- * @property {boolean|undefined} createTopPlane - specify whether to create the horizontal clipping plane on the top level of an extruded geometry
- * @property {boolean|undefined} createBottomPlane - specify whether to create the horizontal clipping plane on the ground level
- * @property {boolean|undefined} createEndingPlanes - create 2 planes at the end of a line with only two coordinates
- * @api
  */
+export type ClippingPlaneCreationOptions = {
+  /**
+   * specify the clip direction. If true, everything outside the clippingPlaneCollection should be cut off
+   */
+  reverse?: boolean;
+  /**
+   * specify whether to create the vertical clipping planes
+   */
+  createVerticalPlanes?: boolean;
+  /**
+   * specify whether to create the horizontal clipping plane on the top level of an extruded geometry
+   */
+  createTopPlane?: boolean;
+  /**
+   * specify whether to create the horizontal clipping plane on the ground level
+   */
+  createBottomPlane?: boolean;
+  /**
+   * create 2 planes at the end of a line with only two coordinates
+   */
+  createEndingPlanes?: boolean;
+};
 
 /**
  * Creates a Plane on p1 with the normal in the direction of P2
- * @param {import("@vcmap/cesium").Cartesian3} p1
- * @param {import("@vcmap/cesium").Cartesian3} p2
- * @returns {import("@vcmap/cesium").ClippingPlane}
+ * @param  p1
+ * @param  p2
  */
-function createPlane(p1, p2) {
+function createPlane(p1: Cartesian3, p2: Cartesian3): ClippingPlane {
   const planeNormal = Cartesian3.subtract(p1, p2, new Cartesian3());
   Cartesian3.normalize(planeNormal, planeNormal);
   const plane = Plane.fromPointNormal(p1, planeNormal);
   return ClippingPlane.fromPlane(plane);
 }
 
-/**
- * @param {Array<import("ol/coordinate").Coordinate>} coords
- * @returns {Array<import("@vcmap/cesium").ClippingPlane>} clippingPlanes
- */
-function createVerticalPlanes(coords) {
+function createVerticalPlanes(coords: Coordinate[]): ClippingPlane[] {
   const clippingPlanes = [];
-  // @ts-ignore
-  const cartesiansCoords = coords.map(c => Cartesian3.fromDegrees(...Projection.mercatorToWgs84(c)));
+  const cartesiansCoords = coords.map((c) => mercatorToCartesian(c));
   for (let i = 0; i < cartesiansCoords.length - 1; i++) {
     const nextIndex = i + 1;
     const normal = new Cartesian3();
@@ -67,18 +85,16 @@ function createVerticalPlanes(coords) {
   return clippingPlanes;
 }
 
-/**
- * @param {import("ol").Feature<import("ol/geom/Geometry").default>} feature
- * @param {Array<import("ol/coordinate").Coordinate>} coords
- * @param {CreationOptions=} options
- * @returns {Array<import("@vcmap/cesium").ClippingPlane>} clippingPlanes
- */
-function createHorizontalPlanes(feature, coords, options) {
+function createHorizontalPlanes(
+  feature: Feature,
+  coords: Coordinate[],
+  options: ClippingPlaneCreationOptions = {},
+): ClippingPlane[] {
   const clippingPlanes = [];
   const extent = Extent3D.fromGeometry(feature.getGeometry());
   let min = Number.isFinite(extent.minZ) ? extent.minZ : 0;
   let max = Number.isFinite(extent.maxZ) ? extent.maxZ : 0;
-  const extruded = feature.get('olcs_extrudedHeight');
+  const extruded = feature.get('olcs_extrudedHeight') as number | undefined;
   if (extruded) {
     max += extruded;
     if (feature.get('olcs_skirt')) {
@@ -86,7 +102,6 @@ function createHorizontalPlanes(feature, coords, options) {
     }
   }
 
-
   if (min === max) {
     max += 1;
   }
@@ -106,18 +121,17 @@ function createHorizontalPlanes(feature, coords, options) {
 /**
  * creates a plane for each point in the opposite direction of the other point.
  * only works for two coordinates
- * @param {Array<import("ol/coordinate").Coordinate>} coords
- * @returns {Array<import("@vcmap/cesium").ClippingPlane>} clippingPlanes
+ * @param  coords
+ * @returns  clippingPlanes
  */
-function createEndingPlanes(coords) {
-  const clippingPlanes = [];
-  // @ts-ignore
-  const cartesiansCoords = coords.map(c => Cartesian3.fromDegrees(...Projection.mercatorToWgs84(c)));
+function createEndingPlanes(coords: Coordinate[]): ClippingPlane[] {
+  const clippingPlanes: ClippingPlane[] = [];
+  const cartesiansCoords = coords.map((c) => mercatorToCartesian(c));
   const normal = new Cartesian3();
   Cartesian3.cross(cartesiansCoords[0], cartesiansCoords[1], normal);
   Cartesian3.normalize(normal, normal);
 
-  function createOuter(cartesian) {
+  function createOuter(cartesian: Cartesian3): void {
     const moved = Cartesian3.add(cartesian, normal, new Cartesian3());
     const planeNormal = new Cartesian3();
     Cartesian3.cross(cartesian, moved, planeNormal);
@@ -134,34 +148,48 @@ function createEndingPlanes(coords) {
 
 /**
  * create a Cesium ClippingPlaneCollection based on a given feature having a multi-curve, polygon, or extruded solid geometry
- * @param {import("ol").Feature<import("ol/geom/Geometry").default>} feature - base for calculating the clipping planes.
- * @param {CreationOptions=} options
- * @param {import("@vcmap/cesium").Matrix4=} transformMatrix - 4x4 matrix specifying the transform of clipping planes from Earth's fixed frame to another one
- * @returns {import("@vcmap/cesium").ClippingPlaneCollection|null}
- * @api stable
- * @export
+ * @param  feature - base for calculating the clipping planes.
+ * @param  options
+ * @param  transformMatrix - 4x4 matrix specifying the transform of clipping planes from Earth's fixed frame to another one
  */
-export function createClippingPlaneCollection(feature, options = {}, transformMatrix) {
+export function createClippingPlaneCollection(
+  feature: Feature,
+  options: ClippingPlaneCreationOptions = {},
+  transformMatrix: Matrix4 | undefined = undefined,
+): ClippingPlaneCollection | null {
   check(feature, Feature);
   check(options, Object);
   checkMaybe(transformMatrix, Matrix4);
 
   const clippingPlanes = [];
-  const geometry = feature.getGeometry();
+  const geometry = feature.getGeometry() as Geometry;
   const geometryType = geometry.getType();
 
   if (geometryType === 'Point') {
-    clippingPlanes.push(...createHorizontalPlanes(feature, [geometry.getCoordinates()], options));
+    clippingPlanes.push(
+      ...createHorizontalPlanes(
+        feature,
+        [geometry.getCoordinates() as Coordinate],
+        options,
+      ),
+    );
   } else {
     const coords = getFlatCoordinatesFromGeometry(geometry);
-    if (coords.length < 2 || (coords[0][0] === coords[1][0] && coords[0][1] === coords[1][1])) {
+    if (
+      coords.length < 2 ||
+      (coords[0][0] === coords[1][0] && coords[0][1] === coords[1][1])
+    ) {
       return null;
     }
 
     if (geometryType === 'Polygon') {
       enforceEndingVertex(coords);
       enforceRightHand(coords);
-    } else if (geometryType === 'LineString' && coords.length === 2 && options.createEndingPlanes) {
+    } else if (
+      geometryType === 'LineString' &&
+      coords.length === 2 &&
+      options.createEndingPlanes
+    ) {
       clippingPlanes.push(...createEndingPlanes(coords));
     }
 
@@ -169,13 +197,16 @@ export function createClippingPlaneCollection(feature, options = {}, transformMa
       clippingPlanes.push(...createVerticalPlanes(coords));
     }
 
-    if (feature.get('olcs_altitudeMode') === 'absolute' && (options.createBottomPlane || options.createTopPlane)) {
+    if (
+      feature.get('olcs_altitudeMode') === 'absolute' &&
+      (options.createBottomPlane || options.createTopPlane)
+    ) {
       clippingPlanes.push(...createHorizontalPlanes(feature, coords, options));
     }
   }
 
   if (transformMatrix) {
-    clippingPlanes.forEach((/** @type {import("@vcmap/cesium").ClippingPlane} */ plane) => {
+    clippingPlanes.forEach((plane) => {
       const result = Plane.transform(plane, transformMatrix);
       plane.normal = result.normal;
       plane.distance = result.distance;
@@ -183,7 +214,7 @@ export function createClippingPlaneCollection(feature, options = {}, transformMa
   }
 
   if (options.reverse) {
-    clippingPlanes.forEach((/** @type {import("@vcmap/cesium").ClippingPlane} */ plane) => {
+    clippingPlanes.forEach((plane) => {
       Cartesian3.negate(plane.normal, plane.normal);
       plane.distance *= -1;
     });
@@ -197,15 +228,17 @@ export function createClippingPlaneCollection(feature, options = {}, transformMa
 
 /**
  * copies the clippingplanes and the properties from source to result
- * @param {import("@vcmap/cesium").ClippingPlaneCollection} source
- * @param {import("@vcmap/cesium").ClippingPlaneCollection} result
- * @param {import("@vcmap/cesium").Matrix4=} transformMatrix - 4x4 matrix specifying the transform of clipping planes from Earth's fixed frame to another one
- * @param {import("@vcmap/cesium").Cartesian3=} originPoint - the origin point of the transformation target, so the plane distance can be set correctly
- * @returns {import("@vcmap/cesium").ClippingPlaneCollection}
- * @api stable
- * @export
+ * @param  source
+ * @param  result
+ * @param  transformMatrix - 4x4 matrix specifying the transform of clipping planes from Earth's fixed frame to another one
+ * @param  originPoint - the origin point of the transformation target, so the plane distance can be set correctly
  */
-export function copyClippingPlanesToCollection(source, result, transformMatrix, originPoint) {
+export function copyClippingPlanesToCollection(
+  source: ClippingPlaneCollection,
+  result: ClippingPlaneCollection,
+  transformMatrix?: Matrix4,
+  originPoint?: Cartesian3,
+): ClippingPlaneCollection {
   check(source, ClippingPlaneCollection);
   check(result, ClippingPlaneCollection);
 
@@ -230,18 +263,20 @@ export function copyClippingPlanesToCollection(source, result, transformMatrix,
   return result;
 }
 
-/**
- * @param {import("@vcmap/cesium").Globe|import("@vcmap/cesium").Cesium3DTileset|import("@vcmap/cesium").Entity} target
- */
-export function clearClippingPlanes(target) {
+export function clearClippingPlanes(
+  target: Globe | Cesium3DTileset | Entity,
+): void {
   if (target instanceof Entity) {
     if (target.model) {
       if (target.model.clippingPlanes) {
-        const entityClippingPlanes =
-          (/** @type {import("@vcmap/cesium").ConstantProperty} */ (target.model.clippingPlanes)).getValue();
+        const entityClippingPlanes = (
+          target.model.clippingPlanes as ConstantProperty
+        ).getValue() as ClippingPlaneCollection;
         entityClippingPlanes.removeAll();
       } else {
-        target.model.clippingPlanes = new ConstantProperty(new ClippingPlaneCollection());
+        target.model.clippingPlanes = new ConstantProperty(
+          new ClippingPlaneCollection(),
+        );
       }
     }
   } else if (target.clippingPlanes) {
@@ -251,17 +286,19 @@ export function clearClippingPlanes(target) {
   }
 }
 
-/**
- * @param {import("@vcmap/cesium").Cesium3DTileset} cesium3DTileset
- * @param {import("@vcmap/cesium").ClippingPlaneCollection} clippingPlaneCollection
- * @param {boolean=} local
- */
-function setTilesetClippingPlane(cesium3DTileset, clippingPlaneCollection, local) {
+function setTilesetClippingPlane(
+  cesium3DTileset: Cesium3DTileset,
+  clippingPlaneCollection: ClippingPlaneCollection,
+  local?: boolean,
+): void {
   clearClippingPlanes(cesium3DTileset);
   // copyClippingPlanesToCollection(clippingPlaneCollection, cesium3DTileset.clippingPlanes); XXX this is in release-4.0 but i think its an oversight
   if (!local) {
     if (!clippingPlaneCollection.modelMatrix.equals(Matrix4.IDENTITY)) {
-      copyClippingPlanesToCollection(clippingPlaneCollection, cesium3DTileset.clippingPlanes);
+      copyClippingPlanesToCollection(
+        clippingPlaneCollection,
+        cesium3DTileset.clippingPlanes,
+      );
       cesium3DTileset.clippingPlanes.modelMatrix = Matrix4.multiply(
         Matrix4.inverse(
           cesium3DTileset.clippingPlanesOriginMatrix,
@@ -272,10 +309,16 @@ function setTilesetClippingPlane(cesium3DTileset, clippingPlaneCollection, local
       );
     } else {
       const rotation = Matrix4.getMatrix3(
-        Matrix4.inverse(cesium3DTileset.clippingPlanesOriginMatrix, new Matrix4()),
+        Matrix4.inverse(
+          cesium3DTileset.clippingPlanesOriginMatrix,
+          new Matrix4(),
+        ),
         new Matrix3(),
       );
-      const transformationMatrix = Matrix4.fromRotationTranslation(rotation, new Cartesian3());
+      const transformationMatrix = Matrix4.fromRotationTranslation(
+        rotation,
+        new Cartesian3(),
+      );
       copyClippingPlanesToCollection(
         clippingPlaneCollection,
         cesium3DTileset.clippingPlanes,
@@ -284,34 +327,47 @@ function setTilesetClippingPlane(cesium3DTileset, clippingPlaneCollection, local
       );
     }
   } else {
-    copyClippingPlanesToCollection(clippingPlaneCollection, cesium3DTileset.clippingPlanes);
+    copyClippingPlanesToCollection(
+      clippingPlaneCollection,
+      cesium3DTileset.clippingPlanes,
+    );
   }
 }
 
-/**
- * @param {import("@vcmap/cesium").Globe} globe
- * @param {import("@vcmap/cesium").ClippingPlaneCollection} clippingPlaneCollection
- */
-function setGlobeClippingPlanes(globe, clippingPlaneCollection) {
+function setGlobeClippingPlanes(
+  globe: Globe,
+  clippingPlaneCollection: ClippingPlaneCollection,
+): void {
   clearClippingPlanes(globe);
   copyClippingPlanesToCollection(clippingPlaneCollection, globe.clippingPlanes);
 }
 
 /**
  * apply a clippingPlaneCollection to an entity
- * @param {import("@vcmap/cesium").Entity} entity
- * @param {import("@vcmap/cesium").ClippingPlaneCollection} clippingPlaneCollection
- * @param {boolean=} local
+ * @param  entity
+ * @param  clippingPlaneCollection
+ * @param  local
  */
-function setEntityClippingPlanes(entity, clippingPlaneCollection, local) {
+function setEntityClippingPlanes(
+  entity: Entity,
+  clippingPlaneCollection: ClippingPlaneCollection,
+  local?: boolean,
+): void {
   if (entity.model) {
     clearClippingPlanes(entity);
-    const entityClippingPlanes =
-      (/** @type {import("@vcmap/cesium").ConstantProperty} */ (entity.model.clippingPlanes)).getValue();
-    copyClippingPlanesToCollection(clippingPlaneCollection, entityClippingPlanes);
+    const entityClippingPlanes = (
+      entity.model.clippingPlanes as ConstantProperty
+    ).getValue() as ClippingPlaneCollection;
+    copyClippingPlanesToCollection(
+      clippingPlaneCollection,
+      entityClippingPlanes,
+    );
     if (!local) {
       const localToFixedFrame = entity.computeModelMatrix(JulianDate.now());
-      Matrix4.inverseTransformation(localToFixedFrame, entityClippingPlanes.modelMatrix);
+      Matrix4.inverseTransformation(
+        localToFixedFrame,
+        entityClippingPlanes.modelMatrix,
+      );
       if (!clippingPlaneCollection.modelMatrix.equals(Matrix4.IDENTITY)) {
         Matrix4.multiply(
           entityClippingPlanes.modelMatrix,
@@ -324,11 +380,15 @@ function setEntityClippingPlanes(entity, clippingPlaneCollection, local) {
 }
 
 /**
- * @param {import("@vcmap/cesium").Globe|import("@vcmap/cesium").Cesium3DTileset|import("@vcmap/cesium").Entity} target
- * @param {import("@vcmap/cesium").ClippingPlaneCollection} clippingPlaneCollection
- * @param {boolean=} local
+ * @param  target
+ * @param  clippingPlaneCollection
+ * @param  local
  */
-export function setClippingPlanes(target, clippingPlaneCollection, local) {
+export function setClippingPlanes(
+  target: Globe | Cesium3DTileset | Entity,
+  clippingPlaneCollection: ClippingPlaneCollection,
+  local?: boolean,
+): void {
   if (target instanceof Cesium3DTileset) {
     setTilesetClippingPlane(target, clippingPlaneCollection, local);
   } else if (target instanceof Globe) {
@@ -339,16 +399,19 @@ export function setClippingPlanes(target, clippingPlaneCollection, local) {
 }
 
 /**
- * Creates a new feature at the given coordinate, which can be set on a {@link ClippingObjectEditor}.
- * @param {import("ol/coordinate").Coordinate} coordinate - in WGS84
- * @param {import("@vcmap/cesium").Camera} camera
- * @param {boolean} [vertical=false]
- * @param {number} [offsetDistance=25] - the offset from the coordinate to use for the size of the geometry
- * @returns {import("ol").Feature<import("ol/geom/Geometry").default>} - the features geometry is in web mercator
- * @api
- * @export
+ * Creates a new feature at the given coordinate, which can be set on a .
+ * @param  coordinate - in WGS84
+ * @param  camera
+ * @param  [vertical=false]
+ * @param  [offsetDistance=25] - the offset from the coordinate to use for the size of the geometry
+ * @returns  - the features geometry is in web mercator
  */
-export function createClippingFeature(coordinate, camera, vertical = false, offsetDistance = 25) {
+export function createClippingFeature(
+  coordinate: Coordinate,
+  camera: Camera,
+  vertical = false,
+  offsetDistance = 25,
+): Feature {
   check(coordinate, [Number]);
   check(vertical, Boolean);
   check(offsetDistance, Number);
@@ -357,17 +420,19 @@ export function createClippingFeature(coordinate, camera, vertical = false, offs
   if (vertical) {
     const p1 = offset(coordinate, -offsetDistance, camera.heading);
     const p2 = offset(coordinate, offsetDistance, camera.heading);
-    geometry = new LineString([
-      [p1[0], p1[1], coordinate[2]],
-      [p2[0], p2[1], coordinate[2]],
-      // @ts-ignore
-    ], GeometryLayout.XYZ);
+    geometry = new LineString(
+      [
+        [p1[0], p1[1], coordinate[2]],
+        [p2[0], p2[1], coordinate[2]],
+      ],
+      'XYZ',
+    );
   } else {
-    geometry = new Polygon([[]], GeometryLayout.XYZ);
-    let bearing = (2 * Math.PI) - (Math.PI / 4); // Bearing NW
-    const coordinates = [...new Array(4)].map(() => {
+    geometry = new Polygon([[]], 'XYZ');
+    let bearing = 2 * Math.PI - Math.PI / 4; // Bearing NW
+    const coordinates = [...(new Array(4) as undefined[])].map(() => {
       const newPoint = offset(coordinate, offsetDistance, bearing);
-      bearing -= (Math.PI / 2);
+      bearing -= Math.PI / 2;
       return [newPoint[0], newPoint[1], coordinate[2]];
     });
     geometry.setCoordinates([coordinates]);
@@ -384,30 +449,30 @@ export function createClippingFeature(coordinate, camera, vertical = false, offs
 
 /**
  * Gets the clipping options for the current feature to be infinite or not for the given feature created by
- * {@link createClippingFeature}.
- * @param {import("ol").Feature<import("ol/geom/Geometry").default>=} feature - the feature created by {@link createClippingFeature}
- * @param {boolean=} [infinite=false]
- * @returns {CreationOptions}
- * @api
- * @export
+ * .
+ * @param  feature - the feature created by
+ * @param  [infinite=false]
  */
-export function getClippingOptions(feature, infinite = false) {
+export function getClippingOptions(
+  feature?: Feature,
+  infinite = false,
+): ClippingPlaneCreationOptions {
   checkMaybe(feature, Feature);
   check(infinite, Boolean);
 
-  const vertical = feature ?
-    feature.getGeometry().getType() === 'LineString' :
-    false;
+  const vertical = feature
+    ? feature.getGeometry()!.getType() === 'LineString'
+    : false;
 
-  return vertical ?
-    {
-      createBottomPlane: !infinite,
-      createTopPlane: !infinite,
-      createEndingPlanes: !infinite,
-      createVerticalPlanes: true,
-    } :
-    {
-      createVerticalPlanes: !infinite,
-      createBottomPlane: true,
-    };
+  return vertical
+    ? {
+        createBottomPlane: !infinite,
+        createTopPlane: !infinite,
+        createEndingPlanes: !infinite,
+        createVerticalPlanes: true,
+      }
+    : {
+        createVerticalPlanes: !infinite,
+        createBottomPlane: true,
+      };
 }