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:
Interleaving Method |
Dimensions of Image Variable |
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.