open-location-code 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 378b33bb5f5bdf0ec82c286db7e7b54b762f2723
+  data.tar.gz: b2f0ded83b4ed9c914a0220c177ae6bb3e43adf5
+SHA512:
+  metadata.gz: 052d9fb0aeeab2fd7969ae25b00824813e9f63b4877d7e73d5a5aa75d5d51c17fc1eeb51482c1f08f8cfa3d50ca3793ca2e44263c225c9244b9e5fa541f94c51
+  data.tar.gz: 34f7c50ad9dd924e7afaa441ab3cdefe80b32de655b97cdb17f5c06d3c698738855e5c80af8d3c08f1cdce82bb494e23b22580933893d8a77cfb686fe4fa5f47

data/lib/plus_codes.rb

@@ -0,0 +1,26 @@
+# Plus+Codes is a Ruby implementation of Google Open Location Code(Plus+Codes).
+#
+# @author We-Ming Wu
+module PlusCodes
+
+  # A separator used to separate the code into two parts.
+  SEPARATOR = '+'.freeze
+
+  # The max number of characters can be placed before the separator.
+  SEPARATOR_POSITION = 8
+
+  # The character used to pad a code
+  PADDING = '0'.freeze
+
+  # The character set used to encode coordinates.
+  CODE_ALPHABET = '23456789CFGHJMPQRVWX'.freeze
+
+  # ASCII lookup table.
+  DECODE = (CODE_ALPHABET.chars + [PADDING, SEPARATOR]).reduce([]) do |ary, c|
+    ary[c.ord] = CODE_ALPHABET.index(c)
+    ary[c.downcase.ord] = CODE_ALPHABET.index(c)
+    ary[c.ord] ||= -1
+    ary
+  end.freeze
+
+end

data/lib/plus_codes/code_area.rb

@@ -0,0 +1,38 @@
+module PlusCodes
+
+  # [CodeArea] contains coordinates of a decoded Open Location Code(Plus+Codes).
+  # The coordinates include the latitude and longitude of the lower left and
+  # upper right corners and the center of the bounding box for the area the
+  # code represents.
+  #
+  # @author We-Ming Wu
+  class CodeArea
+    attr_accessor :south_latitude, :west_longitude, :latitude_height,
+    :longitude_width, :latitude_center, :longitude_center
+
+    # Creates a [CodeArea].
+    #
+    # @param south_latitude [Numeric] the latitude of the SW corner in degrees
+    # @param west_longitude [Numeric] the longitude of the SW corner in degrees
+    # @param latitude_height [Numeric] the height from the SW corner in degrees
+    # @param longitude_width [Numeric] the width from the SW corner in degrees
+    # @return [CodeArea] a code area which contains the coordinates
+    def initialize(south_latitude, west_longitude, latitude_height, longitude_width)
+      @south_latitude = south_latitude
+      @west_longitude = west_longitude
+      @latitude_height = latitude_height
+      @longitude_width = longitude_width
+      @latitude_center = south_latitude + latitude_height / 2.0
+      @longitude_center = west_longitude + longitude_width / 2.0
+    end
+
+    def north_latitude
+      @south_latitude + @latitude_height
+    end
+
+    def east_longitude
+      @west_longitude + @longitude_width
+    end
+  end
+
+end

data/lib/plus_codes/open_location_code.rb

@@ -0,0 +1,264 @@
+require_relative '../plus_codes'
+require_relative '../plus_codes/code_area'
+
+module PlusCodes
+
+  # [OpenLocationCode] implements the Google Open Location Code(Plus+Codes) algorithm.
+  #
+  # @author We-Ming Wu
+  class OpenLocationCode
+
+    # Determines if a string is a valid sequence of Open Location Code(Plus+Codes) characters.
+    #
+    # @param code [String] a plus+codes
+    # @return [TrueClass, FalseClass] true if the code is valid, false otherwise
+    def valid?(code)
+      valid_length?(code) &&
+      valid_separator?(code) &&
+      valid_padding?(code) &&
+      valid_character?(code)
+    end
+
+    # Determines if a string is a valid short Open Location Code(Plus+Codes).
+    #
+    # @param code [String] a plus+codes
+    # @return [TrueClass, FalseClass] true if the code is short, false otherwise
+    def short?(code)
+      valid?(code) && code.index(SEPARATOR) < SEPARATOR_POSITION
+    end
+
+    # Determines if a string is a valid full Open Location Code(Plus+Codes).
+    #
+    # @param code [String] a plus+codes
+    # @return [TrueClass, FalseClass] true if the code is full, false otherwise
+    def full?(code)
+      valid?(code) && !short?(code)
+    end
+
+    # Converts a latitude and longitude into a Open Location Code(Plus+Codes).
+    #
+    # @param latitude [Numeric] a latitude in degrees
+    # @param longitude [Numeric] a longitude in degrees
+    # @param code_length [Integer] the number of characters in the code, this excludes the separator
+    # @return [String] a plus+codes
+    def encode(latitude, longitude, code_length = 10)
+      raise ArgumentError,
+      "Invalid Open Location Code(Plus+Codes) length: #{code_length}" if invalid_length?(code_length)
+
+      latitude = clip_latitude(latitude)
+      longitude = normalize_longitude(longitude)
+      latitude -= precision_by_length(code_length) if latitude == 90
+
+      lat = (latitude + 90).to_r
+      lng = (longitude + 180).to_r
+
+      digit = 0
+      code = ''
+      while digit < code_length
+        lat, lng = narrow_region(digit, lat, lng)
+        digit, lat, lng = build_code(digit, code, lat, lng)
+        code << SEPARATOR if (digit == SEPARATOR_POSITION)
+      end
+
+      digit < SEPARATOR_POSITION ? padded(code) : code
+    end
+
+    # Decodes an Open Location Code(Plus+Codes) into a [CodeArea].
+    #
+    # @param code [String] a plus+codes
+    # @return [CodeArea] a code area which contains the coordinates
+    def decode(code)
+      raise ArgumentError,
+      "Open Location Code(Plus+Codes) is not a valid full code: #{code}" unless full?(code)
+
+      code = code.gsub(SEPARATOR, '')
+      code = code.gsub(/#{PADDING}+/, '')
+      code = code.upcase
+
+      south_latitude = -90.0
+      west_longitude = -180.0
+
+      lat_resolution = 400.to_r
+      lng_resolution = 400.to_r
+
+      digit = 0
+      while digit < code.length
+        if digit < 10
+          lat_resolution /= 20
+          lng_resolution /= 20
+          south_latitude += lat_resolution * DECODE[code[digit].ord]
+          west_longitude += lng_resolution * DECODE[code[digit + 1].ord]
+          digit += 2
+        else
+          lat_resolution /= 5
+          lng_resolution /= 4
+          row = DECODE[code[digit].ord] / 4
+          column = DECODE[code[digit].ord] % 4
+          south_latitude += lat_resolution * row
+          west_longitude += lng_resolution * column
+          digit += 1
+        end
+      end
+
+      CodeArea.new(south_latitude, west_longitude, lat_resolution, lng_resolution)
+    end
+
+    # Recovers a full Open Location Code(Plus+Codes) from a short code and a reference location.
+    #
+    # @param short_code [String] a plus+codes
+    # @param reference_latitude [Numeric] a reference latitude in degrees
+    # @param reference_longitude [Numeric] a reference longitude in degrees
+    # @return [String] a plus+codes
+    def recover_nearest(short_code, reference_latitude, reference_longitude)
+      return short_code if full?(short_code)
+      raise ArgumentError,
+      "Open Location Code(Plus+Codes) is not valid: #{short_code}" unless short?(short_code)
+
+      ref_lat = clip_latitude(reference_latitude)
+      ref_lng = normalize_longitude(reference_longitude)
+
+      prefix_len = SEPARATOR_POSITION - short_code.index(SEPARATOR)
+      code = prefix_by_reference(ref_lat, ref_lng, prefix_len) << short_code
+      code_area = decode(code)
+
+      area_range = precision_by_length(prefix_len)
+      area_edge = area_range / 2
+
+      latitude = code_area.latitude_center
+      latitude_diff = latitude - ref_lat
+      if (latitude_diff > area_edge)
+        latitude -= area_range
+      elsif (latitude_diff < -area_edge)
+        latitude += area_range
+      end
+
+      longitude = code_area.longitude_center
+      longitude_diff = longitude - ref_lng
+      if (longitude_diff > area_edge)
+        longitude -= area_range
+      elsif (longitude_diff < -area_edge)
+        longitude += area_range
+      end
+
+      encode(latitude, longitude, code.length - SEPARATOR.length)
+    end
+
+    # Removes four, six or eight digits from the front of an Open Location Code(Plus+Codes) given a reference location.
+    #
+    # @param code [String] a plus+codes
+    # @param latitude [Numeric] a latitude in degrees
+    # @param longitude [Numeric] a longitude in degrees
+    # @return [String] a short plus+codes
+    def shorten(code, latitude, longitude)
+      raise ArgumentError,
+      "Open Location Code(Plus+Codes) is a valid full code: #{code}" unless full?(code)
+      raise ArgumentError,
+      "Cannot shorten padded codes: #{code}" unless code.index(PADDING).nil?
+
+      code_area = decode(code)
+      lat_diff = (latitude - code_area.latitude_center).abs
+      lng_diff = (longitude - code_area.longitude_center).abs
+      max_diff = [lat_diff, lng_diff].max
+      [8, 6, 4].each do |removal_len|
+        area_edge = precision_by_length(removal_len + 2) / 2
+        return code[removal_len..-1] if max_diff < area_edge
+      end
+
+      code.upcase
+    end
+
+    private
+
+    def prefix_by_reference(latitude, longitude, prefix_len)
+      precision = precision_by_length(prefix_len)
+      rounded_latitude = (latitude / precision).floor * precision
+      rounded_longitude = (longitude / precision).floor * precision
+      encode(rounded_latitude, rounded_longitude)[0...prefix_len]
+    end
+
+    def narrow_region(digit, latitude, longitude)
+      if digit == 0
+        latitude /= 20
+        longitude /= 20
+      elsif digit < 10
+        latitude *= 20
+        longitude *= 20
+      else
+        latitude *= 5
+        longitude *= 4
+      end
+      [latitude, longitude]
+    end
+
+    def build_code(digit_count, code, latitude, longitude)
+      lat_digit = latitude.to_i
+      lng_digit = longitude.to_i
+      if digit_count < 10
+        code << CODE_ALPHABET[lat_digit]
+        code << CODE_ALPHABET[lng_digit]
+        [digit_count + 2, latitude - lat_digit, longitude - lng_digit]
+      else
+        code << CODE_ALPHABET[4 * lat_digit + lng_digit]
+        [digit_count + 1, latitude - lat_digit, longitude - lng_digit]
+      end
+    end
+
+    def valid_length?(code)
+      !code.nil? && code.length >= 2 + SEPARATOR.length && code.split(SEPARATOR).last.length != 1
+    end
+
+    def valid_separator?(code)
+      separator_idx = code.index(SEPARATOR)
+      code.count(SEPARATOR) == 1 && separator_idx <= SEPARATOR_POSITION && separator_idx.even?
+    end
+
+    def valid_padding?(code)
+      if code.include?(PADDING)
+        return false if code.start_with?(PADDING)
+        return false if code[-2..-1] != PADDING + SEPARATOR
+
+        paddings = code.scan(/#{PADDING}+/)
+        return false if !paddings.one? || paddings[0].length.odd?
+        return false if paddings[0].length > SEPARATOR_POSITION - 2
+      end
+      true
+    end
+
+    def valid_character?(code)
+      code.chars.each { |ch| return false if DECODE[ch.ord].nil? }
+      true
+    end
+
+    def invalid_length?(code_length)
+      code_length < 2 || (code_length < SEPARATOR_POSITION && code_length.odd?)
+    end
+
+    def padded(code)
+      code << PADDING * (SEPARATOR_POSITION - code.length) << SEPARATOR
+    end
+
+    def precision_by_length(code_length)
+      if code_length <= 10
+        precision = 20 ** ((code_length / -2).to_i + 2)
+      else
+        precision = (20 ** -3) / (5 ** (code_length - 10))
+      end
+      precision.to_r
+    end
+
+    def clip_latitude(latitude)
+      [90.0, [-90.0, latitude].max].min
+    end
+
+    def normalize_longitude(longitude)
+      until longitude < 180
+        longitude -= 360
+      end
+      until longitude >= -180
+        longitude += 360
+      end
+      longitude
+    end
+  end
+
+end

data/test/plus_codes_test.rb

@@ -0,0 +1,90 @@
+require 'test/unit'
+require_relative '../lib/plus_codes/open_location_code'
+
+class PlusCodesTest < Test::Unit::TestCase
+
+  def setup
+    @test_data_folder_path = File.join(File.dirname(__FILE__), '..', '..', 'test_data')
+    @olc = PlusCodes::OpenLocationCode.new
+  end
+
+  def test_validity
+    read_csv_lines('validityTests.csv').each do |line|
+      cols = line.split(',')
+      code = cols[0]
+      is_valid = cols[1] == 'true'
+      is_short = cols[2] == 'true'
+      is_full = cols[3] == 'true'
+      is_valid_olc = @olc.valid?(code)
+      is_short_olc = @olc.short?(code)
+      is_full_olc = @olc.full?(code)
+      result = is_valid_olc == is_valid && is_short_olc == is_short && is_full_olc == is_full
+      assert_true(result)
+    end
+  end
+
+  def test_encode_decode
+    read_csv_lines('encodingTests.csv').each do |line|
+      cols = line.split(',')
+      code_area = @olc.decode(cols[0])
+      if cols[0].index('0')
+        code = @olc.encode(cols[1].to_f, cols[2].to_f, cols[0].index('0'))
+      else
+        code = @olc.encode(cols[1].to_f, cols[2].to_f, cols[0].length - 1)
+      end
+      assert_equal(cols[0], code)
+      assert_true((code_area.south_latitude - cols[3].to_f).abs < 0.001)
+      assert_true((code_area.west_longitude - cols[4].to_f).abs < 0.001)
+      assert_true((code_area.north_latitude - cols[5].to_f).abs < 0.001)
+      assert_true((code_area.east_longitude - cols[6].to_f).abs < 0.001)
+    end
+  end
+
+  def test_shorten
+    read_csv_lines('shortCodeTests.csv').each do |line|
+      cols = line.split(',')
+      code = cols[0]
+      lat = cols[1].to_f
+      lng = cols[2].to_f
+      short_code = cols[3]
+      short = @olc.shorten(code, lat, lng)
+      assert_equal(short_code, short)
+      expanded = @olc.recover_nearest(short, lat, lng)
+      assert_equal(code, expanded)
+    end
+    @olc.shorten('9C3W9QCJ+2VX', 60.3701125, 10.202665625)
+  end
+
+  def test_longer_encoding_with_special_case
+    assert_equal('CFX3X2X2+X2RRRRJ', @olc.encode(90.0, 1.0, 15));
+  end
+
+  def test_exceptions
+    assert_raise ArgumentError do
+      @olc.encode(20, 30, 1)
+    end
+    assert_raise ArgumentError do
+      @olc.recover_nearest('9C3W9QCJ-2VX', 51.3708675, -1.217765625)
+    end
+    @olc.recover_nearest('9C3W9QCJ+2VX', 51.3708675, -1.217765625)
+    assert_raise ArgumentError do
+      @olc.decode('sfdg')
+    end
+    assert_raise ArgumentError do
+      @olc.shorten('9C3W9Q+', 1, 2)
+    end
+    assert_raise ArgumentError do
+      @olc.shorten('9C3W9Q00+', 1, 2)
+    end
+  end
+
+  def test_valid_with_special_case
+    assert_false(@olc.valid?('3W00CJJJ+'))
+  end
+
+  def read_csv_lines(csv_file)
+    f = File.open(File.join(@test_data_folder_path, csv_file), 'r')
+    f.each_line.lazy.select { |line| line !~ /^\s*#/ }.map { |line| line.chop }
+  end
+
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: open-location-code
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Wei-Ming Wu
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-10-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: test-unit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Ruby implementation of Google Open Location Code(Plus+Codes)
+email:
+- wnameless@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/plus_codes.rb
+- lib/plus_codes/code_area.rb
+- lib/plus_codes/open_location_code.rb
+- test/plus_codes_test.rb
+homepage: https://github.com/google/open-location-code
+licenses:
+- Apache License, Version 2.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Ruby implementation of Google Open Location Code(Plus+Codes)
+test_files:
+- test/plus_codes_test.rb