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.
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. 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. 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.
PREVIEWS
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.
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 Macinstosh.
Epstool provides limited support for this format.
COMMANDS (one only):
-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 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.
OPTIONS
-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 files.
--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.
--doseps-reverse
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 72
dpi.
--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
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
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-errors
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
use gswin32c.exe.
--gs-args arguments
Specify additional Ghostscript arguments. This might be used to
select anti-aliasing with "-dTextAlphaBits=4
-dGraphicsAlphaBits=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.
--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. 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.
--quiet
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.
--replace-composite
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
--custom-colours.
MACINTOSH
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 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 is 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.
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 or /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, --mac-double, --mac-binary or --mac-rsrc.
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 (see Examples).
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.
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 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 the
CMYK image using --dpi.
When replacing the composite page with a CMYK image using
--replace-composite, 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: 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
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 and ._tiger.eps need to be on a
foreign file system accessible to the Mac.
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.
NOTES
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.
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.
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).