- background, foreground, frame, label, and page colors,
- BoundingBox adjustment and measurement,
- checking for non-EPS operators,
- clipping,
- framing,
- image rotation, scaling, and translation,
- linewidth scaling,
- page magnification and translation, and
- PostScript alteration.
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 6200 bytes larger for each rotation because of the wrapper overhead. That overhead could be reduced to about 4100 bytes by eliminating extra spaces and comments beginning with a single percent; readability is, however, considered more important.
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 later, 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. For convenience, here are conversion tables for these units:
_____________________________________________________________________________ | | | |uni| 1bp 1cc 1cm 1dd 1in | |___|_______________________________________________________________________| | b| 1 12.7921 28.3465 1.06601 72 | | c| 0.078173 1 2.21593 0.0833333 5.62846| | c| 0.0352778 0.451278 1 0.0376065 2.54 | | d| 0.938077 12 26.5911 1 67.5415 | | i| 0.0138889 0.177669 0.393701 0.0148057 1 | | m| 0.352778 4.51278 10 0.376065 25.4 | | p| 0.0836458 1.07001 2.37106 0.0891674 6.0225 | | p| 1.00375 12.8401 28.4528 1.07001 72.27 | | s| 65781.8 841489 1864680 70124.1 4736287 | |___|_______________________________________________________________________|
________________________________________________________________ | | | |uni| 1mm 1pc 1pt 1000000sp | |___|__________________________________________________________| | b| 2.83465 11.9552 0.996264 15.2018 | | c| 0.221593 0.934572 0.077881 1.18837 | | c| 0.1 0.421752 0.035146 0.536285| | d| 2.65911 11.2149 0.934572 14.2604 | | i| 0.0393701 0.166044 0.013837 0.211136| | m| 1 4.21752 0.35146 5.36285 | | p| 0.237106 1 0.0833333 1.27157 | | p| 2.84528 12 1 15.2588 | | s| 186468 786432 65536 1000000 | |___|__________________________________________________________|
Letter case is significant in option names and dimension units.
Several options may be assigned lists of items. List items must be separated by any single character other than a letter, digits, plus, minus, or period. However, multiple spaces are reduced to single spaces before extracting list items. Comma or slash is a readable choice for a separator character, and avoids the need to quote the values to protect them from possible shell interpretation.
Color values can be provided in several different color models, set by the COLORMODEL=[CMYK|GRAY|HSB|RGB|X] option. In most cases, epsutil can guess the color model from the syntax of the color value, so that the COLORMODEL option rarely needs to be set.
A color can be specified as:
- a color name (e.g. red, green, blue, skyblue, bisque, ...) [letter case is not significant];
- a hexadecimal color (e.g. #3af, #33aaff, #333aaafff, #3333aaaaffff) in the X Window System RGB model;
- a triple of numbers, each in the range 0..1, for the RGB and HSB models;
- a quadruple of numbers, each in the range 0..1, for the CMYK model;
- a single number in the range 0..1 for the GRAY model.
Color names are looked up in the file specified by the RGBFILE=rgbfile option, or, if that is not given, in the X Window System rgb.txt color mapping file. These files associate red, green, and blue intensities with color names; their lines contain three numbers in the range 0..255, followed by a color name, separated by whitespace. 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 in order to get Italian color names.
Hexadecimal colors in the X Window System color model specify red, green, and blue intensities on a scale of 0..15 (3 hexadecimal digits), 0..255 (6 hexadecimal digits), 0..4095 (9 hexadecimal digits), or 0..65536 (12 hexadecimal digits). Thus, #3cf corresponds to 3/15 red, 12/15 green, and 15/15 blue, that is, 0.2 red, 0.8 green, and 1.0 blue.
In the RGB model, three numbers in the range 0..1 define red, green, and blue intensities. In this model, major colors are:
Black 0 0 0| Blue 0 0 1 Red 1 0 0| Magenta 1 0 1 Green 0 1 0| Cyan 0 1 1 Yellow 1 1 0| White 1 1 1
Like the RGB model, the HSB (hue, saturation, brightness) model also has three numbers in the range 0..1. 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). The HSB model is the only one for which COLORMODEL must be defined, because epsutil otherwise assumes a default RGB model, and other models can be determined from context.
The color printing-industry standard CMYK (cyan, magenta, yellow, black) model requires four numbers in the range 0..1. The first three are values for cyan, magenta, and yellow (0 means no color, 1 means full color). The fourth value is the amount of black (0 means none, 1 means completely black) to be added to darken the color.
Finally, in the GRAY model, a single number in the range 0..1 defines the amount of gray: 0 is black and 1 is white. A value of g in the GRAY model is equivalent to g,g,g in the RGB model.
Sample options:
FG=HotPink4 BG=0.9 (GRAY assumed) PAGEBG=1,1,0 (RGB assumed) RGBFILE=mycolors.rgb IDBG=#7ed (X assumed) COLORMODEL=HSB BG=0.6,0.8,0.9 FG=0.5,1,0.8,0.7 (CMYK assumed)
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. 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. See the CLIP option description following.
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
The grid is always drawn after the image, so that it cannot be overwritten by it.
The default grid is in standard PostScript units of big points, and is matched to the selected paper size, leaving a small margin near the page edges where most PostScript printers are incapable of printing.
For greater control, you can specify suitable values for the GRIDX and GRIDY options. These each take the form of a list of up to ten items: minimum number, numbering stepsize, maximum number, dimension unit name, grid stepsize, tick stepsize, tick length, thickening multiple, font size, and font name. List items can be omitted, in which case internal defaults corresponding to the selected paper type will be supplied; see the Paper type section later. As with ordinary coordinate values, an omitted dimension on a number defaults to big points.
The default setting for the horizontal axis on American standard A-format letter paper is GRIDX=50bp,25bp,575bp,bp,25bp,5bp,5bp,100bp,9bp,Helvetica. This means that the axis will run from 50bp in steps of 25bp to 575bp, using units of big points, with grid lines every 25bp, tick marks 5bp long every 5bp, grid lines thickened at multiples of 100bp, with text in a 9bp-Helvetica font. Thus, the axis will be numbered 25, 75, 100, ..., 550, 575, with grid lines drawn at the numbers, and 5 tick intervals between each pair of grid lines. If the eighth value were changed from 100bp to 0bp, then grid line thickening would be suppressed.
Sample options:
GRID=0 GRID=1 GRIDX=,,,,,,,100bp GRIDX=,,,,,,,,18bp,Times-Bold GRIDX=50bp,25bp,575bp,bp GRIDX=0bp,50bp,600bp,bp,5bp,5bp,5bp,100bp,9bp,Palatino-BoldItalic GRIDY=0cm@1cm@25cm@cm@1cm@1mm@@5cm GRIDY=0in,1in,11in,in GRIDY=0in:1in:11in:in GRIDY=0/50/700
The label location is measured on the output page, relative to the lower-left corner, independent of geometric transformations. The label is drawn after the image and the grid, in a shaded box which hides what lies under it.
An optional third value defines the font size (default: 24bp), and an optional fourth value defines the font name (default: Helvetica-Bold).
The font size is automatically reduced to fit a long label into the available space, so that it will always be completely visible.
For convenience, the special assignment ID=1 will produce a label in a default position, near the top of the page.
Sample options:
ID=1 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 MX, MY, and MXY options define magnification factors which are applied after page translation, and before all other transformations. MX and MY are used if provided; otherwise, MXY is used for both x and y scaling. If none of these is specified, then no page magnification is done; this is equivalent to setting MXY=1.
The page location about which magnification is done is (PMX,PMY), or (PMXY,PMXY) if PMX and PMY are not provided. The default page location is the lower-left corner, (0bp,0bp).
As a convenience, symbolic coordinates of nine points of the BoundingBox (four corners, four edge centers, or box center) may be used for the page location values: combine a corner/edge/center designator L (left), R (right), B (bottom), T (top), C (center), or alternatively, compass-point names, with an additional coordinate designator X or Y for PMX and PMY,