Proj4js is a JavaScript library to transform point coordinates from one coordinate system to another, including datum transformations.
Originally a port of PROJ (then known as PROJ.4) and GCTCP C (Archive) it is
a part of the MetaCRS group of projects.
Installing
Depending on your preferences
npm install proj4
or download dist.zip from the latest release and grab proj4.js from it.
If you do not want to download anything, Proj4js is also available via jsDelivr for direct use in your browser applications:
Projections can be proj or wkt strings, or PROJJSON objects.
Coordinates may be an object of the form {x:x,y:y} or an array of the form [x,y].
When all 3 arguments are given, the result is that the coordinates are transformed from projection1 to projection 2. And returned in the same format that they were given in.
var firstProjection = 'PROJCS["NAD83 / Massachusetts Mainland",GEOGCS["NAD83",DATUM["North_American_Datum_1983",SPHEROID["GRS 1980",6378137,298.257222101,AUTHORITY["EPSG","7019"]],AUTHORITY["EPSG","6269"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.01745329251994328,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4269"]],UNIT["metre",1,AUTHORITY["EPSG","9001"]],PROJECTION["Lambert_Conformal_Conic_2SP"],PARAMETER["standard_parallel_1",42.68333333333333],PARAMETER["standard_parallel_2",41.71666666666667],PARAMETER["latitude_of_origin",41],PARAMETER["central_meridian",-71.5],PARAMETER["false_easting",200000],PARAMETER["false_northing",750000],AUTHORITY["EPSG","26986"],AXIS["X",EAST],AXIS["Y",NORTH]]';var secondProjection = "+proj=gnom +lat_0=90 +lon_0=0 +x_0=6300000 +y_0=6300000 +ellps=WGS84 +datum=WGS84 +units=m +no_defs";//I'm not going to redefine those two in latter examples.proj4(firstProjection,secondProjection,[-122.305887, 58.9465872]);// [-2690575.447893817, 36622916.8071244564]
The library can also parse coordinates provided with an elevation and measure, again as an object of the form {x:x,y:y,z:z,m:m} or an array of the form [x,y,z,m].
If no coordinates are given an object with two methods is returned, its methods are forward which projects from the first projection to the second and inverse which projects from the second to the first.
Note: The generation of the floating point value 40.99999999999986 in this example represents the fact that some variance in precision is involved in any conversion between one coordinate reference system and another.
Named Projections
If you prefer to define a projection as a string and reference it that way, you may use the proj4.defs method which can be called 2 ways, with a name and projection:
By default, proj4 uses [x,y] axis order for projected (cartesian) coordinate systems and [x=longitude,y=latitude] for geographic coordinates. To enforce the axis order of the provided proj or wkt string, use the
Proj4js has built-in Helmert transformations for many datums to transform to and from WGS84, which is used as pivot for datum transformations. If a datum is not available or not accurate enough for the desired region, custom Helmert transformations or grid based datum adjustments are supported.
WKT1 definitions can contain a TOWGS84 parameter. For proj strings, towgs84 or nadgrids can be specified. When using WKT2 or PROJJSON definitions, if a BOUNDCRS with an ABRIDGEDTRANDFORMATION to WGS84 is provided, Helmert transformation parameters (like +towgs84= in proj strings) or the name of the parameter file (like +nadgrids= in proj strings) will be extracted from it.
Grid Based Datum Adjustments
NTV2 format (.gsb)
To use +nadgrids= in a proj definition or a WKT2/PROJJSON ABRIDGEDTRANSFORM with an NTv2 method, first read your NTv2 .gsb file (e.g. from https://github.com/OSGeo/proj-datumgrid) into an ArrayBuffer, then pass it to proj4.nadgrid. E.g:
Optionally, if your .gsb file does not contain latitude and longitude error columns, you can provide an options object argument to the proj4.nadgrid call, setting the includeErrorFields property to false, e.g:
Then use the given key in your definition, e.g. proj4.defs("EPSG:32188","+proj=tmerc +lat_0=0 +lon_0=-73.5 +k=0.9999 +x_0=304800 +y_0=0 +ellps=GRS80 +nadgrids=ca_nrc_NA83SCRS.tif +units=m +no_defs +type=crs"); noting the +nadgrids=ca_nrc_NA83SCRS.tif parameter.
Developing
To set up build tools make sure you have node installed and then run npm install.
To do the complete build run
npm run build
To run node and browser tests run
npm test
To run node tests with coverage run
npm run buildnpm run test:coverage
To create a build with only default projections (latlon and Mercator) run
node scripts/build.mjs default
To create a build with only custom projections include a comma separated list of projections codes (the file name in 'lib/projections' without the '.js'), e.g.