Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
EPSTOOL(1)		    General Commands Manual		    EPSTOOL(1)

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

       epstool command [ options ] inputfile outputfile

       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.

       EPS files may contain a preview to be used by programs that  can't  in-
       terpret	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  bi-
	      nary 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.  Ep-
	      stool 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 --de-
	      vice pgmraw, or monochrome using --device	 bmpmono  or  --device

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

	      Add  a Mac PICT preview.	EPSF files with	PICT previews can gen-
	      erally 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 Win-
	      dows bitmap, a PBMPLUS file, a TIFF image	or a Windows Metafile.
	      Window bitmaps and PBMPLUS files will be converted to TIFF6 com-
	      pressed 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-num-

       --copy 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
	      out.eps.Cyan etc.

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

	      Partially	test if	a file complies	with the EPSF specification.

       -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  pre-
	      view  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  cor-

       --dpi resolution
	      Set  the	resolution of the preview or bitmap. The default is 72

       --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  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
	      use gswin32c.exe.

       --gs-args arguments
	      Specify additional Ghostscript arguments.	This might be used  to
	      select   anti-aliasing   with  "-dTextAlphaBits=4	 -dGraphicsAl-

       --output	filename
	      Specify the output file (instead of using	the second file	param-
	      eter).  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 the

	      When  adding  a PICT preview, use	the AppleDouble	format for the

	      When adding a PICT preview, use the Resource format for the Mac.

	      When adding a PICT preview, use the AppleSingle format  for  the

	      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	multi-
	      ple  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 de-
	      rived 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 re-
       source 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 au-
       tomatically when	copying	files to and from a foreign file system.  When
       copying test.eps	to a foreign file system, the data fork	would be writ-
       ten  as test.eps	and the	finder info and	resource fork to the AppleDou-
       ble file	._test.eps or .AppleDouble/test.eps.

       Epstool can read	MacBinary and AppleSingle files.  It can write	MacBi-
       nary  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

       If the output file name starts with . then AppleDouble will be assumed,
       otherwise if it ends with .as then AppleSingle will be assumed,	other-
       wise if it ends with .rsrc or /rsrc then	Resource will be assumed, oth-
       erwise 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).

       The  Desktop  Color  Separation	(DCS) image file format	contains a low
       resolution preview, a main file with the	full resolution	composite  im-
       age, 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 con-
	      tains  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 al-
       lows 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 de-
       termine if the composite	page does not contain an image,	use --dcs2-re-
       port  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 im-
       age derived from	the separations.  Set the resolution of	the CMYK image
       using --dpi.

       When  replacing	the  composite	page  with  a  CMYK  image using --re-
       place-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.

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

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

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

       epstool was written by Russell Lang <>

       This man	page was contributed by	Martin Pitt <> for the
       Debian GNU/Linux	system (but may	be used	by others).

Martin Pitt and	Russell	Lang	  2005-06-10			    EPSTOOL(1)


Want to link to this manual page? Use this URL:

home | help