| 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 "Tifftopnm User Manual" 1 "02 January 2015" "netpbm documentation" |
| 7 |
|
| 8 |
.SH NAME |
| 9 |
|
| 10 |
tifftopnm - convert a TIFF file into a PNM image |
| 11 |
|
| 12 |
.UN synopsis |
| 13 |
.SH SYNOPSIS |
| 14 |
|
| 15 |
\fBtifftopnm\fP |
| 16 |
|
| 17 |
[\fB-alphaout=\fP{\fIalpha-filename\fP,\fB-\fP}] |
| 18 |
[\fB-headerdump\fP] |
| 19 |
[\fB-verbose\fP] |
| 20 |
[\fB-respectfillorder\fP] |
| 21 |
[\fB-byrow\fP] |
| 22 |
[\fB-orientraw\fP] |
| 23 |
[\fItiff-filename\fP] |
| 24 |
|
| 25 |
|
| 26 |
.UN description |
| 27 |
.SH DESCRIPTION |
| 28 |
.PP |
| 29 |
This program is part of |
| 30 |
.BR "Netpbm" (1)\c |
| 31 |
\&. |
| 32 |
.PP |
| 33 |
\fBtifftopnm\fP reads a TIFF file as input and produces a PNM image as |
| 34 |
output. The type of the output file depends on the input file - if it's black |
| 35 |
and white, \fBtifftopnm\fP generates a PBM image; if it's grayscale, it |
| 36 |
generates a PGM image; otherwise, the output is PPM. The program tells you |
| 37 |
which type it is writing. |
| 38 |
.PP |
| 39 |
If the TIFF file contains multiple images (multiple |
| 40 |
"directories"), \fBtifftopnm\fP generates a multi-image PNM |
| 41 |
output stream. Before Netpbm 10.27 (March 2005), however, it would |
| 42 |
just ignore all but the first input image. |
| 43 |
.PP |
| 44 |
The \fItiff-filename\fP argument names the file that contains the Tiff |
| 45 |
image. If you specify "-" or don't specify this |
| 46 |
argument, \fBtifftopnm\fP uses Standard Input. |
| 47 |
.PP |
| 48 |
In either case, before Netpbm 10.70 (March 2015), the file must be |
| 49 |
seekable. That means no pipe, but any regular file is fine. In current |
| 50 |
Netpbm, the file need not be seekable, but if it isn't, \fBtifftopnm\fP |
| 51 |
creates a temporary regular file containing the entire image, so you must have |
| 52 |
resources for that (and it may defeat your reason for using a pipe). |
| 53 |
|
| 54 |
.UN library |
| 55 |
.SS TIFF Capability |
| 56 |
.PP |
| 57 |
\fBpamtotiff\fP uses the Libtiff.org TIFF library (or whatever |
| 58 |
equivalent you provide) to interpret the TIFF input. So the set of files |
| 59 |
it is able to interpret is determined mostly by that library. |
| 60 |
.PP |
| 61 |
This program cannot read every possible TIFF file -- there are |
| 62 |
myriad variations of the TIFF format. However, it does understand |
| 63 |
monochrome and gray scale, RGB, RGBA (red/green/blue with transparency |
| 64 |
channel), CMYK (Cyan-Magenta-Yellow-Black ink color separation), and |
| 65 |
color palette TIFF files. An RGB file can have either single plane |
| 66 |
(interleaved) color or multiple plane format. The program reads 1-8 |
| 67 |
and 16 bit-per-sample input, the latter in either bigendian or |
| 68 |
littlendian encoding. Tiff directory information may also be either |
| 69 |
bigendian or littlendian. |
| 70 |
.PP |
| 71 |
There are many TIFF formats that \fBtifftopnm\fP can read only if |
| 72 |
the image is small enough to fit in memory. \fBtifftopnm\fP uses the |
| 73 |
TIFF library's TIFFRGBAImageGet() function to process the TIFF image |
| 74 |
if it can get enough memory for TIFFRGBAImageGet() to store the whole |
| 75 |
image in memory at once (that's what TIFFRGBAImageGet() does). If |
| 76 |
not, \fBtifftopnm\fP uses a more primitive row-by-row conversion |
| 77 |
strategy using the raw data returned by TIFFReadScanLine() and native |
| 78 |
intelligence. That native intelligence does not know as many formats |
| 79 |
as TIFFRGBAImageGet() does. And certain compressed formats simply |
| 80 |
cannot be read with TIFFReadScanLine(). |
| 81 |
.PP |
| 82 |
Before Netpbm 10.11 (October 2002), \fBtifftopnm\fP never used |
| 83 |
TIFFRGBAImageGet(), so it could not interpret many of the formats it |
| 84 |
can interpret today. |
| 85 |
.PP |
| 86 |
There is no fundamental reason that this program could not read |
| 87 |
other kinds of TIFF files even when they don't fit in memory all at |
| 88 |
once. The existing limitations are mainly because no one has asked |
| 89 |
for more. |
| 90 |
|
| 91 |
.UN output |
| 92 |
.SS Output Image |
| 93 |
.PP |
| 94 |
The PNM output has the same maxval as the Tiff input, except that |
| 95 |
if the Tiff input is colormapped (which implies a maxval of 65535) the |
| 96 |
PNM output has a maxval of 255. Though this may result in lost |
| 97 |
information, such input images hardly ever actually have more color |
| 98 |
resolution than a maxval of 255 provides and people often cannot deal |
| 99 |
with PNM files that have maxval > 255. By contrast, a |
| 100 |
non-colormapped Tiff image that doesn't need a maxval > 255 doesn't |
| 101 |
\fIhave\fP a maxval > 255, so when \fBtifftopnm\fP sees a |
| 102 |
non-colormapped maxval > 255, it takes it seriously and produces a |
| 103 |
matching output maxval. |
| 104 |
.PP |
| 105 |
Another exception is where the TIFF maxval is greater than 65535, |
| 106 |
which is the maximum allowed by the Netpbm formats. In that case, |
| 107 |
\fBtifftopnm\fP uses a maxval of 65535, and you lose some information |
| 108 |
in the conversion. |
| 109 |
|
| 110 |
.UN options |
| 111 |
.SH OPTIONS |
| 112 |
.PP |
| 113 |
In addition to the options common to all programs based on libnetpbm |
| 114 |
(most notably \fB-quiet\fP, see |
| 115 |
.UR index.html#commonoptions |
| 116 |
Common Options |
| 117 |
.UE |
| 118 |
\&), \fBtifftopnm\fP recognizes the following |
| 119 |
command line options: |
| 120 |
.PP |
| 121 |
You may abbreviate any option to its shortest unique prefix. You may use |
| 122 |
two hyphens instead of one in options. You may separate an option and |
| 123 |
its value either by an equals sign or white space. |
| 124 |
|
| 125 |
|
| 126 |
.TP |
| 127 |
\fB-alphaout=\fP\fIalpha-filename\fP |
| 128 |
\fBtifftopnm \fPcreates a PGM file containing the alpha channel |
| 129 |
values in the input image. If the input image doesn't contain a |
| 130 |
transparency channel, the \fIalpha-filename\fP file contains all zero |
| 131 |
(transparent) transparency values. If you don't specify \fB-alphaout\fP, |
| 132 |
|
| 133 |
\fBtifftopnm\fP does not generate a transparency file, and if the input |
| 134 |
image has an transparency channel, \fBtifftopnm\fP simply discards it. |
| 135 |
.sp |
| 136 |
If you specify \fB-\fP as the filename, \fBtifftopnm\fP |
| 137 |
writes the transparency output to Standard Output and discards the image. |
| 138 |
.sp |
| 139 |
See |
| 140 |
.BR "pamcomp" (1)\c |
| 141 |
\& for one way to use |
| 142 |
the transparency output file. |
| 143 |
|
| 144 |
.TP |
| 145 |
\fB-respectfillorder\fP |
| 146 |
By default, \fBtifftopnm \fP ignores the "fillorder" |
| 147 |
tag in the TIFF input, which means it may incorrectly interpret the |
| 148 |
image. To make it follow the spec, use this option. For a lengthy |
| 149 |
but engaging discussion of why \fBtifftopnm\fP works this way and how |
| 150 |
to use the \fB-respectfillorder\fP option, see the note on fillorder |
| 151 |
below. |
| 152 |
|
| 153 |
.TP |
| 154 |
\fB-byrow\fP |
| 155 |
This option can make \fBtifftopnm\fP run faster. |
| 156 |
.sp |
| 157 |
\fBtifftopnm\fP has two ways to do the conversion from Tiff to PNM, using |
| 158 |
respectively two facilities of the TIFF library: |
| 159 |
|
| 160 |
|
| 161 |
|
| 162 |
.TP |
| 163 |
Whole Image |
| 164 |
Decode the entire image into memory at once, using |
| 165 |
\fBTIFFRGBAImageGet()\fP, then convert to PNM and output row by row. |
| 166 |
|
| 167 |
.TP |
| 168 |
Row By Row |
| 169 |
Read, convert, and output one row at a time |
| 170 |
using \fBTIFFReadScanline()\fP |
| 171 |
|
| 172 |
|
| 173 |
.sp |
| 174 |
Whole Image is preferable because the Tiff library does more of the |
| 175 |
work, which means it understands more of the Tiff format possibilities |
| 176 |
now and in the future. Also, some compressed TIFF formats don't allow |
| 177 |
you to extract an individual row. |
| 178 |
.sp |
| 179 |
Row By Row uses far less memory, which means with large images, it |
| 180 |
can run in environments where Whole Image cannot and may also run |
| 181 |
faster. And because Netpbm code does more of the work, it's possible |
| 182 |
that it can be more flexible or at least give better diagnostic |
| 183 |
information if there's something wrong with the TIFF. |
| 184 |
.sp |
| 185 |
The Netpbm native code may do something correctly that the TIFF |
| 186 |
library does incorrectly, or vice versa. |
| 187 |
.sp |
| 188 |
In Netpbm, we stress function over performance, so by default we |
| 189 |
try Whole Image first, and if we can't get enough memory for the |
| 190 |
decoded image or \fBTIFFRGBAImageGet()\fP fails, we fall back to Row By Row. |
| 191 |
But if you specify the \fB-byrow\fP option, \fBtifftopnm\fP will not |
| 192 |
attempt Whole Image. If Row By Row does not work, it simply fails. |
| 193 |
.sp |
| 194 |
See |
| 195 |
.UR #cmyk |
| 196 |
Color Separation (CMYK) TIFFs |
| 197 |
.UE |
| 198 |
\& for a |
| 199 |
description of one way Row By Row makes a significant difference in |
| 200 |
your results. |
| 201 |
.sp |
| 202 |
Whole Image costs you precision when your TIFF image uses more than |
| 203 |
8 bits per sample. \fBTIFFRGBAImageGet()\fP converts the samples to 8 bits. |
| 204 |
\fBtifftopnm\fP then scales them back to maxval 65535, but the lower |
| 205 |
8 bits of information is gone. |
| 206 |
.sp |
| 207 |
In many versions of the TIFF library, \fBTIFFRGBAImageGet()\fP does not |
| 208 |
correctly interpret TIFF files in which the raster orientation is |
| 209 |
column-major (i.e. a row of the raster is a column of the image). |
| 210 |
With such a TIFF library and file, you must use \fB-byrow\fP to get |
| 211 |
correct output. |
| 212 |
.sp |
| 213 |
Before Netpbm 10.11 (October 2002), \fBtifftopnm\fP always did Row |
| 214 |
By Row. Netpbm 10.12 always tried Whole Image first. \fB-byrow\fP |
| 215 |
came in with Netpbm 10.13 (January 2003). |
| 216 |
|
| 217 |
.TP |
| 218 |
\fB-orientraw\fP |
| 219 |
A TIFF stream contains raster data which can be arranged in the |
| 220 |
stream various ways. Most commonly, it is arranged by rows, with the |
| 221 |
top row first, and the pixels left to right within each row, but many |
| 222 |
other orientations are possible. |
| 223 |
.sp |
| 224 |
The common orientation is the same one the Netpbm formats use, so |
| 225 |
\fBtifftopnm\fP can do its jobs quite efficiently when the TIFF raster |
| 226 |
is oriented that way. |
| 227 |
.sp |
| 228 |
But if the TIFF raster is oriented any other way, it can take a |
| 229 |
considerable amount of processing for \fBtifftopnm\fP to convert it to |
| 230 |
Netpbm format. |
| 231 |
.sp |
| 232 |
\fB-orientraw\fP says to produce an output image that represents the raw |
| 233 |
raster in the TIFF stream rather than the image the TIFF stream is supposed to |
| 234 |
represent. In the output, the top left corner corresponds to the start of the |
| 235 |
TIFF raster, the next pixel to the right is the next pixel in the TIFF raster, |
| 236 |
etc. \fBtifftopnm\fP can do this easily, but you don't get the right image |
| 237 |
out. You can use \fBpamflip\fP to turn the output into the image the TIFF |
| 238 |
stream represents (but if you do that, you pretty much lose the benefit of |
| 239 |
\fB-orientraw\fP). |
| 240 |
.sp |
| 241 |
With this option, \fBtifftopnm\fP always uses the Row By Row method |
| 242 |
(see \fB-byrow\fP). |
| 243 |
.sp |
| 244 |
This option was new in Netpbm 10.42 (March 2008). Before that, |
| 245 |
\fBtifftopnm\fP generally produces arbitrary results with TIFF images |
| 246 |
that have an orientation other than the common one. |
| 247 |
|
| 248 |
.TP |
| 249 |
\fB-verbose\fP |
| 250 |
Print extra messages to Standard Error about the conversion. |
| 251 |
|
| 252 |
.TP |
| 253 |
\fB-headerdump\fP |
| 254 |
Also dump TIFF file information to stderr. This information may be useful |
| 255 |
in debugging TIFF file conversion problems. |
| 256 |
|
| 257 |
|
| 258 |
|
| 259 |
.UN notes |
| 260 |
.SH NOTES |
| 261 |
|
| 262 |
.UN fillorder |
| 263 |
.SS Fillorder |
| 264 |
.PP |
| 265 |
There is a piece of information in the header of a TIFF image called |
| 266 |
"fillorder." The TIFF specification quite clearly states |
| 267 |
that this value tells the order in which bits are arranged in a byte |
| 268 |
in the description of the image's pixels. There are two options, |
| 269 |
assuming that the image has a format where more than one pixel can be |
| 270 |
represented by a single byte: 1) the byte is filled from most |
| 271 |
significant bit to least significant bit going left to right in the |
| 272 |
image; and 2) the opposite. |
| 273 |
.PP |
| 274 |
However, there is confusion in the world as to the meaning of |
| 275 |
fillorder. Evidence shows that some people believe it has to do with |
| 276 |
byte order when a single value is represented by two bytes. |
| 277 |
.PP |
| 278 |
These people cause TIFF images to be created that, while they use a |
| 279 |
MSB-to-LSB fillorder, have a fillorder tag that says they used LSB-to-MSB. |
| 280 |
A program that properly interprets a TIFF image will not end up with the |
| 281 |
image that the author intended in this case. |
| 282 |
.PP |
| 283 |
For a long time, \fBtifftopnm\fP did not understand fillorder itself |
| 284 |
and assumed the fillorder was MSB-to-LSB regardless of the fillorder |
| 285 |
tag in the TIFF header. And as far as I know, there is no legitimate |
| 286 |
reason to use a fillorder other than MSB-to-LSB. So users of |
| 287 |
\fBtifftopnm\fP were happily using those TIFF images that had |
| 288 |
incorrect fillorder tags. |
| 289 |
.PP |
| 290 |
So that those users can continue to be happy, \fBtifftopnm\fP today |
| 291 |
continues to ignore the fillorder tag unless you tell it not to. (It |
| 292 |
does, however, warn you when the fillorder tag does not say MSB-to-LSB |
| 293 |
that the tag is being ignored). |
| 294 |
.PP |
| 295 |
If for some reason you have a TIFF image that actually has LSB-to-MSB |
| 296 |
fillorder, and its fillorder tag correctly indicates that, you must |
| 297 |
use the \fB-respectfillorder\fP option on \fBtifftopnm\fP to get |
| 298 |
proper results. |
| 299 |
.PP |
| 300 |
Examples of incorrect TIFF images are at |
| 301 |
.UR ftp://weather.noaa.gov. |
| 302 |
ftp://weather.noaa.gov. |
| 303 |
.UE |
| 304 |
\& They are |
| 305 |
apparently created by a program called \fBfaxtotiff\fP. |
| 306 |
.PP |
| 307 |
This note was written on January 1, 2002. |
| 308 |
|
| 309 |
|
| 310 |
.UN cmyk |
| 311 |
.SS Color Separation (CMYK) TIFFs |
| 312 |
.PP |
| 313 |
Some TIFF images contain color information in CMYK form, whereas PNM |
| 314 |
images use RGB. There are various formulas for converting between these |
| 315 |
two forms, and \fBtifftopnm\fP can use either of two. |
| 316 |
.PP |
| 317 |
The TIFF library (Version 3.5.4 from libtiff.org) uses |
| 318 |
Y=(1-K)*(1-B) (similar for R and G) in its TIFFRGBAImageGet() service. |
| 319 |
When \fBtifftopnm\fP works in Whole Image mode, it uses that service, |
| 320 |
so that's the conversion you get. |
| 321 |
.PP |
| 322 |
But when \fBtifftopnm\fP runs in Row By Row mode, it does not use |
| 323 |
TIFFRGBAImageGet(), and you get what appears to be more useful: |
| 324 |
Y=1-(B+K). This is the inverse of what \fBpnmtotiffcmyk\fP does. |
| 325 |
.PP |
| 326 |
See the \fB-byrow\fP option for more information on Whole Image versus |
| 327 |
Row By Row mode. |
| 328 |
.PP |
| 329 |
Before Netpbm 10.21 (March 2004), \fBtifftopnm\fP used the |
| 330 |
Y=(1-K)*(1-B) formula always. |
| 331 |
|
| 332 |
|
| 333 |
.UN seealso |
| 334 |
.SH SEE ALSO |
| 335 |
.BR "pnmtotiff" (1)\c |
| 336 |
\&, |
| 337 |
.BR "pnmtotiffcmyk" (1)\c |
| 338 |
\&, |
| 339 |
.BR "pamcomp" (1)\c |
| 340 |
\&, |
| 341 |
.BR "pnm" (1)\c |
| 342 |
\& |
| 343 |
|
| 344 |
.UN author |
| 345 |
.SH AUTHOR |
| 346 |
.PP |
| 347 |
Derived by Jef Poskanzer from tif2ras.c, which is Copyright (c) |
| 348 |
1990 by Sun Microsystems, Inc. Author: Patrick J. Naughton (\[email protected]\fP). |
| 349 |
.SH DOCUMENT SOURCE |
| 350 |
This manual page was generated by the Netpbm tool 'makeman' from HTML |
| 351 |
source. The master documentation is at |
| 352 |
.IP |
| 353 |
.B http://netpbm.sourceforge.net/doc/tifftopnm.html |
| 354 |
.PP |