The READ_TIFF function reads single or multi-channel images from TIFF format files and returns the image and color table vectors in the form of IDL variables.
| Note |
Result = READ_TIFF( Filename [, R, G, B] [, CHANNELS=scalar or vector] [, DOT_RANGE=variable] [, GEOTIFF=variable] [, ICC_PROFILE=variable] [, IMAGE_INDEX=value] [, INTERLEAVE={0 | 1 |2}] [, ORIENTATION=variable] [, PHOTOSHOP=variable] [, PLANARCONFIG=variable] [, SUB_RECT=[x, y, width, height]] [, /VERBOSE] )
READ_TIFF returns a byte, unsigned integer, long, or float array (based on the data format in the TIFF file) containing the image data. The dimensions of the Result are [Columns, Rows] for single-channel images, or [Channels, Columns, Rows] for multi-channel images, unless a different type of interleaving is specified with the INTERLEAVE keyword.
For 1-bit (bilevel) images, the image values are 0 or 1. For 4-bit grayscale images the image values are in the range 0 to 15.
RGB images are a special case of multi-channel images, and contain three channels. Most TIFF readers and writers can handle only images with one or three channels.
As a special case, for three-channel TIFF image files that are stored in planar interleave format, and if four parameters are provided, READ_TIFF returns the integer value zero, sets the variable defined by the PLANARCONFIG keyword to 2, and returns three separate images in the variables defined by the R, G, and B arguments.
A scalar string specifying the full pathname of the TIFF file to read.
Named variables that will contain the Red, Green, and Blue color vectors of the color table from the file if one exists. If the TIFF file is written as a three-channel image, interleaved by plane, and the R, G, and B parameters are present, the three channels of the image are returned in the R, G, and B variables.
Set this keyword to a scalar or vector giving the channel numbers to be returned for a multi-channel image, starting with zero. The default is to return all of the channels. This keyword is ignored for single-channel images, or for three-channel planar-interleaved images when the R, G, and B arguments are specified.
Set this keyword to a named variable in which to return a two-element integer array containing the TIFF DotRange tag value. If DotRange is not defined in the TIFF file, then a scalar zero will be returned instead. The DotRange tag is typically only present in CMYK TIFF files. DOT_RANGE[0] gives the image value that corresponds to a 0% dot, while DOT_RANGE[1] gives the image value that corresponds to a 100% dot.
Returns an anonymous structure containing one field for each of the GeoTIFF tags and keys found in the file. If no GeoTIFF information is present in the file, the returned variable is undefined.
The GeoTIFF structure is formed using fields named from the following table.
| Note |
Selects the image number within the file to be read (see QUERY_TIFF to determine the number of images in the file).
Set this keyword to a named variable in which to return a byte array containing the TIFF ICC_PROFILE tag value. If the ICC_PROFILE tag is not contained in the TIFF file then a scalar zero will be returned instead. The ICC_PROFILE array is returned as an opaque array of byte values which the user can then pass to the WRITE_TIFF routine.
| Note |
For multi-channel images, set this keyword to one of the following values to force the Result to have a specific interleaving, regardless of the type of interleaving in the file being read:
If this keyword is not specified, the Result will always be pixel interleaved, regardless of the type of interleaving in the file being read. For files stored in planar-interleave format, this keyword is ignored if the R, G, and B arguments are specified.
Set this keyword to a named variable that will contain the orientation value from the TIFF file. Possible return values are:
If an orientation value does not appear in the TIFF file, an orientation of 0 is returned.
Set this keyword to a named variable in which to return a byte array containing the TIFF PHOTOSHOP tag value. If the PHOTOSHOP tag is not contained in the TIFF file, then a scalar zero will be returned instead. The PHOTOSHOP array is returned as an opaque array of byte values which the user can then pass to the WRITE_TIFF routine.
| Note |
Set this keyword to a named variable that will contain the interleave parameter for the TIFF file. This parameter is returned as 1 for TIFF files that are GrayScale, Palette, or interleaved by pixel. This parameter is returned as 2 for multi-channel TIFF files interleaved by image.
Set this keyword to a four-element array, [x, y, width, height], that specifies a rectangular region within the file to extract. Only the rectangular portion of the image selected by this keyword is read and returned. The rectangle is measured in pixels from the lower left corner (right hand coordinate system).
| Tip |
Produce additional diagnostic output during the read.
The following keywords are obsolete:
For information on obsolete keywords, See Obsolete Features.
Read the file my.tif in the current directory into the variable image, and save the color tables in the variables, R, G, and B by entering:
image = READ_TIFF('my.tif', R, G, B)
To view the image, load the new color table and display the image by entering:
TVLCT, R, G, B TV, image
Write and read a multi-image TIFF file. The first image is a 16-bit single-channel image stored using compression. The second image is an RGB image stored using 32-bits/channel uncompressed.
; Write the image data:
data = FIX(DIST(256))
rgbdata = LONARR(3,320,240)
WRITE_TIFF,'multi.tif',data,COMPRESSION=1,/SHORT
WRITE_TIFF,'multi.tif',rgbdata,/LONG,/APPEND
; Read the image data back:
ok = QUERY_TIFF('multi.tif',s)
IF (ok) THEN BEGIN
FOR i=0,s.NUM_IMAGES-1 DO BEGIN
imp = QUERY_TIFF('multi.tif',t,IMAGE_INDEX=i)
img = READ_TIFF('multi.tif',IMAGE_INDEX=i)
HELP,t,/STRUCTURE
HELP,img
ENDFOR
ENDIF
Write and read a multi-channel image:
data = LINDGEN(10, 256, 256) ; 10 channels
; Write the image data:
WRITE_TIFF, 'multichannel.tif', data, /LONG
; Read back only channels [0,2,4,6,8], using planar-interleaving
img = READ_TIFF('multichannel.tif', CHANNELS=[0,2,4,6,8], $
INTERLEAVE=2)
HELP, img
IDL prints:
IMG LONG = Array[256, 256, 5]
Introduced: 5.0
DOT_RANGE, ICC_PROFILE, and PHOTOSHOP keywords added: 6.1