PHOTO_QUERY_FILE Function

Reference Guide > P Routines > PHOTO_QUERY_FILE Function

Reads the file header of the specified image file and if successful it returns the file type of the file.

note	The PHOTO routines are only available on 64-bit PV-WAVE.

Usage

status = PHOTO_QUERY_FILE(filename[, filetype])

Input Parameters

filename — On input, a string containing the path and file name to query. System variables/logicals and special characters recognized by the operating system shell can be used in the path. If you use a wildcard and it matches more than one valid file and invalid filename error is returned.

Output Parameters

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 an error reading the file or a bad file type if Readable was used.

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 PHOTO_READ Function.

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

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

2. If no encoded ID number is detected, return the image type corresponding to the type specified by the Default_Filetype keyword.

3. If no encoded ID number is detected and the Default_Filetype keyword is not present, the function tries to match the filename suffix to a list of standard suffixes for supported image file types.

4. If the image type cannot be determined by the above rules, the function returns an error.

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 = PHOTO_QUERY_FILE( $

   !Dir + '/demo/gallery3/data/veggies.jpg', filetype)

PRINT, status, ' ', filetype

; PV-WAVE prints: 0 JPEG

status = PHOTO_QUERY_FILE( $

   !Dir + '/demo/gallery3/data/veggies.jpg', $

   Default_Filetype='tif')

PRINT, status, ' ', filetype

; PV-WAVE prints: 0 JPEG

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 = PHOTO_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 PHOTO_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, PHOTO_QUERY_FILE

; looks at the value of Default_Filetype keyword, which in this

; case was incorrect.

imagefile = !Data_Dir + '/usa_map.tga'

status = PHOTO_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 = PHOTO_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 = PHOTO_QUERY_FILE(imagefile, filetype)

PRINT, status

; PV-WAVE prints: -3