{ "mode": "man", "parameter": "pstopnm", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pstopnm/1/json", "generated": "2026-10-09T12:46:16Z", "synopsis": "", "sections": { "NAME": { "content": "pstopnm - convert a PostScript file to a PNM image\n\n", "subsections": [] }, "SYNOPSIS": { "content": "", "subsections": [ { "name": "pstopnm", "content": "[-stdout]\n\n[-forceplain]\n\n[-help]\n\n[-dpi=dpi]\n\n[-xsize=pixels] [-ysize=pixels]\n\n[-xborder=frac] [-yborder=frac] [-landscape]\n\n[-portrait]\n\n[-nocrop]\n\n[-pbm\n\n|-pgm\n\n|-ppm]\n\n[-llx=s] [-lly=s] [-urx=s] [-ury=s]\n\n[-verbose]\n\n[-xmax=pixels] [-ymax=pixels]\n\n[-textalphabits={1,2,4}]\n\n\npsfile[.ps]\n\n" } ] }, "OPTION USAGE": { "content": "Minimum unique abbreviation of option is acceptable. You may use double hyphens instead of\nsingle hyphen to denote options. You may use white space in place of the equals sign to sep‐\narate an option name from its value.\n\n", "subsections": [] }, "DESCRIPTION": { "content": "This program is part of Netpbm(1).\n\npstopnm reads a PostScript file as input and produces PBM, PGM, or PPM images as output.\nThis program simply uses GhostScript to render a PostScript file with its PNM device drivers.\nIf you don't have GhostScript installed or the version you have installed was not built with\nthe relevant PNM device drivers, pstopnm will fail. You can see if you have the proper envi‐\nronment by issuing the command gs --help . If it responds and lists under \"Available De‐\nvices\" pbm, pbmraw, pgm, pgmraw, pnm, pnmraw, ppm, or ppmraw, you're in business.\n\nIt's important to understand that pstopnm is a Netpbm image file format converter only in the\nbroadest sense of the word, because Postscript is far from an image file format. What\npstopnm really is is a Postscript renderer - an image generator. One place you'll notice the\ndifference is where you expect pstopnm | pnmtops to be idempotent (which is not the case).\nThere are details on this kind of conversion below.\n\npstopnm uses the value of the GHOSTSCRIPT environment variable as the file name for the\nGhostscript program. If GHOSTSCRIPT is not set, pstopnm searches your PATH for a regular\nfile named gs. If it doesn't find one, it assumes Ghostscript is in the file /usr/bin/gs.\n\npstopnm does not use the Netpbm libraries to generate the output files, so may not be en‐\ntirely consistent with most Netpbm programs.\n\npsfile[.ps] is the name of the input file. pstopnm will add the ps to the end of the name\nyou specify if no file exists by the exact name you specify, but one with .psadded does. For\nStandard Input, use - or just don't give any argument.\n\nIf you use the -stdout option or your input is from Standard Input, pstopnm outputs images\nof all the pages as a multi-image file to Standard Output. Otherwise, pstopnm creates one\nfile for each page in the Postscript input. The files are named as follows: If the input\nfile is named psfile.ps, the name of the files will be psfile001.ppm, psfile002.ppm, etc.\nThe filetype suffix is .ppm, .pgm, or .pbm, depending on which kind of output you choose with\nyour invocation options. If the input file name does not end in .ps, the whole file name is\nused in the output file name. For example, if the input file is named psfile.old, the output\nfile name is psfile.old001.ppm, etc.\n\nNote that the output file selection is inconsistent with most Netpbm programs, because it\ndoes not default to Standard Output. This is for historical reasons, based on the fact that\nthe Netpbm formats did not always provide for a sequence of images in a single file.\n\nWhen your input is from Standard Input, you may feed multiple Encapsulated Postscript docu‐\nments, one after another, and pstopnm converts every document and places it in the Standard\nOutput stream as an image. But if your input is from a named file, pstopnm expects the file\nto be an Encapsulated Postscript file, which means it contains only one Enapsulated Post‐\nscript document. If the file contains multiple concatenated documents, pstopnm ignores every\ndocument but the first. This distinction does not exist for non-EPSF Postscript input -\npstopnm generates an output image for each page of the input regardless of whether the input\nis from Standard Input or from a named file.\n\nNote that you can generate both kinds of files - concatenated EPSF and multi-page non-EPSF -\nwith pnmtops, selecting with the -setpage option.\n\nEach output image contains a rectangular area of the page to which it pertains. See the Di‐\nmensions section for details on what part of the input image goes into the output image and\nhow big it is in the output and what borders and margins are in the output image.\n\nIt has been reported that on some Postscript Version 1 input, Ghostscript, and therefore\npstopnm, produces no output. To solve this problem, you can convert the file to Postscript\nVersion 3 with the program ps2ps. It is reported that the program pstops does not work.\n\n", "subsections": [ { "name": "Dimensions", "content": "This section describes what part of the input image gets used in the output and the dimen‐\nsions of the output, including borders and background.\n\nNote that an output image is associated with a single input page.\n\npstopnm starts by taking a rectangular area from the input page. That is called the subject\nimage.\n\npstopnm may add borders to the subject image to form what is called the bordered subject im‐\nage.\n\npstopnm places the bordered subject image in the center of the output image and clips the\nedges as necessary to fit the computed output image size.\n\nThe location of the subject image in the Postscript input page is defined by four numbers,\nthe lower left corner and the upper right corner x and y coordinates. These coordinates are\nusually specified by the BoundingBox DSC statement (a Postscript comment) in the PostScript\nfile, but they can be overridden by the user by specifying one or more of the following op‐\ntions: -llx, -lly, -urx, and -ury.\n\nThe presence and thickness of a border to be added to the subject image to form the bordered\nsubject image is controlled by the options -xborder and -yborder. If pstopnm does not find a\nBoundingBox statement in the input, and you don't specify image area coordinates on the com‐\nmand line, pstopnm uses default values. If your input is from Standard Input, pstopnm does\nnot use the BoundingBox values (because of the technical difficulty of extracting that infor‐\nmation and still feeding the file to Ghostscript), so you either have to specify the image\narea coordinates or take the default.\n\nThe output image size is a confusing thing. In a Postscript file, things have spatial dimen‐\nsions. For example, a particular line may be 3 centimeters long. A Postscript printer is\nsupposed to print the line 3 centimeters long, using however many pixels that takes, without\nregard to how big the sheet of paper on which it is printing is. In a PNM image, by con‐\ntrast, there is no spatial dimension; there are only pixels. You might have a line that is\n100 pixels long, but the PNM image says nothing about how long that line should be on a\nprinted page.\n\npstopnm fills the role of a Postscript printer. The PNM image is a virtual printed page.\npstopnm must determine how many pixels it will use in the output image to represent an inch\nof input image, which is the \"output device resolution.\" Think of it as the number of dots\nper inch the virtual printer prints on the virtual page.\n\nThe simplest thing is for you to tell pstopnm exactly what output device resolution to use,\nusing the -dpi option. If you say for example -dpi=300 and the bordered subject image is 2\ninches by 3 inches, the PNM output will be 600 pixels by 900 pixels. Using this method, the\noutput device resolution has to be the same in both directions.\n\nOr you can set the output image dimensions with -xsize and -ysize. For example, if you say" }, { "name": "-xsize=1200 -ysize=1800", "content": "output image is 1200 by 1800 pixels, with each pixel representing 1/600 inch of input image.\n\nIn the unlikely event that you want different output device resolutions in the two direc‐\ntions, you could use -xsize and -ysize to do that. In the above example, if you change" }, { "name": "-ysize", "content": "If you specify one of -xsize and -ysize and not the other, pstopnm defaults the other such\nthat the output device resolution is the same in both directions.\n\nThe \"x\" and \"y\" of -xsize and -ysize refer to the image being printed on the page, not the\npage. So if pstopnm prints it in landscape orientation, \"x\" would pertain to the vertical\ndirection on the page, i.e. the vertical direction in the output PNM image.\n\nIf you specify neither the output size nor the output device resolution, pstopnm does some\nweird computation which exists mainly for historical reasons:\n\nIf you specify -nocrop, pstopnm uses the values of -xmax and -ymax for the output image di‐\nmensions. These default to 612 and 792 pixels, respectively.\n\nThe final case, the default, is where you don't specify any size or resolution options or" }, { "name": "-nocrop", "content": "device resolution that would generate the number of pixels indicated by -xmax and -ymax from\nthe bordered subject image. Then, based on that resolution, it chooses an output image size\nthat is just large enough to accommodate the subject image (no borders). Remember (above)\nthat pstopnm trims the edges of the bordered subject image to fit the computed output size.\n\n\n" }, { "name": "Ghostscript Limitations", "content": "Tests done in 2013 with Ghostscript 8.71 indicate that Ghostscript's pgmraw output driver has\nsome kind of rounding error that causes the pixel values to change slightly, and that means\npstopnm generates incorrect output when you have monochrome Postscript input. But with color\nPostscript input, pstopnm uses Ghostscript's ppmraw output driver and generates correct PPM\noutput.\n\n\n" }, { "name": "Usage Notes", "content": "There is some good advice on converting to and from Postscript, in the document Postcript\nFile Conversions\" (1) by Andrew T. Young.\n" }, { "name": "Reversible Conversion", "content": "If you're trying to do the equivalent of the naive pnmtops | pstopnm, the following steps\nwill do it.\n\n$ pnmtops -nocenter -equalpixels -dpi 72 -noturn testimg.ppm > testimg.ps\n$ pstopnm -xborder=0 -yborder=0 -xsize=XSIZE -ysize=YSIZE \\\n-portrait -stdout -quiet testimg.ps >testimg2.ppm\n\n\nXSIZE and YSIZE above are the image dimensions, which you can get from testimg.ps like in the\nfollowing example (the grep, awk and echo commands are just to help demonstrate how the other\ncommands work - you wouldn't use those in a program).\n\n$ grep \"BoundingBox\" testimg.ps\n%%BoundingBox: 0 0 227 149\n\n$ awk '/%%BoundingBox/ {print $4,$5}' testimg.ps\n227 149\n\n$ xysize=$(awk '/%%BoundingBox/ {print \"-xsize=\"$4,\"-ysize=\"$5}' testimg.ps)\n$ echo $xysize\n\n-xsize=227 -ysize=149\n\n$ pstopnm -xborder=0 -yborder=0 $xysize -portrait ... testimg.ps\n\n\nNote that Ghostscript bugs can keep this from doing a perfect reversible conversion.\n\n\n" } ] }, "OPTIONS": { "content": "In addition to the options common to all programs based on libnetpbm (most notably -quiet,\nsee Common Options ), pstopnm recognizes the following command line options:\n\n\n", "subsections": [ { "name": "-forceplain", "content": "forces the output file to be in plain (text) format. Otherwise, it is in raw (bi‐\nnary) format. See pbm(1), etc. Use this instead of the -plain common option if you\nneed plain format output.\n\n" }, { "name": "-llx=_", "content": "selects bx as the lower left corner x coordinate (in inches) on the Postscript input\npage of the subject image. See the Dimensions section .\n\n" }, { "name": "-lly=_", "content": "selects by as the lower left corner y coordinate (in inches) on the Postscript input\npage of the subject image. See the Dimensions section .\n\n" }, { "name": "-landscape", "content": "renders the image in landscape orientation.\n\nIf you specify neither -portrait nor -landscape, pstopnm chooses the orientation that\nbest fits the image on the output page.\n\nLandscape means printed sideways on the page, not printed the long way. Those are\ndifferent things if the long edge of the page is the top one.\n\n" }, { "name": "-portrait", "content": "renders the image in portrait orientation.\n\nSee -landscape.\n\n" }, { "name": "-nocrop", "content": "This option causes pstopnm to make the output image exactly the dimensions of the bor‐\ndered subject image. By default, pstopnm makes the output image the dimensions speci‐\nfied by -xmax and -ymax. See the Dimensions section .\n\n" }, { "name": "-pbm", "content": "" }, { "name": "-pgm", "content": "" }, { "name": "-ppm", "content": "" }, { "name": "-stdout", "content": "causes output to go to Standard Output instead of to regular files, one per page (see\ndescription of output files above). Use pnmsplit to extract individual pages from\nStandard Output.\n\n" }, { "name": "-urx=_", "content": "selects tx as the upper right corner x coordinate (in inches) on the Postscript input\npage of the subject image. See the Dimensions section .\n\n" }, { "name": "-ury=_", "content": "selects ty as the upper right corner y coordinate (in inches) on the Postscript input\npage of the subject image. See the Dimensions section .\n\n\n" }, { "name": "-verbose", "content": "prints processing information to stdout.\n\n" }, { "name": "-xborder=_", "content": "specifies that the left and right borders added to the subject image are to be frac\ntimes the subject image width. The default value is 0.1. See the Dimensions section\n.\n\n\n" }, { "name": "-xmax=_", "content": "specifies that the output image is to be xmax pixels wide. The default is 612. See\nthe Dimensions section .\n\n\n" }, { "name": "-xsize=_", "content": "specifies that the output image is to be xsize pixels wide. See the Dimensions sec‐\ntion .\n\n" }, { "name": "-yborder=_", "content": "specifies that the top and bottom borders added to the subject image are to be frac\ntimes the subject image height. The default value is 0.1. See the Dimensions section\n.\n\n\n" }, { "name": "-ymax=_", "content": "specifies that the output image is to be ymax pixels high. The default is 792. See\nthe Dimensions section .\n\n" }, { "name": "-ysize=_", "content": "specifies that the output image is to be ymax pixels high. See the Dimensions section\n.\n\n" }, { "name": "-dpi=_", "content": "specifies the output device resolution, in dots per inch, of the Postscript printer\nthat pstopnm simulates. This is the number of PNM pixels pstopnm generates for each\ninch of image. See the Dimensions section .\n\nThis option was new in Netpbm 10.21 (March 2004).\n\n" }, { "name": "-textalphabits=", "content": "This controls subsample antialiasing of text. Antialiasing is a form of smoothing\nthat eliminates jagged edges on characters. Subsample antialiasing is a kind of an‐\ntialiasing that uses subpixels in a box, and the value of this option is the size of\nthat box. 4 gives you the best looking output, while 1 causes no antialiasing.\nSmaller numbers make pnmtops use less CPU time.\n\nPstopnm uses Ghostscript's TextAlphaBits parameter for this.\n\nThe default is 4.\n\nThis option was new in Netpbm 10.53 (December 2010). Older versions of pstopnm do no\nantialiasing.\n\n\n\n\n" } ] }, "LIMITATIONS": { "content": "The program will produce incorrect results with PostScript files that initialize the current\ntransformation matrix. In these cases, page translation and rotation will not have any ef‐\nfect. To render these files, probably the best bet is to use the following options:\n\npstopnm -xborder 0 -yborder 0 -portrait -nocrop file.ps\n\n\nAdditional options may be needed if the document is supposed to be rendered on a medium dif‐\nferent from letter-size paper.\n\n", "subsections": [] }, "SEE ALSO": { "content": "gs, pnmtops(1), psidtopgm(1), pbmtolps(1), pbmtoepsi(1), pnmsplit(1), pstofits\n\n\n\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright (c) 1992 Smithsonian Astrophysical Observatory\n\nPostScript is a Trademark of Adobe Systems Incorporated.\n\n\n", "subsections": [] }, "AUTHOR": { "content": "Alberto Accomazzi, WIPL, Center for Astrophysics.\n", "subsections": [] }, "DOCUMENT SOURCE": { "content": "This manual page was generated by the Netpbm tool 'makeman' from HTML source. The master\ndocumentation is at\n\nhttp://netpbm.sourceforge.net/doc/pstopnm.html\n\nnetpbm documentation 06 December 2013 Pstopnm User Manual(1)", "subsections": [] } }, "summary": "pstopnm - convert a PostScript file to a PNM image", "flags": [ { "flag": "", "long": null, "arg": null, "description": "forces the output file to be in plain (text) format. Otherwise, it is in raw (bi‐ nary) format. See pbm(1), etc. Use this instead of the -plain common option if you need plain format output." }, { "flag": "", "long": null, "arg": null, "description": "selects bx as the lower left corner x coordinate (in inches) on the Postscript input page of the subject image. See the Dimensions section ." }, { "flag": "", "long": null, "arg": null, "description": "selects by as the lower left corner y coordinate (in inches) on the Postscript input page of the subject image. See the Dimensions section ." }, { "flag": "", "long": null, "arg": null, "description": "renders the image in landscape orientation. If you specify neither -portrait nor -landscape, pstopnm chooses the orientation that best fits the image on the output page. 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." }, { "flag": "", "long": null, "arg": null, "description": "renders the image in portrait orientation. See -landscape." }, { "flag": "", "long": null, "arg": null, "description": "This option causes pstopnm to make the output image exactly the dimensions of the bor‐ dered subject image. By default, pstopnm makes the output image the dimensions speci‐ fied by -xmax and -ymax. See the Dimensions section ." }, { "flag": "", "long": null, "arg": null, "description": "" }, { "flag": "", "long": null, "arg": null, "description": "" }, { "flag": "", "long": null, "arg": null, "description": "" }, { "flag": "", "long": null, "arg": null, "description": "causes output to go to Standard Output instead of to regular files, one per page (see description of output files above). Use pnmsplit to extract individual pages from Standard Output." }, { "flag": "", "long": null, "arg": null, "description": "selects tx as the upper right corner x coordinate (in inches) on the Postscript input page of the subject image. See the Dimensions section ." }, { "flag": "", "long": null, "arg": null, "description": "selects ty as the upper right corner y coordinate (in inches) on the Postscript input page of the subject image. See the Dimensions section ." }, { "flag": "", "long": null, "arg": null, "description": "prints processing information to stdout." }, { "flag": "", "long": null, "arg": null, "description": "specifies that the left and right borders added to the subject image are to be frac times the subject image width. The default value is 0.1. See the Dimensions section ." }, { "flag": "", "long": null, "arg": null, "description": "specifies that the output image is to be xmax pixels wide. The default is 612. See the Dimensions section ." }, { "flag": "", "long": null, "arg": null, "description": "specifies that the output image is to be xsize pixels wide. See the Dimensions sec‐ tion ." }, { "flag": "", "long": null, "arg": null, "description": "specifies that the top and bottom borders added to the subject image are to be frac times the subject image height. The default value is 0.1. See the Dimensions section ." }, { "flag": "", "long": null, "arg": null, "description": "specifies that the output image is to be ymax pixels high. The default is 792. See the Dimensions section ." }, { "flag": "", "long": null, "arg": null, "description": "specifies that the output image is to be ymax pixels high. See the Dimensions section ." }, { "flag": "", "long": null, "arg": null, "description": "specifies the output device resolution, in dots per inch, of the Postscript printer that pstopnm simulates. This is the number of PNM pixels pstopnm generates for each inch of image. See the Dimensions section . This option was new in Netpbm 10.21 (March 2004)." }, { "flag": "", "long": null, "arg": null, "description": "This controls subsample antialiasing of text. Antialiasing is a form of smoothing that eliminates jagged edges on characters. Subsample antialiasing is a kind of an‐ tialiasing 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 pnmtops use less CPU time. Pstopnm uses Ghostscript's TextAlphaBits parameter for this. The default is 4. This option was new in Netpbm 10.53 (December 2010). Older versions of pstopnm do no antialiasing." } ], "examples": [], "see_also": [ { "name": "pnmtops", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pnmtops/1/json" }, { "name": "psidtopgm", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/psidtopgm/1/json" }, { "name": "pbmtolps", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pbmtolps/1/json" }, { "name": "pbmtoepsi", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pbmtoepsi/1/json" }, { "name": "pnmsplit", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pnmsplit/1/json" } ], "tldr": { "source": "official", "description": "Convert a PostScript file to a PNM image.", "examples": [ { "description": "Convert a PS file to PNM images, storing page N of the input to `path/to/fileN.ppm`", "command": "pstopnm {{path/to/file.ps}}" }, { "description": "Explicitly specify the output format", "command": "pstopnm -{{pbm|pgm|ppm}} {{path/to/file.ps}}" }, { "description": "Specify the resolution of the output in dots per inch", "command": "pstopnm -dpi {{n}} {{path/to/file.ps}}" } ] } }