|
|
IDL Reference Guide: Procedures and Functions |
|
The WRITE_TIFF procedure can write TIFF files with one or more channels, where each channel can contain 1, 4, 8, 16, or 32-bit integer pixels, or floating-point values.
WRITE_TIFF, Filename [, Image] [, /APPEND] [, BITS_PER_SAMPLE={1 | 4 | 8}] [, RED, GREEN, BLUE=value] [, /CMYK] [, COMPRESSION={0 | 1 | 2 | 3}] [, DESCRIPTION=string] [, DOCUMENT_NAME=string] [, DOT_RANGE=intarray] [, GEOTIFF=structure] [, /LONG | , /SHORT | , /FLOAT] [, ICC_PROFILE=bytearray] [, ORIENTATION=value] [, PHOTOSHOP=array] [, PLANARCONFIG={1 | 2}] [, UNITS={1 | 2 | 3}] [, /VERBOSE] [, XPOSITION=units] [, XRESOL=pixels/inch] [, YPOSITION=units] [, YRESOL=pixels/inch]
A scalar string containing the full pathname of the TIFF to write.
The array to be written to the TIFF. If Image has dimensions (k,n,m), a k-channel TIFF is written. Image should be in top to bottom scan line order. By default, this array is converted to byte format before being written (see the LONG, SHORT and FLOAT keywords below). Note that many TIFF readers can read only one- or three-channel images.
| Note The Image argument is ignored if PLANARCONFIG is set to 2 and the RED, GREEN, and BLUE keywords have been set to 2D arrays. |
| Note Grayscale TIFF images are written out with the PhotometricInterpretation tag set to BlackIsZero, implying that values of 0 should correspond to black. If you want values of 0 to correspond to white, you should invert your pixel values before calling WRITE_TIFF. |
Set this keyword to specify that the image should be added to the existing file, creating a multi-image TIFF file.
Set this keyword to either 1, 4, or 8 to create a grayscale image file with the specified number of bits per pixel. For 1-bit (bi-level) images, an output pixel is assigned the value 1 (one) if the corresponding input pixel is nonzero. For 4-bit grayscale images, the input pixel values must be in the range 0 through 15, or the image will be garbled. The default is BITS_PER_SAMPLE=8. This keyword is ignored if an RGB image or color palette is present, or if one of the FLOAT, LONG, or SHORT keywords is set.
Set this keyword to indicate that Image contains a 4-channel image, where the channels represent colors in the CMYK color-separated format. This corresponds to setting PhotometricInterpretation = 5 in the resulting TIFF file, which allows TIFF readers to interpret the image as CMYK. The Image argument can either be (4, Columns, Rows) or (Columns, Rows, 4) depending upon the PLANARCONFIG keyword.
| Note If Image has 4 channels but the CMYK keyword is not set, then the image is written as a standard multi-channel image, with PhotometricInterpretation = 2. |
Set this keyword to select the type of compression to be used:
| Note For COMPRESSION=3 (JPEG), all images are assumed to be in top-to-bottom order, and the ORIENTATION keyword should not be specified. If your input image is not in top-to-bottom order, you should use REVERSE(image, 2) to flip the order before calling WRITE_TIFF. |
Set this keyword to a scalar string containing the value of the ImageDescription tag to be stored in the TIFF file. If this keyword is not provided then the ImageDescription tag is set to "IDL TIFF file".
Set this keyword to a scalar string containing the value of the DocumentName tag to be stored in the TIFF file. If this keyword is not provided then the DocumentName tag is set to the filename.
Set this keyword to a two-element integer array containing the TIFF DotRange tag value. If this keyword is not provided then the DotRange tag is not stored. The DotRange tag is typically only present in CMYK TIFF files. DOT_RANGE[0] gives the image value that corresponds to a 0% dot, while DOT_RANGE[1] gives the image value that corresponds to a 100% dot.
Set this keyword to write the pixel components as floating-point entities (the default is 8-bit).
Set this keyword to an anonymous structure containing one field for each of the GeoTIFF tags and keys to be written into the file. The GeoTIFF structure is formed using fields named from the following table.
| Note If a GeoTIFF key appears multiple times in a file, only the value for the first instance of the key is returned. |
Set this keyword to a byte array containing the ICC_PROFILE tag, as returned by the READ_TIFF routine.
| Note The ICC_PROFILE tag is an opaque byte array. It is assumed that the tag will be read from an existing file, and written out to a new file without modification. |
Set this keyword to write the pixel components as unsigned 32-bit entities (the default is 8-bit).
Set this keyword to an integer value to specify the orientation of the TIFF image. The default is ORIENTATION=1.
| Note For COMPRESSION=3 (JPEG), all images are assumed to be in top-to-bottom order, and this keyword should not be specified. |
Possible values are:
| Warning Not all TIFF readers honor the value of the ORIENTATION field. IDL writes the value into the file, but some readers are known to ignore this value. In such cases, we recommend that you convert the image to top-to-bottom order with the REVERSE function and then set ORIENTATION to 1. If your image is a True Color three-channel image, which is pixel- or line-interleaved, then set the REVERSE call's optional 'Subscript_Index' argument to 3. If your image is band-interleaved or is a one-channel image, set that argument to 2. |
| Note Setting the ORIENTATION keyword does not alter the way the image data is stored. The raw data is not rotated prior to being written to disk. |
Set this keyword to a byte array containing the TIFF PHOTOSHOP tag value, as returned by the READ_TIFF routine.
| Note The PHOTOSHOP tag is an opaque byte array. It is assumed that the tag will be read from an existing file, and written out to a new file without modification. |
This keyword determines the order in which a multi-channel image is stored and written. It has no effect with a single-channel image. Set this keyword to 2 to if the Image parameter is interleaved by "plane", or band, and its dimensions are (Columns, Rows, Channels). The default value is 1, indicating that multi-channel images are interleaved by color, also called channel, and its dimensions are (Channels, Columns, Rows).
As a special case, this keyword may be set to 2 to write an RGB image that is contained in three separate arrays (color planes), stored in the variables specified by the RED, GREEN, and BLUE keywords. Otherwise, omit this parameter (or set it to 1).
| Note Many TIFF readers can read only one- or three-channel images. |
If you are writing a Palette color image, set these keywords equal to the color table vectors, scaled from 0 to 255.
If you are writing an RGB interleaved image (i.e., if the PLANARCONFIG keyword is set to 2), set these keywords to the names of the variables containing the three image components.
Set this keyword to write the pixel components as unsigned 16-bit entities (the default is 8-bit).
Set this keyword to one of the following values to specify the units used for the values specified by the XRESOL and YRESOL keywords:
Set this keyword to produce additional diagnostic output during the write.
Set this keyword to the X offset relative to the left side of the image, in units specified by the UNITS keyword. XPOSITION must be nonnegative. If XPOSITION is not specified then this tag is not written to the file.
| Note The XPOSITION tag is usually ignored by most TIFF readers. |
Set this keyword to the horizontal resolution, in pixels per unit, where the unit is specified by the value of the UNITS keyword (inches, by default). The default value of XRESOL is 100. Note that while this value is stored in the TIFF file, it may be interpreted by the TIFF reader in a variety of ways, or ignored.
Set this keyword to the Y offset relative to the top of the image (with positive Y increasing downwards), in units specified by the UNITS keyword. YPOSITION must be nonnegative. If YPOSITION is not specified then this tag is not written to the file.
| Note The YPOSITION tag is usually ignored by most TIFF readers. |
Set this keyword to the vertical resolution, in pixels per unit, where the unit is specified by the value of the UNITS keyword (inches, by default). The default value of YRESOL is 100. Note that while this value is stored in the TIFF file, it may be interpreted by the TIFF reader in a variety of ways, or ignored.
Create a pseudo screen dump from the current window. Note that this works only on a PseudoColor (8-bit) display:
WRITE_TIFF, 'test.tiff', TVRD()
Write a three-channel image from three one-channel (two-dimensional) arrays, contained in the variables Red, Green, and Blue:
WRITE_TIFF, 'test.tif', RED=Red, GREEN=Green, BLUE=Blue, $ PLANARCONFIG=2
Write and read a multi-image TIFF file. The first image is a 16-bit single channel image stored using compression. The second image is an RGB image stored using 32-bits/channel uncompressed.
; Write the image data:
data = FIX(DIST(256))
rgbdata = LONARR(3,320,240)
WRITE_TIFF,'multi.tif',data,COMPRESSION=1,/SHORT
WRITE_TIFF,'multi.tif',rgbdata,/LONG,/APPEND
; Read the image data back
ok = QUERY_TIFF('multi.tif',s)
IF (ok) THEN BEGIN
FOR i=0,s.NUM_IMAGES-1 DO BEGIN
imp = QUERY_TIFF('multi.tif',t,IMAGE_INDEX=i)
img = READ_TIFF('multi.tif',IMAGE_INDEX=i)
HELP,t,/STRUCTURE
HELP,img
ENDFOR
ENDIF
|
5.0
|
Introduced
|
|
5.5
|
Deprecated Order argument.
|
|
5.6
|
Added ITIFF support
|
|
6.1
|
Added CMYK, DESCRIPTION, DOCUMENT_NAME, DOT_RANGE, ICC_PROFILE, PHOTOSHOP, XPOSITION, and YPOSITION keywords
|
For information on obsolete keywords, see Obsolete Features.
IDL Online Help (March 06, 2007)