timezone_finder 1.5.5 → 1.5.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 13d427ec4275e9a9cf091179165cdaee2c427f08
-  data.tar.gz: bd258529875fec7b818f7839c2a116ff6a29e434
+  metadata.gz: e74c3bfc9784467f66b1c270bc2473168e8b8838
+  data.tar.gz: c5bce138f2d33d467b46a3cdf8bfd214e3d01971
 SHA512:
-  metadata.gz: a7e3da84f42cc2b1a55c06cfd0ceb35119be8dce2c549a1872fd7f32f3373685582891d34800d03456111e3b89c3c55bda86902a8ff62aa3699077e3e72c525b
-  data.tar.gz: 48374abaab46b420242964dd2373899b4d602f10605964f7497b7580f24200af8d62e99b6f551ea32b79c446dfc2b6cf266d41cfbdad58328f0722c4e9b2097c
+  metadata.gz: 205cb31ffe251b8c2104fbe97f4535462d94a1a71625f7e090ecdb05937fd9c79861e8c912858d344ff6cf6b8aa8e00ab720c5d48f62ac2fa82010b0b3e1d4b9
+  data.tar.gz: c183ace8223052a82150e8627e91779647be2ca83ee83b33ca456c0033c56eecb2e40e315d70734794232cca6f6db355db4e015b4fdf7ebbcd4e283e5c39dad3

data/ChangeLog

@@ -1,3 +1,11 @@
+== 2016-06-19 version 1.5.6
+
+* using little endian encoding now
+* introduced test for checking the proper functionality of the helper functions
+* wrote tests for proximity algorithms
+* improved proximity algorithms: introduced exact_computation, return_distances and force_evaluation functionality (s. Readme or documentation for more info)
+
+
 == 2016-06-03 version 1.5.5
 
 * using the newest version (2016d, May 2016) of the tz_world data from http://efele.net/maps/tz/world/

data/README.md

@@ -34,10 +34,13 @@ require 'timezone_finder'
 tf = TimezoneFinder.create
 ```
 
-#### fast algorithm:
+#### timezone\_at():
 
-This approach is fast, but might not be what you are looking for:
-For example when there is only one possible timezone in proximity, this timezone would be returned (without checking if the point is included first).
+This is the default function to check which timezone a point lies in.
+If no timezone has been found, `nil` is being returned.
+**NOTE:** This approach is optimized for speed and the common case to only query points actually within a timezone.
+This might not be what you are looking for however: When there is only one possible timezone in proximity, this timezone would be returned
+(without checking if the point is included first).
 
 ```ruby
 # point = (longitude, latitude)
@@ -46,36 +49,53 @@ puts tf.timezone_at(*point)
 # = Europe/Berlin
 ```
 
-#### To make sure a point is really inside a timezone (slower):
+#### certain\_timezone\_at()
+
+This function is for making sure a point is really inside a timezone. It is slower, because all polygons (with shortcuts in that area)
+are checked until one polygon is matched.
 
 ```ruby
 puts tf.certain_timezone_at(*point)
 # = Europe/Berlin
 ```
 
-#### To find the closest timezone (slow):
+#### Proximity algorithm
+
+Only use this when the point is not inside a polygon, because the approach otherwise makes no sense.
+This returns the closest timezone of all polygons within +-1 degree lng and +-1 degree lat (or None).
 
 ```ruby
-# only use this when the point is not inside a polygon!
-# this checks all the polygons within +-1 degree lng and +-1 degree lat
 point = (12.773955, 55.578595)
 puts tf.closest_timezone_at(*point)
 # = Europe/Copenhagens
 ```
 
-#### To increase search radius even more (very slow):
+#### Other options:
+
+To increase search radius even more, use the `delta_degree`-option:
 
 ```ruby
-# this checks all the polygons within +-3 degree lng and +-3 degree lat
-# I recommend only slowly increasing the search radius
-# keep in mind that x degrees lat are not the same distance apart than x degree lng!
 puts tf.closest_timezone_at(*point, 3)
 # = Europe/Copenhagens
 ```
 
-(to make sure you really got the closest timezone increase the search
-radius until you get a result. then increase the radius once more and
-take this result.)
+This checks all the polygons within +-3 degree lng and +-3 degree lat.
+I recommend only slowly increasing the search radius, since computation time increases quite quickly
+(with the amount of polygons which need to be evaluated) and there might be many polygons within a couple degrees.
+
+Also keep in mind that x degrees lat are not the same distance apart than x degree lng (earth is a sphere)!
+So to really make sure you got the closest timezone increase the search radius until you get a result,
+then increase the radius once more and take this result. (this should only make a difference in really rare cases)
+
+With `exact_computation=true` the distance to every polygon edge is computed (way more complicated)
+, instead of just evaluating the distances to all the vertices. This only makes a real difference when polygons are very close.
+
+With `return_distances=true` the output looks like this:
+
+[ 'tz_name_of_the_closest_polygon',[ distances to every polygon in km], [tz_names of every polygon]]
+
+Note that some polygons might not be tested (for example when a zone is found to be the closest already).
+To prevent this use `force_evaluation=true`.
 
 ## Developer
 

data/lib/timezone_finder/file_converter.rb

@@ -102,6 +102,8 @@ module TimezoneFinder
     def parse_polygons_from_json(path = 'tz_world.json')
       f = open(path, 'r')
       puts 'Parsing data from .json'
+      puts 'encountered holes at: '
+
       # file_line is the current line in the .json file being parsed. This is not the id of the Polygon!
       file_line = 0
       f.each_line do |row|
@@ -671,7 +673,7 @@ EOT
 
       puts("number of filled shortcut zones are: #{amount_filled_shortcuts} (=#{(amount_filled_shortcuts.fdiv(amount_of_shortcuts) * 100).round(2)}% of all shortcuts)")
 
-      # for every shortcut S> and L> is written (nr of entries and address)
+      # for every shortcut S< and L< is written (nr of entries and address)
       shortcut_space = 360 * NR_SHORTCUTS_PER_LNG * 180 * NR_SHORTCUTS_PER_LAT * 6
       nr_of_entries_in_shortcut.each do |nr|
         # every line in every shortcut takes up 2bytes
@@ -685,28 +687,28 @@ EOT
       puts("now writing file \"#{path}\"")
       output_file = open(path, 'wb')
       # write nr_of_lines
-      output_file.write([@nr_of_lines].pack('S>'))
+      output_file.write([@nr_of_lines].pack('S<'))
       # write start address of shortcut_data:
-      output_file.write([shortcut_start_address].pack('L>'))
+      output_file.write([shortcut_start_address].pack('L<'))
 
-      # S> amount of holes
-      output_file.write([@amount_of_holes].pack('S>'))
+      # S< amount of holes
+      output_file.write([@amount_of_holes].pack('S<'))
 
-      # L> Address of Hole area (end of shortcut area +1) @ 8
-      output_file.write([hole_start_address].pack('L>'))
+      # L< Address of Hole area (end of shortcut area +1) @ 8
+      output_file.write([hole_start_address].pack('L<'))
 
       # write zone_ids
       zone_ids.each do |zone_id|
-        output_file.write([zone_id].pack('S>'))
+        output_file.write([zone_id].pack('S<'))
       end
       # write number of values
       @all_lengths.each do |length|
-        output_file.write([length].pack('S>'))
+        output_file.write([length].pack('S<'))
       end
 
       # write polygon_addresses
       @all_lengths.each do |length|
-        output_file.write([polygon_address].pack('L>'))
+        output_file.write([polygon_address].pack('L<'))
         # data of the next polygon is at the address after all the space the points take
         # nr of points stored * 2 ints per point * 4 bytes per int
         polygon_address += 8 * length
@@ -719,16 +721,16 @@ EOT
 
       # write boundary_data
       @boundaries.each do |b|
-        output_file.write(b.map { |c| Helpers.coord2int(c) }.pack('l>l>l>l>'))
+        output_file.write(b.map { |c| Helpers.coord2int(c) }.pack('l<l<l<l<'))
       end
 
       # write polygon_data
       @all_coords.each do |x_coords, y_coords|
         x_coords.each do |x|
-          output_file.write([Helpers.coord2int(x)].pack('l>'))
+          output_file.write([Helpers.coord2int(x)].pack('l<'))
         end
         y_coords.each do |y|
-          output_file.write([Helpers.coord2int(y)].pack('l>'))
+          output_file.write([Helpers.coord2int(y)].pack('l<'))
         end
       end
 
@@ -738,7 +740,7 @@ EOT
       # write all nr of entries
       nr_of_entries_in_shortcut.each do |nr|
         fail "There are too many polygons in this shortcuts: #{nr}" if nr > 300
-        output_file.write([nr].pack('S>'))
+        output_file.write([nr].pack('S<'))
       end
 
       # write  Address of first Polygon_nr  in shortcut field (x,y)
@@ -746,9 +748,9 @@ EOT
       shortcut_address = output_file.tell + 259_200 * NR_SHORTCUTS_PER_LNG * NR_SHORTCUTS_PER_LAT
       nr_of_entries_in_shortcut.each do |nr|
         if nr == 0
-          output_file.write([0].pack('L>'))
+          output_file.write([0].pack('L<'))
         else
-          output_file.write([shortcut_address].pack('L>'))
+          output_file.write([shortcut_address].pack('L<'))
           # each line_nr takes up 2 bytes of space
           shortcut_address += 2 * nr
         end
@@ -758,17 +760,17 @@ EOT
       shortcut_entries.each do |entries|
         entries.each do |entry|
           fail entry if entry > @nr_of_lines
-          output_file.write([entry].pack('S>'))
+          output_file.write([entry].pack('S<'))
         end
       end
 
       # [HOLE AREA, Y = number of holes (very few: around 22)]
 
-      # '!H' for every hole store the related line
+      # 'S<' for every hole store the related line
       i = 0
       @related_line.each do |line|
         fail ArgumentError, line if line > @nr_of_lines
-        output_file.write([line].pack('S>'))
+        output_file.write([line].pack('S<'))
         i += 1
       end
 
@@ -776,15 +778,15 @@ EOT
         fail ArgumentError, 'There are more related lines than holes.'
       end
 
-      # 'S>'  Y times [H unsigned short: nr of values (coordinate PAIRS! x,y in int32 int32) in this hole]
+      # 'S<'  Y times [H unsigned short: nr of values (coordinate PAIRS! x,y in int32 int32) in this hole]
       @all_hole_lengths.each do |length|
-        output_file.write([length].pack('S>'))
+        output_file.write([length].pack('S<'))
       end
 
-      # '!I' Y times [ I unsigned int: absolute address of the byte where the data of that hole starts]
+      # 'L<' Y times [ I unsigned int: absolute address of the byte where the data of that hole starts]
       hole_address = output_file.tell + @amount_of_holes * 4
       @all_hole_lengths.each do |length|
-        output_file.write([hole_address].pack('L>'))
+        output_file.write([hole_address].pack('L<'))
         # each pair of points takes up 8 bytes of space
         hole_address += 8 * length
       end
@@ -793,10 +795,10 @@ EOT
       # write hole polygon_data
       @all_holes.each do |x_coords, y_coords|
         x_coords.each do |x|
-          output_file.write([Helpers.coord2int(x)].pack('l>'))
+          output_file.write([Helpers.coord2int(x)].pack('l<'))
         end
         y_coords.each do |y|
-          output_file.write([Helpers.coord2int(y)].pack('l>'))
+          output_file.write([Helpers.coord2int(y)].pack('l<'))
         end
       end
 
@@ -821,56 +823,56 @@ and it takes lot less space, without loosing too much accuracy (min accuracy is
 
 no of rows (= no of polygons = no of boundaries)
 approx. 28k -> use 2byte unsigned short (has range until 65k)
-'S>' = n
+'S<' = n
 
-L> Address of Shortcut area (end of polygons+1) @ 2
+L< Address of Shortcut area (end of polygons+1) @ 2
 
-S> amount of holes @6
+S< amount of holes @6
 
-L> Address of Hole area (end of shortcut area +1) @ 8
+L< Address of Hole area (end of shortcut area +1) @ 8
 
-'S>'  n times [H unsigned short: zone number=ID in this line, @ 12 + 2* lineNr]
+'S<'  n times [H unsigned short: zone number=ID in this line, @ 12 + 2* lineNr]
 
-'S>'  n times [H unsigned short: nr of values (coordinate PAIRS! x,y in long long) in this line, @ 12 + 2n + 2* lineNr]
+'S<'  n times [H unsigned short: nr of values (coordinate PAIRS! x,y in long long) in this line, @ 12 + 2n + 2* lineNr]
 
-'L>'n times [ I unsigned int: absolute address of the byte where the polygon-data of that line starts,
+'L<'n times [ I unsigned int: absolute address of the byte where the polygon-data of that line starts,
 @ 12 + 4 * n +  4*lineNr]
 
 
 
 n times 4 int32 (take up 4*4 per line): xmax, xmin, ymax, ymin  @ 12 + 8n + 16* lineNr
-'l>l>l>l>'
+'l<l<l<l<'
 
 
 [starting @ 12+ 24*n = polygon data start address]
 (for every line: x coords, y coords:)   stored  @ Address section (see above)
-'l>' * amount of points
+'l<' * amount of points
 
 360 * NR_SHORTCUTS_PER_LNG * 180 * NR_SHORTCUTS_PER_LAT:
 [atm: 360* 1 * 180 * 2 = 129,600]
-129,600 times S>   number of entries in shortcut field (x,y)  @ Pointer see above
+129,600 times S<   number of entries in shortcut field (x,y)  @ Pointer see above
 
 
 [SHORTCUT AREA]
 360 * NR_SHORTCUTS_PER_LNG * 180 * NR_SHORTCUTS_PER_LAT:
 [atm: 360* 1 * 180 * 2 = 129,600]
-129,600 times S>   number of entries in shortcut field (x,y)  @ Pointer see above
+129,600 times S<   number of entries in shortcut field (x,y)  @ Pointer see above
 
 
 Address of first Polygon_nr  in shortcut field (x,y) [0 if there is no entry] @  Pointer see above + 129,600
-129,600 times L>
+129,600 times L<
 
 [X = number of filled shortcuts]
-X times S> * amount Polygon_Nr    @ address stored in previous section
+X times S< * amount Polygon_Nr    @ address stored in previous section
 
 
 [HOLE AREA, Y = number of holes (very few: around 22)]
 
-'S>' for every hole store the related line
+'S<' for every hole store the related line
 
-'S>'  Y times [S unsigned short: nr of values (coordinate PAIRS! x,y in int32 int32) in this hole]
+'S<'  Y times [S unsigned short: nr of values (coordinate PAIRS! x,y in int32 int32) in this hole]
 
-'L>' Y times [ L unsigned int: absolute address of the byte where the data of that hole starts]
+'L<' Y times [ L unsigned int: absolute address of the byte where the data of that hole starts]
 
 Y times [ 2x i signed ints for every hole: x coords, y coords ]
 

data/lib/timezone_finder/gem_version.rb

@@ -1,5 +1,5 @@
 module TimezoneFinder
-  VERSION = '1.5.5' unless defined? TimezoneFinder::Version
+  VERSION = '1.5.6' unless defined? TimezoneFinder::Version
   # https://github.com/MrMinimal64/timezonefinder
-  BASED_SHA1_OF_PYTHON = 'f291dad017a839f25c472f4976d2a187de104ca8'
+  BASED_SHA1_OF_PYTHON = 'c948967a2f9c8bd03535b181fa6faa13168955ca'
 end

data/lib/timezone_finder/helpers.rb

@@ -5,9 +5,9 @@
 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 [is not needed]
-    #             0 for pX  right of the line
+    #     Return: -1 for pX left of the line from! p1 to! p2
+    #             0 for pX on the line [is not needed]
+    #             1 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
@@ -15,9 +15,9 @@ module TimezoneFinder
         if x > x2
           # pX is further right than p2,
           if y1 > y2
-            return 2
+            return -1
           else
-            return 0
+            return 1
           end
         end
 
@@ -25,9 +25,9 @@ module TimezoneFinder
           # pX is further left than p1
           if y1 > y2
             # so it has to be right of the line p1-p2
-            return 0
+            return 1
           else
-            return 2
+            return -1
           end
         end
 
@@ -39,9 +39,9 @@ module TimezoneFinder
           # pX is further right than p1,
           if y1 > y2
             # so it has to be left of the line p1-p2
-            return 2
+            return -1
           else
-            return 0
+            return 1
           end
         end
 
@@ -49,16 +49,16 @@ module TimezoneFinder
           # pX is further left than p2,
           if y1 > y2
             # so it has to be right of the line p1-p2
-            return 0
+            return 1
           else
-            return 2
+            return -1
           end
         end
 
         # TODO: is not return also accepted
         if x1 == x2 && x == x1
           # could also be equal
-          return 1
+          return 0
         end
 
         # x1 greater than x2
@@ -74,35 +74,35 @@ module TimezoneFinder
       if delta_x > 0
         if x1gtx2
           if y1 > y2
-            return 0
+            return 1
           else
-            return 2
+            return -1
           end
 
         else
           if y1 > y2
-            return 0
+            return 1
           else
-            return 2
+            return -1
           end
         end
 
       elsif delta_x == 0
-        return 1
+        return 0
 
       else
         if x1gtx2
           if y1 > y2
-            return 2
+            return -1
           else
-            return 0
+            return 1
           end
 
         else
           if y1 > y2
-            return 2
+            return -1
           else
-            return 0
+            return 1
           end
         end
       end
@@ -120,7 +120,7 @@ module TimezoneFinder
             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
+            if position_to_line(x, y, x1, x2, y1, y2) == -1
               # 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!
@@ -131,7 +131,7 @@ module TimezoneFinder
           if y2 < y
             x1 = coords[0][i - 1]
             x2 = coords[0][i]
-            if position_to_line(x, y, x1, x2, y1, y2) == 0
+            if position_to_line(x, y, x1, x2, y1, y2) == 1
               # point is right of line
               wn -= 1
             end
@@ -148,7 +148,7 @@ module TimezoneFinder
         if y2 >= y
           x1 = coords[0][-1]
           x2 = coords[0][0]
-          if position_to_line(x, y, x1, x2, y1, y2) == 2
+          if position_to_line(x, y, x1, x2, y1, y2) == -1
             # point is left of line
             wn += 1
           end
@@ -157,7 +157,7 @@ module TimezoneFinder
         if y2 < y
           x1 = coords[0][-1]
           x2 = coords[0][0]
-          if position_to_line(x, y, x1, x2, y1, y2) == 0
+          if position_to_line(x, y, x1, x2, y1, y2) == 1
             # point is right of line
             wn -= 1
           end
@@ -205,52 +205,54 @@ module TimezoneFinder
       [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)
+    def self.y_rotate(rad, 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]
+      # this is actually a rotation with -rad (use symmetry of sin/cos)
+      sin_rad = Math.sin(rad)
+      cos_rad = Math.cos(rad)
+      [point[0] * cos_rad - point[2] * sin_rad, point[1], point[2] * cos_rad - point[0] * sin_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)]
+    def self.coords2cartesian(lng_rad, lat_rad)
+      [Math.cos(lng_rad) * Math.cos(lat_rad), Math.sin(lng_rad) * Math.cos(lat_rad), Math.sin(lat_rad)]
     end
 
-    # uses the simplified haversine formula for this special case
+    # uses the simplified haversine formula for this special case (lat_p1 = 0)
     # :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
+    # :return: distance between the point and p1 (lng_rad_p1,0) in km
+    # this is only an approximation since the earth is not a real sphere
     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))
+      # 2* for the distance in rad and * 12742 (mean diameter of earth) for the distance in km
+      12742 * Math.asin(Math.sqrt((Math.sin(lat_rad / 2.0)) ** 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
+    # :return: distance between p1 and p2 in km
+    # this is only an approximation since the earth is not a real sphere
     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))
+      # 2* for the distance in rad and * 12742(mean diameter of earth) for the distance in km
+      12742 * 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
+    # :param lng_rad: lng of px in radians
+    # :param lat_rad: lat of px in radians
+    # :param p0_lng: lng of p0 in radians
+    # :param p0_lat: lat of p0 in radians
+    # :param pm1_lng: lng of pm1 in radians
+    # :param pm1_lat: lat of pm1 in radians
+    # :param p1_lng: lng of p1 in radians
+    # :param p1_lat: lat of p1 in radians
     # :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
+    def self.compute_min_distance(lng_rad, lat_rad, p0_lng, p0_lat, pm1_lng, pm1_lat, p1_lng, p1_lat)
+      # rotate coordinate system (= all the points) so that p0 would have lat_rad=lng_rad=0 (=origin)
+      # z rotation is simply substracting the lng_rad
       # convert the points to the cartesian coorinate system
-      px_cartesian = coords2cartesian(lng - p0_lng, lat)
+      px_cartesian = coords2cartesian(lng_rad - p0_lng, lat_rad)
       p1_cartesian = coords2cartesian(p1_lng - p0_lng, p1_lat)
       pm1_cartesian = coords2cartesian(pm1_lng - p0_lng, pm1_lat)
 
@@ -260,16 +262,16 @@ module TimezoneFinder
 
       # for both p1 and pm1 separately do:
 
-      # rotate coordinate system so that this point also has lat=0 (p0 does not change!)
+      # rotate coordinate system so that this point also has lat_p1_rad=0 and lng_p1_rad>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:
+      # if lng_rad of px is between 0 (<-point1) and lng_rad 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
+      # so clamp/clip the lng_rad of px to the interval of [0; lng_rad 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)
 
@@ -294,11 +296,11 @@ module TimezoneFinder
       (double * 10**7).to_i
     end
 
-    def self.distance_to_polygon(lng, lat, nr_points, points, trans_points)
+    def self.distance_to_polygon_exact(lng_rad, lat_rad, 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])
+        trans_points[0][i] = radians(int2coord(points[0][i]))
+        trans_points[1][i] = radians(int2coord(points[1][i]))
       end
 
       # check points -2, -1, 0 first
@@ -307,8 +309,8 @@ module TimezoneFinder
 
       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)
+      min_distance = compute_min_distance(lng_rad, lat_rad, trans_points[0][-1], trans_points[1][-1], pm1_lng, pm1_lat,
+                                          p1_lng, p1_lat)
 
       index_p0 = 1
       index_p1 = 2
@@ -316,9 +318,9 @@ module TimezoneFinder
         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
+        min_distance = [min_distance,
+                        compute_min_distance(lng_rad, lat_rad, trans_points[0][index_p0], trans_points[1][index_p0],
+                        pm1_lng, pm1_lat, p1_lng, p1_lat)].min
 
         index_p0 += 2
         index_p1 += 2
@@ -329,20 +331,31 @@ module TimezoneFinder
       min_distance
     end
 
+    def self.distance_to_polygon(lng_rad, lat_rad, nr_points, points)
+      min_distance = 40100000
+
+      (0...nr_points).each do |i|
+        min_distance = [min_distance, haversine(lng_rad, lat_rad, radians(int2coord(points[0][i])),
+          radians(int2coord(points[1][i])))].min
+      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>*'
+          unpack_format = 'S<*'
         end
       else
         case byte_width
         when 4
-          unpack_format = 'l>*'
+          unpack_format = 'l<*'
         when 8
-          unpack_format = 'q>*'
+          unpack_format = 'q<*'
         end
       end
 

data/lib/timezone_finder/timezone_finder.rb

@@ -17,15 +17,15 @@ module TimezoneFinder
 
       # 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]
+      @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]
+      @shortcuts_start = @binary_file.read(4).unpack('L<')[0]
 
-      @amount_of_holes = @binary_file.read(2).unpack('S>')[0]
+      @amount_of_holes = @binary_file.read(2).unpack('S<')[0]
 
-      @hole_area_start = @binary_file.read(4).unpack('L>')[0]
+      @hole_area_start = @binary_file.read(4).unpack('L<')[0]
 
       @nr_val_start_address = 2 * @nr_of_entries + 12
       @adr_start_address = 4 * @nr_of_entries + 12
@@ -44,7 +44,7 @@ module TimezoneFinder
       amount_of_holes = 0
       @binary_file.seek(@hole_area_start)
       (0...@amount_of_holes).each do |i|
-        related_line = @binary_file.read(2).unpack('S>')[0]
+        related_line = @binary_file.read(2).unpack('S<')[0]
         # puts(related_line)
         if related_line == last_encountered_line_nr
           amount_of_holes += 1
@@ -74,7 +74,7 @@ module TimezoneFinder
     def id_of(line = 0)
       # ids start at address 6. per line one unsigned 2byte int is used
       @binary_file.seek((12 + 2 * line))
-      @binary_file.read(2).unpack('S>')[0]
+      @binary_file.read(2).unpack('S<')[0]
     end
 
     def ids_of(iterable)
@@ -83,7 +83,7 @@ module TimezoneFinder
       i = 0
       iterable.each do |line_nr|
         @binary_file.seek((12 + 2 * line_nr))
-        id_array[i] = @binary_file.read(2).unpack('S>')[0]
+        id_array[i] = @binary_file.read(2).unpack('S<')[0]
         i += 1
       end
 
@@ -100,10 +100,10 @@ module TimezoneFinder
       # 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]
+      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])
+      @binary_file.seek(@binary_file.read(4).unpack('L<')[0])
       Helpers.fromfile(@binary_file, true, 2, nr_of_polygons)
     end
 
@@ -113,19 +113,19 @@ module TimezoneFinder
       # 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]
+      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])
+      @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]
+      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])
+      @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)]
@@ -139,10 +139,10 @@ module TimezoneFinder
 
       (0...amount_of_holes).each do |_i|
         @binary_file.seek(@nr_val_hole_address + 2 * hole_id)
-        nr_of_values = @binary_file.read(2).unpack('S>')[0]
+        nr_of_values = @binary_file.read(2).unpack('S<')[0]
 
         @binary_file.seek(@adr_hole_address + 4 * hole_id)
-        @binary_file.seek(@binary_file.read(4).unpack('L>')[0])
+        @binary_file.seek(@binary_file.read(4).unpack('L<')[0])
 
         yield [Helpers.fromfile(@binary_file, false, 4, nr_of_values),
                Helpers.fromfile(@binary_file, false, 4, nr_of_values)]
@@ -158,22 +158,54 @@ module TimezoneFinder
     # (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!
+    # This is also the reason why there could still be a closer polygon even though you got a result already.
+    # order to make sure to get the closest polygon, you should increase the search radius
+    # until you get a result and then increase it once more (and take that result).
+    # This should only make a difference in really rare cases however.
     # :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)
+    # :param exact_computation: when enabled the distance to every polygon edge is computed (way more complicated),
+    # instead of only evaluating the distances to all the vertices (=default).
+    # This only makes a real difference when polygons are very close.
+    # :param return_distances: when enabled the output looks like this:
+    # ( 'tz_name_of_the_closest_polygon',[ distances to all polygons in km], [tz_names of all polygons])
+    # :param force_evaluation:
+    # :return: the timezone name of the closest found polygon, the list of distances or None
+    def closest_timezone_at(lng, lat, delta_degree = 1, exact_computation = false, return_distances = false, force_evaluation = false)
+      exact_routine = lambda do |polygon_nr|
+        coords = coords_of(polygon_nr)
+        nr_points = coords[0].length
+        empty_array = [[0.0] * nr_points, [0.0] * nr_points]
+        Helpers.distance_to_polygon_exact(lng, lat, nr_points, coords, empty_array)
+      end
+
+      normal_routine = lambda do |polygon_nr|
+        coords = coords_of(polygon_nr)
+        nr_points = coords[0].length
+        Helpers.distance_to_polygon(lng, lat, nr_points, coords)
+      end
+
       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
+      if exact_computation
+        routine = exact_routine
+      else
+        routine = normal_routine
+      end
+
+      # the maximum possible distance is half the perimeter of earth pi * 12743km = 40,054.xxx km
+      min_distance = 40100
       # 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
 
+      lng = Helpers.radians(lng)
+      lat = Helpers.radians(lat)
+
       polygon_nrs = []
 
       # there are 2 shortcuts per 1 degree lat, so to cover 1 degree two shortcuts (rows) have to be checked
@@ -205,39 +237,57 @@ module TimezoneFinder
 
       # 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
+      if ids.count(first_entry) == polygons_in_list
+        unless return_distances || force_evaluation
+          return TIMEZONE_NAMES[first_entry]
+          # TODO: sort from least to most occurrences
+        end
+      end
 
+      distances = [nil] * 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 force_evaluation
+        polygon_nrs.each do |polygon_nr|
+          distance = routine.call(polygon_nr)
+          distances[pointer] = distance
           if distance < min_distance
             min_distance = distance
             current_closest_id = ids[pointer]
-            # whole list has to be searched again!
-            polygons_checked = 1
           end
+          pointer += 1
         end
-        pointer = (pointer + 1) % polygons_in_list
+      else
+        # stores which polygons have been checked yet
+        already_checked = [false] * polygons_in_list
+        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
+            distance = routine.call(polygon_nrs[pointer])
+            distances[pointer] = distance
+
+            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
+      end
+
+      if return_distances
+        return TIMEZONE_NAMES[current_closest_id], distances, ids.map { |x| TIMEZONE_NAMES[x] }
       end
 
-      # the the whole list has been searched
       TIMEZONE_NAMES[current_closest_id]
     end
 
@@ -279,7 +329,6 @@ module TimezoneFinder
         return TIMEZONE_NAMES[same_element] if same_element != -1
 
         # 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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: timezone_finder
 version: !ruby/object:Gem::Version
-  version: 1.5.5
+  version: 1.5.6
 platform: ruby
 authors:
 - Tasuku SUENAGA a.k.a. gunyarakun
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-06-04 00:00:00.000000000 Z
+date: 2016-06-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler