.TL
Pnmtotiff User Manual
.SH 1
pnmtotiff
.LP
Updated: 27 March 2005
.br
Table Of Contents
.SH 2
NAME
.LP
pnmtotiff - convert a PNM image to a TIFF file
.SH 2
SYNOPSIS
.LP
\fBpnmtotiff\fR
[\fB-none\fR | \fB-packbits\fR | \fB-lzw\fR | \fB-g3\fR | \fB-g4\fR
| \fB-flate\fR | \fB-adobeflate\fR]
[\fB-2d\fR]
[\fB-fill\fR]
[\fB-predictor=\fR\fIn\fR]
[\fB-msb2lsb\fR|\fB-lsb2msb\fR]
[\fB-rowsperstrip=\fR\fIn\fR]
[\fB-minisblack\fR|\fB-miniswhite\fR|\fBmb\fR|\fBmw\fR]
[\fB-truecolor\fR]
[\fB-color\fR]
[\fB-indexbits=\fR\fIbitwidthlist\fR]
[\fB-xresolution=\fR\fIxres\fR]
[\fB-yresolution=\fR\fIyres\fR]
[\fB-resolutionunit=\fR{\fBinch\fR | \fBcentimeter\fR | \fBnone\fR |
\fBin\fR | \fBcm\fR | \fBno\fR}]
[\fB-indexbits=\fR[\fB1\fR[\fB2\fR[\fB4\fR[\fB8\fR]]]]]
[\fB-append\fR]
[\fIpnmfile\fR]
.LP
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.
.SH 2
DESCRIPTION
.LP
.LP
This program is part of Netpbm.
.LP
\fBpnmtotiff\fR reads a PNM image as input and produces a TIFF file
as output.
.LP
Actually, it handles multi-image PNM 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 PNM image in the input stream.
.SH 3
The Output File
.LP
.LP
The output goes to Standard Output.  \fBpnmtotiff\fR approaches
this output file differently from Unix and Netpbm convention.  This is
entirely due to \fBpnmtotiff\fR's use of the TIFF library to do all
TIFF output.
.IP \(bu
The output file must be seekable.  \fBpnmtotiff\fR does not
write it sequentially.  Therefore, you can't use a pipe; you can't
pipe the output of \fBpnmtotiff\fR to some other program.  But any
regular file should work.
.IP \(bu
If the output file descriptor is readable, you must either specify
\fB-append\fR so as to add to the existing file, or make sure the
file is empty.  Otherwise, \fBpnmtotiff\fR will fail with an
unhelpful message telling you that a TIFF library function failed to
open the TIFF output stream.
.IP \(bu
If you are converting multiple images (your input stream contains
multiple images), the output file must be both readable and writable.
.LP
.LP
If you're using a Unix command shell to run \fBpnmtotiff\fR, 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:
.DS L
\f(CW    $ pnmtotiff myimage.pnm >/tmp/myimage.tiff
\fR.DE
In Bash, you would set up a read/write Standard Output to the file
/tmp/myimage.tiff like this:
.DS L
\f(CW    $ pnmtotiff myimage.pnm 1<>/tmp/myimage.tiff
\fR.DE
.SH 2
OPTIONS
.LP
.SH 3
Compression
.LP
.LP
By default, \fBpnmtotiff\fR 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.
.LP
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 \fBpnmtotiff\fR
behavior remains the same for compatibility with older TIFF libraries
and applications of \fBpnmtotiff\fR.
.LP
The \fB-none\fR, \fB-packbits\fR, \fB-lzw\fR, \fB-g3\fR,
\fB-g4\fR, \fB-flate\fR, and \fB-adobeflate\fR options are used to
override the default and set the compression scheme used in creating
the output file.  The CCITT Group 3 and Group 4 compression algorithms
can be used only with bilevel data.  The \fB-2d\fR and \fB-fill\fR
options are meaningful only with Group 3 compression: \fB-2d\fR
requests 2-dimensional encoding, while \fB-fill\fR requests that each
encoded scanline be zero-filled to a byte boundary.  The
\fB-predictor\fR 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,
\fBpnmtotiff\fR creates a TIFF file with msb-to-lsb fill order.  The
\fB-msb2lsb\fR and \fB-lsb2msb\fR options are used to override the
default and set the fill order used in creating the file.
.LP
With some older TIFF libraries, \fB-lzw\fR 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, \fB-lzw\fR works because no
distributors of the TIFF library were sensitive yet to the patent
issue.
.LP
\fB-flate\fR 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.
.SH 3
Fill Order
.LP
.LP
The \fB-msb2lsb\fR and \fBlsb2msb\fR options controll the fill order.
.LP
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.
.LP
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).
.SH 3
Color Space
.LP
.LP
\fB-color\fR tells \fBpnmtotiff\fR 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, \fBpnmtotiff\fR
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, \fBpnmtotiff\fR always
produces grayscale TIFF output and this option has no effect.
.LP
The \fB-color\fR option can prevent \fBpnmtotiff\fR from making
two passes through the input file, thus improving speed and memory
usage.  See Multiple Passes.
.LP
\fB-truecolor\fR tells \fBpnmtotiff\fR to produce the 24-bit RGB
form of TIFF output if it is producing a color TIFF image.  Without
this option, \fBpnmtotiff\fR produces a colormapped (paletted) TIFF
image unless there are more than 256 colors (and in the latter case,
issues a warning).
.LP
The \fB-truecolor\fR option can prevent \fBpnmtotiff\fR from
making two passes through the input file, thus improving speed and
memory usage.  See Multiple Passes.
.LP
The \fB-color\fR and \fB-truecolor\fR options did not exist
before Netpbm 9.21 (December 2001).
.LP
If \fBpnmtotiff\fR produces a grayscale TIFF image, this option
has no effect.
.LP
The \fB-minisblack\fR and \fB-miniswhite\fR options force the
output image to have a "minimum is black" or "minimum
is white" photometric, respectively.  If you don't specify
either, \fBpnmtotiff\fR uses minimum is black except when using Group
3 or Group 4 compression, in which case \fBpnmtotiff\fR follows CCITT
fax standards and uses "minimum is white." This usually
results in better compression and is generally preferred for bilevel
coding.
.LP
Before February 2001, \fBpnmtotiff\fR always produced
"minimum is black," due to a bug.  In either case,
\fBpnmtotiff\fR sets the photometric interpretation tag in the TIFF
output according to which photometric is actually used.
.LP
The \fB-indexbits\fR 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.
\fBpnmtotiff\fR 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.
.LP
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
\fB-indexbits\fR option.  The value is a comma-separated list of the
bit widths you allow.  \fBpnmtotiff\fR chooses the smallest width you allow
that allows it to index the entire color table.  If you don't allow any
such width, \fBpnmtotiff\fR fails.  Normally, the only useful value for
this option is \fB1,2,4,8\fR, because a program either understands the 8
bit width (default) or understands them all.
.LP
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.
.LP
This option was added in June 2002.  Before that, only 8 bit indices were
possible.
.SH 3
Resolution
.LP
.LP
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.  You control that with the \fB-xresolution\fR, \fB-yresolution\fR,
and \fB-resolutionunit\fR options.
.LP
These options do not control how many pixels \fBpnmtotiff\fR generates or
how much information is in the pixels.  They control only the value of tags
that may or may not be used by whatever reads the image.
.LP
The value of the \fB-xresolution\fR option is a floating point
decimal number that tells how many pixels there are per unit of
distance in the horizontal direction.  \fB-yresolution\fR is
analogous for the vertical direction.
.LP
The unit of distance is given by the value of the
\fB-resolutionunit\fR option.  That value is either \fBinch\fR,
\fBcentimeter\fR or \fBnone\fR (or abbreviations \fBin\fR,
\fBcm\fR, or \fBno\fR).  \fBnone\fR 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).
.LP
If you don't specify \fB-xresolution\fR, the Tiff image does not contain
horizontal resolution information.  Likewise for \fB-yresolution\fR.  If
you don't specify \fB-resolutionunit\fR, the default is inches.
.LP
Before Netpbm 10.16 (June 2003), \fB-resolutionunit\fR did not exist and
the resolution unit was always inches.
.SH 3
Other
.LP
.LP
You can use the \fB-rowsperstrip\fR 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.
.LP
The \fB-append\fR option tells \fBpnmtotiff\fR 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.
.LP
\fB-append\fR was new in Netpbm 10.27 (March 2005).
.SH 2
NOTES
.LP
.LP
There are myriad variations of the TIFF format, and this program
generates only a few of them.  \fBpnmtotiff\fR creates a grayscale
TIFF file if its input is a PBM (monochrome) or PGM (grayscale) file.
\fBpnmtotiff\fR also creates a grayscale file if it input is PPM
(color), 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,
\fBpnmtotiff\fR generates a color palette TIFF file.  If there are
more colors than that, \fBpnmtotiff\fR generates an RGB (not RGBA)
single plane TIFF file.  Use \fBpnmtotiffcmyk\fR to generate the
cyan-magenta-yellow-black ink color separation TIFF format.
.LP
The number of bits per sample in the TIFF output is determined by
the maxval of the PNM 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.
.SH 3
Multiple Passes
.LP
.LP
\fBpnmtotiff\fR 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 \fB-truecolor\fR and \fB-color\fR
options.
.LP
 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.
.LP
When the input is from a file that cannot be rewound and reread,
\fBpnmtotiff\fR reads the entire input image into a temporary file
which can, and works from that.  Even if it needs only one pass.
.LP
Before Netpbm 9.21 (December 2001), \fBpnmtotiff\fR always read
the entire image into virtual memory and then did one, two, or three
passes through the memory copy.  The \fB-truecolor\fR and
\fB-color\fR 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.
.SH 2
SEE ALSO
.LP
\fBtifftopnm\fR,
\fBpnmtotiffcmyk\fR,
\fBpnmdepth\fR,
\fBpnm\fR
.SH 2
AUTHOR
.LP
Derived by Jef Poskanzer from ras2tiff.c, which is
Copyright (c) 1990 by Sun Microsystems, Inc.
Author: Patrick J. Naughton (naughton@wind.sun.com).
.br
\l'5i'
.SH 2
Table Of Contents
.LP
.IP \(bu
NAME
.IP \(bu
SYNOPSIS
.IP \(bu
DESCRIPTION
.IP \(bu
OPTIONS
.IP \(bu
NOTES
.IP \(bu
Multiple Passes
.LP
.IP \(bu
SEE ALSO
.IP \(bu
AUTHOR
.LP