@itowns/geographic 2.46.1-next.5 → 2.46.1-next.51

package/lib/Extent.d.ts

@@ -0,0 +1,246 @@
+import { Vector2, Vector4, Box3, type Matrix4 } from 'three';
+import Coordinates from './Coordinates';
+import type { ProjectionLike } from './Crs';
+export interface ExtentLike {
+    readonly west: number;
+    readonly east: number;
+    readonly south: number;
+    readonly north: number;
+}
+/**
+ * A class representing a geographical extent.
+ *
+ * An extent is a geographical bounding rectangle defined by 4 limits: west,
+ * east, south and north.
+ *
+ * **Warning**: Using a geocentric projection is not suitable for representing a
+ * geographical extent. Please use a geographic projection.
+ */
+declare class Extent {
+    /**
+     * Read-only flag to check if a given object is of type `Extent`.
+     */
+    readonly isExtent: true;
+    /**
+     * A default or user-defined CRS (see {@link ProjectionLike}).
+     */
+    crs: ProjectionLike;
+    /**
+     * West longitude bound of this extent.
+     */
+    west: number;
+    /**
+     * East longitude bound of this extent.
+     */
+    east: number;
+    /**
+     * South latitude bound of this extent.
+     */
+    south: number;
+    /**
+     * North latitude bound of this extent.
+     */
+    north: number;
+    /**
+     * @param crs - A default or user-defined CRS (see {@link ProjectionLike}).
+     * @param west - the `west` value of this extent. Default is 0.
+     * @param east - the `east` value of this extent. Default is 0.
+     * @param south - the `south` value of this extent. Default is 0.
+     * @param north - the `north` value of this extent. Default is 0.
+     */
+    constructor(crs: ProjectionLike, west?: number, east?: number, south?: number, north?: number);
+    /**
+     * Returns a new extent with the same bounds and crs as this one.
+     */
+    clone(): Extent;
+    /**
+     * Projects this extent to the specified projection.
+     *
+     * @param crs - target's projection.
+     * @param target - The target to store the projected extent. If this not
+     * provided a new extent will be created.
+     */
+    as(crs: string, target?: Extent): Extent;
+    /**
+     * Returns the center of the extent.
+     *
+     * @param target - The target to store the center coordinate. If this not
+     * provided a new coordinate will be created.
+     */
+    center(target?: Coordinates): Coordinates;
+    /**
+     * Returns the planar dimensions as two-vector planar distances west/east
+     * and south/north.
+     * The planar distance is a straight-line Euclidean distance calculated in a
+     * 2D Cartesian coordinate system.
+     *
+     * @param target - optional target
+     */
+    planarDimensions(target?: Vector2): Vector2;
+    /**
+     * Returns the geodetic dimensions as two-vector planar distances west/east
+     * and south/north.
+     * Geodetic distance is calculated in an ellispoid space as the distance
+     * across the curved surface of the ellipsoid.
+     *
+     * @param target - optional target
+     */
+    geodeticDimensions(target?: Vector2): Vector2;
+    /**
+     *  Returns the spatial euclidean dimensions as a two-vector spatial
+     *  euclidean distances between west/east corner and south/north corner.
+     *  Spatial euclidean distance chord is calculated in an ellispoid space.
+     *
+     * @param target - optional target
+     */
+    spatialEuclideanDimensions(target?: Vector2): Vector2;
+    /**
+     * Checks whether a coordinates is inside the extent.
+     *
+     * @param coord - the given coordinates.
+     * @param epsilon - error margin when comparing to the coordinates.
+     * Default is 0.
+     */
+    isPointInside(coord: Coordinates, epsilon?: number): boolean;
+    /**
+     * Checks whether another extent is inside the extent.
+     *
+     * @param extent - the extent to check
+     * @param epsilon - error margin when comparing the extent bounds.
+     */
+    isInside(extent: Extent, epsilon?: number): boolean;
+    /**
+     * Return the translation and scale to transform this extent to the input
+     * extent.
+     *
+     * @param extent - input extent
+     * @param target - copy the result to target.
+     * @returns A {@link THREE.Vector4} where the `x` property encodes the
+     * translation on west-east, the `y` property the translation on
+     * south-north, the `z` property the scale on west-east, the `w` property
+     * the scale on south-north.
+     */
+    offsetToParent(extent: Extent, target?: Vector4): Vector4;
+    /**
+     * Checks wheter this bounding box intersects with the given extent
+     * parameter.
+     * @param extent - the provided extent
+     */
+    intersectsExtent(extent: Extent): boolean;
+    static intersectsExtent(extentA: Extent, extentB: Extent): boolean;
+    /**
+     * Returns the intersection of this extent with another one.
+     * @param extent - extent to intersect
+     */
+    intersect(extent: Extent): Extent;
+    /**
+     * Set west, east, south and north values.
+     *
+     * @param v0 - the `west` value of this extent. Default is 0.
+     * @param v1 - the `east` value of this extent. Default is 0.
+     * @param v2 - the `south` value of this extent. Default is 0.
+     * @param v3 - the `north` value of this extent. Default is 0.
+     */
+    set(v0: number, v1: number, v2: number, v3: number): this;
+    /**
+     * Sets this extent `west` property to `array[offset + 0]`, `east` property
+     * to `array[offset + 1]`, `south` property to `array[offset + 2]` and
+     * `north` property to `array[offset + 3]`.
+     * @param array - the source array
+     * @param offset - offset into the array. Default is 0.
+     */
+    setFromArray(array: ArrayLike<number>, offset?: number): this;
+    /**
+     * Sets this extent `west`, `east`, `south` and `north` properties from an
+     * `extent` bounds.
+     * @param extent - the source extent
+     */
+    setFromExtent(extent: ExtentLike): this;
+    /**
+     * Copies the passed extent to this extent.
+     * @param extent - extent to copy.
+     */
+    copy(extent: Extent): this;
+    /**
+     * Union this extent with the input extent.
+     * @param extent - the extent to union.
+     */
+    union(extent: Extent): void;
+    /**
+     * expandByCoordinates perfoms the minimal extension
+     * for the coordinates to belong to this Extent object
+     * @param coordinates - The coordinates to belong
+     */
+    expandByCoordinates(coordinates: Coordinates): void;
+    /**
+    * expandByValuesCoordinates perfoms the minimal extension
+    * for the coordinates values to belong to this Extent object
+    * @param we - The coordinate on west-east
+    * @param sn - The coordinate on south-north
+    *
+    */
+    expandByValuesCoordinates(we: number, sn: number): void;
+    /**
+     * Instance Extent with THREE.Box3.
+     *
+     * If crs is a geocentric projection, the `box3.min` and `box3.max`
+     * should be the geocentric coordinates of `min` and `max` of a `box3`
+     * in local tangent plane.
+     *
+     * @param crs - Projection of extent to instancied.
+     * @param box - Bounding-box
+     */
+    static fromBox3(crs: ProjectionLike, box: Box3): Extent;
+    /**
+     * Return values of extent in string, separated by the separator input.
+     * @param sep - string separator
+     */
+    toString(sep?: string): string;
+    /**
+     * Subdivide equally an extent from its center to return four extents:
+     * north-west, north-east, south-west and south-east.
+     *
+     * @returns An array containing the four sections of the extent. The order
+     * of the sections is [NW, NE, SW, SE].
+     */
+    subdivision(): Extent[];
+    /**
+     * subdivise extent by scheme.x on west-east and scheme.y on south-north.
+     *
+     * @param scheme - The scheme to subdivise.
+     * @returns subdivised extents.
+     */
+    subdivisionByScheme(scheme?: Vector2): Extent[];
+    /**
+     * Multiplies all extent `coordinates` (with an implicit 1 in the 4th
+     * dimension) and `matrix`.
+     *
+     * @param matrix - The matrix
+     * @returns return this extent instance.
+     */
+    applyMatrix4(matrix: Matrix4): this;
+    /**
+     * clamp south and north values
+     *
+     * @param south - The min south
+     * @param north - The max north
+     * @returns this extent
+     */
+    clampSouthNorth(south?: number, north?: number): this;
+    /**
+     * clamp west and east values
+     *
+     * @param west - The min west
+     * @param east - The max east
+     * @returns this extent
+     */
+    clampWestEast(west?: number, east?: number): this;
+    /**
+     * clamp this extent by passed extent
+     *
+     * @param extent - The maximum extent.
+     * @returns this extent.
+     */
+    clampByExtent(extent: ExtentLike): this;
+}
+export default Extent;

package/lib/Extent.js

@@ -54,11 +54,7 @@ class Extent {
    * @param south - the `south` value of this extent. Default is 0.
    * @param north - the `north` value of this extent. Default is 0.
    */
-  constructor(crs) {
-    let west = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 0;
-    let east = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 0;
-    let south = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : 0;
-    let north = arguments.length > 4 && arguments[4] !== undefined ? arguments[4] : 0;
+  constructor(crs, west = 0, east = 0, south = 0, north = 0) {
     if (CRS.isGeocentric(crs)) {
       throw new Error(`Non-compatible geocentric projection ${crs} to build a geographical extent`);
     }
@@ -85,8 +81,7 @@ class Extent {
    * @param target - The target to store the projected extent. If this not
    * provided a new extent will be created.
    */
-  as(crs) {
-    let target = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : new Extent('EPSG:4326');
+  as(crs, target = new Extent('EPSG:4326')) {
     CRS.isValid(crs);
     if (this.crs != crs) {
       // Compute min/max in x/y by projecting 8 cardinal points,
@@ -126,8 +121,7 @@ class Extent {
    * @param target - The target to store the center coordinate. If this not
    * provided a new coordinate will be created.
    */
-  center() {
-    let target = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : new Coordinates(this.crs);
+  center(target = new Coordinates(this.crs)) {
     this.planarDimensions(_dim);
     target.crs = this.crs;
     target.setFromValues(this.west + _dim.x * 0.5, this.south + _dim.y * 0.5);
@@ -142,8 +136,7 @@ class Extent {
    *
    * @param target - optional target
    */
-  planarDimensions() {
-    let target = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : new Vector2();
+  planarDimensions(target = new Vector2()) {
     // Calculte the dimensions for x and y
     return target.set(Math.abs(this.east - this.west), Math.abs(this.north - this.south));
   }
@@ -156,8 +149,7 @@ class Extent {
    *
    * @param target - optional target
    */
-  geodeticDimensions() {
-    let target = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : new Vector2();
+  geodeticDimensions(target = new Vector2()) {
     // set 3 corners extent
     cNorthWest.crs = this.crs;
     cSouthWest.crs = this.crs;
@@ -177,8 +169,7 @@ class Extent {
    *
    * @param target - optional target
    */
-  spatialEuclideanDimensions() {
-    let target = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : new Vector2();
+  spatialEuclideanDimensions(target = new Vector2()) {
     // set 3 corners extent
     cNorthWest.crs = this.crs;
     cSouthWest.crs = this.crs;
@@ -198,8 +189,7 @@ class Extent {
    * @param epsilon - error margin when comparing to the coordinates.
    * Default is 0.
    */
-  isPointInside(coord) {
-    let epsilon = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 0;
+  isPointInside(coord, epsilon = 0) {
     if (this.crs == coord.crs) {
       _c.copy(coord);
     } else {
@@ -216,8 +206,7 @@ class Extent {
    * @param extent - the extent to check
    * @param epsilon - error margin when comparing the extent bounds.
    */
-  isInside(extent) {
-    let epsilon = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : CRS.reasonableEpsilon(this.crs);
+  isInside(extent, epsilon = CRS.reasonableEpsilon(this.crs)) {
     extent.as(this.crs, _extent);
     return this.east - _extent.east <= epsilon && _extent.west - this.west <= epsilon && this.north - _extent.north <= epsilon && _extent.south - this.south <= epsilon;
   }
@@ -233,8 +222,7 @@ class Extent {
    * south-north, the `z` property the scale on west-east, the `w` property
    * the scale on south-north.
    */
-  offsetToParent(extent) {
-    let target = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : new Vector4();
+  offsetToParent(extent, target = new Vector4()) {
     if (this.crs != extent.crs) {
       throw new Error('unsupported mix');
     }
@@ -314,8 +302,7 @@ class Extent {
    * @param array - the source array
    * @param offset - offset into the array. Default is 0.
    */
-  setFromArray(array) {
-    let offset = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 0;
+  setFromArray(array, offset = 0) {
     this.west = array[offset];
     this.east = array[offset + 1];
     this.south = array[offset + 2];
@@ -439,8 +426,7 @@ class Extent {
    * Return values of extent in string, separated by the separator input.
    * @param sep - string separator
    */
-  toString() {
-    let sep = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : '';
+  toString(sep = '') {
     return `${this.east}${sep}${this.north}${sep}${this.west}${sep}${this.south}`;
   }
 
@@ -461,8 +447,7 @@ class Extent {
    * @param scheme - The scheme to subdivise.
    * @returns subdivised extents.
    */
-  subdivisionByScheme() {
-    let scheme = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : defaultScheme;
+  subdivisionByScheme(scheme = defaultScheme) {
     const subdivisedExtents = [];
     const dimSub = this.planarDimensions(_dim).divide(scheme);
     for (let x = scheme.x - 1; x >= 0; x--) {
@@ -509,9 +494,7 @@ class Extent {
    * @param north - The max north
    * @returns this extent
    */
-  clampSouthNorth() {
-    let south = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : this.south;
-    let north = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : this.north;
+  clampSouthNorth(south = this.south, north = this.north) {
     this.south = Math.max(this.south, south);
     this.north = Math.min(this.north, north);
     return this;
@@ -524,9 +507,7 @@ class Extent {
    * @param east - The max east
    * @returns this extent
    */
-  clampWestEast() {
-    let west = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : this.west;
-    let east = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : this.east;
+  clampWestEast(west = this.west, east = this.east) {
     this.west = Math.max(this.west, west);
     this.east = Math.min(this.east, east);
     return this;

package/lib/OrientationUtils.d.ts

@@ -0,0 +1,105 @@
+import { Quaternion } from 'three';
+import { type ProjectionDefinition } from 'proj4';
+import Coordinates from './Coordinates';
+interface EulerAngles {
+    /** angle in degrees */
+    roll: number;
+    /** angle in degrees */
+    pitch: number;
+    /** angle in degrees */
+    heading: number;
+}
+interface PhotogrammetryAngles {
+    /** angle in degrees */
+    omega: number;
+    /** angle in degrees */
+    phi: number;
+    /** angle in degrees */
+    kappa: number;
+}
+type Attitude = Partial<EulerAngles> | Partial<PhotogrammetryAngles>;
+type QuaternionFunction = (coords: Coordinates, target?: Quaternion) => Quaternion;
+type ProjectionLike = ProjectionDefinition | string;
+type LCCProjection = {
+    long0: number;
+    lat0: number;
+};
+type TMercProjection = {
+    a: number;
+    b: number;
+    e?: number;
+    long0: number;
+};
+/**
+ * The transform from the platform frame to the local East, North, Up (ENU)
+ * frame is `RotationZ(heading).RotationX(pitch).RotationY(roll)`.
+ *
+ * @param roll - angle in degrees. Default is 0.
+ * @param pitch - angle in degrees. Default is 0.
+ * @param heading - angle in degrees. Default is 0
+ * @param target - output Quaternion
+ *
+ * @returns The target quaternion
+ */
+export declare function quaternionFromRollPitchHeading(roll?: number, pitch?: number, heading?: number, target?: Quaternion): Quaternion;
+/**
+ * From
+ * [DocMicMac](https://github.com/micmacIGN/Documentation/raw/master/DocMicMac.pdf),
+ * the transform from the platform frame to the local East, North, Up (ENU)
+ * frame is:
+ *
+ * ```
+ * RotationX(omega).RotationY(phi).RotationZ(kappa).RotationX(PI)
+ * Converts between the 2 conventions for the camera local frame:
+ * RotationX(PI) <=> Quaternion(1,0,0,0)
+ * X right, Y bottom, Z front : convention in photogrammetry and computer vision
+ * X right, Y top,    Z back  : convention in webGL, threejs
+ * ```
+ *
+ * @param omega - angle in degrees. Default is 0.
+ * @param phi - angle in degrees. Default is 0.
+ * @param kappa - angle in degrees. Default is 0.
+ * @param target - output quaternion
+ *
+ * @returns The target quaternion
+ */
+export declare function quaternionFromOmegaPhiKappa(omega?: number, phi?: number, kappa?: number, target?: Quaternion): Quaternion;
+/**
+ * Sets the quaternion according to the rotation from the platform frame to the
+ * local frame.
+ *
+ * @param attitude - either euler angles or photogrammetry angles
+ * @param target - output Quaternion
+ *
+ * @returns The target quaternion
+ */
+export declare function quaternionFromAttitude(attitude: Attitude, target?: Quaternion): Quaternion;
+export declare function quaternionFromEnuToGeocent(): QuaternionFunction;
+export declare function quaternionFromEnuToGeocent(coords: Coordinates, target?: Quaternion): Quaternion;
+export declare function quaternionFromGeocentToEnu(): QuaternionFunction;
+export declare function quaternionFromGeocentToEnu(coords: Coordinates, target?: Quaternion): Quaternion;
+export declare function quaternionFromLCCToEnu(proj: LCCProjection): QuaternionFunction;
+export declare function quaternionFromLCCToEnu(proj: LCCProjection, coords: Coordinates, target?: Quaternion): Quaternion;
+export declare function quaternionFromEnuToLCC(proj: LCCProjection): QuaternionFunction;
+export declare function quaternionFromEnuToLCC(proj: LCCProjection, coords: Coordinates, target?: Quaternion): Quaternion;
+export declare function quaternionFromTMercToEnu(proj: TMercProjection): QuaternionFunction;
+export declare function quaternionFromTMercToEnu(proj: TMercProjection, coords: Coordinates, target?: Quaternion): Quaternion;
+export declare function quaternionFromEnuToTMerc(proj: TMercProjection): QuaternionFunction;
+export declare function quaternionFromEnuToTMerc(proj: TMercProjection, coords: Coordinates, target?: Quaternion): Quaternion;
+export declare function quaternionFromLongLatToEnu(): QuaternionFunction;
+export declare function quaternionFromLongLatToEnu(coords: Coordinates, target?: Quaternion): Quaternion;
+export declare function quaternionFromEnuToLongLat(): QuaternionFunction;
+export declare function quaternionFromEnuToLongLat(coords: Coordinates, target?: Quaternion): Quaternion;
+export declare function quaternionUnimplemented(proj: {
+    projName?: string;
+}): QuaternionFunction;
+export declare function quaternionUnimplemented(proj: {
+    projName?: string;
+}, coords: Coordinates, target?: Quaternion): Quaternion;
+export declare function quaternionFromEnuToCRS(proj: ProjectionLike): QuaternionFunction;
+export declare function quaternionFromEnuToCRS(proj: ProjectionLike, coords: Coordinates, target?: Quaternion): Quaternion;
+export declare function quaternionFromCRSToEnu(proj: ProjectionLike): QuaternionFunction;
+export declare function quaternionFromCRSToEnu(proj: ProjectionLike, coords: Coordinates, target?: Quaternion): Quaternion;
+export declare function quaternionFromCRSToCRS(crsIn: string, crsOut: string): QuaternionFunction;
+export declare function quaternionFromCRSToCRS(crsIn: string, crsOut: string, coords: Coordinates, target?: Quaternion): Quaternion;
+export {};