proj4 2.16.2 → 2.19.0

package/lib/nadgrid.js

@@ -4,13 +4,79 @@
  * - http://mimaka.com/help/gs/html/004_NTV2%20Data%20Format.htm
  */
 
+/**
+ * @typedef {Object} NadgridInfo
+ * @property {string} name The name of the NAD grid or 'null' if not specified.
+ * @property {boolean} mandatory Indicates if the grid is mandatory (true) or optional (false).
+ * @property {*} grid The loaded NAD grid object, or null if not loaded or not applicable.
+ * @property {boolean} isNull True if the grid is explicitly 'null', otherwise false.
+ */
+
+/**
+ * @typedef {Object} NTV2GridOptions
+ * @property {boolean} [includeErrorFields=true] Whether to include error fields in the subgrids.
+ */
+
+/**
+ * @typedef {Object} NadgridHeader
+ * @property {number} [nFields] Number of fields in the header.
+ * @property {number} [nSubgridFields] Number of fields in each subgrid header.
+ * @property {number} nSubgrids Number of subgrids in the file.
+ * @property {string} [shiftType] Type of shift (e.g., "SECONDS").
+ * @property {number} [fromSemiMajorAxis] Source ellipsoid semi-major axis.
+ * @property {number} [fromSemiMinorAxis] Source ellipsoid semi-minor axis.
+ * @property {number} [toSemiMajorAxis] Target ellipsoid semi-major axis.
+ * @property {number} [toSemiMinorAxis] Target ellipsoid semi-minor axis.
+ */
+
+/**
+ * @typedef {Object} Subgrid
+ * @property {Array<number>} ll Lower left corner of the grid in radians [longitude, latitude].
+ * @property {Array<number>} del Grid spacing in radians [longitude interval, latitude interval].
+ * @property {Array<number>} lim Number of columns in the grid [longitude columns, latitude columns].
+ * @property {number} [count] Total number of grid nodes.
+ * @property {Array} cvs Mapped node values for the grid.
+ */
+
+/** @typedef {{header: NadgridHeader, subgrids: Array<Subgrid>}} NADGrid */
+
 var loadedNadgrids = {};
 
 /**
- * Load a binary NTv2 file (.gsb) to a key that can be used in a proj string like +nadgrids=<key>. Pass the NTv2 file
- * as an ArrayBuffer.
+ * @overload
+ * @param {string} key - The key to associate with the loaded grid.
+ * @param {ArrayBuffer} data - The NTv2 grid data as an ArrayBuffer.
+ * @param {NTV2GridOptions} [options] - Optional parameters for loading the grid.
+ * @returns {NADGrid} - The loaded NAD grid information.
+ */
+/**
+ * @overload
+ * @param {string} key - The key to associate with the loaded grid.
+ * @param {import('geotiff').GeoTIFF} data - The GeoTIFF instance to read the grid from.
+ * @returns {{ready: Promise<NADGrid>}} - A promise that resolves to the loaded grid information.
+ */
+/**
+ * Load either a NTv2 file (.gsb) or a Geotiff (.tif) to a key that can be used in a proj string like +nadgrids=<key>. Pass the NTv2 file
+ * as an ArrayBuffer. Pass Geotiff as a GeoTIFF instance from the geotiff.js library.
+ * @param {string} key - The key to associate with the loaded grid.
+ * @param {ArrayBuffer|import('geotiff').GeoTIFF} data The data to load, either an ArrayBuffer for NTv2 or a GeoTIFF instance.
+ * @param {NTV2GridOptions} [options] Optional parameters.
+ * @returns {{ready: Promise<NADGrid>}|NADGrid} - A promise that resolves to the loaded grid information.
  */
 export default function nadgrid(key, data, options) {
+  if (data instanceof ArrayBuffer) {
+    return readNTV2Grid(key, data, options);
+  }
+  return { ready: readGeotiffGrid(key, data) };
+}
+
+/**
+ * @param {string} key The key to associate with the loaded grid.
+ * @param {ArrayBuffer} data The NTv2 grid data as an ArrayBuffer.
+ * @param {NTV2GridOptions} [options] Optional parameters for loading the grid.
+ * @returns {NADGrid} The loaded NAD grid information.
+ */
+function readNTV2Grid(key, data, options) {
   var includeErrorFields = true;
   if (options !== undefined && options.includeErrorFields === false) {
     includeErrorFields = false;
@@ -24,8 +90,60 @@ export default function nadgrid(key, data, options) {
   return nadgrid;
 }
 
+/**
+ * @param {string} key The key to associate with the loaded grid.
+ * @param {import('geotiff').GeoTIFF} tiff The GeoTIFF instance to read the grid from.
+ * @returns {Promise<NADGrid>} A promise that resolves to the loaded NAD grid information.
+ */
+async function readGeotiffGrid(key, tiff) {
+  var subgrids = [];
+  var subGridCount = await tiff.getImageCount();
+  // proj produced tiff grid shift files appear to organize lower res subgrids first, higher res/ child subgrids last.
+  for (var subgridIndex = subGridCount - 1; subgridIndex >= 0; subgridIndex--) {
+    var image = await tiff.getImage(subgridIndex);
+
+    var rasters = await image.readRasters();
+    var data = rasters;
+    var lim = [image.getWidth(), image.getHeight()];
+    var imageBBoxRadians = image.getBoundingBox().map(degreesToRadians);
+    var del = [image.fileDirectory.ModelPixelScale[0], image.fileDirectory.ModelPixelScale[1]].map(degreesToRadians);
+
+    var maxX = imageBBoxRadians[0] + (lim[0] - 1) * del[0];
+    var minY = imageBBoxRadians[3] - (lim[1] - 1) * del[1];
+
+    var latitudeOffsetBand = data[0];
+    var longitudeOffsetBand = data[1];
+    var nodes = [];
+
+    for (let i = lim[1] - 1; i >= 0; i--) {
+      for (let j = lim[0] - 1; j >= 0; j--) {
+        var index = i * lim[0] + j;
+        nodes.push([-secondsToRadians(longitudeOffsetBand[index]), secondsToRadians(latitudeOffsetBand[index])]);
+      }
+    }
+
+    subgrids.push({
+      del: del,
+      lim: lim,
+      ll: [-maxX, minY],
+      cvs: nodes
+    });
+  }
+
+  var tifGrid = {
+    header: {
+      nSubgrids: subGridCount
+    },
+    subgrids: subgrids
+  };
+  loadedNadgrids[key] = tifGrid;
+  return tifGrid;
+};
+
 /**
  * Given a proj4 value for nadgrids, return an array of loaded grids
+ * @param {string} nadgrids A comma-separated list of grid names, optionally prefixed with '@' to indicate optional grids.
+ * @returns
  */
 export function getNadgrids(nadgrids) {
   // Format details: http://proj.maptools.org/gen_parms.html
@@ -36,6 +154,10 @@ export function getNadgrids(nadgrids) {
   return grids.map(parseNadgridString);
 }
 
+/**
+ * @param {string} value The nadgrid string to get information for.
+ * @returns {NadgridInfo|null} An object with grid information, or null if the input is empty.
+ */
 function parseNadgridString(value) {
   if (value.length === 0) {
     return null;
@@ -55,6 +177,10 @@ function parseNadgridString(value) {
   };
 }
 
+function degreesToRadians(degrees) {
+  return (degrees) * Math.PI / 180;
+}
+
 function secondsToRadians(seconds) {
   return (seconds / 3600) * Math.PI / 180;
 }
@@ -115,6 +241,10 @@ function readSubgrids(view, header, isLittleEndian, includeErrorFields) {
   return grids;
 }
 
+/**
+ * @param {*} nodes
+ * @returns Array<Array<number>>
+ */
 function mapNodes(nodes) {
   return nodes.map(function (r) {
     return [secondsToRadians(r.longitudeShift), secondsToRadians(r.latitudeShift)];

package/lib/parseCode.js

@@ -30,6 +30,10 @@ function checkProjStr(item) {
 function testProj(code) {
   return code[0] === '+';
 }
+/**
+ * @param {string | import('./core').PROJJSONDefinition | import('./defs').ProjectionDefinition} code
+ * @returns {import('./defs').ProjectionDefinition}
+ */
 function parse(code) {
   if (testObj(code)) {
     // check to see if this is a WKT string
@@ -51,7 +55,7 @@ function parse(code) {
     if (testProj(code)) {
       return projStr(code);
     }
-  } else if (!code.projName) {
+  } else if (!('projName' in code)) {
     return wkt(code);
   } else {
     return code;

package/lib/projString.js

@@ -3,13 +3,19 @@ import PrimeMeridian from './constants/PrimeMeridian';
 import units from './constants/units';
 import match from './match';
 
+/**
+ * @param {string} defData
+ * @returns {import('./defs').ProjectionDefinition}
+ */
 export default function (defData) {
+  /** @type {import('./defs').ProjectionDefinition} */
   var self = {};
   var paramObj = defData.split('+').map(function (v) {
     return v.trim();
   }).filter(function (a) {
     return a;
   }).reduce(function (p, a) {
+    /** @type {Array<?>} */
     var split = a.split('=');
     split.push(true);
     p[split[0].toLowerCase()] = split[1];

package/lib/projections/aea.js

@@ -4,6 +4,30 @@ import adjust_lon from '../common/adjust_lon';
 import asinz from '../common/asinz';
 import { EPSLN } from '../constants/values';
 
+/**
+ * @typedef {Object} LocalThis
+ * @property {number} temp
+ * @property {number} es
+ * @property {number} e3
+ * @property {number} sin_po
+ * @property {number} cos_po
+ * @property {number} t1
+ * @property {number} con
+ * @property {number} ms1
+ * @property {number} qs1
+ * @property {number} t2
+ * @property {number} ms2
+ * @property {number} qs2
+ * @property {number} t3
+ * @property {number} qs0
+ * @property {number} ns0
+ * @property {number} c
+ * @property {number} rh
+ * @property {number} sin_phi
+ * @property {number} cos_phi
+ */
+
+/** @this {import('../defs.js').ProjectionDefinition & LocalThis} */
 export function init() {
   if (Math.abs(this.lat1 + this.lat2) < EPSLN) {
     return;
@@ -41,6 +65,7 @@ export function init() {
 
 /* Albers Conical Equal Area forward equations--mapping lat,long to x,y
   ------------------------------------------------------------------- */
+/** @this {import('../defs.js').ProjectionDefinition & LocalThis} */
 export function forward(p) {
   var lon = p.x;
   var lat = p.y;

package/lib/projections/aeqd.js

@@ -1,5 +1,5 @@
 import adjust_lon from '../common/adjust_lon';
-import { HALF_PI, EPSLN, D2R } from '../constants/values';
+import { HALF_PI, EPSLN } from '../constants/values';
 import mlfn from '../common/mlfn';
 import e0fn from '../common/e0fn';
 import e1fn from '../common/e1fn';
@@ -7,12 +7,23 @@ import e2fn from '../common/e2fn';
 import e3fn from '../common/e3fn';
 import asinz from '../common/asinz';
 import imlfn from '../common/imlfn';
-import { Geodesic } from 'geographiclib-geodesic';
+import { vincentyDirect, vincentyInverse } from '../common/vincenty';
 
+/**
+ * @typedef {Object} LocalThis
+ * @property {number} es
+ * @property {number} sin_p12
+ * @property {number} cos_p12
+ * @property {number} a
+ * @property {number} f
+ */
+
+/** @this {import('../defs.js').ProjectionDefinition & LocalThis} */
 export function init() {
   this.sin_p12 = Math.sin(this.lat0);
   this.cos_p12 = Math.cos(this.lat0);
-  this.g = new Geodesic.Geodesic(this.a, this.es / (1 + Math.sqrt(1 - this.es)));
+  // flattening for ellipsoid
+  this.f = this.es / (1 + Math.sqrt(1 - this.es));
 }
 
 export function forward(p) {
@@ -21,7 +32,7 @@ export function forward(p) {
   var sinphi = Math.sin(p.y);
   var cosphi = Math.cos(p.y);
   var dlon = adjust_lon(lon - this.long0);
-  var e0, e1, e2, e3, Mlp, Ml, c, kp, cos_c, lat1, lon1, lat2, lon2, vars, azi1;
+  var e0, e1, e2, e3, Mlp, Ml, c, kp, cos_c, vars, azi1;
   if (this.sphere) {
     if (Math.abs(this.sin_p12 - 1) <= EPSLN) {
       // North Pole case
@@ -67,14 +78,8 @@ export function forward(p) {
         p.x = p.y = 0;
         return p;
       }
-      lat1 = this.lat0 / D2R;
-      lon1 = this.long0 / D2R;
-      lat2 = lat / D2R;
-      lon2 = lon / D2R;
-
-      vars = this.g.Inverse(lat1, lon1, lat2, lon2, this.g.AZIMUTH);
-      azi1 = vars.azi1 * D2R;
-
+      vars = vincentyInverse(this.lat0, this.long0, lat, lon, this.a, this.f);
+      azi1 = vars.azi1;
       p.x = vars.s12 * Math.sin(azi1);
       p.y = vars.s12 * Math.cos(azi1);
       return p;
@@ -85,7 +90,7 @@ export function forward(p) {
 export function inverse(p) {
   p.x -= this.x0;
   p.y -= this.y0;
-  var rh, z, sinz, cosz, lon, lat, con, e0, e1, e2, e3, Mlp, M, lat1, lon1, azi1, s12, vars;
+  var rh, z, sinz, cosz, lon, lat, con, e0, e1, e2, e3, Mlp, M, azi1, s12, vars;
   if (this.sphere) {
     rh = Math.sqrt(p.x * p.x + p.y * p.y);
     if (rh > (2 * HALF_PI * this.a)) {
@@ -109,13 +114,6 @@ export function inverse(p) {
           lon = adjust_lon(this.long0 - Math.atan2(-p.x, p.y));
         }
       } else {
-        /* con = cosz - this.sin_p12 * Math.sin(lat);
-        if ((Math.abs(con) < EPSLN) && (Math.abs(p.x) < EPSLN)) {
-          //no-op, just keep the lon value as is
-        } else {
-          var temp = Math.atan2((p.x * sinz * this.cos_p12), (con * rh));
-          lon = adjust_lon(this.long0 + Math.atan2((p.x * sinz * this.cos_p12), (con * rh)));
-        } */
         lon = adjust_lon(this.long0 + Math.atan2(p.x * sinz, rh * this.cos_p12 * cosz - p.y * this.sin_p12 * sinz));
       }
     }
@@ -151,14 +149,12 @@ export function inverse(p) {
       return p;
     } else {
       // default case
-      lat1 = this.lat0 / D2R;
-      lon1 = this.long0 / D2R;
-      azi1 = Math.atan2(p.x, p.y) / D2R;
+      azi1 = Math.atan2(p.x, p.y);
       s12 = Math.sqrt(p.x * p.x + p.y * p.y);
-      vars = this.g.Direct(lat1, lon1, azi1, s12, this.g.STANDARD);
+      vars = vincentyDirect(this.lat0, this.long0, azi1, s12, this.a, this.f);
 
-      p.x = vars.lon2 * D2R;
-      p.y = vars.lat2 * D2R;
+      p.x = vars.lon2;
+      p.y = vars.lat2;
       return p;
     }
   }

package/lib/projections/bonne.js

@@ -6,8 +6,19 @@ import pj_inv_mlfn from '../common/pj_inv_mlfn';
 import pj_mlfn from '../common/pj_mlfn';
 import { HALF_PI } from '../constants/values';
 
+/**
+ * @typedef {Object} LocalThis
+ * @property {number} phi1
+ * @property {number} cphi1
+ * @property {number} es
+ * @property {Array<number>} en
+ * @property {number} m1
+ * @property {number} am1
+ */
+
 var EPS10 = 1e-10;
 
+/** @this {import('../defs.js').ProjectionDefinition & LocalThis} */
 export function init() {
   var c;
 

package/lib/projections/cass.js

@@ -9,6 +9,17 @@ import adjust_lat from '../common/adjust_lat';
 import imlfn from '../common/imlfn';
 import { HALF_PI, EPSLN } from '../constants/values';
 
+/**
+ * @typedef {Object} LocalThis
+ * @property {number} es
+ * @property {number} e0
+ * @property {number} e1
+ * @property {number} e2
+ * @property {number} e3
+ * @property {number} ml0
+ */
+
+/** @this {import('../defs.js').ProjectionDefinition & LocalThis} */
 export function init() {
   if (!this.sphere) {
     this.e0 = e0fn(this.es);

package/lib/projections/cea.js

@@ -3,11 +3,17 @@ import qsfnz from '../common/qsfnz';
 import msfnz from '../common/msfnz';
 import iqsfnz from '../common/iqsfnz';
 
-/*
+/**
+ * @typedef {Object} LocalThis
+ * @property {number} e
+ */
+
+/**
   reference:
     "Cartographic Projection Procedures for the UNIX Environment-
     A User's Manual" by Gerald I. Evenden,
     USGS Open File Report 90-284and Release 4 Interim Reports (2003)
+  @this {import('../defs.js').ProjectionDefinition & LocalThis}
 */
 export function init() {
   // no-op

package/lib/projections/eqdc.js

@@ -9,6 +9,28 @@ import adjust_lat from '../common/adjust_lat';
 import imlfn from '../common/imlfn';
 import { EPSLN } from '../constants/values';
 
+/**
+ * @typedef {Object} LocalThis
+ * @property {number} temp
+ * @property {number} es
+ * @property {number} e
+ * @property {number} e0
+ * @property {number} e1
+ * @property {number} e2
+ * @property {number} e3
+ * @property {number} sin_phi
+ * @property {number} cos_phi
+ * @property {number} ms1
+ * @property {number} ml1
+ * @property {number} ms2
+ * @property {number} ml2
+ * @property {number} ns
+ * @property {number} g
+ * @property {number} ml0
+ * @property {number} rh
+ */
+
+/** @this {import('../defs.js').ProjectionDefinition & LocalThis} */
 export function init() {
   /* Place parameters in static storage for common use
       ------------------------------------------------- */
@@ -25,18 +47,18 @@ export function init() {
   this.e2 = e2fn(this.es);
   this.e3 = e3fn(this.es);
 
-  this.sinphi = Math.sin(this.lat1);
-  this.cosphi = Math.cos(this.lat1);
+  this.sin_phi = Math.sin(this.lat1);
+  this.cos_phi = Math.cos(this.lat1);
 
-  this.ms1 = msfnz(this.e, this.sinphi, this.cosphi);
+  this.ms1 = msfnz(this.e, this.sin_phi, this.cos_phi);
   this.ml1 = mlfn(this.e0, this.e1, this.e2, this.e3, this.lat1);
 
   if (Math.abs(this.lat1 - this.lat2) < EPSLN) {
-    this.ns = this.sinphi;
+    this.ns = this.sin_phi;
   } else {
-    this.sinphi = Math.sin(this.lat2);
-    this.cosphi = Math.cos(this.lat2);
-    this.ms2 = msfnz(this.e, this.sinphi, this.cosphi);
+    this.sin_phi = Math.sin(this.lat2);
+    this.cos_phi = Math.cos(this.lat2);
+    this.ms2 = msfnz(this.e, this.sin_phi, this.cos_phi);
     this.ml2 = mlfn(this.e0, this.e1, this.e2, this.e3, this.lat2);
     this.ns = (this.ms1 - this.ms2) / (this.ml2 - this.ml1);
   }

package/lib/projections/equi.js

@@ -1,5 +1,12 @@
 import adjust_lon from '../common/adjust_lon';
 
+/**
+ * @typedef {Object} LocalThis
+ * @property {number} t1
+ * @property {number} t2
+ */
+
+/** @this {import('../defs.js').ProjectionDefinition} */
 export function init() {
   this.x0 = this.x0 || 0;
   this.y0 = this.y0 || 0;
@@ -8,8 +15,10 @@ export function init() {
   /// this.t2;
 }
 
-/* Equirectangular forward equations--mapping lat,long to x,y
-  --------------------------------------------------------- */
+/**
+ * Equirectangular forward equations--mapping lat,long to x,y
+ * @this {import('../defs.js').ProjectionDefinition & LocalThis}
+ */
 export function forward(p) {
   var lon = p.x;
   var lat = p.y;

package/lib/projections/etmerc.js

@@ -10,6 +10,18 @@ import clens from '../common/clens';
 import clens_cmplx from '../common/clens_cmplx';
 import adjust_lon from '../common/adjust_lon';
 
+/**
+ * @typedef {Object} LocalThis
+ * @property {number} es
+ * @property {Array<number>} cbg
+ * @property {Array<number>} cgb
+ * @property {Array<number>} utg
+ * @property {Array<number>} gtu
+ * @property {number} Qn
+ * @property {number} Zb
+ */
+
+/** @this {import('../defs.js').ProjectionDefinition & LocalThis} */
 export function init() {
   if (!this.approx && (isNaN(this.es) || this.es <= 0)) {
     throw new Error('Incorrect elliptical usage. Try using the +approx option in the proj string, or PROJECTION["Fast_Transverse_Mercator"] in the WKT.');

package/lib/projections/gauss.js

@@ -2,6 +2,18 @@ import srat from '../common/srat';
 var MAX_ITER = 20;
 import { HALF_PI, FORTPI } from '../constants/values';
 
+/**
+ * @typedef {Object} LocalThis
+ * @property {number} rc
+ * @property {number} C
+ * @property {number} phic0
+ * @property {number} ratexp
+ * @property {number} K
+ * @property {number} e
+ * @property {number} es
+ */
+
+/** @this {import('../defs.js').ProjectionDefinition & LocalThis} */
 export function init() {
   var sphi = Math.sin(this.lat0);
   var cphi = Math.cos(this.lat0);

package/lib/projections/geos.js

@@ -1,5 +1,21 @@
 import hypot from '../common/hypot';
 
+/**
+ * @typedef {Object} LocalThis
+ * @property {1 | 0} flip_axis
+ * @property {number} h
+ * @property {number} radius_g_1
+ * @property {number} radius_g
+ * @property {number} radius_p
+ * @property {number} radius_p2
+ * @property {number} radius_p_inv2
+ * @property {'ellipse'|'sphere'} shape
+ * @property {number} C
+ * @property {string} sweep
+ * @property {number} es
+ */
+
+/** @this {import('../defs.js').ProjectionDefinition & LocalThis} */
 export function init() {
   this.flip_axis = (this.sweep === 'x' ? 1 : 0);
   this.h = Number(this.h);

package/lib/projections/gnom.js

@@ -2,12 +2,21 @@ import adjust_lon from '../common/adjust_lon';
 import asinz from '../common/asinz';
 import { EPSLN } from '../constants/values';
 
-/*
+/**
+ * @typedef {Object} LocalThis
+ * @property {number} sin_p14
+ * @property {number} cos_p14
+ * @property {number} infinity_dist
+ * @property {number} rc
+ */
+
+/**
   reference:
     Wolfram Mathworld "Gnomonic Projection"
     http://mathworld.wolfram.com/GnomonicProjection.html
     Accessed: 12th November 2009
-  */
+   @this {import('../defs.js').ProjectionDefinition & LocalThis}
+ */
 export function init() {
   /* Place parameters in static storage for common use
       ------------------------------------------------- */

package/lib/projections/gstmerc.js

@@ -3,6 +3,18 @@ import sinh from '../common/sinh';
 import cosh from '../common/cosh';
 import invlatiso from '../common/invlatiso';
 
+/**
+ * @typedef {Object} LocalThis
+ * @property {number} e
+ * @property {number} lc
+ * @property {number} rs
+ * @property {number} cp
+ * @property {number} n2
+ * @property {number} xs
+ * @property {number} ys
+*/
+
+/** @this {import('../defs.js').ProjectionDefinition & LocalThis} */
 export function init() {
   // array of:  a, b, lon0, lat0, k0, x0, y0
   var temp = this.b / this.a;