coyote: CGASPECT

Description
The purpose of this function is to calculate a position in a graphics window with
a specified aspect ratio (ysize/xsize).
Categories
Utility
Params
aspect_ratio: in, required, type=float
     The requested aspect ratio. Be careful to specify this as a float.
Keywords
align: in, optional, type=string, default='center'
     Normally, the output position is centered in the intial input position. This
     keyword can alter the placement of the final position with respect to the initial
     position. Allowed values are "top", "right", "bottom", "left", and "center".
aspect: in, optional, type=array
     This keyword provides an alternative way of specifying the `aspect_rato` value. Pass
     this keyword any 2D array, and the aspect ratio will be calculated to match the 2D array.
position: in, optional, type=array
     Use this keyword to specify a four-element normalized starting position for calculating
     the final position in the graphics window. By default, the staring position is given 
     by [0.0, 0.0, 1.0, 1.0] (the entire window). If the `Single_Plot` keyword is set, the
     default position is given by [0.125, 0.125, 0.9, 0.9].
single_plot: in, optional, type=boolean, default=0
     Set this keyword to change the default starting `Position` to [0.125, 0.125, 0.9, 0.9].
waspect: in, optional, type=float
     Set this keyword to the window aspect ratio. If not used, the window aspect is calculated from
     the current graphics window as Float(!D.Y_VSize) / !D.X_VSize.
Examples
Here is how to use this program to display two differently sized images aligned at their tops::
    img1 = cgDemoData(7)
    img2 = congrid(img1, 360, 180)
    cgDisplay, 900, 450
    pos = cgLayout([2,1], OYMargin=[4, 11], OXMargin=[5, 8], XGap=6)
    pos1 = pos[*,0]
    img1pos = cgAspect(Position=pos1, Aspect=img1, Align='top')
    cgImage, img1, CTIndex=3, /AXES, POSITION=img1pos, OPOSITION=op
    cgColorbar, CTIndex=3, /Fit    
    pos2 = pos[*,1]
    img2pos = cgAspect(Position=pos2, Aspect=img2, Align='top')
    cgImage, img2, /AXES, POSITION=img2pos, CTIndex=2, /NoErase
    cgColorbar, CTIndex=2, /Fit  
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, 12 February 2013 by David W. Fanning.
Copyright
Copyright (c) 2013, Fanning Software Consulting, Inc.