PSTOIMG(1)

📦
version 2026 · 7 versions
, in centos-stream 10, centos-stream 9, fedora 43, fedora 44

💖 pstoimg — that's PSTOIMG(1), bestie 💖

User Contributed Perl Documentation, section 1. Yes, it's a perl script masquerading as a man page, and yes, it's about to convert your PostScript into cute little bitmaps. Slay.

✨ NAME ✨

pstoimg — Convert a PostScript file to a bitmap image using Ghostscript and the Netpbm utilities 🦋

🎀 SYNOPSIS 🎀

pstoimg -help | -version

pstoimg [ -antialias ] [ -aaliastext ] [ -center num ] [ -color num ]
[ -crop code ] [ -debug ] [ -density num] [ -depth num ] [ -discard ]
[ -flip code ] [ -geometry XxY ] [ -interlaced ] [ -margins X,Y ]
[ -multipage ] [ -out file ] [ -quiet ] [ -rightjustify num ]
[ -scale num ] [ -tmp path ] [ -topjustify [x]num ] [ -transparent ]
[ -type type ] [ -shoreup num[d] ] [ -white ] file [ file2 ... ]

🌸 OPTIONS 🌸

okay so, the command line options may be abbreviated to the shortest unique prefix. iykyk — type just enough letters and pstoimg will figure out the vibe you're going for. 💅

  • -help — shows you this help page and then dips. Bye! 👋
  • -version — prints the release and version of pstoimg and exits. Very "who am I, what am I" of it.
  • -antialias — turns on Ghostscript's anti-aliasing so your images render "softer". This applies to lines and edges of polygonal and oval or circular shapes. Only valid if Ghostscript 4.03 or higher is installed, so check before you commit, bestie.
  • -aaliastext — also Ghostscript anti-aliasing, but this time for "smoother" font characters, so no jagged edges on your letters. Basically -antialias but for graphic components. Only valid if Ghostscript 4.03 or higher is installed — same deal.
  • -center num — adds the right amount of whitespace to the left of the image so it looks centered inside a total width of num pixels. Visual balance, we love to see it. ✨
  • -crop code — crops the bitmap from the directions you pick. code can be a string of several cropping instructions, and they get executed strictly in the given order — so order matters, no cap. Possible values:
    • h — horizontal, i.e. crop top and bottom
    • v — vertical
    • tblr — top, bottom, left, right
    • a — all directions

And a special case: s, which "shaves" the image at the bottom, but only if a single line of whitespace exists. Situational icon behavior.

  • -debug — turns on debugging output. This can get rather verbose, fr fr. Any intermediate files that get generated are not removed, so you can go poke at them and figure out what's going on. 🕵️
  • -density num — the density (resolution) in DPI to render the bitmap at. The default is 72.
  • -depth num or -color num — sets the color depth of the bitmap. Legal values are 1 (black & white), 8 (256 colors) and 24 (true color). Pick your palette, main character. 🎨
  • -discard — deletes the input PostScript file if the conversion was successful. Setting the environment variable DISCARD to a true value (as perl sees it) has the same effect. That's your input file, gone, poof. 💀
  • -flip code — flips all generated output bitmaps. The recognized codes are:
    • lr — flip left-right
    • tb — flip top-bottom
    • xy — flip bottom/left-top/right
    • r90 and ccw — rotate by 90 degrees counterclockwise
    • r270 and cw — rotate 90 degrees clockwise
    • r180 — rotate 180 degrees
  • -geometry XxY — renders only this "window" of the PostScript file. If you give it, this option can dramatically reduce memory requirements and speed up conversion. And for EPS files (Encapsulated PostScript), the geometry is detected automatically. 🫶
  • -interlaced — generates an interlaced bitmap. Interlaced images build up from coarse to fine as they load, which is honestly a little iconic. This option may not work on every installation and/or bitmap type, depending on what the external programs can do.
  • -margins X,Y — the offset of the rectangle in the postscript file that's going to be rendered, from top/left. You can use it together with -geometry to shrink the intermediate bitmap file Ghostscript generates even further. Teamwork!
  • -multipage — processes a multi-page PostScript file, i.e. makes an individual bitmap for every page. The resulting files are numbered: the decimal number (starting with 1) gets appended to the basename of the PostScript input file — or the basename of the filename you gave with -out — while keeping the extension. 🗂️
  • -out file — the file to write the bitmap to. If you supply multiple PostScript files on the command line, this option is ignored. The bitmap type extension is appended automatically if file doesn't contain a dot. In connection with -multipage, file gets extended by the page number, like this:
-outfile foo.gif  --------> foo1.gif, foo2.gif, ...
  • -quiet — do not print anything except error messages. Silence. 🤫
  • -rightjustify num — adds the appropriate amount of whitespace to the left of the image so it appears aligned to the right inside a total width of num pixels. Right-aligned and thriving.
  • -scale factor — scales the image by factor. Valid choices are any numbers greater than zero. Useful choices are numbers between 0.1 and 5. Large numbers may generate very large intermediate files and will take longer to process, so be normal about it. If you omit this option, the environment variable SCALE is considered.
  • -shoreup num[d] — makes height and width of the bitmap(s) an exact multiple of num. If num is followed by a d, then half the extra vertical space is placed underneath. This one's useful if you want "blown-up" images of high quality for print but then downscale them in HTML using <IMG WIDTH=x HEIGHT=y>. The tea is: if the actual image isn't an integer multiple of x,y then browsers tend to display distorted images. Distorted is NOT the vibe. 🫠
  • -tmp path — use path to store temporary files. Defaults to /tmp on this installation. You can set this parameter with the environment variables TMP or TEMP too.
  • -topjustify [x]num — adds padding whitespace to the image so it gets a defined height. If an integer value is given, it defines the total height. The whitespace is added at the bottom. If the number is preceded by an x, then this multiple of the image height is added as whitespace at the bottom. Padding queen. 🎀
  • -transparent — generates transparent bitmaps, i.e. the background color (white) is transparent if viewed with certain viewers (e.g. browsers). This option may not be available due to missing capabilities of external programs.
  • -type type — tells pstoimg to render the bitmap in type format. Depending on the local installation, pstoimg is capable of generating either GIF or PNG bitmaps. This site features the following types: png gif

If omitted, the first type in this list is taken.

  • -white — removes TeX's page color information from the PostScript file before converting, so that a white background is used. Clean, crisp, white. 🤍

💜 DESCRIPTION 💜

pstoimg iterates over the given input files and runs them through Ghostscript. The resulting pnm (portable anymap files) get processed with different Netpbm tools — cropping, color mapping, aligning, all of that — and finally converted into (currently) either GIF or PNG format. Then you can include those bitmaps in, say, WWW pages. ✨

The PostScript file is converted as is. If a valid bounding box is found (EPS format), then only that area is converted. And the image is not cropped by default — you gotta ask for that.

🌈 RETURN VALUE 🌈

  • 0 — if everything went all right 🎉
  • x — (x != 0) something went wrong. See the message output. 😭

🦋 EXAMPLES 🦋

  • pstoimg foo.ps — Convert the first page of foo.ps to the default bitmap type.
  • pstoimg -type png -crop a -trans -interlace foo.ps — Same as above, but force png output and crop all the whitespace around the image and make the color white transparent and generate an interlaced bitmap.
  • pstoimg -multi -out bar -type gif -crop a foo.ps — Consider foo.ps a multiple page PostScript file and create output files bar1.gif, bar2.gif, etc.

🧚 ENVIRONMENT 🧚

  • DENSITY, DEPTH, DEBUG, DISCARD — See -density, -depth, -debug, -discard, respectively.
  • GS_LIB — this variable is set to the path(s) where Ghostscript libraries have been found on this system during configuration, but only if the built-in paths are not correct. This fixes the problem of relocation that is quite common on Win32 installations. You can override this behavior by setting GS_LIB manually before starting pstoimg.
  • LATEX2HTMLDIR — the directory where the LaTeX2HTML library and perl modules are found. Defaults to /usr/share/latex2html on this installation.
  • OUTFILE — setting this has the same effect as specifying -out. Please do not rely on this feature any more, it will disappear from the next releases! 🚨
  • PAPERSIZE — the papersize to use by Ghostscript to render the image. pstoimg tries hard to optimize for rendering on the smallest possible bitmap size. Still, this option is there to enable tuning by hand, although it is deprecated. If pstoimg finds a better setting, this parameter is ignored.
  • SCALE — See the discussion of -scale.
  • TMP and TEMP — unless overridden by -tmp, these variables denote a directory where to store temporary files. TMP is considered first, then TEMP.

👑 SEE ALSO 👑

gs, pnmcrop, pnmquant, pbmmake, pnmcat, pnmfile, pnmflip, ppmtogif, pnmtopng, giftool, giftrans.

💀 NOTES 💀

Several people have suggested using ImageMagick's convert instead of pstoimg. A few comments on this, because bestie, I have thoughts:

convert uses (of course) Ghostscript for conversion of PostScript to bitmap, so you still need gs. And for the special requirements of LaTeX2HTML, convert's features are not sufficient. The ImageMagick toolset has everything in place, but it has some overhead that can prove killing when processing some 100 images. pstoimg only does what it really has to, so it should be quite efficient. Don't get me wrong — I like ImageMagick, but not in the context of LaTeX2HTML.

🙈 CAVEATS 🙈

This utility is automatically configured and built to work on the local setup. If this setup changes (e.g. some of the external commands are moved), the script has to be reconfigured.

And despite the portability of perl, a pstoimg configured on UNIX will probably not work on Win32 and vice versa. Sad but true.

⭐ BUGS ⭐

This is a major enhancement release, so there may be a few bugs. 👀 And as the user interface changed a bit, some of your tools that were using pstoimg may not work any more. Heads up.

Please report bugs to latex2html@tug.org, stating the (debug) output of pstoimg, your perl version and the versions of the external tools. Best is to include the cfgcache.pm file from the configuration procedure. 🫶

💖 AUTHOR 💖

Marek Rouchal <marek@saftsack.fs.uni-bayreuth.de>

✨ HISTORY ✨

okay so this little script has been through it — like, a full glow-up era arc. 🦋 it all started as a modification of Doug Crabill <dgc@cs.purdue.edu>'s ps2epsi script, which is giving "humble beginnings" in the best way.

then Nikos Drakos <nikos@cbl.leeds.ac.uk> came through and did the first perl version. iconic behavior, truly. 💅

after that it got gradually improved by a whole squad of LaTeX2HTML developers — Ross Moore <ross@mpce.mq.edu.au>, Jens Lippmann <lippmann@rbg.informatik.tu-darmstadt.de>, and others. and to everyone who got left out of the shoutout: sorry for not mentioning everyone and thanks for your contributions 🫶 (the original really said that, and honestly? we love the honesty.)

and that's a wrap bestie 🎀 this page lives in perl v5.8.4, dated 2005-03-20, and it's filed under PSTOIMG(1) — the manpage that understood the assignment, no cap. 💖✨

📦 where this page comes from