| | 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> |
projects / wxWidgets.git / blame_incremental