openlayers
Version:
Build tools and sources for developing OpenLayers based mapping applications
475 lines (428 loc) • 16.6 kB
JavaScript
goog.provide('ol.proj');
goog.require('ol');
goog.require('ol.extent');
goog.require('ol.proj.Projection');
goog.require('ol.proj.Units');
goog.require('ol.proj.proj4');
goog.require('ol.proj.projections');
goog.require('ol.proj.transforms');
goog.require('ol.sphere.NORMAL');
/**
* Meters per unit lookup table.
* @const
* @type {Object.<ol.proj.Units, number>}
* @api stable
*/
ol.proj.METERS_PER_UNIT = ol.proj.Units.METERS_PER_UNIT;
if (ol.ENABLE_PROJ4JS) {
/**
* 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);
*
* @param {proj4} proj4 Proj4.
* @api
*/
ol.proj.setProj4 = function(proj4) {
ol.DEBUG && console.assert(typeof proj4 == 'function',
'proj4 argument should be a function');
ol.proj.proj4.set(proj4);
};
}
/**
* 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.
* @param {ol.proj.Projection} projection The projection.
* @param {number} resolution Nominal resolution in projection units.
* @param {ol.Coordinate} point Point to find adjusted resolution at.
* @return {number} Point resolution at point in projection units.
* @api
*/
ol.proj.getPointResolution = function(projection, resolution, point) {
var pointResolution;
var getter = projection.getPointResolutionFunc();
if (getter) {
pointResolution = getter(resolution, point);
} else {
var units = projection.getUnits();
if (units == ol.proj.Units.DEGREES) {
pointResolution = resolution;
} else {
// Estimate point resolution by transforming the center pixel to EPSG:4326,
// measuring its width and height on the normal sphere, and taking the
// average of the width and height.
var toEPSG4326 = ol.proj.getTransformFromProjections(projection, ol.proj.get('EPSG:4326'));
var vertices = [
point[0] - resolution / 2, point[1],
point[0] + resolution / 2, point[1],
point[0], point[1] - resolution / 2,
point[0], point[1] + resolution / 2
];
vertices = toEPSG4326(vertices, vertices, 2);
var width = ol.sphere.NORMAL.haversineDistance(
vertices.slice(0, 2), vertices.slice(2, 4));
var height = ol.sphere.NORMAL.haversineDistance(
vertices.slice(4, 6), vertices.slice(6, 8));
pointResolution = (width + height) / 2;
var metersPerUnit = projection.getMetersPerUnit();
if (metersPerUnit !== undefined) {
pointResolution /= metersPerUnit;
}
}
}
return pointResolution;
};
/**
* Registers transformation functions that don't alter coordinates. Those allow
* to transform between projections with equal meaning.
*
* @param {Array.<ol.proj.Projection>} projections Projections.
* @api
*/
ol.proj.addEquivalentProjections = function(projections) {
ol.proj.addProjections(projections);
projections.forEach(function(source) {
projections.forEach(function(destination) {
if (source !== destination) {
ol.proj.transforms.add(source, destination, ol.proj.cloneTransform);
}
});
});
};
/**
* Registers transformation functions to convert coordinates in any projection
* in projection1 to any projection in projection2.
*
* @param {Array.<ol.proj.Projection>} projections1 Projections with equal
* meaning.
* @param {Array.<ol.proj.Projection>} projections2 Projections with equal
* meaning.
* @param {ol.TransformFunction} forwardTransform Transformation from any
* projection in projection1 to any projection in projection2.
* @param {ol.TransformFunction} inverseTransform Transform from any projection
* in projection2 to any projection in projection1..
*/
ol.proj.addEquivalentTransforms = function(projections1, projections2, forwardTransform, inverseTransform) {
projections1.forEach(function(projection1) {
projections2.forEach(function(projection2) {
ol.proj.transforms.add(projection1, projection2, forwardTransform);
ol.proj.transforms.add(projection2, projection1, inverseTransform);
});
});
};
/**
* Add a Projection object to the list of supported projections that can be
* looked up by their code.
*
* @param {ol.proj.Projection} projection Projection instance.
* @api stable
*/
ol.proj.addProjection = function(projection) {
ol.proj.projections.add(projection.getCode(), projection);
ol.proj.transforms.add(projection, projection, ol.proj.cloneTransform);
};
/**
* @param {Array.<ol.proj.Projection>} projections Projections.
*/
ol.proj.addProjections = function(projections) {
var addedProjections = [];
projections.forEach(function(projection) {
addedProjections.push(ol.proj.addProjection(projection));
});
};
/**
* Clear all cached projections and transforms.
*/
ol.proj.clearAllProjections = function() {
ol.proj.projections.clear();
ol.proj.transforms.clear();
};
/**
* @param {ol.proj.Projection|string|undefined} projection Projection.
* @param {string} defaultCode Default code.
* @return {ol.proj.Projection} Projection.
*/
ol.proj.createProjection = function(projection, defaultCode) {
if (!projection) {
return ol.proj.get(defaultCode);
} else if (typeof projection === 'string') {
return ol.proj.get(projection);
} else {
return /** @type {ol.proj.Projection} */ (projection);
}
};
/**
* 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.
*
* @param {ol.ProjectionLike} source Source projection.
* @param {ol.ProjectionLike} destination Destination projection.
* @param {function(ol.Coordinate): ol.Coordinate} forward The forward transform
* function (that is, from the source projection to the destination
* projection) that takes a {@link ol.Coordinate} as argument and returns
* the transformed {@link ol.Coordinate}.
* @param {function(ol.Coordinate): ol.Coordinate} inverse The inverse transform
* function (that is, from the destination projection to the source
* projection) that takes a {@link ol.Coordinate} as argument and returns
* the transformed {@link ol.Coordinate}.
* @api stable
*/
ol.proj.addCoordinateTransforms = function(source, destination, forward, inverse) {
var sourceProj = ol.proj.get(source);
var destProj = ol.proj.get(destination);
ol.proj.transforms.add(sourceProj, destProj,
ol.proj.createTransformFromCoordinateTransform(forward));
ol.proj.transforms.add(destProj, sourceProj,
ol.proj.createTransformFromCoordinateTransform(inverse));
};
/**
* Creates a {@link ol.TransformFunction} from a simple 2D coordinate transform
* function.
* @param {function(ol.Coordinate): ol.Coordinate} transform Coordinate
* transform.
* @return {ol.TransformFunction} Transform function.
*/
ol.proj.createTransformFromCoordinateTransform = function(transform) {
return (
/**
* @param {Array.<number>} input Input.
* @param {Array.<number>=} opt_output Output.
* @param {number=} opt_dimension Dimension.
* @return {Array.<number>} Output.
*/
function(input, opt_output, opt_dimension) {
var length = input.length;
var dimension = opt_dimension !== undefined ? opt_dimension : 2;
var output = opt_output !== undefined ? opt_output : new Array(length);
var point, i, j;
for (i = 0; i < length; i += dimension) {
point = transform([input[i], input[i + 1]]);
output[i] = point[0];
output[i + 1] = point[1];
for (j = dimension - 1; j >= 2; --j) {
output[i + j] = input[i + j];
}
}
return output;
});
};
/**
* Transforms a coordinate from longitude/latitude to a different projection.
* @param {ol.Coordinate} coordinate Coordinate as longitude and latitude, i.e.
* an array with longitude as 1st and latitude as 2nd element.
* @param {ol.ProjectionLike=} opt_projection Target projection. The
* default is Web Mercator, i.e. 'EPSG:3857'.
* @return {ol.Coordinate} Coordinate projected to the target projection.
* @api stable
*/
ol.proj.fromLonLat = function(coordinate, opt_projection) {
return ol.proj.transform(coordinate, 'EPSG:4326',
opt_projection !== undefined ? opt_projection : 'EPSG:3857');
};
/**
* Transforms a coordinate to longitude/latitude.
* @param {ol.Coordinate} coordinate Projected coordinate.
* @param {ol.ProjectionLike=} opt_projection Projection of the coordinate.
* The default is Web Mercator, i.e. 'EPSG:3857'.
* @return {ol.Coordinate} Coordinate as longitude and latitude, i.e. an array
* with longitude as 1st and latitude as 2nd element.
* @api stable
*/
ol.proj.toLonLat = function(coordinate, opt_projection) {
return ol.proj.transform(coordinate,
opt_projection !== undefined ? opt_projection : 'EPSG:3857', 'EPSG:4326');
};
/**
* Fetches a Projection object for the code specified.
*
* @param {ol.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 object, or null if not in list.
* @api stable
*/
ol.proj.get = function(projectionLike) {
var projection = null;
if (projectionLike instanceof ol.proj.Projection) {
projection = projectionLike;
} else if (typeof projectionLike === 'string') {
var code = projectionLike;
projection = ol.proj.projections.get(code);
if (ol.ENABLE_PROJ4JS) {
var proj4js = ol.proj.proj4.get();
if (!projection && typeof proj4js == 'function' &&
proj4js.defs(code) !== undefined) {
projection = new ol.proj.Projection({code: code});
ol.proj.addProjection(projection);
}
}
}
return projection;
};
/**
* 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.
*
* @param {ol.proj.Projection} projection1 Projection 1.
* @param {ol.proj.Projection} projection2 Projection 2.
* @return {boolean} Equivalent.
* @api
*/
ol.proj.equivalent = function(projection1, projection2) {
if (projection1 === projection2) {
return true;
}
var equalUnits = projection1.getUnits() === projection2.getUnits();
if (projection1.getCode() === projection2.getCode()) {
return equalUnits;
} else {
var transformFn = ol.proj.getTransformFromProjections(
projection1, projection2);
return transformFn === ol.proj.cloneTransform && equalUnits;
}
};
/**
* 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.ProjectionLike} source Source.
* @param {ol.ProjectionLike} destination Destination.
* @return {ol.TransformFunction} Transform function.
* @api stable
*/
ol.proj.getTransform = function(source, destination) {
var sourceProjection = ol.proj.get(source);
var destinationProjection = ol.proj.get(destination);
return ol.proj.getTransformFromProjections(
sourceProjection, destinationProjection);
};
/**
* 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 object.
* @param {ol.proj.Projection} destinationProjection Destination Projection
* object.
* @return {ol.TransformFunction} Transform function.
*/
ol.proj.getTransformFromProjections = function(sourceProjection, destinationProjection) {
var sourceCode = sourceProjection.getCode();
var destinationCode = destinationProjection.getCode();
var transform = ol.proj.transforms.get(sourceCode, destinationCode);
if (ol.ENABLE_PROJ4JS && !transform) {
var proj4js = ol.proj.proj4.get();
if (typeof proj4js == 'function') {
var sourceDef = proj4js.defs(sourceCode);
var destinationDef = proj4js.defs(destinationCode);
if (sourceDef !== undefined && destinationDef !== undefined) {
if (sourceDef === destinationDef) {
ol.proj.addEquivalentProjections([destinationProjection, sourceProjection]);
} else {
var proj4Transform = proj4js(destinationCode, sourceCode);
ol.proj.addCoordinateTransforms(destinationProjection, sourceProjection,
proj4Transform.forward, proj4Transform.inverse);
}
transform = ol.proj.transforms.get(sourceCode, destinationCode);
}
}
}
if (!transform) {
ol.DEBUG && console.assert(transform, 'transform should be defined');
transform = ol.proj.identityTransform;
}
return transform;
};
/**
* @param {Array.<number>} input Input coordinate array.
* @param {Array.<number>=} opt_output Output array of coordinate values.
* @param {number=} opt_dimension Dimension.
* @return {Array.<number>} Input coordinate array (same array as input).
*/
ol.proj.identityTransform = function(input, opt_output, opt_dimension) {
if (opt_output !== undefined && input !== opt_output) {
// TODO: consider making this a warning instead
ol.DEBUG && console.assert(false, 'This should not be used internally.');
for (var i = 0, ii = input.length; i < ii; ++i) {
opt_output[i] = input[i];
}
input = opt_output;
}
return input;
};
/**
* @param {Array.<number>} input Input coordinate array.
* @param {Array.<number>=} opt_output Output array of coordinate values.
* @param {number=} opt_dimension Dimension.
* @return {Array.<number>} Output coordinate array (new array, same coordinate
* values).
*/
ol.proj.cloneTransform = function(input, opt_output, opt_dimension) {
var output;
if (opt_output !== undefined) {
for (var i = 0, ii = input.length; i < ii; ++i) {
opt_output[i] = input[i];
}
output = opt_output;
} else {
output = input.slice();
}
return output;
};
/**
* Transforms a coordinate from source projection to destination projection.
* This returns a new coordinate (and does not modify the original).
*
* See {@link ol.proj.transformExtent} for extent transformation.
* See the transform method of {@link ol.geom.Geometry} and its subclasses for
* geometry transforms.
*
* @param {ol.Coordinate} coordinate Coordinate.
* @param {ol.ProjectionLike} source Source projection-like.
* @param {ol.ProjectionLike} destination Destination projection-like.
* @return {ol.Coordinate} Coordinate.
* @api stable
*/
ol.proj.transform = function(coordinate, source, destination) {
var transformFn = ol.proj.getTransform(source, destination);
return transformFn(coordinate, undefined, coordinate.length);
};
/**
* Transforms an extent from source projection to destination projection. This
* returns a new extent (and does not modify the original).
*
* @param {ol.Extent} extent The extent to transform.
* @param {ol.ProjectionLike} source Source projection-like.
* @param {ol.ProjectionLike} destination Destination projection-like.
* @return {ol.Extent} The transformed extent.
* @api stable
*/
ol.proj.transformExtent = function(extent, source, destination) {
var transformFn = ol.proj.getTransform(source, destination);
return ol.extent.applyTransform(extent, transformFn);
};
/**
* Transforms the given point to the destination projection.
*
* @param {ol.Coordinate} point Point.
* @param {ol.proj.Projection} sourceProjection Source projection.
* @param {ol.proj.Projection} destinationProjection Destination projection.
* @return {ol.Coordinate} Point.
*/
ol.proj.transformWithProjections = function(point, sourceProjection, destinationProjection) {
var transformFn = ol.proj.getTransformFromProjections(
sourceProjection, destinationProjection);
return transformFn(point);
};