/** * @module ol/proj */ import Sphere from './Sphere.js'; import {applyTransform} from './extent.js'; import math from './math.js'; import EPSG3857 from './proj/EPSG3857.js'; import EPSG4326 from './proj/EPSG4326.js'; import Projection from './proj/Projection.js'; import Units from './proj/Units.js'; import _ol_proj_projections_ from './proj/projections.js'; import {add as addTransformFunc, clear as clearTransformFuncs, get as getTransformFunc} from './proj/transforms.js'; /** * Meters per unit lookup table. * @const * @type {Object.} * @api */ export var METERS_PER_UNIT = Units.METERS_PER_UNIT; /** * A place to store the mean radius of the Earth. * @type {ol.Sphere} */ var SPHERE = new Sphere(Sphere.DEFAULT_RADIUS); /** * @param {Array.} input Input coordinate array. * @param {Array.=} opt_output Output array of coordinate values. * @param {number=} opt_dimension Dimension. * @return {Array.} Output coordinate array (new array, same coordinate * values). */ export function cloneTransform(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; } /** * @param {Array.} input Input coordinate array. * @param {Array.=} opt_output Output array of coordinate values. * @param {number=} opt_dimension Dimension. * @return {Array.} Input coordinate array (same array as input). */ export function identityTransform(input, opt_output, opt_dimension) { if (opt_output !== undefined && input !== opt_output) { for (var i = 0, ii = input.length; i < ii; ++i) { opt_output[i] = input[i]; } input = opt_output; } return input; } /** * 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 */ export function addProjection(projection) { _ol_proj_projections_.add(projection.getCode(), projection); addTransformFunc(projection, projection, cloneTransform); } /** * @param {Array.} projections Projections. */ export function addProjections(projections) { projections.forEach(addProjection); } /** * 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 */ export function get(projectionLike) { var projection = null; if (projectionLike instanceof Projection) { projection = projectionLike; } else if (typeof projectionLike === 'string') { var code = projectionLike; projection = _ol_proj_projections_.get(code); } return projection; } /** * 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 * by default 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. * A custom function can be provided for a specific projection, either * by setting the `getPointResolution` option in the * {@link ol.proj.Projection} constructor or by using * {@link ol.proj.Projection#setGetPointResolution} to change an existing * projection object. * @param {ol.ProjectionLike} projection The projection. * @param {number} resolution Nominal resolution in projection units. * @param {ol.Coordinate} point Point to find adjusted resolution at. * @param {ol.proj.Units=} opt_units Units to get the point resolution in. * Default is the projection's units. * @return {number} Point resolution. * @api */ export function getPointResolution(projection, resolution, point, opt_units) { projection = get(projection); var pointResolution; var getter = projection.getPointResolutionFunc(); if (getter) { pointResolution = getter(resolution, point); } else { var units = projection.getUnits(); if (units == Units.DEGREES && !opt_units || opt_units == 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 = getTransformFromProjections(projection, 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 = SPHERE.haversineDistance( vertices.slice(0, 2), vertices.slice(2, 4)); var height = SPHERE.haversineDistance( vertices.slice(4, 6), vertices.slice(6, 8)); pointResolution = (width + height) / 2; var metersPerUnit = opt_units ? Units.METERS_PER_UNIT[opt_units] : 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.} projections Projections. * @api */ export function addEquivalentProjections(projections) { addProjections(projections); projections.forEach(function(source) { projections.forEach(function(destination) { if (source !== destination) { addTransformFunc(source, destination, cloneTransform); } }); }); } /** * Registers transformation functions to convert coordinates in any projection * in projection1 to any projection in projection2. * * @param {Array.} projections1 Projections with equal * meaning. * @param {Array.} 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.. */ export function addEquivalentTransforms(projections1, projections2, forwardTransform, inverseTransform) { projections1.forEach(function(projection1) { projections2.forEach(function(projection2) { addTransformFunc(projection1, projection2, forwardTransform); addTransformFunc(projection2, projection1, inverseTransform); }); }); } /** * Clear all cached projections and transforms. */ export function clearAllProjections() { _ol_proj_projections_.clear(); clearTransformFuncs(); } /** * @param {ol.proj.Projection|string|undefined} projection Projection. * @param {string} defaultCode Default code. * @return {ol.proj.Projection} Projection. */ export function createProjection(projection, defaultCode) { if (!projection) { return get(defaultCode); } else if (typeof projection === 'string') { return get(projection); } else { return /** @type {ol.proj.Projection} */ (projection); } } /** * Creates a {@link ol.TransformFunction} from a simple 2D coordinate transform * function. * @param {function(ol.Coordinate): ol.Coordinate} coordTransform Coordinate * transform. * @return {ol.TransformFunction} Transform function. */ export function createTransformFromCoordinateTransform(coordTransform) { return ( /** * @param {Array.} input Input. * @param {Array.=} opt_output Output. * @param {number=} opt_dimension Dimension. * @return {Array.} 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 = coordTransform([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; }); } /** * 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 */ export function addCoordinateTransforms(source, destination, forward, inverse) { var sourceProj = get(source); var destProj = get(destination); addTransformFunc(sourceProj, destProj, createTransformFromCoordinateTransform(forward)); addTransformFunc(destProj, sourceProj, createTransformFromCoordinateTransform(inverse)); } /** * 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 */ export function fromLonLat(coordinate, opt_projection) { return 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 */ export function toLonLat(coordinate, opt_projection) { var lonLat = transform(coordinate, opt_projection !== undefined ? opt_projection : 'EPSG:3857', 'EPSG:4326'); var lon = lonLat[0]; if (lon < -180 || lon > 180) { lonLat[0] = math.modulo(lon + 180, 360) - 180; } return lonLat; } /** * 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 */ export function equivalent(projection1, projection2) { if (projection1 === projection2) { return true; } var equalUnits = projection1.getUnits() === projection2.getUnits(); if (projection1.getCode() === projection2.getCode()) { return equalUnits; } else { var transformFunc = getTransformFromProjections(projection1, projection2); return transformFunc === cloneTransform && equalUnits; } } /** * 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. */ export function getTransformFromProjections(sourceProjection, destinationProjection) { var sourceCode = sourceProjection.getCode(); var destinationCode = destinationProjection.getCode(); var transformFunc = getTransformFunc(sourceCode, destinationCode); if (!transformFunc) { transformFunc = identityTransform; } return transformFunc; } /** * 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 */ export function getTransform(source, destination) { var sourceProjection = get(source); var destinationProjection = get(destination); return getTransformFromProjections( sourceProjection, destinationProjection); } /** * 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 */ export function transform(coordinate, source, destination) { var transformFunc = getTransform(source, destination); return transformFunc(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 */ export function transformExtent(extent, source, destination) { var transformFunc = getTransform(source, destination); return applyTransform(extent, transformFunc); } /** * 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. */ export function transformWithProjections(point, sourceProjection, destinationProjection) { var transformFunc = getTransformFromProjections( sourceProjection, destinationProjection); return transformFunc(point); } /** * Add transforms to and from EPSG:4326 and EPSG:3857. This function is called * by when this module is executed and should only need to be called again after * `clearAllProjections()` is called (e.g. in tests). */ export function addCommon() { // Add transformations that don't alter coordinates to convert within set of // projections with equal meaning. addEquivalentProjections(EPSG3857.PROJECTIONS); addEquivalentProjections(EPSG4326.PROJECTIONS); // Add transformations to convert EPSG:4326 like coordinates to EPSG:3857 like // coordinates and back. addEquivalentTransforms( EPSG4326.PROJECTIONS, EPSG3857.PROJECTIONS, EPSG3857.fromEPSG4326, EPSG3857.toEPSG4326); } addCommon();