QUERY_* Routines
Query routines allow users to obtain information about an image or ASCII file without having to read the file. The following QUERY_* routines are available in IDL:
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 is an anonymous structure containing all of the available information for that 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.
For image formats, the returned anonymous structure has (minimally) the following fields. 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.
The QUERY_ASCII routine has its own return structure; for more information, see its documentation.
General Query * 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
|
SBIT_VALUES |
Byte array |
The values
[red, green, blue, gray, alpha] of the original image, if they were set.
0 = Grayscale - the sBIT chunk contains a single byte
2 = True Color- the SBIT chunk contains three bytes for the red, green and blue channels
3 = Indexed Color- the sBIT chunk contains three bytes for the red, green and blue palette entries
4 = Grayscale with Alpha Channel - the sBIT chunk contains two bytes, for the source grayscale data and source alpha data
6 = True Color with Alpha Channel - the sBIT chunk contains four bytes, for the red, green, blue and alpha channels
|
TYPE |
String |
String identifying the file format
|
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_PNG-Specific Routine Info Structures
Field |
IDL data type |
Description |
BACKGROUND |
Byte, Byte array, UInt, or UInt array
|
Background color, if specified in the bKGD chunk.
If the image has a palette, then this will be the Byte index into the palette.
If the image is grayscale or grayscale/alpha, then this will be a Byte or UInt gray value.
If the image is RGB or RGBA, then this will be a 3-element RGB color Byte or UInt array.
|
GAMMA |
Double |
Screen gamma correction factor, if specified in gAMa chunk
|
PIXELS_PER_METER
|
Double array |
Pixel dimensions, if specified in the pHYs chunk.
|
TEXT |
OrderedHash |
Collection of the key/value string pairs, if specified in tEXt or zTXt chunks.
|
QUERY_TIFF-Specific Routine Info Structures
Field |
IDL data type |
Description |
BITS_PER_SAMPLE |
Long |
Number of bits per channel. Possible values are 1, 4, 8, 16, or 32.
|
COMPRESSION |
Long |
The compression format. Some possible values (not comprehensive): 1=no compression, 2=CCITT modified Huffman, 4=CCITT T.6, 5=LZW, 7=JPEG, 8=DEFLATE, 32773=PackBits, 50000=Zstandard (zstd). This is the internal TIFF file value, and is not the same as the compression keyword to WRITE_TIFF. |
DESCRIPTION |
String |
The contents of the TIFF ImageDescription tag, or an empty string of undefined.
|
DOCUMENT_NAME |
String |
The contents of the TIFF DocumentName tag, or an empty string if undefined.
|
DATE_TIME |
String |
The contents of the TIFF DateTime tag, or an empty 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]
|
VERSION |
Long |
Type of TIFF file.
42 - Regular TIFF (4GB limited)
43 - BIGTIFF |
Version History
5.2 |
Introduced |
9.0 |
Added COMPRESSION field for TIFF files
|