EPSTOOL(1)

💖 EPSTOOL(1) — General Commands Manual 💖

okay bestie, sit down, hydrate, and let me tell you about epstool, the icon of section 1 of the General Commands Manual. she does preview images and bounding box glow-ups for EPS files and honestly? she ate. 🎀

---

✨ NAME ✨

epstool — Edit preview images and fix bounding boxes in EPS files.

---

🌸 SYNOPSIS 🌸

epstool command [ options ] inputfile outputfile

---

🦋 DESCRIPTION 🦋

epstool is a utility to create or extract preview images in EPS files. It can also calculate optimal bounding boxes. like, it's giving "I do it all and I do it well" energy 💅

🌈 EPS (Encapsulated PostScript Format) 🌈

EPS is a specialised form of a PostScript file that complies with the Document Structuring Conventions (DSC) and is intended to be embedded inside another PostScript file. so it's the little sister format that's meant to live inside a bigger file, got it? 🫶

An EPS file must contain a special first line that identifies it as an EPS file (e.g. %!PS-Adobe-3.0 EPSF-3.0) and it must contain a %%BoundingBox: line. no cap, those two are non-negotiable. 👑

The EPS file only draws within the rectangle defined by the bounding box. The PostScript code must avoid using PostScript operators that would interfere with the embedding. These include operators with global effects such as changing the page size and changing the half tone screen. so like, no touching the global settings, bestie, that's rude to your host file 🙈

🎀 PREVIEWS 🎀

EPS files may contain a preview to be used by programs that can't interpret the PostScript code. (yes, some programs just can't read the vibe ✨) There are three ways to add a preview to an EPS file.

• Interchange — This preview is included within PostScript comments in a section marked %%BeginPreview: / %%EndPreview. The actual image data is stored in hexadecimal format. This format is most commonly used on Unix.
• DOS EPS — The preview is a TIFF or Windows Metafile. A DOS EPS file has a 30 byte binary header which gives offsets and lengths for the PostScript, TIFF and Windows Metafile sections. You can't send a DOS EPS file directly to a printer — you have to remove the binary header and preview first. This format is most commonly used on MS-Windows.
• PICT — The preview is in PICT format stored in the resource fork of the file. This format is most commonly used on the Macintosh. Epstool provides limited support for this format.

---

👑 COMMANDS (one only): 👑

okay so the whole point: pick ONE command. one. singular. not two, not three. 💀

• -t4, --add-tiff4-preview — Add a TIFF 4 preview. The preview is monochrome and is intended for use with old programs that won't read TIFF6, such as Word Perfect 5.1 for DOS. (grandma tech, we respect her 🫡)
• -t6u, --add-tiff6u-preview — Add a TIFF 6 uncompressed preview. See --add-tiff6p-preview for how to add a greyscale or monochrome preview.
• -t6p, --add-tiff6p-preview — Add a TIFF 6 preview compressed with packbits (simple run length encoding). The preview will normally be full colour, but you can make it greyscale by adding the option --device bmpgray or --device pgmraw, or monochrome using --device bmpmono or --device pbmraw.
• -tg, --add-tiff-preview — Add a TIFF preview using ghostscript to generate the TIFF file. You must specify a suitable TIFF device using --device. If you want a compressed monochrome image, you might use --device tiffg3.
• -i, --add-interchange-preview — Add a monochrome interchange preview.
• -w, --add-metafile-preview — Add a Windows Metafile (WMF) preview. The metafile will contain a bitmap, not vector information. The preview will normally be full colour. See --add-tiff6p-preview for how to add a greyscale or monochrome preview.
• --add-pict-preview — Add a Mac PICT preview. EPSF files with PICT previews can generally be used only on Mac computers. The preview will be full colour. The AppleSingle and MacBinary formats will contain the EPSF and the preview. The AppleDouble or Resource format will contain the preview only and needs to accompany the original EPSF file. To specify the file format use --mac-single, --mac-double, --mac-binary or --mac-rsrc.
• --add-user-preview filename — Add a user supplied image as a preview. The image can be a Windows bitmap, a PBMPLUS file, a TIFF image or a Windows Metafile. Window bitmaps and PBMPLUS files will be converted to TIFF6 compressed with packbits. TIFF and Windows Metafile images will be added unchanged.
• --bitmap — Create a bitmap of the area within the EPS bounding box. The bitmap type must be specified with --device. If processing a DCS 2.0 file, the separation can be specified with --page-number.
• --copy — Copy the EPS file. This is generally used with the --bbox option to update the bounding box.
• --dcs2-multi — Convert DCS 2.0 separations to multiple files. See DCS 2.0. If the output name is out.eps, then the separations would be named out.eps.Cyan etc. ✨
• --dcs2-single — Convert DCS 2.0 separations to a single file. See DCS 2.0.
• --dcs2-report — Write the separation names, lengths and CMYK values to standard output. This can be used to identify if a DCS 2.0 file is missing the composite page or preview.
• --dump — Display some information about the file type and DSC comments.
• -p, --extract-postscript — Extract the PostScript section from a DOS EPS file.
• -v, --extract-preview — Extract the preview section from a DOS EPS file.
• -h, --help — Display a summary of the epstool commands and options.
• --test-eps — Partially test if a file complies with the EPSF specification. (partially! she's honest about her limits 💅)

✨ OPTIONS ✨

okay bestie, here's the whole menu of flags. every single one. hydrate before you read, it's a lot 💅

• -b, --bbox — works out the bounding box using the ghostscript bbox device, then updates it inside the EPS file. no cap, that's the whole job ✨
• --combine-separations filename — merges the separations of your input DCS 2.0 file with the separations of this file. it's an error if the bounding boxes don't match, or if they've got separations sharing the same name 😭 you have to pair this with --dcs2-multi or --dcs2-single. heads up: the composite page might still need a lil glow-up afterwards with --replace-composite 🫶
• --combine-tolerance pts — when you're using --combine-separations, this lets the bounding boxes wobble by up to pts points. the default is 0, so by default they have to match exactly — no wiggle room, periodt.
• --custom-colours filename — when you run --replace-composite on a DCS 2.0 file, use the colours written in this file instead of the ones in the composite page. your colours, your rules 💖
• -d, --debug — spill the tea about progress (more verbose), and don't delete the temporary files. she's messy on purpose.
• --device name — pick a ghostscript device for making the preview or bitmap:
  • for --add-tiff-preview it must be one of the ghostscript tiff devices, like tiffg3 or tiff24nc
  • for any other preview it must be one of the bmp or pbmplus devices, like bmpgray, bmp16m, pgmraw or ppmraw
  • for bitmap output (--bitmap) it can be any ghostscript bitmap device 👑
• --doseps-reverse — when writing a DOS EPS file (that's the TIFF or WMF preview situation), the default is to write the PostScript before the preview. this flag flips it so the preview comes before the PostScript section. some buggy programs literally demand it 🙈 either order is correct, so don't stress.
• --dpi resolution — sets the resolution of the preview or the bitmap. default is 72 dpi. classic.
• --dpi-render resolution — renders at a higher resolution set by --dpi-render, then downsamples down to whatever --dpi says. this works when you're adding a preview image or using --replace-composite, but not when using --bitmap 🚫 it upgrades your preview quality when the original contains a pre-rendered image and --dpi-render is set to match the original target printer. glow up achieved ✨
• --ignore-information — ignore information messages from the DSC parser. use at your own risk. these messages usually mean something's wrong with the EPS file, but most EPS handlers probably won't care. example: a line with more than 255 characters. 💀
• --ignore-warnings — ignore warnings from the DSC parser. use at your own risk. these are usually about faults in the DSC comments that epstool can recover from, but they might confuse other EPS handlers. example: a bounding box that incorrectly uses floating point numbers instead of integer. not the vibe but okay.
• --ignore-errors — ignore warnings from the DSC parser. use at your own risk. bestie. you really should fix the EPS file first 😭 fr fr.
• --gs command — name the ghostscript program. on Unix the default is gs. on Windows, epstool checks the registry for installed versions of ghostscript and uses the latest one, otherwise it falls back to gswin32c.exe.
• --gs-args arguments — extra Ghostscript arguments. you might use this to select anti-aliasing with "-dTextAlphaBits=4 -dGraphicsAlphaBits=4" 🦋
• --output filename — pick the output file instead of using the second file parameter. and if the filename is -, epstool writes to standard output — which requires --quiet. yes, both, or it won't slay.
• --mac-binary — when adding a PICT preview, use the MacBinary I format. for the Mac 🍎
• --mac-double — when adding a PICT preview, use the AppleDouble format for the Mac.
• --mac-rsrc — when adding a PICT preview, use the Resource format for the Mac.
• --mac-single — when adding a PICT preview, use the AppleSingle format for the Mac.
• --missing-separations — when writing a DCS 2.0 file, epstool will normally fail if a separation is missing. with this flag, it removes references to the missing separations while writing the file instead. problem solved 💅
• --page-number page — when you're creating a bitmap with --device from a DCS 2.0 file, page says which separation to use. page 1 is the composite, page 2 is the first separation. use --dcs2-report to get the full list of separations. iykyk.
• --quiet — try to run without writing to standard output. she's shy.
• --rename-separation oldname newname — when copying a DCS 2.0 file with --dcs2-multi or --dcs2-single, rename the separation called oldname to newname. this option implies --missing-separations. it's assumed the new name is just an alias for the same colour and that the CMYK or RGB values for the separation don't change. you can use this one multiple times. and you must use it if the input file incorrectly has two separations with the same name. messy input, clean output ✨
• --replace-composite — some DCS 2.0 files just don't have an image in the composite page (iconic of them). this replaces the composite page with a CMYK image derived from the separations. must be used with --dcs2-multi or --dcs2-single. see also --dpi and --custom-colours 🫶

---

🍎 MACINTOSH 🍎

okay so the Macintosh does not do a flat file system. every file can have a data fork and a resource fork, and that's the whole plot twist 🌀

EPSF files keep their PostScript in the data fork, and optionally keep a preview in the resource fork as a PICT image. also, the file type comes from the finder info, not from a file extension. file types use a four character code, like "EPSF" or "PICT". when Macintosh files get copied to a foreign file system, the resource fork might just get left behind 😭 the ways to keep the resource fork are:

• package the finder data, data fork and resource fork all into a single MacBinary or AppleSingle file, or
• put the data fork in a flat file and the finder info plus resource fork into an AppleDouble file.

the Mac OSX finder handles AppleDouble files automatically when copying files to and from a foreign file system. so if you copy test.eps to a foreign file system, the data fork gets written as test.eps and the finder info and resource fork go into the AppleDouble file ._test.eps or .AppleDouble/test.eps ✨

Epstool can read MacBinary and AppleSingle files. it can write MacBinary I, AppleSingle, AppleDouble or Resource files. files written by epstool will have type EPSF and creator MSWD. when adding a preview to test.eps, it's suggested that you create the MacBinary file test.eps.bin. on a Macintosh computer you then need to extract it with StuffIt Expander. another alternative is to write the AppleDouble file to ._test.eps, then copy both files to a file system accessible to a Mac computer 🫶

here's how epstool guesses the format:

• if the output file name starts with . → AppleDouble is assumed
• otherwise if it ends with .as → AppleSingle is assumed
• otherwise if it ends with .rsrc or /rsrc → Resource is assumed
• otherwise → MacBinary is assumed

when writing a MacBinary file, it's recommended that you end the filename in .bin. to force the file type, use --mac-single, --mac-double, --mac-binary or --mac-rsrc. no guessing needed 💅

on Mac OS X you can access a file's resource fork from command line tools by appending /rsrc to the original file name. the easiest way to add a preview to the file test.eps on Mac OS X is to let epstool write in --mac-rsrc format to test.eps/rsrc (peep the Examples section) 👑

---

🌈 DESKTOP COLOR SEPARATIONS (DCS 2.0) 🌈

The Desktop Color Separation (DCS) image file format contains a low resolution preview, a main file with the full resolution composite image, and colour separations with full resolution separated plates. the separations will typically contain Cyan, Magenta, Yellow, Black and possibly spot colours. there are two versions of DCS 2.0, and they are not the same girl 💅

Multiple File

the main file contains %%PlateFile: (name) EPS Local filename comments which give the filenames of the separation plates. the main file may contain a low resolution DOS EPS preview. the separation files do not contain previews.

Single File

this is an abuse of the EPS specification 😭 the single file contains the main file and the separations concatenated together, which makes the DSC comments incorrect. the main file specifies the byte offsets to the separations using %%PlateFile: (name) EPS #offset size. the single file may then be placed inside a DOS EPS file with a low resolution preview. by default, epstool writes single file DCS 2.0.

---

Epstool can add previews to single and multiple file DCS 2.0. it can split single file DCS 2.0 into multiple files and vice versa. this means you can split a single file DCS 2.0, replace the composite image, create a new preview, and then recombine it back into a single file. a whole makeover arc ✨

some DCS 2.0 files do not have an image in the composite page. to figure out whether the composite page has no image, use --dcs2-report and look to see if the composite section is very short. using --dcs2-single --replace-composite replaces the composite page with the headers of the original composite page and a body containing a CMYK image derived from the separations. set the resolution of that CMYK image using --dpi 🎀

when replacing the composite page with a CMYK image using --replace-composite, the --custom-colours option is super useful for dealing with DCS 2.0 files that have incorrect CMYK colours — for example, specifying that the varnish layer is grey. each line of the CMYK colours file is formatted like a DSC %%CMYKCustomColor: or %%RGBCustomColor: line, as shown in the example below:

%%CMYKCustomColor: 0.00 0.00 0.00 0.00 Varnish

%%CMYKCustomColor: 1.00 0.68 0.00 0.12 (Dark Blue)

%%RGBCustomColor: 0.5 0.0 0.0 (Dark Red)

DCS2 files should not have two separations with the same name. epstool will not allow a DCS2 output file to have duplicate separation names. use --rename-separation to resolve this 🙈

✨ EXAMPLES ✨

Okay bestie, this is the part where it all clicks, fr. Real commands, real files, copy-paste energy. Let's go 💅

---

🐯 Add colour preview (24bit/pixel) to EPS file

epstool -t6p tiger.eps output.eps

---

📠 Add TIFF (G3 Fax) preview to tiger.eps

epstool --add-tiff-preview --device tiffg3 tiger.eps output.eps

Any GS TIFF device can be used, e.g. tiffg4, tiffpack 🌈

---

🫳 Extract TIFF preview from tiger.eps

epstool -v tiger.eps tiger.tif

---

📐 Fix incorrect %%BoundingBox then add TIFF4 preview

epstool --bbox -t4 golfer.eps output.eps

---

🔧 Adjust the BoundingBox of an existing EPS file, but don't add a preview

epstool --copy --bbox input.eps output.eps

---

🪟 Add user supplied Windows Metafile to EPS file

epstool --add-user-preview logo.wmf logo.eps output.eps

Typically used when an application can export EPS and WMF separately but can't export EPS with WMF preview. Not me being the middle-man for your files 💀

---

🍎 Add a PICT preview and write an AppleDouble file

epstool --add-pict-preview --mac-double tiger.eps ._tiger.eps

To be used by a Mac, both tiger.eps and ._tiger.eps need to be on a foreign file system accessible to the Mac. Two files, one destiny, no cap 🦋

---

💾 Add a PICT preview, overwriting the existing resources

epstool --add-pict-preview --mac-rsrc tiger.eps tiger.eps/rsrc

On Mac OS X you can access a file's resource fork from command line tools by appending "/rsrc" to the file's original name. Iconic behaviour honestly 👑

---

📝 NOTES 📝

Okay so important stuff, listen up bestie 🫶

When adding a WMF preview to an EPS file using -add-user-preview filename, the placeable metafile header is removed from the metafile as it is put into the EPS file. When extracting a WMF preview from an EPS file, a placeable metafile header is created from the EPS BoundingBox information. This placeable metafile header assumes that the WMF has its origin at (0,0), which might not be correct. ⚠️

That last bit is the drama: it assumes (0,0). If your WMF doesn't actually live at (0,0), things may look off. That's just how it is, iykyk 😭

When epstool is creating a TIFF or WMF preview, it will convert palette colour images into 24-bit/pixel. Glow up, literally ✨

The environment variable TEMP should point to a writeable directory for temporary files. If not defined, /tmp will be used for Unix and the current directory will be used for other platforms. 🗂️

---

👑 AUTHOR 👑

epstool was written by Russell Lang <gsview@ghostgum.com.au> 💖

This man page was contributed by Martin Pitt <martin@piware.de> for the Debian GNU/Linux system (but may be used by others). 🌸

---

That's the whole page, bestie!! Written by Martin Pitt and Russell Lang, dated 2005-06-10, and it lives in the manual as EPSTOOL(1). You made it all the way to the bottom of the man page — that's main character energy, fr fr. Go fix those BoundingBoxes. Slay 💅✨🎀