Merge pull request #70 from isaacbrodsky/bump-3.7.0

Update to H3 v3.7.0

Author: isaacbrodsky

.gitignore

@@ -24,3 +24,5 @@ pom.xml.releaseBackup
 pom.xml.versionsBackup
 pom.xml.next
 release.properties
+
+.vscode/

CHANGELOG.md

@@ -7,6 +7,13 @@ file [H3Core.java](./src/main/java/com/uber/h3core/H3Core.java), and support
 for the Linux x64 and Darwin x64 platforms.
 
 ## [Unreleased]
+## Added
+- Area and haversine distance functions (#70)
+    - `cellArea`
+    - `pointDist`
+    - `exactEdgeLength`
+## Changed
+- Updated the core library to v3.7.1. (#70)
 
 ## [3.6.4] - 2020-06-29
 ### Changed

h3version.properties

@@ -1 +1 @@
-h3.git.reference=v3.6.4
+h3.git.reference=v3.7.1

src/main/c/h3-java/src/jniapi.c

@@ -763,6 +763,106 @@ JNIEXPORT jint JNICALL Java_com_uber_h3core_NativeMethods_uncompact(
     return ret;
 }
 
+/*
+ * Class:     com_uber_h3core_NativeMethods
+ * Method:    cellAreaRads2
+ * Signature: (J)D
+ */
+JNIEXPORT jdouble JNICALL Java_com_uber_h3core_NativeMethods_cellAreaRads2(
+    JNIEnv *env, jobject thiz, jlong h3) {
+    return cellAreaRads2(h3);
+}
+
+/*
+ * Class:     com_uber_h3core_NativeMethods
+ * Method:    cellAreaKm2
+ * Signature: (J)D
+ */
+JNIEXPORT jdouble JNICALL Java_com_uber_h3core_NativeMethods_cellAreaKm2(
+    JNIEnv *env, jobject thiz, jlong h3) {
+    return cellAreaKm2(h3);
+}
+
+/*
+ * Class:     com_uber_h3core_NativeMethods
+ * Method:    cellAreaM2
+ * Signature: (J)D
+ */
+JNIEXPORT jdouble JNICALL Java_com_uber_h3core_NativeMethods_cellAreaM2(
+    JNIEnv *env, jobject thiz, jlong h3) {
+    return cellAreaM2(h3);
+}
+
+/*
+ * Class:     com_uber_h3core_NativeMethods
+ * Method:    pointDistRads
+ * Signature: (DDDD)D
+ */
+JNIEXPORT jdouble JNICALL Java_com_uber_h3core_NativeMethods_pointDistRads(
+    JNIEnv *env, jobject thiz, jdouble lat1, jdouble lon1, jdouble lat2,
+    jdouble lon2) {
+    GeoCoord c1 = {.lat = lat1, .lon = lon1};
+    GeoCoord c2 = {.lat = lat2, .lon = lon2};
+    return pointDistRads(&c1, &c2);
+}
+
+/*
+ * Class:     com_uber_h3core_NativeMethods
+ * Method:    pointDistKm
+ * Signature: (DDDD)D
+ */
+JNIEXPORT jdouble JNICALL Java_com_uber_h3core_NativeMethods_pointDistKm(
+    JNIEnv *env, jobject thiz, jdouble lat1, jdouble lon1, jdouble lat2,
+    jdouble lon2) {
+    GeoCoord c1 = {.lat = lat1, .lon = lon1};
+    GeoCoord c2 = {.lat = lat2, .lon = lon2};
+    return pointDistKm(&c1, &c2);
+}
+
+/*
+ * Class:     com_uber_h3core_NativeMethods
+ * Method:    pointDistM
+ * Signature: (DDDD)D
+ */
+JNIEXPORT jdouble JNICALL Java_com_uber_h3core_NativeMethods_pointDistM(
+    JNIEnv *env, jobject thiz, jdouble lat1, jdouble lon1, jdouble lat2,
+    jdouble lon2) {
+    GeoCoord c1 = {.lat = lat1, .lon = lon1};
+    GeoCoord c2 = {.lat = lat2, .lon = lon2};
+    return pointDistM(&c1, &c2);
+}
+
+/*
+ * Class:     com_uber_h3core_NativeMethods
+ * Method:    exactEdgeLengthRads
+ * Signature: (J)D
+ */
+JNIEXPORT jdouble JNICALL
+Java_com_uber_h3core_NativeMethods_exactEdgeLengthRads(JNIEnv *env,
+                                                       jobject thiz, jlong h3) {
+    return exactEdgeLengthRads(h3);
+}
+
+/*
+ * Class:     com_uber_h3core_NativeMethods
+ * Method:    exactEdgeLengthKm
+ * Signature: (J)D
+ */
+JNIEXPORT jdouble JNICALL Java_com_uber_h3core_NativeMethods_exactEdgeLengthKm(
+    JNIEnv *env, jobject thiz, jlong h3) {
+    return exactEdgeLengthKm(h3);
+}
+
+/*
+ * Class:     com_uber_h3core_NativeMethods
+ * Method:    exactEdgeLengthM
+ * Signature: (J)D
+ */
+JNIEXPORT jdouble JNICALL Java_com_uber_h3core_NativeMethods_exactEdgeLengthM(
+    JNIEnv *env, jobject thiz, jlong h3) {
+    return exactEdgeLengthM(h3);
+}
+
 /*
  * Class:     com_uber_h3core_NativeMethods
  * Method:    hexAreaKm2

src/main/java/com/uber/h3core/AreaUnit.java

@@ -19,6 +19,10 @@
  * Unit of measurement for areas.
  */
 public enum AreaUnit {
+    /**
+     * Square radians on the WGS84 sphere
+     */
+    rads2,
     /**
      * Square kilometers
      */

src/main/java/com/uber/h3core/H3Core.java

@@ -966,6 +966,88 @@ public long stringToH3(String h3Address) {
         return Long.parseUnsignedLong(h3Address, 16);
     }
 
+    /**
+     * Calculates the area of the given H3 cell.
+     *
+     * @param h3Address Cell to find the area of.
+     * @param unit      Unit to calculate the area in.
+     * @return Cell area in the given units.
+     */
+    public double cellArea(String h3Address, AreaUnit unit) {
+        return cellArea(stringToH3(h3Address), unit);
+    }
+
+    /**
+     * Calculates the area of the given H3 cell.
+     *
+     * @param h3   Cell to find the area of.
+     * @param unit Unit to calculate the area in.
+     * @return Cell area in the given units.
+     */
+    public double cellArea(long h3, AreaUnit unit) {
+        if (unit == AreaUnit.rads2)
+            return h3Api.cellAreaRads2(h3);
+        else if (unit == AreaUnit.km2)
+            return h3Api.cellAreaKm2(h3);
+        else if (unit == AreaUnit.m2)
+            return h3Api.cellAreaM2(h3);
+        else
+            throw new IllegalArgumentException(String.format("Invalid unit: %s", unit));
+    }
+
+    /**
+     * Return the distance along the sphere between two points.
+     *
+     * @param a    First point
+     * @param b    Second point
+     * @param unit Unit to return the distance in.
+     * @return Distance from point <code>a</code> to point <code>b</code>
+     */
+    public double pointDist(GeoCoord a, GeoCoord b, LengthUnit unit) {
+        double lat1 = toRadians(a.lat);
+        double lng1 = toRadians(a.lng);
+        double lat2 = toRadians(b.lat);
+        double lng2 = toRadians(b.lng);
+
+        if (unit == LengthUnit.rads)
+            return h3Api.pointDistRads(lat1, lng1, lat2, lng2);
+        else if (unit == LengthUnit.km)
+            return h3Api.pointDistKm(lat1, lng1, lat2, lng2);
+        else if (unit == LengthUnit.m)
+            return h3Api.pointDistM(lat1, lng1, lat2, lng2);
+        else
+            throw new IllegalArgumentException(String.format("Invalid unit: %s", unit));
+    }
+
+    /**
+     * Calculate the edge length of the given H3 edge.
+     *
+     * @param edgeAddress Edge to find the edge length of.
+     * @param unit        Unit of measure to use.
+     * @return Length of the given edge.
+     */
+    public double exactEdgeLength(String edgeAddress, LengthUnit unit) {
+        return exactEdgeLength(stringToH3(edgeAddress), unit);
+    }
+
+    /**
+     * Calculate the edge length of the given H3 edge.
+     *
+     * @param edge Edge to find the edge length of.
+     * @param unit Unit of measure to use.
+     * @return Length of the given edge.
+     */
+    public double exactEdgeLength(long edge, LengthUnit unit) {
+        if (unit == LengthUnit.rads)
+            return h3Api.exactEdgeLengthRads(edge);
+        else if (unit == LengthUnit.km)
+            return h3Api.exactEdgeLengthKm(edge);
+        else if (unit == LengthUnit.m)
+            return h3Api.exactEdgeLengthM(edge);
+        else
+            throw new IllegalArgumentException(String.format("Invalid unit: %s", unit));
+    }
+
     /**
      * Returns the average area in <code>unit</code> for indexes at resolution <code>res</code>.
      *

src/main/java/com/uber/h3core/LengthUnit.java

@@ -19,6 +19,10 @@
  * Unit of measurement for lengths.
  */
 public enum LengthUnit {
+    /**
+     * Radians on the WGS84 sphere
+     */
+    rads,
     /**
      * Kilometers
      */

src/main/java/com/uber/h3core/NativeMethods.java

@@ -61,6 +61,16 @@ final class NativeMethods {
     native int maxUncompactSize(long[] h3, int res);
     native int uncompact(long[] h3, int res, long[] results);
 
+    native double cellAreaRads2(long h3);
+    native double cellAreaKm2(long h3);
+    native double cellAreaM2(long h3);
+    native double pointDistRads(double lat1, double lon1, double lat2, double lon2);
+    native double pointDistKm(double lat1, double lon1, double lat2, double lon2);
+    native double pointDistM(double lat1, double lon1, double lat2, double lon2);
+    native double exactEdgeLengthRads(long h3);
+    native double exactEdgeLengthKm(long h3);
+    native double exactEdgeLengthM(long h3);
+
     native double hexAreaKm2(int res);
     native double hexAreaM2(int res);
     native double edgeLengthKm(int res);