ctioga2 0.0

data/lib/ctioga2/graphics/types.rb

@@ -0,0 +1,188 @@
+# types.rb: various useful types to interact with Tioga
+# copyright (c) 2009 by Vincent Fourmond
+  
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+  
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details (in the COPYING file).
+
+require 'ctioga2/graphics/types/dimensions'
+require 'ctioga2/graphics/types/point'
+require 'ctioga2/graphics/types/boundaries'
+require 'ctioga2/graphics/types/boxes'
+require 'ctioga2/graphics/types/bijection'
+
+# In addition to the former, here are some useful constants
+# This module contains all the classes used by ctioga
+module CTioga2
+
+  Version::register_svn_info('$Revision: 96 $', '$Date: 2009-06-27 20:56:17 +0200 (Sat, 27 Jun 2009) $')
+
+  module Graphics
+
+    # A small convenience module for line styles
+    module LineStyles
+      include Tioga::FigureConstants
+
+      Line_Type_Dash_Dot_Dot = [[5,2,1,2,1,2],0]
+      Line_Type_Small_Dots = [[0.5,1],0]
+
+      # Shortcut for line styles:
+      Solid  = Line_Type_Solid
+      Dots   = Line_Type_Dots
+      Dashes = Line_Type_Dashes
+      Small_Dots = Line_Type_Small_Dots
+      Dot_Long_Dash = Line_Type_Dot_Long_Dash
+      Dash_Dot_Dot = Line_Type_Dash_Dot_Dot
+    end
+
+
+    ColorType = CmdType.new('color', {
+                              :type => :tioga_color,
+                              :namespace => Tioga::ColorConstants
+                            }, <<EOD)
+A color. It can take three forms:
+ * the name of a named color; see 
+http://tioga.rubyforge.org/doc/classes/Tioga/ColorConstants.html
+for the list of colors.
+ * an HTML color: for instance, #f00 or #ff0000 is red;
+ * a list of three numbers between 0 and 1: 1,0,0 is red too.
+EOD
+
+    ColorOrFalseType = 
+      CmdType.new('color-or-false', {
+                    :type => :tioga_color,
+                    :namespace => Tioga::ColorConstants,
+                    :shortcuts => {'none' => false }
+                  }, <<EOD)
+A {type: color}, or false to say that nothing should be drawn.
+EOD
+
+    LineStyleType = 
+      CmdType.new('line-style', {
+                    :type => :tioga_line_style,
+                    :namespace => LineStyles
+                  }, <<EOD)
+A line style.
+EOD
+
+    MarkerType = 
+      CmdType.new('marker', {
+                    :type => :tioga_marker,
+                    :namespace => Tioga::MarkerConstants,
+                    :shortcuts => {
+                      'None' => 'None',
+                      'no' => 'None',
+                      'none' => 'None',
+                      'off' => 'None', 
+                    },}, <<EOD)
+A Tioga Marker.
+EOD
+
+    PointType = 
+      CmdType.new('point', :point, <<EOD)
+A given point on a figure.
+EOD
+
+    JustificationType = 
+      CmdType.new('justification', :tioga_justification, <<EOD)
+Horizontal aligment for text.
+EOD
+
+    AlignmentType = 
+      CmdType.new('alignment', :tioga_align, <<EOD)
+Vertical aligment for text.
+EOD
+
+    PDFFont = 
+      CmdType.new('pdf-font', :integer, <<EOD)
+A number between 1 and 14 that designates one of the 14 standard 
+PDF fonts.
+EOD
+
+    AlignedPointType = 
+      CmdType.new('aligned-point', {:type => :aligned_point, 
+                    :default => :frame}, <<EOD)
+A point together with alignment specifications.
+EOD
+
+    FrameMarginsType = 
+      CmdType.new('frame-margins', {:type => 
+                    :frame_margins, :shortcuts => 
+                    { /^\s*auto\s*$/i => nil}}, <<EOD)
+Margins around a plot, ie the distance from the side of the plot to
+the corresponding side of the container (most likely the whole
+PDF). It can take three forms:
+
+ * dimension (applies to all sides)
+ * left_right, top_bottom
+ * left, right, top, bottom
+
+Each of the elements is a valid {type: dimension}.
+
+It can also be auto, in which case the position of the margins is
+computed automatically to accomodate the various labels/ticks.
+EOD
+
+    # Now, axes stuff:
+
+    AxisDecorationType = 
+      CmdType.new('axis-decoration', :tioga_axis_type, <<EOD)
+Kinds of decoration on a axis line, such as nothing, lines, ticks, 
+tick labels...
+EOD
+
+    # Dimensions
+
+    DimensionType = 
+      CmdType.new('dimension', { :type => :dimension, 
+                    :default => :dy }, <<EOD)
+
+A dimension, in absolute units, or in units of text height, figure,
+frame or page coordinates. It is in the form 
+
+@ value unit
+
+Where value is a number and unit can be one of pt,bp,in,cm (absolute
+units, same meaning as in TeX), dy (1.0 dy is the height of a text
+line), figure (for figure coordinates, i.e. the coordinates of the
+plot), frame (1.0 frame is the full size of the current subplot) and
+page (1.0 page is the whole height/width of the output file).
+
+figure can be abbreviated as f, frame as F and page as p.
+EOD
+
+    # Boxes
+
+    BoxType = 
+      CmdType.new('box', :box, <<EOD)
+The specification for a box, such as an inset. Specifications vary for
+now... 
+
+TODO: to be written later on.
+EOD
+
+    # Coordinate transformations
+    BijectionType = 
+      CmdType.new('bijection', :bijection, <<EOD)
+A pair of functions of x specifying a bidirectional coordinate
+transformation , separated by a double colon (::), in the order
+from::to.
+
+Each of the functions must be valid Ruby code - it is not exactly
+mathematical functions, in particular Ruby does not like floats which
+are missing digits on either side of the dot : for instance, .3 and
+1. are not valid. Sorry.
+
+In most of the usual cases, the coordinate transform is an involution,
+that is from and to is the same function (this is the case for
+a/x). In this case, you can omit the second function.
+EOD
+
+  end
+end

data/lib/ctioga2/graphics/types/bijection.rb

@@ -0,0 +1,79 @@
+# bijection.rb: a bijection representing a reversible coordinate transformation
+# copyright (c) 2009 by Vincent Fourmond
+  
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+  
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details (in the COPYING file).
+
+require 'ctioga2/utils'
+require 'ctioga2/log'
+
+module CTioga2
+
+  Version::register_svn_info('$Revision: 67 $', '$Date: 2009-05-30 23:38:00 +0200 (Sat, 30 May 2009) $')
+
+  module Graphics
+
+    module Types
+
+      # This class represents a *reversible* arbitrary coordinate
+      # transformation, such as the ones that could be desirable for
+      # alternative axes. Characterized by two Block objects, #from
+      # and #to, that converts respectively from and to the target
+      # coordinates.
+      class Bijection
+
+        # A Block converting from the target coordinates
+        attr_accessor :from
+
+        # A Block converting to the target coordinates
+        attr_accessor :to
+
+        # Creates a new Bijection with the given blocks.
+        def initialize(from, to = nil)
+          @from = from
+          @to = to || @from
+        end
+
+        # Converts a vector to the target coordinates
+        def convert_to(vect)
+          return vect.map do |x|
+            self.to.call(x)
+          end
+        end
+
+        # Converts a vector from the target coordinates
+        def convert_from(vect)
+          return vect.map do |x|
+            self.from.call(x)
+          end
+        end
+
+        # Creates a Bijection from a text representation.
+        #
+        # Takes functions of _x_. Takes two blocks _from_ _to_
+        # separated by :: -- or only one block in the case of an
+        # involution (very common, actually, all 1/x transforms).
+        #
+        # TODO: few things around here to change... in particular,
+        # I should try to find a way to include Math... 
+        #
+        # TODO: add very common cases ?
+        def self.from_text(spec)
+          blocks = spec.split(/::/).map do |code|
+            eval("proc do |x|\n#{code}\nend")
+          end
+          return Bijection.new(*blocks)
+        end
+      end
+
+    end
+  end
+end
+

data/lib/ctioga2/graphics/types/boundaries.rb

@@ -0,0 +1,170 @@
+# boundaries.rb: manipulation of Plot boundaries
+# copyright (c) 2009 by Vincent Fourmond
+  
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+  
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details (in the COPYING file).
+
+require 'ctioga2/utils'
+require 'ctioga2/log'
+
+module CTioga2
+
+  Version::register_svn_info('$Revision: 2 $', '$Date: 2009-04-25 14:03:30 +0200 (Sat, 25 Apr 2009) $')
+
+  # This module contains all graphical elements of CTioga2
+  module Graphics
+
+    # A module holding different data types useful for interacting
+    # with Tioga
+    module Types
+
+      # An object representing boundaries for a plot.
+      class Boundaries
+
+        # Boundaries
+        attr_accessor :left, :right, :top, :bottom
+
+        # Creates a new Boundaries object with the given boundaries. A
+        # _nil_, _false_ or NaN in one of those means *unspecified*.
+        def initialize(left, right, top, bottom)
+          @left = left
+          @right = right
+          @top = top
+          @bottom = bottom
+        end
+
+        # Converts to an array suitable for use with Tioga.
+        def to_a
+          return [@left, @right, @top, @bottom]
+        end
+
+        # Minimum x value
+        def xmin
+          @left < @right ? @left : @right
+        end
+
+        # Maximum x value
+        def xmax
+          @left > @right ? @left : @right
+        end
+
+        # Minimum y value
+        def ymin
+          @bottom < @top ? @bottom : @top
+        end
+
+        # Maxiumum y value
+        def ymax
+          @bottom > @top ? @bottom : @top
+        end
+
+
+        # Converts to an [xmin, xmax, ymin, ymax] array
+        def extrema
+          return [xmin, xmax, ymin, ymax]
+        end
+
+        # The algebraic width of the boundaries
+        def width
+          return @right - @left
+        end
+
+        # The algebraic height of the boundaries
+        def height
+          return @top - @bottom
+        end
+
+        # This function makes sures that the Boundaries object is big
+        # enough to encompass what it currently does and the _bounds_
+        # Boundaries object.
+        def extend(bounds)
+          # Left/right
+          if (! @left.is_a? Float) or @left.nan? or
+              (@left > bounds.left)
+            @left = bounds.left
+          end
+          if (! @right.is_a? Float) or @right.nan? or
+              (@right < bounds.right)
+            @right = bounds.right
+          end
+
+          # Top/bottom
+          if (! @top.is_a? Float) or @top.nan? or
+              (@top < bounds.top)
+            @top = bounds.top
+          end
+          if (! @bottom.is_a? Float) or @bottom.nan? or
+              (@bottom > bounds.bottom)
+            @bottom = bounds.bottom
+          end
+          return self
+        end
+
+
+        # Override the Boundaries with the contents of _override_. All
+        # elements which are not _nil_ or NaN from _override_
+        # precisely override those in _self_.
+        def override_boundaries(override)
+          for el in [ :left, :right, :top, :bottom]
+            val = override.send(el)
+            if val and (val == val) # Strip NaN on the property that NaN != NaN
+              self.send("#{el}=", val)
+            end
+          end
+        end
+
+        # Apply a fixed margin on the Boundaries.
+        def apply_margin!(margin)
+          w = self.width
+          @left = @left - margin * w
+          @right = @right + margin * w
+          h = self.height
+          @top = @top + margin * h
+          @bottom = @bottom - margin * h
+        end
+
+        # Sets the values of the Boundaries for the _which_ axis from
+        # the given _range_.
+        def set_from_range(range, which)
+          case which
+          when :x
+            @left, @right = range.first, range.last
+          when :y
+            @bottom, @top = range.first, range.last
+          else
+            raise "What is this #{which} axis ? "
+          end
+        end
+
+        # Returns a boundary object that exactly contains all _x_values_
+        # and _y_values_ (including error bars if applicable)
+        def self.bounds(x_values, y_values)
+          return Boundaries.new(x_values.min, x_values.max,
+                                y_values.max, y_values.min)
+        end
+
+        # Takes an array of Boundaries and returns a Boundaries object
+        # that precisely encompasses them all. Invalid floats are simply
+        # ignored.
+        def self.overall_bounds(bounds)
+          retval = Boundaries.new(nil, nil, nil, nil)
+          for b in bounds
+            retval.extend(b)
+          end
+          return retval
+        end
+
+      end
+      
+    end
+
+  end
+
+end

data/lib/ctioga2/graphics/types/boxes.rb

@@ -0,0 +1,157 @@
+# boxes.rb: various ways to represent a box in Tioga
+# copyright (c) 2009 by Vincent Fourmond
+  
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+  
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details (in the COPYING file).
+
+require 'ctioga2/utils'
+require 'ctioga2/log'
+
+module CTioga2
+
+  Version::register_svn_info('$Revision: 92 $', '$Date: 2009-06-24 01:17:46 +0200 (Wed, 24 Jun 2009) $')
+
+  # This module contains all graphical elements of CTioga2
+  module Graphics
+
+    # A module holding different data types useful for interacting
+    # with Tioga
+    module Types
+
+      # The base class for different kind of boxes
+      class Box
+
+        def initialize
+          raise "Use a derived class !"
+        end
+
+        # This function returns the frame coordinates of the box, in
+        # the form:
+        #  [ xl, yt, xr, yb ]
+        # This function *must* be reimplemented in children.
+        def to_frame_coordinates(t)
+          raise "Reimplement this in children !"
+        end
+
+        # Converts this object into an array suitable for use with
+        # FigureMaker#set_sub_frame.
+        def to_frame_margins(t)
+          xl, yt, xr, yb = self.to_frame_coordinates(t)
+          return [xl, 1 - xr, 1 - yt, yb]
+        end
+        
+      end
+
+      # A box defined by its margins
+      class MarginsBox < Box
+
+        # Margin specifications. These are Dimension objects.
+        attr_accessor :left, :right, :top, :bottom
+
+        # Creates a new MarginsBox object with the specified margins,
+        # as String (passed on to Dimension::to_text), float (defaults
+        # to frame coordinates) or directly as Dimension objects.
+        #
+        # The Dimension's orientation is automatically tweaked.
+        def initialize(left, right, top, bottom)
+          # First, convert any float into Dimension:
+          a = [left, right, top, bottom]
+          a.each_index do |i|
+            if ! a[i].is_a? Dimension
+              a[i] = Dimension::from_text(a[i].to_s, :x, :frame)
+            end
+          end
+          left, right, top, bottom = a
+
+          # Then assign to the appropriate stuff:
+          @left = left
+          @left.orientation = :x
+          @right = right
+          @right.orientation = :x
+          @top = top
+          @top.orientation = :y
+          @bottom = bottom
+          @bottom.orientation = :y
+        end
+
+        def to_frame_coordinates(t)
+          return [@left.to_frame(t), 1 - @top.to_frame(t),
+                  1 - @right.to_frame(t), @bottom.to_frame(t)]
+        end
+
+        # Returns the dimensions composing the MarginsBox, in the
+        # order _left_, _right_, _top_, _bottom_, suitable for feeding
+        # to MarginsBox.new.
+        def margins
+          return [@left, @right, @top, @bottom]
+        end
+
+      end
+
+      # A box defined by an AlignedPoint and two dimensions
+      class PointBasedBox < Box
+
+        # The aligned point of the box:
+        attr_accessor :point
+
+        # The width
+        attr_accessor :width
+        
+        # The height
+        attr_accessor :height
+
+        # Creates a new PointBasedBox at the given _point_, with the
+        # given _width_ and _height_.
+        def initialize(point, width, height)
+          @point = point
+          @width = width
+          @height = height
+        end
+
+        # A well formed point-based box must match the following
+        # regular expression.
+        PointBasedBoxRE = /^\s*(.*):([^,]+)(?:,\s*(.*))?$/
+
+        # Returns a new PointBasedBox object based on the text
+        # specification, which reads:
+        #
+        #   aligned_point:w(,h)
+        #
+        # The default holds for point and dimensions
+        def self.from_text(text, default = :frame)
+          if text =~ PointBasedBoxRE
+            po,w,h = $1,$2,$3
+            point = AlignedPoint.from_text(po, default)
+            width = Dimension.from_text(w, :x, default)
+            if h
+              height = Dimension.from_text(h, :y, default)
+            else
+              height = width.dup
+            end
+            return PointBasedBox.new(point, width, height)
+          else
+            raise "#{text} is not a point-based box."
+          end
+        end
+
+        # Returns the frame coordinates of the box.
+        def to_frame_coordinates(t)
+          dx = @width.to_figure(t, :x)
+          dy = @height.to_figure(t, :y)
+          a = @point.to_frame_coordinates(t, dx, dy)
+          return @point.to_frame_coordinates(t, dx, dy)
+        end
+        
+      end
+
+    end
+  end
+end
+