1Pamtotiff User Manual(0)                              Pamtotiff User Manual(0)
2
3
4

NAME

6       pamtotiff - convert a Netpbm image to a TIFF file
7
8

SYNOPSIS

10       pamtotiff
11
12       [-none | -packbits | -lzw | -g3 | -g4 | -flate | -adobeflate]
13
14       [-2d]
15
16       [-fill]
17
18       [-predictor=n]
19
20       [-msb2lsb|-lsb2msb]
21
22       [-rowsperstrip=n]
23
24       [-minisblack|-miniswhite|mb|mw]
25
26       [-truecolor]
27
28       [-color]
29
30       [-indexbits=bitwidthlist] [-xresolution=xres]
31
32       [-yresolution=yres]  [-resolutionunit={inch  | centimeter | none | in |
33       cm | no}]
34
35       [-append]
36
37       [-tag=taglist]
38
39       [pamfile]
40
41       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
45

DESCRIPTION

47       This program is part of Netpbm(1).
48
49       pamtotiff reads a PNM or PAM image as input and produces a TIFF file as
50       output.
51
52       Actually,  it handles multi-image Netpbm streams, producing multi-image
53       TIFF streams (i.e. a TIFF stream  with  multiple  "directories").   But
54       before  Netpbm  10.27 (March 2005), it ignored all but the first Netpbm
55       image in the input stream.
56
57
58   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
63       Because of the way the TIFF library (which pamtotiff uses) works,  when
64       the  program  writes  to  Standard Output, it generates the entire TIFF
65       image in a temporary file and then copies it to  Standard  Output;  you
66       may see negative performance effects of this.
67
68       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
73       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
77       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
81       Before Netpbm 10.67 (June 2014), there is no -output option  and  Stan‐
82       dard Output must be seekable.  So pipes are out.
83
84       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
88       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
93
94       Old Versions
95
96       As alluded to above, pamtotiff does output very differently in releases
97       before  10.67.   The  following  describes  the  old function, which is
98       unusual both for Netpbm and for Unix programs in general.
99
100
101
102       ·      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
107
108       ·      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
114
115       ·      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
119
120
121       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
126           $ pamtotiff myimage.pnm >/tmp/myimage.tiff
127
128       In Bash, you would set up a read/write  Standard  Output  to  the  file
129       /tmp/myimage.tiff like this:
130
131           $ pamtotiff myimage.pnm 1<>/tmp/myimage.tiff
132
133
134   TIFF Capability
135       pamtotiff uses the Libtiff.org TIFF library (or whatever equivalent you
136       provide) to generate the TIFF output.  Details of the  format  it  pro‐
137       duces are therefore controlled by that library.
138
139

OPTIONS

141   Compression
142       By default, pamtotiff creates a TIFF file with no compression.  This is
143       your best bet most of the time.  If you want to try another compression
144       scheme  or  tweak  some  of the other even more obscure output options,
145       there are a number of options which to play.
146
147       Before Netpbm 8.4 (April 2000), the default was to use LZW compression.
148       But then new releases of the TIFF library started omitting the LZW com‐
149       pression capability because of concern about patents on LZW.  So  since
150       then,  the  default  has been no compression.  The LZW patents have now
151       expired and new TIFF libraries  do  LZW,  but  the  pamtotiff  behavior
152       remains the same for compatibility with older TIFF libraries and appli‐
153       cations of pamtotiff.
154
155       The -none, -packbits, -lzw, -g3, -g4, -flate, and  -adobeflate  options
156       are used to override the default and set the compression scheme used in
157       creating the output file.
158
159       The -predictor option is meaningful only with LZW compression:  a  pre‐
160       dictor  value  of 2 causes each scanline of the output image to undergo
161       horizontal differencing before it is encoded; a value of 1 forces  each
162       scanline  to  be  encoded  without differencing.  By default, pamtotiff
163       creates a TIFF file with  msb-to-lsb  fill  order.   The  -msb2lsb  and
164       -lsb2msb  options  are  used  to  override the default and set the fill
165       order used in creating the file.
166
167       With some older TIFF libraries, -lzw  doesn't  work  because  the  TIFF
168       library  doesn't do LZW compression.  This is because of concerns about
169       Unisys's patent on LZW which was then in force.   Actually,  with  very
170       old  TIFF  libraries,  -lzw  works  because no distributors of the TIFF
171       library were sensitive yet to the patent issue.
172
173       -flate chooses "flate" compression, which is the  patent-free  compres‐
174       sion  common  in  the Unix world implemented by the "Z" library.  It is
175       what the PNG format uses.
176
177       Fax Compression
178
179       If you have bilevel data (e.g. PBM), you can generate a TIFF that  uses
180       the same compression scheme specified for use by fax machines.  See the
181       Fax Format(1) page for more information on these compression schemes.
182
183       These formats all relate to ITU Group 3 and Group 4 fax  machine  stan‐
184       dards.
185
186       The  -g3  option  chooses  MH or MR compression: MR with the additional
187       option -2d; MH without it.  -g4 selects MMR.  The option  names  are  a
188       little  unfortunate  and  historical,  but are consistent with the TIFF
189       specification.
190
191       MMR has a better compression ratio than the other two.
192
193       -fill specifies that for MH or MR compression,  each  encoded  scanline
194       shall be zero-filled to a byte boundary.
195
196       -2d and -fill are meaningful only with -g3.
197
198
199
200   Fill Order
201       The -msb2lsb and lsb2msb options control the fill order.
202
203       The  fill  order is the order in which pixels are packed into a byte in
204       the Tiff raster, in the case that there are multiple pixels  per  byte.
205       msb-to-lsb means that the leftmost columns go into the most significant
206       bits of the byte in the Tiff image.   However,  there  is  considerable
207       confusion  about  the  meaning  of  fill  order.  Some believe it means
208       whether 16 bit sample values in the Tiff  image  are  little-endian  or
209       big-endian.  This is totally erroneous (The endianness of integers in a
210       Tiff image is  designated  by  the  image's  magic  number).   However,
211       ImageMagick  and  older  Netpbm  both have been known to implement that
212       interpretation.  2001.09.06.
213
214       If the image does not have  sub-byte  pixels,  these  options  have  no
215       effect  other  than  to  set the value of the FILLORDER tag in the Tiff
216       image (which may be useful for those programs that misinterpret the tag
217       with reference to 16 bit samples).
218
219
220   Color Space
221       -color  tells  pamtotiff  to  produce a color, as opposed to grayscale,
222       TIFF image if the input is PPM, even if  it  contains  only  shades  of
223       gray.   Without  this option, pamtotiff produces a grayscale TIFF image
224       if the input is PPM and contains only shades of gray, and at  most  256
225       shades.   Otherwise,  it produces a color TIFF output.  For PBM and PGM
226       input, pamtotiff always produces grayscale TIFF output and this  option
227       has no effect.
228
229       The  -color option can prevent pamtotiff from making two passes through
230       the input file, thus improving speed and memory  usage.   See  Multiple
231       Passes ⟨#multipass⟩ .
232
233       -truecolor  tells pamtotiff to produce the 24-bit RGB form of TIFF out‐
234       put if it is producing a color TIFF image.  Without this option, pamto‐
235       tiff produces a colormapped (paletted) TIFF image unless there are more
236       than 256 colors (and in the latter case, issues a warning).
237
238       The -truecolor option can prevent  pamtotiff  from  making  two  passes
239       through  the  input  file,  thus improving speed and memory usage.  See
240       Multiple Passes ⟨#multipass⟩ .
241
242       The -color and -truecolor options did  not  exist  before  Netpbm  9.21
243       (December 2001).
244
245       If  pamtotiff  produces  a  grayscale  TIFF  image,  this option has no
246       effect.
247
248       The -minisblack and -miniswhite options force the output image to  have
249       a  "minimum  is black" or "minimum is white" photometric, respectively.
250       If you don't specify either, pamtotiff uses  minimum  is  black  except
251       when using Group 3 or Group 4 compression, in which case pamtotiff fol‐
252       lows CCITT fax standards and uses  "minimum  is  white."  This  usually
253       results  in  better  compression and is generally preferred for bilevel
254       coding.  These photometrics are for grayscale images, so these  options
255       are  invalid if the image is color (but only if it is truly color; they
256       are valid with, for example, a PPM image that contains only  shades  of
257       gray).
258
259       Before  Netpbm 9.11 (February 200)1, pamtotiff always produced "minimum
260       is black," because of a bug.  In either case, pamtotiff sets the photo‐
261       metric  interpretation tag in the TIFF output according to which photo‐
262       metric is actually used.
263
264       Before Netpbm 10.78 (March 2017), pamtotiff respected  -miniswhite  and
265       -minisblack  even with color images, producing invalid TIFF images that
266       have the indicated photometric but red, green, and blue raster planes.
267
268       The -indexbits option is meaningful only for a  colormapped  (paletted)
269       image.   In  this  kind  of image, the raster contains values which are
270       indexes into a table of colors, with the indexes normally  taking  less
271       space  that the color description in the table.  pamtotiff can generate
272       indexes of 1, 2, 4, or 8 bits.  By default, it will use 8, because many
273       programs that interpret TIFF images can't handle any other width.
274
275       But  if you have a small number of colors, you can make your image con‐
276       siderably smaller by allowing fewer than 8 bits per  index,  using  the
277       -indexbits  option.   The  value  is  a comma-separated list of the bit
278       widths you allow.  pamtotiff chooses the smallest width you allow  that
279       allows it to index the entire color table.  If you don't allow any such
280       width, pamtotiff fails.  Normally,  the  only  useful  value  for  this
281       option is 1,2,4,8, because a program either understands the 8 bit width
282       (default) or understands them all.
283
284       In a Baseline TIFF image, according to the 1992 TIFF 6.0 specification,
285       4  and 8 are the only valid widths.  There are no formal standards that
286       allow any other values.
287
288       This option was added in June 2002.  Before that, only  8  bit  indices
289       were possible.
290
291
292   Extra Tags
293       There are lots of tag types in the TIFF format that don't correspond to
294       any information in the PNM format or  to  anything  in  the  conversion
295       process.   For  example, a TIFF_ARTIST tag names the artist who created
296       the image.
297
298       You can tell pamtotiff explicitly to include tags such as this  in  its
299       output with the -tag option.  You identify a list of tag types and val‐
300       ues and pamtotiff includes a tag in the output for each  item  in  your
301       list.
302
303       The value of -tag is the list of tags, like this example:
304
305           -tag=subfiletype=reducedimage,documentname=Fred,xposition=25
306
307       As  you  see,  it  is a list of tag specifications separated by commas.
308       Each tag specification is a name and a  value  separated  by  an  equal
309       sign.   The  name  is  the  name  of  the tag type, except in arbitrary
310       upper/lower case.  One place to see the names of TIFF tag types  is  in
311       the TIFF library's tiff.h file, where there is a macro defined for each
312       consisting of "TIFF_" plus the name.   E.g.  for  the  SUBFILETYPE  tag
313       type, there is a macro TIFF_SUBFILETYPE.
314
315       The  format of the value specification for a tag (stuff after the equal
316       sign) depends upon what kind of value the tag type has:
317
318
319
320       ·      Integer: a decimal number
321
322
323       ·      Floating point number: a decimal number
324
325
326       ·      String: a string
327
328
329       ·      Enumerated (For example, a 'subfiletype' tag takes an enumerated
330              value.   Its possible values are REDUCEDIMAGE, PAGE, and MASK.):
331              The name of the value.  You can see the possible value names  in
332              the  TIFF  library's tiff.h file, where there is a macro defined
333              for each consisting of a qualifier plus the  value  name.   E.g.
334              for  the  REDUCEDIMAGE  value  of a SUBFILETYPE tag, you see the
335              macro FILETYPE_REDUCEDIMAGE.
336
337              The TIFF format assigns a unique number to each enumerated value
338              and  you can specify that number, in decimal, as an alternative.
339              This is useful if you are using an extension of TIFF that pamto‐
340              tiff doesn't know about.
341
342
343
344       If you specify a tag type with -tag that is not independent of the con‐
345       tent of your PNM source image and pamtotiff's conversion process  (i.e.
346       a  tag  type  in  which pamtotiff is interested), pamtotiff fails.  For
347       example, you cannot specify an IMAGEWIDTH tag with -tag, because pamto‐
348       tiff  generates  an  IMAGEWIDTH  tag that gives the actual width of the
349       image.
350
351       -tag was new in Netpbm 10.31 (December 2005).
352
353
354   Output
355       See The Output File ⟨output⟩ .
356
357       -output names the output file.  Without this option pamtotiff writes to
358       Standard Output.
359
360       The  -append option tells pamtotiff only to append to the file named by
361       output; not create it.  Without this option, the  program  creates  the
362       file  it  does  not  already  exist.   But  even then, if the file does
363       already exist, the program appends the image to what  is  in  the  file
364       already.  (A TIFF file may contain multiple images).
365
366       -append has no effect if you don't also specify -output.
367
368       Before Netpbm 10.67 (June 2014), -append means something rather differ‐
369       ent: it means to append the image to the output  TIFF  file  (which  is
370       always Standard Output in 10.67) instead of replacing its contents.
371
372       -append was new in Netpbm 10.27 (March 2005).
373
374
375
376
377   Other
378       You  can  use the -rowsperstrip option to set the number of rows (scan‐
379       lines) in each strip of data in the output file.  By default, the  out‐
380       put  file  has  the  number  of rows per strip set to a value that will
381       ensure each strip is no more than 8 kilobytes long.
382
383
384

NOTES

386       There are myriad variations of the TIFF format, and this program gener‐
387       ates  only  a  few of them.  pamtotiff creates a grayscale TIFF file if
388       its input is a PBM (monochrome) or PGM (grayscale)  or  equivalent  PAM
389       file.   pamtotiff  also  creates  a  grayscale  file if it input is PPM
390       (color) or equivalent PAM, but there is only one color in the image.
391
392       If the input is a PPM (color) file and there are 256 colors  or  fewer,
393       but  more  than  1,  pamtotiff generates a color palette TIFF file.  If
394       there are more colors than that, pamtotiff generates an RGB (not  RGBA)
395       single  plane  TIFF  file.   Use  pnmtotiffcmyk  to  generate the cyan-
396       magenta-yellow-black ink color separation TIFF format.
397
398       The number of bits per sample in the TIFF output is determined  by  the
399       maxval  of  the Netpbm input.  If the maxval is less than 256, the bits
400       per sample in the output is the smallest number  that  can  encode  the
401       maxval.   If  the  maxval is greater than or equal to 256, there are 16
402       bits per sample in the output.
403
404
405   Extra Channels
406       Like most Netpbm programs, pamtotiff's function is mostly undefined  if
407       the  input  is  PAM  image  with  tuple  type other than BLACKANDWHITE,
408       GRAYSCALE, or RGB.  Most of the statements in this  manual  assume  the
409       input  is  not  such an exotic PAM.  But there is a little defined pro‐
410       cessing of other PAM subformats.
411
412       pamtotiff assumes any 1 plane PAM image is BLACKANDWHITE  or  GRAYSCALE
413       (and doesn't distinguish between those two).
414
415       pamtotiff  assumes  a  PAM  with more than 1 plane is of tuple type RGB
416       except with that number of planes  instead  of  3.   pamtotiff  doesn't
417       really  understand  red,  green,  and blue, so it has no trouble with a
418       2-component or 5-component color space.   The  TIFF  format  allows  an
419       arbitrary  number of color components, so pamtotiff simply maps the PAM
420       planes directly to TIFF color components.  I don't know if the meanings
421       of  5  components in a TIFF image are standard at all, but the function
422       is there if you want to use it.
423
424       Note that pamtotiff may generate  either  a  truecolor  or  colormapped
425       image  with  an arbitrary number of color components.  In the truecolor
426       case, the raster has that number of planes.  In the  colormapped  case,
427       the  raster  has of course 1 plane, but the color map has all the color
428       components in it.
429
430       The most common reason for a PAM to have extra planes is when the tuple
431       type  is  xxx_ALPHA, which means the highest numbered plane is a trans‐
432       parency plane (alpha channel).  At least one user  found  that  a  TIFF
433       with an extra plane for transparency was useful.
434
435       Note  that  the  grayscale detection works on N-component colors, so if
436       your planes aren't really color components, you'll want to disable this
437       via the -color option.
438
439
440
441   Multiple Passes
442       pamtotiff  reads  the  input image once if it can, and otherwise twice.
443       It needs that second pass (which  happens  before  the  main  pass,  of
444       course)  to  analyze  the  colors in the image and generate a color map
445       (palette) and determine if the image is grayscale.  So the second  pass
446       happens only when the input is PPM.  And you can avoid it then by spec‐
447       ifying both the -truecolor and -color options.
448
449        If the input image is small enough to fit in your system's file cache,
450       the  second  pass  is very fast.  If not, it requires reading from disk
451       twice, which can be slow.
452
453       When the input is from a file that cannot be rewound and reread, pamto‐
454       tiff  reads the entire input image into a temporary file which can, and
455       works from that.  Even if it needs only one pass.
456
457       Before Netpbm 9.21 (December 2001), pamtotiff always  read  the  entire
458       image  into  virtual  memory  and  then  did  one, two, or three passes
459       through the memory copy.  The -truecolor and  -color  options  did  not
460       exist.   The  passes  through  memory  would involve page faults if the
461       entire image did not  fit  into  real  memory.   The  image  in  memory
462       required  considerably more memory (12 bytes per pixel) than the cached
463       file version of the image would.
464
465
466
467   Resolution
468       A Tiff image may contain information about the resolution of the image,
469       which  means  how big in real dimensions (centimeters, etc.) each pixel
470       in the raster is.  That information is in the TIFF XRESOLUTION,  YRESO‐
471       LUTION,  and  RESOLUTIONUNIT  tags.   By  default,  pamtotiff  does not
472       include any tags of these types, but you  can  specify  them  with  the
473       -tags option.
474
475       There are also options -xresolution, -yresolution, and -resolutionunit,
476       but those are obsolete.  Before  -tags  existed  (before  Netpbm  10.31
477       (December 2005), they were the only way.
478
479       Note  that  the  number of pixels in the image and how much information
480       each contains is determined independently from the setting of the reso‐
481       lution  tags.  The number of pixels in the output is the same as in the
482       input, and each pixel contains the same information.  For your  resolu‐
483       tion  tags to be meaningful, they have to consistent with whatever cre‐
484       ated the PNM input.  E.g. if a scanner  turned  a  10  centimeter  wide
485       image into a 1000 pixel wide PNM image, then your horizontal resolution
486       is 100 pixels per centimeter, and if your XRESOLUTION tag says anything
487       else,  something  that prints your TIFF image won't print the proper 10
488       centimeter image.
489
490       The value of the XRESOLUTION tag is a  floating  point  decimal  number
491       that  tells how many pixels there are per unit of distance in the hori‐
492       zontal direction.  -yresolution is analogous for  the  vertical  direc‐
493       tion.
494
495       The  unit  of  distance  is  given  by  the value of the RESOLUTIONUNIT
496       option.  That value is either INCH, CENTIMETER, or  NONE.   NONE  means
497       the unit is arbitrary or unspecified.  This could mean that the creator
498       and user of the image have a separate agreement as to what the unit is.
499       But  usually, it just means that the horizontal and vertical resolution
500       values cannot be used for anything except  to  determine  aspect  ratio
501       (because even though the unit is arbitrary or unspecified, it has to be
502       the same for both resolution numbers).
503
504       If you don't use a -tag option to specify the resolution  tag  and  use
505       the obsolete options instead, note the following:
506
507
508
509       ·      If  you  don't  include  an specify -xresolution, the Tiff image
510              does not contain horizontal  resolution  information.   Likewise
511              for  -yresolution.   If  you  don't specify -resolutionunit, the
512              default is inches.
513
514
515       ·      Before Netpbm 10.16 (June 2003), -resolutionunit did  not  exist
516              and the resolution unit was always inches.
517
518
519
520

HISTORY

522       pamtotiff  was  originally  pnmtotiff and did not handle PAM input.  It
523       was extended and renamed in Netpbm 10.30 (October 2005).
524
525
526

SEE ALSO

528       tifftopnm(1), pnmtotiffcmyk(1), pamdepth(1), pamtopnm(1), pam(1)
529
530

AUTHOR

532       Derived by Jef Poskanzer from ras2tiff.c, which is Copyright  (c)  1990
533       by    Sun    Microsystems,    Inc.    Author:   Patrick   J.   Naughton
534       (naughton@wind.sun.com).
535

DOCUMENT SOURCE

537       This manual page was generated by the Netpbm tool 'makeman'  from  HTML
538       source.  The master documentation is at
539
540              http://netpbm.sourceforge.net/doc/pamtotiff.html
541
542netpbm documentation             05 April 2017        Pamtotiff User Manual(0)
Impressum