DC_WRITE_TIFF Function

Writes image data to a file using the Tag Image File Format (TIFF) format.

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

Usage

status = DC_WRITE_TIFF(filename, imgarr)

Input Parameters

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

imgarr — The 2 or 3-D byte array from which the image data is transferred. Note that variables of type structure are not supported.

Returned Value

status — The value returned by DC_WRITE_TIFF; expected values are:

< 0 — Indicates an error, such as an invalid filename or image number.
0 — Indicates a successful write.

Keywords

Class — TIFF class conformance level; supplied as a string. If not provided, Class='Bilevel' is assumed. Valid values are:

'Bilevel'

'Grayscale'

'Palette Color'

'RGB Full Color'

The strings can be abbreviated to one letter, if you wish.

The four classes of TIFF image conformance are explained in more detail in the PV‑WAVE Programmer’s Guide.

Compress — A string that signifies the kind of image data compression to use as the data is written to the file (if TIFF class 'B' (Bilevel) is specified). If not provided, no compression is performed. Valid values at this time are:

'None'

'PackBits'

Negative — If set, the dithering function is reversed so that all pixels in the image that are less than or equal to the threshold are set to 255. All other pixels are set to 0. This keyword is only valid when the Class keyword is set to Bilevel. The default threshold is 128.

Order — If nonzero, returns the image mirrored in the y-direction. (Default: Do not mirror the image.)

Palette — The color table to store with the image data if TIFF class P (Palette Color) is specified. Palette must be a 3-by-256 array of integers.

Threshold — An integer specifying the threshold value for dithering a grayscale image to a binary image. When the Class keyword is set to Bilevel, the image is converted to a binary image before being stored to disk. Pixels in the image that are greater than the threshold level are set to 255. All other pixels are set to 0. This keyword is only valid when the Class keyword is set to Bilevel. If Bilevel is specified and no threshold is given, the threshold value defaults to 128.

Discussion

DC_WRITE_TIFF facilitates the exporting of TIFF images from 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 writing the data.

If imgarr is not a 2 or 3-D byte array, DC_WRITE_TIFF returns an error status and no data is written to the output file.

Requirements of the Various TIFF Classes

If TIFF class 'B' (Bilevel) is specified, you can use the Compress keyword to create compressed TIFF image files.

If TIFF class 'P' (Palette Color) is specified, you must use the Palette keyword to specify a palette array.

If TIFF class 'RGB' (RGB Full Color) is specified, imgarr must be a 3-D byte array with the last dimension equal to 3. In other words, imgarr must be an image-interleaved image; pixel-interleaved images cannot be stored in a TIFF file when using the DC_WRITE_TIFF function. The difference between pixel-interleaved and image-interleaved data is discussed in the PV‑WAVE Programmer’s Guide.

Example 1

If the variable mandril is a 512-by-512 byte array, the commands:

; Read the image.
mandril = BYTARR(512, 512)
OPENR, unit, !Data_dir + 'mandril.img', /Get_lun
READU, unit, mandril
FREE_LUN, unit
status = DC_WRITE_TIFF('mandril.tif', mandril,  $
   Class='Bi', Compress='Pack')

create the file mandril.tif and use it to store the image data contained in the variable maverick. The created TIFF file is compressed and conforms to the TIFF 'Bilevel' classification.

Example 2

If the variable denver24 is a 256-by-256-by-3 true-color 24-bit image (byte array), the commands:

; Read the image.
denver24 = BYTARR(256, 256, 3)
OPENR, unit, !Dir + '/demo/gallery3/data/denver24.img', /Get_lun
READU, unit, denver24
FREE_LUN, unit
status = DC_WRITE_TIFF('denver24.tif', denver24, Class='RGB')

create the file denver24.tif and use it to store the RGB color image data contained in the variable denver24; image interleaving is used because the variable is 256-by-256-by-3. The created TIFF file conforms to the TIFF RGB Full Color classification.