ctioga 1.11.1

data/lib/CTioga/layout.rb

@@ -0,0 +1,595 @@
+# layout.rb, copyright (c) 2006 by Vincent Fourmond: 
+# The core of the layout computation
+  
+# 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 'Tioga/Utils'
+require 'CTioga/log'
+require 'CTioga/dimension'
+require 'CTioga/boundaries'
+
+
+module CTioga
+
+  Version::register_svn_info('$Revision: 836 $', '$Date: 2008-10-10 01:27:54 +0200 (Fri, 10 Oct 2008) $')
+
+  # This class merely stores various information about the layout,
+  # such as the desired mimimum amount of padding on the sides,
+  # the desired distance between plots and legends, the size and
+  # position of the legend...
+  #
+  # For now, this class is hardly more than a Struct, but that is
+  # a very convenient way to carry across several objects and keep the
+  # documentation.
+  #
+  # Every Container should have a LayoutPreference object in its
+  # layout_preferences attribute.
+  class LayoutPreferences
+
+    LayoutDefaults = {
+      :padding => [Dimension.new(0.05),
+                   Dimension.new(0.05),
+                   Dimension.new(0.05),
+                   Dimension.new(0.05)],
+      :legend_size => Dimension.new(0.15),
+      :legend_position => :right,
+      :legend_glue => Dimension.new("2pt")
+    }
+
+    # Padding: (left, right, top, bottom)
+    # An array of Dimensions specifiying the desired amount of padding
+    # around a given object.
+    attr_accessor :padding
+
+    # The legend position: :left, :right, :top, :bottom or :inside
+    attr_accessor :legend_position
+
+    # The size of the legend. Not applicable in the case of an
+    # :inside legend specification.
+    attr_accessor :legend_size
+
+    # The full legend specification, in the case of an inside legend.
+    attr_accessor :legend_spec
+
+    # The minimum space between the graph and the legend, when the latter
+    # is on one of the sides of the graph.
+    attr_accessor :legend_glue
+
+    def initialize
+      for key,val in LayoutDefaults
+        self.send("#{key}=", val)
+      end
+    end
+
+
+    # Converts the padding to values relative to the given
+    # frames
+    def self.padding_relative_values(p, frames)
+      ret_val = []
+      4.times do |i|
+        if p[i]
+          ret_val[i] = p[i].to_relative(frames,
+                                        i < 2 ? :horizontal : :vertical)
+        else
+          ret_val[i] = 0        # safely default to 0 ???
+        end
+      end
+      return ret_val
+    end
+
+    def padding_relative_values(frames)
+      return LayoutPreferences.padding_relative_values(@padding, frames)
+    end
+  end
+
+  # Handles the gory details of placement of objects. It can be called
+  # to provide any of the specification for a subplot/subfigure, or
+  # the hash necessary to be fed to show_plot_with_legend.
+  #
+  # Every layout object has a root object (object), the base one,
+  # the one which
+  # limits its capabilities. No layout object should touch anything
+  # that is not a descendant of the root object -- or the root object
+  # itself.
+  #
+  # In addition to that, the layout can handle many children of this
+  # root object that request it.
+  class Layout
+
+    include Log
+
+    # The object the layout is handling. Should never be null.
+    attr_accessor :object
+    
+    # The layouts that would wish to report extensions information
+    # to this one.
+    attr_accessor :child_layouts
+
+    # The parent layout. Can be nil. Most of the layouts won't
+    # reall take something from this.
+    attr_accessor :parent
+
+    # Performs basic initialization. All descendants from this class
+    # should have at least three arguments, and at most three mandatory
+    # ones, always the same. Else, the convert_layout function
+    # won't work, and that means trouble.
+    def initialize(ro, ch = [], children = [] )
+      @object = ro
+      @object.layout = self
+      @child_layouts = []
+      for c in children
+        add_child(c)
+      end
+      @parent = nil
+    end
+
+    # Converts self into another layout, whose class is _cls_.
+    def convert_layout(cls)
+      return cls.new(object, @child_layouts)
+    end
+
+    # Ask this layout to manage a child. No check is done to
+    # actually ensure that the child really is a child.
+    def add_child(child)
+      child.parent = self
+      @child_layouts << child
+    end
+    
+    # Returns the specs to be fed to show_plot_with_legend
+    # for the given _object_.
+    #
+    # Defaults to full plot.
+    def legend_specs(object, t = nil)
+      return [0,0,0,0].to_frame("plot_%s_margin")
+    end
+
+    # Now, various utility functions that should make the
+    # life much easier for derived classes (or at least
+    # to the person who'll be writing them).
+
+    # A utility function that adds an extension as reported by
+    # Axes#extension (or any other, for what matters)
+    # to an already existing array of _extensions_.
+    # It will replace the current element unless it is smaller.
+    def update_extension_with_object(extensions, object, t, scale = 1)
+      new_ext = object.extension(t,scale)
+      return update_extensions(extensions, new_ext)
+    end
+
+    # Simply updates the given extensions with the new ones, making
+    # sure that nall the objects can be crammed inside.
+    def update_extensions(extensions, new_ext)
+      return Dimension.update_extensions(extensions, new_ext)
+    end
+
+    # Returns the extension of the layout
+    def extension(t)
+      extensions = [0,0,0,0]
+      # TODO: maybe this code should move within the PlotStyle object
+      for a in [:title, :xlabel, :ylabel]
+        update_extension_with_object(extensions, 
+                                     @object.plot_style.send(a),
+                                     t, @object.rescale || 1)
+      end
+      update_extension_with_object(extensions, @object.plot_style.edges,t)
+      debug "Layout #{"%x" % self.object_id} extensions #{extensions.inspect}"
+      return extensions
+    end
+
+    # Computes the extension for the legend, according to the
+    # position. Does not check if the object actually needs to
+    # display any legend whatsoever.
+    def legend_extension(t)
+      frame = @object.outer_frame(t)
+      case @object.layout_preferences.legend_position
+      when :left
+        return [@object.layout_preferences.
+                legend_size.to_absolute(frame, :horizontal),0,0,0]
+      when :right
+        return [0,@object.layout_preferences.
+                legend_size.to_absolute(frame, :horizontal),0,0]
+      when :top
+        return [0,0,@object.layout_preferences.
+                legend_size.to_absolute(frame, :vertical),0]
+      when :bottom
+        return [0,0,0,
+                @object.layout_preferences.
+                legend_size.to_absolute(frame, :vertical)]
+      when :inside
+        return [0,0,0,0]        # Inside doesn't count !
+      else
+        warn "Invalid legend position specification"
+        return [0,0,0,0]        # Does not count.
+      end
+    end
+
+    # All the things about legends here should eventually be
+    # moved to their own file, very much like the axes things. There
+    # is no real reason to differentiate them.
+
+    # Converts the legend extension to a full legend specification.
+    def legend_only_specs(t, padding)
+      frame = @object.outer_frame(t)
+      case @object.layout_preferences.legend_position
+      when :inside
+        # Use the legend_spec without any other modification.
+        return @object.layout_preferences.legend_spec
+      else
+        ext = legend_extension(t)
+        mar = Dimension.absolute_to_relative(ext, frame)
+      end
+
+      target = [0,0,0,0]
+      4.times do |i|
+        if mar[i] > 0
+          target[(i/2) * 2 + ((i+1) % 2)] = 1 - mar[i]
+        end
+      end
+
+      # Now, the legend spec is nearly ready; we just need to
+      # modify it so that it matches the sides of the plot.
+      case @object.layout_preferences.legend_position
+      when :left, :right
+        target[2] = padding[2]
+        target[3] = padding[3]
+      when :top, :bottom
+        target[0] = padding[0]
+        target[1] = padding[1]
+      end
+
+      return target.to_frame("legend_%s_margin")
+    end
+
+    # Returns the padding for the given object, taking into
+    # account the position of legends:
+    def compute_padding(object)
+      prefs = @object.layout_preferences
+      padding = @object.layout_preferences.padding.dup
+
+      # If the object has a legend 
+      if @object.display_legend? && Utils::side?(prefs.legend_position)
+        padding[Utils::side(prefs.legend_position)] = 
+          prefs.legend_glue.dup
+      end
+      return padding
+    end
+
+  end
+
+  # Now come the interesting part: the layouts !!!!
+
+
+  # This class takes care of simple plots. All children
+  # are considered for computing the extension of the plots, but
+  # they won't receive anything else than a default full frame.
+  #
+  # For now, the legend is not taken into consideration -- and the
+  # children as well ;-) !!
+  #
+  # The SimpleLayout class is also meant as a base class for any
+  # layout that would need to know its extensions, but that will
+  # not get positionned at all in the same way.
+  class SimpleLayout < Layout
+
+    # A hash setting the 'bounding box' for the plot. It is relative
+    # to the Container#outer_frame. Defaults to 0: the object occupies
+    # all the frame.
+    attr_accessor :bounding_box
+
+    def initialize(ro, ch = [], children = [] )
+      super
+      @bounding_box = [0.0, 0.0, 0.0, 0.0]
+    end
+
+    # Returns the object's frame.
+    def legend_specs(t = nil)
+      a = extension(t)
+      frames = @object.outer_frame(t)
+      padding = Dimension.absolute_to_relative(a, frames)
+
+      padding_prefs = 
+        LayoutPreferences.padding_relative_values(compute_padding(@object), 
+                                                  frames)
+
+      update_extensions(padding, padding_prefs)
+      
+      # If we display a legend, add the legend to the side.
+      if @object.display_legend?
+        a = Dimension.absolute_to_relative(legend_extension(t),frames)
+        4.times do |i|
+          padding[i] += a[i]
+        end
+      end
+      
+      specs = {}
+      i = 0
+      for side in %w(left right top bottom)
+        specs["plot_#{side}_margin"] = padding[i] + @bounding_box[i]
+        i += 1
+      end
+      if @object.display_legend?
+        a = legend_only_specs(t, padding)
+        return specs.merge(a)
+      else
+        return specs
+      end
+    end
+
+    # Returns this layout's extension. By default, it also
+    # includes the children's extensions, unless the
+    # @ignore_children_extensions variable is set.
+    def extension(t)
+      # We use the simple extensions computation from Layout
+      a = super
+      # We update it with the children's informations:
+      unless @ignore_children_extensions
+        for f in @child_layouts
+          update_extensions(a, f.extension(t))
+        end
+      end
+      return a
+    end
+
+  end
+
+  # This class implements a layout for objects that only need to report
+  # extension information to the parent but don't need to really take
+  # this into consideration for themselves. A good example is the
+  # 'alternative axes' things.
+  class FixedLayout < SimpleLayout
+
+    # The margins of the given object, either an array or a hash
+    # with plot_%s_margin
+    attr_accessor :position
+
+    # Creates a Fixed layout for the given object.
+    def initialize(ro, ch = [], children = [])
+      super
+      @position = [0, 0, 0, 0]
+    end
+
+    # Return default plot specifications: we don't take the
+    # legend into consideration, for instance.
+    def legend_specs(object, t = nil)
+
+      # First, the position of the layout:
+      if @position.is_a? Hash
+        specs = @position.dup
+      else
+        specs = @position.to_frame("plot_%s_margin")
+      end
+
+
+      # Then handling of the legends if applicable:
+      # TODO: this will fail for normal legends....
+      if @object.display_legend?
+        case @object.layout_preferences.legend_position
+        when :inside
+          a = @object.layout_preferences.legend_spec
+          
+          legend = Utils::frame_to_array(a, "legend_%s_margin")
+          frame = Utils::frame_to_array(specs, "plot_%s_margin")
+          
+          target = Utils::compose_margins(frame, legend)
+          a = target.to_frame("legend_%s_margin")
+        else
+          warn "Legend position #{@object.layout_preferences.legend_position.inspect} not implemented for FixedLayout"
+          a = {}
+        end
+        return specs.merge(a)
+      else
+        return specs
+      end
+    end
+
+  end
+
+  # A layout that will handle objects aligned on a grid. All objects
+  # belonging to one row of the grid will share the same vertical padding.
+  # All the ones belonging to a column will share the same
+  # horizontal padding. All layouts added to this one should
+  # be a GridItemLayout or a descendant, or at least something
+  # behaving correctly in that respect.
+  class GridLayout < SimpleLayout
+
+    def initialize(*a)
+      super
+      # We don't want the children's extensions messing
+      # with this layout's extension
+      @ignore_children_extensions = true
+    end
+
+    # Some various 'accessors' for rows and columns:
+
+    # Sets the number of rows. The number of columns will be computed
+    # automatically.
+    def rows=(nb)
+      @rows = nb
+      @columns = false
+    end
+
+    # Returns the number of rows
+    def rows
+      return @rows if @rows
+      return (@child_layouts.size.to_f / @columns).ceil
+    end
+
+    # Sets the number of columns. The number of rows will be computed
+    # automatically.
+    def columns=(nb)
+      @columns = nb
+      @rows = false
+    end
+
+    # Returns the number of rows
+    def columns
+      return @columns if @columns
+      return (@child_layouts.size.to_f / @rows).ceil
+    end
+
+    # Returns the position of the given child layout in terms of
+    # [row, col]. The layouts are added first in columns
+    def child_position(child)
+      i = @child_layouts.index(child)
+      return [i % rows, i / rows]
+    end
+
+    # Returns the child at position (row, col)
+    def child(row, col)
+      return @child_layouts[col * rows + row ]
+    end
+    
+    # Computes the various extensions for each columns and row
+    def compute_extensions(t)
+      @rows_extensions = []
+      rows.times do |i|
+        a = [0,0,0,0]
+        columns.times do |j|
+          update_extensions(a, child(i,j).extension(t)) if child(i,j)
+        end
+        @rows_extensions[i] = a
+      end
+      debug "Grid layout rows #{@rows_extensions.inspect}"
+      @columns_extensions = []
+      columns.times do |j|
+        a = [0,0,0,0]
+        columns.times do |i|
+          update_extensions(a, child(i,j).extension(t)) if child(i,j)
+        end
+        @columns_extensions[j] = a
+      end
+      debug "Grid layout columns #{@columns_extensions.inspect}"
+    end
+
+    # Computes the positions of the various columns/rows, so that
+    # all the objects in the same line/column share the same size
+    # in both directions -- that is, all plots are identical.
+    def compute_positions(t)
+      compute_extensions(t) unless @rows_extensions
+      frame = @object.outer_frame(t)
+      @rows_positions = []
+      vert_ext = 0
+      vert_top = []
+      vert_bottom = []
+      for f in @rows_extensions
+        a = Dimension.absolute_to_relative(f,frame)
+        vert_top << a[2]
+        vert_bottom << a[3]
+        vert_ext += a[2] + a[3]
+      end
+
+      # Now, vert_top and vert_bottom contain the necessary
+      # spacing above and below each element, in relative size.
+      height = (1.0 - vert_ext)/rows
+      debug "Grid layout height #{height}"
+      current = 0
+      rows.times do |i|
+        new = current + vert_top[i] + height + vert_bottom[i]
+        @rows_positions << [0,0, # ignored
+                            current, 1 - new]
+        current  = new
+      end
+
+      debug "Grid layout rows positions #{@rows_positions.inspect}"
+
+      # Now, rows_positions contains the vertical position of
+      # the given row.
+
+      # We can now do the same for the horizontal positions:
+      @columns_positions = []
+      horiz_ext = 0
+      horiz_left = []
+      horiz_right = []
+      for f in @columns_extensions
+        a = Dimension.absolute_to_relative(f,frame)
+        horiz_left << a[0]
+        horiz_right << a[1]
+        horiz_ext += a[0] + a[1]
+      end
+      debug "Grid horiz left #{ horiz_left.inspect }"
+      debug "Grid horiz right #{horiz_right.inspect}"
+
+      # Now, horiz_left and horiz_right contain the necessary
+      # spacing above and below each element, in relative size.
+      width = (1.0 - horiz_ext)/columns
+      debug "Grid layout width #{width}"
+      current = 0
+      columns.times do |i|
+        new = current + horiz_left[i] + width + horiz_right[i]
+        @columns_positions << [current, 1 - new, 0, 0]
+        current =  new
+      end
+      debug "Grid layout columns positions #{@columns_positions.inspect}"
+      
+    end
+
+    # Returns the extension for the given child.
+    def child_extension(child,t)
+      compute_extensions(t) unless @columns_extensions
+      row,col = child_position(child)
+      a = @rows_extensions[row].dup
+      # We override the horizontal extensions with the
+      # @columns_extensions
+      a[0] = @columns_extensions[col][0]
+      a[1] = @columns_extensions[col][1]
+      return a
+    end
+
+    # Returns the frame allocated for one item of the layout.
+    def child_frame(t, row,col = nil)
+      if row.is_a? Layout       # Row is a child, actually...
+        return child_frame(t, *child_position(row))
+      end
+
+      compute_positions(t) unless @rows_positions
+      a = @rows_positions[row].dup
+      a[0] = @columns_positions[col][0]
+      a[1] = @columns_positions[col][1]
+      return a
+    end
+
+    
+  end
+
+  # The layout that should be used for every single object
+  # in a grid. Should.
+  class GridItemLayout < SimpleLayout
+
+    # Returns the object's frame.
+    def legend_specs(t = nil)
+      # To compute the legend specification, 
+      a = parent.child_extension(self, t)
+
+      frames = @object.outer_frame(t)
+      padding = Dimension.absolute_to_relative(a, frames)
+
+      padding_prefs = @object.layout_preferences.
+        padding_relative_values(frames)
+
+      update_extensions(padding, padding_prefs)
+      my_frame = parent.child_frame(t, self)
+      
+      debug "Child frame #{my_frame.inspect}"
+      debug "Child padding #{padding.inspect}"
+      debug "Child padding prefs #{padding_prefs.inspect}"
+      
+      specs = {}
+      i = 0
+      for s in %w(left right top bottom)
+        specs["plot_#{s}_margin"] = padding[i] + my_frame[i]
+        i += 1
+      end
+      debug "Child specs #{specs.inspect}"
+      return specs
+    end
+  end
+
+end