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       [-indexbits=[1[2[4[8]]]]]
36
37       [-append]
38
39       [-tag=taglist]
40
41       [pamfile]
42
43       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
47

DESCRIPTION

49       This program is part of Netpbm(1).
50
51       pamtotiff reads a PNM or PAM image as input and produces a TIFF file as
52       output.
53
54       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
59
60   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
65
66
67       ·      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
72
73       ·      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
79
80       ·      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
84
85
86       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
91           $ pamtotiff myimage.pnm >/tmp/myimage.tiff
92
93       In Bash, you would set up a read/write  Standard  Output  to  the  file
94       /tmp/myimage.tiff like this:
95
96           $ pamtotiff myimage.pnm 1<>/tmp/myimage.tiff
97
98
99   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
104

OPTIONS

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
112       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
120       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
124       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
132       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
138       -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
142       Fax Compression
143
144       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(1)pageformoreinformationonthese compression schemes.
147
148       These formats all relate to ITU Group 3 and Group 4 fax  machine  stan‐
149       dards.
150
151       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
156       MMR has a better compression ratio than the other two.
157
158       -fill specifies that for MH or MR compression,  each  encoded  scanline
159       shall be zero-filled to a byte boundary.
160
161       -2d and -fill are meaningful only with -g3.
162
163
164
165   Fill Order
166       The -msb2lsb and lsb2msb options control the fill order.
167
168       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
179       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
184
185   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
194       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
198       -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
203       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
207       The -color and -truecolor options did  not  exist  before  Netpbm  9.21
208       (December 2001).
209
210       If  pamtotiff  produces  a  grayscale  TIFF  image,  this option has no
211       effect.
212
213       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
221       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
226       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
233       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
242       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
246       This  option  was  added in June 2002.  Before that, only 8 bit indices
247       were possible.
248
249
250   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
256       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
261       The value of -tag is the list of tags, like this example:
262
263           -tag=subfiletype=reducedimage,documentname=Fred,xposition=25
264
265       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
273       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
276
277
278       ·      Integer: a decimal number
279
280
281       ·      Floating point number: a decimal number
282
283
284       ·      String: a string
285
286
287       ·      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
295              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
300
301
302       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
309       -tag was new in Netpbm 10.31 (December 2005).
310
311
312   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
318       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
322       -append was new in Netpbm 10.27 (March 2005).
323
324
325

NOTES

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
333       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
339       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
345
346   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
353       pamtotiff assumes any 1 plane PAM image is BLACKANDWHITE  or  GRAYSCALE
354       (and doesn't distinguish between those two).
355
356       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
365       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
371       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
376       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
380
381
382   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
390        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
394       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
398       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
406
407
408   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
416       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
420       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
431       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
436       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
445       If you don't use a -tag option to specify the resolution  tag  and  use
446       the obsolete options instead, note the following:
447
448
449
450       ·      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
455
456       ·      Before Netpbm 10.16 (June 2003), -resolutionunit did  not  exist
457              and the resolution unit was always inches.
458
459
460
461

HISTORY

463       pamtotiff  was  originally  pnmtotiff and did not handle PAM input.  It
464       was extended and renamed in Netpbm 10.30 (October 2005).
465
466
467

SEE ALSO

469       tifftopnm(1), pnmtotiffcmyk(1), pamdepth(1), pamtopnm(1), pam(1)
470
471

AUTHOR

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).
476
477
478
479netpbm documentation           03 December 2008       Pamtotiff User Manual(0)
Impressum