defra_ruby_address 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20ddcc7878b6c76c1e8cc3049ba6b746d630ab58256ce27e673dc6da03e3449c
-  data.tar.gz: bc3e90c8b26939f24d9d15a4209a8cace6486d97aa504e39adc0e505c709865a
+  metadata.gz: a5d4b459711e84d2d0caac1f48600cb928c1cede9b4ca85e5d23e53b12f4a881
+  data.tar.gz: 0c6b7e465734d6f4cc4cbea1df20b40a2d93d9e0d38035dc7d2d8ffbe639855e
 SHA512:
-  metadata.gz: 49bacebde4493276d5240e5f6b428578fb0b45753e41bc6a484b36f0bc722b9ee8def33bfe99ed06fed0fe2a72294f2fdd95aaf50e129fb66d0bf3072f2dc8c0
-  data.tar.gz: fe934edffe97f32bf09960e3b62826195bb1bf5046015125dcbd19365ba69519e8dc2512317859930fcc7ea7342e80987722dd5ca5a4ed97f0a97a05b572e890
+  metadata.gz: c80f7606cbfffc7dc4f03c06b106c2df3d23ad5c4fd93e29849c3ff035e6b5d53836b8bad16816f40164674de1d9437b07792d13410d99b8df4775cb72c10c2c
+  data.tar.gz: 7dc7df096183d0422971325ba71e4f5607b9e279833f10d8bd86249ef808af6c758be28a610e16bfb6f2604489992fbfa3eba0c089543fabbe2d6bec9197029b

data/README.md

@@ -270,6 +270,22 @@ The expected format of each result matches the EA Address Facade v1.1 format:
 }
 ```
 
+### Coordinate conversion
+
+The gem also provides a pair of services for converting British National Grid easting and northing coordinates (OSGB36) to WGS84 latitude and longitude, and back again, for example to support geospatial queries.
+
+The conversion is pure Ruby, using the 7-parameter Helmert transformation and Transverse Mercator formulae from the OS guide [A guide to coordinate systems in Great Britain](https://www.ordnancesurvey.co.uk/documents/resources/guide-coordinate-systems-great-britain.pdf), and is accurate to around 5 metres.
+
+Unlike the address lookup services these do not call an external API, and they return a plain hash rather than a `Response` object. String arguments are coerced to floats.
+
+```ruby
+DefraRuby::Address::EastingNorthingToLatLonService.run(358_130, 172_688)
+# => { latitude: 51.45161..., longitude: -2.60394... }
+
+DefraRuby::Address::LatLonToEastingNorthingService.run(51.451616, -2.603943)
+# => { easting: 358129.8..., northing: 172687.8... }
+```
+
 ## Contributing to this project
 
 If you have an idea you'd like to contribute please log an issue.

data/lib/defra_ruby/address/helmert_transformation.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module DefraRuby
+  module Address
+    # Shifts latitude/longitude between the OSGB36 and WGS84 datums using the
+    # 7-parameter Helmert transformation from the OS guide "A guide to
+    # coordinate systems in Great Britain". Accurate to around 5 metres.
+    #
+    # The OSGB36 to WGS84 direction is ported from the breasal gem
+    # (https://github.com/theodi/breasal, MIT licence, copyright 2013
+    # pezholio), corrected to the published OS guide parameters. The reverse
+    # direction just negates them.
+    class HelmertTransformation
+      AIRY_1830 = { a: 6_377_563.396, b: 6_356_256.909 }.freeze
+      WGS84 = { a: 6_378_137.0, b: 6_356_752.3141 }.freeze
+
+      ARC_SECOND_IN_RADIANS = Math::PI / 648_000
+
+      # Translations (tx, ty, tz) in metres, scale change (s) in parts per
+      # unit and rotations (rx, ry, rz) in radians, for the OSGB36 to WGS84
+      # direction; negated they transform in the opposite direction.
+      PARAMETERS = {
+        tx: 446.448,
+        ty: -125.157,
+        tz: 542.060,
+        s: -0.0000204894,
+        rx: 0.1502 * ARC_SECOND_IN_RADIANS,
+        ry: 0.2470 * ARC_SECOND_IN_RADIANS,
+        rz: 0.8421 * ARC_SECOND_IN_RADIANS
+      }.freeze
+
+      def self.osgb36_to_wgs84(latitude, longitude)
+        new(AIRY_1830, WGS84, 1).transform(latitude, longitude)
+      end
+
+      def self.wgs84_to_osgb36(latitude, longitude)
+        new(WGS84, AIRY_1830, -1).transform(latitude, longitude)
+      end
+
+      def initialize(source_ellipsoid, target_ellipsoid, direction)
+        @source_ellipsoid = source_ellipsoid
+        @target_ellipsoid = target_ellipsoid
+        @direction = direction
+      end
+
+      def transform(latitude, longitude)
+        to_geodetic(apply_helmert(to_cartesian(latitude, longitude)))
+      end
+
+      private
+
+      attr_reader :source_ellipsoid, :target_ellipsoid, :direction
+
+      def to_cartesian(latitude, longitude)
+        e_squared = eccentricity_squared(source_ellipsoid)
+        phi = latitude * Math::PI / 180
+        lambda = longitude * Math::PI / 180
+        nu = source_ellipsoid[:a] / Math.sqrt(1.0 - (e_squared * (Math.sin(phi)**2)))
+
+        [nu * Math.cos(phi) * Math.cos(lambda),
+         nu * Math.cos(phi) * Math.sin(lambda),
+         (1.0 - e_squared) * nu * Math.sin(phi)]
+      end
+
+      def apply_helmert(cartesian)
+        x, y, z = cartesian
+        scale = 1.0 + parameter(:s)
+        rx = parameter(:rx)
+        ry = parameter(:ry)
+        rz = parameter(:rz)
+
+        [parameter(:tx) + (scale * x) - (rz * y) + (ry * z),
+         parameter(:ty) + (rz * x) + (scale * y) - (rx * z),
+         parameter(:tz) - (ry * x) + (rx * y) + (scale * z)]
+      end
+
+      def to_geodetic(cartesian)
+        x, y, z = cartesian
+        e_squared = eccentricity_squared(target_ellipsoid)
+        p = Math.hypot(x, y)
+        phi = Math.atan(z / (p * (1.0 - e_squared)))
+
+        10.times do
+          nu = target_ellipsoid[:a] / Math.sqrt(1.0 - (e_squared * (Math.sin(phi)**2)))
+          phi = Math.atan((z + (e_squared * nu * Math.sin(phi))) / p)
+        end
+
+        [phi * 180 / Math::PI, Math.atan2(y, x) * 180 / Math::PI]
+      end
+
+      def parameter(key)
+        direction * PARAMETERS[key]
+      end
+
+      def eccentricity_squared(ellipsoid)
+        a = ellipsoid[:a]
+        b = ellipsoid[:b]
+        ((a * a) - (b * b)) / (a * a)
+      end
+    end
+  end
+end

data/lib/defra_ruby/address/services/base_service.rb

@@ -6,8 +6,8 @@ require "rest-client"
 module DefraRuby
   module Address
     class BaseService
-      def self.run(attrs = nil)
-        new.run(attrs)
+      def self.run(*)
+        new.run(*)
       end
     end
   end

data/lib/defra_ruby/address/services/easting_northing_to_lat_lon_service.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module DefraRuby
+  module Address
+    # Converts a British National Grid easting and northing to a WGS84
+    # latitude and longitude. Accurate to around 5 metres.
+    class EastingNorthingToLatLonService < BaseService
+      def run(easting, northing)
+        osgb36_latitude, osgb36_longitude = TransverseMercatorProjection.easting_northing_to_lat_lon(
+          Float(easting), Float(northing)
+        )
+        latitude, longitude = HelmertTransformation.osgb36_to_wgs84(osgb36_latitude, osgb36_longitude)
+
+        { latitude: latitude, longitude: longitude }
+      end
+    end
+  end
+end

data/lib/defra_ruby/address/services/lat_lon_to_easting_northing_service.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module DefraRuby
+  module Address
+    # Converts a WGS84 latitude and longitude to a British National Grid
+    # easting and northing. Accurate to around 5 metres.
+    class LatLonToEastingNorthingService < BaseService
+      def run(latitude, longitude)
+        osgb36_latitude, osgb36_longitude = HelmertTransformation.wgs84_to_osgb36(
+          Float(latitude), Float(longitude)
+        )
+        easting, northing = TransverseMercatorProjection.lat_lon_to_easting_northing(
+          osgb36_latitude, osgb36_longitude
+        )
+
+        { easting: easting, northing: northing }
+      end
+    end
+  end
+end

data/lib/defra_ruby/address/transverse_mercator_projection.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module DefraRuby
+  module Address
+    # Converts between British National Grid easting/northing and OSGB36
+    # latitude/longitude, a Transverse Mercator projection on the Airy 1830
+    # ellipsoid. Variable names follow the terms in the OS guide "A guide to
+    # coordinate systems in Great Britain".
+    #
+    # The easting/northing to lat/lon direction is ported from the breasal
+    # gem (https://github.com/theodi/breasal, MIT licence, copyright 2013
+    # pezholio). Breasal has no reverse conversion, so that direction comes
+    # straight from the OS guide's forward projection formulae.
+    class TransverseMercatorProjection
+      A = HelmertTransformation::AIRY_1830[:a]
+      B = HelmertTransformation::AIRY_1830[:b]
+      E_SQUARED = ((A * A) - (B * B)) / (A * A)
+      N = (A - B) / (A + B)
+
+      F0 = 0.9996012717
+      PHI0 = 49.0 * Math::PI / 180
+      LAMBDA0 = -2.0 * Math::PI / 180
+      E0 = 400_000.0
+      N0 = -100_000.0
+
+      def self.easting_northing_to_lat_lon(easting, northing)
+        new.easting_northing_to_lat_lon(easting, northing)
+      end
+
+      def self.lat_lon_to_easting_northing(latitude, longitude)
+        new.lat_lon_to_easting_northing(latitude, longitude)
+      end
+
+      def easting_northing_to_lat_lon(easting, northing)
+        phi_prime = converged_phi_prime(northing)
+        delta_e = easting - E0
+
+        [latitude_from(phi_prime, delta_e) * 180 / Math::PI,
+         longitude_from(phi_prime, delta_e) * 180 / Math::PI]
+      end
+
+      def lat_lon_to_easting_northing(latitude, longitude)
+        phi = latitude * Math::PI / 180
+        delta_lambda = (longitude * Math::PI / 180) - LAMBDA0
+
+        [easting_from(phi, delta_lambda), northing_from(phi, delta_lambda)]
+      end
+
+      private
+
+      # Converges within a few iterations for any real coordinates; the cap
+      # guards against non-finite input looping forever
+      def converged_phi_prime(northing)
+        phi_prime = ((northing - N0) / (A * F0)) + PHI0
+
+        100.times do
+          delta = northing - N0 - meridional_arc(phi_prime)
+          break if delta < 0.001
+
+          phi_prime += delta / (A * F0)
+        end
+
+        phi_prime
+      end
+
+      # The methods below are a straight port of the OS guide formulae; the
+      # ABC metric counts every arithmetic operator, so is disabled for them.
+      # rubocop:disable Metrics/AbcSize
+
+      # M in the OS guide
+      def meridional_arc(phi)
+        delta_phi = phi - PHI0
+        sum_phi = phi + PHI0
+
+        B * F0 * (((1 + N + ((5.0 / 4) * (N**2)) + ((5.0 / 4) * (N**3))) * delta_phi) -
+          (((3 * N) + (3 * (N**2)) + ((21.0 / 8) * (N**3))) * Math.sin(delta_phi) * Math.cos(sum_phi)) +
+          ((((15.0 / 8) * (N**2)) + ((15.0 / 8) * (N**3))) * Math.sin(2 * delta_phi) * Math.cos(2 * sum_phi)) -
+          (((35.0 / 24) * (N**3)) * Math.sin(3 * delta_phi) * Math.cos(3 * sum_phi)))
+      end
+
+      # Terms VII, VIII and IX in the OS guide
+      def latitude_from(phi_prime, delta_e)
+        tan = Math.tan(phi_prime)
+        tan2 = tan**2
+        nu = nu(phi_prime)
+        rho = rho(phi_prime)
+        eta_squared = (nu / rho) - 1.0
+
+        vii = tan / (2 * rho * nu)
+        viii = (tan / (24 * rho * (nu**3))) * (5 + (3 * tan2) + eta_squared - (9 * tan2 * eta_squared))
+        ix = (tan / (720 * rho * (nu**5))) * (61 + (90 * tan2) + (45 * (tan2**2)))
+
+        phi_prime - (vii * (delta_e**2)) + (viii * (delta_e**4)) - (ix * (delta_e**6))
+      end
+
+      # Terms X, XI, XII and XIIA in the OS guide
+      def longitude_from(phi_prime, delta_e)
+        sec = 1.0 / Math.cos(phi_prime)
+        tan2 = Math.tan(phi_prime)**2
+        nu = nu(phi_prime)
+
+        x = sec / nu
+        xi = (sec / (6 * (nu**3))) * ((nu / rho(phi_prime)) + (2 * tan2))
+        xii = (sec / (120 * (nu**5))) * (5 + (28 * tan2) + (24 * (tan2**2)))
+        xiia = (sec / (5040 * (nu**7))) * (61 + (662 * tan2) + (1320 * (tan2**2)) + (720 * (tan2**3)))
+
+        LAMBDA0 + (x * delta_e) - (xi * (delta_e**3)) + (xii * (delta_e**5)) - (xiia * (delta_e**7))
+      end
+
+      # Terms IV, V and VI in the OS guide
+      def easting_from(phi, delta_lambda)
+        nu = nu(phi)
+        rho = rho(phi)
+        eta_squared = (nu / rho) - 1.0
+        cos_phi = Math.cos(phi)
+        tan2 = Math.tan(phi)**2
+
+        iv = nu * cos_phi
+        v = (nu / 6) * (cos_phi**3) * ((nu / rho) - tan2)
+        vi = (nu / 120) * (cos_phi**5) * (5 - (18 * tan2) + (tan2**2) + (14 * eta_squared) - (58 * tan2 * eta_squared))
+
+        E0 + (iv * delta_lambda) + (v * (delta_lambda**3)) + (vi * (delta_lambda**5))
+      end
+
+      # Terms I, II, III and IIIA in the OS guide
+      def northing_from(phi, delta_lambda)
+        nu = nu(phi)
+        eta_squared = (nu / rho(phi)) - 1.0
+        sin_phi = Math.sin(phi)
+        cos_phi = Math.cos(phi)
+        tan2 = Math.tan(phi)**2
+
+        i = meridional_arc(phi) + N0
+        ii = (nu / 2) * sin_phi * cos_phi
+        iii = (nu / 24) * sin_phi * (cos_phi**3) * (5 - tan2 + (9 * eta_squared))
+        iiia = (nu / 720) * sin_phi * (cos_phi**5) * (61 - (58 * tan2) + (tan2**2))
+
+        i + (ii * (delta_lambda**2)) + (iii * (delta_lambda**4)) + (iiia * (delta_lambda**6))
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def nu(phi)
+        A * F0 * ((1.0 - (E_SQUARED * (Math.sin(phi)**2)))**-0.5)
+      end
+
+      def rho(phi)
+        A * F0 * (1.0 - E_SQUARED) * ((1.0 - (E_SQUARED * (Math.sin(phi)**2)))**-1.5)
+      end
+    end
+  end
+end

data/lib/defra_ruby/address/version.rb

@@ -2,6 +2,6 @@
 
 module DefraRuby
   module Address
-    VERSION = "0.3.0"
+    VERSION = "0.4.0"
   end
 end

data/lib/defra_ruby/address.rb

@@ -2,12 +2,16 @@
 
 require_relative "address/configuration"
 require_relative "address/ea_address_facade_request"
+require_relative "address/helmert_transformation"
 require_relative "address/no_match_error"
 require_relative "address/response"
+require_relative "address/transverse_mercator_projection"
 
 require_relative "address/services/base_service"
 require_relative "address/services/ea_address_facade_v1_1_service"
 require_relative "address/services/ea_address_facade_v1_service"
+require_relative "address/services/easting_northing_to_lat_lon_service"
+require_relative "address/services/lat_lon_to_easting_northing_service"
 require_relative "address/services/os_api_address_lookup_v1_service"
 require_relative "address/services/os_places_address_lookup_service"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: defra_ruby_address
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Defra
@@ -40,13 +40,17 @@ files:
 - lib/defra_ruby/address.rb
 - lib/defra_ruby/address/configuration.rb
 - lib/defra_ruby/address/ea_address_facade_request.rb
+- lib/defra_ruby/address/helmert_transformation.rb
 - lib/defra_ruby/address/no_match_error.rb
 - lib/defra_ruby/address/response.rb
 - lib/defra_ruby/address/services/base_service.rb
 - lib/defra_ruby/address/services/ea_address_facade_v1_1_service.rb
 - lib/defra_ruby/address/services/ea_address_facade_v1_service.rb
+- lib/defra_ruby/address/services/easting_northing_to_lat_lon_service.rb
+- lib/defra_ruby/address/services/lat_lon_to_easting_northing_service.rb
 - lib/defra_ruby/address/services/os_api_address_lookup_v1_service.rb
 - lib/defra_ruby/address/services/os_places_address_lookup_service.rb
+- lib/defra_ruby/address/transverse_mercator_projection.rb
 - lib/defra_ruby/address/version.rb
 homepage: https://github.com/DEFRA/defra-ruby-address
 licenses:
@@ -61,7 +65,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="