@itowns/geographic 2.46.1-next.6 → 2.46.1-next.60

package/lib/CoordStars.d.ts

@@ -0,0 +1,13 @@
+declare const CoordStars: {
+    getSunPosition(): (date: Date | number, lat: number, lon: number) => {
+        EclipticLongitude: number;
+        declinaison: number;
+        ascension: number;
+        H: number;
+        SiderealTime: number;
+        altitude: number;
+        azimuth: number;
+    };
+    getSunPositionInScene(date: Date | number, lat: number, lon: number): import("three").Vector3;
+};
+export default CoordStars;

package/lib/Coordinates.d.ts

@@ -0,0 +1,208 @@
+import { Vector3, type Vector3Like, type Matrix4 } from 'three';
+import type { ProjectionLike } from './Crs';
+export interface CoordinatesLike {
+    readonly crs: string;
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+/**
+ * A class representing a geographic or geocentric coordinate.
+ *
+ * A coordinate is defined by a [CRS](http://inspire.ec.europa.eu/theme/rs)
+ * (Coordinate Reference System) and a 3-dimensional vector `(x, y, z)`.
+ * For geocentric projections, it is recommended to use the `latitude`,
+ * `longitude` and `altitude` aliases to refer to vector components.
+ *
+ * To change a value, prefer the use of the `set*` methods.
+ *
+ * By default, the `EPSG:4978` and `EPSG:4326` projections are supported. To use
+ * a different projection, it must have been declared previously with `proj4`.
+ * A comprehensive list of projections and their corresponding proj4 string can
+ * be found at [epsg.io](https://epsg.io/).
+ *
+ * @example Geocentric coordinates
+ * ```js
+ * new Coordinates('EPSG:4978', 20885167, 849862, 23385912);
+ * ```
+ *
+ * @example Geographic coordinates
+ * ```js
+ * new Coordinates('EPSG:4326', 2.33, 48.24, 24999549);
+ * ```
+ *
+ * @example Defining the EPSG:2154 projection with proj4
+ * ```js
+ * proj4.defs('EPSG:2154', `+proj=lcc +lat_0=46.5 +lon_0=3 +lat_1=49 +lat_2=44
+ * +x_0=700000 +y_0=6600000 +ellps=GRS80 +towgs84=0,0,0,0,0,0,0 +units=m
+ * +no_defs +type=crs`);
+ * ```
+ */
+declare class Coordinates {
+    /**
+     * Read-only flag to check if a given object is of type `Coordinates`.
+     */
+    readonly isCoordinates: boolean;
+    /**
+     * A default or user-defined CRS (see {@link ProjectionLike}).
+     */
+    crs: ProjectionLike;
+    /** The x value (or longitude) of this coordinate. */
+    x: number;
+    /** The y value (or latitude) of this coordinate. */
+    y: number;
+    /** The z value (or altitude) of this coordinate. */
+    z: number;
+    private _normal;
+    private _normalNeedsUpdate;
+    /**
+     * @param crs - A default or user-defined CRS (see {@link ProjectionLike}).
+     * @param x - x or longitude value.
+     * @param y - y or latitude value.
+     * @param z - z or altitude value.
+     */
+    constructor(crs: ProjectionLike, x?: number, y?: number, z?: number);
+    /**
+     * Sets the Coordinate Reference System.
+     * @param crs - Coordinate Reference System (e.g. 'EPSG:4978')
+     * @returns
+     */
+    setCrs(crs: ProjectionLike): this;
+    /**
+     * Sets the x, y and z components of this coordinate.
+     *
+     * @param x - x or longitude value.
+     * @param y - y or latitude value.
+     * @param z - z or altitude value.
+     * @returns
+     */
+    setFromValues(x?: number, y?: number, z?: number): this;
+    /**
+     * Sets the coordinates's {@link Coordinates#x | x} component to
+     * `array[offset + 0]`, {@link Coordinates#y | y} component to
+     * `array[offset + 1]` and {@link Coordinates#z | z} component to
+     * `array[offset + 2]`.
+     *
+     * @param array - The source array.
+     * @param offset - Optional offset into the array. Default is 0.
+     * @returns
+     */
+    setFromArray(array: number[], offset?: number): this;
+    /**
+     * Sets the `(x, y, z)` vector of this coordinate from a 3-dimensional
+     * vector-like object. This object shall have both `x`, `y` and `z`
+     * properties.
+     *
+     * @param v - The source object.
+     * @returns
+     */
+    setFromVector3(v: Vector3Like): this;
+    /**
+     * Returns a new coordinate with the same `(x, y, z)` vector and crs as this
+     * one.
+     * @returns
+     */
+    clone(): Coordinates;
+    /**
+     * Copies the `(x, y, z)` vector components and crs of the passed coordinate
+     * to this coordinate.
+     *
+     * @param src - The source coordinate to copy from.
+     * @returns
+     */
+    copy(src: CoordinatesLike): this;
+    get longitude(): number;
+    get latitude(): number;
+    get altitude(): number;
+    set altitude(value: number);
+    /**
+     * The geodesic normal of the coordinate.
+     * @returns
+     */
+    get geodesicNormal(): Vector3;
+    /**
+     * Copies the `x`, `y` and `z` components into the provided `THREE.Vector3`.
+     *
+     * @param target - An object to store this vector to. If this is not
+     * specified, a new vector will be created.
+     *
+     * @returns A vector `(x, y, z)`, or copies x, y and z into the provided
+     * vector.
+     */
+    toVector3(target?: Vector3): Vector3;
+    /**
+     * Copies the `x`, `y` and `z` components into the provided array.
+     *
+     * @param array - An array to store this vector to. If this is not
+     * provided a new array will be created.
+     * @param offset - An optional offset into the array.
+     *
+     * @returns An array [x, y, z], or copies x, y and z into the provided
+     * array.
+     */
+    toArray(array?: number[], offset?: number): ArrayLike<number>;
+    /**
+     * Computes the planar distance from this coordinates to `coord`.
+     * **Planar distance** is the straight-line euclidean distance calculated in
+     * a 2D cartesian coordinate system.
+     * @param coord
+     * @returns
+     */
+    planarDistanceTo(coord: Coordinates): number;
+    /**
+     * Computes the geodetic distance from this coordinates to `coord`.
+     * **Geodetic distance** is calculated in an ellipsoid space as the shortest
+     * distance across the curved surface of the ellipsoid.
+     * @param coord
+     * @returns
+     */
+    geodeticDistanceTo(coord: Coordinates): number;
+    /**
+     * Computes the euclidean distance from this coordinates to `coord` in a
+     * WGS84 projection.
+     *
+     * @param coord - The coordinate
+     * @returns earth euclidean distance
+     */
+    spatialEuclideanDistanceTo(coord: Coordinates): number;
+    /**
+     * Multiplies this coordinate (with an implicit 1 in the 4th dimension)
+     * by `mat`, and divides by perspective.
+     *
+     * @param mat - The matrix.
+     * @returns
+     */
+    applyMatrix4(mat: Matrix4): this;
+    /**
+     * Projects this coordinate to the specified
+     * [CRS](http://inspire.ec.europa.eu/theme/rs).
+     *
+     * @param crs - The target CRS to which the coordinate will be converted.
+     * @param target - The target to store the projected coordinate. If this not
+     * provided a new coordinate will be created.
+     *
+     * @returns The coordinate projected into the specified CRS.
+     *
+     * @example Conversion from a geographic to a geocentric reference system
+     * ```js
+     * const geographicCoords = new Coordinates('EPSG:4326',
+     *     2.33,        // longitude
+     *     48.24,       // latitude
+     *     24999549,    // altitude
+     * );
+     * const geocentricCoords = geographicCoords.as('EPSG:4978');
+     * ```
+     *
+     * @example Conversion from a geocentric to a geographic reference system
+     * ```js
+     * const geocentricCoords = new Coordinates('EPSG:4978',
+     *     20885167,    // x
+     *     849862,      // y
+     *     23385912,    // z
+     * );
+     * const geographicCoords = geocentricCoords.as('EPSG:4326');
+     * ```
+     */
+    as(crs: ProjectionLike, target?: Coordinates): Coordinates;
+}
+export default Coordinates;

package/lib/Coordinates.js

@@ -1,23 +1,9 @@
 import { Vector3, MathUtils } from 'three';
-import proj4 from 'proj4';
 import Ellipsoid from "./Ellipsoid.js";
 import * as CRS from "./Crs.js";
 const ellipsoid = /* @__PURE__ */new Ellipsoid();
-const projectionCache = {};
 const v0 = /* @__PURE__ */new Vector3();
 const v1 = /* @__PURE__ */new Vector3();
-let coord0;
-let coord1;
-function proj4cache(crsIn, crsOut) {
-  if (!projectionCache[crsIn]) {
-    projectionCache[crsIn] = {};
-  }
-  if (!projectionCache[crsIn][crsOut]) {
-    projectionCache[crsIn][crsOut] = proj4(crsIn, crsOut);
-  }
-  return projectionCache[crsIn][crsOut];
-}
-
 /**
  * A class representing a geographic or geocentric coordinate.
  *
@@ -71,10 +57,7 @@ class Coordinates {
    * @param y - y or latitude value.
    * @param z - z or altitude value.
    */
-  constructor(crs) {
-    let x = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 0;
-    let y = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 0;
-    let z = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : 0;
+  constructor(crs, x = 0, y = 0, z = 0) {
     this.isCoordinates = true;
     CRS.isValid(crs);
     this.crs = crs;
@@ -108,6 +91,7 @@ class Coordinates {
   /**
    * Sets the Coordinate Reference System.
    * @param crs - Coordinate Reference System (e.g. 'EPSG:4978')
+   * @returns
    */
   setCrs(crs) {
     CRS.isValid(crs);
@@ -121,11 +105,9 @@ class Coordinates {
    * @param x - x or longitude value.
    * @param y - y or latitude value.
    * @param z - z or altitude value.
+   * @returns
    */
-  setFromValues() {
-    let x = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 0;
-    let y = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 0;
-    let z = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 0;
+  setFromValues(x = 0, y = 0, z = 0) {
     this.x = x;
     this.y = y;
     this.z = z;
@@ -141,9 +123,9 @@ class Coordinates {
    *
    * @param array - The source array.
    * @param offset - Optional offset into the array. Default is 0.
+   * @returns
    */
-  setFromArray(array) {
-    let offset = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 0;
+  setFromArray(array, offset = 0) {
     return this.setFromValues(array[offset], array[offset + 1], array[offset + 2]);
   }
 
@@ -153,6 +135,7 @@ class Coordinates {
    * properties.
    *
    * @param v - The source object.
+   * @returns
    */
   setFromVector3(v) {
     return this.setFromValues(v.x, v.y, v.z);
@@ -161,6 +144,7 @@ class Coordinates {
   /**
    * Returns a new coordinate with the same `(x, y, z)` vector and crs as this
    * one.
+   * @returns
    */
   clone() {
     return new Coordinates(this.crs, this.x, this.y, this.z);
@@ -171,6 +155,7 @@ class Coordinates {
    * to this coordinate.
    *
    * @param src - The source coordinate to copy from.
+   * @returns
    */
   copy(src) {
     this.crs = src.crs;
@@ -191,6 +176,7 @@ class Coordinates {
 
   /**
    * The geodesic normal of the coordinate.
+   * @returns
    */
   get geodesicNormal() {
     if (this._normalNeedsUpdate) {
@@ -215,8 +201,7 @@ class Coordinates {
    * @returns A vector `(x, y, z)`, or copies x, y and z into the provided
    * vector.
    */
-  toVector3() {
-    let target = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : new Vector3();
+  toVector3(target = new Vector3()) {
     return target.copy(this);
   }
 
@@ -230,9 +215,7 @@ class Coordinates {
    * @returns An array [x, y, z], or copies x, y and z into the provided
    * array.
    */
-  toArray() {
-    let array = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : [];
-    let offset = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 0;
+  toArray(array = [], offset = 0) {
     return Vector3.prototype.toArray.call(this, array, offset);
   }
 
@@ -240,6 +223,8 @@ class Coordinates {
    * Computes the planar distance from this coordinates to `coord`.
    * **Planar distance** is the straight-line euclidean distance calculated in
    * a 2D cartesian coordinate system.
+   * @param coord
+   * @returns
    */
   planarDistanceTo(coord) {
     this.toVector3(v0).setZ(0);
@@ -251,6 +236,8 @@ class Coordinates {
    * Computes the geodetic distance from this coordinates to `coord`.
    * **Geodetic distance** is calculated in an ellipsoid space as the shortest
    * distance across the curved surface of the ellipsoid.
+   * @param coord
+   * @returns
    */
   geodeticDistanceTo(coord) {
     this.as('EPSG:4326', coord0);
@@ -276,6 +263,7 @@ class Coordinates {
    * by `mat`, and divides by perspective.
    *
    * @param mat - The matrix.
+   * @returns
    */
   applyMatrix4(mat) {
     Vector3.prototype.applyMatrix4.call(this, mat);
@@ -312,20 +300,19 @@ class Coordinates {
    * const geographicCoords = geocentricCoords.as('EPSG:4326');
    * ```
    */
-  as(crs) {
-    let target = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : new Coordinates(crs);
+  as(crs, target = new Coordinates(crs)) {
     if (this.crs == crs) {
       target.copy(this);
     } else {
       if (CRS.is4326(this.crs) && crs == 'EPSG:3857') {
         this.y = MathUtils.clamp(this.y, -89.999999, 89.999999);
       }
-      target.setFromArray(proj4cache(this.crs, crs).forward([this.x, this.y, this.z]));
+      target.setFromArray(CRS.transform(this.crs, crs).forward([this.x, this.y, this.z]));
     }
     target.crs = crs;
     return target;
   }
 }
-coord0 = /* @__PURE__ */new Coordinates('EPSG:4326', 0, 0, 0);
-coord1 = /* @__PURE__ */new Coordinates('EPSG:4326', 0, 0, 0);
+const coord0 = /* @__PURE__ */new Coordinates('EPSG:4326', 0, 0, 0);
+const coord1 = /* @__PURE__ */new Coordinates('EPSG:4326', 0, 0, 0);
 export default Coordinates;

package/lib/Crs.d.ts

@@ -0,0 +1,111 @@
+import type { Converter } from 'proj4';
+import type { ProjectionDefinition } from 'proj4/dist/lib/defs';
+/**
+ * A projection as a CRS identifier string. This identifier references a
+ * projection definition previously defined with
+ * [`proj4.defs`](https://github.com/proj4js/proj4js#named-projections).
+ */
+export type ProjectionLike = string;
+export declare function transform(crsIn: ProjectionLike, crsOut: ProjectionLike): Converter;
+/**
+ * System units supported for a coordinate system. See
+ * [proj](https://proj4.org/en/9.5/operations/conversions/unitconvert.html#angular-units).
+ * Note that only degree and meters units are supported for now.
+ */
+export declare const UNIT: {
+    /**
+     * Angular unit in degree.
+     */
+    readonly DEGREE: 1;
+    /**
+     * Distance unit in meter.
+     */
+    readonly METER: 2;
+    /**
+     * Distance unit in foot.
+     */
+    readonly FOOT: 3;
+};
+/**
+ * Checks that the CRS is EPSG:4326.
+ * @internal
+ *
+ * @param crs - The CRS to test.
+ * @returns
+ */
+export declare function is4326(crs: ProjectionLike): crs is "EPSG:4326";
+/**
+ * Returns the horizontal coordinates system units associated with this CRS.
+ *
+ * @param crs - The CRS to extract the unit from.
+ * @returns Either `UNIT.METER`, `UNIT.DEGREE`, `UNIT.FOOT` or `undefined`.
+ */
+export declare function getUnit(crs: ProjectionLike): 1 | 2 | 3 | undefined;
+/**
+ * Asserts that the CRS is using metric units.
+ *
+ * @param crs - The CRS to check.
+ * @returns
+ * @throws {Error} if the CRS is not valid.
+ */
+export declare function isMetricUnit(crs: ProjectionLike): boolean;
+/**
+ * Asserts that the CRS is geographic.
+ *
+ * @param crs - The CRS to check.
+ * @returns
+ * @throws {Error} if the CRS is not valid.
+ */
+export declare function isGeographic(crs: ProjectionLike): boolean;
+/**
+ * Asserts that the CRS is geocentric.
+ *
+ * @param crs - The CRS to test.
+ * @returns false if the crs isn't defined.
+ */
+export declare function isGeocentric(crs: ProjectionLike): boolean;
+/**
+ * Asserts that the CRS is valid, meaning it has been previously defined and
+ * includes an unit.
+ *
+ * @param crs - The CRS to test.
+ * @throws {Error} if the crs is not valid.
+ */
+export declare function isValid(crs: ProjectionLike): void;
+/**
+ * Gives a reasonable epsilon for this CRS.
+ *
+ * @param crs - The CRS to use.
+ * @returns 0.01 if the CRS is EPSG:4326, 0.001 otherwise.
+ */
+export declare function reasonableEpsilon(crs: ProjectionLike): 0.01 | 0.001;
+/**
+ * Returns the axis parameter defined in proj4 for the provided crs.
+ * Might be undefined depending on crs definition.
+ *
+ * @param crs - The CRS to get axis from.
+ * @returns the matching proj4 axis string, 'enu' for instance (east, north, up)
+ */
+export declare function axisOrder(crs: ProjectionLike): string | undefined;
+/**
+ * Defines a proj4 projection as a named alias.
+ * This function is an alias for the
+ * [`proj4.defs`](https://github.com/proj4js/proj4js#named-projections) function.
+ */
+export declare const defs: typeof import("proj4/dist/lib/defs").default;
+/**
+ * Fetches a CRS definition from epsg.io and registers it with proj4.
+ * If the CRS is already defined, returns the existing definition.
+ *
+ * @param crs - The EPSG code string (e.g. "EPSG:2154").
+ * @returns The proj4 projection definition.
+ *
+ * @example
+ * // Register EPSG:2154 (RGF93 / Lambert-93)
+ * await CRS.fromEPSG('EPSG:2154');
+ *
+ * // Register EPSG:4269 (NAD83)
+ * await CRS.fromEPSG('EPSG:4269');
+ */
+export declare function fromEPSG(crs: string): Promise<ProjectionDefinition>;
+export declare function defsFromWkt(wkt: string): string;

package/lib/Crs.js

@@ -12,7 +12,18 @@ proj4.defs('WGS84').axis = 'neu';
  * projection definition previously defined with
  * [`proj4.defs`](https://github.com/proj4js/proj4js#named-projections).
  */
+// TODO Unify with OrientationUtils.js
 
+const proj4Cache = {};
+export function transform(crsIn, crsOut) {
+  if (!proj4Cache[crsIn]) {
+    proj4Cache[crsIn] = {};
+  }
+  if (!proj4Cache[crsIn][crsOut]) {
+    proj4Cache[crsIn][crsOut] = proj4(crsIn, crsOut);
+  }
+  return proj4Cache[crsIn][crsOut];
+}
 function isString(s) {
   return typeof s === 'string' || s instanceof String;
 }
@@ -47,6 +58,7 @@ export const UNIT = {
  * @internal
  *
  * @param crs - The CRS to test.
+ * @returns
  */
 export function is4326(crs) {
   return crs === 'EPSG:4326';
@@ -56,7 +68,7 @@ function unitFromProj4Unit(proj) {
     return UNIT.DEGREE;
   } else if (proj.units === 'm' || proj.units === 'meter') {
     return UNIT.METER;
-  } else if (proj.units === 'foot') {
+  } else if (proj.units === 'foot' || proj.units === 'ft') {
     return UNIT.FOOT;
   } else if (proj.units === undefined && proj.to_meter === undefined) {
     // See https://proj.org/en/9.4/usage/projections.html [17/10/2024]
@@ -86,7 +98,8 @@ export function getUnit(crs) {
  * Asserts that the CRS is using metric units.
  *
  * @param crs - The CRS to check.
- * @throws {@link Error} if the CRS is not valid.
+ * @returns
+ * @throws {Error} if the CRS is not valid.
  */
 export function isMetricUnit(crs) {
   return getUnit(crs) === UNIT.METER;
@@ -96,7 +109,8 @@ export function isMetricUnit(crs) {
  * Asserts that the CRS is geographic.
  *
  * @param crs - The CRS to check.
- * @throws {@link Error} if the CRS is not valid.
+ * @returns
+ * @throws {Error} if the CRS is not valid.
  */
 export function isGeographic(crs) {
   return getUnit(crs) === UNIT.DEGREE;
@@ -119,12 +133,12 @@ export function isGeocentric(crs) {
  * includes an unit.
  *
  * @param crs - The CRS to test.
- * @throws {@link Error} if the crs is not valid.
+ * @throws {Error} if the crs is not valid.
  */
 export function isValid(crs) {
   const proj = proj4.defs(crs);
   if (!proj) {
-    throw new Error(`Undefined crs '${crs}'. Add it with proj4.defs('${crs}', string)`);
+    throw new Error(`Undefined crs '${crs}'. Add it with itowns.CRS.defs('${crs}', wktString)`);
   }
   if (!unitFromProj4Unit(proj)) {
     throw new Error(`No valid unit found for crs '${crs}', found ${proj.units}`);
@@ -160,11 +174,53 @@ export function axisOrder(crs) {
 
 /**
  * Defines a proj4 projection as a named alias.
- * This function is a specialized wrapper over the
- * [`proj4.defs`](https://github.com/proj4js/proj4js#named-projections)
- * function.
+ * This function is an alias for the
+ * [`proj4.defs`](https://github.com/proj4js/proj4js#named-projections) function.
+ */
+export const defs = proj4.defs;
+
+/**
+ * Fetches a CRS definition from epsg.io and registers it with proj4.
+ * If the CRS is already defined, returns the existing definition.
+ *
+ * @param crs - The EPSG code string (e.g. "EPSG:2154").
+ * @returns The proj4 projection definition.
  *
- * @param code - Named alias of the currently defined projection.
- * @param proj4def - Proj4 or WKT string of the defined projection.
+ * @example
+ * // Register EPSG:2154 (RGF93 / Lambert-93)
+ * await CRS.fromEPSG('EPSG:2154');
+ *
+ * // Register EPSG:4269 (NAD83)
+ * await CRS.fromEPSG('EPSG:4269');
  */
-export const defs = (code, proj4def) => proj4.defs(code, proj4def);
+export async function fromEPSG(crs) {
+  const def = proj4.defs(crs);
+  if (def) {
+    return def;
+  }
+  const code = crs.replace(/^EPSG:/i, '');
+  const response = await fetch(`https://epsg.io/${code}.proj4`);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch EPSG:${code} from epsg.io: ${response.status}`);
+  }
+  const proj4def = await response.text();
+  proj4.defs(crs, proj4def);
+  return proj4.defs(crs);
+}
+export function defsFromWkt(wkt) {
+  proj4.defs('unknown', wkt);
+  const proj4Defs = proj4.defs;
+  let projCS;
+  if (proj4Defs('unknown').type === 'COMPD_CS') {
+    console.warn('Compound coordinate system is not yet supported.');
+    projCS = proj4Defs('unknown').PROJCS;
+  } else {
+    projCS = proj4Defs('unknown');
+  }
+  const crsAlias = projCS.title || projCS.name || 'EPSG:XXXX';
+  if (!(crsAlias in proj4.defs)) {
+    proj4.defs(crsAlias, projCS);
+  }
+  delete proj4Defs.unknown;
+  return crsAlias;
+}