silva 0.0.1 → 0.0.2

data/.gitignore

@@ -15,3 +15,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+.#

data/LICENSE.txt

@@ -0,0 +1,21 @@
+Copyright 2012 Robert Dallas Gray
+
+Redistribution and use in source and binary forms, with or without modification, are
+permitted provided that the following conditions are met:
+
+   1. Redistributions of source code must retain the above copyright notice, this list of
+      conditions and the following disclaimer.
+
+   2. Redistributions in binary form must reproduce the above copyright notice, this list
+      of conditions and the following disclaimer in the documentation and/or other materials
+      provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY <COPYRIGHT HOLDER> ''AS IS'' AND ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -1,27 +1,29 @@
-What is Silva?
-=============
-A RubyGem which provides utilities to convert between the WGS84 standard for location information (as used by Google Maps, the GPS system, etc.) and the UK Ordnance Survey's OSGB36 datum, easting/northing format and standard grid references.
 
 How do I use it?
 ================
-`gem install silva`
-
-`require 'silva'`
 
-`Silva::Location.from(:wgs84, :lat => 52.658008, :long => 1.716077).to(:gridref)`
+    gem install silva
+    
+    require 'silva'
+    
+    Silva::Location.from(:wgs84, :lat => 52.658008, :long => 1.716077).to(:gridref)
 
-`"TG51411318"``
+    "TG51411318"
 
 What else can it do?
 ===================
 Silva works with four different location systems:
 
-- WGS84 `(:wgs84, :lat => [latitude], :long => [longitude], :alt => [optional altitude])`
-- OSGB36 `(:osgb36, params as above)`
-- EN `(:en, :easting => [easting], :northing => [northing])`
-- GridRef `(:gridref, :gridref => [gridref] OR :easting => [easting], :northing => [northing])`
+- WGS84 
+`(:wgs84, :lat => [latitude], :long => [longitude], :alt => [optional altitude])`
+- OSGB36 
+`(:osgb36, params as above)`
+- EN 
+`(:en, :easting => [easting], :northing => [northing])`
+- GridRef 
+`(:gridref, :gridref => [gridref] OR :easting => [easting], :northing => [northing])`
 
-It can convert freely among each of them using the syntax Silva::Location.from(:system, params).to(:system, params).
+It can convert freely among each of them using the syntax `Silva::Location.from(:system, params).to(:system, params)`.
 
 Why did you write it?
 =====================
@@ -29,7 +31,7 @@ I needed to convert between WGS84 co-ordinates and Ordnance Survey grid referenc
 
 Anything else?
 =============
-I began with code written by (Harry Wood)[http://www.harrywood.co.uk/blog/2010/06/29/ruby-code-for-converting-to-uk-ordnance-survey-coordinate-systems-from-wgs84], who adapted code written by (Chris Veness)[http://www.movable-type.co.uk/scripts/latlong-convert-coords.html]. I subsequently went back over the maths to make sure I understood it reasonably well, and clarified it so that it's easy to check against the resources supplied by the Ordnance Survey. Some of Chris's and Harry's code is probably still lurking in there.
+I began with code written by [Harry Wood](http://www.harrywood.co.uk/blog/2010/06/29/ruby-code-for-converting-to-uk-ordnance-survey-coordinate-systems-from-wgs84), who adapted code written by [Chris Veness](http://www.movable-type.co.uk/scripts/latlong-convert-coords.html). I subsequently went back over the maths to make sure I understood it reasonably well, and clarified it so that it's easy to check against the resources supplied by the Ordnance Survey. Some of Chris's and Harry's code is probably still lurking in there.
 
 It should be accurate to about 5 to 10 metres.
 

data/lib/silva/exception.rb

@@ -0,0 +1,7 @@
+module Silva
+  class InvalidSystemError < StandardError; end
+  class InvalidTransformError < StandardError; end
+  class InvalidParamError < StandardError; end
+  class InvalidParamValueError < StandardError; end
+  class InsufficentParamsError < StandardError; end
+end

data/lib/silva/location.rb

@@ -0,0 +1,19 @@
+module Silva
+  ##
+  # A spoonful of syntactic sugar for creating location systems from the relevant parameters:
+  #
+  # loc = Silva::Location.from(:en, :easting => 651409, :northing => 31377).to(:wgs84)
+  # lat = loc.lat, long = loc.long
+  #
+  module Location
+    ##
+    # Create a location system from the given parameters.
+    # 
+    # @param [Symbol] system_name The name of the system -- at present, :wgs84, :en, :osgb36 or :gridref.
+    # @param [Hash] options Parameters relevant to the system (see individual systems for details).
+    # @return [Silva::System] A new location system.
+    def self.from(system_name, options)
+      Silva::System.create(system_name, options)
+    end
+  end
+end

data/lib/silva/system/base.rb

@@ -0,0 +1,68 @@
+module Silva
+  ##
+  # A location system -- :wgs84, :osgb36, :en or :gridref.
+  module System
+    ##
+    # A factory method to simplify and moderate creation of location systems.
+    # @param [Symbol] system_name The name of the system to be created.
+    # @param [Hash] options Parameters relevant to the given system.
+    # @return [Silva::System] A valid location system.
+    # @raises Silva::InvalidSystemError If the given system can't be created.
+    def self.create(system_name, options)
+      return Silva::System.const_get(system_name.to_s.capitalize).new(options)
+    rescue NameError
+      raise Silva::InvalidSystemError, "Can't create system: #{system_name}"
+    end
+
+    ##
+    # Provides basic utility functions.
+    #
+    class Base
+      # Default parameters can be specified for each system.
+      DEFAULT_PARAMS = {}
+      # Some parameters must be given
+      REQUIRED_PARAMS = []
+
+      ##
+      # Create the given system with relevant options.
+      #
+      # @param [Hash] options Parameters relevant to the given system.
+      #
+      def initialize(options)
+        @system_name = self.class.name.split('::').last.downcase.to_sym
+        options = DEFAULT_PARAMS.merge(options)
+        params_satisfied?(options)
+        options.each {|param, val| set_param(param, val) }
+      end
+
+      ##
+      # Transforms the base system to a different system.
+      # 
+      # @param [Symbol] target_system_name The system to convert to.
+      # @param [Hash] options Parameters relevant to the target system.
+      # @return [Silva::System] A new location system of type target_system_name.
+      def to(target_system_name, options = nil)
+        return self if target_system_name == @system_name
+        to_method = "to_#{target_system_name}".to_sym
+        unless respond_to?(to_method, true)
+          raise Silva::InvalidTransformError, "#{@system_name} cannot be transformed to #{target_system_name}."
+        end
+        send(to_method, options)
+      end
+
+      private
+
+      # Set the params given in options, if they pass validation.
+      def set_param(param, val)
+        val_method = "validate_#{param}".to_sym
+        raise Silva::InvalidParamError, "Invalid param: #{param}." unless respond_to?(val_method, true)
+        raise Silva::InvalidParamValueError, "Invalid #{param}: #{val}." unless (send(val_method, val))
+        instance_variable_set("@#{param}", val)
+      end
+
+      def params_satisfied?(options)
+        raise InsufficientParamsError unless REQUIRED_PARAMS & options.keys == REQUIRED_PARAMS
+      end
+    end
+  end
+end

data/lib/silva/system/co_ordinate.rb

@@ -0,0 +1,39 @@
+module Silva
+  module System
+    ##
+    # Provides simple validations and accessors for a lat, long, alt co-ordinate system.
+    #
+    module CoOrdinate
+      # Allowed range of latitude
+      LAT_RANGE  = (-90..90)
+      # Allowed range of longitude
+      LONG_RANGE = (-180..180)
+      # Allowed range of altitude
+      ALT_RANGE  = (-500..4000)
+
+      # Default altitude = 0
+      DEFAULT_PARAMS = { :alt => 0 }
+      REQUIRED_PARAMS = [:lat, :long]
+
+      attr_reader :lat, :long, :alt
+
+      def inspect
+        [lat, long, alt].to_s
+      end
+
+      private 
+
+      def validate_lat(lat)
+        lat.is_a?(Numeric) && LAT_RANGE.cover?(lat)
+      end
+
+      def validate_long(long)
+        long.is_a?(Numeric) && LONG_RANGE.cover?(long)
+      end
+
+      def validate_alt(alt)
+        alt.is_a?(Numeric) && ALT_RANGE.cover?(alt)
+      end
+    end
+  end
+end

data/lib/silva/system/en.rb

@@ -0,0 +1,30 @@
+module Silva
+  module System
+    ##
+    # Location system representing Ordnance Survey OSGB36 eastings and northings.
+    #
+    class En < Base
+      include OsEn
+
+      def inspect
+        [easting, northing].to_s
+      end
+      
+      private 
+
+      def to_osgb36(options = nil)
+        Silva::Transform.en_to_osgb36(self)
+      end
+
+      def to_wgs84(options = nil)
+        Silva::Transform.osgb36_to_wgs84(to_osgb36)
+      end
+
+      def to_gridref(options = nil)
+        options ||= {}
+        options = options.merge({ :easting => easting, :northing => northing })
+        System.create(:gridref, options)
+      end
+    end
+  end
+end

data/lib/silva/system/gridref.rb

@@ -0,0 +1,105 @@
+module Silva
+  module System
+    ##
+    # Location system representing Ordnance Survey Standard Grid References.
+    # 
+    # Can be created given the options :easting => e, :northing => n or :gridref => g
+    #
+    class Gridref < Base
+      include OsEn
+      # :digits can be 6, 8 or 10
+      DEFAULT_PARAMS = { :digits => 8 }
+      # UK two-letter prefixes
+      OSGB_PREFIXES = ["SV", "SW", "SX", "SY", "SZ", "TV", "TW",
+                       "SQ", "SR", "SS", "ST", "SU", "TQ", "TR",
+                       "SL", "SM", "SN", "SO", "SP", "TL", "TM",
+                       "SF", "SG", "SH", "SJ", "SK", "TF", "TG",
+                       "SA", "SB", "SC", "SD", "SE", "TA", "TB",
+                       "NV", "NW", "NX", "NY", "NZ", "OV", "OW",
+                       "NQ", "NR", "NS", "NT", "NU", "OQ", "OR",
+                       "NL", "NM", "NN", "NO", "NP", "OL", "OM",
+                       "NF", "NG", "NH", "NJ", "NK", "OF", "OG",
+                       "NA", "NB", "NC", "ND", "NE", "OA", "OB",
+                       "HV", "HW", "HX", "HY", "HZ", "JV", "JW",
+                       "HQ", "HR", "HS", "HT", "HU", "JQ", "JR",
+                       "HL", "HM", "HN", "HO", "HP", "JL", "JM"]
+      # Width of the UK grid
+      OSGB_GRID_WIDTH = 7
+      # Height of the UK grid
+      OSGB_GRID_SCALE = 100000
+
+      attr_reader :gridref
+
+      ##
+      # Lazily create the gridref from given eastings and northings, or just return it if already set.
+      #
+      # @return [String] A standard Ordnance Survey grid reference with the given number of digits.
+      #
+      def gridref
+        unless @gridref
+          e100k = (easting / 100000).floor
+          n100k = (northing / 100000).floor
+          
+          index = n100k * OSGB_GRID_WIDTH + e100k
+          prefix = OSGB_PREFIXES[index]
+          
+          e = ((easting % OSGB_GRID_SCALE) / (10**(5 - @digits / 2))).round
+          n = ((northing % OSGB_GRID_SCALE) / (10**(5 - @digits / 2))).round
+          
+          @gridref = prefix + e.to_s.rjust(@digits / 2) + n.to_s.rjust(@digits / 2)
+        end
+
+        @gridref
+      end
+
+      def inspect
+        gridref
+      end
+
+
+      private
+
+      def to_wgs84(options = nil)
+        Silva::Transform.osgb36_to_wgs84(to_osgb36)
+      end
+
+      def to_osgb36(options = nil)
+        Silva::Transform.en_to_osgb36(to_en)
+      end
+
+      def to_en(options = nil)
+        e100k, n100k = prefix_to_en
+        gridref.delete!(' ')
+        en = gridref[2..-1]
+        e = en[0, (en.length / 2)].ljust(5, '5').to_i + e100k
+        n = en[(en.length / 2)..-1].ljust(5, '5').to_i + n100k
+
+        System.create(:en, :easting => e, :northing => n )
+      end
+
+      def get_prefix
+        gridref[0..1]
+      end
+
+      def prefix_to_en
+        index = OSGB_PREFIXES.index(get_prefix)
+        e = index % OSGB_GRID_WIDTH
+        n = index / OSGB_GRID_WIDTH
+
+        [e * OSGB_GRID_SCALE, n * OSGB_GRID_SCALE]
+      end
+
+      def validate_digits(digits)
+        [6, 8, 10].include?(digits)
+      end
+
+      def validate_gridref(gridref)
+        gridref.match /[HJNOST][A-Z][0-9]{3,5}[0-9]{3,5}/
+      end
+
+      def params_satisfied?(options)
+        super or options.include?(:gridref)
+      end
+    end
+  end
+end

data/lib/silva/system/osen.rb

@@ -0,0 +1,28 @@
+module Silva
+  module System
+    module OsEn
+      ##
+      # Provides simple validations for OS easting/northing systems.
+      #
+      
+      # Allowed range of eastings
+      EASTING_RANGE = (0..700000)
+      # Allowed range of northings
+      NORTHING_RANGE = (0..1300000)
+
+      REQUIRED_PARAMS = [:easting, :northing]
+
+      attr_reader :easting, :northing
+
+      private
+
+      def validate_easting(e)
+        e.is_a?(Numeric) && EASTING_RANGE.cover?(e)
+      end
+
+      def validate_northing(n)
+        n.is_a?(Numeric) && NORTHING_RANGE.cover?(n)
+      end
+    end
+  end
+end

data/lib/silva/system/osgb36.rb

@@ -0,0 +1,24 @@
+module Silva
+  module System
+    ##
+    # Location system representing OSGB36 co-ordinates.
+    #
+    class Osgb36 < Base
+      include CoOrdinate
+
+      private
+
+      def to_en(options = nil)
+        Silva::Transform.osgb36_to_en(self)
+      end
+
+      def to_gridref(options = nil)
+        to_en.to(:gridref, options)
+      end
+
+      def to_wgs84(options = nil)
+        Silva::Transform.osgb36_to_wgs84(self)
+      end
+    end
+  end
+end

data/lib/silva/system/wgs84.rb

@@ -0,0 +1,24 @@
+module Silva
+  module System
+    ##
+    # Location system representing WGS84 co-ordinates.
+    #
+    class Wgs84 < Base
+      include CoOrdinate
+
+      private
+
+      def to_osgb36(options = nil)
+        Silva::Transform.wgs84_to_osgb36(self)
+      end
+
+      def to_en(options = nil)
+        to_osgb36.to(:en)
+      end
+
+      def to_gridref(options = nil)
+        to_en.to(:gridref, options)
+      end
+    end
+  end
+end

data/lib/silva/transform.rb

@@ -0,0 +1,235 @@
+module Silva
+  ##
+  # Encapsulates the hairy maths required to perform the various transforms.
+  # Checked against documentation provided by Orndance Survey:
+  # http://www.ordnancesurvey.co.uk/oswebsite/gps/osnetfreeservices/furtherinfo/questdeveloper.html
+  # http://www.ordnancesurvey.co.uk/oswebsite/gps/information/coordinatesystemsinfo/guidecontents/guide6.html
+  #
+  class Transform
+    # The Airy ellipsoid used by the OSGB36 datum.
+    AIRY1830 = { :a => 6377563.396, :b => 6356256.91 }
+    # The GRS80 ellipsoid used by the WGS84 datum.
+    GRS80 = { :a => 6378137, :b=> 6356752.3141 }
+
+    # The northing of true origin
+    N0 = -100000.0
+    # The easting of true origin
+    E0 = 400000.0
+    # The scale factor on central meridian
+    F0 = 0.9996012717
+    # The latitude of true origin, in radians
+    PHI0 = 49 * Math::PI / 180
+    # The longitude of true origin, in radians
+    LAMBDA0 = -2 * Math::PI / 180
+
+    # Helmert transform parameters
+    HELMERT_PARAMS = { 
+      :tx=> -446.448, :ty=> 125.157, :tz=> -542.060, # m
+      :rx=> -0.1502, :ry=> -0.2470, :rz=> -0.8421, # sec
+      :s=> 20.4894 # ppm
+    }
+
+    # Decimal places to round results in degrees.
+    DEGREE_ROUNDING_PLACES = 6
+
+    ##
+    # Convert an :osgb36 co-ordinate system :wgs84
+    #
+    # @param [Silva::System::Osgb36] osgb36 A valid :osgb36 location system.
+    # @return [Silva::System::Wgs84] A valid :wgs84 location system.
+    #
+    def self.osgb36_to_wgs84(osgb36)
+      helmert_transform(osgb36, :wgs84, AIRY1830, HELMERT_PARAMS.inject({}) { |h, (k, v)| h[k] = v * -1; h }, GRS80)
+    end
+
+    ##
+    # Convert a :wgs84 co-ordinate system to :osgb36
+    #
+    # @param [Silva::System::Wgs84] wgs84 A valid :wgs84 location system.
+    # @return [Silva::System::Osgb36] A valid :osgb36 location system.
+    #
+    def self.wgs84_to_osgb36(wgs84)
+      helmert_transform(wgs84, :osgb36, GRS80, HELMERT_PARAMS, AIRY1830)
+    end
+
+    ##
+    # Convert an :osgb36 co-ordinate system to :en (eastings and northings)
+    #
+    # @param [Silva::System::Osgb36] osgb36 A valid :wgs84 location system.
+    # @return [Silva::System::En] A valid :en location system.
+    #
+    def self.osgb36_to_en(osgb36)
+      self.latlong_to_en(osgb36, AIRY1830)
+    end
+
+    ##
+    # Convert an OSGB36 easting, northing system to :osgb36 co-ordinate system
+    #
+    # @param [Silva::System::En] osgb36 A valid :en location system.
+    # @return [Silva::System::Osgb36] A valid :osgb36 location system.
+    #
+    def self.en_to_osgb36(en)
+      # Algorithm from:
+      # http://www.ordnancesurvey.co.uk/oswebsite/gps/osnetfreeservices/furtherinfo/questdeveloper.html
+      a, b = AIRY1830[:a], AIRY1830[:b]
+      e = en.easting
+      n = en.northing
+      phi_prime = PHI0
+      m = 0
+
+      while n - N0 - m >= 0.0001 do
+        phi_prime = (n - N0 - m) / (a * F0) + phi_prime
+        m = meridional_arc(phi_prime)
+      end
+
+      nu, rho, eta2 = transverse_and_meridional_radii(phi_prime)
+
+      vii = Math.tan(phi_prime) / (2 * rho * nu)
+      viii = Math.tan(phi_prime)/(24 * rho * nu**3) * \
+      (5 + 3 * Math.tan(phi_prime)**2 + eta2 - 9 * Math.tan(phi_prime)**2 * eta2)
+      ix = Math.tan(phi_prime) / (720 * rho * nu**5) * (61 + 90 * Math.tan(phi_prime)**2 + 45 * Math.tan(phi_prime)**4)
+      x = (1 / Math.cos(phi_prime)) / nu
+      xi = (1 / Math.cos(phi_prime)) / (6 * nu**3) * (nu / rho + 2 * Math.tan(phi_prime)**2)
+      xii = (1 / Math.cos(phi_prime)) / (120 * nu**5) * (5 + 28 * Math.tan(phi_prime)**2 + 24 * Math.tan(phi_prime)**4)
+      xiia = (1 / Math.cos(phi_prime)) / (5040 * nu**7) * \
+      (61 + 662 * Math.tan(phi_prime)**2 + 1320 * Math.tan(phi_prime)**4 + 720 * Math.tan(phi_prime)**6)
+
+      phi = phi_prime - vii * (e - E0)**2 + viii * (e - E0)**4 - ix * (e - E0)**6
+      lambda = LAMBDA0 + x * (e - E0) - xi * (e - E0)**3 + xii * (e - E0)**5 - xiia * (e - E0)**7
+
+      System.create(:osgb36, :lat => to_deg(phi).round(DEGREE_ROUNDING_PLACES), \
+                    :long => to_deg(lambda).round(DEGREE_ROUNDING_PLACES), :alt => 0)
+    end
+
+
+    private
+
+    # Convert an :osgb36 or :wgs84 co-ordinate system to OSGB36 easting and northing.
+    def self.latlong_to_en(system, ellipsoid)
+      phi = to_rad(system.lat)
+      lambda = to_rad(system.long)
+
+      nu, rho, eta2 = transverse_and_meridional_radii(phi, ellipsoid)
+      m = meridional_arc(phi, ellipsoid)
+      
+      i = m + N0
+      ii = (nu / 2) * Math.sin(phi) * Math.cos(phi)
+      iii = (nu / 24) * Math.sin(phi) * Math.cos(phi)**3 * (5 - Math.tan(phi)**2 + 9 * eta2)
+      iiia = (nu / 720) * Math.sin(phi) * Math.cos(phi)**5 * (61 - 58 * Math.tan(phi)**2 + Math.tan(phi)**4)
+      iv = nu * Math.cos(phi)
+      v = (nu / 6) * Math.cos(phi)**3 * (nu / rho - Math.tan(phi)**2)
+      vi = (nu / 120) * Math.cos(phi)**5 * \
+      (5 - 18 * Math.tan(phi)**2 + Math.tan(phi)**4 + 14 * eta2 - 58 * Math.tan(phi)**4 * eta2)
+      
+      n = i + ii * (lambda - LAMBDA0)**2 + iii * (lambda - LAMBDA0)**4 + iiia * (lambda - LAMBDA0)**6
+      e = E0 + iv * (lambda - LAMBDA0) + v * (lambda - LAMBDA0)**3 + vi * (lambda - LAMBDA0)**5
+      
+      System.create(:en, :easting => e.round, :northing => n.round)
+    end
+
+    # Transform to/from :osgb36/:wgs84 co-ordinate systems.
+    # Algorithm from: 
+    # http://www.ordnancesurvey.co.uk/oswebsite/gps/information/coordinatesystemsinfo/guidecontents/guide6.html
+    # Portions of code from:
+    # http://www.harrywood.co.uk/blog/2010/06/29/ruby-code-for-converting-to-uk-ordnance-survey-coordinate-systems-from-wgs84/
+
+    def self.helmert_transform(system, target_system, ellipsoid_1, transform, ellipsoid_2)
+      phi = to_rad(system.lat)
+      lambda = to_rad(system.long)
+      alt = system.alt
+      
+      a1 = ellipsoid_1[:a]
+      b1 = ellipsoid_1[:b]
+      
+      sin_phi = Math.sin(phi)
+      cos_phi = Math.cos(phi)
+      sin_lambda = Math.sin(lambda)
+      cos_lambda = Math.cos(lambda)
+      
+      e_sq1 = eccentricity_squared(ellipsoid_1)
+      nu = a1 / Math.sqrt(1 - e_sq1 * sin_phi**2)
+      
+      x1 = (nu + alt) * cos_phi * cos_lambda
+      y1 = (nu + alt) * cos_phi * sin_lambda
+      z1 = ((1 - e_sq1) * nu + alt) * sin_phi
+      
+      tx = transform[:tx]
+      ty = transform[:ty]
+      tz = transform[:tz]
+      rx = transform[:rx] / 3600 * Math::PI / 180 
+      ry = transform[:ry] / 3600 * Math::PI / 180
+      rz = transform[:rz] / 3600 * Math::PI / 180
+      s1 = transform[:s] / 1e6 + 1 
+      
+      x2 = tx + x1 * s1 - y1 * rz + z1 * ry
+      y2 = ty + x1 * rz + y1 * s1 - z1 * rx
+      z2 = tz - x1 * ry + y1 * rx + z1 * s1
+      
+      a2 = ellipsoid_2[:a]
+      b2 = ellipsoid_2[:b]
+      precision = 4 / a2
+      
+      e_sq2 = eccentricity_squared(ellipsoid_2)
+      p = Math.sqrt(x2 * x2 + y2 * y2)
+      phi = Math.atan2(z2, p * (1 - e_sq2))
+      phi_p = 2 * Math::PI
+      
+      while ((phi - phi_p).abs > precision) do
+        nu = a2 / Math.sqrt(1 - e_sq2 * Math.sin(phi)**2)
+        phi_p = phi
+        phi = Math.atan2(z2 + e_sq2 * nu * Math.sin(phi), p)
+      end
+
+      lambda = Math.atan2(y2, x2)
+      h = p / Math.cos(phi) - nu
+      
+      System.create(target_system, :lat => to_deg(phi).round(DEGREE_ROUNDING_PLACES),\
+                    :long => to_deg(lambda).round(DEGREE_ROUNDING_PLACES), :alt => h)
+    end
+
+    # Calculate required n parameter given the relevant ellipsoid
+    def self.n(ellipsoid)
+      (ellipsoid[:a] - ellipsoid[:b]) / (ellipsoid[:a] + ellipsoid[:b])
+    end
+
+    # Calculate M (meridional arc) given latitude and relevant ellipsoid
+    def self.meridional_arc(phi, ellipsoid = AIRY1830)
+      a, b = ellipsoid[:a], ellipsoid[:b]
+      n = self.n(ellipsoid)
+
+      ma = (1 + n + (5.0 / 4.0) * n**2 + (5.0 / 4.0) * n**3) * (phi - PHI0)
+      mb = (3 * n + 3 * n**2 + (21.0 / 8.0) * n**3) * Math.sin(phi - PHI0) *  Math.cos(phi + PHI0)
+      mc = ((15.0 / 8.0) * n**2 + (15.0 / 8.0) * n**3) * Math.sin(2 * (phi - PHI0)) *  Math.cos(2 * (phi + PHI0))
+      md = (35.0 / 24.0) * n**3 * Math.sin(3 * (phi - PHI0)) *  Math.cos(3 * (phi + PHI0))
+
+      b * F0 * (ma - mb + mc - md)
+    end
+
+    # Calculate nu, rho, eta2 (transverse and meridional radii) given latitude and relevant ellipsoid.
+    def self.transverse_and_meridional_radii(phi, ellipsoid = AIRY1830)
+      a, b = ellipsoid[:a], ellipsoid[:b]
+      e2 = self.eccentricity_squared(ellipsoid)
+
+      nu = a * F0 / Math.sqrt(1 - e2 * Math.sin(phi)**2)
+      rho = a * F0 * (1 - e2) / ((1 - e2 * Math.sin(phi)**2)**1.5)
+      eta2 = nu / rho - 1
+
+      [nu, rho, eta2]
+    end
+
+    # Calculate eccentricity**2 given relevant ellipsoid.
+    def self.eccentricity_squared(ellipsoid)
+      (ellipsoid[:a]**2 - ellipsoid[:b]**2) / ellipsoid[:a]**2
+    end
+
+    # Degrees to radians.
+    def self.to_rad(degrees)
+      degrees * Math::PI / 180
+    end
+
+    # Radians to degrees.
+    def self.to_deg(rads)
+      rads * 180 / Math::PI
+    end
+  end
+end

data/lib/silva/version.rb

@@ -1,3 +1,3 @@
 module Silva
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/test/test_data.rb

@@ -0,0 +1,22 @@
+module Silva
+  module Test
+    DATA = [{
+              # from os worked examples
+              :wgs84 => { :lat => 52.658007833, :long => 1.716073973, :alt => 180.05 },
+              :osgb36 => { :lat => 52.65757, :long => 1.717922, :alt => 180.05 },
+              :en => { :easting => 651409.903, :northing => 313177.270 },
+              :gridref => "TG51411318"
+            },
+            {
+              # greenwich
+              :wgs84 => { :lat => 51.478017, :long => -0.001619, :alt => 0},
+              :osgb36 => { :lat => 51.477501, :long => 0, :alt => 0 },
+              :en => { :easting => 538874, :northing => 177344 },
+              :gridref => "TQ38877734"
+            }]
+    LAT_DELTA = 5e-5
+    LONG_DELTA = 2.5e-5
+    EN_DELTA = 10
+    COORD_FROM_GRIDREF_DELTA = 1e-4
+  end
+end

data/test/test_en.rb

@@ -0,0 +1,24 @@
+class TestEn < Test::Unit::TestCase
+  def test_en_to_wgs84
+    Silva::Test::DATA.each do |data|
+      l = Silva::Location.from(:en, data[:en]).to(:wgs84)
+      assert_in_delta data[:wgs84][:lat], l.lat, Silva::Test::LAT_DELTA
+      assert_in_delta data[:wgs84][:long], l.long, Silva::Test::LONG_DELTA
+    end
+  end
+
+  def test_en_to_osgb36
+    Silva::Test::DATA.each do |data|
+      l = Silva::Location.from(:en, data[:en]).to(:osgb36)
+      assert_in_delta data[:osgb36][:lat], l.lat, Silva::Test::LAT_DELTA
+      assert_in_delta data[:osgb36][:long], l.long, Silva::Test::LONG_DELTA
+    end
+  end
+
+  def test_en_to_gridref
+    Silva::Test::DATA.each do |data|
+      l = Silva::Location.from(:en, data[:en]).to(:gridref, :digits => 8)
+      assert_equal data[:gridref], l.gridref
+    end
+  end
+end

data/test/test_gridref.rb

@@ -0,0 +1,28 @@
+class TestGridref < Test::Unit::TestCase
+  def test_gridref_to_en
+    Silva::Test::DATA.each do |data|
+      options = { :gridref => data[:gridref], :digits => 8 }
+      l = Silva::Location.from(:gridref, options).to(:en)
+      assert_in_delta data[:en][:easting], l.easting, Silva::Test::EN_DELTA
+      assert_in_delta data[:en][:northing], l.northing, Silva::Test::EN_DELTA
+    end
+  end
+
+  def test_gridref_to_osgb36
+    Silva::Test::DATA.each do |data|
+      options = { :gridref => data[:gridref], :digits => 8 }
+      l = Silva::Location.from(:gridref, options).to(:osgb36)
+      assert_in_delta data[:osgb36][:lat], l.lat, Silva::Test::COORD_FROM_GRIDREF_DELTA
+      assert_in_delta data[:osgb36][:long], l.long, Silva::Test::COORD_FROM_GRIDREF_DELTA
+    end
+  end
+
+  def test_gridref_to_wgs84
+    Silva::Test::DATA.each do |data|
+      options = { :gridref => data[:gridref], :digits => 8 }
+      l = Silva::Location.from(:gridref, options).to(:wgs84)
+      assert_in_delta data[:wgs84][:lat], l.lat, Silva::Test::COORD_FROM_GRIDREF_DELTA
+      assert_in_delta data[:wgs84][:long], l.long, Silva::Test::COORD_FROM_GRIDREF_DELTA
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,8 @@
+require 'test/unit'
+require_relative '../lib/silva'
+require_relative 'test_data'
+require_relative 'test_location'
+require_relative 'test_wgs84'
+require_relative 'test_en'
+require_relative 'test_osgb36'
+require_relative 'test_gridref'

data/test/test_location.rb

@@ -0,0 +1,33 @@
+class TestLocation < Test::Unit::TestCase
+  def test_invalid_system_raises_error
+    assert_raise Silva::InvalidSystemError do 
+      l = Silva::Location.from(:invalid, nil)
+    end
+  end
+
+  def test_invalid_param_raises_error
+    assert_raise Silva::InvalidParamError do
+      l = Silva::Location.from(:wgs84, :lat => 0, :long => 0, :altitude => 0)
+    end
+  end
+
+  def test_invalid_value_raises_error
+    assert_raise Silva::InvalidParamValueError do
+      l = Silva::Location.from(:wgs84, :lat => "five", :long => 0, :alt => 0)
+    end
+  end
+
+  def test_co_ordinate_system_out_of_range_param_raises_error
+    assert_raise Silva::InvalidParamValueError do
+      l = Silva::Location.from(:wgs84, :lat => 185, :long => 0, :altitude => 0)
+    end
+  end
+
+  def test_co_ordinates_set_correctly
+    Silva::Test::DATA.each do |data|
+      l = Silva::Location.from(:wgs84, data[:wgs84]).to(:wgs84)
+      assert(l.lat == data[:wgs84][:lat] && l.long == data[:wgs84][:long] && l.alt == data[:wgs84][:alt], \
+             "Failed assigning co-ords to System::Wgs84")
+    end
+  end
+end

data/test/test_osgb36.rb

@@ -0,0 +1,2 @@
+class TestOsgb36 < Test::Unit::TestCase
+end

data/test/test_wgs84.rb

@@ -0,0 +1,31 @@
+class TestWgs84 < Test::Unit::TestCase
+  def setup
+  end
+
+  def teardown
+  end
+
+  def test_wgs84_to_en
+    Silva::Test::DATA.each do |data|
+      l = Silva::Location.from(:wgs84, data[:wgs84]).to(:en)
+      assert_in_delta data[:en][:easting], l.easting, Silva::Test::EN_DELTA
+      assert_in_delta data[:en][:northing], l.northing, Silva::Test::EN_DELTA
+    end
+  end
+
+  def test_wgs84_to_osgb36
+    Silva::Test::DATA.each do |data|
+      l = Silva::Location.from(:wgs84, data[:wgs84]).to(:osgb36)
+      assert_in_delta data[:osgb36][:lat], l.lat, Silva::Test::LAT_DELTA
+      assert_in_delta data[:osgb36][:long], l.long, Silva::Test::LONG_DELTA
+    end
+  end
+
+  def test_wgs84_to_gridref
+    Silva::Test::DATA.each do |data|
+      l = Silva::Location.from(:wgs84, data[:wgs84]).to(:gridref, :digits => 8)
+      assert_equal data[:gridref], l.gridref
+    end
+  end
+end
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: silva
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -37,11 +37,29 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - Gemfile
+- LICENSE.txt
 - README.md
 - Rakefile
 - lib/silva.rb
+- lib/silva/exception.rb
+- lib/silva/location.rb
+- lib/silva/system/base.rb
+- lib/silva/system/co_ordinate.rb
+- lib/silva/system/en.rb
+- lib/silva/system/gridref.rb
+- lib/silva/system/osen.rb
+- lib/silva/system/osgb36.rb
+- lib/silva/system/wgs84.rb
+- lib/silva/transform.rb
 - lib/silva/version.rb
 - silva.gemspec
+- test/test_data.rb
+- test/test_en.rb
+- test/test_gridref.rb
+- test/test_helper.rb
+- test/test_location.rb
+- test/test_osgb36.rb
+- test/test_wgs84.rb
 homepage: http://github.com/rdallasgray/silva
 licenses:
 - FreeBSD
@@ -68,5 +86,12 @@ signing_key:
 specification_version: 3
 summary: Convert between the GPS (WGS84) location standard and UK Ordnance Survey
   standards.
-test_files: []
+test_files:
+- test/test_data.rb
+- test/test_en.rb
+- test/test_gridref.rb
+- test/test_helper.rb
+- test/test_location.rb
+- test/test_osgb36.rb
+- test/test_wgs84.rb
 has_rdoc: