Proj4js

Proj4js is a JavaScript library to transform point coordinates from one coordinate system to another, including datum transformations.

This library is a port of both the Proj.4 and GCTCP C libraries to JavaScript. Enabling these transformations in the browser allows geographic data stored in different projections to be combined in browser-based web mapping applications.

Proj4js must have access to coordinate system initialization strings (which are the same as for PROJ.4 command line). Thes can be included in your application using a <script> tag or Proj4js can load CS initialization strings from a local directory or a web service such as spatialreference.org.

Similarly, Proj4js must have access to projection transform code. These can be included individually using a <script> tag in your page, built into a custom build of Proj4js or loaded dynamically at run-time. Using the -combined and -compressed versions of Proj4js includes all projection class code by default.

Note that dynamic loading of defs and code happens ascynchrously, check the Proj.readyToUse flag before using the Proj object. If the defs and code required by your application are loaded through script tags, dynamic loading is not required and the Proj object will be readyToUse on return from the constructor.

All coordinates are handled as points which have a .x and a .y property which will be modified in place.

Override Proj4js.reportError for output of alerts and warnings.

See http://trac.osgeo.org/proj4js/wiki/UserGuide for full details.

Summary

Proj4js	Proj4js is a JavaScript library to transform point coordinates from one coordinate system to another, including datum transformations.
Properties
defaultDatum	The datum to use when no others a specified
Functions
transform(source, dest, point)	Transform a point coordinate from one map projection to another.
reportError	An internal method to report errors back to user.
Private Methods	The following properties and methods are intended for internal use only.
Functions and Properties
extend	Copy all properties of a source object to a destination object.
Class	Base class used to construct all other classes.
bind	Bind a function to an object.
defsLookupService	AJAX service to retreive projection definition parameters from
libPath	internal: http server path to library code.
getScriptLocation	Return the path to this script.
loadScript	Load a JS file from a URL into a <script> tag in the page.
checkReadyState	IE workaround since there is no onerror handler.
Proj4js.Proj	Proj objects provide transformation methods for point coordinates between geodetic latitude/longitude and a projected coordinate system.
Properties
readyToUse	Flag to indicate if initialization is complete for this Proj object
title	The title to describe the projection
projName	The projection class for this projection, e.g.
units	The units of the projection.
datum	The datum specified for the projection
Functions
initialize	Constructor for Proj4js.Proj objects
loadProjDefinition	Loads the coordinate system initialization string if required.
loadFromService	Creates the REST URL for loading the definition from a web service and loads it.
defsLoaded	Continues the Proj object initilization once the def file is loaded
checkDefsLoaded	This is the loadCheck method to see if the def object exists
defsFailed	Report an error in loading the defs file, but continue on using WGS84
loadProjCode	Loads projection class code dynamically if required.
loadProjCodeSuccess	Loads any proj dependencies or continue on to final initialization.
defsFailed	Report an error in loading the proj file.
checkCodeLoaded	This is the loadCheck method to see if the projection code is loaded
initTransforms	Finalize the initialization of the Proj object
parseDefs	Parses the PROJ.4 initialization string and sets the associated properties.
deriveConstants	Sets several derived constant values and initialization of datum and ellipse parameters.
Proj4js.Point

Properties

defaultDatum

The datum to use when no others a specified

Functions

transform(source, dest, point)

transform: function( source,
dest,
point )

Transform a point coordinate from one map projection to another. This is really the only public method you should need to use.

Parameters

source	{Proj4js.Proj} source map projection for the transformation
dest	{Proj4js.Proj} destination map projection for the transformation
point	{Object} point to transform, may be geodetic (long, lat) or projected Cartesian (x,y), but should always have x,y properties.

reportError

reportError: function( msg )

An internal method to report errors back to user. Override this in applications to report error messages or throw exceptions.

Private Methods

The following properties and methods are intended for internal use only.

This is a minimal implementation of JavaScript inheritance methods so that Proj4js can be used as a stand-alone library. These are copies of the equivalent OpenLayers methods at v2.7

Summary

Functions and Properties
extend	Copy all properties of a source object to a destination object.
Class	Base class used to construct all other classes.
bind	Bind a function to an object.
defsLookupService	AJAX service to retreive projection definition parameters from
libPath	internal: http server path to library code.
getScriptLocation	Return the path to this script.
loadScript	Load a JS file from a URL into a <script> tag in the page.
checkReadyState	IE workaround since there is no onerror handler.

Functions and Properties

extend

extend: function( destination,
source )

Copy all properties of a source object to a destination object. Modifies the passed in destination object. Any properties on the source object that are set to undefined will not be (re)set on the destination object.

Parameters

destination	{Object} The object that will be modified
source	{Object} The object with properties to be set on the destination

Returns

{Object} The destination object.

Class

Class: function()

Base class used to construct all other classes. Includes support for multiple inheritance.

bind

bind: function( func,
object )

Bind a function to an object. Method to easily create closures with ‘this’ altered.

Parameters

func	{Function} Input function.
object	{Object} The object to bind to the input function (as this).

Returns

{Function} A closure with ‘this’ set to the passed in object.

defsLookupService

AJAX service to retreive projection definition parameters from

libPath

internal: http server path to library code.

getScriptLocation

getScriptLocation: function ()

Return the path to this script.

Returns

Path to this script

loadScript

loadScript: function( url,
onload,
onfail,
loadCheck )

Load a JS file from a URL into a <script> tag in the page.

Parameters

url	{String} The URL containing the script to load
onload	{Function} A method to be executed when the script loads successfully
onfail	{Function} A method to be executed when there is an error loading the script
loadCheck	{Function} A boolean method that checks to see if the script has loaded. Typically this just checks for the existance of an object in the file just loaded.

checkReadyState

checkReadyState: function()

IE workaround since there is no onerror handler. Calls the user defined loadCheck method to determine if the script is loaded.

Proj4js.Proj

Proj objects provide transformation methods for point coordinates between geodetic latitude/longitude and a projected coordinate system. once they have been initialized with a projection code.

Initialization of Proj objects is with a projection code, usually EPSG codes, which is the key that will be used with the Proj4js.defs array.

The code passed in will be stripped of colons and converted to uppercase to locate projection definition files.

A projection object has properties for units and title strings.

Summary

Properties
readyToUse	Flag to indicate if initialization is complete for this Proj object
title	The title to describe the projection
projName	The projection class for this projection, e.g.
units	The units of the projection.
datum	The datum specified for the projection
Functions
initialize	Constructor for Proj4js.Proj objects
loadProjDefinition	Loads the coordinate system initialization string if required.
loadFromService	Creates the REST URL for loading the definition from a web service and loads it.
defsLoaded	Continues the Proj object initilization once the def file is loaded
checkDefsLoaded	This is the loadCheck method to see if the def object exists
defsFailed	Report an error in loading the defs file, but continue on using WGS84
loadProjCode	Loads projection class code dynamically if required.
loadProjCodeSuccess	Loads any proj dependencies or continue on to final initialization.
defsFailed	Report an error in loading the proj file.
checkCodeLoaded	This is the loadCheck method to see if the projection code is loaded
initTransforms	Finalize the initialization of the Proj object
parseDefs	Parses the PROJ.4 initialization string and sets the associated properties.
deriveConstants	Sets several derived constant values and initialization of datum and ellipse parameters.
Proj4js.Point

Properties

readyToUse

Flag to indicate if initialization is complete for this Proj object

title

The title to describe the projection

projName

The projection class for this projection, e.g. lcc (lambert conformal conic, or merc for mercator). These are exactly equivalent to their Proj4 counterparts.

units

The units of the projection. Values include ‘m’ and ‘degrees’

datum

The datum specified for the projection

Functions

initialize

initialize: function( srsCode )

Constructor for Proj4js.Proj objects

Parameters

srsCode

a code for map projection definition parameters. These are usually (but not always) EPSG codes.

loadProjDefinition

loadProjDefinition: function()

Loads the coordinate system initialization string if required. Note that dynamic loading happens asynchronously so an application must wait for the readyToUse property is set to true. To prevent dynamic loading, include the defs through a script tag in your application.

loadFromService

loadFromService: function()

Creates the REST URL for loading the definition from a web service and loads it.

defsLoaded

defsLoaded: function()

Continues the Proj object initilization once the def file is loaded

checkDefsLoaded

checkDefsLoaded: function()

This is the loadCheck method to see if the def object exists

defsFailed

defsFailed: function()

Report an error in loading the defs file, but continue on using WGS84

loadProjCode

loadProjCode: function( projName )

Loads projection class code dynamically if required. Projection code may be included either through a script tag or in a built version of proj4js

loadProjCodeSuccess

loadProjCodeSuccess: function( projName )

Loads any proj dependencies or continue on to final initialization.

defsFailed

Report an error in loading the proj file. Initialization of the Proj object has failed and the readyToUse flag will never be set.

checkCodeLoaded

checkCodeLoaded: function( projName )

This is the loadCheck method to see if the projection code is loaded

initTransforms

initTransforms: function()

Finalize the initialization of the Proj object

parseDefs

parseDefs: function()

Parses the PROJ.4 initialization string and sets the associated properties.

deriveConstants

deriveConstants: function()

Sets several derived constant values and initialization of datum and ellipse parameters.

Proj4js.Point

Parameters

x {float} or {Array} either the first coordinates component or the full coordinates
y {float} the second component
z {float} the third component, optional.