PSTOPNM(1)

📦
version 11.13.03 · 6 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💅 Pstopnm User Manual — the pstopnm era 💅

okay bestie, sit down, hydrate, because we're about to talk about pstopnm, and she is lowkey iconic. she lives in the General Commands Manual section, she's a whole User Manual, and she does exactly one thing but she does it gorgeously. no cap. 🦋

✨ NAME ✨

pstopnm — convert a PostScript file to a PNM image

like. that's it. that's her job. PostScript in, PNM out. main character energy fr fr 👑

🌸 SYNOPSIS 🌸

pstopnm

[-stdout]

[-forceplain]

[-help]

[-dpi=dpi]

[-xsize=pixels] [-ysize=pixels]

[-xborder=frac] [-yborder=frac] [-landscape]

[-portrait]

[-nocrop]

[-pbm

|-pgm

|-ppm]

[-llx=s] [-lly=s] [-urx=s] [-ury=s]

[-verbose]

[-xmax=pixels] [-ymax=pixels]

[-textalphabits={1,2,4}]

psfile[.ps]

okay so you run pstopnm, you throw a bunch of flag options at it (or don't, she's not needy 💖), and then you hand her psfile[.ps] — that's your PostScript file, and yes the .ps part can literally be implied, the way she just knows what you meant. she's like that. 🙈

just look at that flag list. so many options. so many little knobs to turn. it's giving choose-your-own-adventure but make it raster graphics. ✨

🎀 OPTION USAGE 🎀

okay this part is short but IMPORTANT, so listen up:

  • Minimum unique abbreviation of option is acceptable. you don't have to spell the whole thing out — just enough letters that it's ✨ unambiguous ✨. she's flexible like that. 💅
  • You may use double hyphens instead of single hyphen to denote options. one dash, two dashes, she does not care, she is not going to fight you about it. -verbose and --verbose are the same vibe here.
  • You may use white space in place of the equals sign to separate an option name from its value. so like, the = in -dpi=dpi is a suggestion, not a personality. space works too. slay. 🫶
bestie note: an abbreviation has to stay unique to count — go too short and she genuinely cannot tell what you meant, and then it's awkward for everyone. 😭

more coming, don't go anywhere 💜

💅 DESCRIPTION 💅

So like, first things first: this program is part of Netpbm(1). Family reunion energy. 🫶

pstopnm reads a PostScript or PDF file as input and spits out PBM, PGM, or PPM images. That's the whole vibe. What it's actually doing behind the curtain is just using GhostScript to render the PostScript with its PNM device drivers. So real talk: if you don't have GhostScript installed, or the version you have wasn't built with the relevant PNM device drivers, pstopnm will straight-up fail. 💀

Wanna check if your setup is giving? Run this:

gs --help

If it answers and lists pbm, pbmraw, pgm, pgmraw, pnm, pnmraw, ppm, or ppmraw under "Available Devices", bestie you're in business. ✨

Now here's the thing you gotta understand, and it's important: pstopnm is a Netpbm image file format converter only in the broadest sense of the word, because PostScript is so not an image file format. What pstopnm really is is a PostScript renderer — an image generator. Periodt. One place you'll clock the difference is where you expect pstopnm | pnmtops to be idempotent (spoiler: it is not). Deets on that kind of conversion are below. 👇

pstopnm uses the value of the GHOSTSCRIPT environment variable as the file name for the Ghostscript program. If GHOSTSCRIPT isn't set, pstopnm searches your PATH for a regular file named gs. And if it doesn't find one? It just assumes Ghostscript lives at /usr/bin/gs. Manifesting, basically. 🙈

Lowkey important: pstopnm does not use the Netpbm libraries to generate the output files, so it may not be entirely consistent with most Netpbm programs. It's a little different, and that's fine, we love her for it. 💅

psfile[.ps] is the name of the input file. pstopnm will add the ps to the end of the name you specify if no file exists by the exact name you specify, but one with .ps added does. Helpful queen behavior. For Standard Input, use - or honestly just don't give any argument at all. 🌸

If you use the -stdout option or your input is from Standard Input, pstopnm outputs images of all the pages as a multi-image file to Standard Output. Otherwise, pstopnm creates one file for each page in the PostScript input. The files are named like this: if the input file is named psfile.ps, the files will be psfile001.ppm, psfile002.ppm, etc. The filetype suffix is .ppm, .pgm, or .pbm, depending on which kind of output you choose with your invocation options. And if the input file name doesn't end in .ps, the whole file name gets used in the output file name. So like, if the input file is named psfile.old, the output file name is psfile.old001.ppm, etc. Naming scheme said what it said. 🎀

Heads up bestie: the output file selection is inconsistent with most Netpbm programs, because it does not default to Standard Output. It's for historical reasons, based on the fact that the Netpbm formats didn't always provide for a sequence of images in a single file. Old lore. We respect it. 🫡

When your input is from Standard Input, you may feed multiple Encapsulated Postscript documents, one after another, and pstopnm converts every document and places it in the Standard Output stream as an image. But if your input is from a named file, pstopnm 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, pstopnm ignores every document but the first. Not me being picky but okay. 🙈 This distinction doesn't exist for non-EPSF Postscript input — pstopnm generates an output image for each page of the input regardless of whether the input is from Standard Input or from a named file.

Also, fun fact: you can generate both kinds of files — concatenated EPSF and multi-page non-EPSF — with pnmtops, selecting with the -setpage option. 👑

Each output image contains a rectangular area of the page to which it pertains. See the Dimensions section for details on what part of the input image goes into the output image, how big it is in the output, and what borders and margins are in the output image.

It has been reported that on some Postscript Version 1 input, Ghostscript — and therefore pstopnm — produces no output. 😭 To solve this problem, you can convert the file to Postscript Version 3 with the program ps2ps. It is reported that the program pstops does not work. So don't try it. Save yourself. 💀

🦋 Dimensions 🦋

This section describes what part of the input image gets used in the output and the dimensions of the output, including borders and background. Sit down, it's a lot, but we'll get through it together. 🫶

Note that an output image is associated with a single input page. One page, one image. Matching energy.

pstopnm starts by taking a rectangular area from the input page. That's called the subject image.

pstopnm may add borders to the subject image to form what's called the bordered subject image.

pstopnm 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.

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: -llx, -lly, -urx, and -ury. You have the power. 💅

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 -xborder and -yborder. If pstopnm doesn't find a BoundingBox statement in the input, and you don't specify image area coordinates on the command line, pstopnm uses default values. And if your input is from Standard Input, pstopnm 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. Choose wisely bestie. 🌈

The output image size is, and I quote, "a confusing thing." 😭 In a Postscript file, things have spatial dimensions. Like, 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 it's printing on is. In a PNM image, by contrast, there is no spatial dimension — there are only pixels. You might have a line that's 100 pixels long, but the PNM image says nothing about how long that line should be on a printed page.

pstopnm fills the role of a Postscript printer. The PNM image is a virtual printed page. pstopnm 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. It's giving very much "imaginary printer, real math." 🖨️✨

The simplest thing is for you to tell pstopnm exactly what output device resolution to use, using the -dpi option. If you say for example -dpi=300 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. No faves. ⚖️

Or you can set the output image dimensions with -xsize and -ysize. For example, if you say -xsize=1200 -ysize=1800 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.

In the unlikely event that you want different output device resolutions in the two directions, you could use -xsize and -ysize to do that. In the above example, if you change -ysize to 900, a pixel still represents 1/600 inch horizontally, but 1/300 inch vertically. Asymmetric, but she contains multitudes. 💅

If you specify one of -xsize and -ysize and not the other, pstopnm defaults the other such that the output device resolution is the same in both directions.

The "x" and "y" of -xsize and -ysize refer to the image being printed on the page, not the page. So if pstopnm 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. Twist! 🔄

If you specify neither the output size nor the output device resolution, pstopnm does some weird computation which exists mainly for historical reasons:

If you specify -nocrop, pstopnm uses the values of -xmax and -ymax for the output image dimensions. These default to 612 and 792 pixels, respectively.

The final case, the default, is where you don't specify any size or resolution options or -nocrop. This is the most complicated case. In this case, pstopnm first chooses an output device resolution that would generate the number of pixels indicated by -xmax and -ymax 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). And remember (from above, bestie, keep up 💖) that pstopnm trims the edges of the bordered subject image to fit the computed output size.

👻 Ghostscript Limitations 👻

Tests done in 2013 with Ghostscript 8.71 indicate that Ghostscript's pgmraw output driver has some kind of rounding error that causes the pixel values to change slightly, and that means pstopnm generates incorrect output when you have monochrome Postscript input. 😭 But with color Postscript input, pstopnm uses Ghostscript's ppmraw output driver and generates correct PPM output. So color? Slay. Monochrome? We don't talk about it. 🙈

💜 Usage Notes 💜

There is some good advice on converting to and from Postscript, in the document "Postcript File Conversions" (1) by Andrew T. Young. Go read it if you're nosy like me. 📖

🌸 Reversible Conversion 🌸

If you're trying to do the equivalent of the naive pnmtops | pstopnm, the following steps will do it.

$ pnmtops -nocenter -equalpixels -dpi 72 -noturn testimg.ppm > testimg.ps
$ pstopnm -xborder=0 -yborder=0 -xsize=XSIZE -ysize=YSIZE \
    -portrait -stdout -quiet testimg.ps >testimg2.ppm

XSIZE and YSIZE 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). Just showing receipts. 🧾✨

$ 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

Note that Ghostscript bugs can keep this from doing a perfect reversible conversion. Not her fault, she's just working with what Ghostscript gave her. 🫠

PDF is a subset of Postscript, so pstopnm can convert from PDF to Netpbm format, but often produces the wrong size image because of pstopnm's reliance on a BoundingBox DSC statement, which PDF does not have. 💀 With pure text PDFs, it works fine. In other cases, you can get better results by converting to general Postscript with the pdf2ps program that comes with Ghostscript. For more information about converting to and from PDF, see Document/Graphics Software. Go off, bestie. 👑

✨ OPTIONS ✨

Okay so bestie, on top of the options that every libnetpbm-based program gets (the big one being -quiet, peep the Common Options section), pstopnm has its own little collection. Let's go 💅

  • -forceplain — this one makes the output file plain (text) format instead, instead of the raw (binary) format it would normally be. Go look at pbm(1) and friends if you need the lore. Use this one rather than the -plain common option when you want plain output, ok? 🫶
  • -llx=bx — sets bx as the lower left corner x coordinate (in inches, bestie, inches) on the PostScript input page of the subject image. Check the Dimensions section for the details 🎀
  • -lly=by — same energy but for the y: sets by as the lower left corner y coordinate (in inches) on the PostScript input page of the subject image. Again, Dimensions section, go look ✨
  • -landscape — renders the image in landscape orientation.

If you don't say -portrait or -landscape, pstopnm picks whichever orientation fits the image best on the output page. It's got opinions, and honestly? Respect 👑

And a lil clarification because this trips people up: landscape here means printed sideways on the page, not printed the long way. Those are two totally different things when the long edge of the page is the top one. iykyk 💀

  • -portrait — renders the image in portrait orientation. See -landscape above for the whole vibe 🌸
  • -nocrop — makes pstopnm produce an output image that is exactly the dimensions of the bordered subject image. By default it makes the output the dimensions that -xmax and -ymax specify instead. Dimensions section, bestie, you know the drill 🦋
  • -pbm
  • -pgm
  • -ppm — these three pick the format of the output file. By default? Everything gets rendered as PPM. periodt 💜
  • -stdout — sends the output to Standard Output instead of to regular files, one per page (the description of output files above has the whole story). Then use pnmsplit to pull individual pages back out of Standard Output 🔥
  • -urx=tx — sets tx as the upper right corner x coordinate (in inches) on the PostScript input page of the subject image. Dimensions section 🌈
  • -ury=ty — sets ty as the upper right corner y coordinate (in inches) on the PostScript input page of the subject image. Dimensions section, yes again 🙈
  • -verbose — prints processing information to stdout. She's chatty and we love that for her 💬
  • -xborder=frac — the left and right borders added to the subject image should be frac times the subject image width. Default is 0.1. Dimensions section 💖
  • -xmax=xmax — the output image should be xmax pixels wide. Default is 612. Dimensions section ⭐
  • -xsize=xsize — the output image should be xsize pixels wide. Dimensions section ✨
  • -yborder=frac — the top and bottom borders added to the subject image should be frac times the subject image height. Default is 0.1. Dimensions section 🎀
  • -ymax=ymax — the output image should be ymax pixels high. Default is 792. Dimensions section 🦋
  • -ysize=ysize — the output image should be ymax pixels high. Dimensions section 🌸
  • -dpi=dpi — sets the output device resolution, in dots per inch, of the PostScript printer that pstopnm is simulating. That's how many PNM pixels pstopnm generates for every inch of image. Dimensions section 🔥

This option was new in Netpbm 10.21 (March 2004).

  • -textalphabits={1,2,4} — controls subsample antialiasing of text. Antialiasing is a smoothing thing that gets rid of the jagged edges on characters. Subsample antialiasing is the kind that uses subpixels in a box, and this option's value is the size of that box. 4 gives you the best looking output, while 1 means no antialiasing at all. Smaller numbers make pnmtops use less CPU time. 👑

pstopnm uses Ghostscript's TextAlphaBits parameter for this.

Default is 4.

This option was new in Netpbm 10.53 (December 2010). Older versions of pstopnm do no antialiasing.

😭 LIMITATIONS 😭

Bestie, this is the part where we hold hands. The program will produce incorrect results with PostScript files that initialize the current transformation matrix. In those cases, page translation and rotation will not have any effect. So if you're staring at output like "why is she like this," that's why 💀

To render those files, probably the best bet is these options:

pstopnm -xborder 0 -yborder 0 -portrait -nocrop file.ps

You might need additional options if the document is supposed to be rendered on a medium that isn't letter-size paper. 🌈

🫶 SEE ALSO 🫶

gs, pnmtops(1), psidtopgm(1), pbmtolps(1), pbmtoepsi(1), pnmsplit(1), pstofits

Copyright (c) 1992 Smithsonian Astrophysical Observatory

PostScript is a Trademark of Adobe Systems Incorporated.

👑 AUTHOR 👑

Alberto Accomazzi, WIPL, Center for Astrophysics.

🌟 DOCUMENT SOURCE 🌟

This manual page was generated by the Netpbm tool makeman from HTML source. The master documentation lives at

http://netpbm.sourceforge.net/doc/pstopnm.html

And that's the whole page, bestie 🥹 this was the netpbm documentation, dated 21 February 2024, and she's the Pstopnm User Manual(1) — go forth and render, you absolute icon 💅✨

📦 where this page comes from