All coordinates and extents need to be provided in view projection (default: [EPSG:3857](ol.proj.EPSG3857.html)). To transform, use [ol.proj.transform()](ol.proj.html#transform) and [ol.extent.applyTransform()](ol.extent.html#applyTransform).
[ol.proj](ol.proj.html) |
[Objects](ol.Object.html) can be kept in sync using the [bindTo()](ol.Object.html#bindTo) method.
A [DOM Input](ol.dom.Input.html) class is available to bind Object properties to HTML Input elements. |
diff --git a/src/ol/geom/geometry.js b/src/ol/geom/geometry.js
index d6b2e27b61..d7ca7fd2a1 100644
--- a/src/ol/geom/geometry.js
+++ b/src/ol/geom/geometry.js
@@ -167,6 +167,8 @@ ol.geom.Geometry.prototype.getType = goog.abstractMethod;
/**
* Apply a transform function to the geometry. Modifies the geometry in place.
+ * If you do not want the geometry modified in place, first clone() it and
+ * then use this function on the clone.
* @function
* @param {ol.TransformFunction} transformFn Transform.
* @todo api
@@ -177,6 +179,8 @@ ol.geom.Geometry.prototype.applyTransform = goog.abstractMethod;
/**
* Transform a geometry from one coordinate reference system to another.
* Modifies the geometry in place.
+ * If you do not want the geometry modified in place, first clone() it and
+ * then use this function on the clone.
*
* @param {ol.proj.ProjectionLike} source The current projection. Can be a
* string identifier or a {@link ol.proj.Projection} object.
diff --git a/src/ol/proj/epsg4326projection.js b/src/ol/proj/epsg4326projection.js
index ae5cb5e43e..0290992845 100644
--- a/src/ol/proj/epsg4326projection.js
+++ b/src/ol/proj/epsg4326projection.js
@@ -10,6 +10,10 @@ goog.require('ol.proj.Units');
* @classdesc
* Projection object for WGS84 geographic coordinates (EPSG:4326).
*
+ * Note that OpenLayers does not strictly comply with the EPSG definition.
+ * The EPSG registry defines 4326 as a CRS for Latitude,Longitude (y,x).
+ * OpenLayers treats EPSG:4326 as a pseudo-projection, with x,y coordinates.
+ *
* @constructor
* @extends {ol.proj.Projection}
* @param {string} code Code.
diff --git a/src/ol/proj/proj.js b/src/ol/proj/proj.js
index 99f1028c14..caedc2a735 100644
--- a/src/ol/proj/proj.js
+++ b/src/ol/proj/proj.js
@@ -381,7 +381,9 @@ ol.proj.addProj4jsProjection_ = function(proj4jsProjection) {
/**
- * @param {ol.proj.Projection} projection Projection.
+ * Add a Projection object to the list of supported projections.
+ *
+ * @param {ol.proj.Projection} projection Projection object.
* @todo api
*/
ol.proj.addProjection = function(projection) {
@@ -476,10 +478,12 @@ ol.proj.removeTransform = function(source, destination) {
/**
+ * Fetches a Projection object for the code specified.
+ *
* @param {ol.proj.ProjectionLike} projectionLike Either a code string which is
* a combination of authority and identifier such as "EPSG:4326", or an
* existing projection object, or undefined.
- * @return {ol.proj.Projection} Projection.
+ * @return {ol.proj.Projection} Projection object, or null if not in list.
* @todo api
*/
ol.proj.get = function(projectionLike) {
@@ -555,13 +559,13 @@ ol.proj.equivalent = function(projection1, projection2) {
/**
- * Given the projection-like objects this method searches for a transformation
+ * Given the projection-like objects, searches for a transformation
* function to convert a coordinates array from the source projection to the
* destination projection.
*
* @param {ol.proj.ProjectionLike} source Source.
* @param {ol.proj.ProjectionLike} destination Destination.
- * @return {ol.TransformFunction} Transform.
+ * @return {ol.TransformFunction} Transform function.
* @todo api
*/
ol.proj.getTransform = function(source, destination) {
@@ -573,12 +577,13 @@ ol.proj.getTransform = function(source, destination) {
/**
- * Searches a function that can be used to convert coordinates from the source
- * projection to the destination projection.
+ * Searches in the list of transform functions for the function for converting
+ * coordinates from the source projection to the destination projection.
*
- * @param {ol.proj.Projection} sourceProjection Source projection.
- * @param {ol.proj.Projection} destinationProjection Destination projection.
- * @return {ol.TransformFunction} Transform.
+ * @param {ol.proj.Projection} sourceProjection Source Projection object.
+ * @param {ol.proj.Projection} destinationProjection Destination Projection
+ * object.
+ * @return {ol.TransformFunction} Transform function.
*/
ol.proj.getTransformFromProjections =
function(sourceProjection, destinationProjection) {
@@ -694,15 +699,20 @@ ol.proj.cloneTransform = function(input, opt_output, opt_dimension) {
/**
- * @param {ol.Coordinate} point Point.
- * @param {ol.proj.ProjectionLike} source Source.
- * @param {ol.proj.ProjectionLike} destination Destination.
- * @return {ol.Coordinate} Point.
+ * Transforms a coordinate from source projection to destination projection.
+ * See {@link ol.extent.applyTransform} for extent transformation.
+ * See the applyTransform method of {@link ol.geom.SimpleGeometry} and its
+ * subclasses for geometry transforms.
+ *
+ * @param {ol.Coordinate} coordinate Coordinate.
+ * @param {ol.proj.ProjectionLike} source Source projection-like.
+ * @param {ol.proj.ProjectionLike} destination Destination projection-like.
+ * @return {ol.Coordinate} Coordinate.
* @todo api
*/
-ol.proj.transform = function(point, source, destination) {
+ol.proj.transform = function(coordinate, source, destination) {
var transformFn = ol.proj.getTransform(source, destination);
- return transformFn(point);
+ return transformFn(coordinate);
};
diff --git a/src/ol/proj/proj.jsdoc b/src/ol/proj/proj.jsdoc
index 2b4b835bfa..3ad7f172f3 100644
--- a/src/ol/proj/proj.jsdoc
+++ b/src/ol/proj/proj.jsdoc
@@ -1,3 +1,18 @@
/**
+ * The ol.proj namespace stores:
+ * * a list of {@link 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.
+ *
* @namespace ol.proj
*/