DC_READ_TIFF Function

Reads a Tag Image File Format (TIFF) file.

NOTE: This function was retired with version 6.1, because the new IMAGE_READ function provides the same capability. Although DC_READ_TIFF is still available for backward compatibility, we strongly recommend that you use IMAGE_READ instead.


0	Indicates an error, such as an invalid filename or image number.
0	Indicates a successful read.

Keywords

BitsPerSample

The number of bits that comprise each sample in the TIFF image is returned; a pixel consists of one or more "samples". BitsPerSample is returned as an integer; typical values are 2, 4, and 8.

Colormap The TIFF image colormap. If present, the colormap associated with the TIFF image is returned. Colormap is returned as a 2-dimensional array of long integers.

Compression The compression style used in the TIFF image. Compression is returned as an integer; expected values are:


1	None (no compression)
2	CCITT Group 3
5	LZW
32733	PackBits

Imagelength

The TIFF image length. If present, the TIFF image length is returned. Imagelength is returned as a long integer value.

Imagewidth The TIFF image width. If present, the TIFF image width is returned. Imagewidth is returned as a long integer value.

Imgnum The number of the image to read from the file. If not provided, the first image (image number 0) is read.

Order If nonzero, Order reverses the y-axis direction of the original image. In other words, if the original image is stored from top to bottom, the returned image is stored from bottom to top.

PhotometricInterpretation The class of the TIFF image. If present, retrieves photometric information from the TIFF image header. PhotometricInterpretation is returned as an integer; expected values are:


0	Bilevel/Grayscale
2	Full RGB color
3	Palette color
4	Transparency mask

Transparency mask indicates the image is used to define an irregularly shaped region of another image in the same TIFF file. PhotometricInterpretation=4 is not supported by PV-WAVE.

The first four classes of TIFF images are explained in more detail in the PV-WAVE Programmer's Guide.

PlanarConfig The arrangement of the RGB information. If present, retrieves RGB configuration information from the TIFF image header. PlanarConfig is returned as an integer; expected values are:


1	RGB triplets (pixel interleaving)
2	Separate planes (image interleaving)

The methods for interleaving image data are explained more fully in the PV-WAVE Programmer's Guide.

ResolutionUnit The type of resolution units specified in the TIFF image header. If present, retrieves unit information from the TIFF image. ResolutionUnit is returned as an integer; expected values are:


1	None (no absolute units)
2	Inches
3	Centimeters

SamplesPerPixel

The number of samples associated with each pixel in the TIFF image is returned. SamplesPerSample is returned as an integer; expected values are:


1	Bilevel, Grayscale, Palette color
3	RGB images

XResolution

The number of pixels per ResolutionUnit in the X direction. If present, retrieves information about the number of X pixels from the TIFF image header. XResolution is returned as a floating-point value.

YResolution The number of pixels per ResolutionUnit in the Y direction. If present, retrieves information about the number of Y pixels from the TIFF image header. YResolution is returned as a floating-point value.

For more information about the output keywords described in this section, see the Technical Memorandum, Tag Image File Format Specification, Revision 5.0 (FINAL), published jointly by Aldus(TM) Corporation and Microsoft® Corporation.

Discussion

DC_READ_TIFF enables you to import TIFF images into PV-WAVE. It also handles many steps that you have to do yourself when using other PV-WAVE functions and procedures. These steps include: 1) opening the file, 2) assigning it a logical unit number (LUN), and 3) closing the file when you are done reading the data.

DC_READ_TIFF sets the dimension and type (byte array) of imgarr automatically, depending on the width and height of the image. For 24-bit images, the interleaving method (see description of PlanarConfig keyword) is considered, as well. PV-WAVE uses the following guidelines to dimension imgarr:


Interleaving Method	Dimensions of Image Variable
Pixel (RGB triplets)	Dimension imgarr as 3 x w x h, where w and h are the width and length of the image in pixels.
Image (separate planes)	Dimension imgarr as w x h x 3, where w and h are the width and length of the image in pixels.

The difference between pixel-interleaved and image-interleaved image data is discussed in the PV-WAVE Programmer's Guide.

NOTE: Compressed TIFF images are uncompressed before being transferred to the named variable.

Example 1

The function call:

status = DC_READ_TIFF('oxford.tif', oximage)

reads the file oxford.tif and returns the TIFF image data contained in the first image of that file. The data is transferred to the variable oximage.

Example 2

The function call:

status = DC_READ_TIFF('shamu.tif', shamu,  $
    Imagewidth=xsz, Imagelength=ysz,  $
    PlanarConfig=planar, Photometric=photo)

reads a complete description of the first TIFF image in the file shamu.tif. The width and length of the image are returned in xsz and ysz, respectively. PlanarConfig and PhotometricInterpretation are returned in planar and photo, respectively.

The fact that the PlanarConfig keyword is being returned with the function call suggests that the image in shamu.tif is a full-color RGB (24-bit) image. The PlanarConfig keyword is used to return the image interleaving method for 24-bit images.

DC_READ_TIFF Function

Usage

Input Parameters

Output Parameters

Returned Value

Keywords

Discussion

Example 1

Example 2

See Also