| 1 |
\ |
| 2 |
.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. |
| 3 |
.\" Do not hand-hack it! If you have bug fixes or improvements, please find |
| 4 |
.\" the corresponding HTML page on the Netpbm website, generate a patch |
| 5 |
.\" against that, and send it to the Netpbm maintainer. |
| 6 |
.TH "Pamtotiff User Manual" 1 "05 April 2017" "netpbm documentation" |
| 7 |
|
| 8 |
.SH NAME |
| 9 |
pamtotiff - convert a Netpbm image to a TIFF file |
| 10 |
|
| 11 |
.UN synopsis |
| 12 |
.SH SYNOPSIS |
| 13 |
|
| 14 |
\fBpamtotiff\fP |
| 15 |
|
| 16 |
[\fB-none\fP | \fB-packbits\fP | \fB-lzw\fP | \fB-g3\fP | \fB-g4\fP |
| 17 |
| \fB-flate\fP | \fB-adobeflate\fP] |
| 18 |
|
| 19 |
[\fB-2d\fP] |
| 20 |
|
| 21 |
[\fB-fill\fP] |
| 22 |
|
| 23 |
[\fB-predictor=\fP\fIn\fP] |
| 24 |
|
| 25 |
[\fB-msb2lsb\fP|\fB-lsb2msb\fP] |
| 26 |
|
| 27 |
[\fB-rowsperstrip=\fP\fIn\fP] |
| 28 |
|
| 29 |
[\fB-minisblack\fP|\fB-miniswhite\fP|\fBmb\fP|\fBmw\fP] |
| 30 |
|
| 31 |
[\fB-truecolor\fP] |
| 32 |
|
| 33 |
[\fB-color\fP] |
| 34 |
|
| 35 |
[\fB-indexbits=\fP\fIbitwidthlist\fP] |
| 36 |
[\fB-xresolution=\fP\fIxres\fP] |
| 37 |
|
| 38 |
[\fB-yresolution=\fP\fIyres\fP] |
| 39 |
[\fB-resolutionunit=\fP{\fBinch\fP | \fBcentimeter\fP | \fBnone\fP | |
| 40 |
\fBin\fP | \fBcm\fP | \fBno\fP}] |
| 41 |
|
| 42 |
[\fB-append\fP] |
| 43 |
|
| 44 |
[\fB-tag=\fP\fItaglist\fP] |
| 45 |
|
| 46 |
[\fIpamfile\fP] |
| 47 |
.PP |
| 48 |
You can use the minimum unique abbreviation of the options. You |
| 49 |
can use two hyphens instead of one. You can separate an option name |
| 50 |
from its value with white space instead of an equals sign. |
| 51 |
|
| 52 |
.UN description |
| 53 |
.SH DESCRIPTION |
| 54 |
.PP |
| 55 |
This program is part of |
| 56 |
.BR "Netpbm" (1)\c |
| 57 |
\&. |
| 58 |
.PP |
| 59 |
\fBpamtotiff\fP reads a PNM or PAM image as input and produces a TIFF file |
| 60 |
as output. |
| 61 |
.PP |
| 62 |
Actually, it handles multi-image Netpbm streams, producing multi-image |
| 63 |
TIFF streams (i.e. a TIFF stream with multiple |
| 64 |
"directories"). But before Netpbm 10.27 (March 2005), it |
| 65 |
ignored all but the first Netpbm image in the input stream. |
| 66 |
|
| 67 |
.UN output |
| 68 |
.SS The Output File |
| 69 |
.PP |
| 70 |
By default, the output goes to Standard Output. Alternatively, you can |
| 71 |
specify an output file with the \fB-output\fP option and \fBpamtotiff\fP |
| 72 |
will write its output directly to that file. |
| 73 |
.PP |
| 74 |
Because of the way the TIFF library (which \fBpamtotiff\fP uses) works, |
| 75 |
when the program writes to Standard Output, it generates the entire TIFF image |
| 76 |
in a temporary file and then copies it to Standard Output; you may see |
| 77 |
negative performance effects of this. |
| 78 |
.PP |
| 79 |
The \fB-output\fP method avoids the performance effects of the copy |
| 80 |
through the temporary file, but there are restrictions on the output file: it |
| 81 |
must be seekable and it must be readable. The program fails if it is not. |
| 82 |
With Standard Output, neither of those restrictions applies. |
| 83 |
.PP |
| 84 |
With \fB-output\fP, if the file already exists and has data in it, |
| 85 |
\fBpamtotiff\fP appends the image to the existing TIFF file. (A TIFF file |
| 86 |
may contain multiple images). |
| 87 |
.PP |
| 88 |
By default, \fBpamtotiff\fP creates the file named by \fB-output\fP if it |
| 89 |
does not already exist. But if you also specify \fB-append\fP, the program |
| 90 |
fails if the file named by \fB-output\fP does not already exist. |
| 91 |
.PP |
| 92 |
Before Netpbm 10.67 (June 2014), there is no \fB-output\fP option and |
| 93 |
Standard Output must be seekable. So pipes are out. |
| 94 |
.PP |
| 95 |
Before Netpbm 10.67 (June 2014), you could append to Standard Output. See |
| 96 |
below. The current program does not have the ability; you must |
| 97 |
use \fB-output\fP to append to an existing TIFF file. |
| 98 |
.PP |
| 99 |
The difference above means current \fBpamtotiff\fP is actually not |
| 100 |
backward compatible, which is a rare thing for Netpbm. But it's a good thing |
| 101 |
because the previous function was very strange and probably hardly ever |
| 102 |
exploited. |
| 103 |
|
| 104 |
|
| 105 |
.UN oldoutput |
| 106 |
.B Old Versions |
| 107 |
.PP |
| 108 |
As alluded to above, \fBpamtotiff\fP does output very differently |
| 109 |
in releases before 10.67. The following describes the old function, |
| 110 |
which is unusual both for Netpbm and for Unix programs in general. |
| 111 |
|
| 112 |
|
| 113 |
.IP \(bu |
| 114 |
The output file must be seekable. \fBpamtotiff\fP does not |
| 115 |
write it sequentially. Therefore, you can't use a pipe; you can't |
| 116 |
pipe the output of \fBpamtotiff\fP to some other program. But any |
| 117 |
regular file should work. |
| 118 |
|
| 119 |
.IP \(bu |
| 120 |
If the output file descriptor is readable, you must either specify |
| 121 |
\fB-append\fP so as to add to the existing file, or make sure the |
| 122 |
file is empty. Otherwise, \fBpamtotiff\fP will fail with an |
| 123 |
unhelpful message telling you that a TIFF library function failed to |
| 124 |
open the TIFF output stream. |
| 125 |
|
| 126 |
.IP \(bu |
| 127 |
If you are converting multiple images (your input stream contains |
| 128 |
multiple images), the output file must be both readable and writable. |
| 129 |
|
| 130 |
|
| 131 |
.PP |
| 132 |
If you're using a Unix command shell to run \fBpamtotiff\fP, you |
| 133 |
use facilities of your shell to set up Standard Output. In Bash, |
| 134 |
for example, you would set up a write-only Standard Output to the |
| 135 |
file /tmp/myimage.tiff like this: |
| 136 |
|
| 137 |
.nf |
| 138 |
\f(CW |
| 139 |
$ pamtotiff myimage.pnm >/tmp/myimage.tiff |
| 140 |
\fP |
| 141 |
|
| 142 |
.fi |
| 143 |
|
| 144 |
In Bash, you would set up a read/write Standard Output to the file |
| 145 |
/tmp/myimage.tiff like this: |
| 146 |
|
| 147 |
.nf |
| 148 |
\f(CW |
| 149 |
$ pamtotiff myimage.pnm 1<>/tmp/myimage.tiff |
| 150 |
\fP |
| 151 |
|
| 152 |
.fi |
| 153 |
|
| 154 |
.UN library |
| 155 |
.SS TIFF Capability |
| 156 |
.PP |
| 157 |
\fBpamtotiff\fP uses the Libtiff.org TIFF library (or whatever |
| 158 |
equivalent you provide) to generate the TIFF output. Details of the |
| 159 |
format it produces are therefore controlled by that library. |
| 160 |
|
| 161 |
.UN options |
| 162 |
.SH OPTIONS |
| 163 |
.PP |
| 164 |
In addition to the options common to all programs based on libnetpbm |
| 165 |
(most notably \fB-quiet\fP, see |
| 166 |
.UR index.html#commonoptions |
| 167 |
Common Options |
| 168 |
.UE |
| 169 |
\&), \fBpamtotiff\fP recognizes the following |
| 170 |
command line options: |
| 171 |
|
| 172 |
.UN compression |
| 173 |
.SS Compression |
| 174 |
.PP |
| 175 |
By default, \fBpamtotiff\fP creates a TIFF file with no |
| 176 |
compression. This is your best bet most of the time. If you want to |
| 177 |
try another compression scheme or tweak some of the other even more |
| 178 |
obscure output options, there are a number of options which to |
| 179 |
play. |
| 180 |
.PP |
| 181 |
Before Netpbm 8.4 (April 2000), the default was to use LZW compression. |
| 182 |
But then new releases of the TIFF library started omitting the LZW |
| 183 |
compression capability because of concern about patents on LZW. So |
| 184 |
since then, the default has been no compression. The LZW patents have |
| 185 |
now expired and new TIFF libraries do LZW, but the \fBpamtotiff\fP |
| 186 |
behavior remains the same for compatibility with older TIFF libraries |
| 187 |
and applications of \fBpamtotiff\fP. |
| 188 |
.PP |
| 189 |
The \fB-none\fP, \fB-packbits\fP, \fB-lzw\fP, \fB-g3\fP, |
| 190 |
\fB-g4\fP, \fB-flate\fP, and \fB-adobeflate\fP options are used to |
| 191 |
override the default and set the compression scheme used in creating |
| 192 |
the output file. |
| 193 |
|
| 194 |
The \fB-predictor\fP option is meaningful only with LZW compression: a |
| 195 |
predictor value of 2 causes each scanline of the output image to undergo |
| 196 |
horizontal differencing before it is encoded; a value of 1 forces each |
| 197 |
scanline to be encoded without differencing. By default, \fBpamtotiff\fP |
| 198 |
creates a TIFF file with msb-to-lsb fill order. The \fB-msb2lsb\fP and |
| 199 |
\fB-lsb2msb\fP options are used to override the default and set the fill |
| 200 |
order used in creating the file. |
| 201 |
.PP |
| 202 |
With some older TIFF libraries, \fB-lzw\fP doesn't work because |
| 203 |
the TIFF library doesn't do LZW compression. This is because of |
| 204 |
concerns about Unisys's patent on LZW which was then in force. |
| 205 |
Actually, with very old TIFF libraries, \fB-lzw\fP works because no |
| 206 |
distributors of the TIFF library were sensitive yet to the patent |
| 207 |
issue. |
| 208 |
.PP |
| 209 |
\fB-flate\fP chooses "flate" compression, which is the |
| 210 |
patent-free compression common in the Unix world implemented by the |
| 211 |
"Z" library. It is what the PNG format uses. |
| 212 |
|
| 213 |
.UN faxcompression |
| 214 |
.B Fax Compression |
| 215 |
.PP |
| 216 |
If you have bilevel data (e.g. PBM), you can generate a TIFF that uses the |
| 217 |
same compression scheme specified for use by fax machines. See the |
| 218 |
.BR "Fax Format" (1)\c |
| 219 |
\& page for more information on these |
| 220 |
compression schemes. |
| 221 |
.PP |
| 222 |
These formats all relate to ITU Group 3 and Group 4 fax machine |
| 223 |
standards. |
| 224 |
.PP |
| 225 |
The \fB-g3\fP option chooses MH or MR compression: MR with the additional |
| 226 |
option \fB-2d\fP; MH without it. \fB-g4\fP selects MMR. The option names |
| 227 |
are a little unfortunate and historical, but are consistent with the TIFF |
| 228 |
specification. |
| 229 |
.PP |
| 230 |
MMR has a better compression ratio than the other two. |
| 231 |
.PP |
| 232 |
\fB-fill\fP specifies that for MH or MR compression, each encoded scanline |
| 233 |
shall be zero-filled to a byte boundary. |
| 234 |
.PP |
| 235 |
\fB-2d\fP and \fB-fill\fP are meaningful only with \fB-g3\fP. |
| 236 |
|
| 237 |
|
| 238 |
.UN fillorder |
| 239 |
.SS Fill Order |
| 240 |
.PP |
| 241 |
The \fB-msb2lsb\fP and \fBlsb2msb\fP options control the fill order. |
| 242 |
.PP |
| 243 |
The fill order is the order in which pixels are packed into a byte in |
| 244 |
the Tiff raster, in the case that there are multiple pixels per byte. |
| 245 |
msb-to-lsb means that the leftmost columns go into the most |
| 246 |
significant bits of the byte in the Tiff image. However, there is |
| 247 |
considerable confusion about the meaning of fill order. Some believe |
| 248 |
it means whether 16 bit sample values in the Tiff image are |
| 249 |
little-endian or big-endian. This is totally erroneous (The |
| 250 |
endianness of integers in a Tiff image is designated by the image's |
| 251 |
magic number). However, ImageMagick and older Netpbm both have been known |
| 252 |
to implement that interpretation. 2001.09.06. |
| 253 |
.PP |
| 254 |
If the image does not have sub-byte pixels, these options have no |
| 255 |
effect other than to set the value of the FILLORDER tag in the Tiff |
| 256 |
image (which may be useful for those programs that misinterpret the |
| 257 |
tag with reference to 16 bit samples). |
| 258 |
|
| 259 |
.UN colorspace |
| 260 |
.SS Color Space |
| 261 |
.PP |
| 262 |
\fB-color\fP tells \fBpamtotiff\fP to produce a color, as |
| 263 |
opposed to grayscale, TIFF image if the input is PPM, even if it |
| 264 |
contains only shades of gray. Without this option, \fBpamtotiff\fP |
| 265 |
produces a grayscale TIFF image if the input is PPM and contains only |
| 266 |
shades of gray, and at most 256 shades. Otherwise, it produces a |
| 267 |
color TIFF output. For PBM and PGM input, \fBpamtotiff\fP always |
| 268 |
produces grayscale TIFF output and this option has no effect. |
| 269 |
.PP |
| 270 |
The \fB-color\fP option can prevent \fBpamtotiff\fP from making |
| 271 |
two passes through the input file, thus improving speed and memory |
| 272 |
usage. See |
| 273 |
.UR #multipass |
| 274 |
Multiple Passes |
| 275 |
.UE |
| 276 |
\&. |
| 277 |
.PP |
| 278 |
\fB-truecolor\fP tells \fBpamtotiff\fP to produce the 24-bit RGB |
| 279 |
form of TIFF output if it is producing a color TIFF image. Without |
| 280 |
this option, \fBpamtotiff\fP produces a colormapped (paletted) TIFF |
| 281 |
image unless there are more than 256 colors (and in the latter case, |
| 282 |
issues a warning). |
| 283 |
.PP |
| 284 |
The \fB-truecolor\fP option can prevent \fBpamtotiff\fP from |
| 285 |
making two passes through the input file, thus improving speed and |
| 286 |
memory usage. See |
| 287 |
.UR #multipass |
| 288 |
Multiple Passes |
| 289 |
.UE |
| 290 |
\&. |
| 291 |
.PP |
| 292 |
The \fB-color\fP and \fB-truecolor\fP options did not exist |
| 293 |
before Netpbm 9.21 (December 2001). |
| 294 |
.PP |
| 295 |
If \fBpamtotiff\fP produces a grayscale TIFF image, this option |
| 296 |
has no effect. |
| 297 |
.PP |
| 298 |
The \fB-minisblack\fP and \fB-miniswhite\fP options force the |
| 299 |
output image to have a "minimum is black" or "minimum |
| 300 |
is white" photometric, respectively. If you don't specify |
| 301 |
either, \fBpamtotiff\fP uses minimum is black except when using Group |
| 302 |
3 or Group 4 compression, in which case \fBpamtotiff\fP follows CCITT |
| 303 |
fax standards and uses "minimum is white." This usually |
| 304 |
results in better compression and is generally preferred for bilevel |
| 305 |
coding. These photometrics are for grayscale images, so these options are |
| 306 |
invalid if the image is color (but only if it is truly color; they are |
| 307 |
valid with, for example, a PPM image that contains only shades of gray). |
| 308 |
.PP |
| 309 |
Before Netpbm 9.11 (February 200)1, \fBpamtotiff\fP always produced |
| 310 |
"minimum is black," because of a bug. In either case, |
| 311 |
\fBpamtotiff\fP sets the photometric interpretation tag in the TIFF |
| 312 |
output according to which photometric is actually used. |
| 313 |
.PP |
| 314 |
Before Netpbm 10.78 (March 2017), \fBpamtotiff\fP respected |
| 315 |
\fB-miniswhite\fP and \fB-minisblack\fP even with color images, producing |
| 316 |
invalid TIFF images that have the indicated photometric but red, green, and |
| 317 |
blue raster planes. |
| 318 |
.PP |
| 319 |
The \fB-indexbits\fP option is meaningful only for a colormapped |
| 320 |
(paletted) image. In this kind of image, the raster contains values |
| 321 |
which are indexes into a table of colors, with the indexes normally |
| 322 |
taking less space that the color description in the table. |
| 323 |
\fBpamtotiff\fP can generate indexes of 1, 2, 4, or 8 bits. By |
| 324 |
default, it will use 8, because many programs that interpret TIFF |
| 325 |
images can't handle any other width. |
| 326 |
.PP |
| 327 |
But if you have a small number of colors, you can make your image |
| 328 |
considerably smaller by allowing fewer than 8 bits per index, using the |
| 329 |
\fB-indexbits\fP option. The value is a comma-separated list of the |
| 330 |
bit widths you allow. \fBpamtotiff\fP chooses the smallest width you allow |
| 331 |
that allows it to index the entire color table. If you don't allow any |
| 332 |
such width, \fBpamtotiff\fP fails. Normally, the only useful value for |
| 333 |
this option is \fB1,2,4,8\fP, because a program either understands the 8 |
| 334 |
bit width (default) or understands them all. |
| 335 |
.PP |
| 336 |
In a Baseline TIFF image, according to the 1992 TIFF 6.0 |
| 337 |
specification, 4 and 8 are the only valid widths. There are no formal |
| 338 |
standards that allow any other values. |
| 339 |
.PP |
| 340 |
This option was added in June 2002. Before that, only 8 bit indices were |
| 341 |
possible. |
| 342 |
|
| 343 |
.UN extratags |
| 344 |
.SS Extra Tags |
| 345 |
.PP |
| 346 |
There are lots of tag types in the TIFF format that don't correspond to |
| 347 |
any information in the PNM format or to anything in the conversion process. |
| 348 |
For example, a TIFF_ARTIST tag names the artist who created the image. |
| 349 |
.PP |
| 350 |
You can tell \fBpamtotiff\fP explicitly to include tags such as this |
| 351 |
in its output with the \fB-tag\fP option. You identify a list of tag |
| 352 |
types and values and \fBpamtotiff\fP includes a tag in the output for |
| 353 |
each item in your list. |
| 354 |
.PP |
| 355 |
The value of \fB-tag\fP is the list of tags, like this example: |
| 356 |
|
| 357 |
.nf |
| 358 |
\f(CW |
| 359 |
-tag=subfiletype=reducedimage,documentname=Fred,xposition=25 |
| 360 |
\fP |
| 361 |
|
| 362 |
.fi |
| 363 |
.PP |
| 364 |
As you see, it is a list of tag specifications separated by commas. |
| 365 |
Each tag specification is a name and a value separated by an equal |
| 366 |
sign. The name is the name of the tag type, except in arbitrary |
| 367 |
upper/lower case. One place to see the names of TIFF tag types is in |
| 368 |
the TIFF library's \fBtiff.h\fP file, where there is a macro defined |
| 369 |
for each consisting of "TIFF_" plus the name. E.g. for |
| 370 |
the SUBFILETYPE tag type, there is a macro TIFF_SUBFILETYPE. |
| 371 |
.PP |
| 372 |
The format of the value specification for a tag (stuff after the |
| 373 |
equal sign) depends upon what kind of value the tag type has: |
| 374 |
|
| 375 |
|
| 376 |
.IP \(bu |
| 377 |
Integer: a decimal number |
| 378 |
|
| 379 |
.IP \(bu |
| 380 |
Floating point number: a decimal number |
| 381 |
|
| 382 |
.IP \(bu |
| 383 |
String: a string |
| 384 |
|
| 385 |
.IP \(bu |
| 386 |
Enumerated (For example, a 'subfiletype' tag takes an enumerated |
| 387 |
value. Its possible values are REDUCEDIMAGE, PAGE, and MASK.): The |
| 388 |
name of the value. You can see the possible value names in the TIFF |
| 389 |
library's \fBtiff.h\fP file, where there is a macro defined for each |
| 390 |
consisting of a qualifier plus the value name. E.g. for the |
| 391 |
REDUCEDIMAGE value of a SUBFILETYPE tag, you see the macro |
| 392 |
FILETYPE_REDUCEDIMAGE. |
| 393 |
.sp |
| 394 |
The TIFF format assigns a unique number to each enumerated value and |
| 395 |
you can specify that number, in decimal, as an alternative. This is useful |
| 396 |
if you are using an extension of TIFF that \fBpamtotiff\fP doesn't |
| 397 |
know about. |
| 398 |
|
| 399 |
|
| 400 |
.PP |
| 401 |
If you specify a tag type with \fB-tag\fP that is not independent |
| 402 |
of the content of your PNM source image and \fBpamtotiff\fP's |
| 403 |
conversion process (i.e. a tag type in which \fBpamtotiff\fP is |
| 404 |
interested), \fBpamtotiff\fP fails. For example, you cannot specify |
| 405 |
an IMAGEWIDTH tag with \fB-tag\fP, because \fBpamtotiff\fP generates |
| 406 |
an IMAGEWIDTH tag that gives the actual width of the image. |
| 407 |
.PP |
| 408 |
\fB-tag\fP was new in Netpbm 10.31 (December 2005). |
| 409 |
|
| 410 |
.UN outputoptions |
| 411 |
.SS Output |
| 412 |
.PP |
| 413 |
See |
| 414 |
.UR #output |
| 415 |
The Output File |
| 416 |
.UE |
| 417 |
\&. |
| 418 |
.PP |
| 419 |
\fB-output\fP names the output file. Without this option |
| 420 |
\fBpamtotiff\fP writes to Standard Output. |
| 421 |
.PP |
| 422 |
The \fB-append\fP option tells \fBpamtotiff\fP only to append to the file |
| 423 |
named by \fBoutput\fP; not create it. Without this option, the program |
| 424 |
creates the file it does not already exist. But even then, if the file does |
| 425 |
already exist, the program appends the image to what is in the file already. |
| 426 |
(A TIFF file may contain multiple images). |
| 427 |
.PP |
| 428 |
\fB-append\fP has no effect if you don't also specify \fB-output\fP. |
| 429 |
.PP |
| 430 |
Before Netpbm 10.67 (June 2014), \fB-append\fP means something rather |
| 431 |
different: it means to append the image to the output TIFF file (which is |
| 432 |
always Standard Output in 10.67) instead of replacing its contents. |
| 433 |
.PP |
| 434 |
\fB-append\fP was new in Netpbm 10.27 (March 2005). |
| 435 |
|
| 436 |
|
| 437 |
|
| 438 |
.UN other |
| 439 |
.SS Other |
| 440 |
.PP |
| 441 |
You can use the \fB-rowsperstrip\fP option to set the number of |
| 442 |
rows (scanlines) in each strip of data in the output file. By |
| 443 |
default, the output file has the number of rows per strip set to a |
| 444 |
value that will ensure each strip is no more than 8 kilobytes long. |
| 445 |
|
| 446 |
|
| 447 |
.UN notes |
| 448 |
.SH NOTES |
| 449 |
.PP |
| 450 |
There are myriad variations of the TIFF format, and this program |
| 451 |
generates only a few of them. \fBpamtotiff\fP creates a grayscale |
| 452 |
TIFF file if its input is a PBM (monochrome) or PGM (grayscale) or |
| 453 |
equivalent PAM file. \fBpamtotiff\fP also creates a grayscale file |
| 454 |
if it input is PPM (color) or equivalent PAM, but there is only one |
| 455 |
color in the image. |
| 456 |
.PP |
| 457 |
If the input is a PPM (color) file and there are 256 colors or |
| 458 |
fewer, but more than 1, \fBpamtotiff\fP generates a color palette |
| 459 |
TIFF file. If there are more colors than that, \fBpamtotiff\fP |
| 460 |
generates an RGB (not RGBA) single plane TIFF file. Use |
| 461 |
\fBpnmtotiffcmyk\fP to generate the cyan-magenta-yellow-black ink |
| 462 |
color separation TIFF format. |
| 463 |
.PP |
| 464 |
The number of bits per sample in the TIFF output is determined by |
| 465 |
the maxval of the Netpbm input. If the maxval is less than 256, the bits |
| 466 |
per sample in the output is the smallest number that can encode the |
| 467 |
maxval. If the maxval is greater than or equal to 256, there are 16 |
| 468 |
bits per sample in the output. |
| 469 |
|
| 470 |
.UN extrachannel |
| 471 |
.SS Extra Channels |
| 472 |
.PP |
| 473 |
Like most Netpbm programs, \fBpamtotiff\fP's function is mostly |
| 474 |
undefined if the input is PAM image with tuple type other than |
| 475 |
BLACKANDWHITE, GRAYSCALE, or RGB. Most of the statements in this manual |
| 476 |
assume the input is not such an exotic PAM. But there is a little |
| 477 |
defined processing of other PAM subformats. |
| 478 |
.PP |
| 479 |
\fBpamtotiff\fP assumes any 1 plane PAM image is BLACKANDWHITE |
| 480 |
or GRAYSCALE (and doesn't distinguish between those two). |
| 481 |
.PP |
| 482 |
\fBpamtotiff\fP assumes a PAM with more than 1 plane is of tuple |
| 483 |
type RGB except with that number of planes instead of 3. |
| 484 |
\fBpamtotiff\fP doesn't really understand red, green, and blue, so it |
| 485 |
has no trouble with a 2-component or 5-component color space. The |
| 486 |
TIFF format allows an arbitrary number of color components, so |
| 487 |
\fBpamtotiff\fP simply maps the PAM planes directly to TIFF color |
| 488 |
components. I don't know if the meanings of 5 components in a TIFF image |
| 489 |
are standard at all, but the function is there if you want to use it. |
| 490 |
.PP |
| 491 |
Note that \fBpamtotiff\fP may generate either a truecolor or |
| 492 |
colormapped image with an arbitrary number of color components. In |
| 493 |
the truecolor case, the raster has that number of planes. In the |
| 494 |
colormapped case, the raster has of course 1 plane, but the color map |
| 495 |
has all the color components in it. |
| 496 |
.PP |
| 497 |
The most common reason for a PAM to have extra planes is when the tuple |
| 498 |
type is xxx_ALPHA, which means the highest numbered plane is a transparency |
| 499 |
plane (alpha channel). At least one user found that a TIFF with an extra |
| 500 |
plane for transparency was useful. |
| 501 |
.PP |
| 502 |
Note that the grayscale detection works on N-component colors, so if |
| 503 |
your planes aren't really color components, you'll want to disable this |
| 504 |
via the \fB-color\fP option. |
| 505 |
|
| 506 |
|
| 507 |
.UN multipass |
| 508 |
.SS Multiple Passes |
| 509 |
.PP |
| 510 |
\fBpamtotiff\fP reads the input image once if it can, and |
| 511 |
otherwise twice. It needs that second pass (which happens before the |
| 512 |
main pass, of course) to analyze the colors in the image and generate |
| 513 |
a color map (palette) and determine if the image is grayscale. So the |
| 514 |
second pass happens only when the input is PPM. And you can avoid it |
| 515 |
then by specifying both the \fB-truecolor\fP and \fB-color\fP |
| 516 |
options. |
| 517 |
.PP |
| 518 |
If the input image is small enough to fit in your system's file |
| 519 |
cache, the second pass is very fast. If not, it requires reading from |
| 520 |
disk twice, which can be slow. |
| 521 |
.PP |
| 522 |
When the input is from a file that cannot be rewound and reread, |
| 523 |
\fBpamtotiff\fP reads the entire input image into a temporary file |
| 524 |
which can, and works from that. Even if it needs only one pass. |
| 525 |
.PP |
| 526 |
Before Netpbm 9.21 (December 2001), \fBpamtotiff\fP always read |
| 527 |
the entire image into virtual memory and then did one, two, or three |
| 528 |
passes through the memory copy. The \fB-truecolor\fP and |
| 529 |
\fB-color\fP options did not exist. The passes through memory would |
| 530 |
involve page faults if the entire image did not fit into real memory. |
| 531 |
The image in memory required considerably more memory (12 bytes per |
| 532 |
pixel) than the cached file version of the image would. |
| 533 |
|
| 534 |
|
| 535 |
.UN resolution |
| 536 |
.SS Resolution |
| 537 |
.PP |
| 538 |
A Tiff image may contain information about the resolution of the image, |
| 539 |
which means how big in real dimensions (centimeters, etc.) each pixel in the |
| 540 |
raster is. That information is in the TIFF XRESOLUTION, YRESOLUTION, |
| 541 |
and RESOLUTIONUNIT tags. By default, \fBpamtotiff\fP does not include |
| 542 |
any tags of these types, but you can specify them with the \fB-tags\fP |
| 543 |
option. |
| 544 |
.PP |
| 545 |
There are also options \fB-xresolution\fP, \fB-yresolution\fP, |
| 546 |
and \fB-resolutionunit\fP, but those are obsolete. Before \fB-tags\fP |
| 547 |
existed (before Netpbm 10.31 (December 2005), they were the only way. |
| 548 |
.PP |
| 549 |
Note that the number of pixels in the image and how much information |
| 550 |
each contains is determined independently from the setting of the |
| 551 |
resolution tags. The number of pixels in the output is the same as in |
| 552 |
the input, and each pixel contains the same information. For your |
| 553 |
resolution tags to be meaningful, they have to consistent with |
| 554 |
whatever created the PNM input. E.g. if a scanner turned a 10 centimeter |
| 555 |
wide image into a 1000 pixel wide PNM image, then your horizontal |
| 556 |
resolution is 100 pixels per centimeter, and if your XRESOLUTION |
| 557 |
tag says anything else, something that prints your TIFF image won't |
| 558 |
print the proper 10 centimeter image. |
| 559 |
.PP |
| 560 |
The value of the XRESOLUTION tag is a floating point decimal number |
| 561 |
that tells how many pixels there are per unit of distance in the |
| 562 |
horizontal direction. \fB-yresolution\fP is analogous for the |
| 563 |
vertical direction. |
| 564 |
.PP |
| 565 |
The unit of distance is given by the value of the RESOLUTIONUNIT |
| 566 |
option. That value is either INCH, CENTIMETER, or NONE. NONE |
| 567 |
means the unit is arbitrary or unspecified. This could mean that the |
| 568 |
creator and user of the image have a separate agreement as to what the |
| 569 |
unit is. But usually, it just means that the horizontal and vertical |
| 570 |
resolution values cannot be used for anything except to determine |
| 571 |
aspect ratio (because even though the unit is arbitrary or |
| 572 |
unspecified, it has to be the same for both resolution numbers). |
| 573 |
.PP |
| 574 |
If you \fIdon't\fP use a \fB-tag\fP option to specify the |
| 575 |
resolution tag and use the obsolete options instead, note the |
| 576 |
following: |
| 577 |
|
| 578 |
|
| 579 |
.IP \(bu |
| 580 |
If you don't include an specify \fB-xresolution\fP, the Tiff image |
| 581 |
does not contain horizontal resolution information. Likewise for |
| 582 |
\fB-yresolution\fP. If you don't specify \fB-resolutionunit\fP, the |
| 583 |
default is inches. |
| 584 |
|
| 585 |
.IP \(bu |
| 586 |
Before Netpbm 10.16 (June 2003), \fB-resolutionunit\fP did not |
| 587 |
exist and the resolution unit was always inches. |
| 588 |
|
| 589 |
|
| 590 |
|
| 591 |
.UN history |
| 592 |
.SH HISTORY |
| 593 |
.PP |
| 594 |
\fBpamtotiff\fP was originally \fBpnmtotiff\fP and did not handle |
| 595 |
PAM input. It was extended and renamed in Netpbm 10.30 (October 2005). |
| 596 |
|
| 597 |
|
| 598 |
.UN seealso |
| 599 |
.SH SEE ALSO |
| 600 |
.BR "tifftopnm" (1)\c |
| 601 |
\&, |
| 602 |
.BR "pnmtotiffcmyk" (1)\c |
| 603 |
\&, |
| 604 |
.BR "pamdepth" (1)\c |
| 605 |
\&, |
| 606 |
.BR "pamtopnm" (1)\c |
| 607 |
\&, |
| 608 |
.BR "pam" (1)\c |
| 609 |
\& |
| 610 |
|
| 611 |
.UN author |
| 612 |
.SH AUTHOR |
| 613 |
|
| 614 |
Derived by Jef Poskanzer from ras2tiff.c, which is |
| 615 |
Copyright (c) 1990 by Sun Microsystems, Inc. |
| 616 |
Author: Patrick J. Naughton (\[email protected]\fP). |
| 617 |
.SH DOCUMENT SOURCE |
| 618 |
This manual page was generated by the Netpbm tool 'makeman' from HTML |
| 619 |
source. The master documentation is at |
| 620 |
.IP |
| 621 |
.B http://netpbm.sourceforge.net/doc/pamtotiff.html |
| 622 |
.PP |