diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/pamtotiff.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/pamtotiff.1 | 622 |
1 files changed, 622 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/pamtotiff.1 b/upstream/mageia-cauldron/man1/pamtotiff.1 new file mode 100644 index 00000000..9d6c1536 --- /dev/null +++ b/upstream/mageia-cauldron/man1/pamtotiff.1 @@ -0,0 +1,622 @@ +\ +.\" 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 "Pamtotiff User Manual" 0 "05 April 2017" "netpbm documentation" + +.SH NAME +pamtotiff - convert a Netpbm image to a TIFF file + +.UN synopsis +.SH SYNOPSIS + +\fBpamtotiff\fP + +[\fB-none\fP | \fB-packbits\fP | \fB-lzw\fP | \fB-g3\fP | \fB-g4\fP +| \fB-flate\fP | \fB-adobeflate\fP] + +[\fB-2d\fP] + +[\fB-fill\fP] + +[\fB-predictor=\fP\fIn\fP] + +[\fB-msb2lsb\fP|\fB-lsb2msb\fP] + +[\fB-rowsperstrip=\fP\fIn\fP] + +[\fB-minisblack\fP|\fB-miniswhite\fP|\fBmb\fP|\fBmw\fP] + +[\fB-truecolor\fP] + +[\fB-color\fP] + +[\fB-indexbits=\fP\fIbitwidthlist\fP] +[\fB-xresolution=\fP\fIxres\fP] + +[\fB-yresolution=\fP\fIyres\fP] +[\fB-resolutionunit=\fP{\fBinch\fP | \fBcentimeter\fP | \fBnone\fP | +\fBin\fP | \fBcm\fP | \fBno\fP}] + +[\fB-append\fP] + +[\fB-tag=\fP\fItaglist\fP] + +[\fIpamfile\fP] +.PP +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. + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBpamtotiff\fP reads a PNM or PAM image as input and produces a TIFF file +as output. +.PP +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. + +.UN output +.SS The Output File +.PP +By default, the output goes to Standard Output. Alternatively, you can +specify an output file with the \fB-output\fP option and \fBpamtotiff\fP +will write its output directly to that file. +.PP +Because of the way the TIFF library (which \fBpamtotiff\fP uses) works, +when the program writes to Standard Output, it generates the entire TIFF image +in a temporary file and then copies it to Standard Output; you may see +negative performance effects of this. +.PP +The \fB-output\fP 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. +.PP +With \fB-output\fP, if the file already exists and has data in it, +\fBpamtotiff\fP appends the image to the existing TIFF file. (A TIFF file +may contain multiple images). +.PP +By default, \fBpamtotiff\fP creates the file named by \fB-output\fP if it +does not already exist. But if you also specify \fB-append\fP, the program +fails if the file named by \fB-output\fP does not already exist. +.PP +Before Netpbm 10.67 (June 2014), there is no \fB-output\fP option and +Standard Output must be seekable. So pipes are out. +.PP +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 \fB-output\fP to append to an existing TIFF file. +.PP +The difference above means current \fBpamtotiff\fP 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. + + +.UN oldoutput +.B Old Versions +.PP +As alluded to above, \fBpamtotiff\fP does output very differently +in releases before 10.67. The following describes the old function, +which is unusual both for Netpbm and for Unix programs in general. + + +.IP \(bu +The output file must be seekable. \fBpamtotiff\fP does not +write it sequentially. Therefore, you can't use a pipe; you can't +pipe the output of \fBpamtotiff\fP to some other program. But any +regular file should work. + +.IP \(bu +If the output file descriptor is readable, you must either specify +\fB-append\fP so as to add to the existing file, or make sure the +file is empty. Otherwise, \fBpamtotiff\fP will fail with an +unhelpful message telling you that a TIFF library function failed to +open the TIFF output stream. + +.IP \(bu +If you are converting multiple images (your input stream contains +multiple images), the output file must be both readable and writable. + + +.PP +If you're using a Unix command shell to run \fBpamtotiff\fP, 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: + +.nf +\f(CW + $ pamtotiff myimage.pnm >/tmp/myimage.tiff +\fP + +.fi + +In Bash, you would set up a read/write Standard Output to the file +/tmp/myimage.tiff like this: + +.nf +\f(CW + $ pamtotiff myimage.pnm 1<>/tmp/myimage.tiff +\fP + +.fi + +.UN library +.SS TIFF Capability +.PP +\fBpamtotiff\fP uses the Libtiff.org TIFF library (or whatever +equivalent you provide) to generate the TIFF output. Details of the +format it produces are therefore controlled by that library. + +.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 +\&), \fBpamtotiff\fP recognizes the following +command line options: + +.UN compression +.SS Compression +.PP +By default, \fBpamtotiff\fP 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. +.PP +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 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 \fBpamtotiff\fP +behavior remains the same for compatibility with older TIFF libraries +and applications of \fBpamtotiff\fP. +.PP +The \fB-none\fP, \fB-packbits\fP, \fB-lzw\fP, \fB-g3\fP, +\fB-g4\fP, \fB-flate\fP, and \fB-adobeflate\fP options are used to +override the default and set the compression scheme used in creating +the output file. + +The \fB-predictor\fP 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, \fBpamtotiff\fP +creates a TIFF file with msb-to-lsb fill order. The \fB-msb2lsb\fP and +\fB-lsb2msb\fP options are used to override the default and set the fill +order used in creating the file. +.PP +With some older TIFF libraries, \fB-lzw\fP 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, \fB-lzw\fP works because no +distributors of the TIFF library were sensitive yet to the patent +issue. +.PP +\fB-flate\fP 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. + +.UN faxcompression +.B Fax Compression +.PP +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 +.BR "Fax Format" (1)\c +\& page for more information on these +compression schemes. +.PP +These formats all relate to ITU Group 3 and Group 4 fax machine +standards. +.PP +The \fB-g3\fP option chooses MH or MR compression: MR with the additional +option \fB-2d\fP; MH without it. \fB-g4\fP selects MMR. The option names +are a little unfortunate and historical, but are consistent with the TIFF +specification. +.PP +MMR has a better compression ratio than the other two. +.PP +\fB-fill\fP specifies that for MH or MR compression, each encoded scanline +shall be zero-filled to a byte boundary. +.PP +\fB-2d\fP and \fB-fill\fP are meaningful only with \fB-g3\fP. + + +.UN fillorder +.SS Fill Order +.PP +The \fB-msb2lsb\fP and \fBlsb2msb\fP options control the fill order. +.PP +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, ImageMagick and older Netpbm both have been known +to implement that interpretation. 2001.09.06. +.PP +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). + +.UN colorspace +.SS Color Space +.PP +\fB-color\fP tells \fBpamtotiff\fP 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, \fBpamtotiff\fP +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, \fBpamtotiff\fP always +produces grayscale TIFF output and this option has no effect. +.PP +The \fB-color\fP option can prevent \fBpamtotiff\fP from making +two passes through the input file, thus improving speed and memory +usage. See +.UR #multipass +Multiple Passes +.UE +\&. +.PP +\fB-truecolor\fP tells \fBpamtotiff\fP to produce the 24-bit RGB +form of TIFF output if it is producing a color TIFF image. Without +this option, \fBpamtotiff\fP produces a colormapped (paletted) TIFF +image unless there are more than 256 colors (and in the latter case, +issues a warning). +.PP +The \fB-truecolor\fP option can prevent \fBpamtotiff\fP from +making two passes through the input file, thus improving speed and +memory usage. See +.UR #multipass +Multiple Passes +.UE +\&. +.PP +The \fB-color\fP and \fB-truecolor\fP options did not exist +before Netpbm 9.21 (December 2001). +.PP +If \fBpamtotiff\fP produces a grayscale TIFF image, this option +has no effect. +.PP +The \fB-minisblack\fP and \fB-miniswhite\fP options force the +output image to have a "minimum is black" or "minimum +is white" photometric, respectively. If you don't specify +either, \fBpamtotiff\fP uses minimum is black except when using Group +3 or Group 4 compression, in which case \fBpamtotiff\fP follows CCITT +fax standards and uses "minimum is white." This usually +results in better compression and is generally preferred for bilevel +coding. 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). +.PP +Before Netpbm 9.11 (February 200)1, \fBpamtotiff\fP always produced +"minimum is black," because of a bug. In either case, +\fBpamtotiff\fP sets the photometric interpretation tag in the TIFF +output according to which photometric is actually used. +.PP +Before Netpbm 10.78 (March 2017), \fBpamtotiff\fP respected +\fB-miniswhite\fP and \fB-minisblack\fP even with color images, producing +invalid TIFF images that have the indicated photometric but red, green, and +blue raster planes. +.PP +The \fB-indexbits\fP 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. +\fBpamtotiff\fP 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. +.PP +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 +\fB-indexbits\fP option. The value is a comma-separated list of the +bit widths you allow. \fBpamtotiff\fP chooses the smallest width you allow +that allows it to index the entire color table. If you don't allow any +such width, \fBpamtotiff\fP fails. Normally, the only useful value for +this option is \fB1,2,4,8\fP, because a program either understands the 8 +bit width (default) or understands them all. +.PP +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. +.PP +This option was added in June 2002. Before that, only 8 bit indices were +possible. + +.UN extratags +.SS Extra Tags +.PP +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. +.PP +You can tell \fBpamtotiff\fP explicitly to include tags such as this +in its output with the \fB-tag\fP option. You identify a list of tag +types and values and \fBpamtotiff\fP includes a tag in the output for +each item in your list. +.PP +The value of \fB-tag\fP is the list of tags, like this example: + +.nf +\f(CW + -tag=subfiletype=reducedimage,documentname=Fred,xposition=25 +\fP + +.fi +.PP +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 \fBtiff.h\fP 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. +.PP +The format of the value specification for a tag (stuff after the +equal sign) depends upon what kind of value the tag type has: + + +.IP \(bu +Integer: a decimal number + +.IP \(bu +Floating point number: a decimal number + +.IP \(bu +String: a string + +.IP \(bu +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 \fBtiff.h\fP 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. +.sp +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 \fBpamtotiff\fP doesn't +know about. + + +.PP +If you specify a tag type with \fB-tag\fP that is not independent +of the content of your PNM source image and \fBpamtotiff\fP's +conversion process (i.e. a tag type in which \fBpamtotiff\fP is +interested), \fBpamtotiff\fP fails. For example, you cannot specify +an IMAGEWIDTH tag with \fB-tag\fP, because \fBpamtotiff\fP generates +an IMAGEWIDTH tag that gives the actual width of the image. +.PP +\fB-tag\fP was new in Netpbm 10.31 (December 2005). + +.UN outputoptions +.SS Output +.PP +See +.UR #output +The Output File +.UE +\&. +.PP +\fB-output\fP names the output file. Without this option +\fBpamtotiff\fP writes to Standard Output. +.PP +The \fB-append\fP option tells \fBpamtotiff\fP only to append to the file +named by \fBoutput\fP; not create it. Without this option, the program +creates the file it does not already exist. But even then, if the file does +already exist, the program appends the image to what is in the file already. +(A TIFF file may contain multiple images). +.PP +\fB-append\fP has no effect if you don't also specify \fB-output\fP. +.PP +Before Netpbm 10.67 (June 2014), \fB-append\fP means something rather +different: it means to append the image to the output TIFF file (which is +always Standard Output in 10.67) instead of replacing its contents. +.PP +\fB-append\fP was new in Netpbm 10.27 (March 2005). + + + +.UN other +.SS Other +.PP +You can use the \fB-rowsperstrip\fP option to set the number of +rows (scanlines) in each strip of data in the output file. By +default, the output file has the number of rows per strip set to a +value that will ensure each strip is no more than 8 kilobytes long. + + +.UN notes +.SH NOTES +.PP +There are myriad variations of the TIFF format, and this program +generates only a few of them. \fBpamtotiff\fP creates a grayscale +TIFF file if its input is a PBM (monochrome) or PGM (grayscale) or +equivalent PAM file. \fBpamtotiff\fP also creates a grayscale file +if it input is PPM (color) or equivalent PAM, but there is only one +color in the image. +.PP +If the input is a PPM (color) file and there are 256 colors or +fewer, but more than 1, \fBpamtotiff\fP generates a color palette +TIFF file. If there are more colors than that, \fBpamtotiff\fP +generates an RGB (not RGBA) single plane TIFF file. Use +\fBpnmtotiffcmyk\fP to generate the cyan-magenta-yellow-black ink +color separation TIFF format. +.PP +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. + +.UN extrachannel +.SS Extra Channels +.PP +Like most Netpbm programs, \fBpamtotiff\fP'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 processing of other PAM subformats. +.PP +\fBpamtotiff\fP assumes any 1 plane PAM image is BLACKANDWHITE +or GRAYSCALE (and doesn't distinguish between those two). +.PP +\fBpamtotiff\fP assumes a PAM with more than 1 plane is of tuple +type RGB except with that number of planes instead of 3. +\fBpamtotiff\fP doesn't really 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 components, so +\fBpamtotiff\fP 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. +.PP +Note that \fBpamtotiff\fP may generate either a truecolor or +colormapped 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. +.PP +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. +.PP +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 \fB-color\fP option. + + +.UN multipass +.SS Multiple Passes +.PP +\fBpamtotiff\fP 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 specifying both the \fB-truecolor\fP and \fB-color\fP +options. +.PP + 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. +.PP +When the input is from a file that cannot be rewound and reread, +\fBpamtotiff\fP reads the entire input image into a temporary file +which can, and works from that. Even if it needs only one pass. +.PP +Before Netpbm 9.21 (December 2001), \fBpamtotiff\fP always read +the entire image into virtual memory and then did one, two, or three +passes through the memory copy. The \fB-truecolor\fP and +\fB-color\fP 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. + + +.UN resolution +.SS Resolution +.PP +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, YRESOLUTION, +and RESOLUTIONUNIT tags. By default, \fBpamtotiff\fP does not include +any tags of these types, but you can specify them with the \fB-tags\fP +option. +.PP +There are also options \fB-xresolution\fP, \fB-yresolution\fP, +and \fB-resolutionunit\fP, but those are obsolete. Before \fB-tags\fP +existed (before Netpbm 10.31 (December 2005), they were the only way. +.PP +Note that the number of pixels in the image and how much information +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. +.PP +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. \fB-yresolution\fP is analogous for the +vertical direction. +.PP +The unit of distance is given by the value of the RESOLUTIONUNIT +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 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). +.PP +If you \fIdon't\fP use a \fB-tag\fP option to specify the +resolution tag and use the obsolete options instead, note the +following: + + +.IP \(bu +If you don't include an specify \fB-xresolution\fP, the Tiff image +does not contain horizontal resolution information. Likewise for +\fB-yresolution\fP. If you don't specify \fB-resolutionunit\fP, the +default is inches. + +.IP \(bu +Before Netpbm 10.16 (June 2003), \fB-resolutionunit\fP did not +exist and the resolution unit was always inches. + + + +.UN history +.SH HISTORY +.PP +\fBpamtotiff\fP was originally \fBpnmtotiff\fP and did not handle +PAM input. It was extended and renamed in Netpbm 10.30 (October 2005). + + +.UN seealso +.SH SEE ALSO +.BR "tifftopnm" (1)\c +\&, +.BR "pnmtotiffcmyk" (1)\c +\&, +.BR "pamdepth" (1)\c +\&, +.BR "pamtopnm" (1)\c +\&, +.BR "pam" (1)\c +\& + +.UN author +.SH AUTHOR + +Derived by Jef Poskanzer from ras2tiff.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/pamtotiff.html +.PP
\ No newline at end of file |