osgb 0.3.0 → 0.3.1

data/README.markdown

@@ -1,6 +1,6 @@
 # OSGB
 
-Osgb is a library that converts between British (and Irish) grid references and latitude and longitude co-ordinates. It is theoretically precise to about 1m, which is to say it's good for WGS84 and most GPS use but not up to surveying with ITRS or ETRS89. So don't do that.
+This is a library that converts between British (and Irish) grid references and latitude and longitude co-ordinates. It is theoretically accurate to about 1m, but realistically you can expect precision of about 10m. Good for google map and GPS use, not recommended for surveying nuclear power plants. I don't suppose people often use grid references for that.
 
 ## Installation
 
@@ -22,14 +22,15 @@ Early days: activerecord interface hasn't settled down, some refactoring likely,
 
 ## Usage
 
-You don't need to make any explicit reference to the gem. It adds conversion methods to the String class:
+You don't need to make any explicit reference to the gem. It adds conversion and utility methods to the String class:
 
     "SD28687846".is_gridref?                # -> true
-    "SD28687846".to_latlng                  # -> [54.196763, -3.093320]
+    "SD28687846".to_latlng                  # -> [54.196915, -3.094684]
     "SD28687846".to_wgs84                   # -> [54.196915, -3.094684]
+    "SD28687846".to_osgb36                  # -> [54.196763, -3.093320]
     "1.056789, 55.98978607".is_latlng?      # -> true
-
-and provides some (tentative) help for your ActiveRecord classes:
+    
+There is a Point class that's quite useful for geodetic calculations, and we provides some (tentative) help for your ActiveRecord classes:
 
     class Checkpoint < ActiveRecord::Base
       has_gridref :lat => 'lat', 
@@ -40,6 +41,14 @@ and provides some (tentative) help for your ActiveRecord classes:
 
 The :lat, :lng and :gridref keys should pass in the names of the relevant columns if they don't match these defaults. 
 
+## Geodesy
+
+By default we place our lat/long points on the WGS84 datum, since that's most relevant for online use. You can specify :osgb36 to keep them local:
+
+    "SD28687846".to_latlng(:osgb36)
+
+which involves a bit less processing since that's the datum used by the grid. If you want to use some other datum you will need to define a Helmert transformation from OSGB36 to that ellipsoid.
+
 ## Bugs and features
 
 [Github issues](http://github.com/spanner/osgb/issues) please, or for little things an email or github message is fine.

data/lib/osgb.rb

@@ -1,9 +1,11 @@
+require 'osgb/exceptions'				              # specific error conditions we might want to catch
 require 'osgb/angle_conversions'              # converts degrees to radians and back again
 require 'osgb/ellipsoid'                      # standard approximations to the squashed-circle shape of the earth
 require 'osgb/projection'                     # the geometrical distortions required by a map projection
 require 'osgb/helmert'                        # 3d transformation algorithm for mapping between cartesian and ellipsoidal polar coordinates
 require 'osgb/point'                          # versatile coordinate pair
 require 'osgb/gridref'                        # parse grid references and returns lat/long pairs
+require 'osgb/has_gridref'                    # ActiveRecord helpers
 require 'osgb/string_conversions'             # add conversion methods to String
 require 'osgb/railtie' if defined? Rails      # add useful methods to ActiveRecord
 

data/lib/osgb/exceptions.rb

@@ -0,0 +1,5 @@
+module Osgb
+  class OsgbError < StandardError; end
+  class OsgbConfigurationError < Osgb::OsgbError; end
+  class OsgbConversionError < Osgb::OsgbError; end
+end

data/lib/osgb/has_gridref.rb

@@ -12,7 +12,7 @@ module Osgb
   module ClassMethods
     def has_gridref name, options = {}
       include Osgb::InstanceMethods
-      osgb_options = {
+      self.osgb_options = {
         :lat => 'lat',
         :lng => 'lng',
         :gridref => 'gridref',
@@ -30,16 +30,23 @@ module Osgb
     end
     
     def convert_between_gridref_and_latlng
-      cols = self.class.osgb_options
-      if columns.include?(cols[:lat], cols[:lng], cols[:gridref])
-        if send("#{cols[:gridref]}_changed?") || !send("#{cols[:lat]}?") || !send("#{cols[:lng]}?")
-          latlng = gridref.coordinates
-          send("#{cols[:lat]}=", latlng[0])
-          send("#{cols[:lng]}=", latlng[1])
-        elsif send("#{cols[:lat]}_changed?") || send("#{cols[:lng]}_changed?") || !send("#{cols[:gridref]}?")
-          send("#{cols[:gridref]}=", Osgb::Gridref.from(send(cols[:lat]), send(cols[:lng])))
+      options = self.class.osgb_options
+      cols = self.class.column_names
+      if cols.include?(options[:lat]) && cols.include?(options[:lng]) && cols.include?(options[:gridref])
+
+        if send("#{options[:gridref]}_changed?") || !send("#{options[:lat]}?") || !send("#{options[:lng]}?")
+          point = gridref.to_latlng
+          send("#{options[:lat]}=", point.lat)
+          send("#{options[:lng]}=", point.lng)
+          
+        elsif send("#{options[:lat]}_changed?") || send("#{options[:lng]}_changed?") || !send("#{options[:gridref]}?")
+          send("#{options[:gridref]}=", Osgb::Gridref.from(send(options[:lat]), send(options[:lng])))
         end
+        
+      else
+        raise Osgb::OsgbConfigurationError "OSGB was expecting to see #{options[:lat]}, #{options[:lng]} and #{options[:gridref]} columns."
       end
     end
+
   end
 end

data/lib/osgb/railtie.rb

@@ -9,9 +9,6 @@ module Osgb
           Osgb::Railtie.insert
         end
       end
-      rake_tasks do
-        load "tasks/osgb.rake"
-      end
     end
   end
 

data/lib/tasks/osgb_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :osgb do
+#   # Task goes here
+# end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: osgb
 version: !ruby/object:Gem::Version 
-  hash: 19
+  hash: 17
   prerelease: 
   segments: 
   - 0
   - 3
-  - 0
-  version: 0.3.0
+  - 1
+  version: 0.3.1
 platform: ruby
 authors: 
 - William Ross
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-11-25 00:00:00 Z
+date: 2013-04-12 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rspec
@@ -33,23 +33,7 @@ dependencies:
         version: 2.6.0
   type: :development
   version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: rails
-  prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 21
-        segments: 
-        - 3
-        - 0
-        - 9
-        version: 3.0.9
-  type: :development
-  version_requirements: *id002
-description: Supports the use of Ordnance Survey Grid References in place of lat/lng pairs. Includes activerecord plugin.
+description: Converts between Ordnance Survey grid references and lat/long points, including transformation between datums so that you can turn grid references into GPS points.
 email: will@spanner.org
 executables: []
 
@@ -60,6 +44,7 @@ extra_rdoc_files: []
 files: 
 - lib/osgb/angle_conversions.rb
 - lib/osgb/ellipsoid.rb
+- lib/osgb/exceptions.rb
 - lib/osgb/gridref.rb
 - lib/osgb/has_gridref.rb
 - lib/osgb/helmert.rb
@@ -68,6 +53,7 @@ files:
 - lib/osgb/railtie.rb
 - lib/osgb/string_conversions.rb
 - lib/osgb.rb
+- lib/tasks/osgb_tasks.rake
 - spec/point_spec.rb
 - spec/spec_helper.rb
 - spec/string_spec.rb