coyote: CGSURFACE

Description
The purpose of cgSurface is to create a window where a surface is displayed. Surfaces
can be wire-framed, shaded surfaces, and surfaces with texture maps draped on top of
them, among other types of surfaces. LEFT mouse button rotates the surface, MIDDLE
mouse button zooms out from the surface, RIGHT mouse button zoom into the surface. 
Clicking on the surface axes will allow the user to move or translate the surface, and 
clicking on the plot title will allow the user to move the title.
.. image:: cgsurface.png
Categories
Graphics
Examples
Use as you would use the IDL SURFACE of SHADE_SURF command::
   data = Dist(200)
   LoadCT, 33
   cgSurface, data
   cgSurface, data, /Elevation_Shading
   cgSurface, data, /Shaded
   cgSurface, data, /Shaded, Texture_Image=cgDemoData(16) 
   Setting up the initial surface rotation.
   IDL> T3D, /RESET, ROTATE=[0, 0, 30]
   IDL> T3D, ROTATE=[-90, 0, 0]
   IDL> T3D, ROTATE=[0, 30, 0]
   IDL> T3D, ROTATE=[30, 0, 0]
   IDL> cgSurface, cgDemoData(2), Transform=!P.T
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::
   Completely re-written, 26 November 2010 from old cgSURFACE program. DWF.
   Added ability to translate the surface by clicking on an axis. 28 Nov 2010. DWF.
   Fixed a problem with light controls in which the light controls didn't show the
       current light color. 28 Nov 2010. DWF.
   I was ANDing [XYZ]Style keywords with 8 instead of 4 for hidded axes. Fixed. 4 Jan 2011. DWF.
   Added Axes ON/OFF button. 4 Jan 2011. DWF.
   Rotation is throwing underflow warnings, so switched to code that surpress 
       these warnings. 26 Aug 2011. DWF
   Added TRANSFORM keyword to allow the initial surface to be rotated to user 
       specifications. 26 Sept 2011. DWF.
   Changed FSC_Normalize to cgNormalize to reflect new name. 6 Feb 2013. DWF.
   Axes titles are now changing size with the CHARSIZE keyword, as they are supposed to. 4 Nov 2013. DWF.
   Fixed a problem with the Light Controller when trying to set a color. 21 Mar 2014. DWF.
   Added checks to make sure the surface ranges are not zero. 8 March 2014. DWF.
Copyright
Copyright (c) 2010-2014, Fanning Software Consulting, Inc.
ntrols light intensity by handling selection events from the Intensity Value widget.
Params
data: in, required, type=any
     A two-dimensional array of data to be displayed.
x: in, optional, type=any
     A vector or two-dimensional array specifying the X coordinates of the
     surface grid.
y: in, optional, type=any
     A vector or two-dimensional array specifying the Y coordinates of the
     surface grid.
Keywords
axiscolor: in, optional, type=string, default='black'
   The name of the axis color. By default, 'black'..
background: in, optional, type=string, default='white'
   The name of the background color. By default, 'white'.
block: in, optional, type=boolean, default=0
    Set this keyword to make the program a blocking widget program.
bottom: in, optional, type=string, default=COLOR
   The name of the bottom color. By default, same as COLOR.
brewer: in, optional, type=boolean, default=0
   Set this keyword to indicate that the colortable (CTABLE) is
   to use Brewer color tables rather than IDL standard color tables.
charsize: in, optional, type=float, default=1.0
   The character size of the surface annotation. This value is multiplied
   times a 12 point character size.
color: in, optional, type=string, default='blu6'
   The name of the data color. 
constrain_aspect: in, optional, type=boolean, default=0
   Set this keyword to maintain the aspect ratio of the Y size
   of the data to the Y size of the data. The default is to let the
   sizes conform to a unit square.
ctable: in, optional, type=integer
   The color table to use with the surface. The default is to use the
   current color table.
elevation_shading: in, optional, type=boolean, default=0
   Set this keyword to put elevation shading into effect for the surface.
font: in, optional, type=string, default="Helvetica"
   The name of the true-type font desired for axis annotation and the plot title. 
   If undefined, the default is "Helvetica".
hidden_lines: in, optional, type=boolean, default=1
   Set this keyword to turn hidden line removal on for the surface. Turned 
   ON by default.
group_leader: in, optional, type=long
    Set this keyword to the identifier of a widget that will serve as the
    group leader for this widget program. When the group leader dies, this
    program will die, too.
palette: in, optional, type=byte
   A 3x256 byte array (or 256x3) representing the colors for elevation shading. An alternative
   way of specifying the color table, instead of using the `CTable` keyword.
reverse: in, optional, type=boolean, default=0
   Set this keyword to reverse the color table set by CTABLE.
shaded: in, optional, type=boolean, default=0
   Set this keyword if you wish to display a shaded surface. The is the same as setting STYLE=2.
skirt: in, optional, type=any
    Set this keyword to a Z value where a skirt will be drawn for the surface.
style: in, optional, type=integer, default=1
    Sets the style of the surface::
        0 - Dot surface
        1 - Wire mesh (the default)
        2 - Shaded surface
        3 - Parallel X lines
        4 - Parallel Y line
        5 - Wire mesh lego style
        6 - Solid lego style
texture_image: in, optional, type=byte
    Set this keyword to a 2D or true-color image that will be overlaid on the surface
    as a texture map. If a 2D image is passed, the colortable specified with CTABLE will
    be used to construct a true-color image for the texture map.
tcharsize: in, optional, type=float
    The title character size. By default 1.25 times the `Charsize`.
tcolor: in, optional, type=string
    The name of the title color. By default, the same as `AxisColor`.
title: in, optional, type=string
   The title of the plot. It will be written "flat to the screen", rather than rotated.
transform: in, optional, type=4x4 double array
    A homogeneous transformation matrix to be applied to the initial surface. Such a 
    transformation matrix can be obtained, for example, with the T3D procedure.
vert_colors: in, optional, type=byte
    A vector of colors to be used to specify the color of a surface vertex. The vector
    may be of the form [n] where each entry is a color index, or of the form [3,n] where
    each 3-element row is an RGB color, or of the form [4,n] where each 4-element row
    is an RGBA color. To remove vertex colors after they have been set, set VERT_COLORS
    to a scalar. See the documentation for IDLgrSurface for additional details.
xoffset: in, optional, type=integer, default=50
    The number of pixels the surface window should be offset in the X direction
    from the upper-left corner of the display.
xrange: in, optional, type=float
    The X data range of the data. Normally, just chosen from the data itself.
xsize: in, optional, type=interger, default=640
    The X size of the initial surface window. By default, 640 pixels.
xstyle: in, hidden
    The normal XSTYLE keyword.
xtitle: in, optional, type=string
    The text for the X axis of the surface plot.
yoffset: in, optional, type=integer, default=25
    The number of pixels the surface window should be offset in the Y direction
    from the upper-left corner of the display.
yrange: in, optional, type=float
    The Y data range of the data. Normally, just chosen from the data itself.
ysize: in, optional, type=integer, default=512
    The Y size of the initial surface window. By default, 640 pixels.
ystyle: in, hidden
    The normal YSTYLE keyword.
ytitle: in, optional, type=string
    The text for the Y axis of the surface plot.
zrange: in, optional, type=float
    The Z data range of the data. Normally, just chosen from the data itself.
zscale: in, optional, type=float, default=1.0
     A number between 0.001 and 1.0 that will "scale" the Z axis height. Default is 1.0.
zstyle: in, hidden
    The normal ZSTYLE keyword.
ztitle: in, optional, type=string
    The text for the Z axis of the surface plot.
_extra: in, optional, type=any
   Any keyword appropriate for the IDLgrSurface object is allowed in the program.
Returns
A four-element POSITION array, giving the position in the window for
a plot with this aspect ratio.