OpenLayers v4.0.1 API - Namespace: proj

# Namespace: proj

This documentation is for OpenLayers v4.0.1. The latest is v.

## ol.proj

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 https://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

Projection

### 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.js, line 200

  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.ProjectionLike | Source projection.
  `destination` | ol.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 transformed `ol.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 transformed `ol.Coordinate`.

#### ol.proj.addEquivalentProjections(projections)

src/ol/proj.js, line 97

  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.js, line 139

  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.equivalent(projection1, projection2){boolean}

src/ol/proj.js, line 312

  Checks if two projections are the same, that is every coordinate in one projection does represent the same geographic point as the same coordinate in the other projection.

  Name | Type | Description
  --- | --- | ---
  `projection1` | ol.proj.Projection | Projection 1.
  `projection2` | ol.proj.Projection | Projection 2.

  ##### Returns:

  Equivalent.

#### ol.proj.fromLonLat(coordinate, opt_projection){ol.Coordinate}

src/ol/proj.js, line 252

  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.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.js, line 282

  Fetches a Projection object for the code specified.

  Name | Type | Description
  --- | --- | ---
  `projectionLike` | ol.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.getPointResolution(projection, resolution, point){number}

src/ol/proj.js, line 54

  Get the resolution of the point in degrees or distance units. For projections with degrees as the unit this will simply return the provided resolution. For other projections the point resolution is estimated by transforming the 'point' pixel to EPSG:4326, measuring its width and height on the normal sphere, and taking the average of the width and height.

  Name | Type | Description
  --- | --- | ---
  `projection` | ol.proj.Projection | The projection.
  `resolution` | number | Nominal resolution in projection units.
  `point` | ol.Coordinate | Point to find adjusted resolution at.

  ##### Returns:

  Point resolution at point in projection units.

#### ol.proj.getTransform(source, destination){ol.TransformFunction}

src/ol/proj.js, line 337

  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.ProjectionLike | Source.
  `destination` | ol.ProjectionLike | Destination.

  ##### Returns:

  Transform function.

#### ol.proj.setProj4(proj4)

src/ol/proj.js, line 35

  Register proj4. If not explicitly registered, it will be assumed that proj4js will be loaded in the global namespace. For example in a browserify ES6 environment you could use:

      import ol from 'openlayers';
      import proj4 from 'proj4';
      ol.proj.setProj4(proj4);

  Name | Type | Description
  --- | --- | ---
  `proj4` | proj4 | Proj4.

#### ol.proj.toLonLat(coordinate, opt_projection){ol.Coordinate}

src/ol/proj.js, line 267

  Transforms a coordinate to longitude/latitude.

  Name | Type | Description
  --- | --- | ---
  `coordinate` | ol.Coordinate | Projected coordinate.
  `projection` | ol.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.js, line 435

  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 of `ol.geom.Geometry` and its subclasses for geometry transforms.

  Name | Type | Description
  --- | --- | ---
  `coordinate` | ol.Coordinate | Coordinate.
  `source` | ol.ProjectionLike | Source projection-like.
  `destination` | ol.ProjectionLike | Destination projection-like.

  ##### Returns:

  Coordinate.

#### ol.proj.transformExtent(extent, source, destination){ol.Extent}

src/ol/proj.js, line 451

  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.ProjectionLike | Source projection-like.
  `destination` | ol.ProjectionLike | Destination projection-like.

  ##### Returns:

  The transformed extent.

### Type Definitions

#### ol.proj.Units{string}

  Projection units: `'degrees'`, `'ft'`, `'m'`, `'pixels'`, `'tile-pixels'` or `'us-ft'`.