basis-processing 0.5.9 → 0.6.0

data/README

@@ -4,13 +4,15 @@ Please send bug reports to (avishek.sen.gupta at gmail.com)
 
 **Basis** provides a set of classes for easily plotting and transforming arbitrary 2D coordinate systems by specifying their basis vectors. Originally developed to work with Ruby-Processing, it now supports any class which supports Processing-like semantics.
 
-UPDATE: Starting from version 0.5.9, you can turn grid lines on or off.
+**UPDATE:** Starting from version 0.6.0, Basis allows you to specify axis labels. Additionally, you can specify arrays of points instead of plotting points one at a time. When you do this, you can also specify a corresponding legend string, which will show up in a legend guide. See below for more details.
 
-UPDATE: Starting from version 0.5.8, you can customise axis labels, draw arbitrary shapes/text/plot custom graphics at any point in your coordinate system. See below for more details.
+**UPDATE:** Starting from version 0.5.9, you can turn grid lines on or off. Additionally, the matrix operations implementation has been ported to use the Matrix class in Ruby's stdlib.
 
-UPDATE: With version 0.5.7, experimental support has been added for drawing objects which aren’t points. Interactions with such objects is currently not supported. Additional support for drawing markers/highlighting in custom bases is now in.
+**UPDATE:** Starting from version 0.5.8, you can customise axis labels, draw arbitrary shapes/text/plot custom graphics at any point in your coordinate system. See below for more details.
 
-UPDATE: Starting from version 0.5.1, Basis has been ported to Ruby 1.9.2, because of the kd-tree library dependency. Currently, there are no plans of maintaining Basis compatibility with Ruby 1.8.x. As an aside, I personally recommend using RVM to manage the mess of Ruby/JRuby installations that you’re likely to have on your machine.
+**UPDATE:** With version 0.5.7, experimental support has been added for drawing objects which aren’t points. Interactions with such objects is currently not supported. Additional support for drawing markers/highlighting in custom bases is now in.
+
+**UPDATE:** Starting from version 0.5.1, Basis has been ported to Ruby 1.9.2, because of the kd-tree library dependency. Currently, there are no plans of maintaining Basis compatibility with Ruby 1.8.x. As an aside, I personally recommend using RVM to manage the mess of Ruby/JRuby installations that you’re likely to have on your machine.
 
 UPDATE: Basis has hit version 0.5.0 with experimental support for mouseover interactivity. More work is incoming, but the demo code below is up-to-date, for now. Starting from version 0.5.0, experimental support has been added for mouseover interactivity without (too much) extra effort on your part. This is still a work in progress, though.
 
@@ -96,6 +98,18 @@ Here's some example code, which plots random points.
 	Demo.send :include, Interactive
 	Demo.new(:title => "My Sketch", :width => w, :height => h)
 
+You may choose to plot each point individually, as in the example above. However, you could have achieved the same thing by writing the following directly.
+
+		@screen.plot(points, :legend => 'Some Distribution', :track => true) do |original, mapped, s|
+			s.in_basis do
+				rect(original[:x], original[:y], 3, 3)
+			end
+		end
+
+If you choose this route, you can specify a legend, as shown above. This will show up in a legend guide at a default position. You can customise the positioning of the legend box, while creating the Screen object, like so:
+
+		@screen = Screen.new(screen_transform, self, @basis, LegendBox.new(self, {:x => 1300, :y => 30}))
+
 You have a few options when plotting a point. If you specify ':bar => true', like the line below:
 
 	screen.plot(p, basis, :bar => true) {|p| rect(p[:x], p[:y], 5, 5)}
@@ -217,8 +231,8 @@ Consider the following code:
 			background(0,0,0)
 			color_mode(HSB, 1.0)
 			box = {:minimum => 20, :maximum => 70, :q1 => 30, :q2 => 40, :q3 => 50}
-			@x_unit_vector = {:x => 1.0, :y => 0.0}
-			@y_unit_vector = {:x => 0.0, :y => 1.0}
+			@x_unit_vector = {:x => 1.0, :y => 0.15, :legend => 'x-axis'}
+			@y_unit_vector = {:x => 0.2, :y => 1.0, :legend => 'y-axis'}
 			@screen_transform = Transform.new({:x => 5.0, :y => -5.0}, {:x => @width/2, :y => @screen_height})
 			x_range = ContinuousRange.new({:minimum => 0.0, :maximum => 80.0})
 			y_range = ContinuousRange.new({:minimum => 0.0, :maximum => box[:maximum]})
@@ -252,8 +266,10 @@ The first interesting thing in the code above is that the box hash does not have
 
 The other interesting thing about the above code will become evident if we specify a different set of basis vectors like so:
 
-		@x_unit_vector = {:x => 1.0, :y => 0.15}
-		@y_unit_vector = {:x => 0.2, :y => 1.0}
+		@x_unit_vector = {:x => 1.0, :y => 0.15, :label => 'x-axis'}
+		@y_unit_vector = {:x => 0.2, :y => 1.0, :label => 'y-axis'}
+
+Specifying the :label key is optional, Basis will generate its own legends if you don't specify anything.
 
 The box plot in this modified basis acquires the properties of skewness, rotation, etc. of the host coordinate system. This lets you get on with drawing the object without really worrying about the specific properties of the coordinate space you are plotting in.
 
@@ -263,6 +279,17 @@ The other variation you can use is the at() method of a Screen object. at() beha
 
 ## Axis drawing options
 
+Starting from version 0.6.0, you can specify the axis labels. There are two ways to do this. If you're explicitly specifying your own basis vectors, you can specify the labels there, like so:
+
+		@x_unit_vector = {:x => 1.0, :y => 0.15, :label => 'x-axis'}
+		@y_unit_vector = {:x => 0.2, :y => 1.0, :label => 'y-axis'}
+
+If you're using the convenience method to initialise the standard CoordinateSystem, you can specify the labels like so:
+
+		@c = CoordinateSystem.standard(x_range, y_range, self, {:x => 'Score', :y => 'Probability P(score)'})
+
+In the code above, :x maps to 'Score' for the x-axis, and :y maps to 'Probability P(score)' for the y-axis.
+
 Starting from version 0.5.8, you can customise labels, if you pass two blocks to the draw_axes() method, one for the x-axis, the other for the y-axis. For example, in the fragment below, we're not outputting anything for the x-axis labels (returning an empty string), and converting the y-axis value to an integer.
 
 	@screen.draw_axes(10, 10, :x => ->(p){''}, :y => ->(p){p.to_i})
@@ -271,7 +298,7 @@ Grid lines are drawn by default. To turn them off, set the :gridlines key to fal
 
 	@screen.draw_axes(10, 10, :x => ->(p){''}, :y => ->(p){p.to_i}, :gridlines => false)
 
-## Convenience method for setting up default CoordinateSystem
+## The default CoordinateSystem
 
 If you're doing a simple plot, with standard basis vectors with no transformations, you can use the convenience method in CoordinateSystem to set up a default system.
 

data/basis.gemspec

@@ -1,6 +1,6 @@
 spec = Gem::Specification.new do |s| 
   s.name = "basis-processing"
-  s.version = "0.5.9"
+  s.version = "0.6.0"
   s.add_dependency('knnball', '>= 0.0.6')
   s.author = "Avishek Sen Gupta"
   s.email = "avishek.sen.gupta@gmail.com"

data/lib/coordinate_system.rb

@@ -18,9 +18,9 @@ class CoordinateSystem
 	UNIT_TRANSFORM = [[1,0],[0,1]]
 	attr_accessor :x_basis_vector, :y_basis_vector, :basis_matrix
 
-	def self.standard(x_range, y_range, artist)
-		x_basis_vector = {:x => 1.0, :y => 0.0}
-		y_basis_vector = {:x => 0.0, :y => 1.0}
+	def self.standard(x_range, y_range, artist, labels = {:x => 'x', :y => 'y'})
+		x_basis_vector = {:x => 1.0, :y => 0.0, :label => labels[:x]}
+		y_basis_vector = {:x => 0.0, :y => 1.0, :label => labels[:y]}
 
 		x_range = ContinuousRange.new(x_range)
 		y_range = ContinuousRange.new(y_range)

data/lib/demo.rb

@@ -35,7 +35,7 @@ class Demo < Processing::App
 #		@basis = CoordinateSystem.new(Axis.new(@x_unit_vector,x_range), Axis.new(@y_unit_vector,y_range), self, [[1,0],[0,1]])
 
 #		Accomplish the above in a single line below...
-		@basis = CoordinateSystem.standard({:minimum => 0, :maximum => 200}, {:minimum => 0, :maximum => 300}, self)
+		@basis = CoordinateSystem.standard({:minimum => 0, :maximum => 200}, {:minimum => 0, :maximum => 300}, self, {:x => "X-Axis", :y => "Y-Axis"})
 
 		screen_transform = Transform.new({:x => 2, :y => -2}, {:x => 300, :y => 900})
 		@screen = Screen.new(screen_transform, self, @basis)
@@ -43,11 +43,9 @@ class Demo < Processing::App
 		stroke(1,1,0,1)
 		fill(1,1,0)
 		rect_mode(CENTER)
-		points.each do |p|
-			@screen.plot(p, :track => true) do |original, mapped, s|
-				s.in_basis do
-					rect(original[:x], original[:y], 3, 3)
-				end
+		@screen.plot(points, :track => true) do |original, mapped, s|
+			s.in_basis do
+				rect(original[:x], original[:y], 3, 3)
 			end
 		end
 	end

data/lib/interactive.rb

@@ -6,6 +6,7 @@ module Interactive
 		base.class_eval do
 			alias :old_setup :setup
 			alias :old_draw :draw
+			
 			def setup
 				old_setup
 				@cache = Cache.new(self).refresh

data/lib/legend_box.rb

@@ -0,0 +1,14 @@
+class LegendBox
+	def initialize(artist, top_left = {:x => 20, :y => 20})
+		@x = top_left[:x]
+		@y = top_left[:y]
+		@artist = artist
+	end
+
+	def draw(legend)
+		@artist.rect(@x,@y,10,10)
+		@artist.text(legend.strip == '' ? '[Unknown]' : legend, @x + 50, @y)
+		@y += 15
+	end
+end
+

data/lib/screen.rb

@@ -1,6 +1,7 @@
 require 'transform'
 require 'knnball'
 require 'text_output'
+require 'legend_box'
 
 class Screen
 	attr_accessor :points
@@ -11,7 +12,8 @@ class Screen
 		@buffer = nil if !@should_join
 	end
 	
-	def initialize(transform, artist, basis, output=TextOutput.new)
+	def initialize(transform, artist, basis, legend_box=LegendBox.new(artist), output=TextOutput.new)
+		@legend_box = legend_box
 		@transform = transform
 		@artist = artist
 		@basis = basis
@@ -51,7 +53,19 @@ class Screen
 		end
 	end
 
-	def plot(point, options = {:bar => false, :track => false}, &block)
+	def plot(points, options = {:bar => false, :track => false, :legend => ''}, &block)
+		if points.kind_of? Array
+			points.each {|p| plot_single(p, options, &block)}
+		else
+			plot_single(points, options, &block)
+		end
+		return if options[:legend].nil?
+		outside_basis do
+			@legend_box.draw(options[:legend])
+		end
+	end
+
+	def plot_single(point, options = {:bar => false, :track => false}, &block)
 		if (!point[:x] || !point[:y])
 			@artist.reset_matrix
 			block.call(point, self) if block
@@ -129,6 +143,21 @@ class Screen
 		@artist.line(x_ticks.first[:from][:x],x_ticks.first[:from][:y],x_ticks.last[:from][:x],x_ticks.last[:from][:y])
 		@artist.line(y_ticks.first[:from][:x],y_ticks.first[:from][:y],y_ticks.last[:from][:x],y_ticks.last[:from][:y])
 
+		x_axis_label_position = {:x => (x_ticks.first[:from][:x] + x_ticks.last[:from][:x])/2, :y => (x_ticks.first[:from][:y] + x_ticks.last[:from][:y])/2 + 50}
+		y_axis_label_position = {:x => (y_ticks.first[:from][:x] + y_ticks.last[:from][:x])/2 - 60, :y => (y_ticks.first[:from][:y] + y_ticks.last[:from][:y])/2}
+		
+		@artist.push_matrix
+		@artist.translate(x_axis_label_position[:x], x_axis_label_position[:y])
+		@artist.rotate(2*Math::PI - Math.atan2(@basis.x_basis_vector[:y], @basis.x_basis_vector[:x]))
+		@artist.text(@basis.x_basis_vector[:label], 0, 0)
+		@artist.pop_matrix
+
+		@artist.push_matrix
+		@artist.translate(y_axis_label_position[:x], y_axis_label_position[:y])
+		@artist.rotate(2*Math::PI - Math.atan2(@basis.y_basis_vector[:y], @basis.y_basis_vector[:x]))
+		@artist.text(@basis.y_basis_vector[:label], 0, 0)
+		@artist.pop_matrix
+		
 		draw_ticks(x_ticks, {:x => 0, :y => 20}, options[:x])
 		draw_ticks(y_ticks, {:x => -50, :y => 0}, options[:y])
 		
@@ -143,5 +172,7 @@ class Screen
 	def write(p)
 		@output.notify(p)
 	end
+
+	private :draw_ticks, :normal, :plot_single
 end
 

data/redeploy.sh

@@ -1,3 +1,3 @@
 gem build basis.gemspec
 sudo /home/avishek/jruby/jruby-1.6.4/bin/jruby -S gem uninstall basis-processing
-sudo /home/avishek/jruby/jruby-1.6.4/bin/jruby -S gem install basis-processing-0.5.9.gem
+sudo /home/avishek/jruby/jruby-1.6.4/bin/jruby -S gem install basis-processing-0.6.0.gem

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: basis-processing
 version: !ruby/object:Gem::Version 
-  hash: 25
+  hash: 7
   prerelease: 
   segments: 
   - 0
-  - 5
-  - 9
-  version: 0.5.9
+  - 6
+  - 0
+  version: 0.6.0
 platform: ruby
 authors: 
 - Avishek Sen Gupta
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-10-25 00:00:00 Z
+date: 2011-10-26 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: knnball
@@ -53,6 +53,7 @@ files:
 - lib/demo.rb
 - lib/hash_vector.rb
 - lib/interactive.rb
+- lib/legend_box.rb
 - lib/matrix_extensions.rb
 - lib/ranges.rb
 - lib/screen.rb