diff options
Diffstat (limited to 'upstream/debian-unstable/man1/pnmtojpeg.1')
| -rw-r--r-- | upstream/debian-unstable/man1/pnmtojpeg.1 | 560 |
1 files changed, 560 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man1/pnmtojpeg.1 b/upstream/debian-unstable/man1/pnmtojpeg.1 new file mode 100644 index 00000000..09e736be --- /dev/null +++ b/upstream/debian-unstable/man1/pnmtojpeg.1 @@ -0,0 +1,560 @@ +\ +.\" 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 "Pnmtojpeg User Manual" 1 "23 April 2007" "netpbm documentation" + +.SH NAME +pnmtojpeg - convert PNM image to a JFIF ("JPEG") image + +.UN synopsis +.SH SYNOPSIS + +\fBpnmtojpeg\fP +[\fB-exif=\fP\fIfilespec\fP] +[\fB-quality=\fP\fIn\fP] +[{\fB-grayscale\fP|\fB-greyscale\fP}] +[\fB-density=\fP\fIn\fP\fBx\fP\fIn\fP[\fBdpi\fP,\fBdpcm\fP]] +[\fB-optimize\fP|\fB-optimise\fP] +[\fB-rgb\fP] +[\fB-progressive\fP] +[\fB-comment=\fP\fItext\fP] +[\fB-dct=\fP{\fBint\fP|\fBfast\fP|\fBfloat\fP}] +[\fB-arithmetic\fP] +[\fB-restart=\fP\fIn\fP] +[\fB-smooth=\fP\fIn\fP] +[\fB-maxmemory=\fP\fIn\fP] +[\fB-verbose\fP] +[\fB-baseline\fP] +[\fB-qtables=\fP\fIfilespec\fP] +[\fB-qslots=n[,...]\fP] +[\fB-sample=\fP\fIH\fP\fBx\fP\fIV\fP[,...]] +[\fB-scans=\fP\fIfilespec\fP] +[\fB-tracelevel=\fP\fIN\fP] + +\fIfilename\fP +.PP +Minimum unique abbreviation of option is acceptable. You may use double +hyphens instead of single hyphen to denote options. You may use white +space in place of the equals sign to separate an option name from its value. + + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBpnmtojpeg\fP converts the named PBM, PGM, or PPM image file, or +the standard input if no file is named, to a JFIF file on the standard +output. +.PP +\fBpnmtojpeg\fP uses the Independent JPEG Group's JPEG library to +create the output file. See \fB +.UR http://www.ijg.org +http://www.ijg.org +.UE +\& \fP for information +on the library. +.PP +"JFIF" is the correct name for the image format commonly +known as "JPEG." Strictly speaking, JPEG is a method of +compression. The image format using JPEG compression that is by far +the most common is JFIF. There is also a subformat of TIFF that uses +JPEG compression. +.PP +EXIF is an image format that is a subformat of JFIF (to wit, a JFIF +file that contains an EXIF header as an APP1 marker). +\fBpnmtojpeg\fP creates an EXIF image when you specify the +\fB-exif\fP option. + +.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 +\&), \fBpnmtojpeg\fP recognizes the following +command line options: + +.UN basicopts +.SS Basic Options + + +.TP +\fB-exif=\fP\fIfilespec\fP +This option specifies that the output image is to be EXIF (a subformat +of JFIF), i.e. it will have an EXIF header as a JFIF APP1 marker. +The contents of that marker are the contents of the specified file. +The special value \fB-\fP +means to read the EXIF header contents from standard input. It is +invalid to specify standard input for both the EXIF header and the +input image. +.sp +The EXIF file starts with a two byte field which is the length of +the file, including the length field, in pure binary, most significant +byte first. The special value of zero for the length field means there +is to be no EXIF header, i.e. the same as no \fB-exif\fP +option. This is useful for when you convert a file from JFIF to PNM +using \fBjpegtopnm\fP, +then transform it, then convert it back to JFIF with +\fBpnmtojpeg\fP, and you don't know whether or not it includes an EXIF header. +\fBjpegtopnm\fP +creates an EXIF file containing nothing but two bytes of zero when +the input JFIF file has no EXIF header. Thus, you can transfer +any EXIF header from the input JFIF to the output JFIF without +worrying about whether an EXIF header actually exists. +.sp +The contents of the EXIF file after the length field are the exact +byte for byte contents of the APP1 marker, not counting the length +field, that constitutes the EXIF header. + +.TP +\fB-quality=\fP\fIn\fP +Scale quantization tables to adjust image quality. \fIn\fP is 0 +(worst) to 100 (best); default is 75. Below about 25 can produce images +some interpreters won't be able to interpret. See below for more info. + +.TP +\fB-grayscale\fP +.TP +\fB-greyscale\fP +.TP +\fB-rgb\fP +These options determine the color space used in the JFIF output. +\fB-grayscale\fP (or \fB-greyscale\fP) means to create a gray scale +JFIF, converting from color PPM input if necessary. \fB-rgb\fP means to +create an RGB JFIF, and the program fails if the input is not PPM. +.sp +If you specify neither, The output file is in YCbCr format if the +input is PPM, and grayscale format if the input is PBM or PGM. +.sp +YCbCr format (a color is represented by an intensity value and two +chrominance values) usually compresses much better than RGB (a color +is represented by one red, one green, and one blue value). RGB is +rare. But you may be able to convert between JFIF and PPM faster with +RGB, since it's the same color space PPM uses. +.sp +The \fBtestimg.ppm\fP file that comes with Netpbm is 2.3 times +larger with the \fB-rgb\fP option than with the YCbCr default, and in +one experiment \fBpnmtojpeg\fP took 16% more CPU time to convert it. +The extra CPU time probably indicates that processing of all the extra +compressed data consumed all the CPU time saved by not having to +convert the RGB inputs to YCbCr. +.sp +Grayscale format takes up a lot less space and takes less time to create +and process than the color formats, even if the image contains nothing +but black, white, and gray. +.sp +The \fB-rgb\fP option was added in Netpbm 10.11 in October 2002. + +.TP +\fB-density=\fP\fIdensity\fP +This option determines the density (aka resolution) information +recorded in the JFIF output image. It does not affect the raster in +any way; it just tells whoever reads the JFIF how to interpret the +raster. +.sp +The density value takes the form \fIx\fP\fBx\fP\fIy\fP followed +by an optional unit specifier of \fBdpi\fP or \fBdpcm\fP. Examples: +\fB1x1\fP, \fB3x2\fP, \fB300x300dpi\fP, \fB100x200dpcm\fP. The +first number is the horizontal density; the 2nd number is the vertical +density. Each may be any integer from 1 to 65535. The unit specifier +is \fBdpi\fP for dots per inch or \fBdpcm\fP for dots per +centimeter. If you don't specify the units, the density information +goes into the JFIF explicitly stating "density unspecified" (also +interpreted as "unknown"). This may seem pointless, but note that +even without specifying the units, the density numbers tell the aspect +ratio of the pixels. E.g. \fB1x1\fP tells you the pixels are square. +\fB3x2\fP tells you the pixels are vertical rectangles. +.sp +Note that if you specify different horizontal and vertical +densities, the resulting JFIF image is \fInot\fP a true +representation of the input PNM image, because \fBpnmtojpeg\fP +converts the raster pixel-for-pixel and the pixels of a PNM image are +defined to be square. Thus, if you start with a square PNM image and +specify \fB-density=3x2\fP, the resulting JFIF image is a horizontally +squashed version of the original. However, it is common to use an +input image which is a slight variation on PNM rather than true PNM +such that the pixels are not square. In that case, the appropriate +-density option yields a faithful reproduction of the input pseudo-PNM +image. +.sp +The default is 1x1 in unspecified units. +.sp +Before Netpbm 10.15 (April 2003), this option did not exist and the +\fBpnmtojpeg\fP always created a JFIF with a density of 1x1 in +unspecified units. + +.TP +\fB-optimize\fP + Perform optimization of entropy encoding parameters. Without +this, \fBpnmtojpeg\fP uses default encoding parameters. +\fB-optimize\fP usually makes the JFIF file a little smaller, but +\fBpnmtojpeg\fP runs somewhat slower and needs much more memory. +Image quality and speed of decompression are unaffected by +\fB-optimize\fP. + +.TP +\fB-progressive\fP +Create a progressive JPEG file (see below). +.TP +\fB-comment=\fP\fItext\fP +Include a comment marker in the JFIF output, with comment text +\fItext\fP. + +Without this option, there are no comment markers in the output. + + +.PP +The \fB-quality\fP option lets you trade off compressed file size +against quality of the reconstructed image: the higher the quality +setting, the larger the JFIF file, and the closer the output image +will be to the original input. Normally you want to use the lowest +quality setting (smallest file) that decompresses into something +visually indistinguishable from the original image. For this purpose +the quality setting should be between 50 and 95 for reasonable +results; the default of 75 is often about right. If you see defects +at \fB-quality=75\fP, then go up 5 or 10 counts at a time until you +are happy with the output image. (The optimal setting will vary from +one image to another.) +.PP +\fB-quality=100\fP generates a quantization table of all 1's, +minimizing loss in the quantization step (but there is still +information loss in subsampling, as well as roundoff error). This +setting is of interest mainly for experimental purposes. Quality +values above about 95 are \fInot\fP recommended for normal use; the +compressed file size goes up dramatically for hardly any gain in +output image quality. +.PP +In the other direction, quality values below 50 will produce very +small files of low image quality. Settings around 5 to 10 might be +useful in preparing an index of a large image library, for example. +Try \fB-quality=2\fP (or so) for some amusing Cubist effects. (Note: +quality values below about 25 generate 2-byte quantization tables, +which are considered optional in the JFIF standard. \fBpnmtojpeg\fP +emits a warning message when you give such a quality value, because +some other JFIF programs may be unable to decode the resulting file. +Use \fB-baseline\fP if you need to ensure compatibility at low +quality values.) +.PP +The \fB-progressive\fP option creates a "progressive +JPEG" file. In this type of JFIF file, the data is stored in +multiple scans of increasing quality. If the file is being +transmitted over a slow communications link, the decoder can use the +first scan to display a low-quality image very quickly, and can then +improve the display with each subsequent scan. The final image is +exactly equivalent to a standard JFIF file of the same quality +setting, and the total file size is about the same -- often a little +smaller. +.PP +\fBCaution:\fP progressive JPEG is not yet widely +implemented, so many decoders will be unable to view a progressive +JPEG file at all. +.PP +If you're trying to control the quality/file size tradeoff, you +might consider the JPEG2000 format instead. See +.BR "pamtojpeg2k" (1)\c +\&. + +.UN advancedopts +.SS Advanced options + + + +.TP +\fB-dct=int\fP +Use integer DCT method (default). + +.TP +\fB-dct=fast\fP +Use fast integer DCT (less accurate). + +.TP +\fB-dct=float\fP +Use floating-point DCT method. The float method is very slightly +more accurate than the int method, but is much slower unless your +machine has very fast floating-point hardware. Also note that results +of the floating-point method may vary slightly across machines, while +the integer methods should give the same results everywhere. The fast +integer method is much less accurate than the other two. + +.TP +\fB-arithmetic\fP +Use arithmetic coding. Default is Huffman encoding. Arithmetic coding +tends to get you a smaller result. +.sp +You may need patent licenses to use this option. According to +.UR http://www.faqs.org/faqs/jpeg-faq +the JPEG FAQ +.UE +\&, +This method is covered by patents owned by IBM, AT&T, and Mitsubishi. +.sp +The author of the FAQ recommends against using arithmetic coding (and +therefore this option) because the space savings is not great enough to +justify the legal hassles. +.sp +Most JPEG libraries, including any distributed by the Independent +JPEG Group since about 1998 are not capable of arithmetic encoding. +\fBpnmtojpeg\fP uses a JPEG library (either bound to it when the +\fBpnmtojpeg\fP executable was built or accessed on your system at +run time) to do the JPEG encoding. If \fBpnmtojpeg\fP terminates +with the message, "Sorry, there are legal restrictions on +arithmetic coding" or "Sorry, arithmetic coding not +supported," this is the problem. + +.TP +\fB-restart=\fP\fIn\fP +Emit a JPEG restart marker every \fIn\fP MCU rows, or every \fIn\fP +MCU blocks if you append \fBB\fP to the number. \fB-restart 0\fP +(the default) means no restart markers. + +.TP +\fB-smooth=\fP\fIn\fP +Smooth the input image to eliminate dithering noise. \fIn\fP, +ranging from 1 to 100, indicates the strength of smoothing. 0 (the +default) means no smoothing. + +.TP +\fB-maxmemory=\fP\fIn\fP +Set a limit for amount of memory to use in processing large images. Value is +in thousands of bytes, or millions of bytes if you append +\fBM\fP to the number. For example, \fB-max=4m\fP +selects 4,000,000 bytes. If \fBpnmtojpeg\fP +needs more space, it will use temporary files. + +.TP +\fB-verbose\fP +Print to the Standard Error file messages about the conversion process. +This can be helpful in debugging problems. + +.PP +The \fB-restart\fP option tells \fBpnmtojpeg \fP to insert extra +markers that allow a JPEG decoder to resynchronize after a +transmission error. Without restart markers, any damage to a +compressed file will usually ruin the image from the point of the +error to the end of the image; with restart markers, the damage is +usually confined to the portion of the image up to the next restart +marker. Of course, the restart markers occupy extra space. We +recommend \fB-restart=1\fP for images that will be transmitted +across unreliable networks such as Usenet. +.PP +The \fB-smooth\fP option filters the input to eliminate +fine-scale noise. This is often useful when converting dithered +images to JFIF: a moderate smoothing factor of 10 to 50 gets rid of +dithering patterns in the input file, resulting in a smaller JFIF file +and a better-looking image. Too large a smoothing factor will visibly +blur the image, however. + +.UN wizardopts +.SS Wizard Options + + +.TP +\fB-baseline\fP +Force baseline-compatible quantization tables to be generated. +This clamps quantization values to 8 bits even at low quality +settings. (This switch is poorly named, since it does not ensure that +the output is actually baseline JPEG. For example, you can use +\fB-baseline\fP and \fB-progressive\fP together.) + +.TP +\fB-qtables=\fP\fIfilespec\fP +Use the quantization tables given in the specified text file. + +.TP +\fB-qslots=n[,...]\fP +Select which quantization table to use for each color component. + +.TP +\fB-sample=\fP\fIH\fP\fBx\fP\fIV\fP[,...] +Set JPEG sampling factors for each color component. + +.TP +\fB-scans=\fP\fIfilespec\fP +Use the scan script given in the specified text file. See below +for information on scan scripts. + +.TP +\fB-tracelevel=\fP\fIN\fP +This sets the level of debug tracing the program outputs as it runs. +0 means none, and is the default. This level primarily controls tracing +of the JPEG library, and you can get some pretty interesting information +about the compression process. + + +.PP +The "wizard" options are intended for experimentation +with JPEG. If you don't know what you are doing, \fBdon't use +them\fP. These switches are documented further in the file +wizard.doc that comes with the Independent JPEG Group's JPEG library. + +.UN examples +.SH EXAMPLES +.PP +This example compresses the PPM file foo.ppm with a quality factor +of 60 and saves the output as foo.jpg: + +.nf + \fBpnmtojpeg -quality=60 foo.ppm > foo.jpg\fP + +.fi +.PP +Here's a more typical example. It converts from BMP to JFIF: + +.nf + \fBcat foo.bmp | bmptoppm | pnmtojpeg > foo.jpg\fP + +.fi + +.UN loss +.SH JPEG LOSS +.PP +When you compress with JPEG, you lose information -- i.e. the resulting +image has somewhat lower quality than the original. This is a characteristic +of JPEG itself, not any particular program. So if you do the usual +Netpbm thing and convert from JFIF to PNM, manipulate, then convert back +to JFIF, you will lose quality. The more you do it, the more you lose. +Drawings (charts, cartoons, line drawings, and such with few colors +and sharp edges) suffer the most. +.PP +To avoid this, you can use a compressed image format other than +JPEG. PNG and JPEG2000 are good choices, and Netpbm contains converters +for those. +.PP +If you need to use JFIF on a drawing, you should experiment with +\fBpnmtojpeg\fP's \fB-quality\fP and \fB-smooth\fP options to get a +satisfactory conversion. \fB-smooth 10\fP or so is often helpful. +.PP +Because of the loss, you should do all the manipulation you have to +do on the image in some other format and convert to JFIF as the last +step. And if you can keep a copy in the original format, so much the +better. + +The \fB-optimize\fP option to \fBpnmtojpeg\fP is worth using when +you are making a "final" version for posting or archiving. +It's also a win when you are using low quality settings to make very +small JFIF files; the percentage improvement is often a lot more than +it is on larger files. (At present, \fB-optimize\fP mode is +automatically in effect when you generate a progressive JPEG file). +.PP +You can do flipping and rotating transformations losslessly with +the program \fBjpegtran\fP, which is packaged with the Independent +Jpeg Group's JPEG library. \fBjpegtran\fP exercises its intimate +knowledge of the way JPEG works to do the transformation without ever +actually decompressing the image. + +.UN otherprog +.SH OTHER PROGRAMS +.PP +Another program, \fBcjpeg\fP, is similar. \fBcjpeg\fP is +maintained by the Independent JPEG Group and packaged with the JPEG +library which \fBpnmtojpeg\fP uses for all its JPEG work. Because of +that, you may expect it to exploit more current JPEG features. Also, +since you have to have the library to run \fBpnmtojpeg\fP, but not +vice versa, \fBcjpeg\fP may be more commonly available. +.PP +On the other hand, \fBcjpeg\fP does not use the NetPBM libraries +to process its input, as all the NetPBM tools such as \fBpnmtojpeg\fP +do. This means it is less likely to be consistent with all the other +programs that deal with the NetPBM formats. Also, the command syntax +of \fBpnmtojpeg\fP is consistent with that of the other Netpbm tools, +unlike \fBcjpeg\fP. + +.UN scanscripts +.SH SCAN SCRIPTS +.PP +Use the \fB-scan\fP option to specify a scan script. Or use the +\fB-progressive\fP option to specify a particular built-in scan +script. +.PP +Just what a scan script is, and the basic format of the scan script +file, is covered in the \fBwizard.doc\fP file that comes with the +Independent JPEG Group's JPEG library. Scan scripts are same for +\fBpnmtojpeg\fP as the are for \fBcjpeg\fP. +.PP +This section contains additional information that isn't, but +probably should be, in that document. +.PP +First, there are many restrictions on what is a valid scan script. +The JPEG library, and thus \fBpnmtojpeg\fP, checks thoroughly for any +lack of compliance with these restrictions, but does little to tell +you how the script fails to comply. The messages are very general and +sometimes untrue. +.PP +To start with, the entries for the DC coefficient must come before any +entries for the AC coefficients. The DC coefficient is Coefficient 0; +all the other coefficients are AC coefficients. So in an entry for +the DC coefficient, the two numbers after the colon must be 0 and 0. +In an entry for AC coefficients, the first number after the colon must +not be 0. +.PP +In a DC entry, the color components must be in increasing order. +E.g. "0,2,1" before the colon is wrong. So is "0,0,0". +.PP +In an entry for an AC coefficient, you must specify only one color +component. I.e. there can be only one number before the colon. +.PP +In the first entry for a particular coefficient for a particular color +component, the "Ah" value must be zero, but the Al value can be any +valid bit number. In subsequent entries, Ah must be the Al value from +the previous entry (for that coefficient for that color component), +and the Al value must be one less than the Ah value. +.PP +The script must ultimately specify at least some of the DC coefficient +for every color component. Otherwise, you get the error message +"Script does not transmit all the data." You need not specify all of +the bits of the DC coefficient, or any of the AC coefficients. +.PP +There is a standard option in building the JPEG library to omit scan +script capability. If for some reason your library was built with +this option, you get the message "Requested feature was omitted at +compile time." + +.UN environment +.SH ENVIRONMENT + + +.TP +\fBJPEGMEM\fP +If this environment variable is set, its value is the default +memory limit. The value is specified as described for the +\fB-maxmemory\fP option. An explicit \fB-maxmemory \fP option +overrides any \fBJPEGMEM\fP. + + + +.UN seealso +.SH SEE ALSO +.BR "jpegtopnm" (1)\c +\&, +.BR "pnm" (1)\c +\&, +\fBcjpeg\fP man page, +\fBdjpeg\fP man page, +\fBjpegtran\fP man page, +\fBrdjpgcom\fP man page, +\fBwrjpgcom\fP man page +.PP +Wallace, Gregory K. "The JPEG Still Picture Compression +Standard", Communications of the ACM, April 1991 (vol. 34, +no. 4), pp. 30-44. + + +.UN author +.SH AUTHOR + +\fBpnmtojpeg\fP and this manual were derived in large part from +\fBcjpeg\fP, by the Independent JPEG Group. The program is otherwise +by Bryan Henderson on March 07, 2000. +.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/pnmtojpeg.html +.PP
\ No newline at end of file |