diff options
Diffstat (limited to 'upstream/debian-bookworm/man1/tifftopnm.1')
| -rw-r--r-- | upstream/debian-bookworm/man1/tifftopnm.1 | 354 |
1 files changed, 354 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man1/tifftopnm.1 b/upstream/debian-bookworm/man1/tifftopnm.1 new file mode 100644 index 00000000..0aed143f --- /dev/null +++ b/upstream/debian-bookworm/man1/tifftopnm.1 @@ -0,0 +1,354 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Tifftopnm User Manual" 1 "02 January 2015" "netpbm documentation" + +.SH NAME + +tifftopnm - convert a TIFF file into a PNM image + +.UN synopsis +.SH SYNOPSIS + +\fBtifftopnm\fP + +[\fB-alphaout=\fP{\fIalpha-filename\fP,\fB-\fP}] +[\fB-headerdump\fP] +[\fB-verbose\fP] +[\fB-respectfillorder\fP] +[\fB-byrow\fP] +[\fB-orientraw\fP] +[\fItiff-filename\fP] + + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBtifftopnm\fP reads a TIFF file as input and produces a PNM image as +output. The type of the output file depends on the input file - if it's black +and white, \fBtifftopnm\fP generates a PBM image; if it's grayscale, it +generates a PGM image; otherwise, the output is PPM. The program tells you +which type it is writing. +.PP +If the TIFF file contains multiple images (multiple +"directories"), \fBtifftopnm\fP generates a multi-image PNM +output stream. Before Netpbm 10.27 (March 2005), however, it would +just ignore all but the first input image. +.PP +The \fItiff-filename\fP argument names the file that contains the Tiff +image. If you specify "-" or don't specify this +argument, \fBtifftopnm\fP uses Standard Input. +.PP +In either case, before Netpbm 10.70 (March 2015), the file must be +seekable. That means no pipe, but any regular file is fine. In current +Netpbm, the file need not be seekable, but if it isn't, \fBtifftopnm\fP +creates a temporary regular file containing the entire image, so you must have +resources for that (and it may defeat your reason for using a pipe). + +.UN library +.SS TIFF Capability +.PP +\fBpamtotiff\fP uses the Libtiff.org TIFF library (or whatever +equivalent you provide) to interpret the TIFF input. So the set of files +it is able to interpret is determined mostly by that library. +.PP +This program cannot read every possible TIFF file -- there are +myriad variations of the TIFF format. However, it does understand +monochrome and gray scale, RGB, RGBA (red/green/blue with transparency +channel), CMYK (Cyan-Magenta-Yellow-Black ink color separation), and +color palette TIFF files. An RGB file can have either single plane +(interleaved) color or multiple plane format. The program reads 1-8 +and 16 bit-per-sample input, the latter in either bigendian or +littlendian encoding. Tiff directory information may also be either +bigendian or littlendian. +.PP +There are many TIFF formats that \fBtifftopnm\fP can read only if +the image is small enough to fit in memory. \fBtifftopnm\fP uses the +TIFF library's TIFFRGBAImageGet() function to process the TIFF image +if it can get enough memory for TIFFRGBAImageGet() to store the whole +image in memory at once (that's what TIFFRGBAImageGet() does). If +not, \fBtifftopnm\fP uses a more primitive row-by-row conversion +strategy using the raw data returned by TIFFReadScanLine() and native +intelligence. That native intelligence does not know as many formats +as TIFFRGBAImageGet() does. And certain compressed formats simply +cannot be read with TIFFReadScanLine(). +.PP +Before Netpbm 10.11 (October 2002), \fBtifftopnm\fP never used +TIFFRGBAImageGet(), so it could not interpret many of the formats it +can interpret today. +.PP +There is no fundamental reason that this program could not read +other kinds of TIFF files even when they don't fit in memory all at +once. The existing limitations are mainly because no one has asked +for more. + +.UN output +.SS Output Image +.PP +The PNM output has the same maxval as the Tiff input, except that +if the Tiff input is colormapped (which implies a maxval of 65535) the +PNM output has a maxval of 255. Though this may result in lost +information, such input images hardly ever actually have more color +resolution than a maxval of 255 provides and people often cannot deal +with PNM files that have maxval > 255. By contrast, a +non-colormapped Tiff image that doesn't need a maxval > 255 doesn't +\fIhave\fP a maxval > 255, so when \fBtifftopnm\fP sees a +non-colormapped maxval > 255, it takes it seriously and produces a +matching output maxval. +.PP +Another exception is where the TIFF maxval is greater than 65535, +which is the maximum allowed by the Netpbm formats. In that case, +\fBtifftopnm\fP uses a maxval of 65535, and you lose some information +in the conversion. + +.UN options +.SH OPTIONS +.PP +In addition to the options common to all programs based on libnetpbm +(most notably \fB-quiet\fP, see +.UR index.html#commonoptions + Common Options +.UE +\&), \fBtifftopnm\fP recognizes the following +command line options: +.PP +You may abbreviate any option to its shortest unique prefix. You may use +two hyphens instead of one in options. You may separate an option and +its value either by an equals sign or white space. + + +.TP +\fB-alphaout=\fP\fIalpha-filename\fP +\fBtifftopnm \fPcreates a PGM file containing the alpha channel +values in the input image. If the input image doesn't contain a +transparency channel, the \fIalpha-filename\fP file contains all zero +(transparent) transparency values. If you don't specify \fB-alphaout\fP, + +\fBtifftopnm\fP does not generate a transparency file, and if the input +image has an transparency channel, \fBtifftopnm\fP simply discards it. +.sp +If you specify \fB-\fP as the filename, \fBtifftopnm\fP +writes the transparency output to Standard Output and discards the image. +.sp +See +.BR "pamcomp" (1)\c +\& for one way to use +the transparency output file. + +.TP +\fB-respectfillorder\fP +By default, \fBtifftopnm \fP ignores the "fillorder" +tag in the TIFF input, which means it may incorrectly interpret the +image. To make it follow the spec, use this option. For a lengthy +but engaging discussion of why \fBtifftopnm\fP works this way and how +to use the \fB-respectfillorder\fP option, see the note on fillorder +below. + +.TP +\fB-byrow\fP +This option can make \fBtifftopnm\fP run faster. +.sp +\fBtifftopnm\fP has two ways to do the conversion from Tiff to PNM, using +respectively two facilities of the TIFF library: + + + +.TP +Whole Image +Decode the entire image into memory at once, using +\fBTIFFRGBAImageGet()\fP, then convert to PNM and output row by row. + +.TP +Row By Row +Read, convert, and output one row at a time +using \fBTIFFReadScanline()\fP + + +.sp +Whole Image is preferable because the Tiff library does more of the +work, which means it understands more of the Tiff format possibilities +now and in the future. Also, some compressed TIFF formats don't allow +you to extract an individual row. +.sp +Row By Row uses far less memory, which means with large images, it +can run in environments where Whole Image cannot and may also run +faster. And because Netpbm code does more of the work, it's possible +that it can be more flexible or at least give better diagnostic +information if there's something wrong with the TIFF. +.sp +The Netpbm native code may do something correctly that the TIFF +library does incorrectly, or vice versa. +.sp +In Netpbm, we stress function over performance, so by default we +try Whole Image first, and if we can't get enough memory for the +decoded image or \fBTIFFRGBAImageGet()\fP fails, we fall back to Row By Row. +But if you specify the \fB-byrow\fP option, \fBtifftopnm\fP will not +attempt Whole Image. If Row By Row does not work, it simply fails. +.sp +See +.UR #cmyk +Color Separation (CMYK) TIFFs +.UE +\& for a +description of one way Row By Row makes a significant difference in +your results. +.sp +Whole Image costs you precision when your TIFF image uses more than +8 bits per sample. \fBTIFFRGBAImageGet()\fP converts the samples to 8 bits. +\fBtifftopnm\fP then scales them back to maxval 65535, but the lower +8 bits of information is gone. +.sp +In many versions of the TIFF library, \fBTIFFRGBAImageGet()\fP does not +correctly interpret TIFF files in which the raster orientation is +column-major (i.e. a row of the raster is a column of the image). +With such a TIFF library and file, you must use \fB-byrow\fP to get +correct output. +.sp +Before Netpbm 10.11 (October 2002), \fBtifftopnm\fP always did Row +By Row. Netpbm 10.12 always tried Whole Image first. \fB-byrow\fP +came in with Netpbm 10.13 (January 2003). + +.TP +\fB-orientraw\fP +A TIFF stream contains raster data which can be arranged in the +stream various ways. Most commonly, it is arranged by rows, with the +top row first, and the pixels left to right within each row, but many +other orientations are possible. +.sp +The common orientation is the same one the Netpbm formats use, so +\fBtifftopnm\fP can do its jobs quite efficiently when the TIFF raster +is oriented that way. +.sp +But if the TIFF raster is oriented any other way, it can take a +considerable amount of processing for \fBtifftopnm\fP to convert it to +Netpbm format. +.sp +\fB-orientraw\fP says to produce an output image that represents the raw +raster in the TIFF stream rather than the image the TIFF stream is supposed to +represent. In the output, the top left corner corresponds to the start of the +TIFF raster, the next pixel to the right is the next pixel in the TIFF raster, +etc. \fBtifftopnm\fP can do this easily, but you don't get the right image +out. You can use \fBpamflip\fP to turn the output into the image the TIFF +stream represents (but if you do that, you pretty much lose the benefit of +\fB-orientraw\fP). +.sp +With this option, \fBtifftopnm\fP always uses the Row By Row method +(see \fB-byrow\fP). +.sp +This option was new in Netpbm 10.42 (March 2008). Before that, +\fBtifftopnm\fP generally produces arbitrary results with TIFF images +that have an orientation other than the common one. + +.TP +\fB-verbose\fP +Print extra messages to Standard Error about the conversion. + +.TP +\fB-headerdump\fP +Dump TIFF file information to stderr. This information may be useful +in debugging TIFF file conversion problems. + + + +.UN notes +.SH NOTES + +.UN fillorder +.SS Fillorder +.PP +There is a piece of information in the header of a TIFF image called +"fillorder." The TIFF specification quite clearly states +that this value tells the order in which bits are arranged in a byte +in the description of the image's pixels. There are two options, +assuming that the image has a format where more than one pixel can be +represented by a single byte: 1) the byte is filled from most +significant bit to least significant bit going left to right in the +image; and 2) the opposite. +.PP +However, there is confusion in the world as to the meaning of +fillorder. Evidence shows that some people believe it has to do with +byte order when a single value is represented by two bytes. +.PP +These people cause TIFF images to be created that, while they use a +MSB-to-LSB fillorder, have a fillorder tag that says they used LSB-to-MSB. +A program that properly interprets a TIFF image will not end up with the +image that the author intended in this case. +.PP +For a long time, \fBtifftopnm\fP did not understand fillorder itself +and assumed the fillorder was MSB-to-LSB regardless of the fillorder +tag in the TIFF header. And as far as I know, there is no legitimate +reason to use a fillorder other than MSB-to-LSB. So users of +\fBtifftopnm\fP were happily using those TIFF images that had +incorrect fillorder tags. +.PP +So that those users can continue to be happy, \fBtifftopnm\fP today +continues to ignore the fillorder tag unless you tell it not to. (It +does, however, warn you when the fillorder tag does not say MSB-to-LSB +that the tag is being ignored). +.PP +If for some reason you have a TIFF image that actually has LSB-to-MSB +fillorder, and its fillorder tag correctly indicates that, you must +use the \fB-respectfillorder\fP option on \fBtifftopnm\fP to get +proper results. +.PP +Examples of incorrect TIFF images are at +.UR ftp://weather.noaa.gov. +ftp://weather.noaa.gov. +.UE +\& They are +apparently created by a program called \fBfaxtotiff\fP. +.PP +This note was written on January 1, 2002. + + +.UN cmyk +.SS Color Separation (CMYK) TIFFs +.PP +Some TIFF images contain color information in CMYK form, whereas PNM +images use RGB. There are various formulas for converting between these +two forms, and \fBtifftopnm\fP can use either of two. +.PP +The TIFF library (Version 3.5.4 from libtiff.org) uses +Y=(1-K)*(1-B) (similar for R and G) in its TIFFRGBAImageGet() service. +When \fBtifftopnm\fP works in Whole Image mode, it uses that service, +so that's the conversion you get. +.PP +But when \fBtifftopnm\fP runs in Row By Row mode, it does not use +TIFFRGBAImageGet(), and you get what appears to be more useful: +Y=1-(B+K). This is the inverse of what \fBpnmtotiffcmyk\fP does. +.PP +See the \fB-byrow\fP option for more information on Whole Image versus +Row By Row mode. +.PP +Before Netpbm 10.21 (March 2004), \fBtifftopnm\fP used the +Y=(1-K)*(1-B) formula always. + + +.UN seealso +.SH SEE ALSO +.BR "pnmtotiff" (1)\c +\&, +.BR "pnmtotiffcmyk" (1)\c +\&, +.BR "pamcomp" (1)\c +\&, +.BR "pnm" (1)\c +\& + +.UN author +.SH AUTHOR +.PP +Derived by Jef Poskanzer from tif2ras.c, which is Copyright (c) +1990 by Sun Microsystems, Inc. Author: Patrick J. Naughton (\fInaughton@wind.sun.com\fP). +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/tifftopnm.html +.PP
\ No newline at end of file |