Pamtotiff User Manual(1) General Commands Manual Pamtotiff User Manual(1)
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 be-
fore Netpbm 10.27 (March 2005), it ignored all but the first Netpbm im-
age 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 im-
age 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 Stan-
dard 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 un-
usual 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 spec-
ify -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 con-
tains multiple images), the output file must be both readable
and writable.
If you're using a Unix command shell to run pamtotiff, you use facili-
ties 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/myim-
age.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 pro-
duces 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 com-
pression 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 re-
mains the same for compatibility with older TIFF libraries and applica-
tions 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 pre-
dictor 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 or-
der used in creating the file.
With some older TIFF libraries, -lzw doesn't work because the TIFF li-
brary 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 compres-
sion 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 stan-
dards.
The -g3 option chooses MH or MR compression: MR with the additional op-
tion -2d; MH without it. -g4 selects MMR. The option names are a lit-
tle unfortunate and historical, but are consistent with the TIFF speci-
fication.
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, Image-
Magick and older Netpbm both have been known to implement that inter-
pretation. 2001.09.06.
If the image does not have sub-byte pixels, these options have no ef-
fect 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 out-
put if it is producing a color TIFF image. Without this option, pamto-
tiff 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 (De-
cember 2001).
If pamtotiff produces a grayscale TIFF image, this option has no ef-
fect.
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 fol-
lows CCITT fax standards and uses "minimum is white." This usually re-
sults in better compression and is generally preferred for bilevel cod-
ing. 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 photo-
metric interpretation tag in the TIFF output according to which photo-
metric 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 in-
dexes 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 con-
siderably 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 op-
tion 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 val-
ues 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 up-
per/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 pamto-
tiff doesn't know about.
If you specify a tag type with -tag that is not independent of the con-
tent of your PNM source image and pamtotiff's conversion process (i.e.
a tag type in which pamtotiff is interested), pamtotiff fails. For ex-
ample, you cannot specify an IMAGEWIDTH tag with -tag, because pamto-
tiff generates an IMAGEWIDTH tag that gives the actual width of the im-
age.
-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 al-
ready exist, the program appends the image to what is in the file al-
ready. (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 differ-
ent: it means to append the image to the output TIFF file (which is al-
ways 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 (scan-
lines) 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 en-
sure each strip is no more than 8 kilobytes long.
NOTES
There are myriad variations of the TIFF format, and this program gener-
ates 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-ma-
genta-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 pro-
cessing 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 ex-
cept 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-compo-
nent or 5-component color space. The TIFF format allows an arbitrary
number of color components, so pamtotiff simply maps the PAM planes di-
rectly 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 im-
age 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 trans-
parency 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 spec-
ifying 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, pamto-
tiff 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 ex-
ist. The passes through memory would involve page faults if the entire
image did not fit into real memory. The image in memory required con-
siderably 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 in-
clude 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 (De-
cember 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 reso-
lution tags. The number of pixels in the output is the same as in the
input, and each pixel contains the same information. For your resolu-
tion tags to be meaningful, they have to consistent with whatever cre-
ated the PNM input. E.g. if a scanner turned a 10 centimeter wide im-
age 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 hori-
zontal direction. -yresolution is analogous for the vertical direc-
tion.
The unit of distance is given by the value of the RESOLUTIONUNIT op-
tion. 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 de-
fault 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
netpbm documentation 05 April 2017 Pamtotiff User Manual(1)
Generated by dwww version 1.15 on Sat Jun 29 02:39:40 CEST 2024.