UNPKG

openlayers

Version:

Build tools and sources for developing OpenLayers based mapping applications

475 lines (428 loc) 16.6 kB
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); };