diff --git a/examples/edit-geographic.html b/examples/edit-geographic.html
index 02131724be..3f66d462ba 100644
--- a/examples/edit-geographic.html
+++ b/examples/edit-geographic.html
@@ -7,7 +7,6 @@ docs: >
makes it so the map view uses geographic coordinates (even if the view projection is
not geographic).
tags: "geographic"
-experimental: true
---
diff --git a/examples/geographic.html b/examples/geographic.html
index 77349d450d..8dc9fc1aeb 100644
--- a/examples/geographic.html
+++ b/examples/geographic.html
@@ -7,7 +7,6 @@ docs: >
makes it so the map view uses geographic coordinates (even if the view projection is
not geographic).
tags: "geographic"
-experimental: true
resources:
- https://code.jquery.com/jquery-3.5.1.min.js
- https://maxcdn.bootstrapcdn.com/bootstrap/4.5.0/css/bootstrap.min.css
diff --git a/examples/immediate-geographic.html b/examples/immediate-geographic.html
index 0a9a9ec44f..2683857e27 100644
--- a/examples/immediate-geographic.html
+++ b/examples/immediate-geographic.html
@@ -10,6 +10,5 @@ docs: >
any geometry on each render frame. The `useGeographic` function is used in this example so that
geometries can be in geographic coordinates.
tags: "immediate, geographic"
-experimental: true
---
diff --git a/examples/vector-wfs-geographic.html b/examples/vector-wfs-geographic.html
index f7acd5b60b..5ef38da05a 100644
--- a/examples/vector-wfs-geographic.html
+++ b/examples/vector-wfs-geographic.html
@@ -11,6 +11,5 @@ tags: "geographic, vector, WFS, tile, strategy, loading, server, maptiler"
cloak:
- key: get_your_own_D6rA4zTHduk6KOKTXzGB
value: Get your own API key at https://www.maptiler.com/cloud/
-experimental: true
---
diff --git a/src/ol/View.js b/src/ol/View.js
index 4acc41003a..bda219cb0d 100644
--- a/src/ol/View.js
+++ b/src/ol/View.js
@@ -10,6 +10,7 @@ import {DEFAULT_TILE_SIZE} from './tilegrid/common.js';
import {
METERS_PER_UNIT,
createProjection,
+ disableCoordinateWarning,
fromUserCoordinate,
fromUserExtent,
getUserProjection,
@@ -241,7 +242,7 @@ const DEFAULT_MIN_ZOOM = 0;
* A View has a `projection`. The projection determines the
* coordinate system of the center, and its units determine the units of the
* resolution (projection units per pixel). The default projection is
- * Spherical Mercator (EPSG:3857).
+ * Web Mercator (EPSG:3857).
*
* ### The view states
*
@@ -406,6 +407,9 @@ class View extends BaseObject {
if (options.extent) {
options.extent = fromUserExtent(options.extent, this.projection_);
}
+ if (options.projection) {
+ disableCoordinateWarning();
+ }
this.applyOptions_(options);
}
diff --git a/src/ol/proj.js b/src/ol/proj.js
index fb19ed996a..c8c3876c4b 100644
--- a/src/ol/proj.js
+++ b/src/ol/proj.js
@@ -73,8 +73,8 @@ import {
} from './proj/transforms.js';
import {applyTransform, getWidth} from './extent.js';
import {clamp, modulo} from './math.js';
+import {equals, getWorldsAway} from './coordinate.js';
import {getDistance} from './sphere.js';
-import {getWorldsAway} from './coordinate.js';
/**
* A projection as {@link module:ol/proj/Projection}, SRS identifier
@@ -97,6 +97,16 @@ export {METERS_PER_UNIT};
export {Projection};
+let showCoordinateWarning = true;
+
+/**
+ * @param {boolean} [opt_disable = true] Disable console info about `useGeographic()`
+ */
+export function disableCoordinateWarning(opt_disable) {
+ const hide = opt_disable === undefined ? true : opt_disable;
+ showCoordinateWarning = !hide;
+}
+
/**
* @param {Array} input Input coordinate array.
* @param {Array} [opt_output] Output array of coordinate values.
@@ -386,6 +396,7 @@ export function addCoordinateTransforms(source, destination, forward, inverse) {
* @api
*/
export function fromLonLat(coordinate, opt_projection) {
+ disableCoordinateWarning();
return transform(
coordinate,
'EPSG:4326',
@@ -539,18 +550,17 @@ let userProjection = null;
/**
* Set the projection for coordinates supplied from and returned by API methods.
- * Note that this method is not yet a part of the stable API. Support for user
- * projections is not yet complete and should be considered experimental.
+ * This includes all API methods except for those interacting with tile grids.
* @param {ProjectionLike} projection The user projection.
+ * @api
*/
export function setUserProjection(projection) {
userProjection = get(projection);
}
/**
- * Clear the user projection if set. Note that this method is not yet a part of
- * the stable API. Support for user projections is not yet complete and should
- * be considered experimental.
+ * Clear the user projection if set.
+ * @api
*/
export function clearUserProjection() {
userProjection = null;
@@ -561,15 +571,16 @@ export function clearUserProjection() {
* Note that this method is not yet a part of the stable API. Support for user
* projections is not yet complete and should be considered experimental.
* @return {Projection|null} The user projection (or null if not set).
+ * @api
*/
export function getUserProjection() {
return userProjection;
}
/**
- * Use geographic coordinates (WGS-84 datum) in API methods. Note that this
- * method is not yet a part of the stable API. Support for user projections is
- * not yet complete and should be considered experimental.
+ * Use geographic coordinates (WGS-84 datum) in API methods. This includes all API
+ * methods except for those interacting with tile grids.
+ * @api
*/
export function useGeographic() {
setUserProjection('EPSG:4326');
@@ -598,6 +609,20 @@ export function toUserCoordinate(coordinate, sourceProjection) {
*/
export function fromUserCoordinate(coordinate, destProjection) {
if (!userProjection) {
+ if (
+ showCoordinateWarning &&
+ !equals(coordinate, [0, 0]) &&
+ coordinate[0] >= -180 &&
+ coordinate[0] <= 180 &&
+ coordinate[1] >= -90 &&
+ coordinate[1] <= 90
+ ) {
+ showCoordinateWarning = false;
+ // eslint-disable-next-line no-console
+ console.warn(
+ 'Call useGeographic() ol/proj once to work with [longitude, latitude] coordinates.'
+ );
+ }
return coordinate;
}
return transform(coordinate, userProjection, destProjection);
diff --git a/test/node/ol/proj.test.js b/test/node/ol/proj.test.js
index 5002b807b7..5cf40ab139 100644
--- a/test/node/ol/proj.test.js
+++ b/test/node/ol/proj.test.js
@@ -1,5 +1,6 @@
import Projection from '../../../src/ol/proj/Projection.js';
import Units from '../../../src/ol/proj/Units.js';
+import View from '../../../src/ol/View.js';
import expect from '../expect.js';
import proj4 from 'proj4';
import {HALF_SIZE} from '../../../src/ol/proj/epsg3857.js';
@@ -8,6 +9,7 @@ import {
addCommon,
clearAllProjections,
clearUserProjection,
+ disableCoordinateWarning,
equivalent,
fromLonLat,
fromUserCoordinate,
@@ -890,4 +892,43 @@ describe('ol/proj.js', function () {
);
});
});
+
+ describe('Console info about `setUserProjection`', function () {
+ let originalConsole, callCount;
+ beforeEach(function () {
+ disableCoordinateWarning(false);
+ originalConsole = console;
+ callCount = 0;
+ global.console = {
+ ...console,
+ warn: () => ++callCount,
+ };
+ });
+ afterEach(function () {
+ global.console = originalConsole;
+ clearUserProjection();
+ });
+ it('is shown once when suspicious coordinates are used', function () {
+ const view = new View({
+ center: [16, 48],
+ });
+ view.setCenter([15, 47]);
+ expect(callCount).to.be(1);
+ });
+ it('is not shown when fromLonLat() is used', function () {
+ const view = new View({
+ center: fromLonLat([16, 48]),
+ });
+ view.setCenter(fromLonLat([15, 47]));
+ expect(callCount).to.be(0);
+ });
+ it('is not shown when useGeographic() is used', function () {
+ useGeographic();
+ const view = new View({
+ center: [16, 48],
+ });
+ view.setCenter([15, 47]);
+ expect(callCount).to.be(0);
+ });
+ });
});