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 [-append]
36 [-tag=taglist]
38 [pamfile]
40 You can use the minimum unique abbreviation of the options. You can
42 use two hyphens instead of one. You can separate an option name from
43 its value with white space instead of an equals sign.
44
47 This program is part of Netpbm(1).
48 pamtotiff reads a PNM or PAM image as input and produces a TIFF file as
50 output.
51 Actually, it handles multi-image Netpbm streams, producing multi-image
53 TIFF streams (i.e. a TIFF stream with multiple "directories"). But be‐
54 fore Netpbm 10.27 (March 2005), it ignored all but the first Netpbm im‐
55 age in the input stream.
56 The Output File
59 By default, the output goes to Standard Output. Alternatively, you can
60 specify an output file with the -output option and pamtotiff will write
61 its output directly to that file.
62 Because of the way the TIFF library (which pamtotiff uses) works, when
64 the program writes to Standard Output, it generates the entire TIFF im‐
65 age in a temporary file and then copies it to Standard Output; you may
66 see negative performance effects of this.
67 The -output method avoids the performance effects of the copy through
69 the temporary file, but there are restrictions on the output file: it
70 must be seekable and it must be readable. The program fails if it is
71 not. With Standard Output, neither of those restrictions applies.
72 With -output, if the file already exists and has data in it, pamtotiff
74 appends the image to the existing TIFF file. (A TIFF file may contain
75 multiple images).
76 By default, pamtotiff creates the file named by -output if it does not
78 already exist. But if you also specify -append, the program fails if
79 the file named by -output does not already exist.
80 Before Netpbm 10.67 (June 2014), there is no -output option and Stan‐
82 dard Output must be seekable. So pipes are out.
83 Before Netpbm 10.67 (June 2014), you could append to Standard Output.
85 See below. The current program does not have the ability; you must use
86 -output to append to an existing TIFF file.
87 The difference above means current pamtotiff is actually not backward
89 compatible, which is a rare thing for Netpbm. But it's a good thing
90 because the previous function was very strange and probably hardly ever
91 exploited.
92 Old Versions
95 As alluded to above, pamtotiff does output very differently in releases
97 before 10.67. The following describes the old function, which is un‐
98 usual both for Netpbm and for Unix programs in general.
99 • The output file must be seekable. pamtotiff does not write it
103 sequentially. Therefore, you can't use a pipe; you can't pipe
104 the output of pamtotiff to some other program. But any regular
105 file should work.
106 • If the output file descriptor is readable, you must either spec‐
109 ify -append so as to add to the existing file, or make sure the
110 file is empty. Otherwise, pamtotiff will fail with an unhelpful
111 message telling you that a TIFF library function failed to open
112 the TIFF output stream.
113 • If you are converting multiple images (your input stream con‐
116 tains multiple images), the output file must be both readable
117 and writable.
118 If you're using a Unix command shell to run pamtotiff, you use facili‐
122 ties of your shell to set up Standard Output. In Bash, for example,
123 you would set up a write-only Standard Output to the file /tmp/myim‐
124 age.tiff like this:
125 $ pamtotiff myimage.pnm >/tmp/myimage.tiff
127 In Bash, you would set up a read/write Standard Output to the file
130 /tmp/myimage.tiff like this:
131 $ pamtotiff myimage.pnm 1<>/tmp/myimage.tiff
133 TIFF Capability
137 pamtotiff uses the Libtiff.org TIFF library (or whatever equivalent you
138 provide) to generate the TIFF output. Details of the format it pro‐
139 duces are therefore controlled by that library.
140
143 In addition to the options common to all programs based on libnetpbm
144 (most notably -quiet, see
145 Common Options ⟨index.html#commonoptions⟩ ), pamtotiff recognizes the
146 following command line options:
147 Compression
150 By default, pamtotiff creates a TIFF file with no compression. This is
151 your best bet most of the time. If you want to try another compression
152 scheme or tweak some of the other even more obscure output options,
153 there are a number of options which to play.
154 Before Netpbm 8.4 (April 2000), the default was to use LZW compression.
156 But then new releases of the TIFF library started omitting the LZW com‐
157 pression capability because of concern about patents on LZW. So since
158 then, the default has been no compression. The LZW patents have now
159 expired and new TIFF libraries do LZW, but the pamtotiff behavior re‐
160 mains the same for compatibility with older TIFF libraries and applica‐
161 tions of pamtotiff.
162 The -none, -packbits, -lzw, -g3, -g4, -flate, and -adobeflate options
164 are used to override the default and set the compression scheme used in
165 creating the output file.
166 The -predictor option is meaningful only with LZW compression: a pre‐
168 dictor value of 2 causes each scanline of the output image to undergo
169 horizontal differencing before it is encoded; a value of 1 forces each
170 scanline to be encoded without differencing. By default, pamtotiff
171 creates a TIFF file with msb-to-lsb fill order. The -msb2lsb and
172 -lsb2msb options are used to override the default and set the fill or‐
173 der used in creating the file.
174 With some older TIFF libraries, -lzw doesn't work because the TIFF li‐
176 brary doesn't do LZW compression. This is because of concerns about
177 Unisys's patent on LZW which was then in force. Actually, with very
178 old TIFF libraries, -lzw works because no distributors of the TIFF li‐
179 brary were sensitive yet to the patent issue.
180 -flate chooses "flate" compression, which is the patent-free compres‐
182 sion common in the Unix world implemented by the "Z" library. It is
183 what the PNG format uses.
184 Fax Compression
186 If you have bilevel data (e.g. PBM), you can generate a TIFF that uses
188 the same compression scheme specified for use by fax machines. See the
189 Fax Format(1) page for more information on these compression schemes.
190 These formats all relate to ITU Group 3 and Group 4 fax machine stan‐
192 dards.
193 The -g3 option chooses MH or MR compression: MR with the additional op‐
195 tion -2d; MH without it. -g4 selects MMR. The option names are a lit‐
196 tle unfortunate and historical, but are consistent with the TIFF speci‐
197 fication.
198 MMR has a better compression ratio than the other two.
200 -fill specifies that for MH or MR compression, each encoded scanline
202 shall be zero-filled to a byte boundary.
203 -2d and -fill are meaningful only with -g3.
205 Fill Order
209 The -msb2lsb and lsb2msb options control the fill order.
210 The fill order is the order in which pixels are packed into a byte in
212 the Tiff raster, in the case that there are multiple pixels per byte.
213 msb-to-lsb means that the leftmost columns go into the most significant
214 bits of the byte in the Tiff image. However, there is considerable
215 confusion about the meaning of fill order. Some believe it means
216 whether 16 bit sample values in the Tiff image are little-endian or
217 big-endian. This is totally erroneous (The endianness of integers in a
218 Tiff image is designated by the image's magic number). However, Image‐
219 Magick and older Netpbm both have been known to implement that inter‐
220 pretation. 2001.09.06.
221 If the image does not have sub-byte pixels, these options have no ef‐
223 fect other than to set the value of the FILLORDER tag in the Tiff image
224 (which may be useful for those programs that misinterpret the tag with
225 reference to 16 bit samples).
226 Color Space
229 -color tells pamtotiff to produce a color, as opposed to grayscale,
230 TIFF image if the input is PPM, even if it contains only shades of
231 gray. Without this option, pamtotiff produces a grayscale TIFF image
232 if the input is PPM and contains only shades of gray, and at most 256
233 shades. Otherwise, it produces a color TIFF output. For PBM and PGM
234 input, pamtotiff always produces grayscale TIFF output and this option
235 has no effect.
236 The -color option can prevent pamtotiff from making two passes through
238 the input file, thus improving speed and memory usage. See Multiple
239 Passes ⟨#multipass⟩ .
240 -truecolor tells pamtotiff to produce the 24-bit RGB form of TIFF out‐
242 put if it is producing a color TIFF image. Without this option, pamto‐
243 tiff produces a colormapped (paletted) TIFF image unless there are more
244 than 256 colors (and in the latter case, issues a warning).
245 The -truecolor option can prevent pamtotiff from making two passes
247 through the input file, thus improving speed and memory usage. See
248 Multiple Passes ⟨#multipass⟩ .
249 The -color and -truecolor options did not exist before Netpbm 9.21 (De‐
251 cember 2001).
252 If pamtotiff produces a grayscale TIFF image, this option has no ef‐
254 fect.
255 The -minisblack and -miniswhite options force the output image to have
257 a "minimum is black" or "minimum is white" photometric, respectively.
258 If you don't specify either, pamtotiff uses minimum is black except
259 when using Group 3 or Group 4 compression, in which case pamtotiff fol‐
260 lows CCITT fax standards and uses "minimum is white." This usually re‐
261 sults in better compression and is generally preferred for bilevel cod‐
262 ing. These photometrics are for grayscale images, so these options are
263 invalid if the image is color (but only if it is truly color; they are
264 valid with, for example, a PPM image that contains only shades of
265 gray).
266 Before Netpbm 9.11 (February 200)1, pamtotiff always produced "minimum
268 is black," because of a bug. In either case, pamtotiff sets the photo‐
269 metric interpretation tag in the TIFF output according to which photo‐
270 metric is actually used.
271 Before Netpbm 10.78 (March 2017), pamtotiff respected -miniswhite and
273 -minisblack even with color images, producing invalid TIFF images that
274 have the indicated photometric but red, green, and blue raster planes.
275 The -indexbits option is meaningful only for a colormapped (paletted)
277 image. In this kind of image, the raster contains values which are in‐
278 dexes into a table of colors, with the indexes normally taking less
279 space that the color description in the table. pamtotiff can generate
280 indexes of 1, 2, 4, or 8 bits. By default, it will use 8, because many
281 programs that interpret TIFF images can't handle any other width.
282 But if you have a small number of colors, you can make your image con‐
284 siderably smaller by allowing fewer than 8 bits per index, using the
285 -indexbits option. The value is a comma-separated list of the bit
286 widths you allow. pamtotiff chooses the smallest width you allow that
287 allows it to index the entire color table. If you don't allow any such
288 width, pamtotiff fails. Normally, the only useful value for this op‐
289 tion is 1,2,4,8, because a program either understands the 8 bit width
290 (default) or understands them all.
291 In a Baseline TIFF image, according to the 1992 TIFF 6.0 specification,
293 4 and 8 are the only valid widths. There are no formal standards that
294 allow any other values.
295 This option was added in June 2002. Before that, only 8 bit indices
297 were possible.
298 Extra Tags
301 There are lots of tag types in the TIFF format that don't correspond to
302 any information in the PNM format or to anything in the conversion
303 process. For example, a TIFF_ARTIST tag names the artist who created
304 the image.
305 You can tell pamtotiff explicitly to include tags such as this in its
307 output with the -tag option. You identify a list of tag types and val‐
308 ues and pamtotiff includes a tag in the output for each item in your
309 list.
310 The value of -tag is the list of tags, like this example:
312 -tag=subfiletype=reducedimage,documentname=Fred,xposition=25
314 As you see, it is a list of tag specifications separated by commas.
317 Each tag specification is a name and a value separated by an equal
318 sign. The name is the name of the tag type, except in arbitrary up‐
319 per/lower case. One place to see the names of TIFF tag types is in the
320 TIFF library's tiff.h file, where there is a macro defined for each
321 consisting of "TIFF_" plus the name. E.g. for the SUBFILETYPE tag
322 type, there is a macro TIFF_SUBFILETYPE.
323 The format of the value specification for a tag (stuff after the equal
325 sign) depends upon what kind of value the tag type has:
326 • Integer: a decimal number
330 • Floating point number: a decimal number
333 • String: a string
336 • Enumerated (For example, a 'subfiletype' tag takes an enumerated
339 value. Its possible values are REDUCEDIMAGE, PAGE, and MASK.):
340 The name of the value. You can see the possible value names in
341 the TIFF library's tiff.h file, where there is a macro defined
342 for each consisting of a qualifier plus the value name. E.g.
343 for the REDUCEDIMAGE value of a SUBFILETYPE tag, you see the
344 macro FILETYPE_REDUCEDIMAGE.
345 The TIFF format assigns a unique number to each enumerated value
347 and you can specify that number, in decimal, as an alternative.
348 This is useful if you are using an extension of TIFF that pamto‐
349 tiff doesn't know about.
350 If you specify a tag type with -tag that is not independent of the con‐
354 tent of your PNM source image and pamtotiff's conversion process (i.e.
355 a tag type in which pamtotiff is interested), pamtotiff fails. For ex‐
356 ample, you cannot specify an IMAGEWIDTH tag with -tag, because pamto‐
357 tiff generates an IMAGEWIDTH tag that gives the actual width of the im‐
358 age.
359 -tag was new in Netpbm 10.31 (December 2005).
361 Output
364 See The Output File ⟨#output⟩ .
365 -output names the output file. Without this option pamtotiff writes to
367 Standard Output.
368 The -append option tells pamtotiff only to append to the file named by
370 output; not create it. Without this option, the program creates the
371 file it does not already exist. But even then, if the file does al‐
372 ready exist, the program appends the image to what is in the file al‐
373 ready. (A TIFF file may contain multiple images).
374 -append has no effect if you don't also specify -output.
376 Before Netpbm 10.67 (June 2014), -append means something rather differ‐
378 ent: it means to append the image to the output TIFF file (which is al‐
379 ways Standard Output in 10.67) instead of replacing its contents.
380 -append was new in Netpbm 10.27 (March 2005).
382 Other
387 You can use the -rowsperstrip option to set the number of rows (scan‐
388 lines) in each strip of data in the output file. By default, the out‐
389 put file has the number of rows per strip set to a value that will en‐
390 sure each strip is no more than 8 kilobytes long.
391
395 There are myriad variations of the TIFF format, and this program gener‐
396 ates only a few of them. pamtotiff creates a grayscale TIFF file if
397 its input is a PBM (monochrome) or PGM (grayscale) or equivalent PAM
398 file. pamtotiff also creates a grayscale file if it input is PPM
399 (color) or equivalent PAM, but there is only one color in the image.
400 If the input is a PPM (color) file and there are 256 colors or fewer,
402 but more than 1, pamtotiff generates a color palette TIFF file. If
403 there are more colors than that, pamtotiff generates an RGB (not RGBA)
404 single plane TIFF file. Use pnmtotiffcmyk to generate the cyan-ma‐
405 genta-yellow-black ink color separation TIFF format.
406 The number of bits per sample in the TIFF output is determined by the
408 maxval of the Netpbm input. If the maxval is less than 256, the bits
409 per sample in the output is the smallest number that can encode the
410 maxval. If the maxval is greater than or equal to 256, there are 16
411 bits per sample in the output.
412 Extra Channels
415 Like most Netpbm programs, pamtotiff's function is mostly undefined if
416 the input is PAM image with tuple type other than BLACKANDWHITE,
417 GRAYSCALE, or RGB. Most of the statements in this manual assume the
418 input is not such an exotic PAM. But there is a little defined pro‐
419 cessing of other PAM subformats.
420 pamtotiff assumes any 1 plane PAM image is BLACKANDWHITE or GRAYSCALE
422 (and doesn't distinguish between those two).
423 pamtotiff assumes a PAM with more than 1 plane is of tuple type RGB ex‐
425 cept with that number of planes instead of 3. pamtotiff doesn't really
426 understand red, green, and blue, so it has no trouble with a 2-compo‐
427 nent or 5-component color space. The TIFF format allows an arbitrary
428 number of color components, so pamtotiff simply maps the PAM planes di‐
429 rectly to TIFF color components. I don't know if the meanings of 5
430 components in a TIFF image are standard at all, but the function is
431 there if you want to use it.
432 Note that pamtotiff may generate either a truecolor or colormapped im‐
434 age with an arbitrary number of color components. In the truecolor
435 case, the raster has that number of planes. In the colormapped case,
436 the raster has of course 1 plane, but the color map has all the color
437 components in it.
438 The most common reason for a PAM to have extra planes is when the tuple
440 type is xxx_ALPHA, which means the highest numbered plane is a trans‐
441 parency plane (alpha channel). At least one user found that a TIFF
442 with an extra plane for transparency was useful.
443 Note that the grayscale detection works on N-component colors, so if
445 your planes aren't really color components, you'll want to disable this
446 via the -color option.
447 Multiple Passes
451 pamtotiff reads the input image once if it can, and otherwise twice.
452 It needs that second pass (which happens before the main pass, of
453 course) to analyze the colors in the image and generate a color map
454 (palette) and determine if the image is grayscale. So the second pass
455 happens only when the input is PPM. And you can avoid it then by spec‐
456 ifying both the -truecolor and -color options.
457 If the input image is small enough to fit in your system's file cache,
459 the second pass is very fast. If not, it requires reading from disk
460 twice, which can be slow.
461 When the input is from a file that cannot be rewound and reread, pamto‐
463 tiff reads the entire input image into a temporary file which can, and
464 works from that. Even if it needs only one pass.
465 Before Netpbm 9.21 (December 2001), pamtotiff always read the entire
467 image into virtual memory and then did one, two, or three passes
468 through the memory copy. The -truecolor and -color options did not ex‐
469 ist. The passes through memory would involve page faults if the entire
470 image did not fit into real memory. The image in memory required con‐
471 siderably more memory (12 bytes per pixel) than the cached file version
472 of the image would.
473 Resolution
477 A Tiff image may contain information about the resolution of the image,
478 which means how big in real dimensions (centimeters, etc.) each pixel
479 in the raster is. That information is in the TIFF XRESOLUTION, YRESO‐
480 LUTION, and RESOLUTIONUNIT tags. By default, pamtotiff does not in‐
481 clude any tags of these types, but you can specify them with the -tags
482 option.
483 There are also options -xresolution, -yresolution, and -resolutionunit,
485 but those are obsolete. Before -tags existed (before Netpbm 10.31 (De‐
486 cember 2005), they were the only way.
487 Note that the number of pixels in the image and how much information
489 each contains is determined independently from the setting of the reso‐
490 lution tags. The number of pixels in the output is the same as in the
491 input, and each pixel contains the same information. For your resolu‐
492 tion tags to be meaningful, they have to consistent with whatever cre‐
493 ated the PNM input. E.g. if a scanner turned a 10 centimeter wide im‐
494 age into a 1000 pixel wide PNM image, then your horizontal resolution
495 is 100 pixels per centimeter, and if your XRESOLUTION tag says anything
496 else, something that prints your TIFF image won't print the proper 10
497 centimeter image.
498 The value of the XRESOLUTION tag is a floating point decimal number
500 that tells how many pixels there are per unit of distance in the hori‐
501 zontal direction. -yresolution is analogous for the vertical direc‐
502 tion.
503 The unit of distance is given by the value of the RESOLUTIONUNIT op‐
505 tion. That value is either INCH, CENTIMETER, or NONE. NONE means the
506 unit is arbitrary or unspecified. This could mean that the creator and
507 user of the image have a separate agreement as to what the unit is.
508 But usually, it just means that the horizontal and vertical resolution
509 values cannot be used for anything except to determine aspect ratio
510 (because even though the unit is arbitrary or unspecified, it has to be
511 the same for both resolution numbers).
512 If you don't use a -tag option to specify the resolution tag and use
514 the obsolete options instead, note the following:
515 • If you don't include an specify -xresolution, the Tiff image
519 does not contain horizontal resolution information. Likewise
520 for -yresolution. If you don't specify -resolutionunit, the de‐
521 fault is inches.
522 • Before Netpbm 10.16 (June 2003), -resolutionunit did not exist
525 and the resolution unit was always inches.
526
531 pamtotiff was originally pnmtotiff and did not handle PAM input. It
532 was extended and renamed in Netpbm 10.30 (October 2005).
533
537 tifftopnm(1), pnmtotiffcmyk(1), pamdepth(1), pamtopnm(1), pam(1)
538
541 Derived by Jef Poskanzer from ras2tiff.c, which is Copyright (c) 1990
542 by Sun Microsystems, Inc. Author: Patrick J. Naughton
543 (naughton@wind.sun.com).
544
546 This manual page was generated by the Netpbm tool 'makeman' from HTML
547 source. The master documentation is at
548 http://netpbm.sourceforge.net/doc/pamtotiff.html
550netpbm documentation 05 April 2017 Pamtotiff User Manual(0)