# coyote: GETIMAGE

- coyote/Widget Programming
- coyote/FileIO
- [Source code]

NAME

      GETIMAGE

PURPOSE

      The purpose of this function is to allow the user to open either
      unformmated or XDR binary image files of up to eight dimensions.

CATEGORY

      Widgets, File I/O.

CALLING SEQUENCE

      image = GETIMAGE(filename)

OPTIONAL INPUTS

      filename: The name of the file to open for reading.

OPTIONAL KEYWORD PARAMETERS

      CANCEL: An output variable that can be set to a named variable.
      The value of the return variable will be 1 if the user clicked
      the "Cancel" button or if there was a problem reading the file.
      DATATYPE: The "type" of data you wish to read out of the file.
      The data type corresponds to the Size(image, /TYPE) value. Here
      are the types supported:
      BYTE                   1 (default)
      INTEGER                2
      LONG INTEGER           3
      FLOAT                  4
      DOUBLE                 5
      UNSIGNED INTEGER      12
      UNSIGNED LONG INTEGER 13
      64-bit LONG           14
      64-bit UNSIGNED LONG  15
      DIMENSIONS: A vector of image dimensions. The default value is [256, 256].
      DIRECTORY: The name of the directory the file is located in. By
      default the program looks in the "coyote" directory under the
      main IDL directory, if one exists. Otherwise, it defaults to the
      current directory.
      ENDIAN: Set this keyword to an integer that indicates the byte
      ordering of the data file. If you don't know what byte order means,
      or you don't know anything about the byte order of the data, or
      if you are sure the data was created on the same type of machine
      you are now running IDL on, then just accept the default of 0 or
      "native" ordering. If you are wrong, you will soon know it and you
      can set the keyword to another value on your next try. :-)
      If you know the machine was created on a big endian machine (such
      as a Sun or HP workstation), set this value to 1 (Big Endian). If e
      you are sur the image data was create on a little endian machine (such
      as a Windows PC or laptop running LINUX), set the value to 2 (Little Endian).
      HEADER: The size of any header information in the file in BYTES.
      Default is 0.
      HEADDATA: An optional output keyword that will contain the header
      information read from the file.
      PARENT: The group leader for this widget program. The PARENT is
      required if GETIMAGE is called from another widget program in order
      to make this program a MODAL widget program.
      XDR: Set this keyword if the binary file is of XDR type. The default
      type is "Unformatted".
      XOFFSET: This is the X offset of the program on the display. The
      program will be placed approximately in the middle of the display
      by default.
      YOFFSET: This is the Y offset of the program on the display. The
      program will be placed approximately in the middle of the display
      by default.

COMMON BLOCKS

      None.

SIDE EFFECTS

      A "CANCEL" operation is indicated by a 0 return value.
      Any error in reading the file results in a 0 return value.

EXAMPLE

      To load the image "galaxy.dat" in the $IDL/examples/data
      directory, type:
      image = GETIMAGE('galaxy.dat', DIRECTORY=!DIR + '/examples/data', $
         DIMENSIONS=[256,256], Cancel=cancelled, Parent=event.top)
      IF NOT cancelled THEN TV, image

MODIFICATION HISTORY

      Written by: David Fanning, 3 February 96.
      Fixed bug that prevented reading INTEGER data. 19 Dec 96.
      Modifed program for IDL 5 MODAL operation. 19 Oct 97.
      Added CANCEL keyword. 27 Oct 97. DWF.
      Fixed CANCLE keyword spelling. Sigh... 29 JUN 98. DWF.
      Added COYOTE_FIELD, improved appearance. 19 NOV 99. DWF.
      Updated with latest version of COYOTE_FIELD. 18 FEB 2000. DWF.
      Added CATCH keyword so the program will break when I want
      it to. :-) 18 MAR 2000. DWF.
      Added GROUP_LEADER keyword, which is synonymous with PARENT. 31 MAR 2000. DWF.
      Updated obsolete PICKFILE call to DIALOG_PICKFILE. 17 JAN 2001. DWF.
      Extensive update for IDL Programming Techniques, 3rd Edition. 1 November 2006. DWF.
         XSIZE, YSIZE, CATCH, and FRAMES keyword made obsolete.
         HEADDATA, ENDIAN, DATATYPE, DIMENSIONS keywords added.
      Added ability to parse fully qualified file names passed from Dialog_Pickfile. 30 Oct 2010. DWF.
      IF a file name is not passed into the program, it asks the user to select one now. 10 Jan 2011. DWF.
      Problem with SWAP_ENDIAN keywords fixed. 7 March 2011. DWF.