google_static_maps_helper 1.3.1 → 1.3.2

data/README.rdoc

@@ -11,14 +11,14 @@ Then install this gem
   [sudo] gem install google_static_maps_helper
 
 
-= The easiest way of generating a Google Static Maps URL
+= The easiest way to generating a Google Static Maps URL
 
   GoogleStaticMapsHelper.url_for do
     marker :lng => 1, :lat => 2
     marker :lng => 3, :lat => 4
   end
 
-This will return the url for map with these markers. Please note that if you do use this approach you have to set key, size and sensor setting.
+This will return the URL for a map with these markers. Please note that if you do use this approach you have to set key, size and sensor setting.
 You do this by:
   GoogleStaticMapsHelper.key = 'your google key'
   GoogleStaticMapsHelper.size = '300x600'
@@ -31,6 +31,7 @@ If you are on Rails you can put it in your environment configuration file and wh
   end
 
 It is also possible to create paths:
+
   point1 = {:lng => 1, :lat => 2}
   point2 = {:lng => 3, :lat => 4}
 
@@ -40,16 +41,18 @@ It is also possible to create paths:
 
 ..and of course you can add paths and markers in the same map.
 
+
 = A bit more "low-level" approach instantiating objects yourself
 
+If you need a more flexibility you can create objects yourself. Read on to get a quick introduction of the classes in this library. 
+
 == Marker
-A marker object is, not surprisingly, representing a marker in the Google static map. It is pushed into the Map object and is used
+A marker object is, not surprisingly, representing a marker in the Google static map. It is pushed on to the Map object and used
 to generate the URL for the static map. Markers which are of the same "type" (same color, label and size) are grouped together in the generated URL
-so that we obey the schema of URL which Google has defined as "markers=markerStyles|markerLocation1|markerLocation2|... etc."
+so that we obey the schema of URL which Google has defined as "markers=markerStyles|markerLocation1|markerLocation2|... etc.".
 
 === How to build a Marker?
-The easiest way to build a marker is by simply sending in an object which responds to lng and lat, or
-by sending lng and lat in as a hash.
+You uild a marker by simply sending in an object which responds to lng and lat, or by sending a Hash which has lng and lat keys.
   marker = GoogleStaticMapsHelper::Marker.new(location)
   marker = GoogleStaticMapsHelper::Marker.new(:lng => 1, :lat => 2)
 
@@ -61,9 +64,9 @@ parameter to the new method if you gave a location object, or include it in the
 
 
 == Map
-A Map holds many markers, pluss some additional options like the size of the static image, Google key, what zoom level and center point it should be fixed to
-etc. If no zoom or center point is give it will calculate the map view based on the markers. You can leave markers out, but then you have to supply
-zoom and center. More info can be found here: http://code.google.com/apis/maps/documentation/staticmaps/#URL_Parameters
+A Map holds many markers, paths, pluss some additional options like the size of the static map, Google key, what zoom level and center point it should be fixed to
+etc. If no zoom or center point is give it will calculate the map view based on the markers or paths. You can leave markers and paths out, but then you have to supply
+zoom and center. More info can be found here: http://code.google.com/apis/maps/documentation/staticmaps/#URL_Parameters.
 
 === How to build a map?
 When building a map object you have to supply key, sensor and size. Other options are optional.
@@ -114,6 +117,25 @@ If you feel like it, you can add points at construction time:
   # ..or
   GoogleStaticMapsHelper::Path.new(point1, point2, :color => :red)
 
+
+== Locations
+The location class is what we wrap all our lat- and lng values in. Either it is a Marker, or points for a Path. It has a few helper methods which 
+you can use to calculate distance between locations (<tt>distance_to(another_location)</tt>) and use to generate new locations based on 
+distance and heading (<tt>endpoint(distance, heading)</tt>). It also have a helper method called <tt>endpoints_for_circle_with_radius</tt>
+which returns locations that make up a circle around the receiving location. Some examples:
+
+  # Create a marker object, which it's lng and lat are stored under the hood as a location object.
+  # Methods which the marker itself cannot answer, like lat and lng and distance_to is delegated to the location object
+  marker = GoogleStaticMapsHelper::Marker(:lng => 1, :lat => 2)
+
+  map << marker
+
+  # Lets say we want draw a circle around our marker, with a radius of 1 kilometer.
+  path = GoogleStaticMapsHelper::Path.new(:fillcolor => :blue, :points => marker.endpoints_for_circle_with_radius(1000))
+  
+  map << path
+
+
 == TODO
 * Ruby 1.9 support
 

data/VERSION

@@ -1 +1 @@
-1.3.1
+1.3.2

data/changelog.txt

@@ -1,3 +1,8 @@
+= v.1.3.2 (in git)
+* Location will now round and reduce numbers so it doesn't get above a precision of 6.
+* Added two helper methods to Location: distance_to(another_location) and endpoint(distance, heading).
+* a_location.endpoints_for_circle_with_radius(radius) returns an array of end points making a circle around location.
+
 = v.1.3.1
 * Wrote better docs for all classes.
 * You can add points to Paths with Path.new(point, second_point, :color => :red, :fillcolor => :blue)

data/google_static_maps_helper.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{google_static_maps_helper}
-  s.version = "1.3.0"
+  s.version = "1.3.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Thorbj\303\270rn Hermansen"]
-  s.date = %q{2009-10-28}
+  s.date = %q{2009-10-31}
   s.description = %q{This gem provides a simple interface to the Google Static Maps V2 API.}
   s.email = %q{thhermansen@gmail.com}
   s.extra_rdoc_files = [

data/lib/google_static_maps_helper.rb

@@ -33,8 +33,6 @@ module GoogleStaticMapsHelper
     #
     # Provides a simple DSL stripping away the need of manually instantiating classes
     #
-    # *NOTE* Paths are not supported by the DSL yet.
-    #
     # Usage:
     #
     #   # First of all, you might want to set your key etc
@@ -46,6 +44,7 @@ module GoogleStaticMapsHelper
     #   url = GoogleStaticMapsHelper.url_for do
     #     marker :lng => 1, :lat => 2
     #     marker :lng => 3, :lat => 4
+    #     path {:lng => 5, :lat => 6}, {:lng => 7, :lat => 7}
     #   end
     #
     #   # You can send in key, size etc to url_for

data/lib/google_static_maps_helper/location.rb

@@ -6,6 +6,9 @@ module GoogleStaticMapsHelper
   # and Paths' points.
   #
   class Location
+    EARTH_RADIUS_KM = 6371 # :nodoc:
+    LAT_LNG_PRECISION = 6 # :nodoc:
+
     class NoLngMethod < NoMethodError; end # Raised if incomming object doesnt respond to lng
     class NoLatMethod < NoMethodError; end # Raised if incomming object doesnt respond to lat
     class NoLatKey < ArgumentError; end # Raised if incomming Hash doesnt have key lat
@@ -31,6 +34,61 @@ module GoogleStaticMapsHelper
       end
     end
     
+    #
+    # Calculates the distance in meters to given location
+    #
+    # <tt>location</tt>:: Another location which you want the distance to
+    #
+    def distance_to(location)
+      dLat = deg2rad(location.lat - lat)
+      dLon = deg2rad((location.lng - lng).abs)
+
+      dPhi = Math.log(Math.tan(deg2rad(location.lat) / 2 + Math::PI / 4) / Math.tan(deg2rad(lat) / 2 + Math::PI / 4));
+      q = (dLat.abs > 1e-10) ? dLat/dPhi : Math.cos(deg2rad(lat));
+
+      dLon = 2 * Math::PI - dLon if (dLon > Math::PI) 
+      d = Math.sqrt(dLat * dLat + q * q * dLon * dLon); 
+
+      (d * EARTH_RADIUS_KM * 1000).round
+    end
+
+    #
+    # Returns a new <tt>Location</tt> which has given distance and heading from current location
+    #
+    # <tt>distance</tt>::   The distance in meters for the new Location from current
+    # <tt>heading</tt>::    The heading in degrees we should go from current
+    #
+    def endpoint(distance, heading)
+      d = (distance / 1000.0) / EARTH_RADIUS_KM;
+      heading = deg2rad(heading);
+
+      oX = lng * Math::PI / 180;
+      oY = lat * Math::PI / 180;
+
+      y = Math.asin(Math.sin(oY) * Math.cos(d) + Math.cos(oY) * Math.sin(d) * Math.cos(heading));
+      x = oX + Math.atan2(Math.sin(heading) * Math.sin(d) * Math.cos(oY), Math.cos(d) - Math.sin(oY) * Math.sin(y));
+
+      y = y * 180 / Math::PI;
+      x = x * 180 / Math::PI;
+
+      self.class.new(:lat => y, :lng => x)
+    end
+
+    #
+    # Returns ends poionts which will make up a circle around current location and have given radius
+    #
+    def endpoints_for_circle_with_radius(radius, steps = 30)
+      raise ArgumentError, "Number of points has to be in range of 1..360!" unless (1..360).include? steps
+
+      points = []
+      steps.times do |i|
+        points << endpoint(radius, i * 360 / steps)
+      end
+      points << points.first
+
+      points 
+    end
+
     #
     # Returning the location as a string "lat,lng"
     #
@@ -38,19 +96,36 @@ module GoogleStaticMapsHelper
       [lat, lng].join(',')
     end
 
+
+    [:lng, :lat].each do |attr|
+      define_method("#{attr}=") do |value|
+        instance_variable_set("@#{attr}", lng_lat_to_precision(value, LAT_LNG_PRECISION))
+      end
+    end
+
     private
     def extract_location_from_hash!(location_hash)
       raise NoLngKey unless location_hash.has_key? :lng
       raise NoLatKey unless location_hash.has_key? :lat
-      @lat = location_hash.delete(:lat)
-      @lng = location_hash.delete(:lng)
+      self.lat = location_hash.delete(:lat)
+      self.lng = location_hash.delete(:lng)
     end
 
     def extract_location_from_object(location)
       raise NoLngMethod unless location.respond_to? :lng
       raise NoLatMethod unless location.respond_to? :lat
-      @lat = location.lat
-      @lng = location.lng
+      self.lat = location.lat
+      self.lng = location.lng
+    end
+
+    def lng_lat_to_precision(number, precision)
+      rounded = (Float(number) * 10**precision).round.to_f / 10**precision
+      rounded = rounded.to_i if rounded.to_i == rounded
+      rounded
+    end
+
+    def deg2rad(deg)
+      deg * Math::PI / 180;
     end
   end
 end

data/spec/location_spec.rb

@@ -49,4 +49,93 @@ describe GoogleStaticMapsHelper::Location do
   it "should return to_url with its lat and lng value" do
     GoogleStaticMapsHelper::Location.new(@location_hash).to_url.should == '10,20'
   end
+
+  describe "reduce and round off lng and lat" do
+    before do
+      @location = GoogleStaticMapsHelper::Location.new(:lng => 0, :lat => 1)
+    end
+
+    [:lng, :lat].each do |attribute|
+      it "should not round #{attribute} when it is a number with a precision less than 6" do
+        @location.send("#{attribute}=", 12.000014)
+        @location.send(attribute).should == 12.000014
+      end
+
+      it "should round #{attribute} when it is a number with a precision above 6" do
+        @location.send("#{attribute}=", 12.0000051)
+        @location.send(attribute).should == 12.000005
+      end
+
+      it "should round and reduce #{attribute} when it's value is a float which can be represented with a descrete value" do
+        @location.send("#{attribute}=", 12.00000000001)
+        @location.send(attribute).to_s.should == "12"
+      end
+    end
+  end
+
+  describe "helper methods" do
+    [
+      [{:lat => 60, :lng => 0}, 0],
+      [{:lat => 60, :lng => 1}, 55597],
+      [{:lat => 61, :lng => 0}, 111195],
+      [{:lat => 60, :lng => 0.01}, 556]
+    ].each do |point_distance|
+      it "should calculate correct distance to another location" do
+        another_point, expected_distance = point_distance
+        base = GoogleStaticMapsHelper::Location.new(:lat => 60, :lng => 0)
+        another_point = GoogleStaticMapsHelper::Location.new(another_point)
+        base.distance_to(another_point).should == expected_distance
+      end
+    end
+
+
+    [
+      [1000, 360, {:lat => 59.841958, :lng => 10.439303}],
+      [1000, 324, {:lat => 59.84024, :lng => 10.428782}],
+      [1000, 114, {:lat => 59.829306, :lng=> 10.45565}],
+      [1000, 18, {:lat => 59.841518, :lng => 10.444835}]
+    ].each do |distance_heading_new_point|
+      it "should calculate new end point with given distance and heading" do
+        distance, heading, excpexted_point = distance_heading_new_point
+        base = GoogleStaticMapsHelper::Location.new(:lat => 59.832964751405214, :lng => 10.439303436108082)
+        new_point = base.endpoint(distance, heading)
+
+        new_point.lat.should == excpexted_point[:lat]
+        new_point.lng.should == excpexted_point[:lng]
+      end
+    end
+
+    describe "endpoints_for_circle_with_radius" do
+      it "should 30 + 1 end points for circle as default" do
+        base = GoogleStaticMapsHelper::Location.new(:lat => 59.832964751405214, :lng => 10.439303436108082)
+        endpoints = base.endpoints_for_circle_with_radius(1000)
+        endpoints.length.should == 31
+      end
+
+      it "should have the same point as start and end (to make a closed circle)" do
+        base = GoogleStaticMapsHelper::Location.new(:lat => 59.832964751405214, :lng => 10.439303436108082)
+        endpoints = base.endpoints_for_circle_with_radius(1000)
+        endpoints.first.should == endpoints.last
+      end
+
+      it "should reley on endpoint method to calculate new endpoints when creating circle points" do
+        base = GoogleStaticMapsHelper::Location.new(:lat => 59.832964751405214, :lng => 10.439303436108082)
+        base.should_receive(:endpoint).with(1000, 0 * 360 / 4)
+        base.should_receive(:endpoint).with(1000, 1 * 360 / 4)
+        base.should_receive(:endpoint).with(1000, 2 * 360 / 4)
+        base.should_receive(:endpoint).with(1000, 3 * 360 / 4)
+        endpoints = base.endpoints_for_circle_with_radius(1000, 4)
+      end
+
+      it "should raise argument error if number of points asked to returned when creating a circle is above 360" do
+        base = GoogleStaticMapsHelper::Location.new(:lat => 59, :lng => 10)
+        lambda {base.endpoints_for_circle_with_radius(1000, 361)}.should raise_error(ArgumentError)
+      end
+
+      it "should raise argument error if number of points asked to returned when creating a circle is less than 1" do
+        base = GoogleStaticMapsHelper::Location.new(:lat => 59, :lng => 10)
+        lambda {base.endpoints_for_circle_with_radius(1000, 0)}.should raise_error(ArgumentError)
+      end
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: google_static_maps_helper
 version: !ruby/object:Gem::Version 
-  version: 1.3.1
+  version: 1.3.2
 platform: ruby
 authors: 
 - "Thorbj\xC3\xB8rn Hermansen"
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-10-31 00:00:00 +01:00
+date: 2009-11-01 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency