google_static_maps_helper 1.3.3 → 1.3.4

data/README.rdoc

@@ -97,7 +97,10 @@ Another thing you might want to do is to override the center point and zoom leve
 
 
 == Paths and Polygons
-It is also possible to create Paths and Polygons and to use them together with markers. To create a Path you need two Points and a Path object:
+It is also possible to create Paths and Polygons and to use them together with markers.
+Paths and Polygons will by default encode it's points with Google's encoding algorithm.
+
+To create a Path you need two Points and a Path object:
   path = GoogleStaticMapsHelper::Path.new
   start_point = {:lat => 1, :lng => 2} # You can also use any object which responds to lat and lng here
   end_point = {:lat => 1, :lng => 2}
@@ -136,9 +139,6 @@ It also have a helper method called <tt>endpoints_for_circle_with_radius</tt> wh
   map << path
 
 
-== TODO
-* Add support for encoded polylines (http://code.google.com/apis/maps/documentation/staticmaps/#EncodedPolylines).
-
 == Copyright
 
 Copyright (c) 2009 Thorbjørn Hermansen. See LICENSE for details.

data/VERSION

@@ -1 +1 @@
-1.3.3
+1.3.4

data/changelog.txt

@@ -1,4 +1,8 @@
-= v.1.3.3 (in git)
+= v.1.3.4
+* Paths are now as default encoding it's points with Google's encoding algorithm. Thanks to Joel Rosenberg for providing an easy class to use.
+This will cut the length of the generated URL quite a bit; down to between 1/3 and 1/2 of the old size.
+
+= v.1.3.3
 * We are now supporting ruby 1.9.1.
 
 = v.1.3.2

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.3"
+  s.version = "1.3.4"
 
   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-12-01}
+  s.authors = ["Thorbjørn Hermansen"]
+  s.date = %q{2009-12-03}
   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 = [
@@ -26,6 +26,7 @@ Gem::Specification.new do |s|
      "changelog.txt",
      "google_static_maps_helper.gemspec",
      "lib/google_static_maps_helper.rb",
+     "lib/google_static_maps_helper/gmap_polyline_encoder.rb",
      "lib/google_static_maps_helper/location.rb",
      "lib/google_static_maps_helper/map.rb",
      "lib/google_static_maps_helper/marker.rb",

data/lib/google_static_maps_helper.rb

@@ -4,6 +4,7 @@ require File.dirname(__FILE__) + '/google_static_maps_helper/map'
 require File.dirname(__FILE__) + '/google_static_maps_helper/location'
 require File.dirname(__FILE__) + '/google_static_maps_helper/marker'
 require File.dirname(__FILE__) + '/google_static_maps_helper/path'
+require File.dirname(__FILE__) + '/google_static_maps_helper/gmap_polyline_encoder'
 
 # 
 # The Google Static Map Helper provides a simple interface to the

data/lib/google_static_maps_helper/gmap_polyline_encoder.rb

@@ -0,0 +1,390 @@
+#--
+#
+# Utility for creating Google Maps Encoded GPolylines
+#
+# License: You may distribute this code under the same terms as Ruby itself
+#
+# Author: Joel Rosenberg
+#
+# ( Drawing from the official example pages as well as Mark McClure's work )
+#
+# == Example
+#
+#   data = [
+#     [ 37.4419, -122.1419],
+#     [ 37.4519, -122.1519],
+#     [ 37.4619, -122.1819],
+#   ]
+#
+#   encoder = GMapPolylineEncoder.new()
+#   result = encoder.encode( data )
+#
+#   javascript << "  var myLine = new GPolyline.fromEncoded({\n"
+#   javascript << "     color: \"#FF0000\",\n"
+#   javascript << "     weight: 10,\n"
+#   javascript << "     opacity: 0.5,\n"
+#   javascript << "     zoomFactor: #{result[:zoomFactor]},\n"
+#   javascript << "     numLevels: #{result[:numLevels]},\n"
+#   javascript << "     points: \"#{result[:points]}\",\n"
+#   javascript << "     levels: \"#{result[:levels]}\"\n"
+#   javascript << "  });"
+#
+# == Methods
+#
+#   Constructor args (all optional): 
+#     :numLevels (default 18)
+#     :zoomFactor (default 2)
+#     :reduce: Reduce points (default true)
+#     :escape: Escape backslashes (default true)
+#
+#   encode( points ) method
+#     points (required): array of longitude, latitude pairs
+#
+#     returns hash with keys :points, :levels, :zoomFactor, :numLevels
+#
+# == Background
+#
+# Description: http://www.google.com/apis/maps/documentation/#Encoded_Polylines
+# API: http://www.google.com/apis/maps/documentation/reference.html#GPolyline
+# Hints: http://www.google.com/apis/maps/documentation/polylinealgorithm.html
+#
+# Example Javascript for instantiating an encoded polyline:
+# var encodedPolyline = new GPolyline.fromEncoded({
+#     color: "#FF0000",
+#     weight: 10,
+#     points: "yzocFzynhVq}@n}@o}@nzD",
+#     levels: "BBB",
+#     zoomFactor: 32,
+#     numLevels: 4
+# });
+#
+# == Changes
+#
+# 06.29.2007 - Release 0.1
+#            Profiling showed that distance() accounted for 50% of the time when
+#            processing McClure's British coast data. By moving the distance
+#            calculation into encode(), we can cache a few of the calculations
+#            (magnitude) and eliminate the overhead of the function call. This
+#            reduced the time to encode by ~ 30%
+#
+# 06.21.2007 Implementing the Doublas-Peucker algorithm for removing superflous
+#            points as per Mark McClure's design:
+#                http://facstaff.unca.edu/mcmcclur/GoogleMaps/EncodePolyline/
+#
+# 10.14.2006 Cleaned up (and finally grasped) zoom levels
+#
+# 09.2006    First port of the official example's javascript. Ignoring zoom
+#            levels for now, showing points at all zoom levels
+#
+#++
+module GoogleStaticMapsHelper
+  class GMapPolylineEncoder
+    attr_accessor :reduce, :escape #zoomFactor and numLevels need side effects
+    attr_reader :zoomFactor, :numLevels
+    
+    # The minimum distance from the line that a point must exceed to avoid
+    # elimination under the DP Algorithm.
+    @@dp_threshold = 0.00001
+    
+    def initialize(options = {})
+      # There are no required parameters
+
+      # Nice defaults
+      @numLevels  = options.has_key?(:numLevels)  ? options[:numLevels]  : 18
+      @zoomFactor = options.has_key?(:zoomFactor) ? options[:zoomFactor] : 2
+      
+      # Calculate the distance thresholds for each zoom level
+      calculate_zoom_breaks()
+      
+      # By default we'll simplify the polyline unless told otherwise
+      @reduce = ! options.has_key?(:reduce) ? true : options[:reduce]
+      
+      # Escape by default; most people are using this in a web context
+      @escape = ! options.has_key?(:escape) ? true : options[:escape]
+      
+    end
+    
+    def numLevels=( new_num_levels )
+      @numLevels = new_num_levels
+      # We need to recalculate our zoom breaks
+      calculate_zoom_breaks()
+    end
+    
+    def zoomFactor=( new_zoom_factor )
+      @zoomFactor = new_zoom_factor
+      # We need to recalculate our zoom breaks
+      calculate_zoom_breaks()
+    end
+    
+    def encode( points )
+    
+      #
+      # This is an implementation of the Douglas-Peucker algorithm for simplifying
+      # a line. You can thing of it as an elimination of points that do not
+      # deviate enough from a vector. That threshold for point elimination is in
+      # @@dp_threshold. See
+      #
+      #   http://everything2.com/index.pl?node_id=859282
+      #
+      # for an explanation of the algorithm
+      #
+      
+      max_dist = 0  # Greatest distance we measured during the run
+      stack = []
+      distances = Array.new(points.size)
+    
+      if(points.length > 2)
+        stack << [0, points.size-1]
+        
+        while(stack.length > 0) 
+          current_line = stack.pop()
+          p1_idx = current_line[0]
+          pn_idx = current_line[1]
+          pb_dist = 0
+          pb_idx = nil
+          
+          x1 = points[p1_idx][0]
+          y1 = points[p1_idx][1]
+          x2 = points[pn_idx][0]
+          y2 = points[pn_idx][1]
+          
+          # Caching the line's magnitude for performance
+          magnitude = Math.sqrt((x2 - x1)**2 + (y2 - y1)**2)
+          magnitude_squared = magnitude ** 2
+          
+          # Find the farthest point and its distance from the line between our pair
+          for i in (p1_idx+1)..(pn_idx-1)
+          
+            # Refactoring distance computation inline for performance
+            #current_distance = compute_distance(points[i], points[p1_idx], points[pn_idx])
+            
+            # 
+            # This uses Euclidian geometry. It shouldn't be that big of a deal since
+            # we're using it as a rough comparison for line elimination and zoom
+            # calculation.
+            #
+            # TODO: Implement Haversine functions which would probably bring this to
+            #       a snail's pace (ehhhh)
+            #
+      
+            px = points[i][0]
+            py = points[i][1]
+           
+            current_distance = nil
+            
+            if( magnitude == 0 )
+              # The line is really just a point
+              current_distance = Math.sqrt((x2-px)**2 + (y2-py)**2)
+            else
+           
+              u = (((px - x1) * (x2 - x1)) + ((py - y1) * (y2 - y1))) / magnitude_squared
+              
+              if( u <= 0 || u > 1 )
+                  # The point is closest to an endpoint. Find out which one
+                  ix = Math.sqrt((x1 - px)**2 + (y1 - py)**2)
+                  iy = Math.sqrt((x2 - px)**2 + (y2 - py)**2)
+                  if( ix > iy )
+                    current_distance = iy
+                  else
+                    current_distance = ix
+                  end
+              else
+                  # The perpendicular point intersects the line
+                  ix = x1 + u * (x2 - x1)
+                  iy = y1 + u * (y2 - y1)
+                  current_distance = Math.sqrt((ix - px)**2 + (iy - py)**2)
+              end
+            end
+            
+            # See if this distance is the greatest for this segment so far
+            if(current_distance > pb_dist)
+              pb_dist = current_distance
+              pb_idx = i
+            end
+          end
+          
+          # See if this is the greatest distance for all points
+          if(pb_dist > max_dist)
+            max_dist = pb_dist
+          end
+          
+          if(pb_dist > @@dp_threshold)
+            # Our point, Pb, that had the greatest distance from the line, is also
+            # greater than our threshold. Process again using Pb as a new 
+            # start/end point. Record this distance - we'll use it later when
+            # creating zoom values
+            distances[pb_idx] = pb_dist
+            stack << [p1_idx, pb_idx]
+            stack << [pb_idx, pn_idx]
+          end
+          
+        end
+      end
+      
+      # Force line endpoints to be included (sloppy, but faster than checking for
+      # endpoints in encode_points())
+      distances[0] = max_dist
+      distances[distances.length-1] = max_dist
+    
+      # Create Base64 encoded strings for our points and zoom levels
+      points_enc = encode_points( points, distances)
+      levels_enc = encode_levels( points, distances, max_dist)
+      
+      # Make points_enc an escaped string if desired.
+      # We should escape the levels too, in case google pulls a switcheroo
+      @escape && points_enc && points_enc.gsub!( /\\/, '\\\\\\\\' )
+     
+      
+      # Returning a hash. Yes, I am a Perl programmer
+      return {
+        :points     => points_enc,
+        :levels     => levels_enc,
+        :zoomFactor => @zoomFactor,
+        :numLevels  => @numLevels,
+      }
+      
+    end
+    
+    private
+    
+    def calculate_zoom_breaks()
+      # Calculate the distance thresholds for each zoom level
+      @zoom_level_breaks = Array.new(@numLevels);
+      
+      for i in 0..(@numLevels-1)
+        @zoom_level_breaks[i] = @@dp_threshold * (@zoomFactor ** ( @numLevels-i-1));
+      end
+      
+      return
+    end
+    
+    def encode_points( points, distances )
+      encoded = ""
+      
+      plat = 0
+      plon = 0
+
+      #points.each do |point| # Gah, need the distances.
+      for i in 0..(points.size() - 1)
+        if(! @reduce || distances[i] != nil )
+          point = points[i]
+          late5 = (point[0] * 1e5).floor();
+          lone5 = (point[1] * 1e5).floor();
+
+          dlat = late5 - plat
+          dlon = lone5 - plon
+
+          plat = late5;
+          plon = lone5;
+
+          # I used to need this for some reason
+          #encoded << encodeSignedNumber(Fixnum.induced_from(dlat)).to_s
+          #encoded << encodeSignedNumber(Fixnum.induced_from(dlon)).to_s
+          encoded << encodeSignedNumber(dlat).to_s
+          encoded << encodeSignedNumber(dlon).to_s
+        end
+      end
+
+      return encoded
+
+    end
+    
+    def encode_levels( points, distances, max_dist )
+      
+      encoded = "";
+      
+      # Force startpoint
+      encoded << encodeNumber(@numLevels - 1)
+      
+      if( points.size() > 2 )
+        for i in 1..(points.size() - 2)
+          distance = distances[i]
+          if( ! @reduce || distance != nil)
+            computed_level = 0
+          
+            while (distance < @zoom_level_breaks[computed_level]) do
+              computed_level += 1
+            end
+            
+            encoded << encodeNumber( @numLevels - computed_level - 1 )
+          end
+        end
+      end
+      
+      # Force endpoint
+      encoded << encodeNumber(@numLevels - 1)
+      
+      return encoded;
+      
+    end
+   
+    def compute_distance( point, lineStart, lineEnd )
+    
+      #
+      # Note: This has been refactored to encode() inline for performance and 
+      #       computation caching
+      #
+      
+      px = point[0]
+      py = point[1]
+      x1 = lineStart[0]
+      y1 = lineStart[1]
+      x2 = lineEnd[0]
+      y2 = lineEnd[1]
+     
+      distance = nil
+     
+      magnitude = Math.sqrt((x2 - x1)**2 + (y2 - y1)**2)
+      
+      if( magnitude == 0 )
+        return Math.sqrt((x2-px)**2 + (y2-py)**2)
+      end
+     
+      u = (((px - x1) * (x2 - x1)) + ((py - y1) * (y2 - y1))) / (magnitude**2)
+      
+      if( u <= 0 || u > 1 )
+          # The point is closest to an endpoint. Find out which
+          ix = Math.sqrt((x1 - px)**2 + (y1 - py)**2)
+          iy = Math.sqrt((x2 - px)**2 + (y2 - py)**2)
+          if( ix > iy )
+            distance = iy
+          else
+            distance = ix
+          end
+      else
+          # The perpendicular point intersects the line
+          ix = x1 + u * (x2 - x1)
+          iy = y1 + u * (y2 - y1)
+          distance = Math.sqrt((ix - px)**2 + (iy - py)**2)
+      end
+      
+      return distance
+    end
+    
+    def encodeSignedNumber(num)
+      # Based on the official google example
+      
+      sgn_num = num << 1
+
+      if( num < 0 )
+          sgn_num = ~(sgn_num)
+      end
+
+      return encodeNumber(sgn_num)
+    end
+
+    def encodeNumber(num)
+      # Based on the official google example
+      
+      encoded = "";
+
+      while (num >= 0x20) do
+          encoded << ((0x20 | (num & 0x1f)) + 63).chr;
+          num = num >> 5;
+      end
+
+      encoded << (num + 63).chr;
+      return encoded;
+    end
+  end
+end

data/lib/google_static_maps_helper/path.rb

@@ -9,7 +9,7 @@ module GoogleStaticMapsHelper
 
     OPTIONAL_OPTIONS = [:weight, :color, :fillcolor]
 
-    attr_accessor :points, *OPTIONAL_OPTIONS
+    attr_accessor :encode_points, :points, *OPTIONAL_OPTIONS
 
     #
     # Creates a new Path which you can push points on to to make up lines or polygons
@@ -25,9 +25,11 @@ module GoogleStaticMapsHelper
     #                       as described in the <tt>:color</tt>. When used, the static map will automatically create
     #                       a closed shape.
     # <tt>:points</tt>::    An array of points. You can mix objects responding to lng and lat, and a Hash with lng and lat keys.
+    # <tt>:encode_points::  A flag which tells us if we should encode the points in this path or not. Defaults to <tt>true</tt>
     #
     def initialize(*args)
       @points = []
+      @encode_points = true
     
       extract_options!(args)
       add_points(args)
@@ -49,9 +51,9 @@ module GoogleStaticMapsHelper
 
       out += "#{path_params}|" unless path_params.empty?
 
-      out += inject([]) do |point_params, point|
-        point_params << point.to_url
-      end.join('|')
+      out += encoded_url_points if encoding_points?
+      out += unencoded_url_points unless encoding_points?
+      out
     end
 
   
@@ -78,6 +80,10 @@ module GoogleStaticMapsHelper
       length == 0
     end
 
+    def clear
+      @points = []
+    end
+
     #
     # Pushes a new point into the Path
     #
@@ -91,6 +97,14 @@ module GoogleStaticMapsHelper
       self
     end
 
+    #
+    # Will answer the question if we are encoding the points or not when
+    # building the image URL.
+    #
+    def encoding_points?
+      return !!@encode_points
+    end
+
 
     private
     #
@@ -117,5 +131,19 @@ module GoogleStaticMapsHelper
     def add_points(points)
       points.each {|point| self << point}
     end
+
+    def encoded_url_points
+      encoder = GMapPolylineEncoder.new
+      points_as_array = points.map { |location| [location.lat, location.lng]}
+      result = encoder.encode(points_as_array)
+
+      "enc:#{result[:points]}"
+    end
+
+    def unencoded_url_points
+      inject([]) do |point_params, point|
+        point_params << point.to_url
+      end.join('|')
+    end
   end
 end

data/spec/google_static_maps_helper_spec.rb

@@ -35,7 +35,7 @@ describe GoogleStaticMapsHelper do
         point2 = {:lat => 3, :lng => 4}
 
         out = GoogleStaticMapsHelper.url_for do
-          path point, point2, :color => :red
+          path point, point2, :color => :red, :encode_points => false
         end
 
         out.should include('path=color:red|1,2|3,4')

data/spec/map_spec.rb

@@ -357,7 +357,7 @@ describe GoogleStaticMapsHelper::Map do
 
     describe "paths" do
       before do
-        @path = GoogleStaticMapsHelper::Path.new
+        @path = GoogleStaticMapsHelper::Path.new :encode_points => false
         @point = GoogleStaticMapsHelper::Location.new(:lat => 1, :lng => 2)
         @point2 = GoogleStaticMapsHelper::Location.new(:lat => 3, :lng => 4)
         @path << @point << @point2

data/spec/path_spec.rb

@@ -21,6 +21,23 @@ describe GoogleStaticMapsHelper::Path do
       end
     end
 
+    describe "encoding points flag" do
+      it "should be able to set to false" do
+        path = GoogleStaticMapsHelper::Path.new(:encode_points => false)
+        path.should_not be_encoding_points
+      end
+
+      it "should be able to set to true" do
+        path = GoogleStaticMapsHelper::Path.new(:encode_points => true)
+        path.should be_encoding_points
+      end
+
+      it "should be true as default" do
+        path = GoogleStaticMapsHelper::Path.new
+        path.should be_encoding_points
+      end
+    end
+
     describe "points" do
       before do
         @point = GoogleStaticMapsHelper::Location.new(:lat => 1, :lng => 2)
@@ -50,6 +67,12 @@ describe GoogleStaticMapsHelper::Path do
       @path.points.should == []
     end
 
+    it "should be possible to clear points" do
+      @path << @point << @point2
+      @path.clear
+      @path.length.should == 0
+    end
+
     it "should be able to push points on to a path" do
       @path << @point
       @path.points.length.should == 1
@@ -102,7 +125,7 @@ describe GoogleStaticMapsHelper::Path do
 
   describe "url_params" do
     before do
-      @path = GoogleStaticMapsHelper::Path.new
+      @path = GoogleStaticMapsHelper::Path.new :encode_points => false
       @point = GoogleStaticMapsHelper::Location.new(:lat => 1, :lng => 2)
       @point2 = GoogleStaticMapsHelper::Location.new(:lat => 3, :lng => 4)
       @path << @point << @point2
@@ -148,5 +171,19 @@ describe GoogleStaticMapsHelper::Path do
     it "should concat point locations without any path options" do
       @path.url_params.should == 'path=1,2|3,4'
     end
+
+    describe "encoded poly lines" do
+      before do
+        @path.encode_points = true
+      end
+
+      it "should include 'enc:'" do
+        @path.url_params.should include('enc:')
+      end
+
+      it "should include encoded version of lng and lat" do
+        @path.url_params.should include('_ibE_seK_seK_seK')
+      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.3
+  version: 1.3.4
 platform: ruby
 authors: 
 - "Thorbj\xC3\xB8rn Hermansen"
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-12-01 00:00:00 +01:00
+date: 2009-12-03 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -41,6 +41,7 @@ files:
 - changelog.txt
 - google_static_maps_helper.gemspec
 - lib/google_static_maps_helper.rb
+- lib/google_static_maps_helper/gmap_polyline_encoder.rb
 - lib/google_static_maps_helper/location.rb
 - lib/google_static_maps_helper/map.rb
 - lib/google_static_maps_helper/marker.rb