pamtotiff
pamtotiff
Updated: 27 March 2005
Table Of Contents
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}]
[-indexbits=[1[2[4[8]]]]] [-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.
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
The output goes to Standard Output. pamtotiff approaches this
output file
differently from Unix and Netpbm convention. This is entire-
ly due to
pamtotiff’s use of the TIFF library to do all TIFF output.
* 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
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 compres-
sion scheme or
tweak some of the other even more obscure output options,
there are a number
of options which 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 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 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 CCITT Group 3 and Group 4 compression al-
gorithms can be
used only with bilevel data. The -2d and -fill options are
meaningful only
with Group 3 compression: -2d requests 2-dimensional encoding,
while -fill
requests that each encoded scanline be zero-filled to a byte
boundary. 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 li-
brary 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.
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 confu-
sion 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 total-
ly 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. Oth-
erwise, it
produces a color TIFF output. For PBM and PGM input, pamto-
tiff 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 Multi-
ple Passes.
-truecolor tells pamtotiff to produce the 24-bit RGB form of
TIFF output if
it is producing a color TIFF image. Without this option, pam-
totiff 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.
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, respec-
tively. If you
don’t specify either, pamtotiff uses minimum is black except
when using
Group 3 or Group 4 compression, in which case pamtotiff fol-
lows CCITT fax
standards and uses "minimum is white." This usually results
in better
compression and is generally preferred for bilevel coding.
Before February 2001, pamtotiff always produced "minimum is
black," due to a
bug. In either case, pamtotiff sets the photometric interpre-
tation tag in
the TIFF output according to which photometric is actually
used.
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 al-
lows 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 under-
stands them
all.
In a Baseline TIFF image, according to the 1992 TIFF 6.0 spec-
ification, 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 cor-
respond 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_SUBFILE-
TYPE.
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 enu-
merated 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
foile, 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 exam-
ple, you cannot
specify an IMAGEWIDTH tag with -tag, because pamtotiff gen-
erates an
IMAGEWIDTH tag that gives the actual width of the image.
-tag was new in Netpbm 10.31 (December 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 out-
put file has
the number of rows per strip set to a value that will ensure
each strip is
no more than 8 kilobytes long.
The -append option tells pamtotiff to add images to the exist-
ing output file
(a TIFF file may contain multiple images) instead of the de-
fault, which is
to replace the output file.
-append was new in Netpbm 10.27 (March 2005).
NOTES
There are myriad variations of the TIFF format, and this pro-
gram 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 equiva-
lent 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-yel-
low-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 un-
defined 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 re-
ally 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
compoonents, 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 col-
ormapped 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 hap-
pens 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, YRESO-
LUTION, 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 -reso-
lutionunit, 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 in-
formation 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 direc-
tion.
The unit of distance is given by the value of the RESOLUTIO-
NUNIT 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 can-
not 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 im-
age 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 in-
put. It was
extended and renamed in Netpbm 10.30 (October 2005).
SEE ALSO
tifftopnm, pnmtotiffcmyk, pnmdepth, pamtopnm, pam
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).
_________________________________________________________________
Table Of Contents
* NAME
* SYNOPSIS
* DESCRIPTION
* OPTIONS
* NOTES
+ Multiple Passes
+ Extra Channels
* HISTORY
* SEE ALSO
* AUTHOR
Man(1) output converted with
man2html