Debian Codegraph @

upstream/debian-unstable/man1/tifftopnm.1

raw
1 \
2 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3 .\" Do not hand-hack it! If you have bug fixes or improvements, please find
4 .\" the corresponding HTML page on the Netpbm website, generate a patch
5 .\" against that, and send it to the Netpbm maintainer.
6 .TH "Tifftopnm User Manual" 1 "02 January 2015" "netpbm documentation"
7
8 .SH NAME
9
10 tifftopnm - convert a TIFF file into a PNM image
11
12 .UN synopsis
13 .SH SYNOPSIS
14
15 \fBtifftopnm\fP
16
17 [\fB-alphaout=\fP{\fIalpha-filename\fP,\fB-\fP}]
18 [\fB-headerdump\fP]
19 [\fB-verbose\fP]
20 [\fB-respectfillorder\fP]
21 [\fB-byrow\fP]
22 [\fB-orientraw\fP]
23 [\fItiff-filename\fP]
24
25
26 .UN description
27 .SH DESCRIPTION
28 .PP
29 This program is part of
30 .BR "Netpbm" (1)\c
31 \&.
32 .PP
33 \fBtifftopnm\fP reads a TIFF file as input and produces a PNM image as
34 output. The type of the output file depends on the input file - if it's black
35 and white, \fBtifftopnm\fP generates a PBM image; if it's grayscale, it
36 generates a PGM image; otherwise, the output is PPM. The program tells you
37 which type it is writing.
38 .PP
39 If the TIFF file contains multiple images (multiple
40 "directories"), \fBtifftopnm\fP generates a multi-image PNM
41 output stream. Before Netpbm 10.27 (March 2005), however, it would
42 just ignore all but the first input image.
43 .PP
44 The \fItiff-filename\fP argument names the file that contains the Tiff
45 image. If you specify "-" or don't specify this
46 argument, \fBtifftopnm\fP uses Standard Input.
47 .PP
48 In either case, before Netpbm 10.70 (March 2015), the file must be
49 seekable. That means no pipe, but any regular file is fine. In current
50 Netpbm, the file need not be seekable, but if it isn't, \fBtifftopnm\fP
51 creates a temporary regular file containing the entire image, so you must have
52 resources for that (and it may defeat your reason for using a pipe).
53
54 .UN library
55 .SS TIFF Capability
56 .PP
57 \fBpamtotiff\fP uses the Libtiff.org TIFF library (or whatever
58 equivalent you provide) to interpret the TIFF input. So the set of files
59 it is able to interpret is determined mostly by that library.
60 .PP
61 This program cannot read every possible TIFF file -- there are
62 myriad variations of the TIFF format. However, it does understand
63 monochrome and gray scale, RGB, RGBA (red/green/blue with transparency
64 channel), CMYK (Cyan-Magenta-Yellow-Black ink color separation), and
65 color palette TIFF files. An RGB file can have either single plane
66 (interleaved) color or multiple plane format. The program reads 1-8
67 and 16 bit-per-sample input, the latter in either bigendian or
68 littlendian encoding. Tiff directory information may also be either
69 bigendian or littlendian.
70 .PP
71 There are many TIFF formats that \fBtifftopnm\fP can read only if
72 the image is small enough to fit in memory. \fBtifftopnm\fP uses the
73 TIFF library's TIFFRGBAImageGet() function to process the TIFF image
74 if it can get enough memory for TIFFRGBAImageGet() to store the whole
75 image in memory at once (that's what TIFFRGBAImageGet() does). If
76 not, \fBtifftopnm\fP uses a more primitive row-by-row conversion
77 strategy using the raw data returned by TIFFReadScanLine() and native
78 intelligence. That native intelligence does not know as many formats
79 as TIFFRGBAImageGet() does. And certain compressed formats simply
80 cannot be read with TIFFReadScanLine().
81 .PP
82 Before Netpbm 10.11 (October 2002), \fBtifftopnm\fP never used
83 TIFFRGBAImageGet(), so it could not interpret many of the formats it
84 can interpret today.
85 .PP
86 There is no fundamental reason that this program could not read
87 other kinds of TIFF files even when they don't fit in memory all at
88 once. The existing limitations are mainly because no one has asked
89 for more.
90
91 .UN output
92 .SS Output Image
93 .PP
94 The PNM output has the same maxval as the Tiff input, except that
95 if the Tiff input is colormapped (which implies a maxval of 65535) the
96 PNM output has a maxval of 255. Though this may result in lost
97 information, such input images hardly ever actually have more color
98 resolution than a maxval of 255 provides and people often cannot deal
99 with PNM files that have maxval > 255. By contrast, a
100 non-colormapped Tiff image that doesn't need a maxval > 255 doesn't
101 \fIhave\fP a maxval > 255, so when \fBtifftopnm\fP sees a
102 non-colormapped maxval > 255, it takes it seriously and produces a
103 matching output maxval.
104 .PP
105 Another exception is where the TIFF maxval is greater than 65535,
106 which is the maximum allowed by the Netpbm formats. In that case,
107 \fBtifftopnm\fP uses a maxval of 65535, and you lose some information
108 in the conversion.
109
110 .UN options
111 .SH OPTIONS
112 .PP
113 In addition to the options common to all programs based on libnetpbm
114 (most notably \fB-quiet\fP, see
115 .UR index.html#commonoptions
116 Common Options
117 .UE
118 \&), \fBtifftopnm\fP recognizes the following
119 command line options:
120 .PP
121 You may abbreviate any option to its shortest unique prefix. You may use
122 two hyphens instead of one in options. You may separate an option and
123 its value either by an equals sign or white space.
124
125
126 .TP
127 \fB-alphaout=\fP\fIalpha-filename\fP
128 \fBtifftopnm \fPcreates a PGM file containing the alpha channel
129 values in the input image. If the input image doesn't contain a
130 transparency channel, the \fIalpha-filename\fP file contains all zero
131 (transparent) transparency values. If you don't specify \fB-alphaout\fP,
132
133 \fBtifftopnm\fP does not generate a transparency file, and if the input
134 image has an transparency channel, \fBtifftopnm\fP simply discards it.
135 .sp
136 If you specify \fB-\fP as the filename, \fBtifftopnm\fP
137 writes the transparency output to Standard Output and discards the image.
138 .sp
139 See
140 .BR "pamcomp" (1)\c
141 \& for one way to use
142 the transparency output file.
143
144 .TP
145 \fB-respectfillorder\fP
146 By default, \fBtifftopnm \fP ignores the "fillorder"
147 tag in the TIFF input, which means it may incorrectly interpret the
148 image. To make it follow the spec, use this option. For a lengthy
149 but engaging discussion of why \fBtifftopnm\fP works this way and how
150 to use the \fB-respectfillorder\fP option, see the note on fillorder
151 below.
152
153 .TP
154 \fB-byrow\fP
155 This option can make \fBtifftopnm\fP run faster.
156 .sp
157 \fBtifftopnm\fP has two ways to do the conversion from Tiff to PNM, using
158 respectively two facilities of the TIFF library:
159
160
161
162 .TP
163 Whole Image
164 Decode the entire image into memory at once, using
165 \fBTIFFRGBAImageGet()\fP, then convert to PNM and output row by row.
166
167 .TP
168 Row By Row
169 Read, convert, and output one row at a time
170 using \fBTIFFReadScanline()\fP
171
172
173 .sp
174 Whole Image is preferable because the Tiff library does more of the
175 work, which means it understands more of the Tiff format possibilities
176 now and in the future. Also, some compressed TIFF formats don't allow
177 you to extract an individual row.
178 .sp
179 Row By Row uses far less memory, which means with large images, it
180 can run in environments where Whole Image cannot and may also run
181 faster. And because Netpbm code does more of the work, it's possible
182 that it can be more flexible or at least give better diagnostic
183 information if there's something wrong with the TIFF.
184 .sp
185 The Netpbm native code may do something correctly that the TIFF
186 library does incorrectly, or vice versa.
187 .sp
188 In Netpbm, we stress function over performance, so by default we
189 try Whole Image first, and if we can't get enough memory for the
190 decoded image or \fBTIFFRGBAImageGet()\fP fails, we fall back to Row By Row.
191 But if you specify the \fB-byrow\fP option, \fBtifftopnm\fP will not
192 attempt Whole Image. If Row By Row does not work, it simply fails.
193 .sp
194 See
195 .UR #cmyk
196 Color Separation (CMYK) TIFFs
197 .UE
198 \& for a
199 description of one way Row By Row makes a significant difference in
200 your results.
201 .sp
202 Whole Image costs you precision when your TIFF image uses more than
203 8 bits per sample. \fBTIFFRGBAImageGet()\fP converts the samples to 8 bits.
204 \fBtifftopnm\fP then scales them back to maxval 65535, but the lower
205 8 bits of information is gone.
206 .sp
207 In many versions of the TIFF library, \fBTIFFRGBAImageGet()\fP does not
208 correctly interpret TIFF files in which the raster orientation is
209 column-major (i.e. a row of the raster is a column of the image).
210 With such a TIFF library and file, you must use \fB-byrow\fP to get
211 correct output.
212 .sp
213 Before Netpbm 10.11 (October 2002), \fBtifftopnm\fP always did Row
214 By Row. Netpbm 10.12 always tried Whole Image first. \fB-byrow\fP
215 came in with Netpbm 10.13 (January 2003).
216
217 .TP
218 \fB-orientraw\fP
219 A TIFF stream contains raster data which can be arranged in the
220 stream various ways. Most commonly, it is arranged by rows, with the
221 top row first, and the pixels left to right within each row, but many
222 other orientations are possible.
223 .sp
224 The common orientation is the same one the Netpbm formats use, so
225 \fBtifftopnm\fP can do its jobs quite efficiently when the TIFF raster
226 is oriented that way.
227 .sp
228 But if the TIFF raster is oriented any other way, it can take a
229 considerable amount of processing for \fBtifftopnm\fP to convert it to
230 Netpbm format.
231 .sp
232 \fB-orientraw\fP says to produce an output image that represents the raw
233 raster in the TIFF stream rather than the image the TIFF stream is supposed to
234 represent. In the output, the top left corner corresponds to the start of the
235 TIFF raster, the next pixel to the right is the next pixel in the TIFF raster,
236 etc. \fBtifftopnm\fP can do this easily, but you don't get the right image
237 out. You can use \fBpamflip\fP to turn the output into the image the TIFF
238 stream represents (but if you do that, you pretty much lose the benefit of
239 \fB-orientraw\fP).
240 .sp
241 With this option, \fBtifftopnm\fP always uses the Row By Row method
242 (see \fB-byrow\fP).
243 .sp
244 This option was new in Netpbm 10.42 (March 2008). Before that,
245 \fBtifftopnm\fP generally produces arbitrary results with TIFF images
246 that have an orientation other than the common one.
247
248 .TP
249 \fB-verbose\fP
250 Print extra messages to Standard Error about the conversion.
251
252 .TP
253 \fB-headerdump\fP
254 Also dump TIFF file information to stderr. This information may be useful
255 in debugging TIFF file conversion problems.
256
257
258
259 .UN notes
260 .SH NOTES
261
262 .UN fillorder
263 .SS Fillorder
264 .PP
265 There is a piece of information in the header of a TIFF image called
266 "fillorder." The TIFF specification quite clearly states
267 that this value tells the order in which bits are arranged in a byte
268 in the description of the image's pixels. There are two options,
269 assuming that the image has a format where more than one pixel can be
270 represented by a single byte: 1) the byte is filled from most
271 significant bit to least significant bit going left to right in the
272 image; and 2) the opposite.
273 .PP
274 However, there is confusion in the world as to the meaning of
275 fillorder. Evidence shows that some people believe it has to do with
276 byte order when a single value is represented by two bytes.
277 .PP
278 These people cause TIFF images to be created that, while they use a
279 MSB-to-LSB fillorder, have a fillorder tag that says they used LSB-to-MSB.
280 A program that properly interprets a TIFF image will not end up with the
281 image that the author intended in this case.
282 .PP
283 For a long time, \fBtifftopnm\fP did not understand fillorder itself
284 and assumed the fillorder was MSB-to-LSB regardless of the fillorder
285 tag in the TIFF header. And as far as I know, there is no legitimate
286 reason to use a fillorder other than MSB-to-LSB. So users of
287 \fBtifftopnm\fP were happily using those TIFF images that had
288 incorrect fillorder tags.
289 .PP
290 So that those users can continue to be happy, \fBtifftopnm\fP today
291 continues to ignore the fillorder tag unless you tell it not to. (It
292 does, however, warn you when the fillorder tag does not say MSB-to-LSB
293 that the tag is being ignored).
294 .PP
295 If for some reason you have a TIFF image that actually has LSB-to-MSB
296 fillorder, and its fillorder tag correctly indicates that, you must
297 use the \fB-respectfillorder\fP option on \fBtifftopnm\fP to get
298 proper results.
299 .PP
300 Examples of incorrect TIFF images are at
301 .UR ftp://weather.noaa.gov.
302 ftp://weather.noaa.gov.
303 .UE
304 \& They are
305 apparently created by a program called \fBfaxtotiff\fP.
306 .PP
307 This note was written on January 1, 2002.
308
309
310 .UN cmyk
311 .SS Color Separation (CMYK) TIFFs
312 .PP
313 Some TIFF images contain color information in CMYK form, whereas PNM
314 images use RGB. There are various formulas for converting between these
315 two forms, and \fBtifftopnm\fP can use either of two.
316 .PP
317 The TIFF library (Version 3.5.4 from libtiff.org) uses
318 Y=(1-K)*(1-B) (similar for R and G) in its TIFFRGBAImageGet() service.
319 When \fBtifftopnm\fP works in Whole Image mode, it uses that service,
320 so that's the conversion you get.
321 .PP
322 But when \fBtifftopnm\fP runs in Row By Row mode, it does not use
323 TIFFRGBAImageGet(), and you get what appears to be more useful:
324 Y=1-(B+K). This is the inverse of what \fBpnmtotiffcmyk\fP does.
325 .PP
326 See the \fB-byrow\fP option for more information on Whole Image versus
327 Row By Row mode.
328 .PP
329 Before Netpbm 10.21 (March 2004), \fBtifftopnm\fP used the
330 Y=(1-K)*(1-B) formula always.
331
332
333 .UN seealso
334 .SH SEE ALSO
335 .BR "pnmtotiff" (1)\c
336 \&,
337 .BR "pnmtotiffcmyk" (1)\c
338 \&,
339 .BR "pamcomp" (1)\c
340 \&,
341 .BR "pnm" (1)\c
342 \&
343
344 .UN author
345 .SH AUTHOR
346 .PP
347 Derived by Jef Poskanzer from tif2ras.c, which is Copyright (c)
348 1990 by Sun Microsystems, Inc. Author: Patrick J. Naughton (\[email protected]\fP).
349 .SH DOCUMENT SOURCE
350 This manual page was generated by the Netpbm tool 'makeman' from HTML
351 source. The master documentation is at
352 .IP
353 .B http://netpbm.sourceforge.net/doc/tifftopnm.html
354 .PP