technical_graph 0.4.0 → 0.5.0

data/DOCUMENTATION.md

@@ -36,6 +36,10 @@ Axis labels:
     options[:x_axis_label] = 'x'
     options[:y_axis_label] = 'y'
 
+Adjust axis to be on 'zero':
+
+    options[:adjust_axis_to_zero] = true
+
 Labels has truncate string to define precision. Default it is "%.2f".
 
     options[:truncate_string] = "%.2f"
@@ -57,19 +61,18 @@ Colors:
 Possible #RRGGBB or color names (ex. 'white').
 
     options[:background_color] - background color of image
-    options[:background_hatch_color] - background hatch color
+    options[:background_hatch_color] - background hatch color, used only in rmagick renderer
     options[:axis_color] - color of axis, default #000000
 
 Anti-aliasing:
 
     options[:antialias] - draw axis using antialias
-    # 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[:legend_font_size] - size of font used in legend
     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.

data/DOCUMENTATION.textile

@@ -396,7 +396,21 @@ file_name = 'samples/readme/09_image_size.png'
 
 h2. Colours
 
-p. If you think you have better artistic taste feel free to change colours used in graph :)
+p. If you think you have better artistic taste feel free to change colours used in graph :) Keep in mind that hatch
+color is not available in rasem renderer which is default now.
+
+There are 3 color options per graph:
+
+# options[:background_color] - background color of image
+
+# options[:background_hatch_color] - background hatch color, used only in RMagick renderer
+
+# options[:axis_color] - color of axis, default #000000
+
+Ane 1 layer options
+
+# layer_options[:color] - it is color of layer
+
 
 <pre>
 <code>
@@ -411,31 +425,412 @@ p. If you think you have better artistic taste feel free to change colours used
 
 @tg = TechnicalGraph.new(
   {
-    :width => 600,
-    :height => 300
+    :background_color => '#000000',
+    :background_hatch_color => '#222222',
+    :axis_color => '#FFFFFF'
   })
-@tg.add_layer(@simple_data_array, @layer_params)
+@tg.add_layer(@simple_data_array, {:color => '#0000FF'})
 @tg.render
-file_name = 'samples/readme/09_image_size.png'
+file_name = 'samples/readme/10_colors.png'
 @tg.image_drawer.save_to_file(file_name)
 </code>
 </pre>
 
-!https://github.com/akwiatkowski/technical_graph/raw/master/samples/readme/09_image_size.png((09) image size)!
+!https://github.com/akwiatkowski/technical_graph/raw/master/samples/readme/10_colors.png((10) colors)!
+
+
+h2. Image render
+
+p. From version 0.4.0 there are two render classes: Rasem and RMagick. Rasem is better for fast SVG rendering, but
+RMagick is better for bitmaps like PNG. Svg can be converted to bitmap using 'convert' command (ImageMagick). It is
+intended that Rasem will be default renderer, and RMagick renderer will be supported as long as possible.
+
+You can override default setting which is Rasem using:
+
+<pre>
+<code>
+options[:drawer_class] = :rasem
+options[:drawer_class] = :rmagick
+</code>
+</pre>
+
+There is fallback - if you don't have install rmagick gem even if you set RMagick, technical_graph will use Rasem.
+
+<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(
+  {
+    :drawer_class => :rmagick
+  })
+@tg.add_layer(@simple_data_array)
+@tg.render
+file_name = 'samples/readme/11_renderer_rmagick.png'
+@tg.image_drawer.save_to_file(file_name)
+
+@tg = TechnicalGraph.new(
+  {
+    :drawer_class => :rasem
+  })
+@tg.add_layer(@simple_data_array)
+@tg.render
+file_name = 'samples/readme/11_renderer_rasem.png'
+@tg.image_drawer.save_to_file(file_name)
+</code>
+</pre>
+
+!https://github.com/akwiatkowski/technical_graph/raw/master/samples/readme/11_renderer_rmagick.png((11) RMagick)!
+!https://github.com/akwiatkowski/technical_graph/raw/master/samples/readme/11_renderer_rasem.png((11) Rasem)!
 
 
+h2. Anti-aliasing
+
+p. Anti-aliasing is only available using RMagick renderer. On default it is disabled.
+
+<pre>
+<code>
+options[:antialias] = true
+</code>
+</pre>
+
+Sample graph without anti-aliasing has 11kB, with 69kB. Does size matter to you?
+
+<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(
+  {
+    :antialias => true,
+    :drawer_class => :rmagick
+  })
+@tg.add_layer(@simple_data_array)
+@tg.render
+file_name = 'samples/readme/12_aa_true.png'
+@tg.image_drawer.save_to_file(file_name)
+
+# only for size comparison
+@tg = TechnicalGraph.new(
+  {
+    :antialias => false,
+    :drawer_class => :rmagick
+  })
+@tg.add_layer(@simple_data_array)
+@tg.render
+file_name = 'samples/readme/12_aa_false.png'
+@tg.image_drawer.save_to_file(file_name)
+</code>
+</pre>
+
+!https://github.com/akwiatkowski/technical_graph/raw/master/samples/readme/12_aa_true.png((12) Anti-aliasing enabled)!
+!https://github.com/akwiatkowski/technical_graph/raw/master/samples/readme/12_aa_false.png((12) Anti-aliasing disabled)!
+
+
+
+h2. Font size
+
+p. You can set various font sizes.
+
+# options[:layers_font_size] - size of font used for values in graph, keep in mind that layer_options[:value_labels]
+  must be enabled to see any result
+
+# 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], to see
+  any result at least one of them must be set
+
+
+<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',
+    :layers_font_size => 14,
+    :axis_font_size => 18,
+    :axis_label_font_size => 48
+  })
+@tg.add_layer(@simple_data_array, {:value_labels => true})
+@tg.render
+file_name = 'samples/readme/13_font_sizes.png'
+@tg.image_drawer.save_to_file(file_name)
+</code>
+</pre>
+
+!https://github.com/akwiatkowski/technical_graph/raw/master/samples/readme/13_font_sizes.png((13) Font size)!
+
+
+
+h2. Legend
+
+p. If you want to use legend you only have to set labels for layers and turn legend enabled by using:
+
+# options[:legend] - turn on legend, on default auto position mode is enabled
+
+# layer_options[:label] - label used for legend
+
+Position of legend is calculated automatic - 8 corner places are checked for distance to all graph points. Point
+which has longest distance is used for legend position.
+
+Every layer has own color which can be set by user using code below. If you don't set there is bank of some fixed colors
+and random color generator.
+
+<pre>
+<code>
+layer_options[:color] = '#FF0000' # color in format #RRGGBB
+</code>
+</pre>
+
+Graph sample code:
+
+<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_second = @simple_data_array.collect{|a| {:x => a[:x] + 0.31, :y => a[:y] + 0.21 }}
+@simple_data_array_third = @simple_data_array.collect{|a| {:x => a[:x] * 0.99 + 0.23, :y => a[:y] * 1.2 - 0.12 }}
+
+@tg = TechnicalGraph.new(
+  {
+    :legend => true
+  })
+@tg.add_layer(@simple_data_array, {:label => 'simple', :color => '#FFFF00'})
+@tg.add_layer(@simple_data_array_second, {:label => 'offset', :color => '#00FFFF'})
+@tg.add_layer(@simple_data_array_third, {:label => 'scaled', :color => '#FF00FF'})
+@tg.render
+file_name = 'samples/readme/14_simple_legend.png'
+@tg.image_drawer.save_to_file(file_name)
+</code>
+</pre>
+
+!https://github.com/akwiatkowski/technical_graph/raw/master/samples/readme/14_simple_legend.png((14) Legend)!
+
+You can turn off auto position if you like:
+
+<pre>
+<code>
+options[:legend_auto] = false
+options[:legend_x] = 100
+options[:legend_y] = 100
+</code>
+</pre>
+
+There are also other useful parameters
+
+# options[:legend_width] - width of longest label in pixels used for setting proper distance while drawing on right border
+  default 100 and is enlarged auto. using font size
+
+# options[:legend_margin] - graph margin used not to draw legend on border, default 50
+
+
+
+h2. Smoothing
+
+p. Useful when origin of data is a bit noisy. For best results you can add two layers: one raw, and second with smoothing.
+
+<pre>
+<code>
+@tg = TechnicalGraph.new(
+  {
+    :width => 2000,
+    :height => 1500,
+    :legend => true,
+    :x_axis_label => "Parameter",
+    :y_axis_label => "Value"
+  }
+)
+max = 250 #2000
+
+@layer_data = Array.new
+(0..max).each do |i|
+  x = -10.0 + (20.0 * i.to_f / max.to_f)
+  y = 10.0 * Math.cos(i.to_f * (2.0 * 3.14 / max.to_f))
+
+  y += rand * 2.0
+
+  @layer_data << { :x => x, :y => y }
+end
+
+# adding simple layer
+@layer_params = {
+  :label => 'raw',
+  :value_labels => false,
+  :simple_smoother => false,
+  :simple_smoother_level => 1,
+  :simple_smoother_strategy => :gauss,
+  :simple_smoother_x => false,
+}
+@layer_params_b = @layer_params.clone.merge(
+  {
+    :label => 'smoothed - level 3',
+    :simple_smoother_level => 3,
+    :simple_smoother => true
+  })
+@layer_params_e = @layer_params.clone.merge(
+  {
+    :label => 'smoothed - level 50',
+    :simple_smoother_level => 50,
+    :simple_smoother => true
+  })
+
+@tg.add_layer(@layer_data.clone, @layer_params)
+@tg.add_layer(@layer_data.clone, @layer_params_b)
+@tg.add_layer(@layer_data.clone, @layer_params_e)
+
+@tg.render
+file_name = 'samples/readme/15_smoothing.png'
+@tg.image_drawer.save_to_file(file_name)
+</code>
+</pre>
+
+!https://github.com/akwiatkowski/technical_graph/raw/master/samples/readme/15_smoothing.png((15) Smoothing)!
+
+
+
+h2. Noise removal
+
+p. Useful when origin of data is a bit noisy. For best results you can add two layers: one raw, and second with noise removal.
+   Can be used with smoothing.
+
+<pre>
+<code>
+@tg = TechnicalGraph.new(
+  {
+    :legend => true
+  }
+)
+max = 250
+
+@layer_data = Array.new
+(0..max).each do |i|
+  x = -10.0 + (20.0 * i.to_f / max.to_f)
+  y = -10.0 + (20.0 * i.to_f / max.to_f)
+  @layer_data << { :x => x, :y => y }
+end
+
+# custom spikes
+[3, 36, 99, 187, 204].each do |i|
+  offset = 5.0
+  offset *= -1.0 if rand(100) % 2 == 1
+  @layer_data[i][:y] += offset
+end
+
+# some random spikes
+150.times do
+  i = rand(@layer_data.size)
+  offset = rand(80).to_f / 10.0
+  offset *= -1.0 if rand(100) % 2 == 1
+
+  @layer_data[i][:y] += offset
+end
+
+# adding simple layer
+@layer_params = {
+  :label => 'raw',
+  :value_labels => false,
+}
+@layer_params_b = @layer_params.clone.merge(
+  {
+    :label => 'n.r. level 3, window 10',
+    :noise_removal_window_size => 10,
+    :noise_removal_level => 3,
+    :noise_removal => true
+  })
+@layer_params_e = @layer_params.clone.merge(
+  {
+    :label => 'n.r level 10, window 30',
+    :noise_removal_window_size => 10,
+    :noise_removal_level => 30,
+    :noise_removal => true
+  })
+
+@tg.add_layer(@layer_data.clone, @layer_params)
+@tg.add_layer(@layer_data.clone, @layer_params_b)
+@tg.add_layer(@layer_data.clone, @layer_params_e)
+
+@tg.render
+file_name = 'samples/readme/16_noise_removal.png'
+@tg.image_drawer.save_to_file(file_name)
+</code>
+</pre>
+
+!https://github.com/akwiatkowski/technical_graph/raw/master/samples/readme/16_noise_removal.png((16) Noise removal)!
+
+
+
+
+
+h2. Axis interval enlargement
+
+p. In case of large amount of data axis can be squeezed and graph is unreadable. You can set axis enlargement to kick in
+   in these situations. When distance between axis is lower than set in options[:x_axis_min_distance] or
+   options[:y_axis_min_distance] image dimensions are enlarged to maintain proper axis distances.
+
+<pre>
+<code>
+@tg = TechnicalGraph.new(
+  {
+    :axis_density_enlarge_image => true,
+    :x_axis_min_distance => 500,
+    :x_axis_interval => 1.0,
+    :x_axis_fixed_interval => true,
+    :width => 400
+  }
+)
+max = 250
+
+@layer_data = Array.new
+(0..max).each do |i|
+  x = -10.0 + (20.0 * i.to_f / max.to_f)
+  y = -10.0 + rand(2000).to_f / 100.0
+  @layer_data << { :x => x, :y => y }
+end
+
+@tg.add_layer(@layer_data)
+
+@tg.render
+file_name = 'samples/readme/17_axis_enlargement.png'
+@tg.image_drawer.save_to_file(file_name)
+</code>
+</pre>
 
+!https://github.com/akwiatkowski/technical_graph/raw/master/samples/readme/17_axis_enlargement.png((17) Axis enlargement)!
 
 
 h2. TODO
 
-# 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
+# Axis density checking algorithm - more info
+# Smoother - parameters
+# Noise removal - para
+# Adjusting axis to zero