WRITE_TIFF

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.

If you create a TIFF file larger than 4 GB, IDL automatically creates a file with the correct BigTIFF header. However, if you append to a file which is less than 4GB and the append pushes the file size to over 4GB, IDL will throw an error. In this case, use the BIGTIFF keyword on file creation.

Note: If you need to use signed values using the SHORT, LONG, or L64 keywords, make sure to set the SIGNED keyword as well.

Syntax

WRITE_TIFF, Filename[, Image] [, /APPEND] [, /BIGTIFF] [, BITS_PER_SAMPLE={1 | 4 | 8}] [, RED, GREEN, BLUE=value] [, /CMYK] [, COMPRESSION={0 | 1 | 2 | 3 | 4}] [, DESCRIPTION=string] [, DOCUMENT_NAME=string] [, DOT_RANGE=intarray] [, GEOTIFF=structure] [, /COMPLEX | , /DCOMPLEX | , /DOUBLE | , /L64 | , /LONG | , /SHORT | , /FLOAT] [, ICC_PROFILE=bytearray] [, ORIENTATION=value] [, PHOTOSHOP=array] [, PLANARCONFIG={1 | 2}] [, /SIGNED] [, UNITS={1 | 2 | 3}] [, /VERBOSE] [, XPOSITION=units] [, XRESOL=pixels/inch] [, YPOSITION=units] [, YRESOL=pixels/inch]

Arguments

Filename

A scalar string containing the full pathname of the TIFF to write.

Image

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. The Image array is converted to byte format before being written, unless one of the data type keywords (LONG, SHORT, etc.) is specified. 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. To have values of 0 to correspond to white, invert the pixel values before calling WRITE_TIFF.

Keywords

APPEND

Set this keyword to specify that the image should be added to the existing file, creating a multi-image TIFF file.

Note: If your final file size will be greater than 4Gb, then you should use the BIGTIFF keyword on initial file creation.

BIGTIFF

Set this keyword on the creation of the TIFF file to force the file to be written in BIGTIFF format. The BIGTIFF format is not limited a the 4GB boundary. If BIGTIFF is not specified and the data is less than 4GB, then the file will be created as a normal TIFF file.

Note: The BIGTIFF keyword can only be used on initial file creation, and cannot be changed during an APPEND to an existing file.

BITS_PER_SAMPLE

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 LONG, SHORT, FLOAT, L64, COMPLEX, DCOMPLEX, or DOUBLE keywords is set.

CMYK

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.

COMPLEX

Set this keyword to write the pixel components as complex floating-point entities (the default is to write the data as 8-bit bytes).

COMPRESSION

Set this keyword to select the type of compression to be used:

0 = None (default)
1 = LZW
2 = PackBits
3 = JPEG (ITIFF files)
4 = DEFLATE
5 = Zstandard (zstd)

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, use REVERSE(image, 2) to flip the order before calling WRITE_TIFF.

DCOMPLEX

Set this keyword to write the pixel components as double-precision complex floating-point entities (the default is to write the data as 8-bit bytes).

DESCRIPTION

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”.

DOCUMENT_NAME

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.

DOT_RANGE

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.

DOUBLE

Set this keyword to write the pixel components as double-precision, floating-point entities (the default is to write the data as 8-bit bytes).

FLOAT

Set this keyword to write the pixel components as floating-point entities (the default is to write the data as 8-bit bytes).

GEOTIFF

Set the GEOTIFF keyword equal to an anonymous structure containing one field for each of the GeoTIFF tags and keys to be written into the file. GeoTIFF structure closely resembles the TIFF structure, storing projection parameters in a set of keys, which are explained the the GEOTIFF Structures table, below.

According to http://remotesensing.org, the purpose of the GeoTIFF specification is to define a set of TIFF tags to describe the cartographic information in TIFF imagery that comes from satellite imaging systems, scanned aerial photography, scanned maps, digital elevation models, or from geographic analyses. The specification allows you to tie a raster image to a known model space or map projection.

The tags documented in the GeoTIFF specification are unrelated to the raster data descriptions in the TIFF specification. GeoTIFF tags and keys occasionally change, so refer to he GeoTIFF Specification for the most current information.

Note: See Example 4 below for how to use the GEOTIFF keyword.

The GeoTIFF structure is formed using any subset of the fields named in the following table.

Anonymous Structure Field Name	IDLDatatype
TAGS:
"MODELPIXELSCALETAG"	DOUBLE[3]
"MODELTRANSFORMATIONTAG"	DOUBLE[4,4]
"MODELTIEPOINTTAG"	DOUBLE[6,*]
KEYS:
"GTMODELTYPEGEOKEY"	INT
"GTRASTERTYPEGEOKEY"	INT
"GTCITATIONGEOKEY"	STRING
"GEOGRAPHICTYPEGEOKEY"	INT
"GEOGCITATIONGEOKEY"	STRING
"GEOGGEODETICDATUMGEOKEY"	INT
"GEOGPRIMEMERIDIANGEOKEY"	INT
"GEOGLINEARUNITSGEOKEY"	INT
"GEOGLINEARUNITSIZEGEOKEY"	DOUBLE
"GEOGANGULARUNITSGEOKEY"	INT
"GEOGANGULARUNITSIZEGEOKEY"	DOUBLE
"GEOGELLIPSOIDGEOKEY"	INT
"GEOGSEMIMAJORAXISGEOKEY"	DOUBLE
"GEOGSEMIMINORAXISGEOKEY"	DOUBLE
"GEOGINVFLATTENINGGEOKEY"	DOUBLE
"GEOGAZIMUTHUNITSGEOKEY"	INT
"GEOGPRIMEMERIDIANLONGGEOKEY"	DOUBLE
"PROJECTEDCSTYPEGEOKEY"	INT
"PCSCITATIONGEOKEY"	STRING
"PROJECTIONGEOKEY"	INT
"PROJCOORDTRANSGEOKEY"	INT
"PROJLINEARUNITSGEOKEY"	INT
"PROJLINEARUNITSIZEGEOKEY"	DOUBLE
"PROJSTDPARALLEL1GEOKEY"	DOUBLE
"PROJSTDPARALLEL2GEOKEY"	DOUBLE
"PROJNATORIGINLONGGEOKEY"	DOUBLE
"PROJNATORIGINLATGEOKEY"	DOUBLE
"PROJFALSEEASTINGGEOKEY"	DOUBLE
"PROJFALSENORTHINGGEOKEY"	DOUBLE
"PROJFALSEORIGINLONGGEOKEY"	DOUBLE
"PROJFALSEORIGINLATGEOKEY"	DOUBLE
"PROJFALSEORIGINEASTINGGEOKEY"	DOUBLE
"PROJFALSEORIGINNORTHINGGEOKEY"	DOUBLE
"PROJCENTERLONGGEOKEY"	DOUBLE
"PROJCENTERLATGEOKEY"	DOUBLE
"PROJCENTEREASTINGGEOKEY"	DOUBLE
"PROJCENTERNORTHINGGEOKEY"	DOUBLE
"PROJSCALEATNATORIGINGEOKEY"	DOUBLE
"PROJSCALEATCENTERGEOKEY"	DOUBLE
"PROJAZIMUTHANGLEGEOKEY"	DOUBLE
"PROJSTRAIGHTVERTPOLELONGGEOKEY"	DOUBLE
"VERTICALCSTYPEGEOKEY"	INT
"VERTICALCITATIONGEOKEY"	STRING
"VERTICALDATUMGEOKEY"	INT
"VERTICALUNITSGEOKEY"	INT

Note: If a GeoTIFF key appears multiple times in a file, only the value for the first instance of the key is returned.

ICC_PROFILE

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.

L64

Set this keyword to write the pixel components as unsigned 64-bit integer entities (the default is to write the data as 8-bit bytes). Use the SIGNED keyword to write signed integers.

LONG

Set this keyword to write the pixel components as unsigned 32-bit entities (the default is to write the data as 8-bit bytes). Use the SIGNED keyword to write signed integers.

ORIENTATION

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:

0	Column 0 represents the left-hand side, and row 0 represents the bottom (same as 4)
1	Column 0 represents the left-hand side, and row 0 represents the top.
2	Column 0 represents the right-hand side, and row 0 represents the top.
3	Column 0 represents the right-hand side, and row 0 represents the bottom.
4	Column 0 represents the left-hand side, and row 0 represents the bottom (same as 0)
5	Column 0 represents the top, and row 0 represents the left-hand side.
6	Column 0 represents the top, and row 0 represents the right-hand side.
7	Column 0 represents the bottom, and row 0 represents the right-hand side.
8	Column 0 represents the bottom, and row 0 represents the left-hand side.

Note: 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.

PHOTOSHOP

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.

PLANARCONFIG

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.

RED

GREEN

BLUE

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.

SHORT

Set this keyword to write the pixel components as unsigned 16-bit entities (the default is to write the data as 8-bit bytes). Use the SIGNED keyword to write signed integers.

SIGNED

If the SHORT, LONG, or L64 keywords are set, then set SIGNED to write out signed integers instead of unsigned integers.

UNITS

Set this keyword to one of the following values to specify the units used for the values specified by the XRESOL and YRESOL keywords:

1	No units
2	Inches (the default)
3	Centimeters

VERBOSE

Set this keyword to produce additional diagnostic output during the write.

XPOSITION

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.

XRESOL

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.

YPOSITION

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.

YRESOL

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.

Examples

Example 1

The following lines create an image in an IDL graphics window, read it from the window and write it as a .tif file in the temporary directory, then read the .tif file and display it in the same graphics window:

; Save device settings and tell IDL to use a color table
DEVICE, GET_DECOMPOSED=old_decomposed
DEVICE, DECOMPOSED=0
LOADCT, 14

; Create an image and display it
IMAGE1 = DIST(300)
WINDOW, 1, XSIZE=300, YSIZE=300
TV, IMAGE1

; Write a TIFF file to the temporary directory
; Note the use of the TRUE keyword to TVRD
filename = FILEPATH('test.tif', /TMP)
WRITE_TIFF, filename, TVRD(/TRUE)
PRINT, 'File written to ', filename

; Read in the file
IMAGE2 = READ_TIFF(filename)

; Display the IMAGE1 and IMAGE2 side by side
; Note the use of the TRUE keyword to TV
WINDOW, 1, XSIZE=600, YSIZE=300, $
TITLE='Original (left) and Image read from file (right)'
TV, IMAGE1, 0
TV, IMAGE2, 1, /TRUE

; Restore device settings.
DEVICE, DECOMPOSED=old_decomposed

Example 2

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

Example 3

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.

; Save device settings and tell IDL to use a color table
DEVICE, GET_DECOMPOSED=old_decomposed
DEVICE, DECOMPOSED=0
LOADCT, 0

; Write the image data:
data = FIX(DIST(256))
rgbdata = LONARR(3,320,240)
rgbdata[1,*,*]=DIST(320,240)
rgbdata[2,*,*]=DIST(320,240)
tif_file = GETENV('IDL_TMPDIR')+'multi.tif'
WRITE_TIFF, tif_file, data, COMPRESSION=1, /SHORT
WRITE_TIFF, tif_file, rgbdata, /LONG, /APPEND
; Read the image data back
ok = QUERY_TIFF(tif_file, s)

; Get information on the images
IF (ok) THEN BEGIN & $
   FOR i=0, s.NUM_IMAGES-1 DO BEGIN & $
      imp = QUERY_TIFF(tif_file, t, IMAGE_INDEX=i) & $
      img = READ_TIFF(tif_file, IMAGE_INDEX=i) & $
      HELP, t, /STRUCTURE & $
      HELP, img & $
   ENDFOR & $
ENDIF

; Display the images
WINDOW, 0, XSIZE=256, YSIZE=256
TV, READ_TIFF(tif_file, IMAGE_INDEX=0)
WINDOW, 1, XSIZE=320, YSIZE=240
TV, READ_TIFF(tif_file, IMAGE_INDEX=1), /TRUE

; Restore device settings.
DEVICE, DECOMPOSED=old_decomposed

Example 4

At times you may want to programatically associate georeferencing information with a .tiff file to create a geotiff file. The example below creates a geotiff file containing some of the tags and geokeys available to IDL. The values used here come from an example found on the GeoTIFF Format Specification website: https://trac.osgeo.org/geotiff/

The values in the program are as follows:

Projection—Lambert Conformal Conic
Central Meridian—120 degrees West
Pixel size—25m
Datum—NAD27
Standard Parallels— 41d 20m N and 48d 40m N
Latitude of origin—45d N and occurs at coordinates (80, 100)
False Easting—200000m
False Northing—1500000m

pro example_write_geotiff

;Create some sample tag and geokey information
g_tags = { $
ModelPixelScaleTag: [25, 25, 0d], $
ModelTiepointTag: [80, 100, 0, 200000, 1500000, 0], $
GTModelTypeGeoKey: 1, $ ; (ModelTypeProjected)
GTRasterTypeGeoKey: 1, $ ; (RasterPixelIsArea)
GeographicTypeGeoKey: 4267, $ ; (GCS_NAD27)
ProjectedCSTypeGeoKey: 32767, $ ; (user-defined)
ProjectionGeoKey: 32767, $ ; (user-defined)
ProjLinearUnitsGeoKey: 9001, $ ; (Linear_Meter)
ProjCoordTransGeoKey: 8, $ ; (CT_LambertConfConic_2SP)
ProjStdParallel1GeoKey: 41.333, $
ProjStdParallel2GeoKey: 48.666, $
ProjCenterLongGeoKey: 120.0, $
ProjNatOriginLatGeoKey: 45.0, $
ProjFalseEastingGeoKey: 200000.0, $
ProjFalseNorthingGeoKey: 1500000.0 $
}

;Create an image for the tags and geokeys and then
;write out the file
data = fix(dist(512))
WRITE_TIFF,'example_geotif.tif',data,/float, geotiff=g_tags

;Do a query on the file and print out the information found in the
;tags and geokeys
test=QUERY_TIFF( 'example_geotif.tif', geotiff=my_tag)
PRINT, my_tag
HELP, my_tag, /struct

END

Example 5

This example illustrates how to view the the geotiff structure of an image and write it to a geotiff file. Just click on the following code to run it in IDL:

; Define a variable to hold the image file
dataFilePath = FILEPATH('boulder.tif', $
SUBDIR=['examples','data'])
; Run iopen with the geotiff keyword
; to expose the geotiff structure
IOPEN, dataFilePath, data_variable, GEOTIFF=GeoKeys

Note: You can also open image files using File > Open File or using the IOPEN command. If you use File > Open File, IDL defines the variable names. If you use IOPEN, you define the names of the data and GeoTIFF variables.

You can view the structure of the GeoKeys variable that holds the geotiff structure by looking at the Variables view or by typing the following at the command line.

HELP, GeoKeys, /STRUCTURE

The structure displays as follows:

** Structure <125c498>, 7 tags, length=88, data length=82, refs=1:

MODELPIXELSCALETAG

DOUBLE Array[3]

MODELTIEPOINTTAG

DOUBLE Array[6, 1]

GTMODELTYPEGEOKEY

INT 1

GTRASTERTYPEGEOKEY