coyote: CGLAYOUT

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.