Provided by: netpbm_11.07.00-2_amd64 bug

NAME

       pamtotiff - convert a Netpbm image to a TIFF file

SYNOPSIS

       pamtotiff

       [-none | -packbits | -lzw | -g3 | -g4 | -flate | -adobeflate]

       [-2d]

       [-fill]

       [-predictor=n]

       [-msb2lsb|-lsb2msb]

       [-rowsperstrip=n]

       [-minisblack|-miniswhite|mb|mw]

       [-truecolor]

       [-color]

       [-indexbits=bitwidthlist] [-xresolution=xres]

       [-yresolution=yres] [-resolutionunit={inch | centimeter | none | in | cm | no}]

       [-append]

       [-tag=taglist]

       [pamfile]

       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.

DESCRIPTION

       This program is part of Netpbm(1).

       pamtotiff reads a PNM or PAM image as input and produces a TIFF file as output.

       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.

   The Output File
       By default, the output goes to Standard Output.  Alternatively, you can specify an output file  with  the
       -output option and pamtotiff will write its output directly to that file.

       Because  of  the  way  the TIFF library (which pamtotiff uses) works, when the program writes to Standard
       Output, it generates the entire TIFF image in a temporary file and then copies it to Standard Output; you
       may see negative performance effects of this.

       The  -output  method avoids the performance effects of the copy through the temporary file, but there are
       restrictions on the output file: it must be seekable and it must be readable.  The program fails if it is
       not.  With Standard Output, neither of those restrictions applies.

       With  -output, if the file already exists and has data in it, pamtotiff appends the image to the existing
       TIFF file.  (A TIFF file may contain multiple images).

       By default, pamtotiff creates the file named by -output if it does not already exist.  But  if  you  also
       specify -append, the program fails if the file named by -output does not already exist.

       Before  Netpbm  10.67  (June  2014), there is no -output option and Standard Output must be seekable.  So
       pipes are out.

       Before Netpbm 10.67 (June 2014), you could append to Standard Output.  See below.   The  current  program
       does not have the ability; you must use -output to append to an existing TIFF file.

       The  difference  above means current pamtotiff is actually not backward compatible, which is a rare thing
       for Netpbm.  But it's a good thing because the previous function was very  strange  and  probably  hardly
       ever exploited.

       Old Versions

       As  alluded  to  above,  pamtotiff  does output very differently in releases before 10.67.  The following
       describes the old function, which is unusual both for Netpbm and for Unix programs in general.

       •      The output file must be seekable.  pamtotiff does not write it sequentially.  Therefore, you can't
              use  a  pipe;  you can't pipe the output of pamtotiff to some other program.  But any regular file
              should work.

       •      If the output file descriptor is readable, you must either specify -append so as  to  add  to  the
              existing  file,  or make sure the file is empty.  Otherwise, pamtotiff will fail with an unhelpful
              message telling you that a TIFF library function failed to open the TIFF output stream.

       •      If you are converting multiple images (your input stream contains  multiple  images),  the  output
              file must be both readable and writable.

       If  you're  using  a  Unix  command  shell  to  run pamtotiff, 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:

           $ pamtotiff myimage.pnm >/tmp/myimage.tiff

       In Bash, you would set up a read/write Standard Output to the file /tmp/myimage.tiff like this:

           $ pamtotiff myimage.pnm 1<>/tmp/myimage.tiff

   TIFF Capability
       pamtotiff  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.

OPTIONS

       In addition to the options common to all programs based on libnetpbm (most notably -quiet, see
        Common Options ⟨index.html#commonoptions⟩ ), pamtotiff recognizes the following command line options:

   Compression
       By default, pamtotiff 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 to play.

       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 because of 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  pamtotiff  behavior  remains the same for compatibility with older TIFF libraries and
       applications of pamtotiff.

       The -none, -packbits, -lzw, -g3, -g4, -flate, and -adobeflate options are used to  override  the  default
       and set the compression scheme used in creating the output file.

       The  -predictor  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, pamtotiff creates a TIFF file with msb-to-
       lsb fill order.  The -msb2lsb and -lsb2msb options are used to override the  default  and  set  the  fill
       order used in creating the file.

       With  some  older  TIFF libraries, -lzw 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,  -lzw  works  because no distributors of the TIFF library were sensitive yet to the
       patent issue.

       -flate 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.

       Fax Compression

       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 Fax Format(1) page for more information on these  compression
       schemes.

       These formats all relate to ITU Group 3 and Group 4 fax machine standards.

       The  -g3  option  chooses  MH  or  MR compression: MR with the additional option -2d; MH without it.  -g4
       selects MMR.  The option names are a little unfortunate and historical, but are consistent with the  TIFF
       specification.

       MMR has a better compression ratio than the other two.

       -fill  specifies  that  for  MH  or  MR compression, each encoded scanline shall be zero-filled to a byte
       boundary.

       -2d and -fill are meaningful only with -g3.

   Fill Order
       The -msb2lsb and lsb2msb options control the fill order.

       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.

       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).

   Color Space
       -color tells pamtotiff 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, pamtotiff 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, pamtotiff always produces grayscale TIFF output and this
       option has no effect.

       The -color option can prevent pamtotiff from making two passes through the  input  file,  thus  improving
       speed and memory usage.  See Multiple Passes ⟨#multipass⟩ .

       -truecolor  tells pamtotiff to produce the 24-bit RGB form of TIFF output if it is producing a color TIFF
       image.  Without this option, pamtotiff produces a colormapped (paletted) TIFF image unless there are more
       than 256 colors (and in the latter case, issues a warning).

       The -truecolor option can prevent pamtotiff from making two passes through the input file, thus improving
       speed and memory usage.  See Multiple Passes ⟨#multipass⟩ .

       The -color and -truecolor options did not exist before Netpbm 9.21 (December 2001).

       If pamtotiff produces a grayscale TIFF image, this option has no effect.

       The -minisblack and -miniswhite options force the output image to have a "minimum is black"  or  "minimum
       is white" photometric, respectively.  If you don't specify either, pamtotiff uses minimum is black except
       when using Group 3 or Group 4 compression, in which case pamtotiff follows CCITT fax standards  and  uses
       "minimum  is  white."  This  usually results in better compression and is generally preferred for bilevel
       coding.  These photometrics are for grayscale images, so these options are invalid if the image is  color
       (but  only  if it is truly color; they are valid with, for example, a PPM image that contains only shades
       of gray).

       Before Netpbm 9.11 (February 200)1, pamtotiff always produced "minimum is black," because of a  bug.   In
       either  case,  pamtotiff  sets  the  photometric interpretation tag in the TIFF output according to which
       photometric is actually used.

       Before Netpbm 10.78 (March 2017), pamtotiff respected -miniswhite and -minisblack even with color images,
       producing invalid TIFF images that have the indicated photometric but red, green, and blue raster planes.

       The  -indexbits 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.  pamtotiff 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.

       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 -indexbits option.  The value is a comma-separated list of the bit
       widths you allow.  pamtotiff chooses the smallest width you allow that allows  it  to  index  the  entire
       color  table.   If  you don't allow any such width, pamtotiff fails.  Normally, the only useful value for
       this option is 1,2,4,8, because a program either understands the 8 bit  width  (default)  or  understands
       them all.

       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.

       This option was added in June 2002.  Before that, only 8 bit indices were possible.

   Extra Tags
       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.

       You can tell pamtotiff explicitly to include tags such as this in its output with the -tag  option.   You
       identify  a list of tag types and values and pamtotiff includes a tag in the output for each item in your
       list.

       The value of -tag is the list of tags, like this example:

           -tag=subfiletype=reducedimage,documentname=Fred,xposition=25

       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  tiff.h  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.

       The format of the value specification for a tag (stuff after the equal sign) depends upon  what  kind  of
       value the tag type has:

       •      Integer: a decimal number

       •      Floating point number: a decimal number

       •      String: a string

       •      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 tiff.h file, 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.

              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
              pamtotiff doesn't know about.

       If  you  specify a tag type with -tag that is not independent of the content of your PNM source image and
       pamtotiff's conversion process (i.e. a tag type in which pamtotiff is interested), pamtotiff fails.   For
       example,  you  cannot  specify an IMAGEWIDTH tag with -tag, because pamtotiff generates an IMAGEWIDTH tag
       that gives the actual width of the image.

       -tag was new in Netpbm 10.31 (December 2005).

   Output
       See The Output File ⟨#output⟩ .

       -output names the output file.  Without this option pamtotiff writes to Standard Output.

       The -append option tells pamtotiff only to append to the file named by output; not  create  it.   Without
       this  option,  the  program  creates the file it does not already exist.  But even then, if the file does
       already exist, the program appends the image to what is in the file already.  (A TIFF  file  may  contain
       multiple images).

       -append has no effect if you don't also specify -output.

       Before  Netpbm  10.67 (June 2014), -append means something rather different: it means to append the image
       to the output TIFF file (which is always Standard Output in 10.67) instead of replacing its contents.

       -append was new in Netpbm 10.27 (March 2005).

   Other
       You can use the -rowsperstrip 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.

NOTES

       There are myriad variations of the TIFF format, and this program generates only a few of them.  pamtotiff
       creates  a  grayscale  TIFF  file if its input is a PBM (monochrome) or PGM (grayscale) or equivalent PAM
       file.  pamtotiff also creates a grayscale file if it input is PPM (color) or equivalent PAM, but there is
       only one color in the image.

       If  the  input  is  a  PPM  (color)  file  and  there are 256 colors or fewer, but more than 1, pamtotiff
       generates a color palette TIFF file.  If there are more colors than that, pamtotiff generates an RGB (not
       RGBA)  single  plane  TIFF  file.   Use pnmtotiffcmyk to generate the cyan-magenta-yellow-black ink color
       separation TIFF format.

       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.

   Extra Channels
       Like most Netpbm programs, pamtotiff'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.

       pamtotiff assumes any 1 plane PAM image is BLACKANDWHITE or GRAYSCALE (and  doesn't  distinguish  between
       those two).

       pamtotiff  assumes  a  PAM  with more than 1 plane is of tuple type RGB except with that number of planes
       instead of 3.  pamtotiff 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 components,
       so pamtotiff 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.

       Note  that  pamtotiff  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.

       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.

       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 -color option.

   Multiple Passes
       pamtotiff 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 -truecolor and -color options.

        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.

       When the input is from a file that cannot be rewound and reread, pamtotiff reads the entire  input  image
       into a temporary file which can, and works from that.  Even if it needs only one pass.

       Before  Netpbm  9.21 (December 2001), pamtotiff always read the entire image into virtual memory and then
       did one, two, or three passes through the memory copy.  The -truecolor and -color 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.

   Resolution
       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, pamtotiff does not include any tags of these types,
       but you can specify them with the -tags option.

       There are also options -xresolution, -yresolution, and -resolutionunit, but those are  obsolete.   Before
       -tags existed (before Netpbm 10.31 (December 2005), they were the only way.

       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.

       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.  -yresolution is analogous for the vertical direction.

       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).

       If  you  don't use a -tag option to specify the resolution tag and use the obsolete options instead, note
       the following:

       •      If you don't include  an  specify  -xresolution,  the  Tiff  image  does  not  contain  horizontal
              resolution  information.   Likewise  for  -yresolution.  If you don't specify -resolutionunit, the
              default is inches.

       •      Before Netpbm 10.16 (June 2003), -resolutionunit did not exist and the resolution unit was  always
              inches.

HISTORY

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

SEE ALSO

       tifftopnm(1), pnmtotiffcmyk(1), pamdepth(1), pamtopnm(1), pam(1)

AUTHOR

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

DOCUMENT SOURCE

       This  manual  page was generated by the Netpbm tool 'makeman' from HTML source.  The master documentation
       is at

              http://netpbm.sourceforge.net/doc/pamtotiff.html