User Guide

Basics

Using Proj4js is a matter of:

1. including the library in your page
2. creating source and destination Proj4js objects
3. transforming point coordinates.

// include the library
<script src="lib/proj4js-combined.js"></script>  //adjust the path for your server
                                                 //or else use the compressed version

. . .

// creating source and destination Proj4js objects
// once initialized, these may be re-used as often as needed
var source = new Proj4js.Proj(‘EPSG:4236’);    //source coordinates will be in Longitude/Latitude
var dest = new Proj4js.Proj(‘EPSG:27563’);     //destination coordinates in LCC, south of France

. . .

// transforming point coordinates
var p = new Proj4js.Point(-76.0,45.0);   //any object will do as long as it has 'x' and 'y' properties
Proj4js.transform(source, dest, p);      //do the transformation.  x and y are modified in place

//p.x and p.y are now EPSG:27563 easting and northing in meters
. . .

Note: Proj4js currently depends on some core ​OpenLayers classes which are compiled into the file ​OLprotoype.js. If you are using Proj4js in a page that already includes the OpenLayers library, there is no need to include this file, otherwise you must also include OLprototype.js in a <script> tag. The development plan for Proj4js is to factor out this requirement so that the OpenLayers classes will only be required for dynamic lookup of the CRS definitions (see below).

Proj4js.Proj constructor

Every Proj4js.Proj object must be initialized with the parameters of the CRS to be used. The argument to the constructor is a key in the Proj4js.defs object.

Proj4js.defs["EPSG:27563"]="+title=LAMB sud france  +proj=lcc +lat_1=44.1 +lat_0=44.1 +lon_0=0 +k_0=0.999877499 
                            +x_0=600000 +y_0=200000 +a=6378249.2 +b=6356515 +towgs84=-168,-60,320,0,0,0,0 +pm=paris +units=m";

Proj4js uses the same initialization parameters that ​PROJ.4 uses and these values must be defined before the constructor is called.

If you know the projections to be used in your application

You can define these via the script tag (see examples in the lib/defs directory) or anywhere else in your application.

<script src="lib/defs/EPSG27563.js"></script >

Dynamic lookup of initialization parameters

If you don't know the CRS's to be used by the application, Proj4js can dynamically look up the initialization parameters at run-time. By default, it will use the REST web service at ​spatialreference.org as the lookup service.

To use Proj4js in this way, you will need to:

1. include the OLprotoype.js file in a script tag (only if your page doesn't already include OpenLayers)
2. define a proxy script to allow cross domain HTTP requests, e.g. Proj4js.proxyScript = '/mapbuilder/proxy?url=';

The way dynamic definition string lookup works is to first check for the definition at the path lib/defs. If the appropriate file is found there, it will be loaded and used by Proj4js. If it is not found there (note: in this case it is normal to see an error in the Firebug console), an HTTP request will be issued to spatialreference.org. If the definition for the CRS code is not found there, Proj4js will set the projection to WGS84.

Logging and Errors

Proj4js includes two methods for reporting errors and log info which by default are empty stub functions which do nothing. To see error reports and logs, you must provide an override for these methods, for example:

//somewhere in your JS code
Proj4js.log = function(msg) {console.log(msg);}
Proj4js.reportError = function(msg) {alert(msg);}

Supported projection classes

The following projection classes have been tested and are expected to produce correct results. (The projection class is defined by the '+proj=xyz' parameter in the initialization string):

• utm
• lcc
• tmerc
• merc
• stere
• gauss
• sterea
• aea

The following projection projection classes have the forrward and inverse transformation code available for them but have not been validated against some test points yet:

• aeqd
• eqdc
• equi
• laea
• mill
• moll
• omerc
• ortho
• poly
• sinu
• vandg