mapshaper-proj

This software is a JavaScript port of v4.9.3 of the Proj.4 map projection library. Although it was created to be used by mapshaper, all are welcome to use and improve it.

Why create another Proj.4 port, when there is already proj4js? Unlike proj4js, this port is a very literal translation to JavaScript, so staying up-to-date with future changes to Proj.4 should be relatively simple. Also, this software's output is more consistent with Proj.4's output.

##### Missing features

* No support for datum transformations using grid files.

* About 1/5 of Proj.4's 130-odd projections have not been ported.

Command line programs: mproj and mcs2cs

These are workalike versions of the proj and cs2cs programs from Proj.4.

To install the current versions system-wide, run npm install -g mproj.

Node API

The software can be used in either the Proj.4 style or the proj4js style.

##### proj4js style

``
var proj = require('mproj');


create functions for translating between two coordinate systems

returned object has forward() and inverse() functions

var obj = proj(, );

WGS84 is assumed if a source definition is not given

var obj = proj();

a shortcut for translating a single point

is an [x, y] array or an object with x and y properties

var xy = proj([,] dest definition, );
`

See the proj4js.org website for more detailed help.

##### Proj.4 style

`
var proj = require('mproj');


create a projection object from a proj4 string

var P = proj.pj_init();

project and inverse-project geographical coordinates

var xy = proj.pj_fwd({lam: , phi: }, P);
var lp = proj.pj_inv({x: , y: }, P);

transform arrays of coordinates from one coordinate system to another

proj.pj_transform(, , , [, ]);
`

##### Error handling
The x and y coordinates of unprojectable points are set to Infinity. Other errors cause an Error to be thrown containing an appropriate message.




Building

mapshaper-proj uses the (old-fashioned) technique of concatenating source files and wrapping them in a function to create a module with a shared scope. This method allows for global variables that are invisible outside of the program, making porting from the original C much simpler than if we were to make each source file a separate module.

Running build creates a build containing all supported projections in the dist/ directory.

Running build merc,lcc,aea creates a build containing only the listed projections. You can customize the comma-separated list to include only the projections that you want. Run mproj -l` to see a list of all supported projections.