- background color,
- BoundingBox adjustment and measurement,
- checking for non-EPS operators,
- clipping,
- framing,
- linewidth scaling,
- PostScript alteration,
- rotation,
- scaling, and
- translation.
The output file fully conforms to the PostScript Document Structuring Conventions defined in Appendix G of the PostScript Language Reference Manual, Second Edition, Addison-Wesley (1985), ISBN 0-201-10174-2 (the Adobe red book).
The output of this program is also suitable input to it; after four filtering steps with 90-degree rotation selected, the original figure will be recovered, although the output PostScript file will be about 4300 bytes larger for each rotation because of the wrapper overhead.
The original command line that was used to create the output file is preserved in a %%Title comment in the second line of the output file, as a record of the requested transformations.
A verbatim copy of the original file, minus any %%EOF comments, is embedded in the output between the %%BeginDocument and %%EndDocument lines, where it can be recovered simply by stripping the wrapping PostScript.
If no dimension unit is specified in the variable values described below, physical dimensions are assumed to be measured in standard PostScript units of big points:
72bp = 1in = 25.4mm
Otherwise, any of the TeX dimension units of bp (big point), cc (cicero), cm (centimeter), dd (didot point), in (inch), mm (millimeter), pc (pica), pt (point), or sp (scaled point), may suffix a number, and the value will be converted to big points internally.
Five color models are available. The models are tried in alphabetical order: the first one specified is used, and any settings for the others are silently ignored.
For BG, the value is the name of a color found in either the file specified by the RGBFILE=rgbfile option, or else in the X Window System rgb.txt color mapping file. These files associate red, green, and blue intensities with named colors; their lines contain three numbers in the range 0..255, followed by a color name. The rgb.txt file is found by searching a built-in directory path that covers all major UNIX systems; that path can be overridden by defining a value for the environment variable RGBPATH. For example, on an IBM RS/6000 AIX system, you could set that variable to /usr/lpp/X11/lib/X11/It_IT to get Italian color names.
In CMYK, values for cyan, magenta, and yellow are provided (0 means no color, 1 means full color), and then an amount of black (0 means none, 1 means completely black) is added to darken the color.
In GRAY, 0 is black and 1 is white. GRAY=g is equivalent to RGB=g,g,g.
In HSB, hue runs through the rainbow (approximately, red=0, orange=0.1, limegreen=0.2, green=0.3, cyan=0.5, blue=0.6, magenta=0.8, deeppink=0.9, red=1). Saturation goes from 0 (no color == black) to 1 (full color). Brightness goes from 0 (dark) to 1 (bright).
In RGB, major colors are:
Black 0,0,0 Red 1,0,0 Green 0,1,0 Yellow 1,1,0 Blue 0,0,1 Magenta 1,0,1 Cyan 0,1,1 White 1,1,1
Sample options:
BG=bisque CMYK=1,0,0,0.2 GRAY=0.9 HSB=0.5,1,,0.8 RGB=1,1,0 RGBFILE=mycolors.rgb
To avoid the need for modifying the original PostScript file, the two corner coordinate pairs can be specified as four optionally-dimensioned numbers for the value of the BOUNDINGBOX option. The numbers can be separated by any characters other than plus, minus, digits, period, or lowercase letters; comma or slash are readable choices. Values specified this way override those in the %%BoundingBox comment.
When a BOUNDINGBOX value is given, especially if it covers only a portion of the original figure, clipping should be selected.
Although fractional dimensions are accepted, after converting to big points, the values actually used will be rounded down to the nearest integer at the lower-left corner, and up to the nearest integer at the upper-right corner. This is a requirement of the PostScript Document Structuring Conventions.
Sample options:
BOUNDINGBOX=10,20,500,750 BOUNDINGBOX=10 20 500 750 BOUNDINGBOX=0.1in,0.3in,18cm,25cm BOUNDINGBOX=10mm/20mm/30pc/40pc
If linewidth scaling is requested, the frame will also be affected by the scaling.
The output BoundingBox will automatically be enlarged by the twice the frame thickness, and any MAXLINEWIDTH value will be adjusted upward if necessary to ensure that the frame can be drawn properly.
Sample options:
FRAME=3 FRAME=3mm
Because this option requires additional pattern matching on every input line, and is only occasionally needed, the default is CHECK=0 to suppress the check.
Sample options:
CHECK=0 CHECK=1
Although EPS-including programs are supposed to provide this clipping automatically, not all do so. Thus, the default in this program is to turn on clipping.
The clipping path is set after geometric transformations have been completed, but before any drawing operations are performed. Thus, the BoundingBox frame, and the background color, are subject to clipping.
Sample options:
CLIP=0 CLIP=1
Clipping is automatically suppressed when a grid is selected, in order for the complete grid, with its edge labels, to be visible.
Sample options:
GRID=0 GRID=1
An optional third value defines the font size (default: 10bp), and an optional fourth value defines the font name (default: Helvetica).
Values are separated by characters other than plus, minus, digits, period, or letters.
Sample options:
ID=50,750 ID=0.4in/0.4in/12pt ID='10mm 10mm 8pt Helvetica-Narrow'
PostScript allows zero linewidths, which means the thinnest line that the output device is capable of producing. Such linewidths would not be affected by scaling. Thus, a value for MINLINEWIDTH can be given to force all lines to be at least that thick, and therefore, subject to scaling.
To prevent scaling from producing ridiculously thick lines, a MAXLINEWIDTH value can be set to force an upper limit to linewidths. If not specified, it defaults to 24.
If linewidth scaling is applied to a PostScript file that already has linewidth scaling, the two scalings are not cumulative: only the last scaling applied will have any effect. This unfortunate irregularity is a consequence of the inability of the PostScript language to permit redefinition of an operator to more than one level; attempts to do otherwise simply produce infinite loops in the PostScript interpreter.
Sample options:
LINEWIDTHSCALE=3 MAXLINEWIDTH=6 MAXLINEWIDTH=6bp MINLINEWIDTH=0.1pt
The value of PSCODE is a string containing arbitrary literal PostScript code.
The value of PSFILE is the name of one or more comma- or space-separated files whose contents are to be inserted.
When both options are specified, PSFILE is handled before PSCODE, so that any PostScript read from files can be overridden by literal PostScript from the command line.
Sample options:
PSCODE='0 1 0 setrgbcolor'
PSCODE='/setrgbcolor {add add 3 div setgray} bind def'
PSFILE=mymacros.eps
PSFILE=header1.eps,../tools/monochrome.eps
For example, to turn landscape orientation with the right side at the top of the page into portrait orientation, specify ROTATE=-90. It will usually be necessary to supply additional scaling (HEIGHT or WIDTH, or SX, SY, or SXY options) to make the picture fit on the output page.
Unless otherwise specified by the translation variables (see below), the position of the lower-left corner of the BoundingBox on the output display device is kept invariant, so that after a -90-degree rotation, the lower-right corner of the original BoundingBox will be positioned where the lower-left corner was.
Sample options:
ROTATE=0 ROTATE=-90 ROTATE=90 ROTATE=180 ROTATE=270 ROTATE=360 ROTATE=450
Sample options:
OX=0 OY=0 OX=10mm OY=36bp OXY=1in OXY=3pc
The two sizes refer to the final figure, after any rotation.
If both absolute (HEIGHT and WIDTH) and relative (SX, SY, and SXY) scaling are specified, then absolute scaling is done, and the relative scale factors are ignored.
Sample options:
HEIGHT=400bp HEIGHT=15cm WIDTH=340 WIDTH=150mm
Sample options:
SX=0.5 SY=2.0 SXY=0.7727
Encapsulated PostScript is a subset of standard PostScript, and excludes approximately twenty operators whose use can prevent successful inclusion of a PostScript inside another PostScript file, usually because those operators would obviate the use of a local independently-scaled coordinate system, or would modify the global state of the PostScript environment. When the output file fails to conform to the specified transformations, it is usually because of the use of these excluded operators. If requested by the CHECK=1 option, epsutil looks for those operators, and will raise warnings when they are seen. Unfortunately, their apparent absence does not mean that they are not used, because PostScript files can also contain binary, hexadecimal, and other encodings that can hide such operators from view. Thus, the only truly reliable check is visual examination of the output of epsutil with a PostScript previewer or printer, and its successful incorporation in other documents, such as with TeX \epsffile or \special commands, or in word processors.
Nelson H. F. Beebe Center for Scientific Computing Department of Mathematics University of Utah Salt Lake City, UT 84112 USA Tel: +1 801 581 5254 FAX: +1 801 581 4148 Email: <beebe@math.utah.edu> URL: http://www.math.utah.edu/~beebe