# coyote: CGSURFACE

- coyote/Graphics
- [Source code]

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.