1EPSTOOL(1)                  General Commands Manual                 EPSTOOL(1)
2
3
4

NAME

6       epstool - Edit preview images and fix bounding boxes in EPS files.
7
8

SYNOPSIS

10       epstool command [ options ] inputfile outputfile
11
12

DESCRIPTION

14       epstool  is a utility to create or extract preview images in EPS files.
15       It can also calculate optimal bounding boxes.
16
17
18   EPS (Encapsulated PostScript Format)
19       EPS is a specialised form of a PostScript file that complies  with  the
20       Document  Structuring  Conventions (DSC) and is intended to be embedded
21       inside another PostScript file.  An EPS file  must  contain  a  special
22       first  line  that  identifies  it  as  an EPS file (e.g. %!PS-Adobe-3.0
23       EPSF-3.0) and it must contain a %%BoundingBox: line.  The EPS file only
24       draws within the rectangle defined by the bounding box.  The PostScript
25       code must avoid using PostScript operators that  would  interfere  with
26       the  embedding.   These  include  operators with global effects such as
27       changing the page size and changing the half tone screen.
28
29
30   PREVIEWS
31       EPS files may contain a preview to  be  used  by  programs  that  can't
32       interpret the PostScript code. There are three ways to add a preview to
33       an EPS file.
34
35
36       Interchange
37              This preview is included within PostScript comments in a section
38              marked  %%BeginPreview: / %%EndPreview. The actual image data is
39              stored in hexadecimal format. This format is most commonly  used
40              on Unix.
41
42
43       DOS EPS
44              The  preview is a TIFF or Windows Metafile. A DOS EPS file has a
45              30 byte binary header which gives offsets and  lengths  for  the
46              PostScript, TIFF and Windows Metafile sections. You can't send a
47              DOS EPS file directly to a printer -  you  have  to  remove  the
48              binary  header  and  preview first. This format is most commonly
49              used on MS-Windows.
50
51
52       PICT   The preview is in PICT format stored in the resource fork of the
53              file.   This  format  is  most  commonly used on the Macinstosh.
54              Epstool provides limited support for this format.
55
56

COMMANDS (one only):

58       -t4, --add-tiff4-preview
59              Add a TIFF 4 preview. The preview is monochrome and is  intended
60              for  use  with  old programs that won't read TIFF6, such as Word
61              Perfect 5.1 for DOS.
62
63
64       -t6u, --add-tiff6u-preview
65              Add a TIFF 6 uncompressed preview. See --add-tiff6p-preview  for
66              how to add a greyscale or monochrome preview.
67
68
69       -t6p, --add-tiff6p-preview
70              Add a TIFF 6 preview compressed with packbits (simple run length
71              encoding). The preview will normally be full colour, but you can
72              make  it  greyscale  by  adding  the  option --device bmpgray or
73              --device  pgmraw,  or  monochrome  using  --device  bmpmono   or
74              --device pbmraw.
75
76
77       -tg, --add-tiff-preview
78              Add  a TIFF preview using ghostscript to generate the TIFF file.
79              You must specify a suitable TIFF device using --device.  If  you
80              want  a  compressed  monochrome  image,  you  might use --device
81              tiffg3.
82
83
84       -i, --add-interchange-preview
85              Add a monochrome interchange preview.
86
87
88       -w, --add-metafile-preview
89              Add a Windows Metafile (WMF) preview. The metafile will  contain
90              a  bitmap,  not vector information. The preview will normally be
91              full colour. See --add-tiff6p-preview for how to add a greyscale
92              or monochrome preview.
93
94
95       --add-pict-preview
96              Add  a Mac PICT preview.  EPSF files with PICT previews can gen‐
97              erally be used only on Mac computers.  The preview will be  full
98              colour.   The AppleSingle and MacBinary formats will contain the
99              EPSF and the preview.  The AppleDouble or Resource  format  will
100              contain  the  preview  only  and needs to accompany the original
101              EPSF  file.   To  specify  the  file  format  use  --mac-single,
102              --mac-double, --mac-binary or --mac-rsrc.
103
104
105       --add-user-preview  filename
106              Add  a user supplied image as a preview. The image can be a Win‐
107              dows bitmap, a PBMPLUS file, a TIFF image or a Windows Metafile.
108              Window bitmaps and PBMPLUS files will be converted to TIFF6 com‐
109              pressed with packbits. TIFF and Windows Metafile images will  be
110              added unchanged.
111
112
113       --bitmap
114              Create  a  bitmap  of  the area within the EPS bounding box. The
115              bitmap type must be specified with --device.   If  processing  a
116              DCS  2.0  file, the separation can be specified with --page-num‐
117              ber.
118
119
120       --copy Copy the EPS file. This is generally used with the --bbox option
121              to update the bounding box.
122
123
124       --dcs2-multi
125              Convert  DCS  2.0 separations to multiple files. See DCS 2.0. If
126              the output name is out.eps, then the separations would be  named
127              out.eps.Cyan etc.
128
129
130       --dcs2-single
131              Convert DCS 2.0 separations to a single file. See DCS 2.0.
132
133
134       --dcs2-report
135              Write  the separation names, lengths and CMYK values to standard
136              output. This can be used to identify if a DCS 2.0 file is  miss‐
137              ing the composite page or preview.
138
139
140       --dump Display some information about the file type and DSC comments.
141
142
143       -p, --extract-postscript
144              Extract the PostScript section from a DOS EPS file.
145
146
147       -v, --extract-preview
148              Extract the preview section from a DOS EPS file.
149
150
151       -h, --help
152              Display a summary of the epstool commands and options.
153
154
155       --test-eps
156              Partially test if a file complies with the EPSF specification.
157
158

OPTIONS

160       -b, --bbox
161              Calculate the bounding box using the ghostscript bbox device and
162              update in the EPS file.
163
164
165       --combine-separations  filename
166              Combine the separations of the input DCS 2.0 file with those  of
167              this file.  It is an error if the bounding boxes do not match or
168              they contain separations with the same name.  This  option  must
169              be  used with --dcs2-multi or --dcs2-single.  The composite page
170              may later need to be updated with --replace-composite.
171
172
173       --combine-tolerance  pts
174              When using --combine-separations, allow the  bounding  boxes  to
175              vary  by  up  to  pts  points.  The default is 0 so the bounding
176              boxes must match exactly.
177
178
179       --custom-colours  filename
180              When using --replace-composite  on  a  DCS  2.0  file,  use  the
181              colours  specified in this file in preference to those specified
182              in the composite page.
183
184
185       -d, --debug
186              Be more verbose about progress. Do not remove temporary files.
187
188
189       --device name
190              Specify a ghostscript device to be used when creating  the  pre‐
191              view  or  bitmap. For --add-tiff-preview this must be one of the
192              ghostscript tiff devices (e.g. tiffg3, tiff24nc).  For any other
193              preview,  it  must  be  one  of the bmp or pbmplus devices (e.g.
194              bmpgray, bmp16m, pgmraw, ppmraw). For bitmap  output  (--bitmap)
195              it can be any ghostscript bitmap device.
196
197
198       --doseps-reverse
199              When  writing  a DOS EPS file (TIFF or WMF preview), the default
200              is  to  write  the  PostScript  before   the   preview.    Using
201              --doseps-reverse puts the preview before the PostScript section,
202              which is required by some buggy programs.  Either order is  cor‐
203              rect.
204
205
206       --dpi resolution
207              Set  the  resolution of the preview or bitmap. The default is 72
208              dpi.
209
210
211       --dpi-render resolution
212              Render at a higher resolution set by --dpi-render ,  then  down‐
213              sample  to the resolution set by --dpi. This works when adding a
214              preview image or using --replace-composite , but not when  using
215              --bitmap.   This  improves the preview quality when the original
216              contains a pre-rendered image and --dpi-render is set  to  match
217              the original target printer.
218
219
220       --ignore-information
221              Ignore  information  messages  from the DSC parser.  Use at your
222              own risk.  These messages usually  indicate  that  something  is
223              wrong  with  an  EPS  file,  but that most EPS handlers probably
224              won't care.  An example is a line with more than 255 characters.
225
226
227       --ignore-warnings
228              Ignore warnings from the DSC parser.   Use  at  your  own  risk.
229              These messages are usually about faults in the DSC comments that
230              are recoverable by epstool, but may confuse other EPS  handlers.
231              An  example  is  a  bounding  box that incorrectly uses floating
232              point numbers instead of integer.
233
234
235       --ignore-errors
236              Ignore warnings from the DSC parser. Use at your own  risk.  You
237              really should fix the EPS file first.
238
239
240       --gs command
241              Specify the name the ghostscript program. On Unix the default is
242              gs.  On Windows, epstool will check the registry  for  installed
243              versions  of  ghostscript  and use the latest, otherwise it will
244              use gswin32c.exe.
245
246
247       --gs-args arguments
248              Specify additional Ghostscript arguments. This might be used  to
249              select   anti-aliasing   with  "-dTextAlphaBits=4  -dGraphicsAl‐
250              phaBits=4"
251
252
253       --output filename
254              Specify the output file (instead of using the second file param‐
255              eter).  Using the filename - causes epstool to write to standard
256              output, which requires the use of --quiet.
257
258
259       --mac-binary
260              When adding a PICT preview, use the MacBinary I format.  for the
261              Mac
262
263
264       --mac-double
265              When  adding  a PICT preview, use the AppleDouble format for the
266              Mac.
267
268
269       --mac-rsrc
270              When adding a PICT preview, use the Resource format for the Mac.
271
272
273       --mac-single
274              When adding a PICT preview, use the AppleSingle format  for  the
275              Mac.
276
277
278       --missing-separations
279              When  writing  a  DCS  2.0 file, epstool will normally fail if a
280              separation is missing.  When this option is used, it will remove
281              references to missing separations when writing the file.
282
283
284       --page-number page
285              When  creating  a bitmap with --device from a DCS 2.0 file, page
286              specifies the separation to be used.  Page 1  is  the  composite
287              and  page  2  is the first separation.  Use --dcs2-report to get
288              the list of separations.
289
290
291       --quiet
292              Try to run without writing to standard output.
293
294
295       --rename-separation oldname newname
296              When copying a DCS 2.0 file with --dcs2-multi or  --dcs2-single,
297              rename  separation with oldname to newname.  This option implies
298              --missing-separations.  It is assumed that the new name is  just
299              an alias for the same colour and that the CMYK or RGB values for
300              the separation are not changed.  This option may be used  multi‐
301              ple  times.  This must be used if the input file incorrectly has
302              two separations of the same name.
303
304
305       --replace-composite
306              Some DCS 2.0 files do not have an image in the  composite  page.
307              This  option  replaces  the  composite  page  with  a CMYK image
308              derived from the separations. This  option  must  be  used  with
309              --dcs2-multi  or  --dcs2-single.  See also the options --dpi and
310              --custom-colours.
311
312
313

MACINTOSH

315       The Macintosh does not use a flat file system.  Each file  can  have  a
316       data  fork  and a resource fork.  EPSF files have the PostScript in the
317       data fork, and optionally have a preview in the resource fork as a PICT
318       image.   In addition, file type is obtained from the finder info rather
319       than a file extension.  File types use a four character  code  such  as
320       "EPSF"  or  "PICT".   When Macintosh files are copied to a foreign file
321       system, the resource fork may be left behind.  Alternatives  to  retain
322       the  resource  fork  are  to  package  the  finder  data, data fork and
323       resource fork in a single MacBinary or AppleSingle file, or to put  the
324       data  fork  in  a flat file and the finder info and resource fork in an
325       AppleDouble file.  The Mac OSX finder  will  handle  AppleDouble  files
326       automatically  when  copying  files  to and from a foreign file system.
327       When copying test.eps to a foreign file system, the data fork would  be
328       written as test.eps and the finder info and resource fork to the Apple‐
329       Double file ._test.eps or .AppleDouble/test.eps.
330
331       Epstool can read MacBinary and AppleSingle files.  It can write  MacBi‐
332       nary  I,  AppleSingle, AppleDouble or Resource files.  Files written by
333       epstool will have type EPSF and creator MSWD.  When adding a preview to
334       test.eps,   it   is  suggested  that  you  create  the  MacBinary  file
335       test.eps.bin.  On a Macintosh computer you then need to extract it with
336       StuffIt Expander.  Another alternative is to write the AppleDouble file
337       to ._test.eps then copy both files to a file system accessible to a Mac
338       computer.
339
340       If the output file name starts with . then AppleDouble will be assumed,
341       otherwise if it ends with .as then AppleSingle will be assumed,  other‐
342       wise if it ends with .rsrc or /rsrc then Resource will be assumed, oth‐
343       erwise MacBinary will be assumed.  When writing a MacBinary file, it is
344       recommended that you end the filename in .bin.  To force the file type,
345       use --mac-single, --mac-double, --mac-binary or --mac-rsrc.
346
347       On Mac OS X you can access a file's resource  fork  from  command  line
348       tools by appending /rsrc to the original file name.  The easiest way to
349       add a preview to the file test.eps on Mac OS X is to let epstool  write
350       in --mac-rsrc format to test.eps/rsrc (see Examples).
351
352

DESKTOP COLOR SEPARATIONS (DCS 2.0)

354       The  Desktop  Color  Separation  (DCS) image file format contains a low
355       resolution preview, a main file  with  the  full  resolution  composite
356       image,  and  colour  separations with full resolution separated plates.
357       The separations will typically contain Cyan, Magenta, Yellow, Black and
358       possibly spot colours.  There are two versions of DCS 2.0.
359
360
361       Multiple File
362              The  main  file  contains %%PlateFile: (name) EPS Local filename
363              comments which give the filenames of the separation plates.  The
364              main  file  may  contain  a low resolution DOS EPS preview.  The
365              separation files do not contain previews.
366
367
368       Single File
369              This is an abuse of the EPS specification.  The single file con‐
370              tains  the  main file and the separations concatenated together,
371              which makes the DSC comments incorrect.  The main file specifies
372              the  byte  offsets  to the separations using %%PlateFile: (name)
373              EPS #offset size.  The single file may then be placed  inside  a
374              DOS EPS file with a low resolution preview.  By default, epstool
375              writes single file DCS 2.0.
376
377
378       Epstool can add previews to single and multiple file DCS 2.0.   It  can
379       split  single  file  DCS  2.0 into multiple files and vice versa.  This
380       allows a single file DCS 2.0 to be split, the composite image replaced,
381       a new preview created, and then be recombined into a single file.
382
383       Some  DCS  2.0  files  do  not have an image in the composite page.  To
384       determine if  the  composite  page  does  not  contain  an  image,  use
385       --dcs2-report  and  look to see if the composite section is very short.
386       Using --dcs2-single --replace-composite  replaces  the  composite  page
387       with the headers of the original composite page and a body containing a
388       CMYK image derived from the separations.  Set  the  resolution  of  the
389       CMYK image using --dpi.
390
391       When   replacing   the   composite   page   with  a  CMYK  image  using
392       --replace-composite, the --custom-colours option is useful for  dealing
393       with DCS 2.0 files that have incorrect CMYK colours, for example speci‐
394       fying that the varnish layer is grey.  Each line of  the  CMYK  colours
395       file  is  formatted  like a DSC %%CMYKCustomColor: or %%RGBCustomColor:
396       line, as shown in the example below.
397
398
399       %%CMYKCustomColor: 0.00 0.00 0.00 0.00 Varnish
400
401       %%CMYKCustomColor: 1.00 0.68 0.00 0.12 (Dark Blue)
402
403       %%RGBCustomColor: 0.5 0.0 0.0 (Dark Red)
404
405       DCS2 files should not have two separations with the same name.  Epstool
406       will  not  allow a DCS2 output file to have duplicate separation names.
407       Use --rename-separation to resolve this.
408
409

EXAMPLES

411       Add colour preview (24bit/pixel) to EPS file
412                epstool -t6p tiger.eps output.eps
413
414
415       Add TIFF (G3 Fax) preview to tiger.eps.
416                epstool  --add-tiff-preview  --device  tiffg3  tiger.eps  out‐
417              put.eps
418
419       Any GS TIFF device can be used, e.g. tiffg4, tiffpack
420
421
422       Extract TIFF preview from tiger.eps
423                epstool -v tiger.eps tiger.tif
424
425
426       Fix incorrect %%BoundingBox then add TIFF4 preview.
427                epstool --bbox -t4 golfer.eps output.eps
428
429
430       Adjust  the  BoundingBox  of an existing EPS file, but don't add a pre‐
431       view:
432                epstool --copy --bbox input.eps output.eps
433
434
435       Add user supplied Windows Metafile to EPS file.
436                epstool --add-user-preview logo.wmf logo.eps output.eps
437
438       Typically used when an application can export EPS  and  WMF  separately
439       but can't export EPS with WMF preview.
440
441
442       Add a PICT preview and write an AppleDouble file.
443                epstool --add-pict-preview --mac-double tiger.eps ._tiger.eps
444
445       To  be  used  by  a Mac, both tiger.eps and ._tiger.eps need to be on a
446       foreign file system accessible to the Mac.
447
448
449       Add a PICT preview, overwriting the existing resources.
450               epstool --add-pict-preview --mac-rsrc tiger.eps tiger.eps/rsrc
451
452       On Mac OS X you can access a file's resource  fork  from  command  line
453       tools by appending "/rsrc" to the file's original name.
454
455

NOTES

457       When  adding a WMF preview to an EPS file using -add-user-preview file‐
458       name, the placeable metafile header is removed from the metafile as  it
459       is  put  into  the EPS file.  When extracting a WMF preview from an EPS
460       file, a placeable metafile header is created from the  EPS  BoundingBox
461       information.   This  placeable metafile header assumes that the WMF has
462       its origin at (0,0), which might not be correct.
463
464       When epstool is creating a TIFF or WMF preview, it will convert palette
465       colour images into 24-bit/pixel.
466
467       The environment variable TEMP should point to a writeable directory for
468       temporary files.  If not defined, /tmp will be used for  Unix  and  the
469       current directory will be used for other platforms.
470
471
472

AUTHOR

474       epstool was written by Russell Lang <gsview@ghostgum.com.au>
475
476       This man page was contributed by Martin Pitt <martin@piware.de> for the
477       Debian GNU/Linux system (but may be used by others).
478
479
480
481
482Martin Pitt and Russell Lang      2005-06-10                        EPSTOOL(1)
Impressum