1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
4
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
3
5
<title>GTiff -- GeoTIFF File Format</title>
6
<body bgcolor="#ffffff">
8
10
<h1>GTiff -- GeoTIFF File Format</h1>
10
Most forms of TIFF and GeoTIFF files are supported by GDAL for reading, and
11
somewhat less varieties can be written.<p>
12
<p>Most forms of TIFF and GeoTIFF files are supported by GDAL for reading, and
13
somewhat less varieties can be written.</p>
13
When built with internal libtiff or with libtiff >= 4.0, GDAL also supports
15
<p>When built with internal libtiff or with libtiff >= 4.0, GDAL also supports
14
16
reading and writing BigTIFF files (evolution of the TIFF format to support files
15
17
larger than 4 GB).</p>
17
Currently band types of Byte, UInt16, Int16, UInt32, Int32, Float32, Float64,
19
<p>Currently band types of Byte, UInt16, Int16, UInt32, Int32, Float32, Float64,
18
20
CInt16, CInt32, CFloat32 and CFloat64 are supported for
19
21
reading and writing.
20
22
Paletted images will return palette information associated with
21
23
the band. The compression formats listed below should be supported for
24
As well, one bit files, and some other unusual formulations of GeoTIFF file,
26
<p>As well, one bit files, and some other unusual formulations of GeoTIFF file,
25
27
such as YCbCr color model files, are automatically translated into RGBA
26
(red, green, blue, alpha) form, and treated as four eight bit bands. <p>
28
(red, green, blue, alpha) form, and treated as four eight bit bands. </p>
28
30
<h2>Georeferencing</h2>
30
Most GeoTIFF projections should be supported, with the caveat that in order
32
<p>Most GeoTIFF projections should be supported, with the caveat that in order
31
33
to translate uncommon Projected, and Geographic coordinate systems into
32
34
OGC WKT it is necessary to have the EPSG .csv files available. They must
33
35
be found at the location pointed to by the GEOTIFF_CSV environment variable.
36
Georeferencing from GeoTIFF is supported in the form of one tiepoint and
37
pixel size, a transformation matrix, or a list of GCPs.<p>
38
<p>Georeferencing from GeoTIFF is supported in the form of one tiepoint and
39
pixel size, a transformation matrix, or a list of GCPs.</p>
41
<p>If no georeferencing
40
42
information is available in the TIFF file itself, GDAL will also check for,
41
43
and use an ESRI <a href="frmt_various.html#WLD">world file</a> with the
42
44
extention .tfw, .tifw/.tiffw or .wld, as well as a MapInfo .tab file (only control
43
points used, Coordsys ignored).<P>
45
<h2>Internal nodata masks</h2> (from GDAL 1.6.0)<p>
47
TIFF files can contain internal transparency masks. The GeoTIFF driver
45
points used, Coordsys ignored).</p>
47
<p>GDAL can read and write the <i>RPCCoefficientTag</i> as described in the <a href="http://geotiff.maptools.org/rpc_prop.html">
48
RPCs in GeoTIFF</a> proposed extension. The tag is written only for
49
files created with the default profile GDALGeoTIFF. For other profiles, a .RPB file
50
is created. In GDAL data model, the RPC coefficients are stored into the RPC metadata domain.
51
For more details, see the <a href="http://trac.osgeo.org/gdal/wiki/rfc22_rpc">RPC Georeferencing RFC</a>.
52
If .RPB or _RPC.TXT files are found, they will be used to read the RPCs, even if the <i>RPCCoefficientTag</i> tag is set.
55
<h2><a name="internal_mask">Internal nodata masks</a></h2>
57
<p>(from GDAL 1.6.0)</p>
59
<p>TIFF files can contain internal transparency masks. The GeoTIFF driver
48
60
recognizes an internal directory as being a transparency mask when the
49
61
FILETYPE_MASK bit value is set on the TIFFTAG_SUBFILETYPE tag.
50
62
According to the TIFF specification, such internal transparency masks
52
64
for higher resolutions for the internal transparency mask, the GeoTIFF
53
65
driver only supports internal transparency masks of the same dimensions
54
66
as the main image. Transparency masks of internal overviews are also
57
When the GDAL_TIFF_INTERNAL_MASK environment variable is set to YES and
69
<p>When the GDAL_TIFF_INTERNAL_MASK configuration option is set to YES and
58
70
the GeoTIFF file is opened in update mode, the CreateMaskBand() method
59
71
on a TIFF dataset or rasterband will create an internal transparency mask.
60
72
Otherwise, the default behaviour of nodata mask creation will be used,
61
73
that is to say the creation of a .msk file, as per
62
<a href="http://trac.osgeo.org/gdal/wiki/rfc15_nodatabitmask">RFC 15</a><p>
66
The GeoTIFF driver supports reading, creation and update of internal overviews.
74
<a href="http://trac.osgeo.org/gdal/wiki/rfc15_nodatabitmask">RFC 15</a></p>
76
<p>Starting with GDAL 1.8.0, 1-bit internal mask band are deflate compressed.
77
When reading them back, to make conversion between mask band and alpha band easier,
78
mask bands are exposed to the user as being promoted to full 8 bits (i.e. the
79
value for unmasked pixels is 255) unless the GDAL_TIFF_INTERNAL_MASK_TO_8BIT
80
configuration option is set to NO. This does not affect the way the mask band is
81
written (it is always 1-bit).</p>
83
<h2><a name="overviews"Overviews</a></h2>
85
<p>The GeoTIFF driver supports reading, creation and update of internal overviews.
67
86
Internal overviews can be created on GeoTIFF files opened in update mode
68
87
(with gdaladdo for instance). If the GeoTIFF file is opened as read only,
69
88
the creation of overviews will be done in an external .ovr file.
70
Overview are only updated on request with the BuildOverviews() method.<p>
89
Overview are only updated on request with the BuildOverviews() method.</p>
72
(From GDAL 1.6.0) If a GeoTIFF file has a transparency mask and the GDAL_TIFF_INTERNAL_MASK
91
<p>(From GDAL 1.6.0) If a GeoTIFF file has a transparency mask and the GDAL_TIFF_INTERNAL_MASK
73
92
environment variable is set to YES and the GeoTIFF file is opened in update mode,
74
93
BuildOverviews() will automatically create overviews for the internal transparency mask.
75
94
These overviews will be refreshed by further calls to BuildOverviews() even if
76
GDAL_TIFF_INTERNAL_MASK is not set to YES.<p>
95
GDAL_TIFF_INTERNAL_MASK is not set to YES.</p>
97
<p>(From GDAL 1.8.0) The block size (tile width and height) used for overviews
98
(internal or external) can be specified by setting the GDAL_TIFF_OVR_BLOCKSIZE
99
environment variable to a power-of-two value between 64 and 4096. The default value is 128.</p>
103
<p>GDAL can deal with the following baseline TIFF tags as dataset-level metadata :</p>
105
<li>TIFFTAG_DOCUMENTNAME</li>
106
<li>TIFFTAG_IMAGEDESCRIPTION</li>
107
<li>TIFFTAG_SOFTWARE</li>
108
<li>TIFFTAG_DATETIME</li>
109
<li>TIFFTAG_ARTIST</li>
110
<li>TIFFTAG_HOSTCOMPUTER</li>
111
<li>TIFFTAG_COPYRIGHT</li>
112
<li>TIFFTAG_XRESOLUTION</li>
113
<li>TIFFTAG_YRESOLUTION</li>
114
<li>TIFFTAG_RESOLUTIONUNIT</li>
115
<li>TIFFTAG_MINSAMPLEVALUE (read only)</li>
116
<li>TIFFTAG_MAXSAMPLEVALUE (read only)</li>
119
<p>The name of the metadata item to use is one of the above names ("TIFFTAG_DOCUMENTNAME", ...).</p>
121
<p>Other non standard metadata items can be stored in a TIFF file created with the profile GDALGeoTIFF
122
(the default, see below in the Creation issues section). Those metadata items are grouped together
123
into a XML string stored in the non standard TIFFTAG_GDAL_METADATA ASCII tag (code 42112). When BASELINE
124
or GeoTIFF profile are used, those non standard metadata items are stored into a PAM .aux.xml file.</p>
126
<p>The value of GDALMD_AREA_OR_POINT ("AREA_OR_POINT") metadata item is stored in the GeoTIFF key
127
RasterPixelIsPoint for GDALGeoTIFF or GeoTIFF profiles.</p>
129
<p>Starting with GDAL 1.9.0, XMP metadata can be extracted from the file, and will be
130
stored as XML raw content in the xml:XMP metadata domain.</p>
132
<h2>Nodata value</h2>
134
<p>GDAL stores band nodata value in the non standard TIFFTAG_GDAL_NODATA ASCII tag (code 42113) for
135
files created with the default profile GDALGeoTIFF. Note that all bands must use the same nodata value.
136
When BASELINE or GeoTIFF profile are used, the nodata value is stored into a PAM .aux.xml file.</p>
78
138
<h2>Creation Issues</h2>
80
GeoTIFF files can be created with any GDAL defined band type, including
140
<p>GeoTIFF files can be created with any GDAL defined band type, including
81
141
the complex types. Created files may have any number of bands. Files
82
142
with exactly 3 bands will be
83
143
given a photometric interpretation of RGB, files with exactly four bands
84
144
will have a photometric interpretation of RGBA, while all other combinations
85
145
will have a photometric interpretation of MIN_IS_WHITE. Files with
86
146
pseudo-color tables, or GCPs can currently only be created when creating from
87
an existing GDAL dataset with those objects (GDALDriver::CreateCopy()).<p>
147
an existing GDAL dataset with those objects (GDALDriver::CreateCopy()).</p>
89
Note that the GeoTIFF format does not support parametric description of datums,
90
so TOWGS84 parameters in coordinate systems are lost in GeoTIFF format.<p>
149
<p>Note that the GeoTIFF format does not support parametric description of datums,
150
so TOWGS84 parameters in coordinate systems are lost in GeoTIFF format.</p>
92
152
<h3>Creation Options</h3>
96
<li> <b>TFW=YES</b>: Force the generation of an associated ESRI world
156
<li><p><b>TFW=YES</b>: Force the generation of an associated ESRI world
97
157
file (.tfw).See a <a href="frmt_various.html#WLD">World Files</a> section
158
for details.</p></li>
100
<li> <b>INTERLEAVE=[BAND,PIXEL]</b>: By default TIFF files with pixel
160
<li><p><b>INTERLEAVE=[BAND,PIXEL]</b>: By default TIFF files with pixel
101
161
interleaving (PLANARCONFIG_CONTIG in TIFF terminology) are created. These
102
162
are slightly less efficient than BAND interleaving for some purposes, but
103
some applications only support pixel interleaved TIFF files.<p>
105
<li> <b>TILED=YES</b>: By default stripped TIFF files are created. This
106
option can be used to force creation of tiled TIFF files.<p>
108
<li> <b>BLOCKXSIZE=n</b>: Sets tile width, defaults to 256.<p>
110
<li> <b>BLOCKYSIZE=n</b>: Set tile or strip height. Tile height defaults to
111
256, strip height defaults to a value such that one strip is 8K or less. <p>
113
<li> <b>NBITS=n</b>: Create a file with less than 8 bits per sample by passing a value from 1 to 7. The apparent pixel type should be Byte. From GDAL 1.6.0, values of n=9...15 (UInt16 type) and n=17...31 (UInt32 type) are also accepted. <p>
115
<li> <b>COMPRESS=[JPEG/LZW/PACKBITS/DEFLATE/CCITTRLE/CCITTFAX3/CCITTFAX4/NONE]</b>:
163
some applications only support pixel interleaved TIFF files.</p></li>
165
<li><p><b>TILED=YES</b>: By default stripped TIFF files are created. This
166
option can be used to force creation of tiled TIFF files.</p></li>
168
<li><p><b>BLOCKXSIZE=n</b>: Sets tile width, defaults to 256.</p></li>
170
<li><p><b>BLOCKYSIZE=n</b>: Set tile or strip height. Tile height defaults to
171
256, strip height defaults to a value such that one strip is 8K or less. </p></li>
173
<li><p><b>NBITS=n</b>: Create a file with less than 8 bits per sample by passing a value from 1 to 7. The apparent pixel type should be Byte. From GDAL 1.6.0, values of n=9...15 (UInt16 type) and n=17...31 (UInt32 type) are also accepted. </p></li>
175
<li><p><b>COMPRESS=[JPEG/LZW/PACKBITS/DEFLATE/CCITTRLE/CCITTFAX3/CCITTFAX4/NONE]</b>:
116
176
Set the compression to use. JPEG should generally only be used with Byte data (8 bit per channel).
117
177
But starting with GDAL 1.7.0 and provided that GDAL is built with internal libtiff and libjpeg,
118
178
it is possible to read and write TIFF files with 12bit JPEG compressed TIFF files (seen as UInt16 bands with NBITS=12).
119
See the <a href="12bit JPEG compressed TIFF files">"8 and 12 bit JPEG in TIFF"</a> wiki page for more details.
179
See the <a href="http://trac.osgeo.org/gdal/wiki/TIFF12BitJPEG">"8 and 12 bit JPEG in TIFF"</a> wiki page for more details.
120
180
The CCITT compression should only be used with 1bit (NBITS=1) data. None is the
123
<li> <b>PREDICTOR=[1/2/3]</b>: Set the predictor for LZW or DEFLATE compression. The default is 1 (no predictor), 2 is horizontal differencing and 3 is floating point prediction.<p>
125
<li> <b>SPARSE_OK=TRUE/FALSE</b> (From GDAL 1.6.0): Should newly created files be allowed to be sparse? Sparse files have 0 tile/strip offsets for blocks never written and save space; however, most non-GDAL packages cannot read such files. The default is FALSE.<p>
127
<li> <b>JPEG_QUALITY=[1-100]</b>: Set the JPEG quality when using JPEG compression. A value of 100 is best quality (least compression), and 1 is worst quality (best compression). The default is 75.<p>
129
<li> <b>ZLEVEL=[1-9]</b>: Set the level of compression when using DEFLATE compression. A value of 9 is best, and 1 is least compression. The default is 6.<p>
132
<b>PHOTOMETRIC=[MINISBLACK/MINISWHITE/RGB/CMYK/YCBCR/CIELAB/ICCLAB/ITULAB]</b>:
183
<li><p><b>PREDICTOR=[1/2/3]</b>: Set the predictor for LZW or DEFLATE compression. The default is 1 (no predictor), 2 is horizontal differencing and 3 is floating point prediction.</p></li>
185
<li><p><b>SPARSE_OK=TRUE/FALSE</b> (From GDAL 1.6.0): Should newly created files be allowed to be sparse? Sparse files have 0 tile/strip offsets for blocks never written and save space; however, most non-GDAL packages cannot read such files. The default is FALSE.</p></li>
187
<li><p><b>JPEG_QUALITY=[1-100]</b>: Set the JPEG quality when using JPEG compression. A value of 100 is best quality (least compression), and 1 is worst quality (best compression). The default is 75.</p></li>
189
<li><p><b>ZLEVEL=[1-9]</b>: Set the level of compression when using DEFLATE compression. A value of 9 is best, and 1 is least compression. The default is 6.</p></li>
191
<li><p><b>PHOTOMETRIC=[MINISBLACK/MINISWHITE/RGB/CMYK/YCBCR/CIELAB/ICCLAB/ITULAB]</b>:
133
192
Set the photometric interpretation tag. Default is MINISBLACK, but if the
134
193
input image has 3 or 4 bands of Byte type, then RGB will be selected. You can
135
override default photometric using this option.<p>
194
override default photometric using this option.</p></li>
137
<li> <b>ALPHA=YES</b>: The first "extrasample" is marked as being alpha if
196
<li><p><b>ALPHA=YES</b>: The first "extrasample" is marked as being alpha if
138
197
there are any extra samples. This is necessary if you want to produce
139
a greyscale TIFF file with an alpha band (for instance). <p>
198
a greyscale TIFF file with an alpha band (for instance). </p></li>
141
<li> <b>PROFILE=[GDALGeoTIFF/GeoTIFF/BASELINE]</b>: Control what non-baseline
142
tags are emitted by GDAL.
200
<li><p><b>PROFILE=[GDALGeoTIFF/GeoTIFF/BASELINE]</b>: Control what non-baseline
201
tags are emitted by GDAL.</p>
144
203
<li>With <tt>GDALGeoTIFF</tt> (the default) various GDAL custom tags may be written.</li>
145
204
<li>With <tt>GeoTIFF</tt> only GeoTIFF tags will be added to the baseline.</li>
146
205
<li>With <tt>BASELINE</tt> no GDAL or GeoTIFF tags will be written. BASELINE is occationally useful when writing files to
147
206
be read by applications intolerant of unrecognised tags.</li>
151
<li> <b>BIGTIFF=YES/NO/IF_NEEDED/IF_SAFER</b>: Control whether the created file is a BigTIFF or a classic TIFF.
210
<li><p><b>BIGTIFF=YES/NO/IF_NEEDED/IF_SAFER</b>: Control whether the created file is a BigTIFF or a classic TIFF.</p>
153
212
<li>YES forces BigTIFF.</li>
154
213
<li>NO forces classic TIFF.</li>
155
214
<li>IF_NEEDED will only create a BigTIFF if it is clearly needed (uncompressed, and image larger than 4GB).</li>
156
215
<li>IF_SAFER will create BigTIFF if the resulting file *might* exceed 4GB.</li>
158
BigTIFF is a TIFF variant which can contain more than 4GiB of data (size of classic TIFF is limited by that value). This option is available if GDAL is built with libtiff library version 4.0 or higher (which is the case of the internal libtiff version from GDAL >= 1.5.0). The default is IF_NEEDED. (IF_NEEDED and IF_SAFER are available from GDAL 1.6.0).<p>
159
When creating a new GeoTIFF with no compression, GDAL computes in advance the
217
<p>BigTIFF is a TIFF variant which can contain more than 4GiB of data (size of classic TIFF is limited by that value). This option is available if GDAL is built with libtiff library version 4.0 or higher (which is the case of the internal libtiff version from GDAL >= 1.5.0). The default is IF_NEEDED. (IF_NEEDED and IF_SAFER are available from GDAL 1.6.0).</p>
218
<p>When creating a new GeoTIFF with no compression, GDAL computes in advance the
160
219
size of the resulting file. If that computed file size is over 4GiB, GDAL will automatically
161
220
decide to create a BigTIFF file. However, when compression is used, it is not possible in
162
221
advance to known the final size of the file, so classical TIFF will be chosen. In
163
222
that case, the user must explicitely require the creation of a BigTIFF with BIGTIFF=YES
164
223
if he anticipates the final file to be too big for classical TIFF format.
165
224
If BigTIFF creation is not explicitely asked or guessed and that the resulting file is too big for classical TIFF,
166
libtiff will fail with an error message like "TIFFAppendToStrip:Maximum TIFF file size exceeded".<p>
225
libtiff will fail with an error message like "TIFFAppendToStrip:Maximum TIFF file size exceeded".</p></li>
168
<li> <b>PIXELTYPE=[DEFAULT/SIGNEDBYTE]</b>: By setting this to SIGNEDBYTE, a
169
new Byte file can be forced to be written as signed byte.<p>
227
<li><p><b>PIXELTYPE=[DEFAULT/SIGNEDBYTE]</b>: By setting this to SIGNEDBYTE, a
228
new Byte file can be forced to be written as signed byte.</p></li>
171
230
<!-- Commented for the moment. Not sure we want to advertize that
172
231
<li> <b>ENDIANNESS=[NATIVE/INVERTED/LITTLE/BIG]</b>: Set the endianness of the
174
233
used. Primarily intended for debugging & test purposes</p>
236
<li><p><b>COPY_SRC_OVERVIEWS=[YES/NO]</b>: (GDAL >= 1.8.0, CreateCopy() only) By setting this to YES (default is NO), the potential existing overviews
237
of the source dataset will be copied to the target dataset without being recomputed. If overviews of mask band
238
also exist, provided that the GDAL_TIFF_INTERNAL_MASK configuration option is set to YES, they will also be copied.
239
Note that this creation option will have <a href="http://trac.osgeo.org/gdal/ticket/3917">no effect</a> if general options
240
(i.e. options which are not creation options) of gdal_translate are used.</p></li>
179
244
<h3>About JPEG compression of RGB images </h3>
181
When translating a RGB image to JPEG-In-TIFF, using PHOTOMETRIC=YCBCR can make the size
246
<p>When translating a RGB image to JPEG-In-TIFF, using PHOTOMETRIC=YCBCR can make the size
182
247
of the image typically 2 to 3 times smaller than the default photometric value (RGB).
183
248
When using PHOTOMETRIC=YCBCR, the INTERLEAVE option must be kept to its default value (PIXEL),
184
otherwise libtiff will fail to compress the data.
186
Note also that the dimensions of the tiles or strips must be a multiple of 8 for PHOTOMETRIC=RGB or 16 for PHOTOMETRIC=YCBCR
249
otherwise libtiff will fail to compress the data.</p>
251
Note also that the dimensions of the tiles or strips must be a multiple of 8 for PHOTOMETRIC=RGB or 16 for PHOTOMETRIC=YCBCR</p>
253
<h3>Configuration options</h3>
257
This paragraph lists the configuration options that can be set to alter the default behaviour of the GTiff driver.
260
<!-- debug/autotest option : GTIFF_DONT_WRITE_BLOCKS -->
261
<li>GTIFF_IGNORE_READ_ERRORS : (GDAL >= 1.9.0) Can be set to TRUE to avoid turning libtiff errors into GDAL errors.
262
Can help reading partially corrupted TIFF files</li>
263
<li>ESRI_XML_PAM: Can be set to TRUE to force metadata in the xml:ESRI domain to be written to PAM.</li>
264
<li>JPEG_QUALITY_OVERVIEW: Integer between 0 and 100. Default value : 75. Quality of JPEG compressed overviews, either internal or external.</li>
265
<li>GDAL_TIFF_INTERNAL_MASK: See <a href="#internal_mask"><i>Internal nodata masks</i> section</a>. Default value : FALSE.</li>
266
<li>GDAL_TIFF_INTERNAL_MASK_TO_8BIT: See <a href="#internal_mask"><i>Internal nodata masks</i> section</a>. Default value : TRUE</li>
267
<li>USE_RRD: Can be set to TRUE to force external overviews in the RRD format. Default value : FALSE</li>
268
<li>TIFF_USE_OVR: Can be set to TRUE to force external overviews in the GeoTIFF (.ovr) format. Default value : FALSE</li>
269
<li>GTIFF_POINT_GEO_IGNORE: Can be set to TRUE to revert back to the behaviour of GDAL < 1.8.0
270
regarding how PixelIsPoint is interprated w.r.t geotransform. See <a href="http://trac.osgeo.org/gdal/wiki/rfc33_gtiff_pixelispoint">
271
RFC 33: GTiff - Fixing PixelIsPoint Interpretation</a> for more details. Default value : FALSE</li>
272
<li>GTIFF_REPORT_COMPD_CS: (GDAL >= 1.9.0). Can be set to TRUE to avoid stripping the vertical CS of compound CS. Default value : FALSE</li>
273
<li>GDAL_ENABLE_TIFF_SPLIT : Can be set to FALSE to avoid all-in-one-strip files being presented as having. Default value : TRUE</li>
274
<!-- debug option : <li>GDAL_TIFF_ENDIANNESS : Possible values : LITTLE, BIG, INVERTED, NATIVE. Default value : NATIVE</li> -->
275
<!-- not sure it is wise to advertize this one. I doubt it works correctly if set to NO. CONVERT_YCBCR_TO_RGB -->
276
<!-- debug/autotest option : GTIFF_DELETE_ON_ERROR -->
277
<li>GDAL_TIFF_OVR_BLOCKSIZE : See <a href="#overviews"><i>Overviews</i> section</a>.
278
<li> GTIFF_LINEAR_UNITS: Can be set to BROKEN to read GeoTIFF files that
279
have false easting/northing improperly set in meters when it ought to be in
280
coordinate system linear units. (<a href="http://trac.osgeo.org/gdal/ticket/3901">Ticket #3901</a>).
193
<li> <a href="http://www.remotesensing.org/geotiff/geotiff.html">GeoTIFF Information Page</a>
194
<li> <a href="http://www.remotesensing.org/libtiff/">libtiff Page</a>
289
<li> <a href="http://www.remotesensing.org/geotiff/geotiff.html">GeoTIFF Information Page</a></li>
290
<li> <a href="http://www.remotesensing.org/libtiff/">libtiff Page</a></li>
195
291
<li> <a href="http://www.awaresystems.be/imaging/tiff/bigtiff.html">
196
Details on BigTIFF file format</a>
292
Details on BigTIFF file format</a></li>