projects / wxWidgets.git / blame
| Commit | Line | Data |
|---|---|---|
| 8414a40c VZ |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| 2 | <html lang="en"> | |
| 3 | <head> | |
| 4 | <title>Using The TIFF Library</title> | |
| 5 | <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1"> | |
| 6 | <meta http-equiv="content-language" content="en"> | |
| 7 | <style type="text/css"> | |
| 8 | <!-- | |
| 9 | th {text-align: left; vertical-align: top; font-style: italic; font-weight: normal} | |
| 10 | --> | |
| 11 | </style> | |
| 12 | </head> | |
| 13 | <body lang="en" text="#000000" bgcolor="#ffffff" link="#0000ff" alink="#0000ff" vlink="#0000ff"> | |
| 14 | <table border="0" cellspacing="0" cellpadding="0"> | |
| 15 | <tr> | |
| 16 | <td style="padding-left: 1em; padding-right: 1em"><img src="images/cat.gif" width="113" height="146" alt=""></td> | |
| 17 | <td> | |
| 18 | <h1>Using The TIFF Library</h1> | |
| 19 | <p> | |
| 20 | <tt>libtiff</tt> is a set of C functions (a library) that support | |
| 21 | the manipulation of TIFF image files. | |
| 22 | The library requires an ANSI C compilation environment for building | |
| 23 | and presumes an ANSI C environment for use. | |
| 24 | </p> | |
| 25 | </td> | |
| 26 | </tr> | |
| 27 | </table> | |
| 28 | <br> | |
| 29 | <p> | |
| 30 | <tt>libtiff</tt> | |
| 31 | provides interfaces to image data at several layers of abstraction (and cost). | |
| 32 | At the highest level image data can be read into an 8-bit/sample, | |
| 33 | ABGR pixel raster format without regard for the underlying data organization, | |
| 34 | colorspace, or compression scheme. Below this high-level interface | |
| 35 | the library provides scanline-, strip-, and tile-oriented interfaces that | |
| 36 | return data decompressed but otherwise untransformed. These interfaces | |
| 37 | require that the application first identify the organization of stored | |
| 38 | data and select either a strip-based or tile-based API for manipulating | |
| 39 | data. At the lowest level the library | |
| 40 | provides access to the raw uncompressed strips or tiles, | |
| 41 | returning the data exactly as it appears in the file. | |
| 42 | </p> | |
| 43 | <p> | |
| 44 | The material presented in this chapter is a basic introduction | |
| 45 | to the capabilities of the library; it is not an attempt to describe | |
| 46 | everything a developer needs to know about the library or about TIFF. | |
| 47 | Detailed information on the interfaces to the library are given in | |
| 48 | the <a href="http://www.remotesensing.org/libtiff/man/index.html">UNIX | |
| 49 | manual pages</a> that accompany this software. | |
| 50 | </p> | |
| 51 | <p> | |
| 52 | Michael Still has also written a useful introduction to libtiff for the | |
| 53 | IBM DeveloperWorks site available at | |
| 54 | <a href="http://www.ibm.com/developerworks/linux/library/l-libtiff">http://www.ibm.com/developerworks/linux/library/l-libtiff</a>. | |
| 55 | </p> | |
| 56 | <p> | |
| 57 | The following sections are found in this chapter: | |
| 58 | </p> | |
| 59 | <ul> | |
| 60 | <li><a href="#version">How to tell which version you have</a></li> | |
| 61 | <li><a href="#typedefs">Library Datatypes</a></li> | |
| 62 | <li><a href="#mman">Memory Management</a></li> | |
| 63 | <li><a href="#errors">Error Handling</a></li> | |
| 64 | <li><a href="#fio">Basic File Handling</a></li> | |
| 65 | <li><a href="#dirs">TIFF Directories</a></li> | |
| 66 | <li><a href="#tags">TIFF Tags</a></li> | |
| 67 | <li><a href="#compression">TIFF Compression Schemes</a></li> | |
| 68 | <li><a href="#byteorder">Byte Order</a></li> | |
| 69 | <li><a href="#dataplacement">Data Placement</a></li> | |
| 70 | <li><a href="#tiffrgbaimage">TIFFRGBAImage Support</a></li> | |
| 71 | <li><a href="#scanlines">Scanline-based Image I/O</a></li> | |
| 72 | <li><a href="#strips">Strip-oriented Image I/O</a></li> | |
| 73 | <li><a href="#tiles">Tile-oriented Image I/O</a></li> | |
| 74 | <li><a href="#other">Other Stuff</a></li> | |
| 75 | </ul> | |
| 76 | <hr> | |
| 77 | <h2 id="version">How to tell which version you have</h2> | |
| 78 | <p> | |
| 79 | The software version can be found by looking at the file named | |
| 80 | <tt>VERSION</tt> | |
| 81 | that is located at the top of the source tree; the precise alpha number | |
| 82 | is given in the file <tt>dist/tiff.alpha</tt>. | |
| 83 | If you have need to refer to this | |
| 84 | specific software, you should identify it as: | |
| 85 | </p> | |
| 86 | <p style="margin-left: 40px"> | |
| 87 | <tt>TIFF <<i>version</i>> <<i>alpha</i>></tt> | |
| 88 | </p> | |
| 89 | <p> | |
| 90 | where <tt><<i>version</i>></tt> is whatever you get from | |
| 91 | <tt>"cat VERSION"</tt> and <tt><<i>alpha</i>></tt> is | |
| 92 | what you get from <tt>"cat dist/tiff.alpha"</tt>. | |
| 93 | </p> | |
| 94 | <p> | |
| 95 | Within an application that uses <tt>libtiff</tt> the <tt>TIFFGetVersion</tt> | |
| 96 | routine will return a pointer to a string that contains software version | |
| 97 | information. | |
| 98 | The library include file <tt><tiffio.h></tt> contains a C pre-processor | |
| 99 | define <tt>TIFFLIB_VERSION</tt> that can be used to check library | |
| 100 | version compatiblity at compile time. | |
| 101 | </p> | |
| 102 | <hr> | |
| 103 | <h2 id="typedefs">Library Datatypes</h2> | |
| 104 | <p> | |
| 105 | <tt>libtiff</tt> defines a portable programming interface through the | |
| 106 | use of a set of C type definitions. | |
| 107 | These definitions, defined in in the files <b>tiff.h</b> and | |
| 108 | <b>tiffio.h</b>, | |
| 109 | isolate the <tt>libtiff</tt> API from the characteristics | |
| 110 | of the underlying machine. | |
| 111 | To insure portable code and correct operation, applications that use | |
| 112 | <tt>libtiff</tt> should use the typedefs and follow the function | |
| 113 | prototypes for the library API. | |
| 114 | </p> | |
| 115 | <hr> | |
| 116 | <h2 id="mman">Memory Management</h2> | |
| 117 | <p> | |
| 118 | <tt>libtiff</tt> uses a machine-specific set of routines for managing | |
| 119 | dynamically allocated memory. | |
| 120 | <tt>_TIFFmalloc</tt>, <tt>_TIFFrealloc</tt>, and <tt>_TIFFfree</tt> | |
| 121 | mimic the normal ANSI C routines. | |
| 122 | Any dynamically allocated memory that is to be passed into the library | |
| 123 | should be allocated using these interfaces in order to insure pointer | |
| 124 | compatibility on machines with a segmented architecture. | |
| 125 | (On 32-bit UNIX systems these routines just call the normal <tt>malloc</tt>, | |
| 126 | <tt>realloc</tt>, and <tt>free</tt> routines in the C library.) | |
| 127 | </p> | |
| 128 | <p> | |
| 129 | To deal with segmented pointer issues <tt>libtiff</tt> also provides | |
| 130 | <tt>_TIFFmemcpy</tt>, <tt>_TIFFmemset</tt>, and <tt>_TIFFmemmove</tt> | |
| 131 | routines that mimic the equivalent ANSI C routines, but that are | |
| 132 | intended for use with memory allocated through <tt>_TIFFmalloc</tt> | |
| 133 | and <tt>_TIFFrealloc</tt>. | |
| 134 | </p> | |
| 135 | <hr> | |
| 136 | <h2 id="errors">Error Handling</h2> | |
| 137 | <p> | |
| 138 | <tt>libtiff</tt> handles most errors by returning an invalid/erroneous | |
| 139 | value when returning from a function call. | |
| 140 | Various diagnostic messages may also be generated by the library. | |
| 141 | All error messages are directed to a single global error handler | |
| 142 | routine that can be specified with a call to <tt>TIFFSetErrorHandler</tt>. | |
| 143 | Likewise warning messages are directed to a single handler routine | |
| 144 | that can be specified with a call to <tt>TIFFSetWarningHandler</tt> | |
| 145 | </p> | |
| 146 | <hr> | |
| 147 | <h2 id="fio">Basic File Handling</h2> | |
| 148 | <p> | |
| 149 | The library is modeled after the normal UNIX stdio library. | |
| 150 | For example, to read from an existing TIFF image the | |
| 151 | file must first be opened: | |
| 152 | </p> | |
| 153 | <p style="margin-left: 40px"> | |
| 154 | <tt>#include "tiffio.h"<br> | |
| 155 | main()<br> | |
| 156 | {<br> | |
| 157 | TIFF* tif = TIFFOpen("foo.tif", "r");<br> | |
| 158 | ... do stuff ...<br> | |
| 159 | TIFFClose(tif);<br> | |
| 160 | }</tt> | |
| 161 | </p> | |
| 162 | <p> | |
| 163 | The handle returned by <tt>TIFFOpen</tt> is <i>opaque</i>, that is | |
| 164 | the application is not permitted to know about its contents. | |
| 165 | All subsequent library calls for this file must pass the handle | |
| 166 | as an argument. | |
| 167 | </p> | |
| 168 | <p> | |
| 169 | To create or overwrite a TIFF image the file is also opened, but with | |
| 170 | a <tt>"w"</tt> argument: | |
| 171 | <p> | |
| 172 | <p style="margin-left: 40px"> | |
| 173 | <tt>#include "tiffio.h"<br> | |
| 174 | main()<br> | |
| 175 | {<br> | |
| 176 | TIFF* tif = TIFFOpen("foo.tif", "w");<br> | |
| 177 | ... do stuff ...<br> | |
| 178 | TIFFClose(tif);<br> | |
| 179 | }</tt> | |
| 180 | </p> | |
| 181 | <p> | |
| 182 | If the file already exists it is first truncated to zero length. | |
| 183 | </p> | |
| 184 | <table> | |
| 185 | <tr> | |
| 186 | <td valign=top><img src="images/warning.gif" width="40" height="40" alt=""></td> | |
| 187 | <td><i>Note that unlike the stdio library TIFF image files may not be | |
| 188 | opened for both reading and writing; | |
| 189 | there is no support for altering the contents of a TIFF file.</i></td> | |
| 190 | </tr> | |
| 191 | </table> | |
| 192 | <p> | |
| 193 | <tt>libtiff</tt> buffers much information associated with writing a | |
| 194 | valid TIFF image. Consequently, when writing a TIFF image it is necessary | |
| 195 | to always call <tt>TIFFClose</tt> or <tt>TIFFFlush</tt> to flush any | |
| 196 | buffered information to a file. Note that if you call <tt>TIFFClose</tt> | |
| 197 | you do not need to call <tt>TIFFFlush</tt>. | |
| 198 | </p> | |
| 199 | <hr> | |
| 200 | <h2 id="dirs">TIFF Directories</h2> | |
| 201 | <p> | |
| 202 | TIFF supports the storage of multiple images in a single file. | |
| 203 | Each image has an associated data structure termed a <i>directory</i> | |
| 204 | that houses all the information about the format and content of the | |
| 205 | image data. | |
| 206 | Images in a file are usually related but they do not need to be; it | |
| 207 | is perfectly alright to store a color image together with a black and | |
| 208 | white image. | |
| 209 | Note however that while images may be related their directories are | |
| 210 | not. | |
| 211 | That is, each directory stands on its own; their is no need to read | |
| 212 | an unrelated directory in order to properly interpret the contents | |
| 213 | of an image. | |
| 214 | </p> | |
| 215 | <p> | |
| 216 | <tt>libtiff</tt> provides several routines for reading and writing | |
| 217 | directories. In normal use there is no need to explicitly | |
| 218 | read or write a directory: the library automatically reads the first | |
| 219 | directory in a file when opened for reading, and directory information | |
| 220 | to be written is automatically accumulated and written when writing | |
| 221 | (assuming <tt>TIFFClose</tt> or <tt>TIFFFlush</tt> are called). | |
| 222 | </p> | |
| 223 | <p> | |
| 224 | For a file open for reading the <tt>TIFFSetDirectory</tt> routine can | |
| 225 | be used to select an arbitrary directory; directories are referenced by | |
| 226 | number with the numbering starting at 0. Otherwise the | |
| 227 | <tt>TIFFReadDirectory</tt> and <tt>TIFFWriteDirectory</tt> routines can | |
| 228 | be used for sequential access to directories. | |
| 229 | For example, to count the number of directories in a file the following | |
| 230 | code might be used: | |
| 231 | </p> | |
| 232 | <p style="margin-left: 40px"> | |
| 233 | <tt>#include "tiffio.h"<br> | |
| 234 | main(int argc, char* argv[])<br> | |
| 235 | {<br> | |
| 236 | TIFF* tif = TIFFOpen(argv[1], "r");<br> | |
| 237 | if (tif) {<br> | |
| 238 | int dircount = 0;<br> | |
| 239 | do {<br> | |
| 240 | dircount++;<br> | |
| 241 | } while (TIFFReadDirectory(tif));<br> | |
| 242 | printf("%d directories in %s\n", dircount, argv[1]);<br> | |
| 243 | TIFFClose(tif);<br> | |
| 244 | }<br> | |
| 245 | exit(0);<br> | |
| 246 | }</tt> | |
| 247 | </p> | |
| 248 | <p> | |
| 249 | Finally, note that there are several routines for querying the | |
| 250 | directory status of an open file: | |
| 251 | <tt>TIFFCurrentDirectory</tt> returns the index of the current | |
| 252 | directory and | |
| 253 | <tt>TIFFLastDirectory</tt> returns an indication of whether the | |
| 254 | current directory is the last directory in a file. | |
| 255 | There is also a routine, <tt>TIFFPrintDirectory</tt>, that can | |
| 256 | be called to print a formatted description of the contents of | |
| 257 | the current directory; consult the manual page for complete details. | |
| 258 | </p> | |
| 259 | <hr> | |
| 260 | <h2 id="tags">TIFF Tags</h2> | |
| 261 | <p> | |
| 262 | Image-related information such as the image width and height, number | |
| 263 | of samples, orientation, colorimetric information, etc. | |
| 264 | are stored in each image | |
| 265 | directory in <i>fields</i> or <i>tags</i>. | |
| 266 | Tags are identified by a number that is usually a value registered | |
| 267 | with the Aldus (now Adobe) Corporation. | |
| 268 | Beware however that some vendors write | |
| 269 | TIFF images with tags that are unregistered; in this case interpreting | |
| 270 | their contents is usually a waste of time. | |
| 271 | </p> | |
| 272 | <p> | |
| 273 | <tt>libtiff</tt> reads the contents of a directory all at once | |
| 274 | and converts the on-disk information to an appropriate in-memory | |
| 275 | form. While the TIFF specification permits an arbitrary set of | |
| 276 | tags to be defined and used in a file, the library only understands | |
| 277 | a limited set of tags. | |
| 278 | Any unknown tags that are encountered in a file are ignored. | |
| 279 | There is a mechanism to extend the set of tags the library handles | |
| 280 | without modifying the library itself; | |
| 281 | this is described <a href="addingtags.html">elsewhere</a>. | |
| 282 | </p> | |
| 283 | <p> | |
| 284 | <tt>libtiff</tt> provides two interfaces for getting and setting tag | |
| 285 | values: <tt>TIFFGetField</tt> and <tt>TIFFSetField</tt>. | |
| 286 | These routines use a variable argument list-style interface to pass | |
| 287 | parameters of different type through a single function interface. | |
| 288 | The <i>get interface</i> takes one or more pointers to memory locations | |
| 289 | where the tag values are to be returned and also returns one or | |
| 290 | zero according to whether the requested tag is defined in the directory. | |
| 291 | The <i>set interface</i> takes the tag values either by-reference or | |
| 292 | by-value. | |
| 293 | The TIFF specification defines | |
| 294 | <i>default values</i> for some tags. | |
| 295 | To get the value of a tag, or its default value if it is undefined, | |
| 296 | the <tt>TIFFGetFieldDefaulted</tt> interface may be used. | |
| 297 | </p> | |
| 298 | <p> | |
| 299 | The manual pages for the tag get and set routines specifiy the exact data types | |
| 300 | and calling conventions required for each tag supported by the library. | |
| 301 | </p> | |
| 302 | <hr> | |
| 303 | <h2 id="compression">TIFF Compression Schemes</h2> | |
| 304 | <p> | |
| 305 | <tt>libtiff</tt> includes support for a wide variety of | |
| 306 | data compression schemes. | |
| 307 | In normal operation a compression scheme is automatically used when | |
| 308 | the TIFF <tt>Compression</tt> tag is set, either by opening a file | |
| 309 | for reading, or by setting the tag when writing. | |
| 310 | </p> | |
| 311 | <p> | |
| 312 | Compression schemes are implemented by software modules termed <i>codecs</i> | |
| 313 | that implement decoder and encoder routines that hook into the | |
| 314 | core library i/o support. | |
| 315 | Codecs other than those bundled with the library can be registered | |
| 316 | for use with the <tt>TIFFRegisterCODEC</tt> routine. | |
| 317 | This interface can also be used to override the core-library | |
| 318 | implementation for a compression scheme. | |
| 319 | </p> | |
| 320 | <hr> | |
| 321 | <h2 id="byteorder">Byte Order</h2> | |
| 322 | <p> | |
| 323 | The TIFF specification says, and has always said, that | |
| 324 | <em>a correct TIFF | |
| 325 | reader must handle images in big-endian and little-endian byte order</em>. | |
| 326 | <tt>libtiff</tt> conforms in this respect. | |
| 327 | Consequently there is no means to force a specific | |
| 328 | byte order for the data written to a TIFF image file (data is | |
| 329 | written in the native order of the host CPU unless appending to | |
| 330 | an existing file, in which case it is written in the byte order | |
| 331 | specified in the file). | |
| 332 | </p> | |
| 333 | <hr> | |
| 334 | <h2 id="dataplacement">Data Placement</h2> | |
| 335 | <p> | |
| 336 | The TIFF specification requires that all information except an | |
| 337 | 8-byte header can be placed anywhere in a file. | |
| 338 | In particular, it is perfectly legitimate for directory information | |
| 339 | to be written after the image data itself. | |
| 340 | Consequently TIFF is inherently not suitable for passing through a | |
| 341 | stream-oriented mechanism such as UNIX pipes. | |
| 342 | Software that require that data be organized in a file in a particular | |
| 343 | order (e.g. directory information before image data) does not | |
| 344 | correctly support TIFF. | |
| 345 | <tt>libtiff</tt> provides no mechanism for controlling the placement | |
| 346 | of data in a file; image data is typically written before directory | |
| 347 | information. | |
| 348 | </p> | |
| 349 | <hr> | |
| 350 | <h2 id="tiffrgbaimage">TIFFRGBAImage Support</h2> | |
| 351 | <p> | |
| 352 | <tt>libtiff</tt> provides a high-level interface for reading image | |
| 353 | data from a TIFF file. This interface handles the details of | |
| 354 | data organization and format for a wide variety of TIFF files; | |
| 355 | at least the large majority of those files that one would normally | |
| 356 | encounter. Image data is, by default, returned as ABGR | |
| 357 | pixels packed into 32-bit words (8 bits per sample). Rectangular | |
| 358 | rasters can be read or data can be intercepted at an intermediate | |
| 359 | level and packed into memory in a format more suitable to the | |
| 360 | application. | |
| 361 | The library handles all the details of the format of data stored on | |
| 362 | disk and, in most cases, if any colorspace conversions are required: | |
| 363 | bilevel to RGB, greyscale to RGB, CMYK to RGB, YCbCr to RGB, 16-bit | |
| 364 | samples to 8-bit samples, associated/unassociated alpha, etc. | |
| 365 | </p> | |
| 366 | <p> | |
| 367 | There are two ways to read image data using this interface. If | |
| 368 | all the data is to be stored in memory and manipulated at once, | |
| 369 | then the routine <tt>TIFFReadRGBAImage</tt> can be used: | |
| 370 | </p> | |
| 371 | <p> | |
| 372 | <p style="margin-left: 40px"> | |
| 373 | <tt>#include "tiffio.h"<br> | |
| 374 | main(int argc, char* argv[])<br> | |
| 375 | {<br> | |
| 376 | TIFF* tif = TIFFOpen(argv[1], "r");<br> | |
| 377 | if (tif) {<br> | |
| 378 | uint32 w, h;<br> | |
| 379 | size_t npixels;<br> | |
| 380 | uint32* raster;<br> | |
| 381 | <br> | |
| 382 | TIFFGetField(tif, TIFFTAG_IMAGEWIDTH, &w);<br> | |
| 383 | TIFFGetField(tif, TIFFTAG_IMAGELENGTH, &h);<br> | |
| 384 | npixels = w * h;<br> | |
| 385 | raster = (uint32*) _TIFFmalloc(npixels * sizeof (uint32));<br> | |
| 386 | if (raster != NULL) {<br> | |
| 387 | if (TIFFReadRGBAImage(tif, w, h, raster, 0)) {<br> | |
| 388 | ...process raster data...<br> | |
| 389 | }<br> | |
| 390 | _TIFFfree(raster);<br> | |
| 391 | }<br> | |
| 392 | TIFFClose(tif);<br> | |
| 393 | }<br> | |
| 394 | exit(0);<br> | |
| 395 | }</tt> | |
| 396 | </p> | |
| 397 | <p> | |
| 398 | Note above that <tt>_TIFFmalloc</tt> is used to allocate memory for | |
| 399 | the raster passed to <tt>TIFFReadRGBAImage</tt>; this is important | |
| 400 | to insure the ``appropriate type of memory'' is passed on machines | |
| 401 | with segmented architectures. | |
| 402 | </p> | |
| 403 | <p> | |
| 404 | Alternatively, <tt>TIFFReadRGBAImage</tt> can be replaced with a | |
| 405 | more low-level interface that permits an application to have more | |
| 406 | control over this reading procedure. The equivalent to the above | |
| 407 | is: | |
| 408 | </p> | |
| 409 | <p style="margin-left: 40px"> | |
| 410 | <tt>#include "tiffio.h"<br> | |
| 411 | main(int argc, char* argv[])<br> | |
| 412 | {<br> | |
| 413 | TIFF* tif = TIFFOpen(argv[1], "r");<br> | |
| 414 | if (tif) {<br> | |
| 415 | TIFFRGBAImage img;<br> | |
| 416 | char emsg[1024];<br> | |
| 417 | <br> | |
| 418 | if (TIFFRGBAImageBegin(&img, tif, 0, emsg)) {<br> | |
| 419 | size_t npixels;<br> | |
| 420 | uint32* raster;<br> | |
| 421 | <br> | |
| 422 | npixels = img.width * img.height;<br> | |
| 423 | raster = (uint32*) _TIFFmalloc(npixels * sizeof (uint32));<br> | |
| 424 | if (raster != NULL) {<br> | |
| 425 | if (TIFFRGBAImageGet(&img, raster, img.width, img.height)) {<br> | |
| 426 | ...process raster data...<br> | |
| 427 | }<br> | |
| 428 | _TIFFfree(raster);<br> | |
| 429 | }<br> | |
| 430 | TIFFRGBAImageEnd(&img);<br> | |
| 431 | } else<br> | |
| 432 | TIFFError(argv[1], emsg);<br> | |
| 433 | TIFFClose(tif);<br> | |
| 434 | }<br> | |
| 435 | exit(0);<br> | |
| 436 | }</tt> | |
| 437 | </p> | |
| 438 | <p> | |
| 439 | However this usage does not take advantage of the more fine-grained | |
| 440 | control that's possible. That is, by using this interface it is | |
| 441 | possible to: | |
| 442 | </p> | |
| 443 | <ul> | |
| 444 | <li>repeatedly fetch (and manipulate) an image without opening | |
| 445 | and closing the file</li> | |
| 446 | <li>interpose a method for packing raster pixel data according to | |
| 447 | application-specific needs (or write the data at all)</li> | |
| 448 | <li>interpose methods that handle TIFF formats that are not already | |
| 449 | handled by the core library</li> | |
| 450 | </ul> | |
| 451 | <p> | |
| 452 | The first item means that, for example, image viewers that want to | |
| 453 | handle multiple files can cache decoding information in order to | |
| 454 | speedup the work required to display a TIFF image. | |
| 455 | </p> | |
| 456 | <p> | |
| 457 | The second item is the main reason for this interface. By interposing | |
| 458 | a "put method" (the routine that is called to pack pixel data in | |
| 459 | the raster) it is possible share the core logic that understands how | |
| 460 | to deal with TIFF while packing the resultant pixels in a format that | |
| 461 | is optimized for the application. This alternate format might be very | |
| 462 | different than the 8-bit per sample ABGR format the library writes by | |
| 463 | default. For example, if the application is going to display the image | |
| 464 | on an 8-bit colormap display the put routine might take the data and | |
| 465 | convert it on-the-fly to the best colormap indices for display. | |
| 466 | </p> | |
| 467 | <p> | |
| 468 | The last item permits an application to extend the library | |
| 469 | without modifying the core code. | |
| 470 | By overriding the code provided an application might add support | |
| 471 | for some esoteric flavor of TIFF that it needs, or it might | |
| 472 | substitute a packing routine that is able to do optimizations | |
| 473 | using application/environment-specific information. | |
| 474 | </p> | |
| 475 | <p> | |
| 476 | The TIFF image viewer found in <b>tools/sgigt.c</b> is an example | |
| 477 | of an application that makes use of the <tt>TIFFRGBAImage</tt> | |
| 478 | support. | |
| 479 | </p> | |
| 480 | <hr> | |
| 481 | <h2 id="scanlines">Scanline-based Image I/O</h2> | |
| 482 | <p> | |
| 483 | The simplest interface provided by <tt>libtiff</tt> is a | |
| 484 | scanline-oriented interface that can be used to read TIFF | |
| 485 | images that have their image data organized in strips | |
| 486 | (trying to use this interface to read data written in tiles | |
| 487 | will produce errors.) | |
| 488 | A scanline is a one pixel high row of image data whose width | |
| 489 | is the width of the image. | |
| 490 | Data is returned packed if the image data is stored with samples | |
| 491 | packed together, or as arrays of separate samples if the data | |
| 492 | is stored with samples separated. | |
| 493 | The major limitation of the scanline-oriented interface, other | |
| 494 | than the need to first identify an existing file as having a | |
| 495 | suitable organization, is that random access to individual | |
| 496 | scanlines can only be provided when data is not stored in a | |
| 497 | compressed format, or when the number of rows in a strip | |
| 498 | of image data is set to one (<tt>RowsPerStrip</tt> is one). | |
| 499 | </p> | |
| 500 | <p> | |
| 501 | Two routines are provided for scanline-based i/o: | |
| 502 | <tt>TIFFReadScanline</tt> | |
| 503 | and | |
| 504 | <tt>TIFFWriteScanline</tt>. | |
| 505 | For example, to read the contents of a file that | |
| 506 | is assumed to be organized in strips, the following might be used: | |
| 507 | </p> | |
| 508 | <p style="margin-left: 40px"> | |
| 509 | <tt>#include "tiffio.h"<br> | |
| 510 | main()<br> | |
| 511 | {<br> | |
| 512 | TIFF* tif = TIFFOpen("myfile.tif", "r");<br> | |
| 513 | if (tif) {<br> | |
| 514 | uint32 imagelength;<br> | |
| 515 | tdata_t buf;<br> | |
| 516 | uint32 row;<br> | |
| 517 | <br> | |
| 518 | TIFFGetField(tif, TIFFTAG_IMAGELENGTH, &imagelength);<br> | |
| 519 | buf = _TIFFmalloc(TIFFScanlineSize(tif));<br> | |
| 520 | for (row = 0; row < imagelength; row++)<br> | |
| 521 | tiffreadscanline(tif, buf, row);<br> | |
| 522 | _tifffree(buf);<br> | |
| 523 | tiffclose(tif);<br> | |
| 524 | }<br> | |
| 525 | }</tt> | |
| 526 | </p> | |
| 527 | <p> | |
| 528 | <tt>TIFFScanlineSize</tt> returns the number of bytes in | |
| 529 | a decoded scanline, as returned by <tt>TIFFReadScanline</tt>. | |
| 530 | Note however that if the file had been create with samples | |
| 531 | written in separate planes, then the above code would only | |
| 532 | read data that contained the first sample of each pixel; | |
| 533 | to handle either case one might use the following instead: | |
| 534 | </p> | |
| 535 | <p style="margin-left: 40px"> | |
| 536 | <tt>#include "tiffio.h"<br> | |
| 537 | main()<br> | |
| 538 | {<br> | |
| 539 | TIFF* tif = TIFFOpen("myfile.tif", "r");<br> | |
| 540 | if (tif) {<br> | |
| 541 | uint32 imagelength;<br> | |
| 542 | tdata_t buf;<br> | |
| 543 | uint32 row;<br> | |
| 544 | <br> | |
| 545 | TIFFGetField(tif, TIFFTAG_IMAGELENGTH, &imagelength);<br> | |
| 546 | TIFFGetField(tif, TIFFTAG_PLANARCONFIG, &config);<br> | |
| 547 | buf = _TIFFmalloc(TIFFScanlineSize(tif));<br> | |
| 548 | if (config == PLANARCONFIG_CONTIG) {<br> | |
| 549 | for (row = 0; row < imagelength; row++)<br> | |
| 550 | tiffreadscanline(tif, buf, row);<br> | |
| 551 | } else if (config == planarconfig_separate) {<br> | |
| 552 | uint16 s, nsamples;<br> | |
| 553 | <br> | |
| 554 | tiffgetfield(tif, tifftag_samplesperpixel, &nsamples);<br> | |
| 555 | for (s = 0; s < nsamples; s++)<br> | |
| 556 | for (row = 0; row < imagelength; row++)<br> | |
| 557 | tiffreadscanline(tif, buf, row, s);<br> | |
| 558 | }<br> | |
| 559 | _tifffree(buf);<br> | |
| 560 | tiffclose(tif);<br> | |
| 561 | }<br> | |
| 562 | }</tt> | |
| 563 | </p> | |
| 564 | <p> | |
| 565 | Beware however that if the following code were used instead to | |
| 566 | read data in the case <tt>PLANARCONFIG_SEPARATE</tt>,... | |
| 567 | </p> | |
| 568 | <p style="margin-left: 40px"> | |
| 569 | <tt> for (row = 0; row < imagelength; row++)<br> | |
| 570 | for (s = 0; s < nsamples; s++)<br> | |
| 571 | tiffreadscanline(tif, buf, row, s);</tt> | |
| 572 | </p> | |
| 573 | <p> | |
| 574 | ...then problems would arise if <tt>RowsPerStrip</tt> was not one | |
| 575 | because the order in which scanlines are requested would require | |
| 576 | random access to data within strips (something that is not supported | |
| 577 | by the library when strips are compressed). | |
| 578 | </p> | |
| 579 | <hr> | |
| 580 | <h2 id="strips">Strip-oriented Image I/O</h2> | |
| 581 | <p> | |
| 582 | The strip-oriented interfaces provided by the library provide | |
| 583 | access to entire strips of data. Unlike the scanline-oriented | |
| 584 | calls, data can be read or written compressed or uncompressed. | |
| 585 | Accessing data at a strip (or tile) level is often desirable | |
| 586 | because there are no complications with regard to random access | |
| 587 | to data within strips. | |
| 588 | </p> | |
| 589 | <p> | |
| 590 | A simple example of reading an image by strips is: | |
| 591 | </p> | |
| 592 | <p style="margin-left: 40px"> | |
| 593 | <tt>#include "tiffio.h"<br> | |
| 594 | main()<br> | |
| 595 | {<br> | |
| 596 | TIFF* tif = TIFFOpen("myfile.tif", "r");<br> | |
| 597 | if (tif) {<br> | |
| 598 | tdata_t buf;<br> | |
| 599 | tstrip_t strip;<br> | |
| 600 | <br> | |
| 601 | buf = _TIFFmalloc(TIFFStripSize(tif));<br> | |
| 602 | for (strip = 0; strip < tiffnumberofstrips(tif); strip++)<br> | |
| 603 | tiffreadencodedstrip(tif, strip, buf, (tsize_t) -1);<br> | |
| 604 | _tifffree(buf);<br> | |
| 605 | tiffclose(tif);<br> | |
| 606 | }<br> | |
| 607 | }</tt> | |
| 608 | </p> | |
| 609 | <p> | |
| 610 | Notice how a strip size of <tt>-1</tt> is used; <tt>TIFFReadEncodedStrip</tt> | |
| 611 | will calculate the appropriate size in this case. | |
| 612 | </p> | |
| 613 | <p> | |
| 614 | The above code reads strips in the order in which the | |
| 615 | data is physically stored in the file. If multiple samples | |
| 616 | are present and data is stored with <tt>PLANARCONFIG_SEPARATE</tt> | |
| 617 | then all the strips of data holding the first sample will be | |
| 618 | read, followed by strips for the second sample, etc. | |
| 619 | </p> | |
| 620 | <p> | |
| 621 | Finally, note that the last strip of data in an image may have fewer | |
| 622 | rows in it than specified by the <tt>RowsPerStrip</tt> tag. A | |
| 623 | reader should not assume that each decoded strip contains a full | |
| 624 | set of rows in it. | |
| 625 | </p> | |
| 626 | <p> | |
| 627 | The following is an example of how to read raw strips of data from | |
| 628 | a file: | |
| 629 | </p> | |
| 630 | <p style="margin-left: 40px"> | |
| 631 | <tt>#include "tiffio.h"<br> | |
| 632 | main()<br> | |
| 633 | {<br> | |
| 634 | TIFF* tif = TIFFOpen("myfile.tif", "r");<br> | |
| 635 | if (tif) {<br> | |
| 636 | tdata_t buf;<br> | |
| 637 | tstrip_t strip;<br> | |
| 638 | uint32* bc;<br> | |
| 639 | uint32 stripsize;<br> | |
| 640 | <br> | |
| 641 | TIFFGetField(tif, TIFFTAG_STRIPBYTECOUNTS, &bc);<br> | |
| 642 | stripsize = bc[0];<br> | |
| 643 | buf = _TIFFmalloc(stripsize);<br> | |
| 644 | for (strip = 0; strip < tiffnumberofstrips(tif); strip++) {<br> | |
| 645 | if (bc[strip] > stripsize) {<br> | |
| 646 | buf = _TIFFrealloc(buf, bc[strip]);<br> | |
| 647 | stripsize = bc[strip];<br> | |
| 648 | }<br> | |
| 649 | TIFFReadRawStrip(tif, strip, buf, bc[strip]);<br> | |
| 650 | }<br> | |
| 651 | _TIFFfree(buf);<br> | |
| 652 | TIFFClose(tif);<br> | |
| 653 | }<br> | |
| 654 | }</tt> | |
| 655 | </p> | |
| 656 | <p> | |
| 657 | As above the strips are read in the order in which they are | |
| 658 | physically stored in the file; this may be different from the | |
| 659 | logical ordering expected by an application. | |
| 660 | </p> | |
| 661 | <hr> | |
| 662 | <h2 id="tiles">Tile-oriented Image I/O</h2> | |
| 663 | <p> | |
| 664 | Tiles of data may be read and written in a manner similar to strips. | |
| 665 | With this interface, an image is | |
| 666 | broken up into a set of rectangular areas that may have dimensions | |
| 667 | less than the image width and height. All the tiles | |
| 668 | in an image have the same size, and the tile width and length must each | |
| 669 | be a multiple of 16 pixels. Tiles are ordered left-to-right and | |
| 670 | top-to-bottom in an image. As for scanlines, samples can be packed | |
| 671 | contiguously or separately. When separated, all the tiles for a sample | |
| 672 | are colocated in the file. That is, all the tiles for sample 0 appear | |
| 673 | before the tiles for sample 1, etc. | |
| 674 | </p> | |
| 675 | <p> | |
| 676 | Tiles and strips may also be extended in a z dimension to form | |
| 677 | volumes. Data volumes are organized as "slices". That is, all the | |
| 678 | data for a slice is colocated. Volumes whose data is organized in | |
| 679 | tiles can also have a tile depth so that data can be organized in | |
| 680 | cubes. | |
| 681 | </p> | |
| 682 | <p> | |
| 683 | There are actually two interfaces for tiles. | |
| 684 | One interface is similar to scanlines, to read a tiled image, | |
| 685 | code of the following sort might be used: | |
| 686 | </p> | |
| 687 | <p style="margin-left: 40px"> | |
| 688 | <tt>main()<br> | |
| 689 | {<br> | |
| 690 | TIFF* tif = TIFFOpen("myfile.tif", "r");<br> | |
| 691 | if (tif) {<br> | |
| 692 | uint32 imageWidth, imageLength;<br> | |
| 693 | uint32 tileWidth, tileLength;<br> | |
| 694 | uint32 x, y;<br> | |
| 695 | tdata_t buf;<br> | |
| 696 | <br> | |
| 697 | TIFFGetField(tif, TIFFTAG_IMAGEWIDTH, &imageWidth);<br> | |
| 698 | TIFFGetField(tif, TIFFTAG_IMAGELENGTH, &imageLength);<br> | |
| 699 | TIFFGetField(tif, TIFFTAG_TILEWIDTH, &tileWidth);<br> | |
| 700 | TIFFGetField(tif, TIFFTAG_TILELENGTH, &tileLength);<br> | |
| 701 | buf = _TIFFmalloc(TIFFTileSize(tif));<br> | |
| 702 | for (y = 0; y < imagelength; y += tilelength)<br> | |
| 703 | for (x = 0; x < imagewidth; x += tilewidth)<br> | |
| 704 | tiffreadtile(tif, buf, x, y, 0);<br> | |
| 705 | _tifffree(buf);<br> | |
| 706 | tiffclose(tif);<br> | |
| 707 | }<br> | |
| 708 | }</tt> | |
| 709 | </p> | |
| 710 | <p> | |
| 711 | (once again, we assume samples are packed contiguously.) | |
| 712 | </p> | |
| 713 | <p> | |
| 714 | Alternatively a direct interface to the low-level data is provided | |
| 715 | a la strips. Tiles can be read with | |
| 716 | <tt>TIFFReadEncodedTile</tt> or <tt>TIFFReadRawTile</tt>, | |
| 717 | and written with <tt>TIFFWriteEncodedTile</tt> or | |
| 718 | <tt>TIFFWriteRawTile</tt>. For example, to read all the tiles in an image: | |
| 719 | </p> | |
| 720 | <p style="margin-left: 40px"> | |
| 721 | <tt>#include "tiffio.h"<br> | |
| 722 | main()<br> | |
| 723 | {<br> | |
| 724 | TIFF* tif = TIFFOpen("myfile.tif", "r");<br> | |
| 725 | if (tif) {<br> | |
| 726 | tdata_t buf;<br> | |
| 727 | ttile_t tile;<br> | |
| 728 | <br> | |
| 729 | buf = _TIFFmalloc(TIFFTileSize(tif));<br> | |
| 730 | for (tile = 0; tile < tiffnumberoftiles(tif); tile++)<br> | |
| 731 | tiffreadencodedtile(tif, tile, buf, (tsize_t) -1);<br> | |
| 732 | _tifffree(buf);<br> | |
| 733 | tiffclose(tif);<br> | |
| 734 | }<br> | |
| 735 | }</tt> | |
| 736 | </p> | |
| 737 | <hr> | |
| 738 | <h2 id="other">Other Stuff</h2> | |
| 739 | <p> | |
| 740 | Some other stuff will almost certainly go here... | |
| 741 | </p> | |
| 742 | <hr> | |
| 743 | <p> | |
| 744 | Last updated: $Date: 2005/12/28 06:53:18 $ | |
| 745 | </p> | |
| 746 | </body> | |
| 747 | </html> |