CGSNAPSHOT

CGSNAPSHOT
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.

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.
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.
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.