geoutm 0.0.4 → 1.0.0

data/History.txt

@@ -1,3 +1,11 @@
+== 1.0.0
+
+* RDoc comments
+* Changed the way options are specified
+* Use of throw was replaced by raise and GeoUtm::GeoUtmException
+* Refactoring
+* Better support for zone 32V
+
 == 0.0.4
 
 Publish to gemcutter

data/README.rdoc

@@ -6,51 +6,22 @@ GeoUtm
 
   require 'geoutm'
 
-  coordinate = LatLon.new 100.0 100.0
-  utm_coord = coordinate.to_utm
-  reverse = utm_coord.to_lat_lon
+  coordinate = GeoUtm::LatLon.new 100.0, 100.0
+  to_utm = coordinate.to_utm
+  and_back = utm_coord.to_lat_lon
 
 =INSTALL
 
-  sudo gem sources -a http://gems.github.com
-  sudo gem install tallakt-geoutm
+  gem install geoutm
 
 
 =DESCRIPTION
 
-This module will translate latitude longitude coordinates to Universal Transverse Mercator(UTM) coordinates and vice versa.
+This gem translates between latitude and longitude coordinates to Universal Transverse Mercator(UTM) coordinates.
+The first kind is generally reported by GPS units, while the second is useful as they are represented in meters,
+thus making distance calculations easier.
 
-This is a shameless port of the Perl library Geo::Coordinates::UTM written by Graham Crookham. Most text is copied directly from this library, adapted to ruby syntax.
-
-
-== Mercator Projection
-
-The Mercator projection was first invented to help mariners. They needed to be able to take a course and know the distance traveled, and draw a line on the map which showed the day's journey. In order to do this, Mercator invented a projection which preserved length, by projecting the earth's surface onto a cylinder, sharing the same axis as the earth itself.
-This caused all Latitude and Longitude lines to intersect at a 90 degree angle, thereby negating the problem that longitude lines get closer together at the poles.
-
-== Transverse Mercator Projection
-
-A Transverse Mercator projection takes the cylinder and turns it on its side. Now the cylinder's axis passes through the equator, and it can be rotated to line up with the area of interest. Many countries use Transverse Mercator for their grid systems.
-
-== Universal Transverse Mercator
-
-The Universal Transverse Mercator(UTM) system sets up a universal world wide system for mapping. The Transverse Mercator projection is used, with the cylinder in 60 positions. This creates 60 zones around the world.
-Positions are measured using Eastings and Northings, measured in meters, instead of Latitude and Longitude. Eastings start at 500,000 on the centre line of each zone.
-In the Northern Hemisphere, Northings are zero at the equator and increase northward. In the Southern Hemisphere, Northings start at 10 million at the equator, and decrease southward. You must know which hemisphere and zone you are in to interpret your location globally. 
-Distortion of scale, distance, direction and area increase away from the central meridian.
-
-UTM projection is used to define horizontal positions world-wide by dividing the surface of the Earth into 6 degree zones, each mapped by the Transverse Mercator projection with a central meridian in the center of the zone. 
-UTM zone numbers designate 6 degree longitudinal strips extending from 80 degrees South latitude to 84 degrees North latitude. UTM zone characters designate 8 degree zones extending north and south from the equator. Eastings are measured from the central meridian (with a 500 km false easting to insure positive coordinates). Northings are measured from the equator (with a 10,000 km false northing for positions south of the equator).
-
-UTM is applied separately to the Northern and Southern Hemisphere, thus within a single UTM zone, a single X / Y pair of values will occur in both the Northern and Southern Hemisphere. 
-To eliminate this confusion, and to speed location of points, a UTM zone is sometimes subdivided into 20 zones of Latitude. These grids can be further subdivided into 100,000 meter grid squares with double-letter designations. This subdivision by Latitude and further division into grid squares is generally referred to as the Military Grid Reference System (MGRS).
-The unit of measurement of UTM is always meters and the zones are numbered from 1 to 60 eastward, beginning at the 180th meridian.
-The scale distortion in a north-south direction parallel to the central meridian (CM) is constant However, the scale distortion increases either direction away from the CM. To equalize the distortion of the map across the UTM zone, a scale factor of 0.9996 is applied to all distance measurements within the zone. The distortion at the zone boundary, 3 degrees away from the CM is approximately 1%.
-
-== Datums and Ellipsoids
-
-Unlike local surveys, which treat the Earth as a plane, the precise determination of the latitude and longitude of points over a broad area must take into account the actual shape of the Earth. To achieve the precision necessary for accurate location, the Earth cannot be assumed to be a sphere. Rather, the Earth's shape more closely approximates an ellipsoid (oblate spheroid): flattened at the poles and bulging at the Equator. Thus the Earth's shape, when cut through its polar axis, approximates an ellipse.
-A "Datum" is a standard representation of shape and offset for coordinates, which includes an ellipsoid and an origin. You must consider the Datum when working with geospatial data, since data with two different Datum will not line up. The difference can be as much as a kilometer!
+For more information please refer to http://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system
 
 = EXAMPLES
 
@@ -58,8 +29,7 @@ A description of the available ellipsoids and sample usage of the conversion rou
 
 == Ellipsoids
 
-The Ellipsoids available are as follows:
-
+Ellipsoids describe the shape of the earth used to calculate the UTM grid. As a default, WGS-84 is selected, but any of the following ellipses may be used:
 
 1. Airy
 2. Australian National
@@ -91,23 +61,8 @@ The Ellipsoids available are as follows:
 28. WGS-72
 29. WGS-84
 
-
-== ellipsoid_names
-
-The ellipsoids can be accessed using
-
-     GeoUtm::Ellipsoid::list_names
-
-Alternatively
-
-  GeouUtm::Ellipsoid::each {|ellipsoid| ... }
-
-When converting to and from UTM coordinates, the ellipsoid
-is specified as a parameter which defaults to WGS-84. To use another
-ellipsoid, use
-
-  coord.to_utm Ellipsoid::lookup :wgs60
-
+When specifying the ellipsoid as a parameter, you may use an instance of the GeoUtm::Ellipsoid class, 
+a string containing the name above, or alternatively just a symbol (eg. :wgs84).
 The name is not case sensitive and symbols are allowed. Spaces and - 
 are ignored.
 
@@ -131,13 +86,15 @@ returns
      utm.n     = 6409932.13416127
 
 
-== AUTHOR
+= AUTHOR
 
+This gem is heavily inspired and to a large extent also copied directly from by the Perl library Geo::Coordinates::UTM written by Graham Crookham.
 Graham Crookham, grahamc@cpan.org
 
-Ruby port by Tallak Tveide 2009
+Ruby port by Tallak Tveide, Erling Linde 2009/2011
+
 
-== COPYRIGHT
+= COPYRIGHT
 
 Copyright (c) 2000,2002,2004 by Graham Crookham.  All rights reserved.
     

data/lib/geoutm/ellipsoid.rb

@@ -1,37 +1,8 @@
 module GeoUtm
+  # This class represents the ellipsoid used to convert from latitude/longitude into UTM coordinates. All
+  # operations default to using WGS-84. 
   class Ellipsoid
-    attr_reader :name, :radius, :eccentricity
-
-
-    def initialize(name, radius, eccentricity)
-      @name, @radius, @eccentricity = name, radius, eccentricity
-    end
-
-    def Ellipsoid.lookup(name)
-      List[normalize_name(name.to_s)]
-    end
-
-    def Ellipsoid.list_names
-      List.keys.sort.map do |k|
-        List[k].name
-      end
-    end
-
-    def Ellipsoid.each
-      List.keys.sort do |k|
-        yield List[k]
-      end
-    end
-
-    private
-
-    def Ellipsoid.normalize_name(name)
-      name.gsub(/[\s\-\(\)]/, '').upcase
-    end
-
-    def Ellipsoid.generate_list
-      result = {}
-      data = [
+      ELLIPSOID_DATA = [
         [ "Airy", 6377563, 0.00667054],
         [ "Australian National", 6378160, 0.006694542],
         [ "Bessel 1841", 6377397, 0.006674372],
@@ -62,7 +33,64 @@ module GeoUtm
         [ "Everest Pakistan", 6377296, 0.006637534],
         [ "Indonesian 1974", 6378160, 0.006694609],
       ]
-      data.each do |item|
+    attr_reader :name, :radius, :eccentricity
+
+
+    def initialize(name, radius, eccentricity)
+      @name, @radius, @eccentricity = name, radius, eccentricity
+    end
+
+    # Find a preconfigured ellipsoid
+    # @param [String] the name of the ellipsoid. Spaces, case and `-` are ignored
+    # @return [Ellipsoid]
+    def Ellipsoid.lookup(name)
+      result = List[normalize_name(name.to_s)]
+			raise GeoUtmException, 'Ellipsoid not found: ' + name.to_s unless result
+			result
+    end
+
+
+    # @see #lookup
+		def Ellipsoid.[](name)
+			lookup name
+		end
+
+    # Use this method when you get an ellipsoid-like as a parameter to convert to an ellipsoid
+    # @param [Ellipsoid, String, Symbol]
+    # @return [Ellipsoid]
+		def Ellipsoid.clean_parameter(ellipsoid_or_name)
+			case ellipsoid_or_name
+			when Ellipsoid
+				ellipsoid_or_name
+			else
+				lookup ellipsoid_or_name.to_s
+			end
+		end
+
+    # @return [Array<String>] A list of all the available ellipsoid names
+    def Ellipsoid.list_names
+      List.keys.sort.map do |k|
+        List[k].name
+      end
+    end
+
+    # Iterate over the ellipsoid names
+    def Ellipsoid.each
+      List.keys.sort do |k|
+        yield List[k]
+      end
+    end
+
+
+    # :nodoc:
+    def Ellipsoid.normalize_name(name)
+      name.gsub(/[\s\-\(\)]/, '').upcase
+    end
+
+    # :nodoc:
+    def Ellipsoid.generate_list
+      result = {}
+      ELLIPSOID_DATA.each do |item|
         el = Ellipsoid.new *item
         result[normalize_name(el.name)] = el
       end
@@ -70,6 +98,7 @@ module GeoUtm
     end
 
     List = Ellipsoid::generate_list
+    WGS84 = Ellipsoid[:wgs84]
   end
 
 end

data/lib/geoutm/geo_utm_exception.rb

@@ -0,0 +1,4 @@
+module GeoUtm
+	class GeoUtmException < Exception
+	end
+end

data/lib/geoutm/latlon.rb

@@ -1,136 +1,35 @@
-require 'geoutm/constants'
 require 'geoutm/ellipsoid'
 require 'geoutm/utm'
+require 'geoutm/geo_utm_exception'
 
 module GeoUtm
   class LatLon
     include Math
     attr_reader :lat, :lon
-
+    
+    # Create a new coordinate instance based on latitude and longitude
+    #
+    # @param [Float] the coordinate latitude
+    # @param [Float] the coordinate longitude
     def initialize(lat, lon)
-      throw RuntimeException.new("Invalid longitude #{lon}") unless (-180.0...180.0).member? lon
+      raise GeoUtmException, "Invalid longitude #{lon}" unless (-180.0...180.0).member? lon
       @lat, @lon = lat, lon
     end
     
+    # Textual representation of the coordinate
     def to_s
       north_south = if @lat >= 0.0 then 'N' else 'S' end
       east_west = if @lon >= 0.0 then 'E' else 'W' end
       '%0.6f%s %0.6f%s' % [@lat.abs, north_south, @lon.abs, east_west]
     end
 
-    def to_utm(ellipsoid = Ellipsoid::lookup(:wgs84), zone = nil)
-      lat_radian = Deg2Rad * @lat
-      long_radian = Deg2Rad * long2
-
-      k0 = 0.9996 # scale
-
-      if zone
-        zn, zl = UTM::split_zone zone
-      else
-        zn = calc_utm_zone_number
-        zl = calc_utm_zone_letter
-      end
-
-      eccentricity = ellipsoid.eccentricity
-      longorigin = (zn - 1) * 6 - 180 + 3
-      longoriginradian = Deg2Rad * longorigin
-      eccentprime = ellipsoid.eccentricity/(1.0-eccentricity)
-
-      n = ellipsoid.radius / sqrt(1 - eccentricity * sin(lat_radian)*sin(lat_radian))
-      t = tan(lat_radian) * tan(lat_radian)
-      c = eccentprime * cos(lat_radian)*cos(lat_radian)
-      a = cos(lat_radian) * (long_radian - longoriginradian)
-      m = ellipsoid.radius * (
-        (1 - eccentricity/4 - 3 * eccentricity * eccentricity/64 - 
-          5 * eccentricity * eccentricity * eccentricity/256) * lat_radian - 
-        (3 * eccentricity/8 + 3 * eccentricity * eccentricity/32 + 
-          45 * eccentricity * eccentricity * eccentricity/1024) * sin(2 * lat_radian) + 
-        (15 * eccentricity * eccentricity/256 +
-          45 * eccentricity * eccentricity * eccentricity/1024) * sin(4 * lat_radian) - 
-        (35 * eccentricity * eccentricity * eccentricity/3072) * sin(6 * lat_radian)
-      )
-
-      utm_easting = k0*n*(a+(1-t+c)*a*a*a/6 + (5-18*t+t*t+72*c-58*eccentprime)*a*a*a*a*a/120) + 500000.0
-
-      utm_northing = k0 * ( m + n*tan(lat_radian) * ( a*a/2+(5-t+9*c+4*c*c)*a*a*a*a/24 + 
-                                   (61-58*t+t*t+600*c-330*eccentprime) * a*a*a*a*a*a/720))
-      utm_northing += 10000000.0 if @lat < 0
- 
-      UTM.new '%d%s' % [zn, zl], utm_easting, utm_northing, ellipsoid
-    end
-
-    private 
-
-    def calc_utm_zone_letter
-      case @lat
-        when 72.0..84.0
-          'X'
-        when 64.0..72.0
-          'W'
-        when 56.0..64.0
-          'V'
-        when 48.0..56.0
-          'U'
-        when 40.0..48.0
-          'T'
-        when 32.0..40.0
-          'S'
-        when 24.0..32.0
-          'R'
-        when 16.0..24.0
-          'Q'
-        when 8.0..16.0
-          'P'
-        when 0.0..8.0
-          'N'
-        when -8.0..0.0
-          'M'
-        when -16.0..-8.0
-          'L'
-        when -24.0..-16.0
-          'K'
-        when -32.0..-24.0
-          'J'
-        when -40.0..-32.0
-          'H'
-        when -48.0..-40.0
-          'G'
-        when -56.0..-48.0
-          'F'
-        when -64.0..-56.0
-          'E'
-        when -72.0..-64.0
-          'D'
-        when -80.0..-72.0
-          'C'
-        else
-          throw RuntimeException.new("Latitude #{@lat} out of UTM range")
-        end
-    end
-
-    def long2
-      @lon - ((@lon + 180)/360).to_i * 360
-    end
-
-    def calc_utm_zone_number
-      zone = ((long2 + 180)/6).to_i + 1;
-      if (56.0..64.0).member?(@lat) && (3.0..12.0).member?(long2)
-        zone = 32
-      end
-
-      if (72.0..84.0).member? @lat
-        case long2
-           when 0.0..9.0
-             zone = 31
-           when 9.0..21.0
-             zone = 33
-           when 21.0..33.0
-             zone = 35
-           when 33.0..42.0
-             zone = 37
-         end
-      end
-      zone
+    # Convert the coordinate in latutude/longitude into the UTM coordinate system
+    #
+    # @option options [String,Symbol,Ellipsoid] :ellipsoid The ellipsoid to use
+    # @option options [String] :zone Force the coordiante into another UTM zone than it belongs. Use this to compare two coordinates in different zones
+    # @return [UTM] The converted UTM representation
+    def to_utm(options = {})
+      UTM::latlon_to_utm self, options
     end
   end
 end

data/lib/geoutm/utm.rb

@@ -1,86 +1,124 @@
-require 'geoutm/constants'
 require 'geoutm/ellipsoid'
 require 'geoutm/latlon'
+require 'enumerator'
+require 'geoutm/geo_utm_exception'
+require 'geoutm/utm_zones'
 
 module GeoUtm
   class UTM
-    include Math
+    # Northing
+    attr_reader :n
+    # Easting
+    attr_reader :e
+    attr_reader :zone
+    attr_reader :ellipsoid
+    
+    # Creates a new UTM coorrdinate
+    # 
+    # @param [String] The UTM zone to use, eg. `32H`
+    # @param [Float] The easting component of the coordinate
+    # @param [Float] The northing component of the coordinate
+    # @param [String,Symbol,Ellipsoid] The ellipsoid to use
+    def initialize(zone, e, n, ellipsoid = Ellipsoid::WGS84)
+      @n, @e, @zone, @ellipsoid = n, e, zone, Ellipsoid::clean_parameter(ellipsoid)
+    end
+
+    #:nodoc:
+    def UTM.latlon_to_utm(latlon, options = {})
+			ellipsoid = (options[:ellipsoid] && Ellipsoid::clean_parameter(options[:ellipsoid])) || Ellipsoid::WGS84
 
-    attr_reader :n, :e, :zone, :zone_number, :zone_letter, :ellipsoid
+      lat_rad = Math::PI / 180.0 * latlon.lat
+      k0 = 0.9996 # scale
+      zone = options[:zone] || UTMZones::calc_utm_zone(latlon.lat, latlon.lon)
 
-    def initialize(zone, e, n, ellipsoid = Ellipsoid::lookup(:wgs84))
-      @n, @e, @zone, @ellipsoid = n, e, zone, ellipsoid
-      @zone_number, @zone_letter = UTM::split_zone @zone
+      eccentricity = ellipsoid.eccentricity
+      eccentprime = ellipsoid.eccentricity/(1.0-eccentricity)
+
+      n = ellipsoid.radius / Math::sqrt(1 - eccentricity * Math::sin(lat_rad)*Math::sin(lat_rad))
+      t = Math::tan(lat_rad) * Math::tan(lat_rad)
+      c = eccentprime * Math::cos(lat_rad)*Math::cos(lat_rad)
+      a = Math::cos(lat_rad) * Math::PI / 180.0 * (UTMZones::clean_longitude(latlon.lon) - UTMZones::lon_origin(zone))
+      m = ellipsoid.radius * (
+          (1 - eccentricity/4 - 3 * eccentricity * eccentricity/64 - 
+            5 * eccentricity * eccentricity * eccentricity/256) * lat_rad - 
+          (3 * eccentricity/8 + 3 * eccentricity * eccentricity/32 + 
+            45 * eccentricity * eccentricity * eccentricity/1024) * Math::sin(2 * lat_rad) + 
+          (15 * eccentricity * eccentricity/256 +
+            45 * eccentricity * eccentricity * eccentricity/1024) * Math::sin(4 * lat_rad) - 
+          (35 * eccentricity * eccentricity * eccentricity/3072) * Math::sin(6 * lat_rad)
+        )
+      utm_easting = k0*n*(a+(1-t+c)*a*a*a/6 + (5-18*t+t*t+72*c-58*eccentprime)*a*a*a*a*a/120) + 500000.0
+      utm_northing = k0 * ( m + n*Math::tan(lat_rad) * ( a*a/2+(5-t+9*c+4*c*c)*a*a*a*a/24 + 
+                                   (61-58*t+t*t+600*c-330*eccentprime) * a*a*a*a*a*a/720))
+      utm_northing += 10000000.0 if latlon.lat < 0
+      UTM.new zone, utm_easting, utm_northing, ellipsoid
     end
 
+    # Returns the band letter portion of the zone, eg `H` for `32H`
+		def zone_letter
+      UTMZones::split_zone(@zone).last
+		end
+
+    alias :zone_band :zone_letter
+
+    # Returns the number portion of the zone, eg `32` for `32H`
+		def zone_number
+      UTMZones::split_zone(@zone).first.to_i
+		end
+
+
     def to_s
       '%s %.2f %.2f' % [zone, e, n]
     end
 
+    # Converts this position into the latitude/longitude coordinate system
+    # @return [LatLon]
     def to_lat_lon
       k0 = 0.9996
       x  = @e - 500000 # Remove Longitude offset
       y  = @n
 
       # Set hemisphere (1=Northern, 0=Southern)
-      y    -= 10000000.0 unless northern_hemisphere?
+      y    -= 10000000.0 unless UTMZones::northern_hemisphere? @zone
 
-      longorigin = (@zone_number - 1)*6 - 180 + 3
       ecc = @ellipsoid.eccentricity
       eccPrimeSquared = (ecc)/(1-ecc)
       m  = y / k0
       mu = m / (@ellipsoid.radius * (1 - ecc / 4 - 3 * ecc ** 2 / 64 - 5 * ecc ** 3 / 256))
-      e1 = (1 - sqrt(1 - ecc)) / (1 + sqrt(1 - ecc))
+      e1 = (1 - Math::sqrt(1 - ecc)) / (1 + Math::sqrt(1 - ecc))
       phi1rad = mu +
-        (3 * e1 / 2 - 27 * e1 ** 3 / 32) * sin(2 * mu) +
-        (21 * e1 ** 2 / 16 - 55 * e1 ** 4 / 32) * sin(4 * mu) +
-        (151 * e1 ** 3 / 96) * sin(6 * mu)
-      phi1 = phi1rad * Rad2Deg
-      n1 = @ellipsoid.radius / sqrt(1 - ecc * sin(phi1rad) ** 2)
-      t1 = tan(phi1rad) ** 2
-      c1 = ecc * cos(phi1rad)**2
-      r1 = @ellipsoid.radius * (1 - ecc) / ((1 - ecc * sin(phi1rad) ** 2) ** 1.5)
+        (3 * e1 / 2 - 27 * e1 ** 3 / 32) * Math::sin(2 * mu) +
+        (21 * e1 ** 2 / 16 - 55 * e1 ** 4 / 32) * Math::sin(4 * mu) +
+        (151 * e1 ** 3 / 96) * Math::sin(6 * mu)
+      n1 = @ellipsoid.radius / Math::sqrt(1 - ecc * Math::sin(phi1rad) ** 2)
+      t1 = Math::tan(phi1rad) ** 2
+      c1 = ecc * Math::cos(phi1rad)**2
+      r1 = @ellipsoid.radius * (1 - ecc) / ((1 - ecc * Math::sin(phi1rad) ** 2) ** 1.5)
       d = x / (n1 * k0)
-      latitude = phi1rad-
-        (n1 * tan(phi1rad) / r1) * (d * d / 2 - 
+      latitude_rad = phi1rad-
+        (n1 * Math::tan(phi1rad) / r1) * (d * d / 2 - 
                                     (5 + 3 * t1 + 10 * c1 - 4 * c1 * c1 - 9 * eccPrimeSquared) * d ** 4 / 24 +
                                     (61 + 90 * t1 + 298 * c1 + 45 * t1 * t1 - 
                                      252 * eccPrimeSquared - 3 * c1 * c1) * d ** 6 / 720)
-      latitude = latitude * Rad2Deg
-      longitude = (d - (1 + 2 * t1 + c1) * d ** 3 / 6 +
+      latitude_deg = latitude_rad * 180.0 / Math::PI
+      lon_tmp = (d - (1 + 2 * t1 + c1) * d ** 3 / 6 +
                    (5 - 2 * c1 + 28 * t1 - 3 * c1 * c1 + 8 * eccPrimeSquared +
-                    24 * t1 * t1) * d ** 5 / 120) / cos(phi1rad)
-      longitude = longorigin + longitude * Rad2Deg
-      LatLon.new latitude, longitude
+                    24 * t1 * t1) * d ** 5 / 120) / Math::cos(phi1rad)
+      longitude_deg = UTMZones::lon_origin(@zone) + lon_tmp * 180.0 / Math::PI
+      LatLon.new latitude_deg, longitude_deg
     end
 
+    # The euclidian distance between two points (ie. `sqrt(dx * dx + dy * dy)`)
+    # @param [LatLon,UTM] The other coordinate. Should be in close proximity to avoid large errors
+    # @return [Float]
     def distance_to(other)
       if other.class == LatLon
-        other = other.to_utm(@ellipsoid, @zone)
+        other = UTM::latlon_to_utm other, :ellipsoid => @ellipsoid, :zone => @zone
       end
       unless other.zone == @zone
-        throw RuntimeError.new('Cannot calc distance for points in different zones - convert first')
+        raise GeoUtmException, 'Cannot calc distance for points in different zones - convert first'
       end
-      sqrt((@n - other.n) ** 2.0 + (@e - other.e) ** 2.0) 
-    end
-
-    def UTM.split_zone(zone_in)      
-      m = zone_in.match /^(\d+)([CDEFGHJKLMNPQRSTUVWX])$/
-      throw RuntimeError.new('Illegal zone: ' + zone_in) unless m
-      zn, zl = m[1].to_i, m[2]
-      throw RuntimeError.new('Illegal zone: ' + zone_in) unless (1..60).member? zn
-      return zn, zl
-    end
-
-    def UTM.validate_zone(zone_in)
-      UTM::split_zone zone_in # throw exception
-      true
-    end
-
-    private
-
-    def northern_hemisphere?
-      @zone_letter.match /[NPQRSTUVWX]/
+      Math::sqrt((@n - other.n) ** 2.0 + (@e - other.e) ** 2.0) 
     end
   end
 end

data/lib/geoutm/utm_zones.rb

@@ -0,0 +1,100 @@
+require 'geoutm/geo_utm_exception'
+
+module GeoUtm
+  # This module is used by the UTM class and is generally never used directly
+  module UTMZones 
+    # :nodoc:
+		SPECIAL_ZONES = {
+			'31V' => {:lat => (56.0..64.0), :lon => (0.0..3.0), :lon_origin => 3.0}, 
+			'32V' => {:lat => (56.0..64.0), :lon => (3.0..12.0), :lon_origin => 15.0}, 
+			'31X' => {:lat => (72.0..84.0), :lon => (0.0..9.0), :lon_origin => 3.0}, 
+			'33X' => {:lat => (72.0..84.0), :lon => (9.0..21.0), :lon_origin => 15.0}, 
+			'35X' => {:lat => (72.0..84.0), :lon => (21.0..33.0), :lon_origin => 27.0}, 
+			'37X' => {:lat => (72.0..84.0), :lon => (33.0..42.0), :lon_origin => 39.0}
+		}
+
+    BANDS = {
+        'X' => 72.0..84.0,
+        'W' => 64.0..72.0,
+        'V' => 56.0..64.0,
+        'U' => 48.0..56.0,
+        'T' => 40.0..48.0,
+        'S' => 32.0..40.0,
+        'R' => 24.0..32.0,
+        'Q' => 16.0..24.0,
+        'P' => 8.0..16.0,
+        'N' => 0.0..8.0,
+        'M' => -8.0..0.0,
+        'L' => -16.0..-8.0,
+        'K' => -24.0..-16.0,
+        'J' => -32.0..-24.0,
+        'H' => -40.0..-32.0,
+        'G' => -48.0..-40.0,
+        'F' => -56.0..-48.0,
+        'E' => -64.0..-56.0,
+        'D' => -72.0..-64.0,
+        'C' => -80.0..-72.0,
+    }
+
+    # :nodoc:
+		def UTMZones.calc_utm_zone(lat, lon)
+      search_for_special_zones(lat, lon) || calc_utm_default_zone(lat, lon)
+		end
+
+    # :nodoc:
+    def UTMZones.search_for_special_zones(lat, lon)
+      result = SPECIAL_ZONES.find {|k, v| v[:lat].member?(lat) && v[:lon].member?(lon)}
+      result && result.first
+    end
+
+    # :nodoc:
+		def UTMZones.calc_utm_default_zone(lat, lon)
+      '%d%s' % [((clean_longitude(lon) + 180)/6).to_i + 1, calc_utm_default_letter(lat)]
+		end
+
+    # :nodoc:
+    def UTMZones.lon_origin(zone)
+      sp = SPECIAL_ZONES[zone]
+      (sp && sp[:lon_origin]) || (zone_number_from_zone(zone) - 1) * 6 - 180 + 3
+    end
+
+    # :nodoc:
+		def UTMZones.calc_utm_default_letter(lat)
+      result = BANDS.find {|letter, lats| lats.member?(lat) }
+      raise GeoUtmException, "Latitude #{lat} out of UTM range" unless result
+      result.first
+		end
+
+    # :nodoc:
+    def UTMZones.zone_number_from_zone(zone)
+      UTMZones.split_zone(zone).first.to_i
+    end
+
+    # :nodoc:
+    def UTMZones.split_zone(zone_in)      
+      m = zone_in.match /^(\d+)([CDEFGHJKLMNPQRSTUVWX])$/
+      raise GeoUtmException, 'Illegal zone: ' + zone_in unless m
+      zn, zl = m[1].to_i, m[2]
+      raise GeoUtmException, 'Illegal zone: ' + zone_in unless (1..60).member? zn
+      return zn, zl
+    end
+
+    # :nodoc:
+    def UTMZones.validate_zone(zone_in)
+      UTMZones.split_zone zone_in # throw exception
+      true
+    end
+
+    # :nodoc:
+    def UTMZones.northern_hemisphere?(zone)
+      zone.match /[NPQRSTUVWX]$/
+    end
+
+    # :nodoc:
+    def UTMZones.clean_longitude(lon)
+      lon - ((lon + 180)/360).to_i * 360
+    end
+
+  end
+end
+

data/lib/geoutm.rb

@@ -5,5 +5,5 @@ require 'geoutm/utm'
 require 'geoutm/latlon'
 
 module GeoUtm
-  VERSION = '0.0.4'
+  VERSION = '1.0.0'
 end

data/spec/ellipsoid_spec.rb

@@ -20,5 +20,9 @@ module GeoUtm
     it 'should lookup with symbol names' do
       Ellipsoid::lookup(:wgs84).should be(@wgs84)
     end
+
+		it 'should rasie an exception on bad ellipsoid names' do
+			lambda { Ellipsoid::lookup :dummy }.should raise_error
+		end
   end
 end

data/spec/geoutm_spec.rb

@@ -19,20 +19,19 @@ module GeoUtm
     it "should convert from lat/lon to UTM" do
       @testdata.each do |sample|
         latlon = LatLon.new sample[:latitude].to_f, sample[:longitude].to_f
-        utm = latlon.to_utm Ellipsoid::lookup(sample[:ellipsoid])
-        utm.n.should be_close(sample[:northing].to_f, 0.01)
-        utm.e.should be_close(sample[:easting].to_f, 0.01)
+        utm = latlon.to_utm :ellipsoid => sample[:ellipsoid]
+        utm.n.should be_within(0.01).of(sample[:northing].to_f)
+        utm.e.should be_within(0.01).of(sample[:easting].to_f)
         utm.zone.should == sample[:zone]
       end
     end
 
     it "should convert from UTM to lat/lon" do
       @testdata.each do |sample|
-        utm = UTM.new sample[:zone], sample[:easting].to_f, sample[:northing].to_f, 
-          Ellipsoid::lookup(sample[:ellipsoid])
+        utm = UTM.new sample[:zone], sample[:easting].to_f, sample[:northing].to_f, sample[:ellipsoid]
         latlon = utm.to_lat_lon
-        latlon.lat.should be_close(sample[:latitude].to_f, 0.01)
-        latlon.lon.should be_close(sample[:longitude].to_f, 0.01)
+        latlon.lat.should be_within(0.01).of(sample[:latitude].to_f)
+        latlon.lon.should be_within(0.01).of(sample[:longitude].to_f)
       end
     end
   end

data/spec/latlon_spec.rb

@@ -1,7 +1,6 @@
 require File.dirname(__FILE__) + '/spec_helper.rb'
 
 module GeoUtm
-  # http://rspec.info/
   describe LatLon do
     before :each do
       # some random points
@@ -13,5 +12,20 @@ module GeoUtm
       @p1.to_s.should == '25.966877S 176.847283E'
       @p2.to_s.should == '62.664347N 18.131801W'
     end
+
+		it 'should raise an exception unless longitude is outside -180..180' do
+			lambda { LatLon.new 0.0, -200.0 }.should raise_error(GeoUtm::GeoUtmException)
+			lambda { LatLon.new 0.0, 200.0 }.should raise_error(GeoUtm::GeoUtmException)
+		end
+
+		it 'should raise an exception unless latitude is outside -80..84' do
+			lambda { LatLon.new(-81.0, 0.0).to_utm }.should raise_error(GeoUtm::GeoUtmException)
+			lambda { LatLon.new( 85.0, 0.0).to_utm }.should raise_error(GeoUtm::GeoUtmException)
+		end
+
+		it 'should accept an ellipsoid name in to_utm initializer' do
+			@p1.to_utm :ellipsoid => :wgs84
+			lambda {@p1.to_utm :ellipsoid => :wgs84}.should_not raise_error
+		end
   end
 end

data/spec/spec_helper.rb

@@ -3,7 +3,7 @@ begin
 rescue LoadError
   require 'rubygems'
   gem 'rspec'
-  require 'spec'
+  require 'rspec'
 end
 
 $:.unshift(File.dirname(__FILE__) + '/../lib')

data/spec/testdata.yaml

@@ -474,11 +474,11 @@
   :longitude: "-11.4023259491394"
   :ellipsoid: Australian National
 - :zone: 32V
-  :latitude: "58.8522081830389"
-  :easting: "564252.730916659"
-  :northing: "6524279.99360641"
-  :longitude: "10.1135752098733"
-  :ellipsoid: International
+  :latitude: "59.102298"
+  :easting: "285505.27"
+  :northing: "6557462.78"
+  :longitude: "11.254186"
+  :ellipsoid: WGS-84
 - :zone: 48W
   :latitude: "68.5749166287382"
   :easting: "507579.568049395"

data/spec/utm_spec.rb

@@ -9,12 +9,30 @@ module GeoUtm
       @p2 = UTM.new '27E', 646897.012158895, 3049077.01849759, Ellipsoid::lookup(:airy)
       @p3 = UTM.new '37T', 581477.812337138, 5020289.06897684, Ellipsoid::lookup('bessel 1841')
       @p4 = UTM.new '37T', 677938.186800496, 5048262.27080925, Ellipsoid::lookup('bessel 1841')
+      @p5 = UTM.new '32V', 285505.3, 6557462.8
+    end
+
+    it "should report zone number" do
+      @p1.zone_number.should == 60
+      @p2.zone_number.should == 27
+      @p3.zone_number.should == 37
+      @p4.zone_number.should == 37
+      @p5.zone_number.should == 32
+    end
+
+
+    it 'should report zone bands' do
+      @p1.zone_band.should == 'J'
+      @p2.zone_band.should == 'E'
+      @p3.zone_band.should == 'T'
+      @p4.zone_band.should == 'T'
+      @p5.zone_band.should == 'V'
     end
 
     it "should calculate distance between points" do
-      @p3.distance_to(@p4).should be_close(100434.575034537, 0.0001)
-      @p4.distance_to(@p3).should be_close(100434.575034537, 0.0001)
-      @p4.distance_to(@p4).should be_close(0.0, 0.0001)
+      @p3.distance_to(@p4).should be_within(0.0001).of(100434.575034537)
+      @p4.distance_to(@p3).should be_within(0.0001).of(100434.575034537)
+      @p4.distance_to(@p4).should be_within(0.0001).of(0.0)
     end
     
     it "should not calculate distances between different zones" do
@@ -22,7 +40,11 @@ module GeoUtm
     end
 
     it "should calculate distance to LatLon coordinate" do
-      @p3.distance_to(@p4.to_lat_lon).should be_close(100434.575034537, 0.001)
+      @p3.distance_to(@p4.to_lat_lon).should be_within(0.001).of(100434.575034537)
+    end
+    
+    it "should convert correctly for 32V" do
+      @p5.to_lat_lon.to_s.should == "59.102298N 11.254186E"
     end
 
     it 'should format as string' do
@@ -30,19 +52,28 @@ module GeoUtm
     end
 
     it 'should not accept invalid zone letters' do
-      lambda {UTM::split_zone '56Y'}.should raise_error
-      lambda {UTM::split_zone '56I'}.should raise_error
-      lambda {UTM::split_zone '56O'}.should raise_error
-      lambda {UTM::split_zone '56A'}.should raise_error
+      lambda {UTMZones::split_zone '56Y'}.should raise_error
+      lambda {UTMZones::split_zone '56I'}.should raise_error
+      lambda {UTMZones::split_zone '56O'}.should raise_error
+      lambda {UTMZones::split_zone '56A'}.should raise_error
     end
 
     it 'should not accept invalid zone numbers' do 
-      lambda {UTM::split_zone '00C'}.should raise_error
-      lambda {UTM::split_zone '61C'}.should raise_error
+      lambda {UTMZones::split_zone '00C'}.should raise_error
+      lambda {UTMZones::split_zone '61C'}.should raise_error
     end
 
     it 'should accept valid UTM zones' do
-      lambda {UTM::split_zone '51C'}.should_not raise_error
+      lambda {UTMZones::split_zone '51C'}.should_not raise_error
+    end
+
+    it 'should calculate correct longitude origin' do
+      UTMZones::lon_origin('32U').should == 9
+      UTMZones::lon_origin('32R').should == 9
+      UTMZones::lon_origin('32W').should == 9
+      UTMZones::lon_origin('32V').should == 15
+      UTMZones::lon_origin('32X').should == 9
+      UTMZones::lon_origin('40H').should == 57
     end
   end
 end

metadata

@@ -1,89 +1,76 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: geoutm
-version: !ruby/object:Gem::Version 
-  prerelease: false
-  segments: 
-  - 0
-  - 0
-  - 4
-  version: 0.0.4
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
 platform: ruby
-authors: 
+authors:
 - Tallak Tveide
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2010-05-24 00:00:00 +02:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2011-10-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: rspec
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 0
-        version: "0"
+  requirement: &78899510 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id001
+  prerelease: false
+  version_requirements: *78899510
 description: Conversion between latitude and longitude coordinates and UTM coordiantes
-email: 
+email:
 - tallak@tveide.net
 executables: []
-
 extensions: []
-
-extra_rdoc_files: 
+extra_rdoc_files:
 - README.rdoc
-files: 
-- spec/utm_spec.rb
-- spec/spec.opts
-- spec/latlon_spec.rb
+files:
 - spec/geoutm_spec.rb
 - spec/ellipsoid_spec.rb
-- spec/spec_helper.rb
+- spec/spec.opts
+- spec/utm_spec.rb
 - spec/testdata.yaml
-- lib/geoutm/utm.rb
+- spec/latlon_spec.rb
+- spec/spec_helper.rb
+- lib/geoutm.rb
 - lib/geoutm/latlon.rb
-- lib/geoutm/constants.rb
 - lib/geoutm/ellipsoid.rb
-- lib/geoutm.rb
+- lib/geoutm/utm.rb
+- lib/geoutm/geo_utm_exception.rb
+- lib/geoutm/utm_zones.rb
 - LICENCE
 - README.rdoc
 - History.txt
-has_rdoc: true
 homepage: http://www.github.com/tallakt/geoutm
 licenses: []
-
 post_install_message: 
-rdoc_options: 
+rdoc_options:
 - --main
 - README.rdoc
-require_paths: 
+require_paths:
 - - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: geoutm
-rubygems_version: 1.3.6
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Converting map coordinates
 test_files: []
-
+has_rdoc: true

data/lib/geoutm/constants.rb

@@ -1,4 +0,0 @@
-module GeoUtm
-  Deg2Rad = Math::PI / 180.0
-  Rad2Deg = 180.0 / Math::PI
-end