IDL Reference Guide: Procedures and Functions

READ_TIFF

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.

Syntax

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] )

Return Value

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.

Arguments

Filename

A scalar string specifying the full pathname of the TIFF file to read.

R, G, B

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.

Keywords

CHANNELS

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.

DOT_RANGE

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.

GEOTIFF

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.

IMAGE_INDEX

Selects the image number within the file to be read (see QUERY_TIFF to determine the number of images in the file).

ICC_PROFILE

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.

INTERLEAVE

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.

ORIENTATION

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.

You can use the IDL ROTATE function to efficiently position the image data as specified by the file's ORIENTATION property. Set the ROTATE function DIRECTION value to one of the following based on the ORIENTATION value:

PHOTOSHOP

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.

PLANARCONFIG

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.

SUB_RECT

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

VERBOSE

Produce additional diagnostic output during the read.

Examples

Example 1

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

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  

IMG      LONG     = Array[256, 256, 5]