Refactor GeoHashUtils

libs/geo/src/main/java/org/elasticsearch/geo/geometry/Rectangle.java

@@ -163,6 +163,14 @@ public boolean crossesDateline() {
         return maxLon < minLon;
     }
 
+    /** returns true if rectangle (defined by minLat, maxLat, minLon, maxLon) contains the lat lon point */
+    public boolean containsPoint(final double lat, final double lon) {
+        if (lat >= minLat && lat <= maxLat) {
+            return crossesDateline() ? lon >= minLon || lon <= maxLon : lon >= minLon && lon <= maxLon;
+        }
+        return false;
+    }
+
     @Override
     public boolean equals(Object o) {
         if (this == o) return true;

libs/geo/src/main/java/org/elasticsearch/geo/utils/BitUtil.java

@@ -0,0 +1,75 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.elasticsearch.geo.utils;
+
+/**
+ * Utilities for common Bit twiddling methods. Borrowed heavily from Lucene (org.apache.lucene.util.BitUtil).
+ */
+public class BitUtil {  // magic numbers for bit interleaving
+    private static final long MAGIC[] = {
+        0x5555555555555555L, 0x3333333333333333L,
+        0x0F0F0F0F0F0F0F0FL, 0x00FF00FF00FF00FFL,
+        0x0000FFFF0000FFFFL, 0x00000000FFFFFFFFL,
+        0xAAAAAAAAAAAAAAAAL
+    };
+    // shift values for bit interleaving
+    private static final short SHIFT[] = {1, 2, 4, 8, 16};
+
+    /**
+     * Interleaves the first 32 bits of each long value
+     *
+     * Adapted from: http://graphics.stanford.edu/~seander/bithacks.html#InterleaveBMN
+     */
+    public static long interleave(int even, int odd) {
+        long v1 = 0x00000000FFFFFFFFL & even;
+        long v2 = 0x00000000FFFFFFFFL & odd;
+        v1 = (v1 | (v1 << SHIFT[4])) & MAGIC[4];
+        v1 = (v1 | (v1 << SHIFT[3])) & MAGIC[3];
+        v1 = (v1 | (v1 << SHIFT[2])) & MAGIC[2];
+        v1 = (v1 | (v1 << SHIFT[1])) & MAGIC[1];
+        v1 = (v1 | (v1 << SHIFT[0])) & MAGIC[0];
+        v2 = (v2 | (v2 << SHIFT[4])) & MAGIC[4];
+        v2 = (v2 | (v2 << SHIFT[3])) & MAGIC[3];
+        v2 = (v2 | (v2 << SHIFT[2])) & MAGIC[2];
+        v2 = (v2 | (v2 << SHIFT[1])) & MAGIC[1];
+        v2 = (v2 | (v2 << SHIFT[0])) & MAGIC[0];
+
+        return (v2<<1) | v1;
+    }
+
+    /**
+     * Extract just the even-bits value as a long from the bit-interleaved value
+     */
+    public static long deinterleave(long b) {
+        b &= MAGIC[0];
+        b = (b ^ (b >>> SHIFT[0])) & MAGIC[1];
+        b = (b ^ (b >>> SHIFT[1])) & MAGIC[2];
+        b = (b ^ (b >>> SHIFT[2])) & MAGIC[3];
+        b = (b ^ (b >>> SHIFT[3])) & MAGIC[4];
+        b = (b ^ (b >>> SHIFT[4])) & MAGIC[5];
+        return b;
+    }
+
+    /**
+     * flip flops odd with even bits
+     */
+    public static final long flipFlop(final long b) {
+        return ((b & MAGIC[6]) >>> 1) | ((b & MAGIC[0]) << 1 );
+    }
+}

libs/geo/src/main/java/org/elasticsearch/geo/utils/Geohash.java

@@ -0,0 +1,256 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.elasticsearch.geo.utils;
+
+import org.elasticsearch.geo.geometry.Point;
+import org.elasticsearch.geo.geometry.Rectangle;
+
+import java.util.ArrayList;
+import java.util.Collection;
+
+/**
+ * Utilities for converting to/from the GeoHash standard
+ *
+ * The geohash long format is represented as lon/lat (x/y) interleaved with the 4 least significant bits
+ * representing the level (1-12) [xyxy...xyxyllll]
+ *
+ * This differs from a morton encoded value which interleaves lat/lon (y/x).
+ *
+ * NOTE: this will replace {@code org.elasticsearch.common.geo.GeoHashUtils}
+ */
+public class Geohash {
+    private static final char[] BASE_32 = {'0', '1', '2', '3', '4', '5', '6',
+        '7', '8', '9', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'j', 'k', 'm', 'n',
+        'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z'};
+
+    private static final String BASE_32_STRING = new String(BASE_32);
+    /** maximum precision for geohash strings */
+    private static final int PRECISION = 12;
+    /** number of bits used for quantizing latitude and longitude values */
+    private static final short BITS = 31;
+    private static final double LAT_SCALE = (0x1L<<BITS)/180.0D;
+    private static final double LON_SCALE = (0x1L<<BITS)/360.0D;
+    private static final short MORTON_OFFSET = (BITS<<1) - (PRECISION*5);
+    /** Bit encoded representation of the latitude of north pole */
+    private static final long MAX_LAT_BITS = (0x1L << (PRECISION * 5 / 2)) - 1;
+
+
+    /** Returns a {@link Point} instance from a geohash string */
+    public static Point toPoint(final String geohash) throws IllegalArgumentException {
+        final long hash = mortonEncode(geohash);
+        return new Point(decodeLatitude(hash), decodeLongitude(hash));
+    }
+
+    /**
+     * Computes the bounding box coordinates from a given geohash
+     *
+     * @param geohash Geohash of the defined cell
+     * @return GeoRect rectangle defining the bounding box
+     */
+    public static Rectangle toBoundingBox(final String geohash) {
+        // bottom left is the coordinate
+        Point bottomLeft = toPoint(geohash);
+        int len = Math.min(12, geohash.length());
+        long ghLong = longEncode(geohash, len);
+        // shift away the level
+        ghLong >>>= 4;
+        // deinterleave
+        long lon = BitUtil.deinterleave(ghLong >>> 1);
+        long lat = BitUtil.deinterleave(ghLong);
+        if (lat < MAX_LAT_BITS) {
+            // add 1 to lat and lon to get topRight
+            Point topRight = new Point(unscaleLat((lat + 1) << 2), unscaleLon((lon + 1) << 2));
+            return new Rectangle(bottomLeft.getLat(), topRight.getLat(), bottomLeft.getLon(), topRight.getLon());
+        } else {
+            // We cannot go north of north pole, so just using 90 degrees instead of calculating it using
+            // add 1 to lon to get lon of topRight, we are going to use 90 for lat
+            Point topRight = new Point(unscaleLat(lat << 2), unscaleLon((lon + 1) << 2));
+            return new Rectangle(bottomLeft.getLat(), 90D, bottomLeft.getLon(), topRight.getLon());
+        }
+    }
+
+    /**
+     * Calculate all neighbors of a given geohash cell.
+     *
+     * @param geohash Geohash of the defined cell
+     * @return geohashes of all neighbor cells
+     */
+    public static Collection<? extends CharSequence> getNeighbors(String geohash) {
+        return addNeighborsAtLevel(geohash, geohash.length(), new ArrayList<CharSequence>(8));
+    }
+    /**
+     * Add all geohashes of the cells next to a given geohash to a list.
+     *
+     * @param geohash   Geohash of a specified cell
+     * @param neighbors list to add the neighbors to
+     * @return the given list
+     */
+    public static final <E extends Collection<? super String>> E addNeighbors(String geohash, E neighbors) {
+        return addNeighborsAtLevel(geohash, geohash.length(), neighbors);
+    }
+
+    /**
+     * Add all geohashes of the cells next to a given geohash to a list.
+     *
+     * @param geohash   Geohash of a specified cell
+     * @param level    level of the given geohash
+     * @param neighbors list to add the neighbors to
+     * @return the given list
+     */
+    public static final <E extends Collection<? super String>> E addNeighborsAtLevel(String geohash,
+                                                                                     int level, E neighbors) {
+        String south = getNeighbor(geohash, level, 0, -1);
+        String north = getNeighbor(geohash, level, 0, +1);
+        if (north != null) {
+            neighbors.add(getNeighbor(north, level, -1, 0));
+            neighbors.add(north);
+            neighbors.add(getNeighbor(north, level, +1, 0));
+        }
+
+        neighbors.add(getNeighbor(geohash, level, -1, 0));
+        neighbors.add(getNeighbor(geohash, level, +1, 0));
+
+        if (south != null) {
+            neighbors.add(getNeighbor(south, level, -1, 0));
+            neighbors.add(south);
+            neighbors.add(getNeighbor(south, level, +1, 0));
+        }
+
+        return neighbors;
+    }
+
+    /**
+     * Calculate the geohash of a neighbor of a geohash
+     *
+     * @param geohash the geohash of a cell
+     * @param level   level of the geohash
+     * @param dx      delta of the first grid coordinate (must be -1, 0 or +1)
+     * @param dy      delta of the second grid coordinate (must be -1, 0 or +1)
+     * @return geohash of the defined cell
+     */
+    public static final String getNeighbor(String geohash, int level, int dx, int dy) {
+        int cell = BASE_32_STRING.indexOf(geohash.charAt(level -1));
+
+        // Decoding the Geohash bit pattern to determine grid coordinates
+        int x0 = cell & 1;  // first bit of x
+        int y0 = cell & 2;  // first bit of y
+        int x1 = cell & 4;  // second bit of x
+        int y1 = cell & 8;  // second bit of y
+        int x2 = cell & 16; // third bit of x
+
+        // combine the bitpattern to grid coordinates.
+        // note that the semantics of x and y are swapping
+        // on each level
+        int x = x0 + (x1 / 2) + (x2 / 4);
+        int y = (y0 / 2) + (y1 / 4);
+
+        if (level == 1) {
+            // Root cells at north (namely "bcfguvyz") or at
+            // south (namely "0145hjnp") do not have neighbors
+            // in north/south direction
+            if ((dy < 0 && y == 0) || (dy > 0 && y == 3)) {
+                return null;
+            } else {
+                return Character.toString(encodeBase32(x + dx, y + dy));
+            }
+        } else {
+            // define grid coordinates for next level
+            final int nx = ((level % 2) == 1) ? (x + dx) : (x + dy);
+            final int ny = ((level % 2) == 1) ? (y + dy) : (y + dx);
+
+            // if the defined neighbor has the same parent a the current cell
+            // encode the cell directly. Otherwise find the cell next to this
+            // cell recursively. Since encoding wraps around within a cell
+            // it can be encoded here.
+            // xLimit and YLimit must always be respectively 7 and 3
+            // since x and y semantics are swapping on each level.
+            if (nx >= 0 && nx <= 7 && ny >= 0 && ny <= 3) {
+                return geohash.substring(0, level - 1) + encodeBase32(nx, ny);
+            } else {
+                String neighbor = getNeighbor(geohash, level - 1, dx, dy);
+                return (neighbor != null) ? neighbor + encodeBase32(nx, ny) : neighbor;
+            }
+        }
+    }
+
+    /** base32 encode at the given grid coordinate */
+    private static char encodeBase32(int x, int y) {
+        return BASE_32[((x & 1) + ((y & 1) * 2) + ((x & 2) * 2) + ((y & 2) * 4) + ((x & 4) * 4)) % 32];
+    }
+
+    /**
+     * Encode from geohash string to the geohash based long format (lon/lat interleaved, 4 least significant bits = level)
+     */
+    private static long longEncode(final String hash, int length) {
+        int level = length - 1;
+        long b;
+        long l = 0L;
+        for(char c : hash.toCharArray()) {
+            b = (long)(BASE_32_STRING.indexOf(c));
+            l |= (b<<(level--*5));
+            if (level < 0) {
+                // We cannot handle more than 12 levels
+                break;
+            }
+        }
+        return (l << 4) | length;
+    }
+
+    /**
+     * Encode to a morton long value from a given geohash string
+     */
+    private static final long mortonEncode(final String hash) {
+        if (hash.isEmpty()) {
+            throw new IllegalArgumentException("empty geohash");
+        }
+        int level = 11;
+        long b;
+        long l = 0L;
+        for(char c : hash.toCharArray()) {
+            b = (long)(BASE_32_STRING.indexOf(c));
+            if (b < 0) {
+                throw new IllegalArgumentException("unsupported symbol [" + c + "] in geohash [" + hash + "]");
+            }
+            l |= (b<<((level--*5) + MORTON_OFFSET));
+            if (level < 0) {
+                // We cannot handle more than 12 levels
+                break;
+            }
+        }
+        return BitUtil.flipFlop(l);
+    }
+
+    /** decode longitude value from morton encoded geo point */
+    private static final double decodeLongitude(final long hash) {
+        return unscaleLon(BitUtil.deinterleave(hash));
+    }
+
+    /** decode latitude value from morton encoded geo point */
+    private static final double decodeLatitude(final long hash) {
+        return unscaleLat(BitUtil.deinterleave(hash >>> 1));
+    }
+
+    private static double unscaleLon(final long val) {
+        return (val / LON_SCALE) - 180;
+    }
+
+    private static double unscaleLat(final long val) {
+        return (val / LAT_SCALE) - 90;
+    }
+}