# epstool

EPSTOOL - Create or extract preview bitmaps in EPS files.
Release date: 2002-04-30

## Table of contents

- Overview
- Examples
- Notes
- Copyright
- Other tools
- Revision History

## Overview

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

If you have precompiled executables, epstool.exe is a Win32 console EXE, epstool2.exe is an OS/2 console EXE.

Features:

- Add EPSI or DOS EPS previews.
- Extract PostScript from DOS EPS files.
- Uses Ghostscript to create preview bitmaps.
- Scan a bitmap created by Ghostscript to find bounding box.
- Create a TIFF, WMF or Interchange preview from part of a bitmap created by Ghostscript.
- output to stdout or file.
- input must be from a file.
- works under Win32, MS-DOS, OS/2 and Unix.
- works on little-endian machines (Intel) or big endian (Sun Sparc, Motorola) machines.

Usage: epstool [option] operation filename

Options: |
-aarg | Ghostscript argument
-b | Calculate BoundingBox from image
-e | Ignore DSC warnings (dangerous)
-e2 | Ignore DSC errors (very dangerous)
-gcommand | Ghostscript command
-nnumber | Page number to extract
-ofilename | Output filename
-q | Quiet (no messages)
-rnumber | Preview resolution in dpi
-sWIDTHxHEIGHT | Size of page used with -b
-zdevice | Ghostscript device name (for -t6u, -t6p, -tg, -w)
-d | Debug mode (leave temporary files)
Operations: (one only) |
-i | Add Interchange preview (EPSI)
-t4 | Add TIFF4 preview (DOS EPS)
-t6u | Add TIFF6 uncompressed (DOS EPS)
-t6p | Add TIFF6 packbits (DOS EPS)
-tg | Add GS TIFF preview (DOS EPS)
-w | Add WMF preview (DOS EPS)
-ufilename | Add user supplied preview (DOS EPS)
-p | Extract PostScript (DOS EPS)
-v | Extract Preview (DOS EPS)
-c | Copy without preview (use with -b)
-k | Convert to bitmap

## Examples

Create EPS file tiger.eps with TIFF (G3 Fax) preview
`epstool -tg -ztiffg3 -g"gswin32c" -a"-Id:\gs;d:\psfonts" -otiger.eps tiger.ps`
Any GS TIFF device can be used, e.g. -ztiffg4, -ztiffpack

Add colour preview (8bit/pixel) to EPS file
`epstool -t6p -zbmp256 -g"gswin32c" -a"-Id:\gs;d:\psfonts" -otiger.eps tiger.ps`

Extract TIFF preview from tiger.eps
`epstool -v -otiger.tif tiger.eps`

EPS file has incorrect %%BoundingBox. Add TIFF4 preview and calculate %%BoundingBox from bitmap.
`epstool -b -t4 -ogolfer.eps golfer.ps`

Adjust the BoundingBox of an existing EPS file, but don't add a preview:
`epstool -b -t4 -otemp.eps existing.eps
epstool -p -oexisting.eps temp.eps
del temp.eps`
or
`epstool -b -c -otemp.eps existing.eps
del existing.eps
rename temp.eps existing.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 -ulogo.wmf -ologo2.eps logo.eps`

## Notes

When extracting a page number with "-n", it is your responsibility to make sure that the PostScript file does not use any operators that are forbidden in EPS files. This can be tested with GSview "EPS Warn".

Under OS/2 or MS-DOS, epstool requires Ghostscript 3.51 or later. If you have command line length problems, try setting the Ghostscript include path using the GS_LIB environment variable instead of using -a"-Ic:\gs3.51;c:\gs3.51\fonts;c:\psfonts"

For Windows 95 or Windows NT, use gswin32c.exe. If you installed Aladdin Ghostscript using the self installer, epstool should automatically find the latest Ghostscript command line executable. For OS/2, use gsos2.exe. For MS-DOS, use gs386.exe.

The "-b Calculate BoundingBox from image" option works by scanning a bitmap returned by Ghostscript. This will only work for the operations -i, -t4, -t6u, -t6p, -w and -c. It does not work with -tg or -ufilename. -tg does not return a bitmap in a format understood by epstool. -ufilename does not even use Ghostscript. The bitmap size normally used is 216mm wide (letter width) by 297mm high (A4 height). If the DSC comments specify a default page size using %%DocumentMedia or %%PaperSize, then this page size will be used instead. Any marks made outside this area will be ignored when calculating the bounding box. To use a different bitmap size, specify the size in pts (1/72") using -sWIDTHxHEIGHT. For example, A3 is -s1190x842.

The "-zdevice" should only be used with -tg, -t6u, -t6p and -w.

For -tg, the -zdevice may be any TIFF device.

For -t6u, -t6p and -w: Under OS/2 or MS-DOS, -zdevice can be one of the following: bmpmono, bmp16, bmp256, bmp16m, pbmraw, pgmraw, ppmraw Under Unix, -zdevice can be one of the following: pbmraw, pgmraw, ppmraw

To get a colour preview, you must use -zdevice. The default device used by epstool is monochrome (bmpmono or pbmraw).

When adding a WMF preview using -w, the preview contains a bitmap, not a vector representation. If -zdevice is not used, the Ghostscript device bmpmono or pbmraw will be used to create the bitmap. The bitmap in the metafile will be 1bit/pixel black and white.
`epstool -b -w -onew.eps old.eps`
If you want a colour bitmap in the metafile, specify a bitmap device which supports colour.
`epstool -b -w -zbmp256 -onew.eps old.eps`

When adding a WMF preview to an EPS file using -ufilename, 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.

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 file is part of GSview.

This program is distributed with NO WARRANTY OF ANY KIND. No author or distributor accepts any responsibility for the consequences of using it, or for whether it serves any particular purpose or works at all, unless he or she says so in writing. Refer to the GSview Free Public Licence (the "Licence") for full details.

Every copy of GSview must include a copy of the Licence, normally in a plain ASCII text file named LICENCE. The Licence grants you the right to copy, modify and redistribute GSview, but only under certain conditions described in the Licence. Among other things, the Licence requires that the copyright notice and this notice be preserved on all copies.

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

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

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