= User Guide =

== 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: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 [http://openlayers.org/ OpenLayers] classes which are compiled into the file [https://svn.codehaus.org/mapbuilder/cscs/trunk/proj4js/lib/OLprotoype.js 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 [wiki: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.

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)
 1. define a proxy script to allow cross domain HTTP requests {{{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);}
}}}