Provided by: netpbm_10.97.00-2_amd64 bug

NAME

       tifftopnm - convert a TIFF file into a PNM image

SYNOPSIS

       tifftopnm

       [-alphaout={alpha-filename,-}]   [-headerdump]   [-verbose]  [-respectfillorder]  [-byrow]
       [-orientraw] [tiff-filename]

DESCRIPTION

       This program is part of Netpbm(1).

       tifftopnm reads a TIFF file as input and produces a PNM image as output.  The type of  the
       output file depends on the input file - if it's black and white, tifftopnm generates a PBM
       image; if it's grayscale, it generates a PGM image; otherwise, the  output  is  PPM.   The
       program tells you which type it is writing.

       If  the TIFF file contains multiple images (multiple "directories"), tifftopnm generates a
       multi-image PNM output stream.  Before Netpbm 10.27 (March 2005), however, it  would  just
       ignore all but the first input image.

       The  tiff-filename  argument  names the file that contains the Tiff image.  If you specify
       "-" or don't specify this argument, tifftopnm uses Standard Input.

       In either case, before Netpbm 10.70 (March 2015), the file must be seekable.   That  means
       no  pipe, but any regular file is fine.  In current Netpbm, the file need not be seekable,
       but if it isn't, tifftopnm creates a temporary regular file containing the  entire  image,
       so you must have resources for that (and it may defeat your reason for using a pipe).

   TIFF Capability
       pamtotiff  uses  the  Libtiff.org  TIFF  library  (or  whatever equivalent you provide) to
       interpret the TIFF input.  So the set of files it  is  able  to  interpret  is  determined
       mostly by that library.

       This  program  cannot  read every possible TIFF file -- there are myriad variations of the
       TIFF  format.   However,  it  does  understand  monochrome  and  gray  scale,  RGB,   RGBA
       (red/green/blue  with  transparency  channel),  CMYK  (Cyan-Magenta-Yellow-Black ink color
       separation), and color palette TIFF files.  An RGB  file  can  have  either  single  plane
       (interleaved) color or multiple plane format.  The program reads 1-8 and 16 bit-per-sample
       input, the latter in either bigendian or littlendian encoding.  Tiff directory information
       may also be either bigendian or littlendian.

       There  are  many TIFF formats that tifftopnm can read only if the image is small enough to
       fit in memory.  tifftopnm uses the TIFF library's TIFFRGBAImageGet() function  to  process
       the TIFF image if it can get enough memory for TIFFRGBAImageGet() to store the whole image
       in memory at once (that's what TIFFRGBAImageGet() does).  If not, tifftopnm  uses  a  more
       primitive row-by-row conversion strategy using the raw data returned by TIFFReadScanLine()
       and native intelligence.  That native intelligence  does  not  know  as  many  formats  as
       TIFFRGBAImageGet()  does.   And  certain  compressed  formats  simply  cannot be read with
       TIFFReadScanLine().

       Before Netpbm 10.11 (October 2002), tifftopnm never used TIFFRGBAImageGet(), so  it  could
       not interpret many of the formats it can interpret today.

       There  is no fundamental reason that this program could not read other kinds of TIFF files
       even when they don't fit in memory all at  once.   The  existing  limitations  are  mainly
       because no one has asked for more.

   Output Image
       The  PNM  output  has  the same maxval as the Tiff input, except that if the Tiff input is
       colormapped (which implies a maxval of 65535) the PNM output has a maxval of 255.   Though
       this  may  result  in  lost  information, such input images hardly ever actually have more
       color resolution than a maxval of 255 provides and people often cannot deal with PNM files
       that  have  maxval  >  255.  By contrast, a non-colormapped Tiff image that doesn't need a
       maxval > 255 doesn't have a maxval > 255, so when tifftopnm sees a non-colormapped  maxval
       > 255, it takes it seriously and produces a matching output maxval.

       Another  exception  is  where  the TIFF maxval is greater than 65535, which is the maximum
       allowed by the Netpbm formats.  In that case, tifftopnm uses a maxval of  65535,  and  you
       lose some information in the conversion.

OPTIONS

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

       You  may  abbreviate  any  option  to its shortest unique prefix.  You may use two hyphens
       instead of one in options.  You may separate an option and its value either by  an  equals
       sign or white space.

       -alphaout=alpha-filename
              tifftopnm  creates  a  PGM  file  containing  the alpha channel values in the input
              image.  If the input image doesn't  contain  a  transparency  channel,  the  alpha-
              filename  file  contains  all zero (transparent) transparency values.  If you don't
              specify -alphaout,

              tifftopnm does not generate a transparency file, and if  the  input  image  has  an
              transparency channel, tifftopnm simply discards it.

              If  you  specify  -  as  the  filename, tifftopnm writes the transparency output to
              Standard Output and discards the image.

              See pamcomp(1) for one way to use the transparency output file.

       -respectfillorder
              By default, tifftopnm  ignores the "fillorder" tag in the TIFF input,  which  means
              it  may  incorrectly  interpret  the  image.   To make it follow the spec, use this
              option.  For a lengthy but engaging discussion of why tifftopnm works this way  and
              how to use the -respectfillorder option, see the note on fillorder below.

       -byrow This option can make tifftopnm run faster.

              tifftopnm  has  two  ways to do the conversion from Tiff to PNM, using respectively
              two facilities of the TIFF library:

       Whole Image
              Decode the entire image into memory at once, using TIFFRGBAImageGet(), then convert
              to PNM and output row by row.

       Row By Row
              Read, convert, and output one row at a time using TIFFReadScanline()

              Whole  Image  is  preferable  because the Tiff library does more of the work, which
              means it understands more of the Tiff format possibilities now and in  the  future.
              Also, some compressed TIFF formats don't allow you to extract an individual row.

              Row  By  Row  uses  far  less  memory, which means with large images, it can run in
              environments where Whole Image cannot and may also run faster.  And because  Netpbm
              code  does more of the work, it's possible that it can be more flexible or at least
              give better diagnostic information if there's something wrong with the TIFF.

              The Netpbm native code may do  something  correctly  that  the  TIFF  library  does
              incorrectly, or vice versa.

              In  Netpbm,  we  stress function over performance, so by default we try Whole Image
              first,  and  if  we  can't  get  enough   memory   for   the   decoded   image   or
              TIFFRGBAImageGet()  fails,  we  fall  back  to  Row By Row.  But if you specify the
              -byrow option, tifftopnm will not attempt Whole Image.  If  Row  By  Row  does  not
              work, it simply fails.

              See  Color Separation (CMYK) TIFFs ⟨#cmyk⟩  for a description of one way Row By Row
              makes a significant difference in your results.

              Whole Image costs you precision when your TIFF image uses  more  than  8  bits  per
              sample.   TIFFRGBAImageGet() converts the samples to 8 bits.  tifftopnm then scales
              them back to maxval 65535, but the lower 8 bits of information is gone.

              In many versions  of  the  TIFF  library,  TIFFRGBAImageGet()  does  not  correctly
              interpret TIFF files in which the raster orientation is column-major (i.e. a row of
              the raster is a column of the image).  With such a TIFF library and file, you  must
              use -byrow to get correct output.

              Before  Netpbm 10.11 (October 2002), tifftopnm always did Row By Row.  Netpbm 10.12
              always tried Whole Image first.  -byrow came in with Netpbm 10.13 (January 2003).

       -orientraw
              A TIFF stream contains raster data which can be  arranged  in  the  stream  various
              ways.   Most  commonly,  it  is  arranged  by rows, with the top row first, and the
              pixels left to right within each row, but many other orientations are possible.

              The common orientation is the same one the Netpbm formats use, so tifftopnm can  do
              its jobs quite efficiently when the TIFF raster is oriented that way.

              But if the TIFF raster is oriented any other way, it can take a considerable amount
              of processing for tifftopnm to convert it to Netpbm format.

              -orientraw says to produce an output image that represents the raw  raster  in  the
              TIFF stream rather than the image the TIFF stream is supposed to represent.  In the
              output, the top left corner corresponds to the start of the TIFF raster,  the  next
              pixel  to  the  right  is the next pixel in the TIFF raster, etc.  tifftopnm can do
              this easily, but you don't get the right image out.  You can use  pamflip  to  turn
              the  output  into  the  image  the  TIFF stream represents (but if you do that, you
              pretty much lose the benefit of -orientraw).

              With this option, tifftopnm always uses the Row By Row method (see -byrow).

              This option was new in Netpbm 10.42 (March 2008).  Before that, tifftopnm generally
              produces arbitrary results with TIFF images that have an orientation other than the
              common one.

       -verbose
              Print extra messages to Standard Error about the conversion.

       -headerdump
              Dump TIFF file information to stderr.  This information may be useful in  debugging
              TIFF file conversion problems.

NOTES

   Fillorder
       There is a piece of information in the header of a TIFF image called "fillorder." The TIFF
       specification quite clearly states that this value tells  the  order  in  which  bits  are
       arranged  in  a  byte  in  the  description of the image's pixels.  There are two options,
       assuming that the image has a format where more than one pixel can  be  represented  by  a
       single  byte:  1)  the  byte  is filled from most significant bit to least significant bit
       going left to right in the image; and 2) the opposite.

       However, there is confusion in the world as to the meaning of fillorder.   Evidence  shows
       that  some  people believe it has to do with byte order when a single value is represented
       by two bytes.

       These people cause TIFF images to be created that, while they use a MSB-to-LSB  fillorder,
       have a fillorder tag that says they used LSB-to-MSB.  A program that properly interprets a
       TIFF image will not end up with the image that the author intended in this case.

       For a long time, tifftopnm did not understand fillorder itself and assumed  the  fillorder
       was  MSB-to-LSB regardless of the fillorder tag in the TIFF header.  And as far as I know,
       there is no legitimate reason to use a fillorder  other  than  MSB-to-LSB.   So  users  of
       tifftopnm were happily using those TIFF images that had incorrect fillorder tags.

       So  that  those  users  can  continue to be happy, tifftopnm today continues to ignore the
       fillorder tag unless you tell it not to.  (It does, however, warn you when  the  fillorder
       tag does not say MSB-to-LSB that the tag is being ignored).

       If  for  some reason you have a TIFF image that actually has LSB-to-MSB fillorder, and its
       fillorder tag correctly indicates that, you  must  use  the  -respectfillorder  option  on
       tifftopnm to get proper results.

       Examples     of     incorrect     TIFF     images     are    at    ftp://weather.noaa.gov.
       ⟨ftp://weather.noaa.gov.⟩  They are apparently created by a program called faxtotiff.

       This note was written on January 1, 2002.

   Color Separation (CMYK) TIFFs
       Some TIFF images contain color information in CMYK  form,  whereas  PNM  images  use  RGB.
       There  are  various formulas for converting between these two forms, and tifftopnm can use
       either of two.

       The TIFF library (Version 3.5.4 from libtiff.org) uses Y=(1-K)*(1-B) (similar for R and G)
       in its TIFFRGBAImageGet() service.  When tifftopnm works in Whole Image mode, it uses that
       service, so that's the conversion you get.

       But when tifftopnm runs in Row By Row mode, it does not use  TIFFRGBAImageGet(),  and  you
       get  what appears to be more useful: Y=1-(B+K).  This is the inverse of what pnmtotiffcmyk
       does.

       See the -byrow option for more information on Whole Image versus Row By Row mode.

       Before Netpbm 10.21 (March 2004), tifftopnm used the Y=(1-K)*(1-B) formula always.

SEE ALSO

       pnmtotiff(1), pnmtotiffcmyk(1), pamcomp(1), pnm(1)

AUTHOR

       Derived by Jef Poskanzer from tif2ras.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/tifftopnm.html