sinatra_wms 0.0.1 → 0.0.2

data/Gemfile

@@ -2,3 +2,6 @@ source "http://rubygems.org"
 
 # Specify your gem's dependencies in sinatra_wms.gemspec
 gemspec
+
+gem 'rdoc'
+

data/README.rdoc

@@ -0,0 +1,81 @@
+= SintraWMS
+
+== What does SinatraWMS do?
+
+Suppose you have a huge amount of data containing geolocations which you want to show graphically.
+
+One way to achieve this would be to create a more or less huge image file with RMagick or something and just draw the data into this file.  
+This approach has two drawbacks: Either the image file you create will get really huge - or it won't get that large but doesn't provide the needed or wanted resolution. Also, you will just get a black image with white dots on it or something - not very nice. A real map as background would be nice.
+
+Another way would be to use a Google Map or something and use a JavaScript to add lots and lots of markers to the map.  
+You could zoom in and out an such - but you'd have to care about getting your data to JavaScript to add the markers. And it won't be that fast once you reach some kind of limit.
+
+The solution for this problem: WMS (Web Map Service).  
+This gem helps you to provide a WMS to be used with OpenLayers. OpenLayers will display the OpenStreetMap at a configurable Opacity and add your data on top of it. Whenever you scroll or zoom around the map, OpenLayers will request images of a part of the visible screen. Your code has to generate them on-the-fly and deliver them back.
+
+
+== How do I use SinatraWMS?
+
+Let's build a sample app.  
+In my example, I will use SinatraWMS to display the locations of my geolocated tweets.
+
++Gemfile+:
+  source :rubygems
+  
+  gem "sinatra"
+  gem "rmagick"
+  gem "sinatra_wms"
+  gem "activerecord" # I'm using ActiveRecord to retrieve my data from the Database. You can do this your own way.
+
++sinatra_wms_test.rb+:
+  # This is just stuff for my ActiveRecord-addiction. ;-)
+  # You can use DataMapper, mysql, whatever.
+  
+  ActiveRecord::Base.establish_connection(
+      :adapter => 'mysql',
+      :host =>     'localhost',
+      :username => 'twirror',
+      :password => 'secret',
+      :database => 'twirror',
+      :encoding => 'UTF8')
+  
+  class Tweet < ActiveRecord::Base
+  end
+  
+  before do
+      ActiveRecord::Base.connection.verify!
+  end
+  # End of my ActiveRecord-stuff.
+  
+  # This is the main entry point for this app.
+  # This code just outputs generic HTML code to load OpenLayers, show the OSM
+  # as transparent background and our WMS stuff on top of that.
+  get '/' do
+      SinatraWMS::get_html_for_map_at url("/wms"), :opacity=>0.3, :title=>"My Tweets"
+  end
+  
+  # This code gets run for every image requested by OpenLayers. It is given a
+  # RMagick::Draw object on which you can immediately start painting as well as
+  # a hash containing some information about this request.
+  wms '/wms' do |canvas, options|
+      # Select matching Tweets from the DB.
+      # :bbox denotes the area visible in the current image. So we only select
+      # Tweets with coordinates within this box to draw.
+      # We also use a limit here, because Drawing lots and lots of points with
+      # RMagick is pretty slow. Since zooming in reduces the area each image has
+      # to span, more and more points are going to show up when we zoom in.
+      rel = Tweet.where(:sender_name=>'fabianonline').
+          where("geo_lat IS NOT NULL and geo_long IS NOT NULL").
+          where("geo_lat>=? and geo_lat<=?", options[:bbox][:wgs84][0][0], options[:bbox][:wgs84][1][0]).
+          where("geo_long>=? and geo_long<=?", options[:bbox][:wgs84][0][1], options[:bbox][:wgs84][1][1]).
+          limit(1000)
+      
+      rel.each do |tweet|
+          # Draw each point. This gem extends RMagick::Draw to provide some
+          # methods which directly take coordinates in WGS84 (that's the most)
+          # commonly used format for coordinates. You know, longitude between
+          # -180 (West) and 180 (East) degrees and latitude between -90 (South) 
+          # and 90 (North) degrees).
+          canvas.point_wgs84(tweet.geo_long, tweet.geo_lat)
+      end
+  end

data/Rakefile

@@ -1 +1,7 @@
+require 'rdoc/task'
 require 'bundler/gem_tasks'
+
+RDoc::Task.new do |r|
+	r.main = "README.rdoc"
+	r.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+end

data/lib/sinatra_wms.rb

@@ -3,16 +3,24 @@ require "sinatra_wms/sinatra_extension"
 require "sinatra_wms/rmagick_extension"
 
 module SinatraWMS
+	
+	##
+	# Convert a set of coordinates from sperical mercator to WGS84.
 	def self.merc_to_latlon(x, y)
 		lon = (x / 6378137.0) / Math::PI * 180
 		lat = Math::atan(Math::sinh(y / 6378137.0)) / Math::PI * 180
 		return [lat, lon]
 	end
-
-	def self.deg_sin(x)
-		Math.sin(x * Math::PI / 180)
-	end
 	
+	##
+	# Returns generic HTML code to display a transparent OSM map and images from the WMS.
+	#
+	# * +url+ has to be the full URL to the WMS. Since this module can't use Sinatra's helper,
+	#   please call it using this helper, e.g. +url("/wms")+.
+	# * Other options used are:
+	#   * +:title+ - Sets the HTML title attribute.
+	#   * +:opacity:+ - Sets the opacity of the OSM map in the background.
+	#   * +:datasource_name+ - Sets the name of the WMS source in the layer selector menu.
 	def self.get_html_for_map_at(url, options={})
 		options[:title] ||= "Sinatra-WMS"
 		options[:opacity] ||= 1

data/lib/sinatra_wms/rmagick_extension.rb

@@ -1,10 +1,18 @@
 require 'RMagick'
 
+##
+# Monkeypatching RMagick to add some methods to +Magick::Draw+.
 module Magick
 	class Draw
+		##
+		# Which methods with one coordinates as parameter to add +_wgs84+ method to
 		WMS_FUNCTIONS_SINGLE = %w(color matte point text bigpoint)
+		##
+		# Which methods with two coordinates as parameter to add +_wgs84+ method to
 		WMS_FUNCTIONS_DOUBLE = %w(circle ellipse line rectangle roundrectangle)
 		
+		##
+		# We use method_missing to catch calls to the +_wgs84+ methods.
 		def method_missing(sym, *args, &block)
 			result = sym.to_s.match /^([a-z0-9_]+)_(?:wgs84)$/
 			if result && respond_to?(result[1]) && @wms_settings
@@ -20,6 +28,9 @@ module Magick
 			end
 		end
 		
+		##
+		# This method gets the data from +SinatraExtension+ and does some calculations
+		# to have values prepared when they're needed.
 		def wms_settings=(hash)
 			hash[:min_sin_y] = Math::asinh(Math::tan(hash[:bbox][0][0] / 180.0 * Math::PI)) * 6378137.0
 			hash[:max_sin_y] = Math::asinh(Math::tan(hash[:bbox][1][0] / 180.0 * Math::PI)) * 6378137.0
@@ -27,17 +38,24 @@ module Magick
 			hash[:factor_x] = hash[:width] / (hash[:bbox][1][1] - hash[:bbox][0][1])
 			@wms_settings = hash
 		end
-
+		
+		##
+		# The same as +point+, but draws a "big point" with 3 pixels width and height.
 		def bigpoint(x, y)
 			rectangle(x-1, y-1, x+1, y+1)
 		end
 		
+		##
+		# See +method_missing+
 		def respond_to?(sym)
 			result = sym.to_s.match /^([a-z0-9_]+)_(?:wgs84)$/
 			(result && super(result[1]) && @wms_settings) || super(sym)
 		end
 		
 		private
+		##
+		# Converts WGS84 coordinates to pixel values.
+		# Gets called via +method_missing+, whenever one of the +*_wgs84* methods is used.
 		def latlon_to_pixels(x, y)
 			raise "wms_settings is missing values" unless [:bbox, :factor_x, :min_sin_y, :max_sin_y, :height].all?{|v| @wms_settings.has_key?(v)}
 			x = ((x - @wms_settings[:bbox][0][1]) * @wms_settings[:factor_x]).round

data/lib/sinatra_wms/sinatra_extension.rb

@@ -1,6 +1,19 @@
 require 'sinatra/base'
+##
+# +Sinatra+ is extended to contain the method +wms+, which controls all the
+# WMS-relevant stuff.
 module Sinatra
 	module WMS
+		##
+		# Reacts on WMS calls
+		#
+		# Defines an +url+ to react on WMS calls.
+		# If we get a matching request, we will do some fancy calculations to the
+		# parameters given (as in "convert the bounding box from sperical mercator
+		# to the well-known WGS84 projection" and so on.)
+		# Also, we will prepare an image and a matching canvas which we give to the
+		# given block.
+		# After the block has run, we return the image to the requestee.
 		def wms(url, &block)
 			get url do
 				headers "Content-Type" => "image/png"
@@ -10,7 +23,7 @@ module Sinatra
 				# interpret :width and :height as integer
 				[:width, :height].each {|what| options[what] = options[what].to_i}
 				
-				# convert bounding box coordinates
+				# convert bounding box coordinates to WGS84
 				bbox = options[:bbox].split(',').collect{|v| v.to_f}
 				options[:bbox] = {:original => [[bbox[0], bbox[1]], [bbox[2], bbox[3]]]}
 				if options[:srs]=="EPSG:900913"
@@ -19,19 +32,26 @@ module Sinatra
 				else
 					raise "Unexpected Projection (srs): #{options[:srs]}"
 				end
+				
+				# calculate the current zoom level (between 0 and 17, with 0 being the while world)
 				options[:zoom] = (17-((Math.log((options[:bbox][:google][1][0]-options[:bbox][:google][0][0]).abs*3.281/500) / Math.log(2)).round))
-
+				
+				# generate a transparent image, an empty canvas and set the default
+				# drawing color to black
 				image = Magick::Image.new(options[:width], options[:height]) { self.background_color = 'transparent' }
 				gc = Magick::Draw.new
 				gc.stroke("black")
 				
+				# The canvas needs some values for the calculations for the +*_wgs84+ methods.
 				gc.wms_settings = {
 					:bbox => options[:bbox][:wgs84],
 					:width => options[:width],
 					:height => options[:height]}
 				
+				# Call the block
 				block.call(gc, options)
 				
+				# Add the canvas to the image and return the resulting image as PNG.
 				gc.draw(image) rescue nil
 				image.to_blob {self.format="png"}
 			end

data/lib/sinatra_wms/version.rb

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

data/sinatra_wms.gemspec

@@ -20,5 +20,6 @@ This gem allows you to very easily represent your data via a WMS. On one hand it
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.extra_rdoc_files = ["README.rdoc"]
   s.require_paths = ["lib"]
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: sinatra_wms
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 27
   prerelease: 
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Fabian Schlenz (@fabianonline)
@@ -57,12 +57,12 @@ executables: []
 
 extensions: []
 
-extra_rdoc_files: []
-
+extra_rdoc_files: 
+- README.rdoc
 files: 
 - .gitignore
 - Gemfile
-- README.md
+- README.rdoc
 - Rakefile
 - lib/sinatra_wms.rb
 - lib/sinatra_wms/rmagick_extension.rb

data/README.md

@@ -1,89 +0,0 @@
-SintraWMS
-=========
-
-What does SinatraWMS do?
-------------------------
-
-Suppose you have a huge amount of data containing geolocations which you want to show graphically.
-
-One way to achieve this would be to create a more or less huge image file with RMagick or something and just draw the data into this file.  
-This approach has two drawbacks: Either the image file you create will get really huge - or it won't get that large but doesn't provide the needed or wanted resolution. Also, you will just get a black image with white dots on it or something - not very nice. A real map as background would be nice.
-
-Another way would be to use a Google Map or something and use a JavaScript to add lots and lots of markers to the map.  
-You could zoom in and out an such - but you'd have to care about getting your data to JavaScript to add the markers. And it won't be that fast once you reach some kind of limit.
-
-The solution for this problem: WMS (Web Map Service).  
-This gem helps you to provide a WMS to be used with OpenLayers. OpenLayers will display the OpenStreetMap at a configurable Opacity and add your data on top of it. Whenever you scroll or zoom around the map, OpenLayers will request images of a part of the visible screen. Your code has to generate them on-the-fly and deliver them back.
-
-
-How do I use SinatraWMS?
-------------------------
-
-Let's build a sample app.  
-In my example, I will use SinatraWMS to display the locations of my geolocated tweets.
-
-**Gemfile:**
-```ruby
-source :rubygems
-
-gem "sinatra"
-gem "rmagick"
-gem "sinatra_wms"
-gem "activerecord" # I'm using ActiveRecord to retrieve my data from the Database. You can do this your own way.
-```
-
-**sinatra_wms_test:**
-```ruby
-# This is just stuff for my ActiveRecord-addiction. ;-)
-# You can use DataMapper, mysql, whatever.
-
-ActiveRecord::Base.establish_connection(
-    :adapter => 'mysql',
-    :host =>     'localhost',
-    :username => 'twirror',
-    :password => 'secret',
-    :database => 'twirror',
-    :encoding => 'UTF8')
-
-class Tweet < ActiveRecord::Base
-end
-
-before do
-	ActiveRecord::Base.connection.verify!
-end
-# End of my ActiveRecord-stuff.
-
-# This is the main entry point for this app.
-# This code just outputs generic HTML code to load OpenLayers, show the OSM
-# as transparent background and our WMS stuff on top of that.
-get '/' do
-	SinatraWMS::get_html_for_map_at url("/wms"), :opacity=>0.3, :title=>"My Tweets"
-end
-
-# This code gets run for every image requested by OpenLayers. It is given a
-# RMagick::Draw object on which you can immediately start painting as well as
-# a hash containing some information about this request.
-wms '/wms' do |canvas, options|
-	# Select matching Tweets from the DB.
-	# :bbox denotes the area visible in the current image. So we only select
-	# Tweets with coordinates within this box to draw.
-	# We also use a limit here, because Drawing lots and lots of points with
-	# RMagick is pretty slow. Since zooming in reduces the area each image has
-	# to span, more and more points are going to show up when we zoom in.
-	rel = Tweet.where(:sender_name=>'fabianonline').
-		where("geo_lat IS NOT NULL and geo_long IS NOT NULL").
-		where("geo_lat>=? and geo_lat<=?", options[:bbox][:wgs84][0][0], options[:bbox][:wgs84][1][0]).
-		where("geo_long>=? and geo_long<=?", options[:bbox][:wgs84][0][1], options[:bbox][:wgs84][1][1]).
-		limit(1000)
-		
-	rel.each do |tweet|
-		# Draw each point. This gem extends RMagick::Draw to provide some
-		# methods which directly take coordinates in WGS84 (that's the most)
-		# commonly used format for coordinates. You know, longitude between
-		# -180 (West) and 180 (East) degrees and latitude between -90 (South) 
-		# and 90 (North) degrees).
-		canvas.point_wgs84(tweet.geo_long, tweet.geo_lat)
-	end
-end
-
-```