epstool

EPSTOOL - Create or extract preview images in EPS files.
Release date: 2002-09-17

Table of contents

• Overview
• Encapsulated PostScript Format
• Previews
• Commands
• Options
• DCS 2.0
• Examples
• Notes
• Copyright
• Compiling
• Other tools
• Revision History

Overview

Epstool is a utility to create or extract preview images in EPS files.

Features:

• Add Interchange (EPSI) or DOS EPS preview.
• Extract PostScript or preview from DOS EPS files.
• Create preview using ghostscript.
• Automatically calculate bounding box using ghostscript and update in EPS file.
• Handle DCS 2.0.
• Works under Win32 and Unix.

Usage: epstool command [options] input_filename output_filename

Commands (one only):

  --add-tiff6p-preview       or  -t6p
  --add-tiff6u-preview       or  -t6u
  --add-tiff4-preview        or  -t4
  --add-tiff-preview         or  -tg
  --add-interchange-preview  or  -i
  --add-metafile-preview     or  -w
  --add-user-preview filename
  --dcs2-multi
  --dcs2-single
  --dcs2-report
  --extract-postscript       or  -p
  --extract-preview          or  -v
  --bitmap
  --copy
  --help                     or  -h

  --bbox                     or  -b
  --custom-colours filename
  --debug                    or  -d
  --device name
  --dpi resolution
  --dpi-render resolution
  --ignore-warnings
  --ignore-errors
  --gs command
  --gs-args arguments
  --missing-separations
  --quiet
  --replace-composite

Encapsulated PostScript Format (EPS)

Previews

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 does not support this format.

Commands

One of the following commands must be specified. Trying to use more than one command isn't helpful.

--add-tiff6p-preview or -t6p

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.

--add-tiff6u-preview or -t6u

Add a TIFF 6 uncompressed preview. See --add-tiff6p-preview for how to add a greyscale or monochrome preview.

--add-tiff4-preview or -t4

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.

--add-tiff-preview or -tg

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.

--add-interchange-preview or -i

Add a monochrome interchange preview

--add-metafile-preview or -w

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

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

--extract-postscript or -p

Extract the PostScript section from a DOS EPS file.

--extract-preview or -v

Extract the preview section from a DOS EPS file.

--help or -h

Display a summary of the epstool commands and options.

Options

--bbox or -b

Calculate the bounding box using the ghostscript bbox device and update in the EPS file.

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

--debug or -d

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.

--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 down sample 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-warnings

Ignore warnings from the DSC parser. Use at your own risk. You really should fix the EPS file first. Note that epstool normally outputs a number of information lines about the DSC comments, including lines that are not recognised by the DSC parser. These are often not warnings.

--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"

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

--quiet

Try to run without writing to standard output.

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

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)

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

EPS file has incorrect %%BoundingBox. Add TIFF4 preview and calculate %%BoundingBox from bitmap.
  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. Typically used when an application can export EPS and WMF separately but can't export EPS with WMF preview.
  epstool --add-user-preview logo.wmf logo.eps output.eps

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 it's 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.

Copyright

Copyright (C) 1995-2002 Ghostgum Software Pty Ltd. All rights reserved.

This software is provided AS-IS with no warranty, either express or implied.

This software is distributed under licence and may not be copied, modified or distributed except as expressly authorised under the terms of the licence contained in the file LICENCE in this distribution.

For more information about licensing, please refer to http://www.ghostgum.com.au/ or contact Ghostsgum Software Pty Ltd, 218 Gallaghers Rd, Glen Waverley VIC 3150, AUSTRALIA, Fax +61 3 9886 6616.

Author: Russell Lang, Ghostgum Software Pty Ltd
Internet: gsview at ghostgum.com.au

Compiling

To compile epstool on Unix, make sure that makefile includes src/unix.mak then use
  make epstool

To compile epstool on MS-Windows, use
  nmake -f srcwin/windows.mak VCVER=7 VCDRIVE=C: LIBPNGINC= LIBPNGCFLAGS= LIBPNGLIBS= epstool

Other tools

Other tools that can add previews to EPS files are

• GSview (same code as epstool)
• ps2epsi, which is part of Ghostscript. This only adds Interchange previews.
• ps2epsplus for creating Mac EPS files on a Mac.
• ps2epsmac for creating Mac EPS files under Unix.

Revision History

3.0 2002-09-17

Major rewrite.
Command line changes.
Use ghostscript bbox device for calculating bounding box.
Supports multiple file DCS 2.0.
Add preview to single file DCS 2.0.
Replace composite page of DCS 2.0 with an image derived from the separations.
Down sample images to provide anti-aliasing.
Removed option to extract a page from a multipage file. The input file must now be EPS.

2.2 2002-04-30

Release with GSview 4.3.
Fixed bug in extracting a page.
Handle single file DCS 2.0.
Added '-k' to create a bitmap of the EPS.

2.1 2002-02-07

Release with GSview 4.2.

2.0 2001-11-23

Release with GSview 4.1.
Remove %%BoundingBox from trailer when adding it to header.

1.92 2001-10-20

Release with GSview 4.05 beta.
Added -aargs to separate arguments from -g. This is needed because program name is surrounded by quotes and so some shells were treating the arguments as part of the program name.

1.91 2001-10-06

Release with GSview 4.03 beta.

1.9 2001-07-27

Release with GSview 4.01 beta.
Ignore DSC warnings with -e1, ignore DSC errors with -e2.

1.8 2001-06-02

Release with GSview 4.0.

1.7 2001-03-30

Allow DSC warnings to be ignored with -e.

1.6 2000-12-28

Release with GSview 3.6.
Write correct page ordinal when extracting a page.
Correctly handle DOS EPS files again.

1.5 2000-12-16

Release with GSview 3.5.

1.32 2000-11-06

Updated DSC parser.
Release with GSview 3.41 beta.

1.4 2000-06-30

Fixed handling of files without trailers.

1.3 2000-06-25

Put quotes around Ghostscript EXE name for Windows, OS/2 and Unix. Released with GSview 3.1.

1.21 2000-06-15

Minor fixes for Linux build.

1.2 2000-06-15

Release with GSview 3.0.

1.10 2000-04-01

Fixes to DSC parser.

1.09 2000-03-11

New DSC parser.
Added #pragma pack(1) needed by MSVC++.
Modified BMP reading so it works even if byte packing not used.
, BMP reading might now work with big-endian architectures, so might be able to use BMP devices on Unix (if compiled into Ghostscript). (Untested).

1.08 2000-02-15

Fixed incorrect switch statement in psfile_extract_header()
Fixed -b -c to change the first line to EPS.
Added -sWIDTHxHEIGHT for use with -b -c and large page sizes.

1.07 1998-12-23

Cope with badly written EPS files that leave items on the stack or dictionary stack.

1.06 1998-09-13

Page calculation for descending page order was wrong.
If a multipage non-EPS file was used as input, the output didn't contain the correct single page (or copied garbage).
Added macro for SUNOS4 to use bcopy instead of memmove.

1.05 1997-12-09

When calculating the bounding box from a bitmap, round the area outwards by 0.5 pixels.

1.04 1997-11-29

Released with GSview 2.4

1.03 1997-09-22

TIFF4 preview didn't work from 24bit/pixel source bitmap.
TIFF 6 packbits didn't compress properly for some data (and consquently caused heap corruption).
Fixed TIFF 6 output when using palette (4 or 8 bit/pixel).

1.02 1997-02-15

Removed requirement for EPS file to use showpage.
Added -c to allow correction of %%BoundingBox
When calculating %%BoundingBox, render to a page of letter width and A4 height.
Avoid integer overflow on 16bit machines when calculating width and height.
If TEMP undefined, default to /tmp on Unix.

1.01 1996-11-07

Release separate from GSview. No code changes.
Includes Win32 (epstool.exe) and OS/2 (epstool2.exe) EXEs.

1.0 1996-10-13

Not a beta version. Included with GSview 2.1.

0.81 beta 1996-09-12

Added TIFF packbits compression.
Added -zdevice.
-t5 replaced by -t6u, -t6p.
-wdevice replaced by -w -zdevice
-ttiff3 replaced by -tg -ztiffg3

0.8 beta 1996-09-09

Makefile target for Win32.
Add WMF for all platforms.
Removed restriction that structures must be byte aligned under Unix.
Must still be byte aligned under DOS and OS/2.

0.7 alpha 1995-10-20

Fixed a few error messages.
Use @file to reduce Ghostscript command line length under MS-DOS and OS/2.
Added -q option to GSview and -dQUIET option to Ghostscript command line to allow EPS files to be written to stdout.

0.6 alpha 1995-10-12

Delete temporary bmp file.
Add user supplied preview to a DOS EPS file (which already had a preview) was wrong.

0.5 alpha 1995-09-27

Put stdout into binary mode.
Write placeable WMF header correctly on 32bit and big-endian machines.

0.4 alpha 1995-09-15

Remove placeable WMF header when adding to EPS file, add placeable
WMF header when extracting from EPS file.

0.3 alpha 1995-09-14

First release separate from GSview.

End of epstool documentation