Man Linux: Main Page and Category List

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