# coyote: CGSNAPSHOT

- coyote/Graphics
- [Source code]

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.