coyote: CGSNAPSHOT

Description
To get accurate screen dumps with the IDL command TVRD on 24-bit
PC and Macintosh computers, you have to be sure to set color
decomposition on. This program adds that capability automatically.
In addition, the program will optionally write BMP, GIF, JPEG,
PICT, PNG, and TIFF color image files of the screen dump.
Categories
Graphics
Returns
The returned image will be a 2D image on 8-bit systems and a 24-bit pixel 
interleaved true-color image on 24-bit systems. A -1 will be returned if a 
file output keyword is used (e.g., JPEG, TIFF, etc.).
Params
xstart: in, optional, type=integer, default=0
   The starting column index of the rectantular area that is to be copied.
ystart: in, optional, type=integer, default=0
   The starting row index of the rectantular area that is to be copied.
ncols: in, optional, type=integer
   The number of columns to read in the rectantular area that is to be 
   copied. By default, !D.X_Size - xstart.
nrows: in, optional, type=integer
   The number of rows to read in the rectantular area that is to be 
   copied. By default, !D.Y_Size - ystart.
Keywords
bmp: in, optional, type=boolean, default=0
    Set this keyword to write the screen dump as a color BMP file.
cancel: out, optional, type=boolean, default=0
    An output keyword set to 1 if the user cancels out of a filename dialog. 
    Set to 0 otherwise.
colors: in, optional, type=integer, default=256
    If a 24-bit image has to be quantized, this will set the number of colors in 
    the output image. Applies to BMP, GIF, PICT, and PNG formats written from 
    24-bit displays.(See the COLOR_QUAN documentation for details.)
cube: in, optional, type=integer
    If this keyword is set to a value between 2 and 6 the color quantization will 
    use a cubic method of quantization. Applies to BMP, GIF, PICT, and PNG formats 
    written from 24-bit displays.(See the COLOR_QUAN documentation for details.)
dither: in, optional, type=boolean, default=0 
    If this keyword is set the quantized image will be dithered. Applies to BMP, 
    GIF, PICT, and PNG formats written from 24-bit displays.(See the COLOR_QUAN 
    documentation for details.)
filename: in, optional, type=string
    The name of the output file. If you specify a name with a file extension of the
    type of file you want to create (e.g., *.jpg, *.png, etc), then you do not have
    to use the file type keywords (e.g., JPEG, PNG, etc.). Otherwise, you can specify
    the name of the the file without an extension, use the file keywords, and a file
    extension will be added to the filename automatically, depending upon the type of
    output file selected.
gif: in, optional, type=boolean, default=0
    Set this keyword to write the screen dump as a color GIF file.
jp2: in, optional, type=boolean, default=0
    Set this keyword to write a color JPEG2000 file.
jpeg: in, optional, type=boolean, default=0
    Set this keyword to write the screen dump as a color JPEG file.
nodialog: in, optional, type=boolean, default=0        
    Set this keyword if you wish to avoid the DIALOG_PICKFILE dialog that asks you 
    to name the output file. This keyword should be set, for example, if you are 
    processing screens in batch mode.
order: in, optional, type=boolean, default=0
    Set this keyword to determine the image order for reading the display. Corresponds to 
    !Order and set to such as the default.
overwrite_prompt: in, optional, type=boolean, default=0       
    Set this keyword if you would like to get a prompt if you are overwriting a file. 
    This applies only to operations involving DIALOG_PICKFILE.
pict: in, optional, type=boolean, default=0
    Set this keyword to write the screen dump as a color PICT file.
png: in, optional, type=boolean, default=0
    Set this keyword to write the screen dump as a color PNG file.
position: in, optional, type=float
    An alternative way of setting the `xstart`, `ystart`, `ncols` and `nrows` parameters
    by specifying a four-element normalized array, [x0,y0,x1,y1].
tiff: in, optional, type=boolean, default=0
    Set this keyword to write the screen dump as a color TIFF file.
true: in, optional, type=integer, default=1
    Set this keyword to the type of interleaving you want. 1 = Pixel interleaved, 
    2 = row interleaved, 3 = band interleaved.
type: in, optional, type=string
    Set this keyword to the type of file to write. Use this instead of
    setting BMP, GIF, JPEG, PICT, PNG, or TIFF keywords: TYPE='JPEG'. The
    primary purpose of this is to make widget event handlers easier to write.
quality: in, optional, type=integer, default=75
    This keyword sets the amount of compression for JPEG images. It should be set to a 
    value between 0 and 100. (See the WRITE_JPEG documentation for details.)
wid: in, optional, type=integer
    The index number of the window to read from. The current graphics window
    (!D.Window) is selected by default. An error is issued if no windows are
     currently open on a device that supports windows.
_ref_extra: in, optional
    Any keywords that are appropriate for the WRITE_*** routines are also accepted via 
    keyword inheritance.
Examples
To obtain an image of the current graphics window::
   IDL> image = cgSnapshot()
To create a PNG file, named "test.png", of the current graphics window::
   IDL> void = cgSnapshot(FILENAME='test.png')
To obtain the lower quadrant of a 512-by-512 graphics window as a
band interleaved image::
   IDL> image = cgSnapshot(0, 0, 256, 256, TRUE=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::
   Renamed TVRead to cgSnapshot and retired TVRead. 20 February 2011. DWF.
   Added the ability to get the file type from the file name extension. 26 Dec 2011. DWF.
   Added a POSITION keyword to select a position inside the window for capture. 20 October 2012. DWF.
   Fixed a problem with not setting back to incoming decomposed state on an error. 20 Nov 2012. DWF.
   Added ability to write JPEG2000 files. 7 February 2014. DWF.
Copyright
Copyright (c) 2011-2014, Fanning Software Consulting, Inc.