@itowns/geographic 2.45.1-next.0 → 2.45.1

package/lib/Crs.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 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;
+/**
+ * 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.
+ */
+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.
+ * @throws {@link 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.
+ * @throws {@link 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 {@link 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 a specialized wrapper over the
+ * [`proj4.defs`](https://github.com/proj4js/proj4js#named-projections)
+ * function.
+ *
+ * @param code - Named alias of the currently defined projection.
+ * @param proj4def - Proj4 or WKT string of the defined projection.
+ */
+export declare const defs: (code: string, proj4def: string) => void;

package/lib/Crs.js

@@ -0,0 +1,170 @@
+import proj4 from 'proj4';
+proj4.defs('EPSG:4978', '+proj=geocent +datum=WGS84 +units=m +no_defs');
+
+// Redefining proj4 global projections to match epsg.org database axis order.
+// See https://github.com/iTowns/itowns/pull/2465#issuecomment-2517024859
+proj4.defs('EPSG:4326').axis = 'neu';
+proj4.defs('EPSG:4269').axis = 'neu';
+proj4.defs('WGS84').axis = 'neu';
+
+/**
+ * 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).
+ */
+
+function isString(s) {
+  return typeof s === 'string' || s instanceof String;
+}
+function mustBeString(crs) {
+  if (!isString(crs)) {
+    throw new Error(`Crs parameter value must be a string: '${crs}'`);
+  }
+}
+
+/**
+ * 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 const UNIT = {
+  /**
+   * Angular unit in degree.
+   */
+  DEGREE: 1,
+  /**
+   * Distance unit in meter.
+   */
+  METER: 2,
+  /**
+   * Distance unit in foot.
+   */
+  FOOT: 3
+};
+
+/**
+ * Checks that the CRS is EPSG:4326.
+ * @internal
+ *
+ * @param crs - The CRS to test.
+ */
+export function is4326(crs) {
+  return crs === 'EPSG:4326';
+}
+function unitFromProj4Unit(proj) {
+  if (proj.units === 'degrees') {
+    return UNIT.DEGREE;
+  } else if (proj.units === 'm' || proj.units === 'meter') {
+    return UNIT.METER;
+  } else if (proj.units === 'foot') {
+    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]
+    // > The default unit for projected coordinates is the meter.
+    return UNIT.METER;
+  } else {
+    return undefined;
+  }
+}
+
+/**
+ * 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 function getUnit(crs) {
+  mustBeString(crs);
+  const p = proj4.defs(crs);
+  if (!p) {
+    return undefined;
+  }
+  return unitFromProj4Unit(p);
+}
+
+/**
+ * Asserts that the CRS is using metric units.
+ *
+ * @param crs - The CRS to check.
+ * @throws {@link Error} if the CRS is not valid.
+ */
+export function isMetricUnit(crs) {
+  return getUnit(crs) === UNIT.METER;
+}
+
+/**
+ * Asserts that the CRS is geographic.
+ *
+ * @param crs - The CRS to check.
+ * @throws {@link Error} if the CRS is not valid.
+ */
+export function isGeographic(crs) {
+  return getUnit(crs) === UNIT.DEGREE;
+}
+
+/**
+ * Asserts that the CRS is geocentric.
+ *
+ * @param crs - The CRS to test.
+ * @returns false if the crs isn't defined.
+ */
+export function isGeocentric(crs) {
+  mustBeString(crs);
+  const projection = proj4.defs(crs);
+  return !projection ? false : projection.projName == 'geocent';
+}
+
+/**
+ * Asserts that the CRS is valid, meaning it has been previously defined and
+ * includes an unit.
+ *
+ * @param crs - The CRS to test.
+ * @throws {@link 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)`);
+  }
+  if (!unitFromProj4Unit(proj)) {
+    throw new Error(`No valid unit found for crs '${crs}', found ${proj.units}`);
+  }
+}
+
+/**
+ * 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 function reasonableEpsilon(crs) {
+  if (is4326(crs)) {
+    return 0.01;
+  } else {
+    return 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 function axisOrder(crs) {
+  mustBeString(crs);
+  const projection = proj4.defs(crs);
+  return !projection ? undefined : projection.axis;
+}
+
+/**
+ * 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.
+ *
+ * @param code - Named alias of the currently defined projection.
+ * @param proj4def - Proj4 or WKT string of the defined projection.
+ */
+export const defs = (code, proj4def) => proj4.defs(code, proj4def);

package/lib/Ellipsoid.d.ts

@@ -0,0 +1,74 @@
+import * as THREE from 'three';
+import Coordinates from './Coordinates';
+/**
+ * Length of the semi-axes of the WGS84 ellipsoid.
+ * @internal
+ */
+export declare const ellipsoidSizes: THREE.Vector3;
+declare class Ellipsoid {
+    /**
+     * Length of the semi-axes of the ellipsoid.
+     */
+    size: THREE.Vector3;
+    /**
+     * Eccentricity of the ellipsoid.
+     */
+    eccentricity: number;
+    private _radiiSquared;
+    private _invRadiiSquared;
+    /**
+     * @param size - Length of the semi-axes of the ellipsoid. Defaults to those
+     * defined by the WGS84 ellipsoid.
+     */
+    constructor(size?: THREE.Vector3);
+    /**
+     * Computes the normal vector to an ellipsoid at the given cartesian
+     * coordinate `(x, y, z)`.
+     *
+     * @param cartesian - The given cartesian coordinate.
+     * @param target - An object to store this vector to. If this is not
+     * specified, a new vector will be created.
+     */
+    geodeticSurfaceNormal(cartesian: Coordinates, target?: THREE.Vector3): THREE.Vector3;
+    /**
+     * Computes the normal vector to an ellipsoid at the given geographic
+     * coordinate `(longitude, latitude, altitude)`.
+     *
+     * @param coordCarto - The given geographic coordinate.
+     * @param target - An object to store this vector to. If this is not
+     * specified, a new vector will be created.
+     */
+    geodeticSurfaceNormalCartographic(coordCarto: Coordinates, target?: THREE.Vector3): THREE.Vector3;
+    /**
+     * Sets the length of the semi-axes of this ellipsoid from a 3-dimensional
+     * vector-like object. The object shall have both `x`, `y` and `z`
+     * properties.
+     *
+     * @param size - The source vector.
+     */
+    setSize(size: THREE.Vector3Like): this;
+    cartographicToCartesian(coordCarto: Coordinates, target?: THREE.Vector3): THREE.Vector3;
+    /**
+     * Convert cartesian coordinates to geographic according to the current
+     * ellipsoid of revolution.
+     * @param position - The coordinate to convert
+     * @param target - coordinate to copy result
+     * @returns an object describing the coordinates on the reference ellipsoid,
+     * angles are in degree
+     */
+    cartesianToCartographic(position: THREE.Vector3Like, target?: Coordinates): Coordinates;
+    cartographicToCartesianArray(coordCartoArray: Coordinates[]): THREE.Vector3[];
+    intersection(ray: THREE.Ray): THREE.Vector3 | false;
+    /**
+     * Calculate the geodesic distance, between coordCarto1 and coordCarto2.
+     * It's most short distance on ellipsoid surface between coordCarto1 and
+     * coordCarto2.
+     * It's called orthodromy.
+     *
+     * @param coordCarto1 - The coordinate carto 1
+     * @param coordCarto2 - The coordinate carto 2
+     * @returns The orthodromic distance between the two given coordinates.
+     */
+    geodesicDistance(coordCarto1: Coordinates, coordCarto2: Coordinates): number;
+}
+export default Ellipsoid;

package/lib/Ellipsoid.js

@@ -0,0 +1,186 @@
+import * as THREE from 'three';
+import proj4 from 'proj4';
+import Coordinates from "./Coordinates.js";
+
+/**
+ * Length of the semi-axes of the WGS84 ellipsoid.
+ * @internal
+ */
+export const ellipsoidSizes = new THREE.Vector3(proj4.WGS84.a, proj4.WGS84.a, proj4.WGS84.b);
+const normal = new THREE.Vector3();
+class Ellipsoid {
+  /**
+   * Length of the semi-axes of the ellipsoid.
+   */
+
+  /**
+   * Eccentricity of the ellipsoid.
+   */
+
+  /**
+   * @param size - Length of the semi-axes of the ellipsoid. Defaults to those
+   * defined by the WGS84 ellipsoid.
+   */
+  constructor() {
+    let size = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : ellipsoidSizes;
+    this.size = new THREE.Vector3();
+    this._radiiSquared = new THREE.Vector3();
+    this._invRadiiSquared = new THREE.Vector3();
+    this.eccentricity = 0;
+    this.setSize(size);
+  }
+
+  /**
+   * Computes the normal vector to an ellipsoid at the given cartesian
+   * coordinate `(x, y, z)`.
+   *
+   * @param cartesian - The given cartesian coordinate.
+   * @param target - An object to store this vector to. If this is not
+   * specified, a new vector will be created.
+   */
+  geodeticSurfaceNormal(cartesian) {
+    let target = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : new THREE.Vector3();
+    return cartesian.toVector3(target).multiply(this._invRadiiSquared).normalize();
+  }
+
+  /**
+   * Computes the normal vector to an ellipsoid at the given geographic
+   * coordinate `(longitude, latitude, altitude)`.
+   *
+   * @param coordCarto - The given geographic coordinate.
+   * @param target - An object to store this vector to. If this is not
+   * specified, a new vector will be created.
+   */
+  geodeticSurfaceNormalCartographic(coordCarto) {
+    let target = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : new THREE.Vector3();
+    const longitude = THREE.MathUtils.degToRad(coordCarto.longitude);
+    const latitude = THREE.MathUtils.degToRad(coordCarto.latitude);
+    const cosLatitude = Math.cos(latitude);
+    return target.set(cosLatitude * Math.cos(longitude), cosLatitude * Math.sin(longitude), Math.sin(latitude));
+  }
+
+  /**
+   * Sets the length of the semi-axes of this ellipsoid from a 3-dimensional
+   * vector-like object. The object shall have both `x`, `y` and `z`
+   * properties.
+   *
+   * @param size - The source vector.
+   */
+  setSize(size) {
+    this.size.set(size.x, size.y, size.z);
+    this._radiiSquared.multiplyVectors(size, size);
+    this._invRadiiSquared.x = size.x === 0 ? 0 : 1 / this._radiiSquared.x;
+    this._invRadiiSquared.y = size.y === 0 ? 0 : 1 / this._radiiSquared.y;
+    this._invRadiiSquared.z = size.z === 0 ? 0 : 1 / this._radiiSquared.z;
+    this.eccentricity = Math.sqrt(this._radiiSquared.x - this._radiiSquared.z) / this.size.x;
+    return this;
+  }
+  cartographicToCartesian(coordCarto) {
+    let target = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : new THREE.Vector3();
+    normal.copy(coordCarto.geodesicNormal);
+    target.multiplyVectors(this._radiiSquared, normal);
+    const gamma = Math.sqrt(normal.dot(target));
+    target.divideScalar(gamma);
+    normal.multiplyScalar(coordCarto.altitude);
+    return target.add(normal);
+  }
+
+  /**
+   * Convert cartesian coordinates to geographic according to the current
+   * ellipsoid of revolution.
+   * @param position - The coordinate to convert
+   * @param target - coordinate to copy result
+   * @returns an object describing the coordinates on the reference ellipsoid,
+   * angles are in degree
+   */
+  cartesianToCartographic(position) {
+    let target = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : new Coordinates('EPSG:4326', 0, 0, 0);
+    // for details, see for example http://www.linz.govt.nz/data/geodetic-system/coordinate-conversion/geodetic-datum-conversions/equations-used-datum
+    // TODO the following is only valable for oblate ellipsoid of
+    // revolution. do we want to support triaxial ellipsoid?
+    const R = Math.sqrt(position.x * position.x + position.y * position.y + position.z * position.z);
+    const a = this.size.x; // x
+    const b = this.size.z; // z
+    const e = Math.abs((a * a - b * b) / (a * a));
+    const f = 1 - Math.sqrt(1 - e);
+    const rsqXY = Math.sqrt(position.x * position.x + position.y * position.y);
+    const theta = Math.atan2(position.y, position.x);
+    const nu = Math.atan(position.z / rsqXY * (1 - f + e * a / R));
+    const sinu = Math.sin(nu);
+    const cosu = Math.cos(nu);
+    const phi = Math.atan((position.z * (1 - f) + e * a * sinu * sinu * sinu) / ((1 - f) * (rsqXY - e * a * cosu * cosu * cosu)));
+    const h = rsqXY * Math.cos(phi) + position.z * Math.sin(phi) - a * Math.sqrt(1 - e * Math.sin(phi) * Math.sin(phi));
+    return target.setFromValues(THREE.MathUtils.radToDeg(theta), THREE.MathUtils.radToDeg(phi), h);
+  }
+  cartographicToCartesianArray(coordCartoArray) {
+    const cartesianArray = [];
+    for (let i = 0; i < coordCartoArray.length; i++) {
+      cartesianArray.push(this.cartographicToCartesian(coordCartoArray[i]));
+    }
+    return cartesianArray;
+  }
+  intersection(ray) {
+    const EPSILON = 0.0001;
+    const O_C = ray.origin;
+    const dir = ray.direction;
+    // normalizeVector( dir );
+
+    const a = dir.x * dir.x * this._invRadiiSquared.x + dir.y * dir.y * this._invRadiiSquared.y + dir.z * dir.z * this._invRadiiSquared.z;
+    const b = 2 * O_C.x * dir.x * this._invRadiiSquared.x + 2 * O_C.y * dir.y * this._invRadiiSquared.y + 2 * O_C.z * dir.z * this._invRadiiSquared.z;
+    const c = O_C.x * O_C.x * this._invRadiiSquared.x + O_C.y * O_C.y * this._invRadiiSquared.y + O_C.z * O_C.z * this._invRadiiSquared.z - 1;
+    let d = b * b - 4 * a * c;
+    if (d < 0 || a === 0 || b === 0 || c === 0) {
+      return false;
+    }
+    d = Math.sqrt(d);
+    const t1 = (-b + d) / (2 * a);
+    const t2 = (-b - d) / (2 * a);
+    if (t1 <= EPSILON && t2 <= EPSILON) {
+      // both intersections are behind the ray origin
+      return false;
+    }
+    let t = 0;
+    if (t1 <= EPSILON) {
+      t = t2;
+    } else if (t2 <= EPSILON) {
+      t = t1;
+    } else {
+      t = t1 < t2 ? t1 : t2;
+    }
+    if (t < EPSILON) {
+      return false;
+    } // Too close to intersection
+
+    const inter = new THREE.Vector3();
+    inter.addVectors(ray.origin, dir.clone().setLength(t));
+    return inter;
+  }
+
+  /**
+   * Calculate the geodesic distance, between coordCarto1 and coordCarto2.
+   * It's most short distance on ellipsoid surface between coordCarto1 and
+   * coordCarto2.
+   * It's called orthodromy.
+   *
+   * @param coordCarto1 - The coordinate carto 1
+   * @param coordCarto2 - The coordinate carto 2
+   * @returns The orthodromic distance between the two given coordinates.
+   */
+  geodesicDistance(coordCarto1, coordCarto2) {
+    // The formula uses the distance on approximated sphere,
+    // with the nearest local radius of curvature of the ellipsoid
+    // https://geodesie.ign.fr/contenu/fichiers/Distance_longitude_latitude.pdf
+    const longitude1 = THREE.MathUtils.degToRad(coordCarto1.longitude);
+    const latitude1 = THREE.MathUtils.degToRad(coordCarto1.latitude);
+    const longitude2 = THREE.MathUtils.degToRad(coordCarto2.longitude);
+    const latitude2 = THREE.MathUtils.degToRad(coordCarto2.latitude);
+    const distRad = Math.acos(Math.sin(latitude1) * Math.sin(latitude2) + Math.cos(latitude1) * Math.cos(latitude2) * Math.cos(longitude2 - longitude1));
+    const e = this.eccentricity;
+    const latMoy = (latitude1 + latitude2) * 0.5;
+    const es = (e * Math.sin(latMoy)) ** 2;
+    const rho = this.size.x * (1 - e ** 2) / (1 - es) ** (3 / 2);
+    const N = this.size.x / Math.sqrt(1 - es);
+    return distRad * Math.sqrt(rho * N);
+  }
+}
+export default Ellipsoid;