Move geo related helper functions

Author: camdecoster

src/lib/geo_location_utils.js

@@ -79,6 +79,28 @@ function locationToFeature(locationmode, location, features) {
     return false;
 }
 
+// Offset used to lift negative longitudes (-180..0) into a continuous frame
+// (180..360) so polygons and points that straddle the antimeridian can be
+// compared with linear math. Shared between polygon stitching and hover
+// hit-testing so both sides stay in sync.
+const ANTIMERIDIAN_LON_SHIFT = 360;
+
+/**
+ * Find the first index where a polygon ring crosses the antimeridian
+ * (a transition from positive to negative longitude between consecutive
+ * points). Returns null when no crossing is found.
+ *
+ * @param {Array<Array<number>>} pts - polygon points as [lon, lat] pairs
+ * @return {number|null} index of the segment that crosses, or null
+ */
+function doesCrossAntiMeridian(pts) {
+    for (let l = 0; l < pts.length - 1; l++) {
+        if (pts[l][0] > 0 && pts[l + 1][0] < 0) return l;
+    }
+
+    return null;
+}
+
 function feature2polygons(feature) {
     var geometry = feature.geometry;
     var coords = geometry.coordinates;
@@ -87,13 +109,6 @@ function feature2polygons(feature) {
     var polygons = [];
     var appendPolygon, j, k, m;
 
-    function doesCrossAntiMerdian(pts) {
-        for (var l = 0; l < pts.length - 1; l++) {
-            if (pts[l][0] > 0 && pts[l + 1][0] < 0) return l;
-        }
-        return null;
-    }
-
     if (loc === 'RUS' || loc === 'FJI') {
         // Russia and Fiji have landmasses that cross the antimeridian,
         // we need to add +360 to their longitude coordinates, so that
@@ -105,13 +120,13 @@ function feature2polygons(feature) {
         appendPolygon = function (_pts) {
             var pts;
 
-            if (doesCrossAntiMerdian(_pts) === null) {
+            if (doesCrossAntiMeridian(_pts) === null) {
                 pts = _pts;
             } else {
                 pts = new Array(_pts.length);
                 for (m = 0; m < _pts.length; m++) {
                     // do not mutate calcdata[i][j].geojson !!
-                    pts[m] = [_pts[m][0] < 0 ? _pts[m][0] + 360 : _pts[m][0], _pts[m][1]];
+                    pts[m] = [_pts[m][0] < 0 ? _pts[m][0] + ANTIMERIDIAN_LON_SHIFT : _pts[m][0], _pts[m][1]];
                 }
             }
 
@@ -121,7 +136,7 @@ function feature2polygons(feature) {
         // Antarctica has a landmass that wraps around every longitudes which
         // confuses the 'contains' methods.
         appendPolygon = function (pts) {
-            var crossAntiMeridianIndex = doesCrossAntiMerdian(pts);
+            var crossAntiMeridianIndex = doesCrossAntiMeridian(pts);
 
             // polygon that do not cross anti-meridian need no special handling
             if (crossAntiMeridianIndex === null) {
@@ -139,7 +154,7 @@ function feature2polygons(feature) {
 
             for (m = 0; m < pts.length; m++) {
                 if (m > crossAntiMeridianIndex) {
-                    stitch[si++] = [pts[m][0] + 360, pts[m][1]];
+                    stitch[si++] = [pts[m][0] + ANTIMERIDIAN_LON_SHIFT, pts[m][1]];
                 } else if (m === crossAntiMeridianIndex) {
                     stitch[si++] = pts[m];
                     stitch[si++] = [pts[m][0], -90];
@@ -426,7 +441,20 @@ function getFitboundsLonRange(lons) {
     const antimeridianGap = 360 - naiveSpan;
     if (maxGap <= antimeridianGap) return null;
 
-    return [sorted[gapStart + 1], sorted[gapStart] + 360];
+    return [sorted[gapStart + 1], sorted[gapStart] + ANTIMERIDIAN_LON_SHIFT];
+}
+
+/**
+ * Return a monotonic version of a `[lon0, lon1]` longitude range so its
+ * midpoint and span can be computed as if longitude were a regular linear
+ * coordinate. When the range crosses the antimeridian (`lon0 > 0`, `lon1 < 0`)
+ * `lon1` is shifted by +360°; otherwise the input pair is returned unchanged.
+ *
+ * @param {[number, number]} lonRange - `[lon0, lon1]`, each in [-180, 180]
+ * @return {[number, number]} the unwrapped range
+ */
+function unwrapLonRange([lon0, lon1]) {
+    return [lon0, lon0 > 0 && lon1 < 0 ? lon1 + ANTIMERIDIAN_LON_SHIFT : lon1];
 }
 
 module.exports = {
@@ -436,5 +464,8 @@ module.exports = {
     extractTraceFeature,
     fetchTraceGeoData,
     computeBbox,
-    getFitboundsLonRange
+    doesCrossAntiMeridian,
+    getFitboundsLonRange,
+    unwrapLonRange,
+    ANTIMERIDIAN_LON_SHIFT
 };

src/plots/geo/geo.js

@@ -27,6 +27,7 @@ var constants = require('./constants');
 
 var geoUtils = require('../../lib/geo_location_utils');
 var getFitboundsLonRange = geoUtils.getFitboundsLonRange;
+var unwrapLonRange = geoUtils.unwrapLonRange;
 var topojsonUtils = require('../../lib/topojson_utils');
 var topojsonFeature = require('topojson-client').feature;
 
@@ -827,14 +828,10 @@ function makeGraticule(axisName, geoLayout, fullLayout) {
 // Note that clipPad padding is added around range to avoid aliasing.
 function makeRangeBox(lon, lat) {
     var clipPad = constants.clipPad;
-    var lon0 = lon[0] + clipPad;
-    var lon1 = lon[1] - clipPad;
+    const [lon0, lon1] = unwrapLonRange([lon[0] + clipPad, lon[1] - clipPad]);
     var lat0 = lat[0] + clipPad;
     var lat1 = lat[1] - clipPad;
 
-    // to cross antimeridian w/o ambiguity
-    if(lon0 > 0 && lon1 < 0) lon1 += 360;
-
     var dlon4 = (lon1 - lon0) / 4;
 
     return {

src/plots/geo/layout_defaults.js

@@ -3,6 +3,7 @@
 var Lib = require('../../lib');
 var handleSubplotDefaults = require('../subplot_defaults');
 var getSubplotData = require('../get_data').getSubplotData;
+var unwrapLonRange = require('../../lib/geo_location_utils').unwrapLonRange;
 
 var constants = require('./constants');
 var layoutAttributes = require('./layout_attributes');
@@ -108,10 +109,7 @@ function handleGeoDefaults(geoLayoutIn, geoLayoutOut, coerce, opts) {
     var lonRange = geoLayoutOut.lonaxis.range;
     var latRange = geoLayoutOut.lataxis.range;
 
-    // to cross antimeridian w/o ambiguity
-    var lon0 = lonRange[0];
-    var lon1 = lonRange[1];
-    if(lon0 > 0 && lon1 < 0) lon1 += 360;
+    const [lon0, lon1] = unwrapLonRange(lonRange);
 
     var centerLon = (lon0 + lon1) / 2;
     var projLon;

src/traces/choropleth/hover.js

@@ -3,6 +3,7 @@
 var Axes = require('../../plots/cartesian/axes');
 var attributes = require('./attributes');
 var fillText = require('../../lib').fillText;
+const { ANTIMERIDIAN_LON_SHIFT } = require('../../lib/geo_location_utils');
 
 module.exports = function hoverPoints(pointData, xval, yval) {
     var cd = pointData.cd;
@@ -12,7 +13,10 @@ module.exports = function hoverPoints(pointData, xval, yval) {
     var pt, i, j, isInside;
 
     var xy = [xval, yval];
-    var altXy = [xval + 360, yval];
+    // Polygons that cross the antimerdian are shifted by
+    // ANTIMERIDIAN_LON_SHIFT in feature2polygons (src/lib/geo_location_utils.js),
+    // so test the hover point in both the original and shifted frames.
+    const altXy = [xval + ANTIMERIDIAN_LON_SHIFT, yval];
 
     for(i = 0; i < cd.length; i++) {
         pt = cd[i];
@@ -23,7 +27,6 @@ module.exports = function hoverPoints(pointData, xval, yval) {
                 if(pt._polygons[j].contains(xy)) {
                     isInside = !isInside;
                 }
-                // for polygons that cross antimeridian as xval is in [-180, 180]
                 if(pt._polygons[j].contains(altXy)) {
                     isInside = !isInside;
                 }

test/jasmine/tests/lib_geo_location_utils_test.js

@@ -1,4 +1,4 @@
-const { getFitboundsLonRange } = require('../../../src/lib/geo_location_utils');
+const { getFitboundsLonRange, unwrapLonRange, doesCrossAntiMeridian } = require('../../../src/lib/geo_location_utils');
 
 describe('Test geo_location_utils.getFitboundsLonRange', () => {
     it('returns the compact crossing range when point data straddles the antimeridian', () => {
@@ -23,3 +23,31 @@ describe('Test geo_location_utils.getFitboundsLonRange', () => {
         expect(getFitboundsLonRange([])).toBe(null);
     });
 });
+
+describe('Test geo_location_utils.unwrapLonRange', () => {
+    it('shifts lon1 by +360 when the range crosses the antimeridian', () => {
+        expect(unwrapLonRange([170, -170])).toEqual([170, 190]);
+        expect(unwrapLonRange([1, -1])).toEqual([1, 359]);
+    });
+
+    it('leaves the pair unchanged when the range does not cross the antimeridian', () => {
+        expect(unwrapLonRange([-170, 170])).toEqual([-170, 170]);
+        expect(unwrapLonRange([-10, 10])).toEqual([-10, 10]);
+        expect(unwrapLonRange([-170, -10])).toEqual([-170, -10]);
+        expect(unwrapLonRange([10, 170])).toEqual([10, 170]);
+    });
+});
+
+describe('Test geo_location_utils.doesCrossAntiMeridian', () => {
+    it('returns the index of the first positive-to-negative longitude transition', () => {
+        expect(doesCrossAntiMeridian([[170, 0], [179, 0], [-179, 0], [-170, 0]])).toBe(1);
+        expect(doesCrossAntiMeridian([[1, 0], [-1, 0]])).toBe(0);
+    });
+
+    it('returns null when no segment crosses the antimeridian', () => {
+        expect(doesCrossAntiMeridian([[-179, 0], [-170, 0], [170, 0]])).toBe(null);
+        expect(doesCrossAntiMeridian([[10, 0], [20, 0], [30, 0]])).toBe(null);
+        expect(doesCrossAntiMeridian([])).toBe(null);
+        expect(doesCrossAntiMeridian([[10, 0]])).toBe(null);
+    });
+});