GETIMAGE 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.
Restrictions
Requires the following Coyote Library files:
CENTER_TLB
ERROR_MESSAGE
FSC_FIELD
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.
Now dependent on FSC_FIELD, ERROR_MESSAGE, and CENTER_TLB from Coyote Library.
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.