# 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.
adjust_axis | Normalize or de-normalized the x/y/z axes.
reportError | An internal method to report errors back to user.
Private Methods | The following properties and methods are intended for internal use only.
Functions |
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.
Properties |
scriptName | {String} The filename of this script without any path.
defsLookupService | AJAX service to retreive projection definition parameters from
libPath | internal: http server path to library code.
Functions |
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
x0 | The x coordinate origin
y0 | The y coordinate origin
localCS | Flag to indicate if the projection is a local one in which no transforms are required.
queue | Buffer (FIFO) to hold callbacks waiting to be called when projection loaded.
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
parseWKT | Parses a WKT string to get initialization parameters
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.

### adjust_axis

> adjust_axis: function( | crs,
> | denorm,
> | point | )

Normalize or de-normalized the x/y/z axes. The normal form is “enu” (easting, northing, up). Parameters: crs {Proj4js.Proj} the coordinate reference system denorm {Boolean} when false, normalize point {Object} the coordinates to adjust

### 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 |
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.
Properties |
scriptName | {String} The filename of this script without any path.
defsLookupService | AJAX service to retreive projection definition parameters from
libPath | internal: http server path to library code.
Functions |
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

### 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.

### Properties

### scriptName

{String} The filename of this script without any path.

### defsLookupService

AJAX service to retreive projection definition parameters from

### libPath

internal: http server path to library code.

### Functions

### 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
x0 | The x coordinate origin
y0 | The y coordinate origin
localCS | Flag to indicate if the projection is a local one in which no transforms are required.
queue | Buffer (FIFO) to hold callbacks waiting to be called when projection loaded.
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
parseWKT | Parses a WKT string to get initialization parameters
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

### x0

The x coordinate origin

### y0

The y coordinate origin

### localCS

Flag to indicate if the projection is a local one in which no transforms are required.

### queue

Buffer (FIFO) to hold callbacks waiting to be called when projection loaded.

### Functions

### initialize

> initialize: function( | srsCode,
> | callback | )

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

### parseWKT

> wktRE: /^( | \w+ | )\[(.*)\]$/, parseWKT: function(wkt)

Parses a WKT string to get initialization parameters

### 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.

> transform: function( | source,
> | dest,
> | point | )

Transform a point coordinate from one map projection to another.

> adjust_axis: function( | crs,
> | denorm,
> | point | )

Normalize or de-normalized the x/y/z axes.

> reportError: function( | msg | )

An internal method to report errors back to user.

> extend: function( | destination,
> | source | )

Copy all properties of a source object to a destination object.

> Class: function()

Base class used to construct all other classes.

> bind: function( | func,
> | object | )

Bind a function to an object.

> getScriptLocation: function ()

Return the path to this script.

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

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

> checkReadyState: function()

IE workaround since there is no onerror handler.

> initialize: function( | srsCode,
> | callback | )

Constructor for Proj4js.Proj objects

> loadProjDefinition: function()

Loads the coordinate system initialization string if required.

> loadFromService: function()

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

> defsLoaded: function()

Continues the Proj object initilization once the def file is loaded

> checkDefsLoaded: function()

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

> defsFailed: function()

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

> loadProjCode: function( | projName | )

Loads projection class code dynamically if required.

> loadProjCodeSuccess: function( | projName | )

Loads any proj dependencies or continue on to final initialization.

> checkCodeLoaded: function( | projName | )

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

> initTransforms: function()

Finalize the initialization of the Proj object

> wktRE: /^( | \w+ | )\[(.*)\]$/, parseWKT: function(wkt)

Parses a WKT string to get initialization parameters

> parseDefs: function()

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

> deriveConstants: function()

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