1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML><HEAD><TITLE>Pamtotiff User Manual</TITLE></HEAD>
<BODY>
<H1>pamtotiff</H1>
Updated: 03 December 2008
<BR>
<A HREF="#index">Table Of Contents</A>
<H2>NAME</H2>
pamtotiff - convert a Netpbm image to a TIFF file
<H2 id="synopsis">SYNOPSIS</H2>
<B>pamtotiff</B>
[<B>-none</B> | <B>-packbits</B> | <B>-lzw</B> | <B>-g3</B> | <B>-g4</B>
| <B>-flate</B> | <B>-adobeflate</B>]
[<B>-2d</B>]
[<B>-fill</B>]
[<B>-predictor=</B><I>n</I>]
[<B>-msb2lsb</B>|<B>-lsb2msb</B>]
[<B>-rowsperstrip=</B><I>n</I>]
[<B>-minisblack</B>|<B>-miniswhite</B>|<B>mb</B>|<b>mw</b>]
[<B>-truecolor</B>]
[<B>-color</B>]
[<B>-indexbits=</B><I>bitwidthlist</I>]
<br>
[<B>-xresolution=</b><i>xres</i>]
[<B>-yresolution=</b><i>yres</i>]
<br>
[<B>-resolutionunit=</b>{<b>inch</b> | <b>centimeter</b> | <b>none</b> |
<b>in</b> | <b>cm</b> | <b>no</b>}]
[<B>-indexbits=</b>[<b>1</b>[<b>2</b>[<b>4</b>[<b>8</b>]]]]]
[<b>-append</b>]
[<b>-tag=</b><i>taglist</i>]
[<I>pamfile</I>]
<P>You can use the minimum unique abbreviation of the options. You
can use two hyphens instead of one. You can separate an option name
from its value with white space instead of an equals sign.
<H2 id="description">DESCRIPTION</H2>
<p>This program is part of <a href="index.html">Netpbm</a>.
<p><b>pamtotiff</b> reads a PNM or PAM image as input and produces a TIFF file
as output.
<p>Actually, it handles multi-image Netpbm streams, producing multi-image
TIFF streams (i.e. a TIFF stream with multiple
"directories"). But before Netpbm 10.27 (March 2005), it
ignored all but the first Netpbm image in the input stream.
<h3 id="output">The Output File</h3>
<P>The output goes to Standard Output. <b>pamtotiff</b> approaches
this output file differently from Unix and Netpbm convention. This is
entirely due to <b>pamtotiff</b>'s use of the TIFF library to do all
TIFF output.
<ul>
<li>The output file must be seekable. <b>pamtotiff</b> does not
write it sequentially. Therefore, you can't use a pipe; you can't
pipe the output of <b>pamtotiff</b> to some other program. But any
regular file should work.
<li>If the output file descriptor is readable, you must either specify
<b>-append</b> so as to add to the existing file, or make sure the
file is empty. Otherwise, <b>pamtotiff</b> will fail with an
unhelpful message telling you that a TIFF library function failed to
open the TIFF output stream.
<li>If you are converting multiple images (your input stream contains
multiple images), the output file must be both readable and writable.
</ul>
<p>If you're using a Unix command shell to run <b>pamtotiff</b>, you
use facilities of your shell to set up Standard Output. In Bash,
for example, you would set up a write-only Standard Output to the
file /tmp/myimage.tiff like this:
<pre>
<tt>
$ pamtotiff myimage.pnm >/tmp/myimage.tiff
</tt>
</pre>
In Bash, you would set up a read/write Standard Output to the file
/tmp/myimage.tiff like this:
<pre>
<tt>
$ pamtotiff myimage.pnm 1<>/tmp/myimage.tiff
</tt>
</pre>
<h3 id="library">TIFF Capability</h3>
<p><b>pamtotiff</b> uses the Libtiff.org TIFF library (or whatever
equivalent you provide) to generate the TIFF output. Details of the
format it produces are therefore controlled by that library.
<H2 id="options">OPTIONS</H2>
<h3 id="compression">Compression</h3>
<P>By default, <B>pamtotiff</B> creates a TIFF file with no
compression. This is your best bet most of the time. If you want to
try another compression scheme or tweak some of the other even more
obscure output options, there are a number of options which which to
play.
<p>Before Netpbm 8.4 (April 2000), the default was to use LZW compression.
But then new releases of the TIFF library started omitting the LZW
compression capability due to concern about patents on LZW. So
since then, the default has been no compression. The LZW patents have
now expired and new TIFF libraries do LZW, but the <b>pamtotiff</b>
behavior remains the same for compatibility with older TIFF libraries
and applications of <b>pamtotiff</b>.
<P>The <B>-none</B>, <B>-packbits</B>, <B>-lzw</B>, <B>-g3</B>,
<B>-g4</B>, <B>-flate</B>, and <B>-adobeflate</B> options are used to
override the default and set the compression scheme used in creating
the output file.
The <B>-predictor</B> option is meaningful only with LZW compression: a
predictor value of 2 causes each scanline of the output image to undergo
horizontal differencing before it is encoded; a value of 1 forces each
scanline to be encoded without differencing. By default, <B>pamtotiff</B>
creates a TIFF file with msb-to-lsb fill order. The <B>-msb2lsb</B> and
<B>-lsb2msb</B> options are used to override the default and set the fill
order used in creating the file.
<P>With some older TIFF libraries, <B>-lzw</B> doesn't work because
the TIFF library doesn't do LZW compression. This is because of
concerns about Unisys's patent on LZW which was then in force.
Actually, with very old TIFF libraries, <b>-lzw</b> works because no
distributors of the TIFF library were sensitive yet to the patent
issue.
<p><b>-flate</b> chooses "flate" compression, which is the
patent-free compression common in the Unix world implemented by the
"Z" library. It is what the PNG format uses.
<H4 id="faxcompression">Fax Compression</H4>
<p>If you have bilevel data (e.g. PBM), you can generate a TIFF that uses the
same compression scheme specified for use by fax machines. See the <a
href="faxformat.html">Fax Format</a> page for more information on these
compression schemes.
<p>These formats all relate to ITU Group 3 and Group 4 fax machine
standards.
<p>The <b>-g3</b> option chooses MH or MR compression: MR with the additional
option <b>-2d</b>; MH without it. <b>-g4</b> selects MMR. The option names
are a little unfortunate and historical, but are consistent with the TIFF
specification.
<p>MMR has a better compression ratio than the other two.
<p><b>-fill</b> specifies that for MH or MR compression, each encoded scanline
shall be zero-filled to a byte boundary.
<p><b>-2d</b> and <b>-fill</b> are meaningful only with <b>-g3</b>.
<h3 id="fillorder">Fill Order</h3>
<p>The <b>-msb2lsb</b> and <b>lsb2msb</b> options control the fill order.
<P>The fill order is the order in which pixels are packed into a byte in
the Tiff raster, in the case that there are multiple pixels per byte.
msb-to-lsb means that the leftmost columns go into the most
significant bits of the byte in the Tiff image. However, there is
considerable confusion about the meaning of fill order. Some believe
it means whether 16 bit sample values in the Tiff image are
little-endian or big-endian. This is totally erroneous (The
endianness of integers in a Tiff image is designated by the image's
magic number). However, ImageMagick and older Netpbm both have been known
to implement that interpretation. 2001.09.06.
<P>If the image does not have sub-byte pixels, these options have no
effect other than to set the value of the FILLORDER tag in the Tiff
image (which may be useful for those programs that misinterpret the
tag with reference to 16 bit samples).
<h3 id="colorspace">Color Space</h3>
<P><B>-color</B> tells <B>pamtotiff</B> to produce a color, as
opposed to grayscale, TIFF image if the input is PPM, even if it
contains only shades of gray. Without this option, <B>pamtotiff</B>
produces a grayscale TIFF image if the input is PPM and contains only
shades of gray, and at most 256 shades. Otherwise, it produces a
color TIFF output. For PBM and PGM input, <B>pamtotiff</B> always
produces grayscale TIFF output and this option has no effect.
<P>The <B>-color</B> option can prevent <B>pamtotiff</B> from making
two passes through the input file, thus improving speed and memory
usage. See <a href="#multipass">Multiple Passes</a>.
<P><B>-truecolor</B> tells <B>pamtotiff</B> to produce the 24-bit RGB
form of TIFF output if it is producing a color TIFF image. Without
this option, <B>pamtotiff</B> produces a colormapped (paletted) TIFF
image unless there are more than 256 colors (and in the latter case,
issues a warning).
<P>The <B>-truecolor</B> option can prevent <B>pamtotiff</B> from
making two passes through the input file, thus improving speed and
memory usage. See <a href="#multipass">Multiple Passes</a>.
<P>The <B>-color</b> and <b>-truecolor</b> options did not exist
before Netpbm 9.21 (December 2001).
<P>If <B>pamtotiff</B> produces a grayscale TIFF image, this option
has no effect.
<P>The <B>-minisblack</B> and <B>-miniswhite</B> options force the
output image to have a "minimum is black" or "minimum
is white" photometric, respectively. If you don't specify
either, <B>pamtotiff</b> uses minimum is black except when using Group
3 or Group 4 compression, in which case <B>pamtotiff</B> follows CCITT
fax standards and uses "minimum is white." This usually
results in better compression and is generally preferred for bilevel
coding.
<P>Before February 2001, <B>pamtotiff</B> always produced
"minimum is black," due to a bug. In either case,
<B>pamtotiff</B> sets the photometric interpretation tag in the TIFF
output according to which photometric is actually used.
<P>The <B>-indexbits</B> option is meaningful only for a colormapped
(paletted) image. In this kind of image, the raster contains values
which are indexes into a table of colors, with the indexes normally
taking less space that the color description in the table.
<B>pamtotiff</B> can generate indexes of 1, 2, 4, or 8 bits. By
default, it will use 8, because many programs that interpret TIFF
images can't handle any other width.
<P>But if you have a small number of colors, you can make your image
considerably smaller by allowing fewer than 8 bits per index, using the
<B>-indexbits</B> option. The value is a comma-separated list of the
bit widths you allow. <B>pamtotiff</B> chooses the smallest width you allow
that allows it to index the entire color table. If you don't allow any
such width, <B>pamtotiff</B> fails. Normally, the only useful value for
this option is <B>1,2,4,8</B>, because a program either understands the 8
bit width (default) or understands them all.
<P>In a Baseline TIFF image, according to the 1992 TIFF 6.0
specification, 4 and 8 are the only valid widths. There are no formal
standards that allow any other values.
<P>This option was added in June 2002. Before that, only 8 bit indices were
possible.
<h3 id="extratags">Extra Tags</h3>
<p>There are lots of tag types in the TIFF format that don't correspond to
any information in the PNM format or to anything in the conversion process.
For example, a TIFF_ARTIST tag names the artist who created the image.
<p>You can tell <b>pamtotiff</b> explicitly to include tags such as this
in its output with the <b>-tag</b> option. You identify a list of tag
types and values and <b>pamtotiff</b> includes a tag in the output for
each item in your list.
<p>The value of <b>-tag</b> is the list of tags, like this example:
<pre>
<code>
-tag=subfiletype=reducedimage,documentname=Fred,xposition=25
</code>
</pre>
<p>As you see, it is a list of tag specifications separated by commas.
Each tag specification is a name and a value separated by an equal
sign. The name is the name of the tag type, except in arbitrary
upper/lower case. One place to see the names of TIFF tag types is in
the TIFF library's <b>tiff.h</b> file, where there is a macro defined
for each consisting of "TIFF_" plus the name. E.g. for
the SUBFILETYPE tag type, there is a macro TIFF_SUBFILETYPE.
<p>The format of the value specification for a tag (stuff after the
equal sign) depends upon what kind of value the tag type has:
<ul>
<li>Integer: a decimal number
<li>Floating point number: a decimal number
<li>String: a string
<li>Enumerated (For example, a 'subfiletype' tag takes an enumerated
value. Its possible values are REDUCEDIMAGE, PAGE, and MASK.): The
name of the value. You can see the possible value names in the TIFF
library's <b>tiff.h</b> foile, where there is a macro defined for each
consisting of a qualifier plus the value name. E.g. for the
REDUCEDIMAGE value of a SUBFILETYPE tag, you see the macro
FILETYPE_REDUCEDIMAGE.
<p>The TIFF format assigns a unique number to each enumerated value and
you can specify that number, in decimal, as an alternative. This is useful
if you are using an extension of TIFF that <b>pamtotiff</b> doesn't
know about.
</ul>
<p>If you specify a tag type with <b>-tag</b> that is not independent
of the content of your PNM source image and <b>pamtotiff</b>'s
conversion process (i.e. a tag type in which <b>pamtotiff</b> is
interested), <b>pamtotiff</b> fails. For example, you cannot specify
an IMAGEWIDTH tag with <b>-tag</b>, because <b>pamtotiff</b> generates
an IMAGEWIDTH tag that gives the actual width of the image.
<p><b>-tag</b> was new in Netpbm 10.31 (December 2005).
<h3 id="other">Other</h3>
<P>You can use the <B>-rowsperstrip</B> option to set the number of
rows (scanlines) in each strip of data in the output file. By
default, the output file has the number of rows per strip set to a
value that will ensure each strip is no more than 8 kilobytes long.
<p>The <b>-append</b> option tells <b>pamtotiff</b> to add images to
the existing output file (a TIFF file may contain multiple images)
instead of the default, which is to replace the output file.
<p><b>-append</b> was new in Netpbm 10.27 (March 2005).
<H2 id="notes">NOTES</H2>
<P>There are myriad variations of the TIFF format, and this program
generates only a few of them. <B>pamtotiff</B> creates a grayscale
TIFF file if its input is a PBM (monochrome) or PGM (grayscale) or
equivalent PAM file. <B>pamtotiff</B> also creates a grayscale file
if it input is PPM (color) or equivalent PAM, but there is only one
color in the image.
<p>If the input is a PPM (color) file and there are 256 colors or
fewer, but more than 1, <B>pamtotiff</B> generates a color palette
TIFF file. If there are more colors than that, <B>pamtotiff</B>
generates an RGB (not RGBA) single plane TIFF file. Use
<B>pnmtotiffcmyk</B> to generate the cyan-magenta-yellow-black ink
color separation TIFF format.
<P>The number of bits per sample in the TIFF output is determined by
the maxval of the Netpbm input. If the maxval is less than 256, the bits
per sample in the output is the smallest number that can encode the
maxval. If the maxval is greater than or equal to 256, there are 16
bits per sample in the output.
<h3 id="extrachannel">Extra Channels</h3>
<p>Like most Netpbm programs, <b>pamtotiff</b>'s function is mostly
undefined if the input is PAM image with tuple type other than
BLACKANDWHITE, GRAYSCALE, or RGB. Most of the statements in this manual
assume the input is not such an exotic PAM. But there is a little
defined processing of other PAM subformats.
<p><b>pamtotiff</b> assumes any 1 plane PAM image is BLACKANDWHITE
or GRAYSCALE (and doesn't distinguish between those two).
<p><b>pamtotiff</b> assumes a PAM with more than 1 plane is of tuple
type RGB except with that number of planes instead of 3.
<b>pamtotiff</b> doesn't really understand red, green, and blue, so it
has no trouble with a 2-component or 5-component color space. The
TIFF format allows an arbitrary number of color compoonents, so
<b>pamtotiff</b> simply maps the PAM planes directly to TIFF color
components. I don't know if the meanings of 5 components in a TIFF image
are standard at all, but the function is there if you want to use it.
<p>Note that <b>pamtotiff</b> may generate either a truecolor or
colormapped image with an arbitrary number of color components. In
the truecolor case, the raster has that number of planes. In the
colormapped case, the raster has of course 1 plane, but the color map
has all the color components in it.
<p>The most common reason for a PAM to have extra planes is when the tuple
type is xxx_ALPHA, which means the highest numbered plane is a transparency
plane (alpha channel). At least one user found that a TIFF with an extra
plane for transparency was useful.
<p>Note that the grayscale detection works on N-component colors, so if
your planes aren't really color components, you'll want to disable this
via the <b>-color</b> option.
<H3 id="multipass">Multiple Passes</H3>
<P><B>pamtotiff</B> reads the input image once if it can, and
otherwise twice. It needs that second pass (which happens before the
main pass, of course) to analyze the colors in the image and generate
a color map (palette) and determine if the image is grayscale. So the
second pass happens only when the input is PPM. And you can avoid it
then by specifying both the <B>-truecolor</B> and <B>-color</B>
options.
<P> If the input image is small enough to fit in your system's file
cache, the second pass is very fast. If not, it requires reading from
disk twice, which can be slow.
<P>When the input is from a file that cannot be rewound and reread,
<B>pamtotiff</B> reads the entire input image into a temporary file
which can, and works from that. Even if it needs only one pass.
<P>Before Netpbm 9.21 (December 2001), <b>pamtotiff</b> always read
the entire image into virtual memory and then did one, two, or three
passes through the memory copy. The <b>-truecolor</b> and
<b>-color</b> options did not exist. The passes through memory would
involve page faults if the entire image did not fit into real memory.
The image in memory required considerably more memory (12 bytes per
pixel) than the cached file version of the image would.
<h3>Resolution</h3>
<p>A Tiff image may contain information about the resolution of the image,
which means how big in real dimensions (centimeters, etc.) each pixel in the
raster is. That information is in the TIFF XRESOLUTION, YRESOLUTION,
and RESOLUTIONUNIT tags. By default, <b>pamtotiff</b> does not include
any tags of these types, but you can specify them with the <b>-tags</b>
option.
<p>There are also options <b>-xresolution</b>, <b>-yresolution</b>,
and <b>-resolutionunit</b>, but those are obsolete. Before <b>-tags</b>
existed (before Netpbm 10.31 (December 2005), they were the only way.
<p>Note that the number of pixels in the image and how much information
each contains is determined independently from the setting of the
resolution tags. The number of pixels in the output is the same as in
the input, and each pixel contains the same information. For your
resolution tags to be meaningful, they have to consistent with
whatever created the PNM input. E.g. if a scanner turned a 10 centimeter
wide image into a 1000 pixel wide PNM image, then your horizontal
resolution is 100 pixels per centimeter, and if your XRESOLUTION
tag says anything else, something that prints your TIFF image won't
print the proper 10 centimeter image.
<p>The value of the XRESOLUTION tag is a floating point decimal number
that tells how many pixels there are per unit of distance in the
horizontal direction. <b>-yresolution</b> is analogous for the
vertical direction.
<p>The unit of distance is given by the value of the RESOLUTIONUNIT
option. That value is either INCH, CENTIMETER, or NONE. NONE
means the unit is arbitrary or unspecified. This could mean that the
creator and user of the image have a separate agreement as to what the
unit is. But usually, it just means that the horizontal and vertical
resolution values cannot be used for anything except to determine
aspect ratio (because even though the unit is arbitrary or
unspecified, it has to be the same for both resolution numbers).
<p>If you <em>don't</em> use a <b>-tag</b> option to specify the
resolution tag and use the obsolete options instead, note the
following:
<ul>
<li>If you don't include an specify <b>-xresolution</b>, the Tiff image
does not contain horizontal resolution information. Likewise for
<b>-yresolution</b>. If you don't specify <b>-resolutionunit</b>, the
default is inches.
<li>Before Netpbm 10.16 (June 2003), <B>-resolutionunit</b> did not
exist and the resolution unit was always inches.
</ul>
<h2 id="history">HISTORY</h2>
<p><b>pamtotiff</b> was originally <b>pnmtotiff</b> and did not handle
PAM input. It was extended and renamed in Netpbm 10.30 (October 2005).
<H2 id="seealso">SEE ALSO</H2>
<B><A HREF="tifftopnm.html">tifftopnm</A></B>,
<B><A HREF="pnmtotiffcmyk.html">pnmtotiffcmyk</A></B>,
<B><A HREF="pamdepth.html">pamdepth</A></B>,
<B><A HREF="pamtopnm.html">pamtopnm</A></B>,
<B><A HREF="pam.html">pam</A></B>
<H2 id="author">AUTHOR</H2>
Derived by Jef Poskanzer from ras2tiff.c, which is
Copyright (c) 1990 by Sun Microsystems, Inc.
Author: Patrick J. Naughton (<A HREF="mailto:naughton@wind.sun.com">naughton@wind.sun.com</A>).
<HR>
<H2 id="index">Table Of Contents</H2>
<UL>
<LI><A HREF="#synopsis">SYNOPSIS</A>
<LI><A HREF="#description">DESCRIPTION</A>
<ul>
<li><a href="#outputfile">The Output File</a>
<li><a href="#library">TIFF Capability</a>
</ul>
<LI><A HREF="#options">OPTIONS</A>
<ul>
<li><a href="#compression">Compression</a>
<ul>
<li><a href="#faxcompression">Fax Compression</a>
</ul>
<li><a href="#fillorder">Fill Order</a>
<li><a href="#colorspacer">Color Space</a>
<li><a href="#extratags">Extra Tags</a>
<li><a href="#other">Other</a>
</ul>
<LI><A HREF="#notes">NOTES</A>
<UL>
<LI><A HREF="#multipass">Multiple Passes</A>
<LI><A HREF="#extrachannel">Extra Channels</A>
</UL>
<LI><A HREF="#history">HISTORY</A>
<LI><A HREF="#seealso">SEE ALSO</A>
<LI><A HREF="#author">AUTHOR</A>
</UL>
</BODY>
</HTML>
|
