Lib
Widgets
Index

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
x0
The x coordinate origin
y0
The y coordinate origin
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
This implementation assumes a Spherical Earth.  The (commented) code
has been included for the ellipsoidal forward transform, but derivation of the ellispoidal inverse transform is beyond me.

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
x0
The x coordinate origin
y0
The y coordinate origin
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
This implementation assumes a Spherical Earth.  The (commented) code
has been included for the ellipsoidal forward transform, but derivation of the ellispoidal inverse transform is beyond me.

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

Functions

initialize

initialize: function(srsCode)

Constructor for Proj4js.Proj objects

Parameters

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

This implementation assumes a Spherical Earth.  The (commented) code

has been included for the ellipsoidal forward transform, but derivation of the ellispoidal inverse transform is beyond me.  Note that most of the Proj4JS implementations do NOT currently support ellipsoidal figures.  Therefore this is not seen as a problem - especially this lack of support is explicitly stated here.

ALGORITHM REFERENCES

1.  “Cartographic Projection Procedures for the UNIX Environment - A User’s Manual” by Gerald I.  Evenden, USGS Open File Report 90-284 and Release 4 Interim Reports (2003)

2.  Snyder, John P., “Flattening the EarthTwo Thousand Years of Map Projections”, Univ.  Chicago Press, 1993
Generated by Natural Docs
transform: function(source,
dest,
point)
Transform a point coordinate from one map projection to another.
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)
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
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.