technical_graph 0.3.0 → 0.3.1

data/DOCUMENTATION.textile

@@ -0,0 +1,374 @@
+h1. How to use it
+
+p. All this examples are generated in test/test_technical_readme.rb.
+
+
+
+
+
+h2. Simple graph
+
+p. First thing we need to have data to show on graph, for example something like:
+
+<pre>
+<code>
+@simple_data_array = [
+  { :x => 0, :y => 0 },
+  { :x => 1, :y => 1 },
+  { :x => 2, :y => 2 },
+  { :x => 3, :y => 2 },
+  { :x => 4, :y => 1 },
+  { :x => 5, :y => 0 },
+]
+</code>
+</pre>
+
+p. If you want to put this data on graph you need to create TechnicalGraph object
+
+<pre>
+<code>
+@tg = TechnicalGraph.new
+</code>
+</pre>
+
+p. and add a layer.
+
+<pre>
+<code>
+@tg.add_layer(@simple_data_array)
+</code>
+</pre>
+
+p. We added data but we don't see anything. Now we have to render graph and save it to file.
+
+<pre>
+<code>
+@tg.render
+file_name = 'samples/readme/01_simplest.png'
+@tg.image_drawer.save_to_file(file_name)
+</code>
+</pre>
+
+p. And we got our first graph with one layer without any options changes, a bit raw.
+
+!https://github.com/akwiatkowski/technical_graph/raw/master/samples/readme/01_simplest.png((01) simple graph)!
+
+
+
+
+
+h2. More layers
+
+p. Maybe example with two layers?
+
+<pre>
+<code>
+@simple_data_array = [
+  { :x => 0, :y => 0 },
+  { :x => 1, :y => 1 },
+  { :x => 2, :y => 2 },
+  { :x => 3, :y => 2 },
+  { :x => 4, :y => 1 },
+  { :x => 5, :y => 0 },
+]
+
+@simple_data_array_b = [
+  { :x => 0.5, :y => 0.5 },
+  { :x => 1.5, :y => 0.5 },
+  { :x => 2.5, :y => 1.5 },
+  { :x => 3.5, :y => 1.0 },
+  { :x => 4.5, :y => 1.5 },
+  { :x => 5.5, :y => 1.5 },
+]
+
+@tg = TechnicalGraph.new
+@tg.add_layer(@simple_data_array)
+@tg.add_layer(@simple_data_array_b)
+@tg.render
+file_name = 'samples/readme/02_two_layers.png'
+@tg.image_drawer.save_to_file(file_name)
+</code>
+</pre>
+
+
+!https://github.com/akwiatkowski/technical_graph/raw/master/samples/readme/02_two_layers.png((02) simple graph)!
+
+
+
+
+h2. Ranges
+
+p. On default ranges are calculated automatically so all points are visible. You can override ranges setting.
+
+<pre>
+<code>
+@simple_data_array = [
+  { :x => 0, :y => 0 },
+  { :x => 1, :y => 1 },
+  { :x => 2, :y => 2 },
+  { :x => 3, :y => 2 },
+  { :x => 4, :y => 1 },
+  { :x => 5, :y => 0 },
+]
+
+@tg = TechnicalGraph.new(
+  {
+    :x_min => -2,
+    :x_max => 10,
+    :y_min => -1,
+    :y_max => 10,
+  })
+
+@tg.add_layer(@simple_data_array)
+@tg.render
+file_name = 'samples/readme/03_changed_ranges.png'
+@tg.image_drawer.save_to_file(file_name)
+</code>
+</pre>
+
+!https://github.com/akwiatkowski/technical_graph/raw/master/samples/readme/03_changed_ranges.png((03) changed ranges)!
+
+
+p. Keep in mind that ranges will be changed but any point of graph can enlarge ranges that all points will be visible, unless...
+
+
+
+
+
+h2. Fixed ranges
+
+p. You can turn off automatic range enlargement algorithm by using:
+
+<pre>
+<code>
+options[:xy_behaviour] = :fixed
+</code>
+</pre>
+
+Example:
+
+<pre>
+<code>
+@simple_data_array = [
+  { :x => 0, :y => 0 },
+  { :x => 1, :y => 1 },
+  { :x => 2, :y => 2 },
+  { :x => 3, :y => 2 },
+  { :x => 4, :y => 1 },
+  { :x => 5, :y => 0 },
+]
+
+@tg = TechnicalGraph.new(
+  {
+    :x_min => 1,
+    :x_max => 2,
+    :y_min => 1,
+    :y_max => 2,
+    :xy_behaviour => :fixed,
+  })
+
+@tg.add_layer(@simple_data_array)
+@tg.render
+file_name = 'samples/readme/04_changed_ranges_fixed.png'
+@tg.image_drawer.save_to_file(file_name)
+</code>
+</pre>
+
+!https://github.com/akwiatkowski/technical_graph/raw/master/samples/readme/04_changed_ranges_fixed.png((04) changed ranges)!
+
+
+
+
+h2. Axis interval - fixed count
+
+p. Axis can be calculated using two algorithms:
+
+# fixed interval - axis is every some distance,
+# fixed count - there is fixed amount of axis on graph.
+
+p. Keep in mind that where is X (parameter) and Y (value) axis. If you want to set fixed amount you should set
+options[:x_axis_fixed_interval] and/or options[:y_axis_fixed_interval] to false, like in the example below.
+
+<pre>
+<code>
+@simple_data_array = [
+  { :x => 0, :y => 0 },
+  { :x => 1, :y => 1 },
+  { :x => 2, :y => 2 },
+  { :x => 3, :y => 2 },
+  { :x => 4, :y => 1 },
+  { :x => 5, :y => 0 },
+]
+
+@tg = TechnicalGraph.new(
+  {
+    :x_axis_fixed_interval => false,
+    :y_axis_fixed_interval => false,
+    :y_axis_count => 20,
+    :x_axis_count => 20,
+  })
+
+@tg.add_layer(@simple_data_array)
+@tg.render
+file_name = 'samples/readme/05_axis_fixed_amount.png'
+@tg.image_drawer.save_to_file(file_name)
+</code>
+</pre>
+
+!https://github.com/akwiatkowski/technical_graph/raw/master/samples/readme/05_axis_fixed_amount.png((05) fixed axis count)!
+
+
+
+
+h2. Axis interval - fixed interval
+
+p. Axis can be calculated using two algorithms:
+
+# fixed interval - axis is every some distance,
+# fixed count - there is fixed amount of axis on graph.
+
+p. Keep in mind that where is X (parameter) and Y (value) axis. If you want to set fixed amount you should set
+options[:x_axis_fixed_interval] and/or options[:y_axis_fixed_interval] to false, like in the example below.
+
+<pre>
+<code>
+@simple_data_array = [
+  { :x => 0, :y => 0 },
+  { :x => 1, :y => 1 },
+  { :x => 2, :y => 2 },
+  { :x => 3, :y => 2 },
+  { :x => 4, :y => 1 },
+  { :x => 5, :y => 0 },
+]
+
+@tg = TechnicalGraph.new(
+  {
+    :x_axis_fixed_interval => true,
+    :y_axis_fixed_interval => true,
+    :y_axis_interval => 0.8,
+    :x_axis_interval => 0.6,
+  })
+  @tg.add_layer(@simple_data_array)
+  @tg.render
+  file_name = 'samples/readme/06_axis_fixed_interval.png'
+  @tg.image_drawer.save_to_file(file_name)
+</code>
+</pre>
+
+!https://github.com/akwiatkowski/technical_graph/raw/master/samples/readme/06_axis_fixed_interval.png((06) fixed axis interval)!
+
+
+
+
+
+
+h2. Axis labels
+
+p. You can add label to X and Y axis. using options[:x_axis_label] and options[:y_axis_label], and you can choose font
+size using options[:axis_label_font_size].
+
+<pre>
+<code>
+@simple_data_array = [
+  { :x => 0, :y => 0 },
+  { :x => 1, :y => 1 },
+  { :x => 2, :y => 2 },
+  { :x => 3, :y => 2 },
+  { :x => 4, :y => 1 },
+  { :x => 5, :y => 0 },
+]
+
+@tg = TechnicalGraph.new(
+  {
+    :x_axis_label => 'parameter',
+    :y_axis_label => 'value',
+    :axis_label_font_size => 36
+  })
+  @@tg.add_layer(@simple_data_array)
+  @tg.render
+  file_name = 'samples/readme/07_axis_label.png'
+  @tg.image_drawer.save_to_file(file_name)
+</code>
+</pre>
+
+!https://github.com/akwiatkowski/technical_graph/raw/master/samples/readme/07_axis_label.png((07) axis labels)!
+
+
+
+h2. Float numbers and value labels
+
+p. On default all float number are shown using 2 digits after dot. You can override it using options[:truncate_string]
+like in example below. If you want have values near graph points you can use proper layer options.
+
+p. Layers have also options, and it is useful for this example to turn on value labels.
+
+layer_options[:value_labels]
+
+<pre>
+<code>
+@float_data_array = [
+  { :x => 0, :y => 0 },
+  { :x => 0.111, :y => 0.123 },
+  { :x => 0.222, :y => 1.456 },
+  { :x => 0.333, :y => 2.8756 },
+  { :x => 0.555, :y => 1.042 },
+  { :x => 0.888, :y => 0.988 },
+]
+
+@tg = TechnicalGraph.new(
+  {
+    :truncate_string => "%.3f"
+  })
+@layer_params = {
+  :value_labels => true
+}
+@tg.add_layer(@float_data_array, @layer_params)
+@tg.render
+file_name = 'samples/readme/08a_truncate_string.png'
+@tg.image_drawer.save_to_file(file_name)
+</code>
+</pre>
+
+!https://github.com/akwiatkowski/technical_graph/raw/master/samples/readme/08a_truncate_string.png((08a) displaying float numbers)!
+
+<pre>
+<code>
+@float_data_array = [
+  { :x => 0, :y => 0 },
+  { :x => 0.111, :y => 0.123 },
+  { :x => 0.222, :y => 1.456 },
+  { :x => 0.333, :y => 2.8756 },
+  { :x => 0.555, :y => 1.042 },
+  { :x => 0.888, :y => 0.988 },
+]
+
+@tg = TechnicalGraph.new(
+  {
+    :truncate_string => "%.1f"
+  })
+@layer_params = {
+  :value_labels => true
+}
+@tg.add_layer(@float_data_array, @layer_params)
+@tg.render
+file_name = 'samples/readme/08b_truncate_string.png'
+@tg.image_drawer.save_to_file(file_name)
+</code>
+</pre>
+
+!https://github.com/akwiatkowski/technical_graph/raw/master/samples/readme/08b_truncate_string.png((08b) displaying float numbers)!
+
+
+h2. TODO
+
+# Graph image size
+# Graph colors: background, hatch (option to turn it off?), axis
+# Anti-aliasing: image size comparison, layer antialiases
+# Font sizes
+# Axis density checking algorithm: sample when it us useful
+# Layer labels: used in legend
+# Layer colors, random colors
+# Legend with set position
+# Legend with auto position
+# Smoother:
+# Noise removal

data/README.md

@@ -1,11 +1,38 @@
-technical-graph
+technical_graph
 ===============
 
-Create neat graphs.
+Purpose of this gem is to create neat, meaningful, linear graphs for large amount of data.
 
+If you want to:
 
-Usage
------
+* create big graphs using large amount of data,
+* do it offline,
+* minimize needed code,
+* use only linear graph,
+* speed is not essential,
+* RMagick / ImageMagick is ok for you,
+* tired of forgotten gems/libraries...
+
+then you should try this gem.
+
+I created it because there were not available and maintained gems for that I needed. Now I use it to create hourly
+temperature and wind graphs for vast period of time (months, years), visualize measurements for [HomeIO](https://github.com/akwiatkowski/HomeIO).
+
+If you want to create candy, ultra fast, web graphs it maybe not the best tool. If you want other graph types than linear it
+is definitely not the right tool for you. It is also not SVG ready yet, but it should be within a few months.
+You can find my competitors [here](https://www.ruby-toolbox.com/categories/graphing).
+
+
+Future
+------
+
+1. Finish data processors: smoothing (nearly done), noise removal (50%), interpolation or curved graphs (planned).
+2. Fix export to SVG.
+3. Optimization, and if needed find or write something faster for creating SVGs.
+
+
+Quick start
+-----------
 
 Check currents test when documentation is not enough :)
 
@@ -32,7 +59,7 @@ or
 where:
 
 * layer_data - Array of Hashes, like [{:x => 0, :y => 0}, {:x => 1, :y => 1}, ...]
-* layer_params - Hash of other parameters, all parameters will be described later.
+* layer_params - Hash of other parameters, all parameters are described later.
 
 3. Render graph
 
@@ -46,101 +73,13 @@ or get image binary content.
 
 > tg.image_drawer.to_format(format)
 
-where format is image format, ex. 'png', 'jpeg', ...
+where format is image format, ex. 'png', 'jpeg', ... Of course I prefer 'png'.
 
 
-Options Hash
+Documentation
 -------------
 
-Default ranges:
-
-* options[:x_min]
-* options[:x_max]
-* options[:y_min]
-* options[:y_max]
-
-Ranges calculation mode:
-
-* options[:xy_behaviour] = :default - ranges can be enlarged
-* options[:xy_behaviour] = :fixed - fixed ranges
-
-Axis can be calculated using fixed interval or fixed count per graph.
-
-* options[:x_axis_fixed_interval] = true
-* options[:y_axis_fixed_interval] = true
-
-If fixed interval is set you should specify interval:
-
-* options[:y_axis_interval] = 1.0
-* options[:x_axis_interval] = 1.0
-
-...else, count of axis:
-
-* options[:y_axis_count] = 10
-* options[:x_axis_count] = 10
-
-Axis labels:
-
-* options[:x_axis_label] = 'x'
-* options[:y_axis_label] = 'y'
-
-
-Labels has truncate string to define precision. Default it is "%.2f".
-
-* options[:truncate_string] = "%.2f"
-
-Graph image size:
-
-* options[:width]
-* options[:height]
-
-Colors:
-
-Possible #RRGGBB or color names (ex. 'white').
-
-* options[:background_color] - background color of image
-* options[:background_hatch_color] - background hatch color
-* options[:axis_color] - color of axis
-
-Anti-aliasing:
-
-* options[:axis_antialias] - use anti-aliasing for axis, default false
-* options[:layers_antialias] - use anti-aliasing for data layers, default false, can be override using layer option
-* options[:font_antialias] - use anti-aliasing for all fonts, default false
-
-Font size:
-
-* options[:layers_font_size] - size of font used for values in graph
-* options[:axis_font_size] - size of font used in axis
-* options[:axis_label_font_size] - size of font used in options[:x_axis_label] and options[:y_axis_label]
-
-Sometime because of axis options and large amount of data, axis can be put densely on graph. Turning this option graph
-size will be enlarged to maintain set distanced between axis.
-
-* options[:axis_density_enlarge_image] - turn this options on
-* options[:x_axis_min_distance] - minimum distance between X axis, default 30 pixels
-* options[:y_axis_min_distance] - minimum distance between X axis, default 50 pixels
-
-Legend options:
-
-* options[:legend] - do you want to draw legend?, default false
-* options[:legend_auto] - let legend position to be chosen by algorithm, default true
-* options[:legend_width] - width used for setting proper distance while drawing on right, default 100, legend height is calculated
-* options[:legend_margin] - graph margin used not to draw legend on border, default 50
-* options[:legend_x] - legend X position, used when options[:legend_auto] is false, default 50
-* options[:legend_y] - legend Y position, used when options[:legend_auto] is false, default 50
-
-
-Layer options Hash
-------------------
-
-* layer_options[:label] - label used in legend
-* layer_options[:color] - color of graph layer, ex.: 'red', 'green', '#FFFF00'
-* layer_options[:antialias] - use anti-aliasing for this, default false, override options[:layers_antialias]
-* layer_options[:value_labels] - write values near 'dots', default true
-* layer_options[:simple_smoother] - 'smooth' data, default false
-* layer_options[:simple_smoother_level] - strength of smoothing, this is level of window used for processing, default 3
-* layer_options[:simple_smoother_strategy] - strategy used for smoothing data, you can choose between :rectangular or :gauss, default :rectangular
+Documentation is moved [here](https://github.com/akwiatkowski/technical_graph/blob/master/DOCUMENTATION.textile)
 
 
 Contributing to technical-graph

data/VERSION

@@ -1 +1 @@
-0.3.0
+0.3.1

data/lib/technical_graph/array.rb

@@ -0,0 +1,14 @@
+#encoding: utf-8
+
+# Additional methods for array
+# http://stackoverflow.com/questions/1341271/average-from-a-ruby-array
+
+class Array
+  def sum
+    inject(0.0) { |result, el| result + el }
+  end
+
+  def mean
+    sum / size
+  end
+end

data/lib/technical_graph/data_layer.rb

@@ -1,5 +1,6 @@
 #encoding: utf-8
 
+require 'technical_graph/data_point'
 require 'technical_graph/graph_color_library'
 require 'technical_graph/data_layer_processor'
 
@@ -20,8 +21,9 @@ class DataLayer
     # smoothing parameters
     # by default it is false
     @data_params[:simple_smoother] = true if options[:simple_smoother] == true
+    @data_params[:simple_smoother_x] = true if options[:simple_smoother_x] == true
     @data_params[:simple_smoother_level] ||= 3
-    @data_params[:simple_smoother_strategy] ||= DataLayerProcessor::DEFAULT_STRATEGY
+    @data_params[:simple_smoother_strategy] ||= DataLayerProcessor::DEFAULT_SIMPLE_SMOOTHER_STRATEGY
     # was already done
     @data_params[:processor_finished] = false
 
@@ -36,29 +38,42 @@ class DataLayer
   attr_reader :processor
 
   # Accessor for setting chart data for layer to draw
-  def append_data(d)
-    if d.kind_of? Array
-      @data += d
+  def append_data(data_array)
+    if data_array.kind_of? Array
+      # append as DataPoint
+      # convert to DataPoints, which has more specialized methods
+      data_array.each do |d|
+        @data << DataPoint.new(d)
+      end
+      
       # sort, clean bad records
-      process_data
+      process_data_internal
+
+      # @raw_data is dirty, deleting @processed_data
+      @processed_data = nil
     else
       raise 'Data not an Array'
     end
   end
 
-  # Array of {:x =>, :y =>}
-  attr_reader :data
+  # Array of DataPoints, not processed
+  def raw_data
+    @data
+  end
 
-  # Run external processor (smoothing, ...)
-  def process
-    if simple_smoother and not processor_finished?
-      @processor.strategy = simple_smoother_strategy
-      @processor.level = simple_smoother_level
-      @processor.generate_vector
-      @data = @processor.process
-
-      processor_finished!
+  # Array of DataPoints, after external processing
+  def processed_data
+    if @processed_data.nil?
+      process!
     end
+
+    @processed_data
+  end
+
+  # Run external processor (smoothing, ...)
+  def process!
+    @processed_data = @data.clone
+    @processed_data = @processor.process
   end
 
   # Additional parameters
@@ -97,14 +112,8 @@ class DataLayer
     return @data_params[:simple_smoother_strategy]
   end
 
-  # Was already processed?
-  def processor_finished?
-    @data_params[:processor_finished]
-  end
-
-  # Mark as processed
-  def processor_finished!
-    @data_params[:processor_finished] = true
+  def simple_smoother_x
+    return @data_params[:simple_smoother_x]
   end
 
   # Clear data
@@ -113,24 +122,23 @@ class DataLayer
   end
 
   # Clean and process data used for drawing current data layer
-  def process_data
+  def process_data_internal
     # delete duplicates
-    @data = @data.inject([]) { |result, d| result << d unless result.select { |r| r[:x] == d[:x] }.size > 0; result }
+    @data = @data.inject([]) { |result, d| result << d unless result.select { |r| r.x == d.x }.size > 0; result }
 
-    @data.delete_if { |d| d[:x].nil? or d[:y].nil? }
-    @data.sort! { |d, e| d[:x] <=> e[:x] }
+    @data.delete_if { |d| d.x.nil? or d.y.nil? }
+    @data.sort! { |d, e| d.x <=> e.x }
 
     # default X values, if data is not empty
     if @data.size > 0
-      @data_params[:x_min] = @data.first[:x] || @options[:default_x_min]
-      @data_params[:x_max] = @data.last[:x] || @options[:default_x_max]
+      @data_params[:x_min] = @data.first.x || @options[:default_x_min]
+      @data_params[:x_max] = @data.last.x || @options[:default_x_max]
 
       # default Y values
-      y_sort = @data.sort { |a, b| a[:y] <=> b[:y] }
-      @data_params[:y_min] = y_sort.first[:y] || @options[:default_y_min]
-      @data_params[:y_max] = y_sort.last[:y] || @options[:@default_y_max]
+      y_sort = @data.sort { |a, b| a.y <=> b.y }
+      @data_params[:y_min] = y_sort.first.y || @options[:default_y_min]
+      @data_params[:y_max] = y_sort.last.y || @options[:@default_y_max]
     end
-
   end
 
   def x_min