Coyote Graphics Routines

Date: Fri Mar 27 12:14:20 2015

single page | use frames     summary     class     fields     routine details     file attributes

.\

cgsnapshot.pro


top cgSnapshot

Graphics

result = cgSnapshot( [xstart] [, ystart] [, ncols] [, nrows] [, /BMP] [, /Cancel] [, Colors=integer] [, Cube=integer] [, /Dither] [, Filename=string] [, /GIF] [, /JP2] [, /JPEG] [, /NoDialog] [, /Order] [, /Overwrite_Prompt] [, /PICT] [, /PNG] [, POSITION=float] [, /TIFF] [, True=integer] [, Type=string] [, Quality=integer] [, WID=integer] [, _Ref_Extra=_Ref_Extra])

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.

Return value

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

Parameters

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 information

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

Copyright:

Copyright (c) 2011-2014, Fanning Software Consulting, Inc.

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.

File attributes

Modification date: Fri Mar 27 11:07:38 2015
Lines: 455
Docformat: rst rst