Reference Guide > D Routines > DC_READ_TIFF Function
  

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 Table 5-3: imgarr Guidelines on page 343 to dimension imgarr:
 
Table 5-3: 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.
 
See Also
DC_ERROR_MSG, DC_WRITE_TIFF, IMAGE_READ
See the PV‑WAVE Programmer’s Guide for more information about TIFF image I/O.

Version 2017.0
Copyright © 2017, Rogue Wave Software, Inc. All Rights Reserved.