prawn-graph 1.0.0.pre1 → 1.0.1

data/lib/prawn/graph/chart_components/canvas.rb

@@ -0,0 +1,128 @@
+module Prawn
+  module Graph
+    module ChartComponents
+      # A Prawn::Graph::Canvas represents the area on which a graph will be drawn. Think of it
+      # as the container in which your chart / graph will be sized to fit within. 
+      #
+      class Canvas
+        attr_reader :layout, :series, :prawn, :theme, :options
+
+        # @param series [Array[Prawn::Graph::Series]]
+        # @param prawn [Prawn::Document]
+        # @param options [Hash]
+        # @return [Prawn::Graph::Canvas] a canvas ready to be drawn on the provided +prawn+ document.
+        #
+        def initialize(series, prawn, options = {}, &block)
+          @series   = series
+          verify_series_are_ok!
+          @options  =  {xaxis_labels: []}.merge(options.merge({ series_count: series.size }))
+          @prawn    = prawn
+          @theme    = Prawn::Graph::Theme::Default
+          @layout   = Prawn::Graph::Calculations::LayoutCalculator.new([prawn.bounds.width, prawn.bounds.height], @options, @theme).calculate
+
+          yield self if block_given?
+        end
+
+        # Fires off the actual drawing of the chart on the provided canvas.
+        # @return [nil]
+        #
+        def draw
+          prawn.bounding_box(position, :width => layout.canvas_width, :height => layout.canvas_height, padding: 0) do
+            prawn.save_graphics_state do         
+              apply_theme! 
+              render_title_area!
+              render_series_keys!
+              render_graph_area!
+            end
+          end
+        end
+
+        # The coordinates which the canvas will be drawn at
+        # @return [Array] [X-Coord, Y-Coord]
+        #
+        def position
+          @options[:at] || [0,0]
+        end
+
+        private
+
+        def apply_theme!
+          prawn.fill_color    @theme.default
+          prawn.stroke_color  @theme.default
+          prawn.font_size     @theme.font_sizes.default
+        end
+
+        def plot_series!
+          bar_charts    = series.collect{ |s| s if s.type == :bar }.compact
+          others        = series - bar_charts
+
+          BarChartRenderer.new(bar_charts, self, theme.series[0..(bar_charts.size - 1)]).render unless bar_charts.empty?
+
+          i = bar_charts.size
+          others.each do |series|
+            LineChartRenderer.new(series, self, theme.series[i]).render
+            i+=1
+          end
+        end
+
+        def render_graph_area!
+          if layout.graph_area.renderable?
+            prawn.bounding_box layout.graph_area.point, width: layout.graph_area.width, height: layout.graph_area.height do
+              plot_series!
+            end
+          end
+        end
+
+        def render_title_area!
+          if layout.title_area.renderable?
+            prawn.text_box "<color rgb=\"#{@theme.title}\">#{@options[:title]}</color>", at: layout.title_area.point, inline_format: true, 
+            valign: :center, align: :center, size: @theme.font_sizes.main_title, width: layout.title_area.width, height: layout.title_area.height
+          end
+        end
+
+        def render_series_keys!
+          if layout.series_key_area.renderable?
+            prawn.bounding_box layout.series_key_area.point, width: layout.series_key_area.width, height: layout.series_key_area.height do
+              series.each_with_index do |series, i|
+                series_offset = i + 1
+
+                prawn.save_graphics_state do
+                  prawn.stroke_color = theme.axes
+                  prawn.line_width = 0.5
+                  prawn.fill_color = theme.series[i]
+
+                  
+                  series_offset = series_offset * theme.font_sizes.series_key
+
+                  title = series.title || "Series #{series_offset}"
+                  top_position = (prawn.bounds.top - (series_offset * 3))
+
+
+                  prawn.fill_and_stroke_rectangle([ theme.font_sizes.series_key, top_position ], theme.font_sizes.series_key, theme.font_sizes.series_key)
+                  
+                  prawn.fill_color = theme.axes
+                  prawn.text_box title, at: [ (theme.font_sizes.series_key * 3), top_position ], size: theme.font_sizes.series_key, height: (series_offset * 2)
+                end
+              end
+            end
+          end
+        end
+
+        # Verifies that we provide an array-like object of Prawn::Graph::Series instances to
+        # the Canvas, for later rendering.
+        #
+        def verify_series_are_ok!
+          if @series.respond_to?(:each) && @series.respond_to?(:collect)
+            classes = @series.collect{ |c| c.is_a?(Prawn::Graph::Series) }.uniq
+            if classes.size > 1 || classes[0] != true
+              raise RuntimeError.new("All of the items provided must be instances of Prawn::Graph::Series")
+            end
+          else
+            raise RuntimeError.new("Series provided must be an Array (or Array-like) object.")
+          end
+        end
+        
+      end
+    end
+  end
+end

data/lib/prawn/graph/chart_components/line_chart_renderer.rb

@@ -0,0 +1,92 @@
+module Prawn
+  module Graph
+    module ChartComponents
+
+      # The Prawn::Graph::ChartComponents::SeriesRenderer is used to plot indivdual Prawn::Graph::Series on
+      # a Prawn::Graph::ChartComponents::Canvas and its associated Prawn::Document.
+      #
+      class LineChartRenderer < SeriesRenderer
+
+        def render
+          render_line_chart
+        end
+
+        private
+
+        def mark_minimum_value(min_marked, value, x, y)
+          if @series.mark_minimum? && min_marked == false && value != 0 && value == @series.min 
+            draw_marker_point(@canvas.theme.min, x, y)
+            min_marked = true
+          end
+          min_marked
+        end
+
+        def mark_maximum_value(max_marked, value, x, y)
+          if @series.mark_maximum? && max_marked == false && value != 0 && value == @series.max
+            draw_marker_point(@canvas.theme.max, x, y)
+            max_marked = true
+          end
+          max_marked
+        end
+
+        def mark_average_line
+          if @series.mark_average?
+            average_y_coordinate = (point_height_percentage(@series.avg) * @plot_area_height) - 5
+            prawn.line_width = 1
+            prawn.stroke_color = @color
+            prawn.dash(2)
+            prawn.stroke_line([0, average_y_coordinate], [ @plot_area_width, average_y_coordinate ])
+            prawn.undash
+          end
+        end
+
+        def render_line_chart
+          prawn.bounding_box [@graph_area.point[0] + 5, @graph_area.point[1] - 20], width: @plot_area_width, height: @plot_area_height do
+            j = 2
+            prawn.save_graphics_state do  
+              max_marked = false
+              min_marked = false
+
+              @series.values.each_with_index do |v, i|
+                next if i == 0
+
+                width_per_point = (@plot_area_width / @series.size).round(2).to_f
+                spacing = width_per_point
+
+                prawn.line_width = 2
+                prawn.fill_color    = @color
+                prawn.stroke_color  = @color
+
+                previous_value = @series.values[i - 1]
+                this_value = v
+
+                previous_y  = (point_height_percentage(previous_value) * @plot_area_height) - 5
+                this_y      = (point_height_percentage(this_value) * @plot_area_height) - 5
+
+                previous_x_offset = ((spacing * (j - 1)) - spacing) + (spacing / 2.0)
+                this_x_offset    = ((spacing * j) - spacing) + (spacing / 2.0)
+
+                unless previous_value.zero? || this_value.zero?
+                  prawn.stroke_line([previous_x_offset, previous_y], [ this_x_offset, this_y ])  
+                  prawn.fill_color = @canvas.theme.markers
+                  prawn.fill_ellipse([ ( previous_x_offset), previous_y ], 1) 
+                  prawn.fill_ellipse([ ( this_x_offset), this_y ], 1)
+                end
+
+                min_marked = mark_minimum_value(min_marked, previous_value, previous_x_offset, previous_y)
+                min_marked = mark_minimum_value(min_marked, this_value, this_x_offset, this_y)
+                max_marked = mark_maximum_value(max_marked, previous_value, previous_x_offset, previous_y)
+                max_marked = mark_maximum_value(max_marked, this_value, this_x_offset, this_y)
+
+                j += 1
+              end
+              
+              mark_average_line
+            end
+            render_axes
+          end
+        end
+      end
+    end
+  end
+end

data/lib/prawn/graph/chart_components/series_renderer.rb

@@ -0,0 +1,120 @@
+module Prawn
+  module Graph
+    module ChartComponents
+
+      # The Prawn::Graph::ChartComponents::SeriesRenderer is used to plot indivdual Prawn::Graph::Series on
+      # a Prawn::Graph::ChartComponents::Canvas and its associated Prawn::Document.
+      #
+      class SeriesRenderer
+        # @param series [Prawn::Graph::Series]
+        # @param canvas [Prawn::Graph::ChartComponents::Canvas]
+        #
+        def initialize(series, canvas, color = '000000')
+          if series.is_a?(Array)
+            raise ArgumentError.new("series must be a Prawn::Graph::Series") unless series.first.is_a?(Prawn::Graph::Series)
+          else
+            raise ArgumentError.new("series must be a Prawn::Graph::Series") unless series.is_a?(Prawn::Graph::Series)
+          end
+          raise ArgumentError.new("canvas must be a Prawn::Graph::ChartComponents::Canvas") unless canvas.is_a?(Prawn::Graph::ChartComponents::Canvas)
+
+          @series = series
+          @canvas = canvas
+          @prawn = canvas.prawn
+          @color = color
+
+          @graph_area = @canvas.layout.graph_area
+
+          @plot_area_width  = @graph_area.width - 25
+          @plot_area_height = @graph_area.height - 20
+        end
+
+        def render
+          render_chart
+        end
+
+        private
+
+        def render_chart
+          raise "Subclass Me"
+        end
+
+        def render_axes
+          prawn.stroke_color  = @canvas.theme.axes
+          prawn.fill_color  = @canvas.theme.axes
+          prawn.stroke_horizontal_line(0, @plot_area_width, at: 0) 
+          prawn.stroke_vertical_line(0, @plot_area_height, at: 0) 
+          prawn.fill_and_stroke_ellipse [ 0,0], 1
+
+          add_y_axis_label(max)
+          add_y_axis_label(min)
+          add_y_axis_label(avg)
+          add_y_axis_label(mid)
+
+          add_x_axis_labels
+        end
+
+        def add_x_axis_labels 
+          return if @canvas.options[:xaxis_labels].size.zero?
+          width_of_each_label = (@plot_area_width / @canvas.options[:xaxis_labels].size) - 1
+          @canvas.options[:xaxis_labels].each_with_index do |label, i|
+            offset    = i + 1
+            position  = ((offset * width_of_each_label) - width_of_each_label) + 1
+            
+            prawn.text_box  label, at: [ position, -2 ], width: width_of_each_label, height: 6, valign: :center, align: :center,
+                            overflow: :shrink_to_fit
+          end
+        end
+
+        def add_y_axis_label(value)
+          unless value.zero?
+            y = (point_height_percentage(value) * @plot_area_height)
+            prawn.text_box "#{max}", at: [-14, y], height: 5, overflow: :shrink_to_fit, width: 12, valign: :bottom, align: :right 
+          end
+        end
+
+        # Calculates the relative height of a given point based on the maximum value present in
+        # the series.
+        #
+        def point_height_percentage(value)
+          ((BigDecimal(value, 10)/BigDecimal(@canvas.series.collect(&:max).max, 10)) * BigDecimal(1)).round(2) rescue 0
+        end
+
+        def prawn
+          @prawn
+        end
+
+        def max 
+          @series.max || 0
+        end
+
+        def min
+          @series.min || 0
+        end
+
+        def avg
+          @series.avg || 0
+        end
+
+        def mid
+          (min + max) / 2 rescue 0
+        end
+
+        def draw_marker_point(color, x_position, y_position)
+          prawn.save_graphics_state do
+            prawn.fill_color = color
+            prawn.stroke_color = color
+            prawn.line_width = 1
+
+            prawn.dash(2)
+            prawn.stroke_line([x_position, 0], [x_position, y_position])
+            prawn.undash
+
+            prawn.fill_ellipse([x_position, y_position ], 2)
+            return true
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/prawn/graph/extension.rb

@@ -1,32 +1,25 @@
 module Prawn
   module Graph
     module Extension
-
-      # Draws a bar graph into the PDF
-      #
-      # Example:
-      #
-      #  bar_graph [ ["A", 1], ["B", 2], ["C", 3] ], at: [10,10]
-      #
-      def bar_graph(data, options = {}, &block)
-        graph = Prawn::Graph::Charts::Bar.new(data, self, options, &block)
-        graph.draw
-        {warnings: [], width: graph.prawn.bounds.width, height: graph.prawn.bounds.height}
-      end
-      alias bar_chart bar_graph
-
-      # Draws a line graph into the PDF
-      #
-      # Example:
+      
+      # Plots one or more Prawn::Graph::Series on a chart. Expects an array-like object of
+      # Prawn::Graph::Series objects and some options for positioning the sizing the
+      # rendered graph
       #
-      #  line_graph [ ["A", 1], ["B", 2], ["C", 3] ], at: [10,10]
+      # @param series [Array] of Prawn::Graph::Series objects
+      # @param options [Hash] of options, which can be:
+      #    `:width`       - The overall width of the graph to be drawn. `<Integer>`
+      #    `:height`      - The overall height of the graph to be drawn. `<Integer>`
+      #    `:at`          - The point from where the graph will be drawn. `[<Integer>x, <Integer>y]`
+      #    `:title`       - The title for this chart. Must be a string. `<String>`
+      #    `:series_key`  - Should we render the key to series in this chart? `<Boolean>`
       #
-      def line_graph(data, options = {}, &block)
-        graph = Prawn::Graph::Charts::Line.new(data, self, options, &block)
-        graph.draw
-        {warnings: [], width: graph.prawn.bounds.width, height: graph.prawn.bounds.height}
+      def graph(series, options = {}, &block)
+        canvas = Prawn::Graph::ChartComponents::Canvas.new(series, self, options, &block)
+        canvas.draw
+        {warnings: [], width: self.bounds.width, height: self.bounds.height}
       end
-      alias line_chart line_graph
+      alias chart graph
 
     end
   end

data/lib/prawn/graph/series.rb

@@ -5,33 +5,82 @@ module Prawn
     # on a chart.
     #
     class Series
-      attr_accessor :values, :title, :type
-      VALID_TYPES = [ :bar, :line ]
+      attr_accessor :values, :options
 
-      def initialize(values = [], title = nil, type = :bar)
+      DEFAULT_OPTIONS = {
+        title:            nil,
+        type:             :bar,
+        mark_average:     false,
+        mark_minimum:     false,
+        mark_maximum:     false,
+      }
+
+      def initialize(values = [], options = {})
         @values   = values
-        @title    = title
-        @type     = type
+        @options  = OpenStruct.new(DEFAULT_OPTIONS.merge(options))
+      end
+
+      # @return [String] The value of +options.title+.
+      #
+      def title
+        options.title
       end
 
+      # @return [Symbol] The value of +options.type+.
+      #
+      def type
+        options.type
+      end
+
+      # @param value [Object] a value to be added to the series. Must be of the same kind as other +values+.
+      # @return [Array] The modified +values+ object.
+      #
       def <<(value)
         @values << value
       end
 
+      # @return [Numeric] The smallest value stored in the +values+ of this Series.
+      #
       def min
-        @values.min || 0
+        if values.empty?
+          0
+        else
+          values.sort.collect{ |x| x unless x.zero? }.compact.first
+        end
       end
 
+      # @return [Numeric] The largest value stored in the +values+ of this Series.
+      #
       def max
         @values.max || 0
       end
 
+      # @return [Numeric] The average value stored in the +values+ of this Series.
+      #
+      def avg
+        if size > 0
+          @values.inject(:+) / size
+        else
+          0
+        end
+      end
+
+      # @return [Numeric] The size of the +values+ stored in this Series.
+      #
       def size
         @values.size
       end
 
-      def to_a
-        [title, @values].compact.flatten
+      def mark_average?
+        options.mark_average == true
+      end
+
+      def mark_minimum?
+        options.mark_minimum == true
+      end
+
+      def mark_maximum?
+        options.mark_maximum == true
       end
     end
   end