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.

Usage

status = DC_READ_TIFF(filename, imgarr)

Input Parameters

filename — A string containing the pathname and filename of the TIFF file.

Output Parameters

imgarr — The variable into which the TIFF image data is read. May be an array of any dimension and type; imgarr’s data type is changed to byte and then imgarr is re-dimensioned using information in the TIFF file. Variables of type structure are not supported.

Returned Value

status — Value returned by DC_READ_TIFF; expected values are:

< 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

Note:

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™ 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 guidelines shown in imgarr Guidelines to dimension imgarr:

imgarr Guidelines
Interleaving Method	Dimensions of Image Variable
Pixel (RGB triplets)	Dimension imgarr as 3 × w × h, where w and h are the width and length of the image in pixels.
Image (separate planes)	Dimension imgarr as w × h × 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 a variable.

Example 1

The function call:

status = DC_READ_TIFF(!Data_dir + '/oxford.tif', oximage, /Order)

reads the file oxford.tif and returns the TIFF image data. The data is transferred to the variable oximage.