rubyvis 0.1.7 → 0.2.0

data/History.txt

@@ -1,3 +1,15 @@
+=== 0.2.0 / 2010-11-02
+
+* IMPORTANT: Added 'ruby best practices' API. See README and examples/first_rbp_api.rb to learn how to use
+* Added width and height explicitly on examples pages. 
+* Added examples for interpolation on lines and areas
+* Fixed interpolate for lines and areas. 
+* New spec for Line and Area spec.  
+* Added spec for numeric tick_format
+* Added documentation for Rubyvis::Colors, Rubyvis::Color and Rubyvis::Line
+* Bug fix: interpolate "step-after", "step-before" and "basis" on Area marks doesn't work Spec for Area marks
+* Changed API_VERSION for PROTOVIS_API_VERSION
+
 === 0.1.7 / 2010-10-31
 
 * Added image support

data/Manifest.txt

@@ -5,6 +5,7 @@ Rakefile
 examples/antibiotics/antibiotics.rb
 examples/antibiotics/antibiotics_data.rb
 examples/area.rb
+examples/area_interpolation.rb
 examples/bar_column_chart.rb
 examples/barley/barley.rb
 examples/barley/barley_data.rb
@@ -12,13 +13,15 @@ examples/crimea/crimea_data.rb
 examples/crimea/crimea_grouped_bar.rb
 examples/crimea/crimea_line.rb
 examples/dot.rb
-examples/first.rb
+examples/first_protovis_api.rb
+examples/first_rbp_api.rb
 examples/fixtures/tipsy.gif
 examples/grouped_charts.rb
 examples/image.rb
 examples/image.svg
 examples/line.rb
 examples/line_and_step.rb
+examples/line_interpolation.rb
 examples/nested_grid.rb
 examples/pie_and_donut.rb
 examples/scatterplot.rb
@@ -28,7 +31,6 @@ examples/third.rb
 lib/rubyvis.rb
 lib/rubyvis/color/color.rb
 lib/rubyvis/color/colors.rb
-lib/rubyvis/color/ramp.rb
 lib/rubyvis/format.rb
 lib/rubyvis/format/date.rb
 lib/rubyvis/format/number.rb
@@ -46,6 +48,7 @@ lib/rubyvis/mark/label.rb
 lib/rubyvis/mark/line.rb
 lib/rubyvis/mark/panel.rb
 lib/rubyvis/mark/rule.rb
+lib/rubyvis/mark/shorcut_methods.rb
 lib/rubyvis/mark/wedge.rb
 lib/rubyvis/nest.rb
 lib/rubyvis/property.rb
@@ -56,6 +59,7 @@ lib/rubyvis/scale/ordinal.rb
 lib/rubyvis/scale/quantitative.rb
 lib/rubyvis/scene/svg_area.rb
 lib/rubyvis/scene/svg_bar.rb
+lib/rubyvis/scene/svg_curve.rb
 lib/rubyvis/scene/svg_dot.rb
 lib/rubyvis/scene/svg_image.rb
 lib/rubyvis/scene/svg_label.rb
@@ -67,13 +71,16 @@ lib/rubyvis/scene/svg_wedge.rb
 lib/rubyvis/sceneelement.rb
 lib/rubyvis/transform.rb
 spec/anchor_spec.rb
+spec/area_spec.rb
 spec/bar_spec.rb
 spec/internal_spec.rb
 spec/javascript_behaviour_spec.rb
 spec/label_spec.rb
+spec/line_spec.rb
 spec/mark_spec.rb
 spec/nest_spec.rb
 spec/panel_spec.rb
+spec/ruby_api_spec.rb
 spec/scale_linear_datetime_spec.rb
 spec/scale_linear_spec.rb
 spec/scale_log_spec.rb

data/README.txt

@@ -8,7 +8,7 @@ Ruby port of Protovis[http://vis.stanford.edu/protovis/], a great visualization
 
 == FEATURES/PROBLEMS:
 
-Implemented: All marks, except transient, image and transition. 
+Implemented: All marks, except transient and transitions. 
 
 Basic protovis examples[http://vis.stanford.edu/protovis/ex/] works exactly like ruby ones with minor sintactic modifications:
 * Area Charts: Ok
@@ -28,10 +28,6 @@ Complex examples requires more works:
 
 I try to maintain, when posible, complete compatibility with Javascript API, including camel case naming of functions. Johnson [http://github.com/jbarnette/johnson] - the lovely Javascript wrapper inside Ruby embrace - is our friend to test implementation of basic object. 
 
-Until version 0.1.0, lambdas should always should created explicitly for method you may be temted to call it with a block.
-
-On a second stage, traditional block calling could be using maintaining backwards compatibily with Javascript API. See TODO section for proposal of new API.
-
 User could use +pv+ freely, cause is defined as a global method which call Rubyvis.
 
 == CURRENT PROGRESS
@@ -69,70 +65,45 @@ User could use +pv+ freely, cause is defined as a global method which call Rubyv
 
 == SYNOPSIS:
 
+The primary API, based on Gregory Brown's Ruby Best Practices, uses blocks and name of marks as methods
+
     require 'rubyvis'
     
-    vis = Rubyvis::Panel.new.width(150).height(150);
-    vis.add(pv.Bar).data([1, 1.2, 1.7, 1.5, 0.7, 0.3]).
-    width(20).
-    height(lambda {|d| d * 80}).
-    bottom(0).
-    left(lambda {self.index * 25});
+    vis = Rubyvis::Panel.new do 
+      width 150
+      height 150
+      bar do
+        data [1, 1.2, 1.7, 1.5, 0.7, 0.3]
+        width 20
+        height {|d| d * 80}
+        bottom(0)
+        left {index * 25}
+      end
+    end
+    
     vis.render
     puts vis.to_svg
-    
-See examples directory for original protovis examples adaptations.
-
-== TODO
 
-Implement a ruby-like API, like ReportBuilder[http://ruby-statsample.rubyforge.org/reportbuilder/] or Prawn [http://prawn.majesticseacreature.com/docs/] 
 
-The examples/area.rb script should like somethink like that
+The library allows you to use chain methods API, like original protovis
 
     require 'rubyvis'
-    vis = Rubyvis::Panel.new {
-      width w 
-      height h 
-      bottom 20 
-      left 20 
-      right 10
-      top 5
-      # Y-axis
-      rule {
-        data y.ticks(5)
-        bottom y
-        stroke_style {|d| d!=0 ? "#eee" : "#000"}
-        anchor("left") {  
-          label {
-            text y.tick_format
-          }
-        }
-      }
-      # X-axis
-      rule {
-        data x.ticks
-        visible {|d| d!=0}
-        left x
-        bottom -5
-        height -5
-        label(:anchor=>'bottom') { # shortcut to create a mark inside an anchor
-          text x.tick_format
-        }
-      }
-      
-      # The area with top line.
-      area {
-        data(data)
-        bottom 1
-        left {|d| x.scale(d.x)}
-        height {|d| y.scale(d.y)}
-        fill_style "rgb(121,173,210)"
-        line(:anchor=>"top") {
-          line_width 3
-        }
-      }
-    }
     
+    vis = Rubyvis::Panel.new.width(150).height(150);
+    
+    vis.add(pv.Bar).
+      data([1, 1.2, 1.7, 1.5, 0.7, 0.3]).
+      width(20).
+      height(lambda {|d| d * 80}).
+      bottom(0).
+      left(lambda {self.index * 25});
+    
+    vis.render
     puts vis.to_svg
+    
+
+See examples directory for original protovis examples adaptations and others graphics
+
 
 
 == REQUIREMENTS:

data/examples/area_interpolation.rb

@@ -0,0 +1,56 @@
+# = Area Interpolation
+# This example show the 5 types of interpolation available for areas.
+$:.unshift(File.dirname(__FILE__)+"/../lib")
+require 'rubyvis'
+
+data = pv.range(0, 10, 0.5).map {|x| 
+  OpenStruct.new({:x=> x, :y=> Math.sin(x) + 2+rand()*0.3})
+}
+
+p_w=200
+p_h=150
+#p data
+w = 20+p_w*2
+h = 20+p_h*3
+
+x = pv.Scale.linear(data, lambda {|d| d.x}).range(0, p_w-30)
+y = pv.Scale.linear(data, lambda {|d| d.y}).range(0, p_h-20);
+interpolations=["linear","step-before","step-after", "basis", "cardinal"]
+
+vis = Rubyvis::Panel.new do |pan|
+  pan.width w 
+  pan.height h 
+  pan.bottom 20 
+  pan.left 20 
+  pan.right 10 
+  pan.top 5 
+
+  interpolations.each_with_index do |inter,i|
+    n=i%2
+    m=(i/2).floor
+    pan.panel do
+      left(n*(p_w+10))
+      top(m*(p_h+10))
+      width p_w
+      height p_h
+      label(:anchor=>'top') do
+        text(inter)
+      end
+      # uses 'a' as reference inside block
+      # to use data method with data variable
+      area do |a| 
+        a.data data
+        a.left {|d| x.scale(d.x)}
+        a.height {|d| y.scale(d.y)}
+        a.bottom 1
+        a.interpolate inter
+      end
+    end
+  end
+end  
+     
+
+vis.render();
+
+
+puts vis.to_svg

data/examples/{first.rb → first_protovis_api.rb}

@@ -1,5 +1,5 @@
 # = First example
-# This is the ruby version of "Getting Started" example of Protovis introduction.
+# This is the protovis API version of "Getting Started" example of Protovis introduction.
 # On this example we show you how can you build a bar chart using panel and bar marks.
 # A mark represents a set of graphical elements that share data and visual encodings. Although marks are simple by themselves, you can combine them in interesting ways to make rich, interactive visualizations
 $:.unshift(File.dirname(__FILE__)+"/../lib")

data/examples/first_rbp_api.rb

@@ -0,0 +1,21 @@
+# = First example
+# This is the RBP API version of "Getting Started" example of Protovis introduction.
+# On this example we show you how can you build a bar chart using panel and bar marks.
+# A mark represents a set of graphical elements that share data and visual encodings. Although marks are simple by themselves, you can combine them in interesting ways to make rich, interactive visualizations
+$:.unshift(File.dirname(__FILE__)+"/../lib")
+require 'rubyvis'
+    
+vis = Rubyvis::Panel.new do 
+  width 150
+  height 150
+  bar do
+    data [1, 1.2, 1.7, 1.5, 0.7, 0.3]
+    width 20
+    height {|d| d * 80}
+    bottom(0)
+    left {index * 25}
+  end
+end
+
+vis.render
+puts vis.to_svg

data/examples/image.rb

@@ -16,5 +16,4 @@ dot=vis.add(pv.Image)
     .url(img_url)
     
 vis.render()
-#puts vis.children_inspect
 puts vis.to_svg

data/examples/line.rb

@@ -25,7 +25,6 @@ vis = pv.Panel.new()
   .right(10)
   .top(5)
 
-#/* The area with top line. */
 vis.add(pv.Line).
   data(data).
   line_width(5).

data/examples/line_interpolation.rb

@@ -0,0 +1,55 @@
+# = Line Interpolation
+# This example show the 7 types of interpolation available for lines.
+$:.unshift(File.dirname(__FILE__)+"/../lib")
+require 'rubyvis'
+
+data = pv.range(0, 10, 1).map {|x| 
+  OpenStruct.new({:x=> x, :y=> Math.sin(x) + 2+rand()*0.2})
+}
+
+p_w=200
+p_h=150
+#p data
+w = 20+p_w*2
+h = 20+p_h*4
+
+x = pv.Scale.linear(data, lambda {|d| d.x}).range(0, p_w-30)
+
+
+y = pv.Scale.linear(data, lambda {|d| d.y}).range(0, p_h-20);
+
+interpolations=["linear","step-before","step-after","polar","polar-reverse", "basis", "cardinal"]
+
+#/* The root panel. */
+vis = pv.Panel.new()
+  .width(w)
+  .height(h)
+  .bottom(20)
+  .left(20)
+  .right(10)
+  .top(5)
+
+interpolations.each_with_index do |inter,i|
+  n=i%2
+  m=(i/2).floor
+  panel=vis.add(Rubyvis::Panel).
+  left(n*(p_w+10)).
+  top(m*(p_h+10)).
+  width(p_w).
+  height(p_h)
+  panel.anchor('top').add(Rubyvis::Label).text(inter)
+  panel.add(Rubyvis::Line).data(data).
+  line_width(2).
+  left(lambda {|d| x.scale(d.x)}).
+  bottom(lambda {|d| y.scale(d.y)}).
+  interpolate(inter)
+  
+end
+  
+  
+     
+
+vis.render();
+
+
+puts vis.to_svg

data/lib/rubyvis.rb

@@ -22,12 +22,13 @@ require 'rubyvis/scene/svg_scene'
 require 'rubyvis/transform'
 
 
+
 module Rubyvis
   @document=nil
   # Rubyvis version
-  VERSION = '0.1.7' 
+  VERSION = '0.2.0' 
   # Protovis API on which current Rubyvis is based
-  API_VERSION='3.3'
+  PROTOVIS_API_VERSION='3.3'
   # You actually can do it! http://snipplr.com/view/2137/uses-for-infinity-in-ruby/
   Infinity=1.0 / 0 
   #
@@ -89,4 +90,3 @@ end
 def pv
   Rubyvis
 end
-

data/lib/rubyvis/color/color.rb

@@ -1,5 +1,29 @@
 module Rubyvis
-  
+  # Returns the Rubyvis::Color for the specified color format string. Colors
+  # may have an associated opacity, or alpha channel. 
+  # Color formats are specified by CSS Color Modular Level 3, 
+  # using either in RGB or HSL color space. For example:<ul>
+  #
+  # <li>#f00 // #rgb
+  # <li>#ff0000 // #rrggbb
+  # <li>rgb(255, 0, 0)
+  # <li>rgb(100%, 0%, 0%)
+  # <li>hsl(0, 100%, 50%)
+  # <li>rgba(0, 0, 255, 0.5)
+  # <li>hsla(120, 100%, 50%, 1)
+  # </ul>
+  #
+  # The SVG 1.0 color keywords names are also supported, such as "aliceblue"
+  # and "yellowgreen". The "transparent" keyword is supported for fully-
+  # transparent black.
+  #
+  # <p>If the <tt>format</tt> argument is already an instance of <tt>Color</tt>,
+  # the argument is returned with no further processing.
+  #
+  # * see <a href="http://www.w3.org/TR/SVG/types.html#ColorKeywords">SVG color
+  # keywords</a>
+  # * see <a href="http://www.w3.org/TR/css3-color/">CSS3 color module</a>
+  #/
   def self.color(format)
     return format.rgb if format.respond_to? :rgb
     if (format =~/([a-z]+)\((.*)\)/)
@@ -51,22 +75,53 @@ module Rubyvis
     # Otherwise, pass-through unsupported colors. */
     return Rubyvis::Color.new(format, 1);
   end
-  
+  # Constructs a new RGB color with the specified channel values.
   def self.rgb(r,g,b,a=1)
     Rubyvis::Color::Rgb.new(r,g,b,a)
   end
-
+  def self.hsl(h,s,l,a=1)
+    Rubyvis::Color::Hsl.new(h,s,l,a)
+  end
+  # Represents an abstract (possibly translucent) color. The color is
+  # divided into two parts: the <tt>color</tt> attribute, an opaque color format
+  # string, and the <tt>opacity</tt> attribute, a float in [0, 1]. The color
+  # space is dependent on the implementing class; all colors support the
+  # Color.rgb() method to convert to RGB color space for interpolation.
   class Color
-    attr_reader :color, :opacity
+    # An opaque color format string, such as "#f00".
+    attr_reader :color
+    # The opacity, a float in [0, 1].
+    attr_reader :opacity
+    
+    # Constructs a color with the specified color format string and opacity. This
+    # constructor should not be invoked directly; use Rubyvis.color instead.
     def initialize(color,opacity)
       @color=color
       @opacity=opacity
     end
-    def darker(*args)
-      self.rgb.darker(*args)
+    # Returns a new color that is a brighter version of this color. The behavior of
+    # this method may vary slightly depending on the underlying color space.
+    # Although brighter and darker are inverse operations, the results of a series
+    # of invocations of these two methods might be inconsistent because of rounding
+    # errors.
+    # * @param [k] {number} an optional scale factor; defaults to 1.
+    def brighter(k)
+      self.rgb.lighter(k)
     end
-
-    def self.names
+    
+    # Returns a new color that is a brighter version of this color. The behavior of
+    # this method may vary slightly depending on the underlying color space.
+    # Although brighter and darker are inverse operations, the results of a series
+    # of invocations of these two methods might be inconsistent because of rounding
+    # errors.
+    #
+    # * @param [k] {number} an optional scale factor; defaults to 1.
+    def darker(k)
+      self.rgb.darker(k)
+    end
+    
+    # Association between names and colors
+    def self.names # :nodoc:
       {
         :aliceblue=>"#f0f8ff",
         :antiquewhite=>"#faebd7",
@@ -220,10 +275,17 @@ module Rubyvis
     def self.transparent
       Rubyvis.rgb(0,0,0,0)
     end
-
-
+    # Represents a color in RGB space.
     class Rgb < Color
-      attr_reader :r, :b, :g, :a
+      # The red channel, an integer in [0, 255].
+      attr_reader :r
+      # The blue channel, an integer in [0, 255].
+      attr_reader :b
+      # The green channel, an integer in [0, 255].
+      attr_reader :g
+      # The alpha channel, a float in [0, 1].
+      attr_reader :a
+      # Constructs a new RGB color with the specified channel values.
       def initialize(r,g,b,a)
         @r=r
         @b=b
@@ -239,34 +301,129 @@ module Rubyvis
       def ==(v)
         self.class==v.class and @r==v.r and @b==v.b and @g=v.g and @a=v.a
       end
+      
+      # Constructs a new RGB color with the same green, blue and alpha channels
+      # as this color, with the specified red channel.
       def red(r1)
         Rubyvis.rgb(r1,g,b,a)
       end
+      # Constructs a new RGB color with the same red, blue and alpha channels
+      # as this color, with the specified green channel.
       def green(g1)
         Rubyvis.rgb(r,g1,b,a)
       end
+      # Constructs a new RGB color with the same red, green and alpha channels
+      # as this color, with the specified blue channel.
       def blue(b1)
         Rubyvis.rgb(r,g,b1,a)
       end
+      # Constructs a new RGB color with the same red, green and blue channels as this
+      # color, with the specified alpha channel.
+      
       def alpha(a1)
         Rubyvis.rgb(r,g,b,a1)
       end
-      
+      # Returns the RGB color equivalent to this color. This method is abstract and  must be implemented by subclasses.
       def rgb
         self
       end
-      def darker(*arguments)
-        k,dummy=arguments
-        k = 0.7 ** ( arguments.size>0 ? k : 1)
-        return Rubyvis.rgb(
-          [0, (k * self.r).floor].max,
-          [0, (k * self.g).floor].max,
-          [0, (k * self.b).floor].max,
-          self.a)
+      # Returns a new color that is a brighter version of this color. This method
+      # applies an arbitrary scale factor to each of the three RGB components of this
+      # color to create a brighter version of this color. Although brighter and
+      # darker are inverse operations, the results of a series of invocations of
+      # these two methods might be inconsistent because of rounding errors.
+      def lighter(k=1)
+          k = 0.7**k
+          i = 30
+          r=self.r
+          g=self.g
+          b=self.b
+          return Rubyvis.rgb(i, i, i, a) if (!r and !g and !b) 
+          r = i if (r and (r < i)) 
+          g = i if (g and (g < i)) 
+          b = i if (b and (b < i))
+          Rubyvis.rgb(
+            [255, (r/k).floor].min,
+            [255, (g/k).floor].min,
+            [255, (b/k).floor].min,
+            a)
+      end
+      # Returns a new color that is a darker version of this color. This method
+      # applies an arbitrary scale factor to each of the three RGB components of this
+      # color to create a darker version of this color. Although brighter and darker
+      # are inverse operations, the results of a series of invocations of these two
+      # methods might be inconsistent because of rounding errors.
+      def darker(k=1)
+        k = 0.7 ** k
+        Rubyvis.rgb(
+          [0, (k * r).floor].max,
+          [0, (k * g).floor].max,
+          [0, (k * b).floor].max,
+          a)
       end
+      
       def to_s
         @color
       end
     end
+    # Represents a color in HSL space.
+    class Hsl < Color
+      
+      # The hue, an integer in [0, 360].
+      attr_accessor :h
+      # The saturation, a float in [0, 1].
+      attr_accessor :s
+      # The lightness, a float in [0, 1].
+      attr_accessor :l
+      # The opacity, a float in [0, 1].
+      attr_accessor :a
+      
+      def initialize(h,s,l,a)
+        c="hsl(#{h},#{s * 100}%,#{l * 100}%)"
+        super(c,a)
+        @h=h
+        @s=s
+        @l=l
+        @a=a
+      end
+      
+      # Returns the RGB color equivalent to this HSL color.
+      def rgb
+        h = self.h
+        s = self.s
+        l = self.l
+        
+        # Some simple corrections for h, s and l. */
+        h = h % 360
+        h += 360 if (h < 0)
+        s = [0, [s, 1].min].max
+        l = [0, [l, 1].min].max
+        
+        # From FvD 13.37, CSS Color Module Level 3 
+        m2 = (l <= 0.5) ? (l * (1 + s)) : (l + s - l * s)
+        m1 = 2 * l - m2
+        v=lambda {|h1|
+          if (h1 > 360)
+            h1 -= 360;
+          elsif (h1 < 0)
+             h1 += 360
+          end
+          
+          
+          return m1 + (m2 - m1) * h1 / 60 if (h1 < 60)
+          return m2 if (h1 < 180) 
+          return m1 + (m2 - m1) * (240 - h1) / 60 if (h1 < 240)
+          return m1
+        }
+        vv=lambda {|h1|
+          (v(h1) * 255).round
+        }
+        
+        Rubyvis.rgb(vv.call(h + 120), vv.call(h), vv.call(h - 120), a)
+      end
+    end
+
+    
+    
   end
 end