1Pamtotiff User Manual(0) Pamtotiff User Manual(0)
2
6 pamtotiff - convert a Netpbm image to a TIFF file
7
10 pamtotiff
11 [-none | -packbits | -lzw | -g3 | -g4 | -flate | -adobeflate]
13 [-2d]
15 [-fill]
17 [-predictor=n]
19 [-msb2lsb|-lsb2msb]
21 [-rowsperstrip=n]
23 [-minisblack|-miniswhite|mb|mw]
25 [-truecolor]
27 [-color]
29 [-indexbits=bitwidthlist] [-xresolution=xres]
31 [-yresolution=yres] [-resolutionunit={inch | centimeter | none | in |
33 cm | no}]
34 [-indexbits=[1[2[4[8]]]]]
36 [-append]
38 [-tag=taglist]
40 [pamfile]
42 You can use the minimum unique abbreviation of the options. You can
44 use two hyphens instead of one. You can separate an option name from
45 its value with white space instead of an equals sign.
46
49 This program is part of Netpbm(1).
50 pamtotiff reads a PNM or PAM image as input and produces a TIFF file as
52 output.
53 Actually, it handles multi-image Netpbm streams, producing multi-image
55 TIFF streams (i.e. a TIFF stream with multiple 'directories'). But
56 before Netpbm 10.27 (March 2005), it ignored all but the first Netpbm
57 image in the input stream.
58 The Output File
61 The output goes to Standard Output. pamtotiff approaches this output
62 file differently from Unix and Netpbm convention. This is entirely due
63 to pamtotiff's use of the TIFF library to do all TIFF output.
64 · The output file must be seekable. pamtotiff does not write it
68 sequentially. Therefore, you can't use a pipe; you can't pipe
69 the output of pamtotiff to some other program. But any regular
70 file should work.
71 · If the output file descriptor is readable, you must either spec‐
74 ify -append so as to add to the existing file, or make sure the
75 file is empty. Otherwise, pamtotiff will fail with an unhelpful
76 message telling you that a TIFF library function failed to open
77 the TIFF output stream.
78 · If you are converting multiple images (your input stream con‐
81 tains multiple images), the output file must be both readable
82 and writable.
83 If you're using a Unix command shell to run pamtotiff, you use facili‐
87 ties of your shell to set up Standard Output. In Bash, for example,
88 you would set up a write-only Standard Output to the file /tmp/myim‐
89 age.tiff like this:
90 $ pamtotiff myimage.pnm >/tmp/myimage.tiff
92 In Bash, you would set up a read/write Standard Output to the file
94 /tmp/myimage.tiff like this:
95 $ pamtotiff myimage.pnm 1<>/tmp/myimage.tiff
97 TIFF Capability
100 pamtotiff uses the Libtiff.org TIFF library (or whatever equivalent you
101 provide) to generate the TIFF output. Details of the format it pro‐
102 duces are therefore controlled by that library.
103
106 Compression
107 By default, pamtotiff creates a TIFF file with no compression. This is
108 your best bet most of the time. If you want to try another compression
109 scheme or tweak some of the other even more obscure output options,
110 there are a number of options which which to play.
111 Before Netpbm 8.4 (April 2000), the default was to use LZW compression.
113 But then new releases of the TIFF library started omitting the LZW com‐
114 pression capability due to concern about patents on LZW. So since
115 then, the default has been no compression. The LZW patents have now
116 expired and new TIFF libraries do LZW, but the pamtotiff behavior
117 remains the same for compatibility with older TIFF libraries and appli‐
118 cations of pamtotiff.
119 The -none, -packbits, -lzw, -g3, -g4, -flate, and -adobeflate options
121 are used to override the default and set the compression scheme used in
122 creating the output file.
123 The -predictor option is meaningful only with LZW compression: a pre‐
125 dictor value of 2 causes each scanline of the output image to undergo
126 horizontal differencing before it is encoded; a value of 1 forces each
127 scanline to be encoded without differencing. By default, pamtotiff
128 creates a TIFF file with msb-to-lsb fill order. The -msb2lsb and
129 -lsb2msb options are used to override the default and set the fill
130 order used in creating the file.
131 With some older TIFF libraries, -lzw doesn't work because the TIFF
133 library doesn't do LZW compression. This is because of concerns about
134 Unisys's patent on LZW which was then in force. Actually, with very
135 old TIFF libraries, -lzw works because no distributors of the TIFF
136 library were sensitive yet to the patent issue.
137 -flate chooses 'flate' compression, which is the patent-free compres‐
139 sion common in the Unix world implemented by the 'Z' library. It is
140 what the PNG format uses.
141 Fax Compression
143 If you have bilevel data (e.g. PBM), you can generate a TIFF that uses
145 the same compression scheme specified for use by fax machines. See the
146 FaxFormat[1m(1)pageformoreinformationonthese compression schemes.
147 These formats all relate to ITU Group 3 and Group 4 fax machine stan‐
149 dards.
150 The -g3 option chooses MH or MR compression: MR with the additional
152 option -2d; MH without it. -g4 selects MMR. The option names are a
153 little unfortunate and historical, but are consistent with the TIFF
154 specification.
155 MMR has a better compression ratio than the other two.
157 -fill specifies that for MH or MR compression, each encoded scanline
159 shall be zero-filled to a byte boundary.
160 -2d and -fill are meaningful only with -g3.
162 Fill Order
166 The -msb2lsb and lsb2msb options control the fill order.
167 The fill order is the order in which pixels are packed into a byte in
169 the Tiff raster, in the case that there are multiple pixels per byte.
170 msb-to-lsb means that the leftmost columns go into the most significant
171 bits of the byte in the Tiff image. However, there is considerable
172 confusion about the meaning of fill order. Some believe it means
173 whether 16 bit sample values in the Tiff image are little-endian or
174 big-endian. This is totally erroneous (The endianness of integers in a
175 Tiff image is designated by the image's magic number). However,
176 ImageMagick and older Netpbm both have been known to implement that
177 interpretation. 2001.09.06.
178 If the image does not have sub-byte pixels, these options have no
180 effect other than to set the value of the FILLORDER tag in the Tiff
181 image (which may be useful for those programs that misinterpret the tag
182 with reference to 16 bit samples).
183 Color Space
186 -color tells pamtotiff to produce a color, as opposed to grayscale,
187 TIFF image if the input is PPM, even if it contains only shades of
188 gray. Without this option, pamtotiff produces a grayscale TIFF image
189 if the input is PPM and contains only shades of gray, and at most 256
190 shades. Otherwise, it produces a color TIFF output. For PBM and PGM
191 input, pamtotiff always produces grayscale TIFF output and this option
192 has no effect.
193 The -color option can prevent pamtotiff from making two passes through
195 the input file, thus improving speed and memory usage. See Multiple
196 Passes ⟨#multipass⟩ .
197 -truecolor tells pamtotiff to produce the 24-bit RGB form of TIFF out‐
199 put if it is producing a color TIFF image. Without this option, pamto‐
200 tiff produces a colormapped (paletted) TIFF image unless there are more
201 than 256 colors (and in the latter case, issues a warning).
202 The -truecolor option can prevent pamtotiff from making two passes
204 through the input file, thus improving speed and memory usage. See
205 Multiple Passes ⟨#multipass⟩ .
206 The -color and -truecolor options did not exist before Netpbm 9.21
208 (December 2001).
209 If pamtotiff produces a grayscale TIFF image, this option has no
211 effect.
212 The -minisblack and -miniswhite options force the output image to have
214 a 'minimum is black' or 'minimum is white' photometric, respectively.
215 If you don't specify either, pamtotiff uses minimum is black except
216 when using Group 3 or Group 4 compression, in which case pamtotiff fol‐
217 lows CCITT fax standards and uses 'minimum is white.' This usually
218 results in better compression and is generally preferred for bilevel
219 coding.
220 Before February 2001, pamtotiff always produced 'minimum is black,' due
222 to a bug. In either case, pamtotiff sets the photometric interpreta‐
223 tion tag in the TIFF output according to which photometric is actually
224 used.
225 The -indexbits option is meaningful only for a colormapped (paletted)
227 image. In this kind of image, the raster contains values which are
228 indexes into a table of colors, with the indexes normally taking less
229 space that the color description in the table. pamtotiff can generate
230 indexes of 1, 2, 4, or 8 bits. By default, it will use 8, because many
231 programs that interpret TIFF images can't handle any other width.
232 But if you have a small number of colors, you can make your image con‐
234 siderably smaller by allowing fewer than 8 bits per index, using the
235 -indexbits option. The value is a comma-separated list of the bit
236 widths you allow. pamtotiff chooses the smallest width you allow that
237 allows it to index the entire color table. If you don't allow any such
238 width, pamtotiff fails. Normally, the only useful value for this
239 option is 1,2,4,8, because a program either understands the 8 bit width
240 (default) or understands them all.
241 In a Baseline TIFF image, according to the 1992 TIFF 6.0 specification,
243 4 and 8 are the only valid widths. There are no formal standards that
244 allow any other values.
245 This option was added in June 2002. Before that, only 8 bit indices
247 were possible.
248 Extra Tags
251 There are lots of tag types in the TIFF format that don't correspond to
252 any information in the PNM format or to anything in the conversion
253 process. For example, a TIFF_ARTIST tag names the artist who created
254 the image.
255 You can tell pamtotiff explicitly to include tags such as this in its
257 output with the -tag option. You identify a list of tag types and val‐
258 ues and pamtotiff includes a tag in the output for each item in your
259 list.
260 The value of -tag is the list of tags, like this example:
262 -tag=subfiletype=reducedimage,documentname=Fred,xposition=25
264 As you see, it is a list of tag specifications separated by commas.
266 Each tag specification is a name and a value separated by an equal
267 sign. The name is the name of the tag type, except in arbitrary
268 upper/lower case. One place to see the names of TIFF tag types is in
269 the TIFF library's tiff.h file, where there is a macro defined for each
270 consisting of 'TIFF_' plus the name. E.g. for the SUBFILETYPE tag
271 type, there is a macro TIFF_SUBFILETYPE.
272 The format of the value specification for a tag (stuff after the equal
274 sign) depends upon what kind of value the tag type has:
275 · Integer: a decimal number
279 · Floating point number: a decimal number
282 · String: a string
285 · Enumerated (For example, a 'subfiletype' tag takes an enumerated
288 value. Its possible values are REDUCEDIMAGE, PAGE, and MASK.):
289 The name of the value. You can see the possible value names in
290 the TIFF library's tiff.h foile, where there is a macro defined
291 for each consisting of a qualifier plus the value name. E.g.
292 for the REDUCEDIMAGE value of a SUBFILETYPE tag, you see the
293 macro FILETYPE_REDUCEDIMAGE.
294 The TIFF format assigns a unique number to each enumerated value
296 and you can specify that number, in decimal, as an alternative.
297 This is useful if you are using an extension of TIFF that pamto‐
298 tiff doesn't know about.
299 If you specify a tag type with -tag that is not independent of the con‐
303 tent of your PNM source image and pamtotiff's conversion process (i.e.
304 a tag type in which pamtotiff is interested), pamtotiff fails. For
305 example, you cannot specify an IMAGEWIDTH tag with -tag, because pamto‐
306 tiff generates an IMAGEWIDTH tag that gives the actual width of the
307 image.
308 -tag was new in Netpbm 10.31 (December 2005).
310 Other
313 You can use the -rowsperstrip option to set the number of rows (scan‐
314 lines) in each strip of data in the output file. By default, the out‐
315 put file has the number of rows per strip set to a value that will
316 ensure each strip is no more than 8 kilobytes long.
317 The -append option tells pamtotiff to add images to the existing output
319 file (a TIFF file may contain multiple images) instead of the default,
320 which is to replace the output file.
321 -append was new in Netpbm 10.27 (March 2005).
323
327 There are myriad variations of the TIFF format, and this program gener‐
328 ates only a few of them. pamtotiff creates a grayscale TIFF file if
329 its input is a PBM (monochrome) or PGM (grayscale) or equivalent PAM
330 file. pamtotiff also creates a grayscale file if it input is PPM
331 (color) or equivalent PAM, but there is only one color in the image.
332 If the input is a PPM (color) file and there are 256 colors or fewer,
334 but more than 1, pamtotiff generates a color palette TIFF file. If
335 there are more colors than that, pamtotiff generates an RGB (not RGBA)
336 single plane TIFF file. Use pnmtotiffcmyk to generate the cyan-
337 magenta-yellow-black ink color separation TIFF format.
338 The number of bits per sample in the TIFF output is determined by the
340 maxval of the Netpbm input. If the maxval is less than 256, the bits
341 per sample in the output is the smallest number that can encode the
342 maxval. If the maxval is greater than or equal to 256, there are 16
343 bits per sample in the output.
344 Extra Channels
347 Like most Netpbm programs, pamtotiff's function is mostly undefined if
348 the input is PAM image with tuple type other than BLACKANDWHITE,
349 GRAYSCALE, or RGB. Most of the statements in this manual assume the
350 input is not such an exotic PAM. But there is a little defined pro‐
351 cessing of other PAM subformats.
352 pamtotiff assumes any 1 plane PAM image is BLACKANDWHITE or GRAYSCALE
354 (and doesn't distinguish between those two).
355 pamtotiff assumes a PAM with more than 1 plane is of tuple type RGB
357 except with that number of planes instead of 3. pamtotiff doesn't
358 really understand red, green, and blue, so it has no trouble with a
359 2-component or 5-component color space. The TIFF format allows an
360 arbitrary number of color compoonents, so pamtotiff simply maps the PAM
361 planes directly to TIFF color components. I don't know if the meanings
362 of 5 components in a TIFF image are standard at all, but the function
363 is there if you want to use it.
364 Note that pamtotiff may generate either a truecolor or colormapped
366 image with an arbitrary number of color components. In the truecolor
367 case, the raster has that number of planes. In the colormapped case,
368 the raster has of course 1 plane, but the color map has all the color
369 components in it.
370 The most common reason for a PAM to have extra planes is when the tuple
372 type is xxx_ALPHA, which means the highest numbered plane is a trans‐
373 parency plane (alpha channel). At least one user found that a TIFF
374 with an extra plane for transparency was useful.
375 Note that the grayscale detection works on N-component colors, so if
377 your planes aren't really color components, you'll want to disable this
378 via the -color option.
379 Multiple Passes
383 pamtotiff reads the input image once if it can, and otherwise twice.
384 It needs that second pass (which happens before the main pass, of
385 course) to analyze the colors in the image and generate a color map
386 (palette) and determine if the image is grayscale. So the second pass
387 happens only when the input is PPM. And you can avoid it then by spec‐
388 ifying both the -truecolor and -color options.
389 If the input image is small enough to fit in your system's file cache,
391 the second pass is very fast. If not, it requires reading from disk
392 twice, which can be slow.
393 When the input is from a file that cannot be rewound and reread, pamto‐
395 tiff reads the entire input image into a temporary file which can, and
396 works from that. Even if it needs only one pass.
397 Before Netpbm 9.21 (December 2001), pamtotiff always read the entire
399 image into virtual memory and then did one, two, or three passes
400 through the memory copy. The -truecolor and -color options did not
401 exist. The passes through memory would involve page faults if the
402 entire image did not fit into real memory. The image in memory
403 required considerably more memory (12 bytes per pixel) than the cached
404 file version of the image would.
405 Resolution
409 A Tiff image may contain information about the resolution of the image,
410 which means how big in real dimensions (centimeters, etc.) each pixel
411 in the raster is. That information is in the TIFF XRESOLUTION, YRESO‐
412 LUTION, and RESOLUTIONUNIT tags. By default, pamtotiff does not
413 include any tags of these types, but you can specify them with the
414 -tags option.
415 There are also options -xresolution, -yresolution, and -resolutionunit,
417 but those are obsolete. Before -tags existed (before Netpbm 10.31
418 (December 2005), they were the only way.
419 Note that the number of pixels in the image and how much information
421 each contains is determined independently from the setting of the reso‐
422 lution tags. The number of pixels in the output is the same as in the
423 input, and each pixel contains the same information. For your resolu‐
424 tion tags to be meaningful, they have to consistent with whatever cre‐
425 ated the PNM input. E.g. if a scanner turned a 10 centimeter wide
426 image into a 1000 pixel wide PNM image, then your horizontal resolution
427 is 100 pixels per centimeter, and if your XRESOLUTION tag says anything
428 else, something that prints your TIFF image won't print the proper 10
429 centimeter image.
430 The value of the XRESOLUTION tag is a floating point decimal number
432 that tells how many pixels there are per unit of distance in the hori‐
433 zontal direction. -yresolution is analogous for the vertical direc‐
434 tion.
435 The unit of distance is given by the value of the RESOLUTIONUNIT
437 option. That value is either INCH, CENTIMETER, or NONE. NONE means
438 the unit is arbitrary or unspecified. This could mean that the creator
439 and user of the image have a separate agreement as to what the unit is.
440 But usually, it just means that the horizontal and vertical resolution
441 values cannot be used for anything except to determine aspect ratio
442 (because even though the unit is arbitrary or unspecified, it has to be
443 the same for both resolution numbers).
444 If you don't use a -tag option to specify the resolution tag and use
446 the obsolete options instead, note the following:
447 · If you don't include an specify -xresolution, the Tiff image
451 does not contain horizontal resolution information. Likewise
452 for -yresolution. If you don't specify -resolutionunit, the
453 default is inches.
454 · Before Netpbm 10.16 (June 2003), -resolutionunit did not exist
457 and the resolution unit was always inches.
458
463 pamtotiff was originally pnmtotiff and did not handle PAM input. It
464 was extended and renamed in Netpbm 10.30 (October 2005).
465
469 tifftopnm(1), pnmtotiffcmyk(1), pamdepth(1), pamtopnm(1), pam(1)
470
473 Derived by Jef Poskanzer from ras2tiff.c, which is Copyright (c) 1990
474 by Sun Microsystems, Inc. Author: Patrick J. Naughton
475 (naughton@wind.sun.com).
476netpbm documentation 03 December 2008 Pamtotiff User Manual(0)