# coyote: CGLAYOUT

- coyote/Graphics
- coyote/Utilities
- [Source code]

Description

      The purpose of this program is to return the normalized position coordinates for
      a line plot, contour plot, or image plot with a specific "layout" in the current
      graphics window. A "layout" has a specified grid of columns and rows organized
      inside a graphics display window. This is similar to the positions calculated by
      !P.Multi, although a great deal more flexible. Of course, with additional flexibility
      and power comes more responsibility. You will be required to use the NoErase keyword
      correctly and you will be responsible for setting the character size on your plots.
      These jobs are normally handled by !P.Multi. Some users will find this liberating, some
      will find it a pain in the keister. There is always !P.Multi to go back to.
      A grid position is a combination of the number of columns and rows desired, plus
      the application of inside and outside margins, as well as a desired aspect ratio.
      Margins are specified in units of one-third the !D.X_PX_CM value to be device independent.
      The outside margins locate the grid inside the graphics display window.
      (These are equivalent to !X.OMargin and !Y.OMargin system variable when displaying
      a grid with !P.Multi, for example.) Inside margins use the same units, but are
      used to modify the initial grid positions in the window. (These are equivalent
      to using the XMargin and YMargin keywords on a plot command.) For example, inside margins
      might be used to leave room inside a larger position for color bars or other annotations
      you wish to put on a graphics display. The aspect ratio modifies the grid position
      after the outside and inside margins have been applied to create the final grid position,
      which will be centered in its initial grid position.

Categories

      Graphics, Utilities

Returns

      This function returns the normalized position coordinates for a particular
      location in a grid of locations (if the layout parameter is a three-element array),
      or a 4-by-(ncols*nrows) array of grid positions with one position for each location
      in the ncols by nrows grid of locations (if the layout parameter is a two-element array).
      The return variable is suitable for passing to the POSITION keyword of an IDL graphics
      command (e.g., cgPlot, cgContour, cgImage, etc.). The grid positions are organized in
      row order, starting with the grid location in the upper-left of the graphihcs display window.

Params

      layout: in, required, type=integer
           This parameter sets up the grid layout for the current graphics window. A grid
           is organized by columns and rows, with the first grid position located in the upper-left
           corner of the current graphics display window and proceeding in row order. This parameter
           is either a two-element vector, giving the number of columns and number of rows,
           respectively (e.g., [ncols,nrows]), or it is a three-element vector, giving, in addition, the
           specific grid location for which a position is required (e.g, [ncols, nrows, gridPosition]).
           Grid positions start at 1 with the first grid in the upper left corner of the graphics display
           window and proceed in row order, sequentually, until the last grid position, which is equal
           to the number of columns times the number of rows.

Keywords

      aspect: in, optional, type=float
           This kewyord allows you to specify a specific aspect ratio for the return
           positions. The aspect ratio is calculated as YDimension/XDimension. So, for
           example, if you wish the positions to be twice as wide as they are high, you
           would set the Aspect keyword to 1.0/2.0 or 0.5. If you wish your positions to
           have a square aspect ratio, you would set the Aspect keyword to 1.0.
      ixmargin: in, optional, type=integer
           This keyword is a two-element vector that sets the right and left, respectively, inside
           X margin for the grid position. Units are multiples of !D.X_CH_SIZE. Default = [0,0].
      iymargin: in, optional, type=integer
           This keyword is a two-element vector that sets the bottom and top, respectively, inside
           Y margin for the grid position. Units are multiples of !D.Y_CH_SIZE. Default = [0,0].
      oxmargin: in, optional, type=integer
           This keyword is a two-element vector that sets the right and left, respectively, inside
           X margin for the grid position. The default OXMargins are suitable for displaying line
           plots. If you are displaying image plots, you may wish to make the OXMargins the same on
           both sides of the graphics display window (e.g, OXMargin=[5,5]). Units are multiples of
           !D.X_CH_SIZE. Default = [10,4].
      oymargin: in, optional, type=integer
           This keyword is a two-element vector that sets the bottom and top, respectively, inside
           Y margin for the grid position. The default OYMargins are suitable for displaying line
           plots. There is a little additional room at the top of the plot in the defaults for adding
           a title to a multiple plot set-up. Units are multiples of !D.Y_CH_SIZE. Default = [6,8].
      unit: in, optional, type=float
            The most difficult part of calculating a layout in a device-indepentent manner is
            coming up with a "unit" of measurement that makes sense. The current default unit is
            !D.X_PX_CM / 4.0. This gives respectable results for "normal" sized windows and a
            "normal" number of multiplots. It may not work for you. If not, feel free to set your
            own unit here. The margin and gap keywords are multiplied by this value before the
            layout is calculated.
      xgap: in, optional, type=integer, default=14
           This keywords sets the distance between plots in the X dimension. Units are multiples
           of !D.X_CH_SIZE.
      ygap: in, optional, type=integer, default=8
           This keywords sets the distance between plots in the Y dimension. Units are multiples
           of !D.Y_CH_SIZE.

Examples

      Here is how to use this program to display line plots::
          cgDisplay, WID=0
          pos = cgLayout([2,2])
          FOR j=0,3 DO BEGIN
            cgPlot, cgDemoData(17), NoErase=j NE 0, Position=pos[*,j], Title='Plot ' + StrTrim(j+1,2)
          ENDFOR
          cgText, 0.5, 0.925, /Normal, 'Example Plot Layout', Alignment=0.5, Charsize=cgDefCharsize()*1.25
      Here is how to use this program to display contour plots or images with colorbars::
          cgDisplay, WID=1
          cgLoadCT, 22, /Brewer, /Reverse
          pos = cgLayout([2,2], OXMargin=[5,5], OYMargin=[5,12], XGap=3, YGap=10)
          FOR j=0,3 DO BEGIN
            p = pos[*,j]
            cgImage, cgDemoData(18), NoErase=j NE 0, Position=p
            cgColorBar, position=[p[0], p[3]+0.05, p[2], p[3]+0.1]
          ENDFOR
          cgText, 0.5, 0.925, /Normal, 'Example Image Layout', Alignment=0.5, Charsize=cgDefCharsize()*1.25
      .. image:: cglayout.png
      Here is how to display square plots in a PostScript file::
          cgPS_Open, 'cglayout_example.ps'
          cgDisplay
          pos = cgLayout([2,2], Aspect=1.0)
          FOR j=0,3 DO BEGIN
            cgPlot, cgDemoData(17), NoErase=j NE 0, Position=pos[*,j], Title='Plot ' + StrTrim(j+1,2)
          ENDFOR
          cgText, 0.5, 0.925, /Normal, 'Example Plot Layout', Alignment=0.5, Charsize=cgDefCharsize()*1.25
          cgPS_Close
      Here is how to draw the third plot in a 3 column by 2 row layout::
          cgDisplay, 800, 600, WID=3
          cgPlot, cgDemoData(17), Position=cgLayout([3,2,3])

Author

      FANNING SOFTWARE CONSULTING::
         David W. Fanning
         1645 Sheely Drive
         Fort Collins, CO 80526 USA
         Phone: 970-221-0438
         E-mail: david@idlcoyote.com
         Coyote's Guide to IDL Programming: http://www.idlcoyote.com

History

      Change History::
         Written, 19 December 2012 by David W. Fanning, from suggestions from Matthew Argall.
         Changed the notion of one "unit" from the values of !D.X_CH_SIZE and !D.Y_CH_SIZE to
             1/3 of the value of !D.X_PX_CM. This gives me more consistent measurements on the
             display and in a PostScript file. 12 Feb 2013. DWF.
         Modified the default unit to be !D.X_PX_CM/4.0 and added a UNIT keyword so users can
             choose a value that makes senses for their layouts. 25 Nov 2014. DWF.
         Added checks to be sure margin keywords contain two elements. 15 Dec 2014. DWF.

Copyright

      Copyright (c) 2012-2014, Fanning Software Consulting, Inc.