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