epstool - Edit preview images and fix bounding boxes in EPS files.
] inputfile outputfile
is a utility to create or extract preview images in EPS files. It
can also calculate optimal bounding boxes.
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. 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
line. 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
EPS files may contain a preview to be used by programs that can't interpret the
PostScript code. There are three ways to add a preview to an EPS file.
- 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.
- The preview is in PICT format stored in the resource fork
of the file. This format is most commonly used on the Macinstosh. Epstool
provides limited support for this format.
- -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.
- -t6u, --add-tiff6u-preview
- Add a TIFF 6 uncompressed preview. See
--add-tiff6p-preview for how to add a greyscale or monochrome
- -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
- -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
- -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
- 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
- --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.
- 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 the EPS file. This is generally used with the
--bbox option to update the bounding box.
- 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
- Convert DCS 2.0 separations to a single file. See DCS 2.0.
- 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.
- Display some information about the file type and DSC
- -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.
- Partially test if a file complies with the EPSF
- -b, --bbox
- Calculate the bounding box using the ghostscript bbox
device and update in the EPS file.
- --combine-separations filename
- Combine the separations of the input DCS 2.0 file with
those of this file. It is an error if the bounding boxes do not match or
they contain separations with the same name. This option must be used with
--dcs2-multi or --dcs2-single. The composite page may later
need to be updated with --replace-composite.
- --combine-tolerance pts
- When using --combine-separations, allow the bounding
boxes to vary by up to pts points. The default is 0 so the bounding
boxes must match exactly.
- --custom-colours filename
- When using --replace-composite on a DCS 2.0 file,
use the colours specified in this file in preference to those specified in
the composite page.
- -d, --debug
- Be more verbose about progress. Do not remove temporary
- --device name
- Specify a ghostscript device to be used when creating the
preview or bitmap. For --add-tiff-preview this must be one of the
ghostscript tiff devices (e.g. tiffg3, tiff24nc). For any other preview,
it must be one of the bmp or pbmplus devices (e.g. bmpgray, bmp16m,
pgmraw, ppmraw). For bitmap output ( --bitmap) it can be any
ghostscript bitmap device.
- When writing a DOS EPS file (TIFF or WMF preview), the
default is to write the PostScript before the preview. Using
--doseps-reverse puts the preview before the PostScript section,
which is required by some buggy programs. Either order is correct.
- --dpi resolution
- Set the resolution of the preview or bitmap. The default is
- --dpi-render resolution
- Render at a higher resolution set by --dpi-render ,
then downsample to the resolution set by --dpi. This works when adding
a preview image or using --replace-composite , but not when
using --bitmap. This improves the preview quality when the original
contains a pre-rendered image and --dpi-render is set to match the
original target printer.
- Ignore information messages from the DSC parser. Use at
your own risk. These messages usually indicate that something is wrong
with an EPS file, but that most EPS handlers probably won't care. An
example is a line with more than 255 characters.
- Ignore warnings from the DSC parser. Use at your own risk.
These messages are usually about faults in the DSC comments that are
recoverable by epstool, but may confuse other EPS handlers. An
example is a bounding box that incorrectly uses floating point numbers
instead of integer.
- Ignore warnings from the DSC parser. Use at your own risk.
You really should fix the EPS file first.
- --gs command
- Specify the name the ghostscript program. On Unix the
default is gs. On Windows, epstool will check the registry for
installed versions of ghostscript and use the latest, otherwise it will
- --gs-args arguments
- Specify additional Ghostscript arguments. This might be
used to select anti-aliasing with "-dTextAlphaBits=4
- --output filename
- Specify the output file (instead of using the second file
parameter). Using the filename - causes epstool to write to
standard output, which requires the use of --quiet.
- When adding a PICT preview, use the MacBinary I format. for
- When adding a PICT preview, use the AppleDouble format for
- When adding a PICT preview, use the Resource format for the
- When adding a PICT preview, use the AppleSingle format for
- When writing a DCS 2.0 file, epstool will normally fail if
a separation is missing. When this option is used, it will remove
references to missing separations when writing the file.
- --page-number page
- When creating a bitmap with --device from a DCS 2.0
file, page specifies the separation to be used. Page 1 is the
composite and page 2 is the first separation. Use --dcs2-report to
get the list of separations.
- Try to run without writing to standard output.
- --rename-separation oldname newname
- When copying a DCS 2.0 file with --dcs2-multi or
--dcs2-single, rename separation with oldname to
newname. This option implies --missing-separations. It is
assumed that the new name is just an alias for the same colour and that
the CMYK or RGB values for the separation are not changed. This option may
be used multiple times. This must be used if the input file incorrectly
has two separations of the same name.
- Some DCS 2.0 files do not have an image in the composite
page. This option replaces the composite page with a CMYK image derived
from the separations. This option must be used with --dcs2-multi or
--dcs2-single. See also the options --dpi and
The Macintosh does not use a flat file system. Each file can have a data fork
and a resource fork. EPSF files have the PostScript in the data fork, and
optionally have a preview in the resource fork as a PICT image. In addition,
file type is obtained from the finder info rather than a file extension. File
types use a four character code such as "EPSF" or "PICT".
When Macintosh files are copied to a foreign file system, the resource fork
may be left behind. Alternatives to retain the resource fork are to package
the finder data, data fork and resource fork in a single MacBinary or
AppleSingle file, or to put the data fork in a flat file and the finder info
and resource fork in an AppleDouble file. The Mac OSX finder will handle
AppleDouble files automatically when copying files to and from a foreign file
system. When copying test.eps
to a foreign file system, the data fork
would be written as test.eps
and the finder info and resource fork to
the AppleDouble file ._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
and creator MSWD
. When adding a preview to
, it is suggested that you create the MacBinary file
. On a Macintosh computer you then need to extract it with
StuffIt Expander. Another alternative is to write the AppleDouble file to
then copy both files
to a file system accessible to a
If the output file name starts with .
then AppleDouble will be assumed,
otherwise if it ends with .as
then AppleSingle will be assumed,
otherwise if it ends with .rsrc
then Resource will be
assumed, otherwise MacBinary will be assumed. When writing a MacBinary file,
it is recommended that you end the filename in .bin
. To force the file
type, use --mac-single
On Mac OS X you can access a file's resource fork from command line tools by
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
format to test.eps/rsrc
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.
- 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 allows a single
file DCS 2.0 to be split, the composite image replaced, a new preview created,
and then be recombined into a single file.
Some DCS 2.0 files do not have an image in the composite page. To determine if
the composite page does not contain an image, use --dcs2-report
look to see if the composite section is very short. Using --dcs2-single
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 the CMYK image using --dpi
When replacing the composite page with a CMYK image using
, the --custom-colours
option is 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:
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
to resolve this.
- 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.
- 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
need to be on
a foreign file system accessible to the Mac.
- Add a PICT preview, overwriting the existing
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.
When adding a WMF preview to an EPS file using -add-user-preview
, 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.
When epstool is creating a TIFF or WMF preview, it will convert palette colour
images into 24-bit/pixel.
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.
was written by Russell Lang <firstname.lastname@example.org>
This man page was contributed by Martin Pitt <email@example.com> for the
Debian GNU/Linux system (but may be used by others).