timezone_finder 0.0.1

data/lib/timezone_finder/gem_version.rb

@@ -0,0 +1,5 @@
+module TimezoneFinder
+  VERSION = '0.0.1' unless defined? TimezoneFinder::Version
+  # https://github.com/MrMinimal64/timezonefinder
+  BASED_SHA1_OF_PYTHON = '55861df0d1ae6c4727e7f48068f7cc51ea3891b3'
+end

data/lib/timezone_finder/helpers.rb

@@ -0,0 +1,357 @@
+# rubocop:disable Metrics/ClassLength,Metrics/MethodLength,Metrics/LineLength
+# rubocop:disable Metrics/AbcSize,Metrics/PerceivedComplexity,Metrics/CyclomaticComplexity,Metrics/ParameterLists
+# rubocop:disable Style/PredicateName,Style/Next
+# rubocop:disable Lint/Void
+module TimezoneFinder
+  class Helpers
+    # tests if a point pX(x,y) is Left|On|Right of an infinite line from p1 to p2
+    #     Return: 2 for pX left of the line from! p1 to! p2
+    #            1 for pX on the line
+    #             0 for pX  right of the line
+    #             this approach is only valid because we already know that y lies within ]y1;y2]
+    def self.position_to_line(x, y, x1, x2, y1, y2)
+      if x1 > x2
+        # p1 is further right than p2
+        if x > x1
+          # pX is further right than p1,
+          if y1 > y2
+            # so it has to be left of the line p1-p2
+            return 2
+          else
+            return 0
+          end
+        end
+
+        if x < x2
+          # pX is further left than p2,
+          if y1 > y2
+            # so it has to be right of the line p1-p2
+            return 0
+          else
+            return 2
+          end
+        end
+
+        # x1 greater than x2
+        x1gtx2 = True
+
+      elsif x1 == x2
+        # this is a vertical line, the position of pX is also determined by y1 and y2
+
+        if y1 > y2
+
+          return 2 if x > x1
+          if x == x1
+            return 1
+          else
+            return 0
+          end
+
+        else
+          return 0 if x > x1
+          if x == x1
+            return 1
+          else
+            return 2
+          end
+        end
+
+      else
+        # p2 is further right than p1
+
+        if x > x2
+          # pX is further right than p2,
+          if y1 > y2
+            return 2
+          else
+            return 0
+          end
+        end
+
+        if x < x1
+          # pX is further left than p1
+          if y1 > y2
+            # so it has to be right of the line p1-p2
+            return 0
+          else
+            return 2
+          end
+        end
+
+        x1gtx2 = False
+      end
+
+      # x is between [x1;x2]
+      # compute the x-intersection of the point with the line p1-p2
+      # delta_y =  cannot be 0 here because of the condition 'y lies within ]y1;y2]'
+      # NOTE: bracket placement is important here (we are dealing with 64-bit ints!). first divide then multiply!
+      x_difference = ((y - y1) * ((x2 - x1).fdiv(y2 - y1))) + x1 - x
+
+      if x_difference > 0
+        if x1gtx2
+          if y1 > y2
+            return 0
+          else
+            return 2
+          end
+
+        else
+          if y1 > y2
+            return 0
+          else
+            return 2
+          end
+        end
+
+      elsif x_difference == 0
+        return 1
+
+      else
+        if x1gtx2
+          if y1 > y2
+            return 2
+          else
+            return 0
+          end
+
+        else
+          if y1 > y2
+            return 2
+          else
+            return 0
+          end
+        end
+      end
+    end
+
+    def self.inside_polygon(x, y, coords)
+      wn = 0
+      i = 0
+      y1 = coords[1][0]
+      # TODO: why start with both y1=y2= y[0]?
+      coords[1].each do |y2|
+        if y1 < y
+          if y2 >= y
+            x1 = coords[0][i - 1]
+            x2 = coords[0][i]
+            # print(long2coord(x), long2coord(y), long2coord(x1), long2coord(x2), long2coord(y1), long2coord(y2),
+            #       position_to_line(x, y, x1, x2, y1, y2))
+            if position_to_line(x, y, x1, x2, y1, y2) == 2
+              # point is left of line
+              # return true when its on the line?! this is very unlikely to happen!
+              # and would need to be checked every time!
+              wn += 1
+            end
+          end
+        else
+          if y2 < y
+            x1 = coords[0][i - 1]
+            x2 = coords[0][i]
+            if position_to_line(x, y, x1, x2, y1, y2) == 0
+              # point is right of line
+              wn -= 1
+            end
+          end
+        end
+
+        y1 = y2
+        i += 1
+      end
+
+      y1 = coords[1][-1]
+      y2 = coords[1][0]
+      if y1 < y
+        if y2 >= y
+          x1 = coords[0][-1]
+          x2 = coords[0][0]
+          if position_to_line(x, y, x1, x2, y1, y2) == 2
+            # point is left of line
+            wn += 1
+          end
+        end
+      else
+        if y2 < y
+          x1 = coords[0][-1]
+          x2 = coords[0][0]
+          if position_to_line(x, y, x1, x2, y1, y2) == 0
+            # point is right of line
+            wn -= 1
+          end
+        end
+      end
+      wn != 0
+    end
+
+    def self.cartesian2rad(x, y, z)
+      [Math.atan2(y, x), Math.asin(z)]
+    end
+
+    def self.radians(x)
+      x * Math::PI / 180.0
+    end
+
+    def self.degrees(x)
+      x * 180.0 / Math::PI
+    end
+
+    def self.cartesian2coords(x, y, z)
+      [degrees(Math.atan2(y, x)), degrees(Math.asin(z))]
+    end
+
+    def self.x_rotate(rad, point)
+      # Attention: this rotation uses radians!
+      # x stays the same
+      sin_rad = Math.sin(rad)
+      cos_rad = Math.cos(rad)
+      [point[0], point[1] * cos_rad + point[2] * sin_rad, point[2] * cos_rad - point[1] * sin_rad]
+    end
+
+    def self.y_rotate(degree, point)
+      # y stays the same
+      degree = radians(-degree)
+      sin_rad = Math.sin(degree)
+      cos_rad = Math.cos(degree)
+      [point[0] * cos_rad - point[2] * sin_rad, point[1], point[0] * sin_rad + point[2] * cos_rad]
+    end
+
+    def self.coords2cartesian(lng, lat)
+      lng = radians(lng)
+      lat = radians(lat)
+      [Math.cos(lng) * Math.cos(lat), Math.sin(lng) * Math.cos(lat), Math.sin(lat)]
+    end
+
+    # uses the simplified haversine formula for this special case
+    # :param lng_rad: the longitude of the point in radians
+    # :param lat_rad: the latitude of the point
+    # :param lng_rad_p1: the latitude of the point1 on the equator (lat=0)
+    # :return: distance between the point and p1 (lng_rad_p1,0) in radians
+    def self.distance_to_point_on_equator(lng_rad, lat_rad, lng_rad_p1)
+      2 * Math.asin(Math.sqrt((Math.sin(lat_rad) / 2)**2 + Math.cos(lat_rad) * Math.sin((lng_rad - lng_rad_p1) / 2.0)**2))
+    end
+
+    # :param lng_p1: the longitude of point 1 in radians
+    # :param lat_p1: the latitude of point 1 in radians
+    # :param lng_p2: the longitude of point 1 in radians
+    # :param lat_p2: the latitude of point 1 in radians
+    # :return: distance between p1 and p2 in radians
+    def self.haversine(lng_p1, lat_p1, lng_p2, lat_p2)
+      2 * Math.asin(Math.sqrt(Math.sin((lat_p1 - lat_p2) / 2.0)**2 + Math.cos(lat_p2) * Math.cos(lat_p1) * Math.sin((lng_p1 - lng_p2) / 2.0)**2))
+    end
+
+    # :param lng: lng of px in degree
+    # :param lat: lat of px in degree
+    # :param p0_lng: lng of p0 in degree
+    # :param p0_lat: lat of p0 in degree
+    # :param pm1_lng: lng of pm1 in degree
+    # :param pm1_lat: lat of pm1 in degree
+    # :param p1_lng: lng of p1 in degree
+    # :param p1_lat: lat of p1 in degree
+    # :return: shortest distance between pX and the polygon section (pm1---p0---p1) in radians
+    def self.compute_min_distance(lng, lat, p0_lng, p0_lat, pm1_lng, pm1_lat, p1_lng, p1_lat)
+      # rotate coordinate system (= all the points) so that p0 would have lat=lng=0 (=origin)
+      # z rotation is simply substracting the lng
+      # convert the points to the cartesian coorinate system
+      px_cartesian = coords2cartesian(lng - p0_lng, lat)
+      p1_cartesian = coords2cartesian(p1_lng - p0_lng, p1_lat)
+      pm1_cartesian = coords2cartesian(pm1_lng - p0_lng, pm1_lat)
+
+      px_cartesian = y_rotate(p0_lat, px_cartesian)
+      p1_cartesian = y_rotate(p0_lat, p1_cartesian)
+      pm1_cartesian = y_rotate(p0_lat, pm1_cartesian)
+
+      # for both p1 and pm1 separately do:
+
+      # rotate coordinate system so that this point also has lat=0 (p0 does not change!)
+      rotation_rad = Math.atan2(p1_cartesian[2], p1_cartesian[1])
+      p1_cartesian = x_rotate(rotation_rad, p1_cartesian)
+      lng_p1_rad = Math.atan2(p1_cartesian[1], p1_cartesian[0])
+      px_retrans_rad = cartesian2rad(*x_rotate(rotation_rad, px_cartesian))
+
+      # if lng of px is between 0 (<-point1) and lng of point 2:
+      # the distance between point x and the 'equator' is the shortest
+      # if the point is not between p0 and p1 the distance to the closest of the two points should be used
+      # so clamp/clip the lng of px to the interval of [0; lng p1] and compute the distance with it
+      temp_distance = distance_to_point_on_equator(px_retrans_rad[0], px_retrans_rad[1],
+                                                   [[px_retrans_rad[0], lng_p1_rad].min, 0].max)
+
+      # ATTENTION: vars are being reused. p1 is actually pm1 here!
+      rotation_rad = Math.atan2(pm1_cartesian[2], pm1_cartesian[1])
+      p1_cartesian = x_rotate(rotation_rad, pm1_cartesian)
+      lng_p1_rad = Math.atan2(p1_cartesian[1], p1_cartesian[0])
+      px_retrans_rad = cartesian2rad(*x_rotate(rotation_rad, px_cartesian))
+
+      [
+        temp_distance,
+        distance_to_point_on_equator(px_retrans_rad[0], px_retrans_rad[1],
+                                     [[px_retrans_rad[0], lng_p1_rad].min, 0].max)
+      ].min
+    end
+
+    def self.int2coord(int32)
+      int32.fdiv(10**7)
+    end
+
+    def self.coord2int(double)
+      (double * 10**7).to_i
+    end
+
+    def self.distance_to_polygon(lng, lat, nr_points, points, trans_points)
+      # transform all points (long long) to coords
+      (0...nr_points).each do |i|
+        trans_points[0][i] = int2coord(points[0][i])
+        trans_points[1][i] = int2coord(points[1][i])
+      end
+
+      # check points -2, -1, 0 first
+      pm1_lng = trans_points[0][0]
+      pm1_lat = trans_points[1][0]
+
+      p1_lng = trans_points[0][-2]
+      p1_lat = trans_points[1][-2]
+      min_distance = compute_min_distance(lng, lat, trans_points[0][-1], trans_points[1][-1], pm1_lng, pm1_lat, p1_lng,
+                                          p1_lat)
+
+      index_p0 = 1
+      index_p1 = 2
+      (0...(((nr_points / 2.0) - 1).ceil.to_i)).each do |_i|
+        p1_lng = trans_points[0][index_p1]
+        p1_lat = trans_points[1][index_p1]
+
+        distance = compute_min_distance(lng, lat, trans_points[0][index_p0], trans_points[1][index_p0], pm1_lng,
+                                        pm1_lat, p1_lng, p1_lat)
+        min_distance = distance if distance < min_distance
+
+        index_p0 += 2
+        index_p1 += 2
+        pm1_lng = p1_lng
+        pm1_lat = p1_lat
+      end
+
+      min_distance
+    end
+
+    # Ruby original
+    # like numpy.fromfile
+    def self.fromfile(file, unsigned, byte_width, count)
+      if unsigned
+        case byte_width
+        when 2
+          unpack_format = 'S>*'
+        end
+      else
+        case byte_width
+        when 4
+          unpack_format = 'l>*'
+        when 8
+          unpack_format = 'q>*'
+        end
+      end
+
+      unless unpack_format
+        fail "#{unsigned ? 'unsigned' : 'signed'} #{byte_width}-byte width is not supported in fromfile"
+      end
+
+      file.read(count * byte_width).unpack(unpack_format)
+    end
+  end
+end

data/lib/timezone_finder/timezone_finder.rb

@@ -0,0 +1,279 @@
+# rubocop:disable Metrics/ClassLength,Metrics/MethodLength,Metrics/LineLength
+# rubocop:disable Metrics/AbcSize,Metrics/PerceivedComplexity,Metrics/CyclomaticComplexity,Metrics/ParameterLists
+# rubocop:disable Style/PredicateName,Style/Next,Style/AndOr
+# rubocop:disable Lint/Void
+require_relative 'helpers'
+require_relative 'timezone_names'
+
+module TimezoneFinder
+  # This class lets you quickly find the timezone of a point on earth.
+  # It keeps the binary file with the timezonefinder open in reading mode to enable fast consequent access.
+  # In the file currently used there are two shortcuts stored per degree of latitude and one per degree of longitude
+  # (tests evaluated this to be the fastest setup when being used with numba)
+  class TimezoneFinder
+    def initialize
+      # open the file in binary reading mode
+      @binary_file = open(File.join(File.dirname(__FILE__), 'timezone_data.bin'), 'rb')
+
+      # for more info on what is stored how in the .bin please read the comments in file_converter
+      # read the first 2byte int (= number of polygons stored in the .bin)
+      @nr_of_entries = @binary_file.read(2).unpack('S>')[0]
+
+      # set addresses
+      # the address where the shortcut section starts (after all the polygons) this is 34 433 054
+      @shortcuts_start = @binary_file.read(4).unpack('L>')[0]
+
+      @nr_val_start_address = 2 * @nr_of_entries + 6
+      @adr_start_address = 4 * @nr_of_entries + 6
+      @bound_start_address = 8 * @nr_of_entries + 6
+      # @poly_start_address = 40 * @nr_of_entries + 6
+      @poly_start_address = 24 * @nr_of_entries + 6
+      @first_shortcut_address = @shortcuts_start + 259_200
+
+      ObjectSpace.define_finalizer(self, self.class.__del__)
+    end
+
+    def self.__del__
+      proc do
+        @binary_file.close
+      end
+    end
+
+    def id_of(line = 0)
+      # ids start at address 6. per line one unsigned 2byte int is used
+      @binary_file.seek((6 + 2 * line))
+      @binary_file.read(2).unpack('S>')[0]
+    end
+
+    def ids_of(iterable)
+      id_array = [0] * iterable.length
+
+      i = 0
+      iterable.each do |line_nr|
+        @binary_file.seek((6 + 2 * line_nr))
+        id_array[i] = @binary_file.read(2).unpack('S>')[0]
+        i += 1
+      end
+
+      id_array
+    end
+
+    def shortcuts_of(lng = 0.0, lat = 0.0)
+      # convert coords into shortcut
+      x = (lng + 180).floor.to_i
+      y = ((90 - lat) * 2).floor.to_i
+
+      # get the address of the first entry in this shortcut
+      # offset: 180 * number of shortcuts per lat degree * 2bytes = entries per column of x shortcuts
+      # shortcuts are stored: (0,0) (0,1) (0,2)... (1,0)...
+      @binary_file.seek(@shortcuts_start + 720 * x + 2 * y)
+
+      nr_of_polygons = @binary_file.read(2).unpack('S>')[0]
+
+      @binary_file.seek(@first_shortcut_address + 1440 * x + 4 * y)
+      @binary_file.seek(@binary_file.read(4).unpack('L>')[0])
+      Helpers.fromfile(@binary_file, true, 2, nr_of_polygons)
+    end
+
+    def polygons_of_shortcut(x = 0, y = 0)
+      # get the address of the first entry in this shortcut
+      # offset: 180 * number of shortcuts per lat degree * 2bytes = entries per column of x shortcuts
+      # shortcuts are stored: (0,0) (0,1) (0,2)... (1,0)...
+      @binary_file.seek(@shortcuts_start + 720 * x + 2 * y)
+
+      nr_of_polygons = @binary_file.read(2).unpack('S>')[0]
+
+      @binary_file.seek(@first_shortcut_address + 1440 * x + 4 * y)
+      @binary_file.seek(@binary_file.read(4).unpack('L>')[0])
+      Helpers.fromfile(@binary_file, true, 2, nr_of_polygons)
+    end
+
+    def coords_of(line = 0)
+      @binary_file.seek((@nr_val_start_address + 2 * line))
+      nr_of_values = @binary_file.read(2).unpack('S>')[0]
+
+      @binary_file.seek(@adr_start_address + 4 * line)
+      @binary_file.seek(@binary_file.read(4).unpack('L>')[0])
+
+      # return [Helpers.fromfile(@binary_file, false, 8, nr_of_values),
+      #         Helpers.fromfile(@binary_file, false, 8, nr_of_values)]
+
+      [Helpers.fromfile(@binary_file, false, 4, nr_of_values),
+       Helpers.fromfile(@binary_file, false, 4, nr_of_values)]
+    end
+
+    # @profile
+    # This function searches for the closest polygon in the surrounding shortcuts.
+    # Make sure that the point does not lie within a polygon (for that case the algorithm is simply wrong!)
+    # Note that the algorithm won't find the closest polygon when it's on the 'other end of earth'
+    # (it can't search beyond the 180 deg lng border yet)
+    # this checks all the polygons within [delta_degree] degree lng and lat
+    # Keep in mind that x degrees lat are not the same distance apart than x degree lng!
+    # :param lng: longitude of the point in degree
+    # :param lat: latitude in degree
+    # :param delta_degree: the 'search radius' in degree
+    # :return: the timezone name of the closest found polygon or None
+    def closest_timezone_at(lng, lat, delta_degree = 1)
+      if lng > 180.0 or lng < -180.0 or lat > 90.0 or lat < -90.0
+        fail "The coordinates are out ouf bounds: (#{lng}, #{lat})"
+      end
+
+      # the maximum possible distance is pi = 3.14...
+      min_distance = 4
+      # transform point X into cartesian coordinates
+      current_closest_id = nil
+      central_x_shortcut = (lng + 180).floor.to_i
+      central_y_shortcut = ((90 - lat) * 2).floor.to_i
+
+      polygon_nrs = []
+
+      # there are 2 shortcuts per 1 degree lat, so to cover 1 degree two shortcuts (rows) have to be checked
+      # the highest shortcut is 0
+      top = [central_y_shortcut - 2 * delta_degree, 0].max
+      # the lowest shortcut is 360 (= 2 shortcuts per 1 degree lat)
+      bottom = [central_y_shortcut + 2 * delta_degree, 360].min
+
+      # the most left shortcut is 0
+      left = [central_x_shortcut - delta_degree, 0].max
+      # the most right shortcut is 360 (= 1 shortcuts per 1 degree lng)
+      right = [central_x_shortcut + delta_degree, 360].min
+
+      # select all the polygons from the surrounding shortcuts
+      (left..right).each do |x|
+        (top..bottom).each do |y|
+          polygons_of_shortcut(x, y).each do |p|
+            polygon_nrs << p if polygon_nrs.index(p).nil?
+          end
+        end
+      end
+
+      polygons_in_list = polygon_nrs.length
+
+      return nil if polygons_in_list == 0
+
+      # initialize the list of ids
+      ids = polygon_nrs.map { |x| id_of(x) }
+
+      # if all the polygons in this shortcut belong to the same zone return it
+      first_entry = ids[0]
+      return TIMEZONE_NAMES[first_entry] if ids.count(first_entry) == polygons_in_list
+
+      # stores which polygons have been checked yet
+      already_checked = [false] * polygons_in_list
+
+      pointer = 0
+      polygons_checked = 0
+
+      while polygons_checked < polygons_in_list
+        # only check a polygon when its id is not the closest a the moment!
+        if already_checked[pointer] or ids[pointer] == current_closest_id
+          # go to the next polygon
+          polygons_checked += 1
+
+        else
+          # this polygon has to be checked
+          coords = coords_of(polygon_nrs[pointer])
+          nr_points = coords[0].length
+          empty_array = [[0.0] * nr_points, [0.0] * nr_points]
+          distance = Helpers.distance_to_polygon(lng, lat, nr_points, coords, empty_array)
+
+          already_checked[pointer] = true
+          if distance < min_distance
+            min_distance = distance
+            current_closest_id = ids[pointer]
+            # whole list has to be searched again!
+            polygons_checked = 1
+          end
+        end
+        pointer = (pointer + 1) % polygons_in_list
+      end
+
+      # the the whole list has been searched
+      TIMEZONE_NAMES[current_closest_id]
+    end
+
+    # this function looks up in which polygons the point could be included
+    # to speed things up there are shortcuts being used (stored in the binary file)
+    # especially for large polygons it is expensive to check if a point is really included,
+    # so certain simplifications are made and even when you get a hit the point might actually
+    # not be inside the polygon (for example when there is only one timezone nearby)
+    # if you want to make sure a point is really inside a timezone use 'certain_timezone_at'
+    # :param lng: longitude of the point in degree (-180 to 180)
+    # :param lat: latitude in degree (90 to -90)
+    # :return: the timezone name of the matching polygon or None
+    def timezone_at(lng = 0.0, lat = 0.0)
+      if lng > 180.0 or lng < -180.0 or lat > 90.0 or lat < -90.0
+        fail "The coordinates are out ouf bounds: (#{lng}, #{lat})"
+      end
+
+      possible_polygons = shortcuts_of(lng, lat)
+
+      # x = longitude  y = latitude  both converted to 8byte int
+      x = Helpers.coord2int(lng)
+      y = Helpers.coord2int(lat)
+
+      nr_possible_polygons = possible_polygons.length
+
+      return nil if nr_possible_polygons == 0
+
+      return TIMEZONE_NAMES[id_of(possible_polygons[0])] if nr_possible_polygons == 1
+
+      # initialize the list of ids
+      ids = possible_polygons.map { |p| id_of(p) }
+
+      # if all the polygons belong to the same zone return it
+      first_entry = ids[0]
+      if ids.count(first_entry) == nr_possible_polygons
+        return TIMEZONE_NAMES[first_entry]
+      end
+
+      # otherwise check if the point is included for all the possible polygons
+      (0...nr_possible_polygons).each do |i|
+        polygon_nr = possible_polygons[i]
+
+        # get the boundaries of the polygon = (lng_max, lng_min, lat_max, lat_min)
+        # self.binary_file.seek((@bound_start_address + 32 * polygon_nr), )
+        @binary_file.seek((@bound_start_address + 16 * polygon_nr))
+        boundaries = Helpers.fromfile(@binary_file, false, 4, 4)
+        # only run the algorithm if it the point is withing the boundaries
+        unless x > boundaries[0] or x < boundaries[1] or y > boundaries[2] or y < boundaries[3]
+
+          if Helpers.inside_polygon(x, y, coords_of(polygon_nr))
+            return TIMEZONE_NAMES[ids[i]]
+          end
+        end
+      end
+      nil
+    end
+
+    # this function looks up in which polygon the point certainly is included
+    # this is much slower than 'timezone_at'!
+    # :param lng: longitude of the point in degree
+    # :param lat: latitude in degree
+    # :return: the timezone name of the polygon the point is included in or None
+    def certain_timezone_at(lng = 0.0, lat = 0.0)
+      if lng > 180.0 or lng < -180.0 or lat > 90.0 or lat < -90.0
+        fail "The coordinates are out ouf bounds: (#{lng}, #{lat})"
+      end
+
+      possible_polygons = shortcuts_of(lng, lat)
+
+      # x = longitude  y = latitude  both converted to 8byte int
+      x = Helpers.coord2int(lng)
+      y = Helpers.coord2int(lat)
+
+      possible_polygons.each do |polygon_nr|
+        # get boundaries
+        @binary_file.seek((@bound_start_address + 16 * polygon_nr))
+        boundaries = Helpers.fromfile(@binary_file, false, 4, 4)
+        unless x > boundaries[0] or x < boundaries[1] or y > boundaries[2] or y < boundaries[3]
+          if Helpers.inside_polygon(x, y, coords_of(polygon_nr))
+            fail id_of(polygon_nr) if id_of(polygon_nr) >= 424
+            return TIMEZONE_NAMES[id_of(polygon_nr)]
+          end
+        end
+      end
+      nil
+    end
+  end
+end