minichart 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0574d786b6188b0f2ed6977760ad85bbd2f2487a6d010de8e7be7f50127d51a3
-  data.tar.gz: 5b138c614099b58ff7365a38246641a586417c0fdccb6e1e2677494603f01eb8
+  metadata.gz: 6109cfc57cb909c2ba0a9df4e184bc4319220399b774ff2098b728bf4a41f57e
+  data.tar.gz: 32cd8ff3c3260d08f81106c3ac74037e36990d4601eb8ff7e40c8840d44b3ca3
 SHA512:
-  metadata.gz: 49471660072528ec03c129fb0b549b88f3a2a9f3f5286b969579402ddfb9233c7eb617f1fa64821273a43a88042a724432324bad8f7f0d0143d5825778f4d5fb
-  data.tar.gz: 23d208d26569d432380615d0e5e479a92dfa61492841cbd9c9211dd8c94c036f5be467f5710de49a66b58cffa92a2c3066f9a4a2bf6933fea72ba69c59b9e811
+  metadata.gz: 63e01d19bd4539ccf1283a98bee8f941a7e270ee0f1a2956aed20ecbab21661e7923420588c28f0aa90027cfc6fadc88f5f90b5776ff8dfa3523c9faf85c03ba
+  data.tar.gz: 1861ffff3d852e85fbf9b8c334d091f6dd40ce823086ae4215edb95c96f20a5f9e79e4da5caaf51b35956a8da92ca9de054ee35aae67c84884c02ad5f59af628

data/README.md

@@ -1,16 +1,36 @@
-Minichart - SVG Chart Generator
-==================================================
+# Minichart - SVG Chart Generator
 
 ---
 
 Create SVG mini charts with Ruby
 
+![demo](examples/multiple.svg)
+
 ---
 
-Install
---------------------------------------------------
+* [Install](#install)
+* [Usage](#usage)
+* [Chart Types](#chart-types)
+  * [Line Chart](#line-chart)
+  * [Bar Chart](#bar-chart)
+  * [Area Chart](#area-chart)
+  * [Horizontal Bar Meter](#horizontal-bar-meter)
+  * [Vertical Bar Meter](#vertical-bar-meter)
+* [Configuration](#configuration)
+  * [Class-level default options](#class-level-default-options)
+  * [Instance initialization options](#instance-initialization-options)
+  * [Instance-level options](#instance-level-options)
+* [Options Reference](#options-reference)
+  * [Basic Options](#basic-options)
+  * [Meter Options](#meter-options)
+* [Examples](#examples)
 
-```
+
+---
+
+## Install
+
+```shell
 $ gem install minichart
 ```
 
@@ -20,20 +40,230 @@ Or with bundler:
 gem 'minichart'
 ```
 
-Example
---------------------------------------------------
+## Usage
+
+Require and optionally include the library:
 
 ```ruby
 require 'minichart'
 include Minichart
+```
+
+Initialize a chart with data, and optional options:
+
+```ruby
+data = [3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5, 9]
+chart = AreaChart.new data, color: 'blue'
+```
+
+Get the full SVG output by calling `#render`:
+
+```ruby
+puts chart.render
+#=> <?xml version="1.0" standalone="no"?>
+#   <svg> ... </svg>
+```
+
+Save it to file, by calling `#save`:
+
+```ruby
+chart.save "my-chart.svg"
+```
+
+Get its inner SVG string by calling `#to_s`:
+
+```ruby
+puts chart.to_s
+#=> <polyline fill="blue" stroke="blue" stroke-width="2" points="..."/>
+```
+
+
+The objects returned from all the mini chart classes are [Victor::SVG][2] objects, so they support all methods supported by it as well.
+
+## Chart Types
+
+### Line Chart
+
+<img src='examples/line_chart.svg' align='right' width=300>
+
+```ruby
+LineChart.new data, height: 50, background: '#eee',
+  aspect_ratio: 5, color: 'green'
+```
+
+### Bar Chart
+
+<img src='examples/bar_chart.svg' align='right' width=300>
+
+```ruby
+BarChart.new data, height: 50, background: '#eee',
+  aspect_ratio: 5, color: 'green'
+```
+
+### Area Chart
+
+<img src='examples/area_chart.svg' align='right' width=300>
+
+```ruby
+AreaChart.new data, height: 50, background: '#eee',
+  aspect_ratio: 5, color: 'green'
+```
+
+### Horizontal Bar Meter
+
+<img src='examples/multiple_horizontal_bars.svg' align='right'>
+
+```ruby
+positive = HorizontalBarMeter.new 70,
+  height: 20, width: 250, background: '#9f9', color: 'green'
+
+negative = HorizontalBarMeter.new -80,
+  height: 20, width: 250, background: '#f99', color: 'red'
+
+dual = HorizontalBarMeter.new 80,
+  height: 20, width: 250, background: '#99f', color: 'blue',
+  mode: :dual, zero_line: true
+```
+
+Meter charts support [additional options](#meter-options).
+
+### Vertical Bar Meter
+
+<img src='examples/multiple_vertical_bars.svg' align='right'>
+
+```ruby
+positive = VerticalBarMeter.new 70,
+  width: 20, height: 250, background: '#9f9', color: 'green'
+
+negative = VerticalBarMeter.new -80,
+  width: 20, height: 250, background: '#f99', color: 'red'
+
+dual = VerticalBarMeter.new 80,
+  width: 20, height: 250, background: '#99f', color: 'blue',
+  mode: :dual, zero_line: true
+```
 
-plot = LineChart.new
-plot.aspect_ratio = 2
-plot.data = [10, 30, 20, 40, 30]
-plot.save 'line'
+Meter charts support [additional options](#meter-options).
+
+
+## Configuration
+
+Chart options can be set in one of three ways.
+
+### Class-level default options
+
+See or set default options for any chart class by calling its `::options` method:
+
+```ruby
+# See all options
+p AreaChart.options
+#=> {:background=>"white", :height=>100, :width=>300, :stroke=>2, :style=>{}, :color=>"#66f"}
+
+# Set a single default option
+AreaChart.options[:color] = '#333'
+
+# Set multiple options at once
+AreaChart.options background: 'black', color: 'green'
 ```
 
+### Instance initialization options
+
+Set options by providing a hash as the second argument on initialization:
+
+```ruby
+chart = AreaChart.new data, height: 120, width: 500
+```
+
+### Instance-level options
+
+After initialization, you can still update individual options:
+
+```ruby
+chart = AreaChart.new data
+chart.options[:background] = 'yellow'
+```
+
+## Options Reference
+
+### Basic Options
+
+#### background
+
+Chart background color.
+
+#### color
+
+Chart color.
+
+#### height
+
+Chart height in pixels.
+
+#### width
+
+Chart width in pixels.
+
+#### stroke
+
+Line stroke width. This has a different effect in different chart types.
+
+#### style
+
+CSS Style hash to apply to the entire SVG.
+
+
+### Meter Options
+
+Meter charts support these options in additon to the basic options:
+
+#### mode
+
+Display mode. Can be `:positive`, `:negative`, `:dual` or `:auto` (default).
+
+The `:auto` mode will switch between `:positive` and `:negative` based on the
+value.
+
+#### max
+
+The absolute maximum value. This number should be positive even for negative
+charts.
+
+#### notches
+
+An array of one or more levels to place a notch marker. Use positive values
+only.
+
+#### notch_thickness
+
+Thickness of the notch markers.
+
+#### notch_color
+
+Color of the notch markers.
+
+#### clipping_indicator
+
+If true, show a marker when the value exceeds the range.
+
+#### clipping_indicator_thickness
+
+Thickness of the clipping indicator.
+
+#### clipping_indicator_color
+
+Color of the clipping indicator.
+
+## Examples
+
 See more examples (code and SVG output) in the [examples folder][1].
 
+## Contributing / Support
+
+If you experience any issue, have a question or a suggestion, or if you wish
+to contribute, feel free to [open an issue][issues].
+
+---
 
 [1]: https://github.com/DannyBen/minichart/tree/master/examples#examples
+[2]: https://github.com/DannyBen/victor
+[issues]: https://github.com/DannyBen/minichart/issues

data/lib/minichart.rb

@@ -1,4 +1,12 @@
 require 'victor'
-require 'minichart/chart'
-require 'minichart/line_chart'
-require 'minichart/bar_chart'
+require 'minichart/id_generator'
+require 'minichart/base'
+require 'minichart/charts/chart'
+require 'minichart/charts/line_chart'
+require 'minichart/charts/bar_chart'
+require 'minichart/charts/area_chart'
+require 'minichart/meters/meter'
+require 'minichart/meters/vertical_bar_meter'
+require 'minichart/meters/horizontal_bar_meter'
+
+require 'byebug' if ENV['BYEBUG']

data/lib/minichart/base.rb

@@ -0,0 +1,63 @@
+module Minichart
+  # Base class for all Minichart classes
+  class Base < Victor::SVGBase
+    attr_reader :data, :options
+
+    class << self
+      def master_defaults
+        {
+          background: 'white',
+          height: 100,
+          width: 300,
+          stroke: 2,
+          style: {},
+          color: '#66f'
+        }
+      end
+
+      # For subclasses to define
+      def defaults
+        {}
+      end
+
+      def options(update_hash = nil)
+        @options ||= master_defaults.merge defaults
+        @options.merge! update_hash if update_hash
+        @options
+      end
+    end
+
+    def initialize(data, user_options = {})
+      @data = data
+      @options = self.class.options.merge user_options
+
+      super viewBox: viewbox, style: options[:style]
+      element :rect, x: 0, y: 0,
+        width: options[:width], height: options[:height],
+        fill: options[:background], stroke_width: 0
+
+      clip_path_id = IDGenerator.next
+      setup_clip_path clip_path_id
+
+      element :g, clip_path: "url(##{clip_path_id})" do
+        build
+      end      
+    end
+
+    def setup_clip_path(id)
+      element :defs do
+        element :clipPath, id: id do
+          element :rect, width: options[:width], height: options[:height]
+        end
+      end
+    end
+
+    def viewbox
+      "0 0 #{options[:width]} #{options[:height]}"
+    end
+
+    def build
+      raise NotImplementedError, "#build is not implemented"
+    end
+  end
+end

data/lib/minichart/charts/area_chart.rb

@@ -0,0 +1,27 @@
+module Minichart
+  class AreaChart < Chart
+    def build
+      element :polyline, fill: options[:color],
+        stroke: options[:color],
+        stroke_width: options[:stroke],
+        stroke_linejoin: :round,
+        points: points
+    end
+
+  protected
+
+    def points
+      result = ["0,#{options[:height]}"]
+
+      inverted_points.each do |point|
+        x = options[:width] *point[0]
+        y = options[:height] * point[1]
+        result << "#{x},#{y}"
+      end
+
+      result << "#{options[:width]},#{options[:height]}"
+
+      result
+    end
+  end
+end

data/lib/minichart/charts/bar_chart.rb

@@ -0,0 +1,33 @@
+module Minichart
+  class BarChart < Chart
+    def build
+      opts  = { x_point_count: data.size }
+
+      inverted_points(opts).each do |x, y|
+        element :rect, bar_options(x, y)
+      end
+    end
+
+  protected
+
+    def bar_width
+      @bar_width ||= options[:width] / data.size
+    end
+
+    def bar_options(x, y)
+      y = y * options[:height]
+      bar_height = options[:height] - y
+      { 
+        x: x * options[:width], 
+        y: y, 
+        width: bar_width,
+        height: bar_height,
+        style: {
+          fill: options[:color],
+          stroke_width: options[:stroke],
+          stroke: options[:background]
+        }
+      }
+    end
+  end
+end

data/lib/minichart/charts/chart.rb

@@ -0,0 +1,28 @@
+module Minichart
+  # Base class for charts with data series
+  class Chart < Base
+  
+  protected
+
+    def inverted_points(opts={})
+      normalized_points(opts).map { |point| [point[0], 1-point[1]] }
+    end
+
+    def normalized_points(opts={})
+      x_point_count = opts[:x_point_count] || data.count-1
+
+      range   = (data.max - data.min).to_f
+      x_width = 1 / (x_point_count).to_f
+      result  = []
+
+      data.each_with_index do |y, index|
+        x = index*x_width
+        y = (y - data.min) / range
+        result << [x,y]
+      end
+
+      result
+    end
+
+  end
+end

data/lib/minichart/charts/line_chart.rb

@@ -0,0 +1,23 @@
+module Minichart
+  class LineChart < Chart
+    def build
+      element :polyline, fill: :none,
+        stroke: options[:color],
+        stroke_width: options[:stroke],
+        stroke_linejoin: :round,
+        points: points
+    end
+
+  protected
+
+    def points
+      result = []
+      inverted_points.each do |point|
+        x = options[:width] * point[0]
+        y = options[:height] * point[1]
+        result << "#{x},#{y}"
+      end
+      result
+    end
+  end
+end

data/lib/minichart/id_generator.rb

@@ -0,0 +1,14 @@
+module Minichart
+  module IDGenerator
+    class << self
+      def next
+        @id ||= 0
+        "minichart-#{@id += 1}"
+      end
+
+      def reset
+        @id = 0
+      end
+    end
+  end
+end

data/lib/minichart/meters/horizontal_bar_meter.rb

@@ -0,0 +1,80 @@
+module Minichart
+  class HorizontalBarMeter < Meter
+    class << self
+      def defaults
+        meter_defaults.merge width: 300, height: 50
+      end
+    end
+
+    def build
+      draw_bar
+      draw_notches if options[:notches]
+      draw_clipping_indicator if options[:clipping_indicator] and clipping?
+    end
+
+  protected
+
+    def draw_bar
+      x1 = x_for 0
+      x2 = x_for clamped_value
+      x = [x1, x2].min
+
+      element :rect, x: x, y: 0, height: options[:height],
+        width: bar_width, style: style
+    end
+
+    def draw_notches
+      options[:notches].each do |notch|
+        draw_notch notch
+        draw_notch -notch if mode == :dual and notch != 0
+      end
+    end
+
+    def draw_notch(notch)
+      draw_vertical_line notch, stroke: options[:notch_thickness],
+        color: options[:notch_color]
+    end
+
+    def draw_clipping_indicator
+      draw_vertical_line clamped_value,
+        stroke: options[:clipping_indicator_thickness],
+        color: options[:clipping_indicator_color]
+    end
+
+    def draw_vertical_line(target_value, color:, stroke:)
+      x = x_for target_value
+
+      element :line, x1: x, x2: x, y1: 0, y2: options[:height],
+        stroke: color, stroke_width: stroke
+    end
+
+    def width_factor
+      options[:width] / options[:max].to_f
+    end
+
+    def half_width
+      options[:width] * 0.5
+    end
+
+    def bar_width
+      if mode == :dual
+        clamped_value.abs * width_factor * 0.5
+      else
+        clamped_value.abs * width_factor
+      end
+    end
+
+    def x_for(target_value)
+      result = target_value.abs / options[:max].to_f * options[:width]
+
+      case mode
+      when :positive
+        result
+      when :negative
+        options[:width] - result
+      when :dual
+        target_value / options[:max].to_f * half_width + half_width
+      end
+    end
+  end
+end

data/lib/minichart/meters/meter.rb

@@ -0,0 +1,65 @@
+module Minichart
+  # Base class for charts with a single value
+  class Meter < Base
+
+    class << self
+      def meter_defaults
+        @meter_defaults ||= {
+          height: 50,
+          max: 100,
+          notches: [],
+          notch_thickness: 10,
+          notch_color: 'black',
+          clipping_indicator: false,
+          clipping_indicator_thickness: 20,
+          clipping_indicator_color: 'yellow',
+        }
+      end
+    end
+
+
+  protected 
+
+    def value
+      data
+    end
+
+    def clipping?
+      value > options[:max] || value < -options[:max]
+    end
+
+    def mode
+      @mode ||= mode!
+    end
+
+    def mode!
+      options[:mode] ||= :auto
+
+      if options[:mode] == :auto
+        value >= 0 ? :positive : :negative
+      else
+        options[:mode].to_sym
+      end
+    end
+
+    def clamped_value
+      case mode
+      when :positive
+        value.clamp 0, options[:max]
+      when :negative
+        value.clamp -options[:max], 0
+      when :dual
+        value.clamp -options[:max], options[:max]
+      end
+    end
+
+    def style
+      {
+        fill: options[:color],
+        stroke_width: options[:stroke],
+        stroke: options[:background]
+      }
+    end
+
+  end
+end

data/lib/minichart/meters/vertical_bar_meter.rb

@@ -0,0 +1,80 @@
+module Minichart
+  class VerticalBarMeter < Meter
+    class << self
+      def defaults
+        meter_defaults.merge width: 50, height: 300
+      end
+    end
+    
+    def build
+      draw_bar
+      draw_notches if options[:notches]
+      draw_clipping_indicator if options[:clipping_indicator] and clipping?
+    end
+
+  protected
+
+    def draw_bar
+      y1 = y_for 0
+      y2 = y_for clamped_value
+      y = [y1, y2].min
+
+      element :rect, x: 0, y: y, height: bar_height,
+        width: options[:width], style: style
+    end
+
+    def draw_notches
+      options[:notches].each do |notch|
+        draw_notch notch
+        draw_notch -notch if mode == :dual and notch != 0
+      end
+    end
+
+    def draw_notch(notch)
+      draw_horizontal_line notch, stroke: options[:notch_thickness],
+        color: options[:notch_color]
+    end
+
+    def draw_clipping_indicator
+      draw_horizontal_line clamped_value,
+        stroke: options[:clipping_indicator_thickness],
+        color: options[:clipping_indicator_color]
+    end
+
+    def draw_horizontal_line(target_value, color:, stroke:)
+      y = y_for target_value
+
+      element :line, x1: 0, x2: options[:width], y1: y, y2: y,
+        stroke: color, stroke_width: stroke
+    end
+
+    def height_factor
+      options[:height] / options[:max].to_f
+    end
+
+    def half_height
+      options[:height] * 0.5
+    end
+
+    def bar_height
+      if mode == :dual
+        clamped_value.abs * height_factor * 0.5
+      else
+        clamped_value.abs * height_factor
+      end
+    end
+
+    def y_for(target_value)
+      result = target_value.abs / options[:max].to_f * options[:height]
+
+      case mode
+      when :positive
+        options[:height] - result
+      when :negative
+        result
+      when :dual
+        options[:height] - (target_value / options[:max].to_f * half_height + half_height)
+      end
+    end
+  end
+end

data/lib/minichart/version.rb

@@ -1,3 +1,3 @@
 module Minichart
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: minichart
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Danny Ben Shitrit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-05-22 00:00:00.000000000 Z
+date: 2020-05-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: victor
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.3'
 description: Generate mini charts with SVG
 email: db@dannyben.com
 executables: []
@@ -32,9 +32,15 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/minichart.rb
-- lib/minichart/bar_chart.rb
-- lib/minichart/chart.rb
-- lib/minichart/line_chart.rb
+- lib/minichart/base.rb
+- lib/minichart/charts/area_chart.rb
+- lib/minichart/charts/bar_chart.rb
+- lib/minichart/charts/chart.rb
+- lib/minichart/charts/line_chart.rb
+- lib/minichart/id_generator.rb
+- lib/minichart/meters/horizontal_bar_meter.rb
+- lib/minichart/meters/meter.rb
+- lib/minichart/meters/vertical_bar_meter.rb
 - lib/minichart/version.rb
 homepage: https://github.com/DannyBen/minichart
 licenses:
@@ -48,14 +54,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.0.0
+      version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: SVG Mini Charts

data/lib/minichart/bar_chart.rb

@@ -1,29 +0,0 @@
-module Minichart
-  class BarChart < Chart
-    def build
-      opts  = { x_point_count: data.size }
-
-      inverted_points(opts).each do |x, y|
-        svg.rect bar_options x, y
-      end
-    end
-
-  private
-
-    def bar_width
-      @bar_width ||= width / data.size
-    end
-
-    def bar_options(x, y)
-      y = y*height
-      bar_height = height-y
-      { 
-        x: x*width, 
-        y: y, 
-        width: bar_width, 
-        height: bar_height, 
-        style: { fill: color, stroke_width: stroke, stroke: background }
-      }
-    end
-  end
-end

data/lib/minichart/chart.rb

@@ -1,67 +0,0 @@
-module Minichart
-  class Chart
-    attr_accessor :data, :aspect_ratio, :opts
-
-    def initialize(opts={})
-      @opts = opts
-    end
-
-    def save(name)
-      svg.rect x: 0, y: 0, width: width, height: height, fill: background
-      build
-      svg.save name
-    end
-
-    def build
-      raise NotImplementedError, "#build is not implemented"
-    end
-
-    def inverted_points(opts={})
-      normalized_points(opts).map { |point| [point[0], 1-point[1]] }
-    end
-
-    def normalized_points(opts={})
-      x_point_count = opts[:x_point_count] || data.count-1
-
-      range   = (data.max - data.min).to_f
-      x_width = 1/(x_point_count).to_f
-      result  = []
-
-      data.each_with_index do |y, index|
-        x = index*x_width
-        y = (y-data.min)/range
-        result << [x,y]
-      end
-
-      result
-    end
-
-    def width
-      @width ||= (aspect_ratio * height).round
-    end
-
-    def height
-      100
-    end
-
-    def svg
-      @svg ||= Victor::SVG.new viewBox: "0 0 #{width} #{height}", style: style
-    end
-
-    def style
-      @opts[:style] ||= {}
-    end
-
-    def background
-      @opts[:background] ||= '#eee'
-    end
-
-    def color
-      @opts[:color] || '#333'
-    end
-
-    def stroke
-      @opts[:stroke] ||= 2
-    end
-  end
-end

data/lib/minichart/line_chart.rb

@@ -1,19 +0,0 @@
-module Minichart
-  class LineChart < Chart
-    def build
-      svg.polyline fill: :none, stroke: color, stroke_width: stroke, points: points
-    end
-
-  private
-
-    def points
-      result = []
-      inverted_points.each do |point|
-        x = width*point[0]
-        y = height*point[1]
-        result << "#{x},#{y}"
-      end
-      result
-    end
-  end
-end