QUERY_* Routines

Query routines allow users to obtain information about an image file without having to read the file.

Return Values

All of the QUERY_* routines return a result, which is a long with the value of 1 if the query was successful (and the file type was correct) or 0 on failure. If the query was successful, the return argument will be an anonymous structure containing all of the available information for that image format.

The status is intended to be used to determine if it is appropriate to use the corresponding READ_ routine for a given file. The return status of the QUERY_* will indicate success if the corresponding READ_ routine is likely to be able to read the file. The return status will indicate failure for cases that contain formats that are not supported by the READ_ routines, even though the files may be valid outside of the IDL environment. For example, IDL's READ_BMP does not support 1-bit-deep images and so the QUERY_BMP function would return failure in the case of a monochrome BMP file.

The returned anonymous structure will have (minimally) the following fields for all file formats. If the file does not support multiple images in a single file, the NUM_IMAGES field will always be 1 and the IMAGE_INDEX field will always be 0. Individual routines document additional fields which are returned for a specific format.

Info Structures

All the routines accept the IMAGE_INDEX keyword although formats which do not support multiple images in a single file will ignore this keyword.

QUERY_TIFF-Specific Routine Info Structures

Field	IDL data type	Description
CHANNELS	Long	Number of samples per pixel
DIMENSIONS	2-D long array	Size of the image in pixels
HAS_PALETTE	Integer	True if a palette is present
NUM_IMAGES	Long	Number of images in the file
IMAGE_INDEX	Long	Image number for which this structure is valid
PIXEL_TYPE	Integer	IDL basic type code for a pixel sample
TYPE	String	String identifying the file format


Field	IDL data type	Description
BITS_PER_SAMPLE	Long	Number of bits per channel. Possible values are 1, 4, 8, 16, or 32.
DESCRIPTION	String	The contents of the TIFF ImageDescription tag, or a null string of undefined.
DOCUMENT_NAME	String	The contents of the TIFF DocumentName tag, or a null string if undefined.
DATE_TIME	String	The contents of the TIFF DateTime tag, or a null string if undefined.
ORIENTATION	Long	Image orientation (columns, rows): 1 = Left to right, top to bottom (default) 2 = Right to left, top to bottom 3 = Right to left, bottom to top 4 = Left to right, bottom to top 5 = Top to bottom, left to right 6 = Top to bottom, right to left 7 = Bottom to top, right to left 8 = Bottom to top, left to right
PLANAR_CONFIG	Long	How the components of each pixel are stored. Possible values are: 1 = Pixel interleaved RGB image or a two-dimensional image (no interleaving exists). Pixel components (such as RGB) are stored contiguously. 2 = Image interleaved. Pixel components are stored in separate planes.
POSITION	Float array	Two-element vector [X position, Y position] containing the X and Y offsets in the same units as reported in the UNITS field. The X position is relative to the left side of the image. The Y position is relative to the top of the image, with positive Y increasing downwards. If the XPosition or YPosition tag is not defined in the file then a value of 0.0 is returned for that element.
PHOTOMETRIC	Long	Color mode used for the image data. Possible values are: 0 = White is zero 1 = Black is zero 2 = RGB color model 3 = Palette color model 4 = Transparency mask 5 = Separated (usually CMYK)
RESOLUTION	Float array	Two-element vector [X resolution, Y resolution] containing the number of pixels per unit (as reported in the UNITS field).
UNITS	Long	Units of measurement for RESOLUTION: 1 = No units 2 = Inches (the default) 3 = Centimeters For example, if the UNITS field contains the value 2, then the values in the RESOLUTION field represent pixels per inch.
TILE_SIZE	Long array	Two-element vector [Tile width, Tile height]. Non-tiled images will contain [Image width, 1]