Deprecate GeoDistance enumerators and remove geo distance script helpers

GeoDistance is implemented using a crazy enum that causes issues with the scripting modules. This commit moves all distance calculations to arcDistance and planeDistance static methods in GeoUtils. It also removes unnecessary distance helper methods from ScriptDocValues.GeoPoints.

core/src/main/java/org/elasticsearch/common/geo/GeoDistance.java

@@ -41,7 +41,9 @@ import java.util.Locale;
 public enum GeoDistance implements Writeable {
     /**
      * Calculates distance as points on a plane. Faster, but less accurate than {@link #ARC}.
+     * @deprecated use {@link GeoUtils#planeDistance}
      */
+    @Deprecated
     PLANE {
         @Override
         public double calculate(double sourceLatitude, double sourceLongitude, double targetLatitude, double targetLongitude, DistanceUnit unit) {
@@ -63,7 +65,11 @@ public enum GeoDistance implements Writeable {
 
     /**
      * Calculates distance factor.
+     * Note: {@code calculate} is simply returning the RHS of the spherical law of cosines from 2 lat,lon points.
+     * {@code normalize} also returns the RHS of the spherical law of cosines for a given distance
+     * @deprecated use {@link SloppyMath#haversinMeters} to get distance in meters, law of cosines is being removed
      */
+    @Deprecated
     FACTOR {
         @Override
         public double calculate(double sourceLatitude, double sourceLongitude, double targetLatitude, double targetLongitude, DistanceUnit unit) {
@@ -85,7 +91,9 @@ public enum GeoDistance implements Writeable {
     },
     /**
      * Calculates distance as points on a globe.
+     * @deprecated use {@link GeoUtils#arcDistance}
      */
+    @Deprecated
     ARC {
         @Override
         public double calculate(double sourceLatitude, double sourceLongitude, double targetLatitude, double targetLongitude, DistanceUnit unit) {
@@ -143,6 +151,7 @@ public enum GeoDistance implements Writeable {
      * Default {@link GeoDistance} function. This method should be used, If no specific function has been selected.
      * This is an alias for <code>SLOPPY_ARC</code>
      */
+    @Deprecated
     public static final GeoDistance DEFAULT = SLOPPY_ARC;
 
     public abstract double normalize(double distance, DistanceUnit unit);

core/src/main/java/org/elasticsearch/common/geo/GeoHashUtils.java

@@ -300,4 +300,14 @@ public class GeoHashUtils {
 
         return neighbors;
     }
+
+    /** returns the latitude value from the string based geohash */
+    public static final double decodeLatitude(final String geohash) {
+        return GeoPointField.decodeLatitude(mortonEncode(geohash));
+    }
+
+    /** returns the latitude value from the string based geohash */
+    public static final double decodeLongitude(final String geohash) {
+        return GeoPointField.decodeLongitude(mortonEncode(geohash));
+    }
 }

core/src/main/java/org/elasticsearch/common/geo/GeoUtils.java

@@ -478,6 +478,21 @@ public class GeoUtils {
       return SloppyMath.haversinMeters(centerLat, centerLon, centerLat, (MAX_LON + centerLon) % 360);
     }
 
+    /** Return the distance (in meters) between 2 lat,lon geo points using the haversine method implemented by lucene */
+    public static double arcDistance(double lat1, double lon1, double lat2, double lon2) {
+        return SloppyMath.haversinMeters(lat1, lon1, lat2, lon2);
+    }
+
+    /**
+     * Return the distance (in meters) between 2 lat,lon geo points using a simple tangential plane
+     * this provides a faster alternative to {@link GeoUtils#arcDistance} when points are within 5 km
+     */
+    public static double planeDistance(double lat1, double lon1, double lat2, double lon2) {
+        double x = (lon2 - lon1) * SloppyMath.TO_RADIANS * Math.cos((lat2 + lat1) / 2.0 * SloppyMath.TO_RADIANS);
+        double y = (lat2 - lat1) * SloppyMath.TO_RADIANS;
+        return Math.sqrt(x * x + y * y) * EARTH_MEAN_RADIUS;
+    }
+
     private GeoUtils() {
     }
 }

core/src/main/java/org/elasticsearch/index/fielddata/ScriptDocValues.java

@@ -22,8 +22,9 @@ package org.elasticsearch.index.fielddata;
 
 import org.apache.lucene.index.SortedNumericDocValues;
 import org.apache.lucene.util.BytesRef;
-import org.elasticsearch.common.geo.GeoDistance;
+import org.elasticsearch.common.geo.GeoHashUtils;
 import org.elasticsearch.common.geo.GeoPoint;
+import org.elasticsearch.common.geo.GeoUtils;
 import org.elasticsearch.common.unit.DistanceUnit;
 import org.joda.time.DateTimeZone;
 import org.joda.time.MutableDateTime;
@@ -190,7 +191,7 @@ public interface ScriptDocValues<T> extends List<T> {
         }
     }
 
-    public static class GeoPoints extends AbstractList<GeoPoint> implements ScriptDocValues<GeoPoint> {
+    class GeoPoints extends AbstractList<GeoPoint> implements ScriptDocValues<GeoPoint> {
 
         private final MultiGeoPointValues values;
 
@@ -253,124 +254,41 @@ public interface ScriptDocValues<T> extends List<T> {
             return values.count();
         }
 
-        public double factorDistance(double lat, double lon) {
-            GeoPoint point = getValue();
-            return GeoDistance.FACTOR.calculate(point.lat(), point.lon(), lat, lon, DistanceUnit.DEFAULT);
-        }
-
-        public double factorDistanceWithDefault(double lat, double lon, double defaultValue) {
-            if (isEmpty()) {
-                return defaultValue;
-            }
-            GeoPoint point = getValue();
-            return GeoDistance.FACTOR.calculate(point.lat(), point.lon(), lat, lon, DistanceUnit.DEFAULT);
-        }
-
-        public double factorDistance02(double lat, double lon) {
-            GeoPoint point = getValue();
-            return GeoDistance.FACTOR.calculate(point.lat(), point.lon(), lat, lon, DistanceUnit.DEFAULT) + 1;
-        }
-
-        public double factorDistance13(double lat, double lon) {
-            GeoPoint point = getValue();
-            return GeoDistance.FACTOR.calculate(point.lat(), point.lon(), lat, lon, DistanceUnit.DEFAULT) + 2;
-        }
-
         public double arcDistance(double lat, double lon) {
             GeoPoint point = getValue();
-            return GeoDistance.ARC.calculate(point.lat(), point.lon(), lat, lon, DistanceUnit.DEFAULT);
+            return GeoUtils.arcDistance(point.lat(), point.lon(), lat, lon);
         }
 
         public double arcDistanceWithDefault(double lat, double lon, double defaultValue) {
             if (isEmpty()) {
                 return defaultValue;
             }
-            GeoPoint point = getValue();
-            return GeoDistance.ARC.calculate(point.lat(), point.lon(), lat, lon, DistanceUnit.DEFAULT);
-        }
-
-        public double arcDistanceInKm(double lat, double lon) {
-            GeoPoint point = getValue();
-            return GeoDistance.ARC.calculate(point.lat(), point.lon(), lat, lon, DistanceUnit.KILOMETERS);
-        }
-
-        public double arcDistanceInKmWithDefault(double lat, double lon, double defaultValue) {
-            if (isEmpty()) {
-                return defaultValue;
-            }
-            GeoPoint point = getValue();
-            return GeoDistance.ARC.calculate(point.lat(), point.lon(), lat, lon, DistanceUnit.KILOMETERS);
+            return arcDistance(lat, lon);
         }
 
-        public double arcDistanceInMiles(double lat, double lon) {
+        public double planeDistance(double lat, double lon) {
             GeoPoint point = getValue();
-            return GeoDistance.ARC.calculate(point.lat(), point.lon(), lat, lon, DistanceUnit.MILES);
+            return GeoUtils.planeDistance(point.lat(), point.lon(), lat, lon);
         }
 
-        public double arcDistanceInMilesWithDefault(double lat, double lon, double defaultValue) {
+        public double planeDistanceWithDefault(double lat, double lon, double defaultValue) {
             if (isEmpty()) {
                 return defaultValue;
             }
-            GeoPoint point = getValue();
-            return GeoDistance.ARC.calculate(point.lat(), point.lon(), lat, lon, DistanceUnit.MILES);
-        }
-
-        public double distance(double lat, double lon) {
-            GeoPoint point = getValue();
-            return GeoDistance.PLANE.calculate(point.lat(), point.lon(), lat, lon, DistanceUnit.DEFAULT);
+            return planeDistance(lat, lon);
         }
 
-        public double distanceWithDefault(double lat, double lon, double defaultValue) {
-            if (isEmpty()) {
-                return defaultValue;
-            }
-            GeoPoint point = getValue();
-            return GeoDistance.PLANE.calculate(point.lat(), point.lon(), lat, lon, DistanceUnit.DEFAULT);
-        }
-
-        public double distanceInKm(double lat, double lon) {
-            GeoPoint point = getValue();
-            return GeoDistance.PLANE.calculate(point.lat(), point.lon(), lat, lon, DistanceUnit.KILOMETERS);
-        }
-
-        public double distanceInKmWithDefault(double lat, double lon, double defaultValue) {
-            if (isEmpty()) {
-                return defaultValue;
-            }
-            GeoPoint point = getValue();
-            return GeoDistance.PLANE.calculate(point.lat(), point.lon(), lat, lon, DistanceUnit.KILOMETERS);
-        }
-
-        public double distanceInMiles(double lat, double lon) {
+        public double geohashDistance(String geohash) {
             GeoPoint point = getValue();
-            return GeoDistance.PLANE.calculate(point.lat(), point.lon(), lat, lon, DistanceUnit.MILES);
+            return GeoUtils.arcDistance(point.lat(), point.lon(), GeoHashUtils.decodeLatitude(geohash),
+                GeoHashUtils.decodeLongitude(geohash));
         }
 
-        public double distanceInMilesWithDefault(double lat, double lon, double defaultValue) {
+        public double geohashDistanceWithDefault(String geohash, double defaultValue) {
             if (isEmpty()) {
                 return defaultValue;
             }
-            GeoPoint point = getValue();
-            return GeoDistance.PLANE.calculate(point.lat(), point.lon(), lat, lon, DistanceUnit.MILES);
-        }
-
-        public double geohashDistance(String geohash) {
-            GeoPoint point = getValue();
-            GeoPoint p = new GeoPoint().resetFromGeoHash(geohash);
-            return GeoDistance.ARC.calculate(point.lat(), point.lon(), p.lat(), p.lon(), DistanceUnit.DEFAULT);
+            return geohashDistance(geohash);
         }
-
-        public double geohashDistanceInKm(String geohash) {
-            GeoPoint point = getValue();
-            GeoPoint p = new GeoPoint().resetFromGeoHash(geohash);
-            return GeoDistance.ARC.calculate(point.lat(), point.lon(), p.lat(), p.lon(), DistanceUnit.KILOMETERS);
-        }
-
-        public double geohashDistanceInMiles(String geohash) {
-            GeoPoint point = getValue();
-            GeoPoint p = new GeoPoint().resetFromGeoHash(geohash);
-            return GeoDistance.ARC.calculate(point.lat(), point.lon(), p.lat(), p.lon(), DistanceUnit.MILES);
-        }
-
     }
 }

core/src/test/java/org/elasticsearch/index/fielddata/ScriptDocValuesTests.java

@@ -19,9 +19,8 @@
 
 package org.elasticsearch.index.fielddata;
 
-import org.elasticsearch.common.geo.GeoDistance;
 import org.elasticsearch.common.geo.GeoPoint;
-import org.elasticsearch.common.unit.DistanceUnit;
+import org.elasticsearch.common.geo.GeoUtils;
 import org.elasticsearch.test.ESTestCase;
 
 import java.util.Arrays;
@@ -39,12 +38,12 @@ public class ScriptDocValuesTests extends ESTestCase {
                 }
                 return points[i];
             }
-            
+
             @Override
             public void setDocument(int docId) {
                 this.docID = docId;
             }
-            
+
             @Override
             public int count() {
                 if (docID != 0) {
@@ -94,18 +93,18 @@ public class ScriptDocValuesTests extends ESTestCase {
 
         final double otherLat = randomLat();
         final double otherLon = randomLon();
-        
-        assertEquals(GeoDistance.ARC.calculate(lat, lon, otherLat, otherLon, DistanceUnit.KILOMETERS),
-                script.arcDistanceInKm(otherLat, otherLon), 0.01);
-        assertEquals(GeoDistance.ARC.calculate(lat, lon, otherLat, otherLon, DistanceUnit.KILOMETERS),
-                script.arcDistanceInKmWithDefault(otherLat, otherLon, 42), 0.01);
-        assertEquals(42, emptyScript.arcDistanceInKmWithDefault(otherLat, otherLon, 42), 0);
-
-        assertEquals(GeoDistance.PLANE.calculate(lat, lon, otherLat, otherLon, DistanceUnit.KILOMETERS),
-                script.distanceInKm(otherLat, otherLon), 0.01);
-        assertEquals(GeoDistance.PLANE.calculate(lat, lon, otherLat, otherLon, DistanceUnit.KILOMETERS),
-                script.distanceInKmWithDefault(otherLat, otherLon, 42), 0.01);
-        assertEquals(42, emptyScript.distanceInKmWithDefault(otherLat, otherLon, 42), 0);
+
+        assertEquals(GeoUtils.arcDistance(lat, lon, otherLat, otherLon) / 1000d,
+                script.arcDistance(otherLat, otherLon) / 1000d, 0.01);
+        assertEquals(GeoUtils.arcDistance(lat, lon, otherLat, otherLon) / 1000d,
+                script.arcDistanceWithDefault(otherLat, otherLon, 42) / 1000d, 0.01);
+        assertEquals(42, emptyScript.arcDistanceWithDefault(otherLat, otherLon, 42), 0);
+
+        assertEquals(GeoUtils.planeDistance(lat, lon, otherLat, otherLon) / 1000d,
+                script.planeDistance(otherLat, otherLon) / 1000d, 0.01);
+        assertEquals(GeoUtils.planeDistance(lat, lon, otherLat, otherLon) / 1000d,
+                script.planeDistanceWithDefault(otherLat, otherLon, 42) / 1000d, 0.01);
+        assertEquals(42, emptyScript.planeDistanceWithDefault(otherLat, otherLon, 42), 0);
     }
 
 }

core/src/test/java/org/elasticsearch/search/geo/GeoDistanceIT.java

@@ -22,7 +22,8 @@ package org.elasticsearch.search.geo;
 import org.elasticsearch.Version;
 import org.elasticsearch.action.search.SearchResponse;
 import org.elasticsearch.cluster.metadata.IndexMetaData;
-import org.elasticsearch.common.geo.GeoDistance;
+import org.elasticsearch.common.geo.GeoHashUtils;
+import org.elasticsearch.common.geo.GeoUtils;
 import org.elasticsearch.common.settings.Settings;
 import org.elasticsearch.common.unit.DistanceUnit;
 import org.elasticsearch.common.xcontent.XContentBuilder;
@@ -47,10 +48,11 @@ import static org.hamcrest.Matchers.closeTo;
 
 public class GeoDistanceIT extends ESIntegTestCase {
 
-    private static final double source_lat = 32.798;
-    private static final double source_long = -117.151;
-    private static final double target_lat = 32.81;
-    private static final double target_long = -117.21;
+    private static final double src_lat = 32.798;
+    private static final double src_lon = -117.151;
+    private static final double tgt_lat = 32.81;
+    private static final double tgt_lon = -117.21;
+    private static final String tgt_geohash = GeoHashUtils.stringEncode(tgt_lon, tgt_lat);
 
     @Override
     protected Collection<Class<? extends Plugin>> nodePlugins() {
@@ -65,21 +67,17 @@ public class GeoDistanceIT extends ESIntegTestCase {
             Map<String, Function<Map<String, Object>, Object>> scripts = new HashMap<>();
 
             scripts.put("arcDistance", vars -> distanceScript(vars,
-                    location -> location.arcDistance(target_lat, target_long)));
-            scripts.put("distance", vars -> distanceScript(vars,
-                    location -> location.distance(target_lat, target_long)));
-            scripts.put("arcDistanceInKm", vars -> distanceScript(vars,
-                    location -> location.arcDistanceInKm(target_lat, target_long)));
-            scripts.put("distanceInKm", vars -> distanceScript(vars,
-                    location -> location.distanceInKm(target_lat, target_long)));
-            scripts.put("arcDistanceInKm(lat, lon + 360)", vars -> distanceScript(vars,
-                    location -> location.arcDistanceInKm(target_lat, target_long + 360)));
-            scripts.put("arcDistanceInKm(lat + 360, lon)", vars -> distanceScript(vars,
-                    location -> location.arcDistanceInKm(target_lat + 360, target_long)));
-            scripts.put("arcDistanceInMiles", vars -> distanceScript(vars,
-                    location -> location.arcDistanceInMiles(target_lat, target_long)));
-            scripts.put("distanceInMiles", vars -> distanceScript(vars,
-                    location -> location.distanceInMiles(target_lat, target_long)));
+                    location -> location.arcDistance(tgt_lat, tgt_lon)));
+            scripts.put("arcDistanceGeoUtils", vars -> distanceScript(vars,
+                    location -> GeoUtils.arcDistance(location.getLat(), location.getLon(), tgt_lat, tgt_lon)));
+            scripts.put("planeDistance", vars -> distanceScript(vars,
+                    location -> location.planeDistance(tgt_lat, tgt_lon)));
+            scripts.put("geohashDistance", vars -> distanceScript(vars,
+                    location -> location.geohashDistance(tgt_geohash)));
+            scripts.put("arcDistance(lat, lon + 360)/1000d", vars -> distanceScript(vars,
+                location -> location.arcDistance(tgt_lat, tgt_lon + 360)/1000d));
+            scripts.put("arcDistance(lat + 360, lon)/1000d", vars -> distanceScript(vars,
+                location -> location.arcDistance(tgt_lat + 360, tgt_lon)/1000d));
 
             return scripts;
         }
@@ -108,8 +106,8 @@ public class GeoDistanceIT extends ESIntegTestCase {
                 .setSource(jsonBuilder().startObject()
                         .field("name", "TestPosition")
                         .startObject("location")
-                        .field("lat", source_lat)
-                        .field("lon", source_long)
+                        .field("lat", src_lat)
+                        .field("lon", src_lon)
                         .endObject()
                         .endObject())
                 .get();
@@ -122,62 +120,39 @@ public class GeoDistanceIT extends ESIntegTestCase {
                 .get();
         Double resultDistance1 = searchResponse1.getHits().getHits()[0].getFields().get("distance").getValue();
         assertThat(resultDistance1,
-                closeTo(GeoDistance.ARC.calculate(source_lat, source_long, target_lat, target_long, DistanceUnit.DEFAULT), 0.01d));
+                closeTo(GeoUtils.arcDistance(src_lat, src_lon, tgt_lat, tgt_lon), 0.01d));
 
-        // Test doc['location'].distance(lat, lon)
+        // Test doc['location'].planeDistance(lat, lon)
         SearchResponse searchResponse2 = client().prepareSearch().addStoredField("_source")
-                .addScriptField("distance", new Script("distance", ScriptType.INLINE, CustomScriptPlugin.NAME, null))
-                .get();
+                .addScriptField("distance", new Script("planeDistance", ScriptType.INLINE,
+                    CustomScriptPlugin.NAME, null)).get();
         Double resultDistance2 = searchResponse2.getHits().getHits()[0].getFields().get("distance").getValue();
         assertThat(resultDistance2,
-                closeTo(GeoDistance.PLANE.calculate(source_lat, source_long, target_lat, target_long, DistanceUnit.DEFAULT), 0.01d));
-
-        // Test doc['location'].arcDistanceInKm(lat, lon)
-        SearchResponse searchResponse3 = client().prepareSearch().addStoredField("_source")
-                .addScriptField("distance", new Script("arcDistanceInKm", ScriptType.INLINE, CustomScriptPlugin.NAME, null))
-                .get();
-        Double resultArcDistance3 = searchResponse3.getHits().getHits()[0].getFields().get("distance").getValue();
-        assertThat(resultArcDistance3,
-                closeTo(GeoDistance.ARC.calculate(source_lat, source_long, target_lat, target_long, DistanceUnit.KILOMETERS), 0.01d));
+                closeTo(GeoUtils.planeDistance(src_lat, src_lon, tgt_lat, tgt_lon), 0.01d));
 
-        // Test doc['location'].distanceInKm(lat, lon)
+        // Test doc['location'].geohashDistance(lat, lon)
         SearchResponse searchResponse4 = client().prepareSearch().addStoredField("_source")
-                .addScriptField("distance", new Script("distanceInKm", ScriptType.INLINE, CustomScriptPlugin.NAME, null))
-                .get();
+                .addScriptField("distance", new Script("geohashDistance", ScriptType.INLINE,
+                    CustomScriptPlugin.NAME, null)).get();
         Double resultDistance4 = searchResponse4.getHits().getHits()[0].getFields().get("distance").getValue();
         assertThat(resultDistance4,
-                closeTo(GeoDistance.PLANE.calculate(source_lat, source_long, target_lat, target_long, DistanceUnit.KILOMETERS), 0.01d));
+                closeTo(GeoUtils.arcDistance(src_lat, src_lon, GeoHashUtils.decodeLatitude(tgt_geohash),
+                    GeoHashUtils.decodeLongitude(tgt_geohash)), 0.01d));
 
-        // Test doc['location'].arcDistanceInKm(lat, lon + 360)
+        // Test doc['location'].arcDistance(lat, lon + 360)/1000d
         SearchResponse searchResponse5 = client().prepareSearch().addStoredField("_source")
-                .addScriptField("distance", new Script("arcDistanceInKm(lat, lon + 360)", ScriptType.INLINE, CustomScriptPlugin.NAME, null))
-                .get();
+                .addScriptField("distance", new Script("arcDistance(lat, lon + 360)/1000d", ScriptType.INLINE,
+                    CustomScriptPlugin.NAME, null)).get();
         Double resultArcDistance5 = searchResponse5.getHits().getHits()[0].getFields().get("distance").getValue();
         assertThat(resultArcDistance5,
-                closeTo(GeoDistance.ARC.calculate(source_lat, source_long, target_lat, target_long, DistanceUnit.KILOMETERS), 0.01d));
+                closeTo(GeoUtils.arcDistance(src_lat, src_lon, tgt_lat, tgt_lon)/1000d, 0.01d));
 
-        // Test doc['location'].arcDistanceInKm(lat + 360, lon)
+        // Test doc['location'].arcDistance(lat + 360, lon)/1000d
         SearchResponse searchResponse6 = client().prepareSearch().addStoredField("_source")
-                .addScriptField("distance", new Script("arcDistanceInKm(lat + 360, lon)", ScriptType.INLINE, CustomScriptPlugin.NAME, null))
-                .get();
+                .addScriptField("distance", new Script("arcDistance(lat + 360, lon)/1000d", ScriptType.INLINE,
+                    CustomScriptPlugin.NAME, null)).get();
         Double resultArcDistance6 = searchResponse6.getHits().getHits()[0].getFields().get("distance").getValue();
         assertThat(resultArcDistance6,
-                closeTo(GeoDistance.ARC.calculate(source_lat, source_long, target_lat, target_long, DistanceUnit.KILOMETERS), 0.01d));
-
-        // Test doc['location'].arcDistanceInMiles(lat, lon)
-        SearchResponse searchResponse7 = client().prepareSearch().addStoredField("_source")
-                .addScriptField("distance", new Script("arcDistanceInMiles", ScriptType.INLINE, CustomScriptPlugin.NAME, null))
-                .get();
-        Double resultDistance7 = searchResponse7.getHits().getHits()[0].getFields().get("distance").getValue();
-        assertThat(resultDistance7,
-                closeTo(GeoDistance.ARC.calculate(source_lat, source_long, target_lat, target_long, DistanceUnit.MILES), 0.01d));
-
-        // Test doc['location'].distanceInMiles(lat, lon)
-        SearchResponse searchResponse8 = client().prepareSearch().addStoredField("_source")
-                .addScriptField("distance", new Script("distanceInMiles", ScriptType.INLINE, CustomScriptPlugin.NAME, null))
-                .get();
-        Double resultDistance8 = searchResponse8.getHits().getHits()[0].getFields().get("distance").getValue();
-        assertThat(resultDistance8,
-                closeTo(GeoDistance.PLANE.calculate(source_lat, source_long, target_lat, target_long, DistanceUnit.MILES), 0.01d));
+                closeTo(GeoUtils.arcDistance(src_lat, src_lon, tgt_lat, tgt_lon)/1000d, 0.01d));
     }
 }

docs/reference/modules/scripting/groovy.asciidoc

@@ -43,56 +43,26 @@ on the underlying field type):
 `doc['field_name'].lons`::
     The longitudes of a geo point type, or an empty array.
 
-`doc['field_name'].distance(lat, lon)`::
-    The `plane` distance (in meters) of this geo point field from the provided lat/lon.
-
-`doc['field_name'].distanceWithDefault(lat, lon, default)`::
-    The `plane` distance (in meters) of this geo point field from the provided lat/lon with a default value.
-
-`doc['field_name'].distanceInMiles(lat, lon)`::
-    The `plane` distance (in miles) of this geo point field from the provided lat/lon.
-
-`doc['field_name'].distanceInMilesWithDefault(lat, lon, default)`::
-    The `plane` distance (in miles) of this geo point field from the provided lat/lon with a default value.
-
-`doc['field_name'].distanceInKm(lat, lon)`::
-    The `plane` distance (in km) of this geo point field from the provided lat/lon.
-
-`doc['field_name'].distanceInKmWithDefault(lat, lon, default)`::
-    The `plane` distance (in km) of this geo point field from the provided lat/lon with a default value.
-
 `doc['field_name'].arcDistance(lat, lon)`::
     The `arc` distance (in meters) of this geo point field from the provided lat/lon.
 
 `doc['field_name'].arcDistanceWithDefault(lat, lon, default)`::
-    The `arc` distance (in meters) of this geo point field from the provided lat/lon with a default value.
+    The `arc` distance (in meters) of this geo point field from the provided lat/lon with a default value
+    for empty fields.
 
-`doc['field_name'].arcDistanceInMiles(lat, lon)`::
-    The `arc` distance (in miles) of this geo point field from the provided lat/lon.
-
-`doc['field_name'].arcDistanceInMilesWithDefault(lat, lon, default)`::
-    The `arc` distance (in miles) of this geo point field from the provided lat/lon with a default value.
-
-`doc['field_name'].arcDistanceInKm(lat, lon)`::
-    The `arc` distance (in km) of this geo point field from the provided lat/lon.
-
-`doc['field_name'].arcDistanceInKmWithDefault(lat, lon, default)`::
-    The `arc` distance (in km) of this geo point field from the provided lat/lon with a default value.
-
-`doc['field_name'].factorDistance(lat, lon)`::
-    The distance factor of this geo point field from the provided lat/lon.
+`doc['field_name'].planeDistance(lat, lon)`::
+    The `plane` distance (in meters) of this geo point field from the provided lat/lon.
 
-`doc['field_name'].factorDistance(lat, lon, default)`::
-    The distance factor of this geo point field from the provided lat/lon with a default value.
+`doc['field_name'].planeDistanceWithDefault(lat, lon, default)`::
+    The `plane` distance (in meters) of this geo point field from the provided lat/lon with a default value
+    for empty fields.
 
 `doc['field_name'].geohashDistance(geohash)`::
     The `arc` distance (in meters) of this geo point field from the provided geohash.
 
-`doc['field_name'].geohashDistanceInKm(geohash)`::
-    The `arc` distance (in km) of this geo point field from the provided geohash.
-
-`doc['field_name'].geohashDistanceInMiles(geohash)`::
-    The `arc` distance (in miles) of this geo point field from the provided geohash.
+`doc['field_name'].geohashDistanceWithDefault(geohash, default)`::
+    The `arc` distance (in meters) of this geo point field from the provided geohash with a default value
+    for empty fields.
 
 
 [float]

modules/lang-painless/src/main/resources/org/elasticsearch/painless/org.elasticsearch.txt

@@ -92,26 +92,13 @@ class org.elasticsearch.index.fielddata.ScriptDocValues.GeoPoints -> org.elastic
   double[] getLats()
   double[] getLons()
 
-  # geo distance functions... so many...
-  double factorDistance(double,double)
-  double factorDistanceWithDefault(double,double,double)
-  double factorDistance02(double,double)
-  double factorDistance13(double,double)
+  # geo distance functions
   double arcDistance(double,double)
   double arcDistanceWithDefault(double,double,double)
-  double arcDistanceInKm(double,double)
-  double arcDistanceInKmWithDefault(double,double,double)
-  double arcDistanceInMiles(double,double)
-  double arcDistanceInMilesWithDefault(double,double,double)
-  double distance(double,double)
-  double distanceWithDefault(double,double,double)
-  double distanceInKm(double,double)
-  double distanceInKmWithDefault(double,double,double)
-  double distanceInMiles(double,double)
-  double distanceInMilesWithDefault(double,double,double)
+  double planeDistance(double,double)
+  double planeDistanceWithDefault(double,double,double)
   double geohashDistance(String)
-  double geohashDistanceInKm(String)
-  double geohashDistanceInMiles(String)
+  double geohashDistanceWithDefault(String,double)
 }
 
 # for testing.