[[PageOutline]]

= User Guide =

'''NOTE: This guide is for Proj4js version 1.1.0 and earlier.  Visit [https://github.com/proj4js/proj4js#using the Github page] for information about using more recent versions.'''

== Basics ==

Using Proj4js is a matter of:
 1. including the library in your page
 1. creating source and destination Proj4js objects
 1. 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:4326’);    //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
. . .
}}}

== 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 [http://trac.osgeo.org/proj/ 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 [http://spatialreference.org spatialreference.org] as the lookup service.

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), a request for the definition will be issued to spatialreference.org.  If the definition for the CRS code is not found there, Proj4js will set the projection to WGS84.

Dynamic loading occurs asynchronously so you must ensure that the Proj4js.Proj.readyToUse flag is set before carrying out any transformations.

To prevent invoking dynamic loading, simply ensure that any required files are loaded, either through using a built version of the library or by using <script> tags in your application.  In this case the Proj4js.Proj constructor will behave synchronously and be readyToUse on return.

== Logging and Errors ==

Proj4js includes a method for reporting errors which by default is an empty stub function which does nothing.  You must provide an override for reportError to do something such as throw and exception or issue an alert, for example:

{{{
//somewhere in your JS code
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
 * somerc
 * stere
 * gauss
 * sterea
 * aea
 * cea
 * laea
 * sinu

The following projection projection classes have the forward and inverse transformation code available for them but have '''not''' been validated against any test points yet:
 * aeqd
 * eqdc
 * equi
 * mill
 * moll
 * omerc
 * ortho
 * poly
 * vandg