itowns 2.44.3-next.3 → 2.44.3-next.31

package/lib/Core/Geographic/Crs.js

@@ -1,5 +1,18 @@
 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;
 }
@@ -8,168 +21,150 @@ function mustBeString(crs) {
     throw new Error(`Crs parameter value must be a string: '${crs}'`);
   }
 }
-function isTms(crs) {
-  return isString(crs) && crs.startsWith('TMS');
-}
-function isEpsg(crs) {
-  return isString(crs) && crs.startsWith('EPSG');
-}
-function formatToTms(crs) {
-  mustBeString(crs);
-  return isTms(crs) ? crs : `TMS:${crs.match(/\d+/)[0]}`;
-}
-function formatToEPSG(crs) {
-  mustBeString(crs);
-  return isEpsg(crs) ? crs : `EPSG:${crs.match(/\d+/)[0]}`;
-}
-const UNIT = {
+
+/**
+ * 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,
-  METER: 2
+  /**
+   * Distance unit in meter.
+   */
+  METER: 2,
+  /**
+   * Distance unit in foot.
+   */
+  FOOT: 3
 };
-function is4326(crs) {
+
+/**
+ * Checks that the CRS is EPSG:4326.
+ * @internal
+ *
+ * @param crs - The CRS to test.
+ */
+export function is4326(crs) {
   return crs === 'EPSG:4326';
 }
-function isGeocentric(crs) {
-  mustBeString(crs);
-  const projection = proj4.defs(crs);
-  return !projection ? false : projection.projName == 'geocent';
-}
-function _unitFromProj4Unit(projunit) {
-  if (projunit === 'degrees') {
+function unitFromProj4Unit(proj) {
+  if (proj.units === 'degrees') {
     return UNIT.DEGREE;
-  } else if (projunit === 'm') {
+  } 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;
   }
 }
-function toUnit(crs) {
+
+/**
+ * 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);
-  switch (crs) {
-    case 'EPSG:4326':
-      return UNIT.DEGREE;
-    case 'EPSG:4978':
-      return UNIT.METER;
-    default:
-      {
-        const p = proj4.defs(formatToEPSG(crs));
-        if (!p) {
-          return undefined;
-        }
-        return _unitFromProj4Unit(p.units);
-      }
+  const p = proj4.defs(crs);
+  if (!p) {
+    return undefined;
   }
+  return unitFromProj4Unit(p);
 }
-function toUnitWithError(crs) {
+
+/**
+ * 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 u = toUnit(crs);
-  if (u === undefined) {
-    throw new Error(`No unit found for crs: '${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}`);
   }
-  return u;
 }
 
 /**
- * This module provides basic methods to manipulate a CRS (as a string).
+ * Gives a reasonable epsilon for this CRS.
  *
- * @module CRS
+ * @param crs - The CRS to use.
+ * @returns 0.01 if the CRS is EPSG:4326, 0.001 otherwise.
  */
-export default {
-  /**
-   * Units that can be used for a CRS.
-   *
-   * @enum {number}
-   */
-  UNIT,
-  /**
-   * Assert that the CRS is valid one.
-   *
-   * @param {string} crs - The CRS to validate.
-   *
-   * @throws {Error} if the CRS is not valid.
-   */
-  isValid(crs) {
-    toUnitWithError(crs);
-  },
-  /**
-   * Assert that the CRS is geographic.
-   *
-   * @param {string} crs - The CRS to validate.
-   * @return {boolean}
-   * @throws {Error} if the CRS is not valid.
-   */
-  isGeographic(crs) {
-    return toUnitWithError(crs) == UNIT.DEGREE;
-  },
-  /**
-   * Assert that the CRS is using metric units.
-   *
-   * @param {string} crs - The CRS to validate.
-   * @return {boolean}
-   * @throws {Error} if the CRS is not valid.
-   */
-  isMetricUnit(crs) {
-    return toUnit(crs) == UNIT.METER;
-  },
-  /**
-   * Get the unit to use with the CRS.
-   *
-   * @param {string} crs - The CRS to get the unit from.
-   * @return {number} Either `UNIT.METER`, `UNIT.DEGREE` or `undefined`.
-   */
-  toUnit,
-  /**
-   * Is the CRS EPSG:4326 ?
-   *
-   * @param {string} crs - The CRS to test.
-   * @return {boolean}
-   */
-  is4326,
-  /**
-   * Is the CRS geocentric ?
-   * if crs isn't defined the method returns false.
-   *
-   * @param {string} crs - The CRS to test.
-   * @return {boolean}
-   */
-  isGeocentric,
-  /**
-   * Give a reasonnable epsilon to use with this CRS.
-   *
-   * @param {string} crs - The CRS to use.
-   * @return {number} 0.01 if the CRS is EPSG:4326, 0.001 otherwise.
-   */
-  reasonnableEpsilon(crs) {
-    if (is4326(crs)) {
-      return 0.01;
-    } else {
-      return 0.001;
-    }
-  },
-  /**
-   * format crs to European Petroleum Survey Group notation : EPSG:XXXX.
-   *
-   * @param      {string}  crs     The crs to format
-   * @return     {string}  formated crs
-   */
-  formatToEPSG,
-  /**
-   * format crs to tile matrix set notation : TMS:XXXX.
-   *
-   * @param      {string}  crs     The crs to format
-   * @return     {string}  formated crs
-   */
-  formatToTms,
-  isTms,
-  isEpsg,
-  tms_3857: 'TMS:3857',
-  tms_4326: 'TMS:4326',
-  /**
-   * Define a proj4 projection as a string and reference.
-   *
-   * @param {string}  code    code is the projection's SRS code (only used internally by the Proj4js library)
-   * @param {string}  proj4def is the Proj4 definition string for the projection to use
-   * @return {undefined}
-   */
-  defs: (code, proj4def) => proj4.defs(code, proj4def)
-};
+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);