IMAGE_QUERY_FILE Function

Returns the image type in a specified image file.

Tip: If you have 64-bit PV‑WAVE and need to read and write images up to 32-bits without constraints on data size, use the PHOTO OPI routines.

Usage

status = IMAGE_QUERY_FILE(filename[, filetype])

Input Parameters

filename—On input, a string containing the name of the file to query. System variables/logicals and special characters recognized by the operating system shell can be used in the path.

filetype—(optional) On output, a string containing the type of image in the file.

Keywords

Default_Filetype—A string specifying a supported file type. This keyword is interpreted according to the rules listed in the Discussion section.

Quiet—Suppresses successive levels of error messages, depending on the set value. This keyword accepts the same integer values used with the system variable !Quiet.

Readable—If set, checks the file type of the image against the list of supported readable file types.

Returned Value

status—A value indicating the success or failure of the function.

< 0—Indicates that the file does not contain a supported image type.
0—Indicates that the file does contain a supported image type.

Discussion

For a list of supported image types, refer to the Discussion section of the IMAGE_READ function.

This function returns an image file type according to the following rules of precedence:

If an encoded ID number can be extracted from the file header, and the number matches that of one of the supported image types, return that image type.
If no encoded ID number is detected, return the image type corresponding to the type specified by the Default_Filetype keyword.
If no encoded ID number is detected and the Default_Filetype keyword is not present, try to determine the image type from the filename suffix. The function tries to match the suffix to a list of standard suffixes for supported image file types.
If the image type cannot be determined by the above rules, the function returns an error status.

Example 1

In these two code examples, the correct image type is obtained from the encoded ID number in the file header.

; Image file is a JPG file. Correct image type is obtained from 
; the encoded ID number, which takes precedence over specified 
; filename extension. 
status = IMAGE_QUERY_FILE( $
   !Dir + '/demo/gallery3/data/veggies.jpg', filetype)
PRINT, status, ' ', filetype 
; PV-WAVE prints: 0 JPEG 
status = IMAGE_QUERY_FILE( $
   !Dir + '/demo/gallery3/data/veggies.jpg', $
   Default_Filetype='tif')
PRINT, status, ' ', filetype
; PV-WAVE prints: 0 JPEG

Image file is a PCX file. Correct image type is obtained from the encoded ID number, which takes precedence over both the filename suffix and the Default_Filetype keyword.

Example 2

In this example, the correct filetype for a TGA (Truevision Targa) file is obtained using the Default_Filetype keyword. If the Default_Filetype keyword were not specified, an incorrect image type would have been returned. This is because TGA graphics files don’t contain an encoded ID number (see also Example 3).

status = IMAGE_QUERY_FILE( $
   !Dir + '/demo/gallery3/data/newmexico24.tga', $
   filetype, Default_Filetype='tga')
PRINT, status, ' ', filetype 
; PV-WAVE prints: 0 TGA

Example 3

The following three code examples show how an incorrect file type or an error can be returned for TGA (Truevision Targa) files because they don't contain an encoded ID number. The lack of an encoded ID number results in ambiguity when identifying the file type using the IMAGE_QUERY_FILE function. (Example 2 shows how the correct file type can be returned for a TGA file.)

; Note that the wrong image type, TIFF, was returned. Without an
; encoded ID number in the graphics file, IMAGE_QUERY_FILE 
; looks at the value of Default_Filetype keyword, which in this 
; case was incorrect. 
imagefile = !Data_Dir + '/usa_map.tga'
status = IMAGE_QUERY_FILE(imagefile, $
   filetype, Default_Filetype='tif')
PRINT, status, ' ', filetype
; PV-WAVE prints: 0 TIF 
; Here, once again the incorrect image type is returned for
; a TGA file; since no encoded ID number was found, and 
; no Default_Filetype keyword is specified, function "guesses" 
; the image type by looking at the filename suffix. 
imagefile = !Data_Dir + '/usa_map.tga.txt'
status = IMAGE_QUERY_FILE(imagefile, filetype)
PRINT, status, ' ', filetype 
; PV-WAVE prints: 0 TXT 
; Example code also returns an error status. The error results
; because function can't make a reasonable guess at the image type
; without the following: an encoded ID number, Default_Filetype 
; keyword, and/or a filename suffix. 
imagefile = !Data_Dir + 'usa_map_tga'
status = IMAGE_QUERY_FILE(imagefile, filetype)
PRINT, status
; PV-WAVE prints: -3