diff options
Diffstat (limited to 'upstream/fedora-40/man1/pstopnm.1')
| -rw-r--r-- | upstream/fedora-40/man1/pstopnm.1 | 562 |
1 files changed, 562 insertions, 0 deletions
diff --git a/upstream/fedora-40/man1/pstopnm.1 b/upstream/fedora-40/man1/pstopnm.1 new file mode 100644 index 00000000..17e695e7 --- /dev/null +++ b/upstream/fedora-40/man1/pstopnm.1 @@ -0,0 +1,562 @@ +\ +.\" 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 "Pstopnm User Manual" 0 "06 December 2013" "netpbm documentation" + +.SH NAME +pstopnm - convert a PostScript file to a PNM image + +.UN synopsis +.SH SYNOPSIS + +\fBpstopnm\fP + +[\fB-stdout\fP] + +[\fB-forceplain\fP] + +[\fB-help\fP] + +[\fB-dpi=\fP\fIdpi\fP] + +[\fB-xsize=\fP\fIpixels\fP] +[\fB-ysize=\fP\fIpixels\fP] + +[\fB-xborder=\fP\fIfrac\fP] +[\fB-yborder=\fP\fIfrac\fP] +[\fB-landscape\fP] + +[\fB-portrait\fP] + +[\fB-nocrop\fP] + +[\fB-pbm\fP + +|\fB-pgm\fP + +|\fB-ppm\fP] + +[\fB-llx=\fP\fIs\fP] +[\fB-lly=\fP\fIs\fP] +[\fB-urx=\fP\fIs\fP] +[\fB-ury=\fP\fIs\fP] + +[\fB-verbose\fP] + +[\fB-xmax=\fP\fIpixels\fP] +[\fB-ymax=\fP\fIpixels\fP] + +[\fB-textalphabits=\fP{\fB1\fP,\fB2\fP,\fB4\fP}] + + +\fIpsfile\fP[\fB.ps\fP] + +.SH OPTION USAGE +.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 +\fBpstopnm\fP reads a PostScript file as input and produces PBM, +PGM, or PPM images as output. This program simply uses GhostScript to +render a PostScript file with its PNM device drivers. If you don't +have GhostScript installed or the version you have installed was not +built with the relevant PNM device drivers, \fBpstopnm\fP will fail. +You can see if you have the proper environment by issuing the command +\f(CWgs --help \fP. If it responds and lists under "Available +Devices" \fBpbm\fP, \fBpbmraw\fP, \fBpgm\fP, \fBpgmraw\fP, +\fBpnm\fP, \fBpnmraw\fP, \fBppm\fP, or \fBppmraw\fP, you're in +business. +.PP +It's important to understand that \fBpstopnm\fP is a Netpbm image file +format converter only in the broadest sense of the word, because Postscript is +far from an image file format. What \fBpstopnm\fP really is is a Postscript +renderer - an image generator. One place you'll notice the difference is +where you expect \f(CWpstopnm | pnmtops\fP to be idempotent (which is not +the case). There are details on this kind of conversion below. +.PP +\fBpstopnm\fP uses the value of the \fBGHOSTSCRIPT\fP +environment variable as the file name for the Ghostscript program. If +\fBGHOSTSCRIPT\fP is not set, \fBpstopnm\fP searches your +\fBPATH\fP for a regular file named \fBgs\fP. If it doesn't find +one, it assumes Ghostscript is in the file \fB/usr/bin/gs\fP. +.PP +\fBpstopnm\fP does not use the Netpbm libraries to generate the +output files, so may not be entirely consistent with most Netpbm +programs. +.PP +\fIpsfile\fP[\fB.ps\fP] is the name of the input file. +\fBpstopnm\fP will add the \fBps\fP to the end of the name you specify if no +file exists by the exact name you specify, but one with \fB.ps\fPadded does. +For Standard Input, use \fB-\fP or just don't give any argument. +.PP +If you use the \fB-stdout \fP option or your input is from Standard +Input, \fBpstopnm\fP outputs images of all the pages as a multi-image file to +Standard Output. Otherwise, \fBpstopnm\fP creates one file for each page in +the Postscript input. The files are named as follows: If the input file is +named \fBpsfile.ps\fP, the name of the files will be +\fBpsfile001.ppm\fP, \fBpsfile002.ppm\fP, etc. The filetype suffix +is \fB.ppm\fP, \fB.pgm\fP, or \fB.pbm\fP, depending on which kind +of output you choose with your invocation options. If the input file +name does not end in \fB.ps\fP, the whole file name is used in the +output file name. For example, if the input file is named +\fBpsfile.old\fP, the output file name is \fBpsfile.old001.ppm\fP, +etc. +.PP +Note that the output file selection is inconsistent with most +Netpbm programs, because it does not default to Standard Output. This +is for historical reasons, based on the fact that the Netpbm formats +did not always provide for a sequence of images in a single file. +.PP +When your input is from Standard Input, you may feed multiple Encapsulated +Postscript documents, one after another, and \fBpstopnm\fP converts every +document and places it in the Standard Output stream as an image. But if your +input is from a named file, \fBpstopnm\fP expects the file to be an +Encapsulated Postscript file, which means it contains only one Enapsulated +Postscript document. If the file contains multiple concatenated +documents, \fBpstopnm\fP ignores every document but the first. This +distinction does not exist for non-EPSF Postscript input +- \fBpstopnm\fP generates an output image for each page of the input +regardless of whether the input is from Standard Input or from a named file. +.PP +Note that you can generate both kinds of files - concatenated EPSF +and multi-page non-EPSF - with \fBpnmtops\fP, selecting with the +\fB-setpage\fP option. +.PP +Each output image contains a rectangular area of the page to which +it pertains. See +.UR #dimensions +the Dimensions section +.UE +\& for +details on what part of the input image goes into the output image and +how big it is in the output and what borders and margins are in the +output image. +.PP +It has been reported that on some Postscript Version 1 input, +Ghostscript, and therefore \fBpstopnm\fP, produces no output. To +solve this problem, you can convert the file to Postscript Version 3 +with the program \fBps2ps\fP. It is reported that the program +\fBpstops\fP does not work. + +.UN dimensions +.SS Dimensions +.PP +This section describes what part of the input image gets used in +the output and the dimensions of the output, including borders and +background. +.PP +Note that an output image is associated with a single input page. + +\fBpstopnm\fP starts by taking a rectangular area from the input page. +That is called the subject image. +.PP +\fBpstopnm\fP may add borders to the subject image to form what is called +the bordered subject image. +.PP +\fBpstopnm\fP places the bordered subject image in the center of +the output image and clips the edges as necessary to fit the computed +output image size. +.PP +The location of the subject image in the Postscript input page is +defined by four numbers, the lower left corner and the upper right +corner x and y coordinates. These coordinates are usually specified +by the BoundingBox DSC statement (a Postscript comment) in the +PostScript file, but they can be overridden by the user by specifying +one or more of the following options: \fB-llx\fP, \fB-lly\fP, +\fB-urx\fP, and \fB-ury\fP. +.PP +The presence and thickness of a border to be added to the subject +image to form the bordered subject image is controlled by the options +\fB-xborder\fP and \fB-yborder\fP. If \fBpstopnm\fP does not find +a BoundingBox statement in the input, and you don't specify image area +coordinates on the command line, \fBpstopnm\fP uses default values. +If your input is from Standard Input, \fBpstopnm\fP does not use the +BoundingBox values (because of the technical difficulty of extracting that +information and still feeding the file to Ghostscript), so you either +have to specify the image area coordinates or take the default. +.PP +The output image size is a confusing thing. In a Postscript file, +things have spatial dimensions. For example, a particular line may be +3 centimeters long. A Postscript printer is supposed to print the +line 3 centimeters long, using however many pixels that takes, without +regard to how big the sheet of paper on which it is printing is. In a +PNM image, by contrast, there is no spatial dimension; there are only +pixels. You might have a line that is 100 pixels long, but the PNM +image says nothing about how long that line should be on a printed +page. +.PP +\fBpstopnm\fP fills the role of a Postscript printer. The PNM image +is a virtual printed page. \fBpstopnm\fP must determine how many pixels +it will use in the output image to represent an inch of input image, +which is the "output device resolution." Think of it as the number of +dots per inch the virtual printer prints on the virtual page. +.PP +The simplest thing is for you to tell \fBpstopnm\fP exactly what +output device resolution to use, using the \fB-dpi\fP option. If you +say for example \fB-dpi=300\fP and the bordered subject image is 2 +inches by 3 inches, the PNM output will be 600 pixels by 900 pixels. +Using this method, the output device resolution has to be the same in +both directions. +.PP +Or you can set the output image dimensions with \fB-xsize\fP and +\fB-ysize\fP. For example, if you say \fB-xsize=1200 -ysize=1800\fP and the +bordered subject image is 2 inches wide by 3 inches high, the output image is +1200 by 1800 pixels, with each pixel representing 1/600 inch of input image. +.PP +In the unlikely event that you want different output device resolutions in +the two directions, you could use \fB-xsize\fP and \fB-ysize\fP to do that. +In the above example, if you change \fB-ysize\fP to 900, a pixel still +represents 1/600 inch horizontally, but 1/300 inch vertically. +.PP +If you specify one of \fB-xsize\fP and \fB-ysize\fP and not the +other, \fBpstopnm\fP defaults the other such that the output device +resolution is the same in both directions. +.PP +The "x" and "y" of \fB-xsize\fP and \fB-ysize\fP +refer to the image being printed on the page, not the page. So if +\fBpstopnm\fP prints it in landscape orientation, "x" would pertain +to the vertical direction on the page, i.e. the vertical direction in the +output PNM image. +.PP +If you specify neither the output size nor the output device +resolution, \fBpstopnm\fP does some weird computation which exists +mainly for historical reasons: +.PP +If you specify \fB-nocrop\fP, \fBpstopnm\fP uses the values of +\fB-xmax\fP and \fB-ymax\fP for the output image dimensions. These +default to 612 and 792 pixels, respectively. +.PP +The final case, the default, is where you don't specify any size or +resolution options or \fB-nocrop\fP. This is the most complicated +case. In this case, \fBpstopnm\fP first chooses an output device +resolution that would generate the number of pixels indicated by +\fB-xmax\fP and \fB-ymax\fP from the bordered subject image. Then, +based on that resolution, it chooses an output image size that is just +large enough to accommodate the subject image (no borders). Remember +(above) that \fBpstopnm\fP trims the edges of the bordered subject +image to fit the computed output size. + + +.UN gslimitations +.SS Ghostscript Limitations +.PP +Tests done in 2013 with Ghostscript 8.71 indicate that Ghostscript's +\fBpgmraw\fP output driver has some kind of rounding error that causes the +pixel values to change slightly, and that means \fBpstopnm\fP generates +incorrect output when you have monochrome Postscript input. But with color +Postscript input, \fBpstopnm\fP uses Ghostscript's \fBppmraw\fP output +driver and generates correct PPM output. + + +.UN usagenotes +.SS Usage Notes +.PP +There is some good advice on converting to and from Postscript, in the +document +.BR " +Postcript File Conversions" (1)\c +\& by Andrew T. Young. + +.UN reversible +.B Reversible Conversion +.PP +If you're trying to do the equivalent of the naive +\f(CWpnmtops | pstopnm\fP, the following steps will do it. + +.nf +\f(CW + $ pnmtops -nocenter -equalpixels -dpi 72 -noturn testimg.ppm > testimg.ps + $ pstopnm -xborder=0 -yborder=0 -xsize=\fIXSIZE\fP -ysize=\fIYSIZE\fP \e + -portrait -stdout -quiet testimg.ps >testimg2.ppm +\fP + +.fi + +\fIXSIZE\fP and \fIYSIZE\fP above are the image dimensions, which you can +get from testimg.ps like in the following example (the grep, awk and echo +commands are just to help demonstrate how the other commands work - you +wouldn't use those in a program). + +.nf +\f(CW + $ grep "BoundingBox" testimg.ps + %%BoundingBox: 0 0 227 149 + + $ awk '/%%BoundingBox/ {print $4,$5}' testimg.ps + 227 149 + + $ xysize=$(awk '/%%BoundingBox/ {print "-xsize="$4,"-ysize="$5}' testimg.ps) + $ echo $xysize + + -xsize=227 -ysize=149 + + $ pstopnm -xborder=0 -yborder=0 $xysize -portrait ... testimg.ps +\fP + +.fi +.PP +Note that Ghostscript bugs can keep this from doing a perfect +reversible 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 +\&), \fBpstopnm\fP recognizes the following +command line options: + + +.TP +\fB-forceplain\fP + forces the output file to be in plain (text) format. Otherwise, +it is in raw (binary) format. See +.BR "pbm" (1)\c +\&, +etc. Use this instead of the \fB-plain\fP common option if you need +plain format output. + +.TP +\fB-llx=\fP\fIbx\fP +selects \fIbx\fP as the lower left corner x coordinate (in +inches) on the Postscript input page of the subject image. +See +.UR #dimensions +the Dimensions section +.UE +\&. + +.TP +\fB-lly=\fP\fIby\fP +selects \fIby\fP as the lower left corner y coordinate (in inches) +on the Postscript input page of the subject image. +See +.UR #dimensions +the Dimensions section +.UE +\&. + +.TP +\fB-landscape\fP +renders the image in landscape orientation. +.sp +If you specify neither \fB-portrait\fP nor \fB-landscape\fP, +\fBpstopnm\fP chooses the orientation that best fits the image on the +output page. +.sp +Landscape means printed sideways on the page, not printed the long way. +Those are different things if the long edge of the page is the top one. + +.TP +\fB-portrait\fP +renders the image in portrait orientation. +.sp +See \fB-landscape\fP. + +.TP +\fB-nocrop\fP +This option causes \fBpstopnm\fP to make the output image +exactly the dimensions of the bordered subject image. By default, +\fBpstopnm\fP makes the output image the dimensions specified by +\fB-xmax\fP and \fB-ymax\fP. See +.UR #dimensions +the Dimensions section +.UE +\&. + +.TP +\fB-pbm\fP +.TP +\fB-pgm\fP +.TP +\fB-ppm\fP +selects the format of the output file. By default, all files are +rendered as PPM. + +.TP +\fB-stdout\fP +causes output to go to Standard Output instead of to regular +files, one per page (see description of output files above). Use +\fBpnmsplit\fP to extract individual pages from Standard Output. + +.TP +\fB-urx=\fP\fItx\fP +selects \fItx\fP as the upper right corner x coordinate (in +inches) on the Postscript input page of the subject image. See +.UR #dimensions +the Dimensions section +.UE +\&. + +.TP +\fB-ury=\fP\fIty\fP +selects \fIty\fP as the upper right corner y coordinate (in +inches) on the Postscript input page of the subject image. See +.UR #dimensions +the Dimensions section +.UE +\&. + + +.TP +\fB-verbose\fP +prints processing information to stdout. + +.TP +\fB-xborder=\fP\fIfrac\fP +specifies that the left and right borders added to the subject +image are to be \fIfrac\fP times the subject image width. The +default value is 0.1. See +.UR #dimensions +the Dimensions section +.UE +\&. + + +.TP +\fB-xmax=\fP\fIxmax\fP +specifies that the output image is to be \fIxmax\fP pixels wide. +The default is 612. See +.UR #dimensions +the Dimensions section +.UE +\&. + + +.TP +\fB-xsize=\fP\fIxsize\fP +specifies that the output image is to be \fIxsize\fP pixels wide. +See +.UR #dimensions +the Dimensions section +.UE +\&. + +.TP +\fB-yborder=\fP\fIfrac\fP +specifies that the top and bottom borders added to the subject +image are to be \fIfrac\fP times the subject image height. The +default value is 0.1. See +.UR #dimensions +the Dimensions section +.UE +\&. + + +.TP +\fB-ymax=\fP\fIymax\fP +specifies that the output image is to be \fIymax\fP pixels high. +The default is 792. See +.UR #dimensions +the Dimensions section +.UE +\&. + +.TP +\fB-ysize=\fP\fIysize\fP +specifies that the output image is to be \fIymax\fP pixels high. +See +.UR #dimensions +the Dimensions section +.UE +\&. + +.TP +\fB-dpi=\fP\fIdpi\fP +specifies the output device resolution, in dots per inch, of the +Postscript printer that \fBpstopnm\fP simulates. This is the number of +PNM pixels \fBpstopnm\fP generates for each inch of image. +See +.UR #dimensions +the Dimensions section +.UE +\&. +.sp +This option was new in Netpbm 10.21 (March 2004). + +.TP +\fB-textalphabits=\fP{\fB1\fP,\fB2\fP,\fB4\fP} +This controls subsample antialiasing of text. Antialiasing is a form of +smoothing that eliminates jagged edges on characters. Subsample antialiasing +is a kind of antialiasing that uses subpixels in a box, and the value of this +option is the size of that box. 4 gives you the best looking output, while 1 +causes no antialiasing. Smaller numbers make \fBpnmtops\fP use less CPU +time. +.sp +Pstopnm uses Ghostscript's \fBTextAlphaBits\fP parameter for this. +.sp +The default is 4. +.sp +This option was new in Netpbm 10.53 (December 2010). Older versions of +\fBpstopnm\fP do no antialiasing. + + + + +.UN limitations +.SH LIMITATIONS +.PP +The program will produce incorrect results with PostScript files that +initialize the current transformation matrix. In these cases, page +translation and rotation will not have any effect. To render these +files, probably the best bet is to use the following options: + +.nf + pstopnm -xborder 0 -yborder 0 -portrait -nocrop file.ps + +.fi +.PP +Additional options may be needed if the document is supposed to be +rendered on a medium different from letter-size paper. + +.UN seealso +.SH SEE ALSO + +\fBgs\fP, +.BR "pnmtops" (1)\c +\&, +.BR "psidtopgm" (1)\c +\&, +.BR "pbmtolps" (1)\c +\&, +.BR "pbmtoepsi" (1)\c +\&, +.BR "pnmsplit" (1)\c +\&, +\fBpstofits\fP + + + +.UN copyright +.SH COPYRIGHT +.PP +Copyright (c) 1992 Smithsonian Astrophysical Observatory +.PP +PostScript is a Trademark of Adobe Systems Incorporated. + + +.UN author +.SH AUTHOR +.PP +Alberto Accomazzi, WIPL, Center for Astrophysics. +.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/pstopnm.html +.PP
\ No newline at end of file |