The ol.proj namespace stores:
- a list of
ol.proj.Projection
objects, one for each projection supported by the application - a list of transform functions needed to convert coordinates in one projection into another.
The static functions are the methods used to maintain these. Each transform function can handle not only simple coordinate pairs, but also large arrays of coordinates such as vector geometries.
When loaded, the library adds projection objects for EPSG:4326 (WGS84 geographic coordinates) and EPSG:3857 (Web or Spherical Mercator, as used for example by Bing Maps or OpenStreetMap), together with the relevant transform functions.
Additional transforms may be added by using the http://proj4js.org/
library (version 2.2 or later). You can use the full build supplied by
Proj4js, or create a custom build to support those projections you need; see
the Proj4js website for how to do this. You also need the Proj4js definitions
for the required projections. These definitions can be obtained from
http://epsg.io/, and are a JS function, so can be loaded in a script
tag (as in the examples) or pasted into your application.
The first time there is a request for a projection, either with a
ol.proj.projectionLike
or directly with ol.proj.get
, the
code will check if the Proj4js library and the necessary definition are
loaded; if so, it will register the appropriate ol.proj.Projection
object and add transform functions between the new projection and all the
existing ones. See examples/wms-image-custom-proj for an example of this.
Because the check for presence of the Proj4js library and the definition only
takes place on the first request for them, this means they can be loaded
dynamically as needed; for example, with user-supplied data where you don't
know in advance what projections are needed, you can initially load minimal
support and then load whichever are requested.
Note that Proj4js does not support projection extents. If you want to add
one for creating default tile grids, you can add it after the Projection
object has been created with setExtent
, for example,
ol.proj.get('EPSG:1234').setExtent(extent)
.
In addition to Proj4js support, any transform functions can be added with
ol.proj.addCoordinateTransforms
. To use this, you must first create
a ol.proj.Projection
object for the new projection and add it with
ol.proj.addProjection
. You can then add the forward and inverse
functions with ol.proj.addCoordinateTransforms
. See
examples/wms-custom-proj for an example of this.
Note that if no transforms are needed and you only need to define the
projection, just add a ol.proj.Projection
with
ol.proj.addProjection
. See examples/wms-no-proj for an example of
this.
Classes
Members
-
ol.proj.METERS_PER_UNIT{Object.<ol.proj.Units, number>}
-
Meters per unit lookup table.
Methods
-
ol.proj.addCoordinateTransforms(source, destination, forward, inverse)
src/ol/proj/proj.js, line 535 -
Registers coordinate transform functions to convert coordinates between the source projection and the destination projection. The forward and inverse functions convert coordinate pairs; this function converts these into the functions used internally which also handle extents and coordinate arrays.
Name Type Description source
ol.proj.ProjectionLike Source projection.
destination
ol.proj.ProjectionLike Destination projection.
forward
function The forward transform function (that is, from the source projection to the destination projection) that takes a
ol.Coordinate
as argument and returns the transformedol.Coordinate
.inverse
function The inverse transform function (that is, from the destination projection to the source projection) that takes a
ol.Coordinate
as argument and returns the transformedol.Coordinate
. -
ol.proj.addEquivalentProjections(projections) experimental
src/ol/proj/proj.js, line 410 -
Registers transformation functions that don't alter coordinates. Those allow to transform between projections with equal meaning.
Name Type Description projections
Array.<ol.proj.Projection> Projections.
-
ol.proj.addProjection(projection)
src/ol/proj/proj.js, line 453 -
Add a Projection object to the list of supported projections that can be looked up by their code.
Name Type Description projection
ol.proj.Projection Projection instance.
-
ol.proj.fromLonLat(coordinate, opt_projection){ol.Coordinate}
src/ol/proj/proj.js, line 615 -
Transforms a coordinate from longitude/latitude to a different projection.
Name Type Description coordinate
ol.Coordinate Coordinate as longitude and latitude, i.e. an array with longitude as 1st and latitude as 2nd element.
projection
ol.proj.ProjectionLike Target projection. The default is Web Mercator, i.e. 'EPSG:3857'.
Returns:
Coordinate projected to the target projection.
-
ol.proj.get(projectionLike){ol.proj.Projection}
src/ol/proj/proj.js, line 645 -
Fetches a Projection object for the code specified.
Name Type Description projectionLike
ol.proj.ProjectionLike Either a code string which is a combination of authority and identifier such as "EPSG:4326", or an existing projection object, or undefined.
Returns:
Projection object, or null if not in list.
-
ol.proj.getTransform(source, destination){ol.TransformFunction}
src/ol/proj/proj.js, line 698 -
Given the projection-like objects, searches for a transformation function to convert a coordinates array from the source projection to the destination projection.
Name Type Description source
ol.proj.ProjectionLike Source.
destination
ol.proj.ProjectionLike Destination.
Returns:
Transform function.
-
ol.proj.toLonLat(coordinate, opt_projection){ol.Coordinate}
src/ol/proj/proj.js, line 630 -
Transforms a coordinate to longitude/latitude.
Name Type Description coordinate
ol.Coordinate Projected coordinate.
projection
ol.proj.ProjectionLike Projection of the coordinate. The default is Web Mercator, i.e. 'EPSG:3857'.
Returns:
Coordinate as longitude and latitude, i.e. an array with longitude as 1st and latitude as 2nd element.
-
ol.proj.transform(coordinate, source, destination){ol.Coordinate}
src/ol/proj/proj.js, line 787 -
Transforms a coordinate from source projection to destination projection. This returns a new coordinate (and does not modify the original).
See
ol.proj.transformExtent
for extent transformation. See the transform method ofol.geom.Geometry
and its subclasses for geometry transforms.Name Type Description coordinate
ol.Coordinate Coordinate.
source
ol.proj.ProjectionLike Source projection-like.
destination
ol.proj.ProjectionLike Destination projection-like.
Returns:
Coordinate.
-
ol.proj.transformExtent(extent, source, destination){ol.Extent}
src/ol/proj/proj.js, line 803 -
Transforms an extent from source projection to destination projection. This returns a new extent (and does not modify the original).
Name Type Description extent
ol.Extent The extent to transform.
source
ol.proj.ProjectionLike Source projection-like.
destination
ol.proj.ProjectionLike Destination projection-like.
Returns:
The transformed extent.
Type Definitions
-
ol.proj.ProjectionLike{ol.proj.Projection} {string} {undefined}
-
A projection as
ol.proj.Projection
, SRS identifier string or undefined. -
ol.proj.Units{string}
-
Projection units:
'degrees'
,'ft'
,'m'
,'pixels'
, or'us-ft'
.