NAME¶
postscriptlight - A PostScript based plotting library
DESCRIPTION¶
PSL (PostScriptLight) was created to make the generation of
PostScript page description code easier. PS is a page description language
developed by the Adobe for specifying how a printer should render a page of
text or graphics. It uses a reverse Polish notation that puts and gets items
from a stack to draws lines, text, and images and even performs
calculations. PSL is a self-contained library that presents a series of
functions that can be used to create plots. The resulting PostScript code is
ASCII text (with some exceptions for images if so desired) and can thus be
edited using any text editor. Thus, it is possible to modify a plot file
even after it has been created, e.g., to change text strings, set new gray
shades or colors, experiment with various pen widths, etc. Furthermore,
various tools exist that can parse PostScript and let you make such edits
via a graphical user interface (e.g., Adobe Illustrator). PSL is written in
C but includes FORTRAN bindings and can therefore be called from both C and
FORTRAN programs. To use this library, you must link your plotting program
with PSL. PSL is used by the GMT graphics programs to generate PS. PSL
output is freeform PostScript that conforms to the Adobe PostScript File
Specification Version 3.0.
Before any PSL calls can be issued, the plotting system must be
initialized. This is done by calling PSL_beginsession, which
initializes a new PSL session; then call PSL_setdefaults which sets
internal variables and default settings, accepts settings for measurement
units and character encoding, and returns a pointer to a struct PSL_CTRL
which must be passed as first argument to all other PSL functions. The
measure unit for sizes and positions can be set to be centimeter (c), inch
(i), meter (m), or points (p). A PSL session is terminated by calling
PSL_endsession. You may create one or more plots within the same
session. A new plot is started by calling PSL_beginplot, which
defines macros, sets up the plot-coordinate system, scales, and [optionally]
opens a file where all the PS code will be written. Normally, the plot code
is written to stdout. When all plotting to this file is done, you
finalize the plot by calling PSL_endplot.
A wide variety of output devices that support PostScript exist,
including many printers and large-format plotters. Many tools exists to
display PostScript on a computer screen. Open source tools such as
ghostscript can be used to convert PostScript into PDF or raster images
(e.g., TIFF, JPEG) at a user-defined resolution (DPI). In particular, the
GMT tool psconvert is a front-end to ghostscript and pre-selects the optimal
options for ghostscript that will render quality PDF and images.
The PSL is fully 64-bit compliant. Integer parameters are here
specified by the type long to distinguish them from the 32-bit
int. Note that under standard 32-bit compilation they are equivalent.
Users of this library under 64-bit mode must make sure they pass proper
long variables (under Unix flavors) or __int64 under Windows
64.
UNITS¶
PSL can be instructed to use centimeters, inches, meters or points
as input units for the coordinates and sizes of elements to be plotted. Any
dimension that takes this setting as a unit is specified as user
units or plot units in this manual. Excluded from this are
line widths and font sizes which are always measured in points. The
user units can be further refined by calling PSL_beginaxes, giving
the user the opportunity to specify any linear coordinate frame. Changing
the coordinate frame only affects the coordinates of plotted material
indicated as measured in plot units, not the sizes of symbols (which
remain in user units), nor line widths or font sizes (which remain in
points).
COLOR¶
PSL uses the direct color model where red, green, and blue are
given separately, each must be in the range from 0-1. If red = -1 then no
fill operation takes place. If red = -3, then pattern fill will be used, and
the green value will indicate the pattern to be used. Most plot-items can be
plotted with or without outlines. If outline is desired (i.e., set to 1), it
will be drawn using the current line width and pattern. PSL uses highly
optimized macro substitutions and scales the coordinates depending on the
resolution of the hardcopy device so that the output file is kept as compact
as possible.
JUSTIFICATION¶
Text strings, text boxes and images can be "justified"
by specifying the corner to which the x and y coordinates of
the subroutine call apply. Nine different values are possible, as shown
schematically in this diagram:
9------------10----------- 11
| |
5 6 7
| |
1------------ 2------------ 3
The box represents the text or image. E.g., to plot a text string
with its center at (x, y), you must use justify == 6.
justify == 0 means "no justification", which generally
means (x, y) is at the bottom left. Convenience values
PSL_NONE, PSL_BL, PSL_BC, PSL_BL, PSL_ML, PSL_MC, PSL_MR, PSL_TL, PSL_TC and
PSL_TR are available.
INITIALIZATION¶
These functions initialize or terminate the PSL system. We use the
term PSL session to indicate one instance of the PSL system (a complicated
program could run many PSL sessions concurrently as each would operate via
its own control structure). During a single session, one or more plots may
be created. Here are the functions involved in initialization:
struct PSL_CTRL *New_PSL_Ctrl (char
*session)
This is the first function that must be called as it
creates a new PSL session. Specifically, it will allocate a new PSL control
structure and initialize the session default parameters. The pointer that is
returned must be passed to all subsequent PSL functions.
long *PSL_beginsession (struct PSL_CTRL *PSL,
long search, char *sharedir, char
*userdir)
This is the second function that must be called as it
initializes the new PSL session. Here, search is an integer that is
passed as 0 in GMT but should be 1 for other users. If so we will search for
the environmental parameters PSL_SHAREDIR and PSL_USERDIR should the
corresponding arguments sharedir and userdir be NULL.
long PSL_endsession (struct PSL_CTRL
*PSL)
This function terminates the active PSL session; it is
the last function you must call in your program. Specifically, this function
will deallocate memory used and free up resources.
struct PSL_CTRL *PSL_beginlayer (struct PSL_CTRL
*PSL, long layer)
Adds a DSC comment by naming this layer; give a unique
integer value. Terminate layer with PSL_endlayer
struct PSL_CTRL *PSL_endlayer (struct PSL_CTRL
*PSL)
Terminate current layer with a DSC comment.
long PSL_fopen (char *file, char
*mode)
This function simply opens a file, just like fopen. The
reason it is replicated here is that under Windows, file pointers must be
assigned within the same DLL as they are being used. Yes, this is retarded but
if we do not do so then PSL will not work well under Windows. Under
non-Windows this functions is just a macro that becomes fopen.
void PSL_free (void *ptr)
This function frees up the memory allocated inside PSL.
Programmers using C/C++ should now this is a macro and there is no need to
cast the pointer to void * as this will be done by the macro. Fortran
programmers should instead call PSL_freefunction.
void PSL_beginaxes (struct PSL_CTRL *PSL,
double llx, double lly, double
width, double height, double x0,
double y0, double x1, double
y1)
This function sets up the mapping that takes the users
data coordinates and converts them to the positions on the plot in PostScript
units. This should be used when plotting data coordinates and is terminated
with PSL_endaxes, which returns PSL to the default measurement units
and scaling. Here, llx and lly sets the lower left position of
the mapping region, while width and height sets the dimension of
the plot area in user units. Finally, x0, x1 and y0,
y1 indicate the range of the users x- and y-coordinates, respectively.
Specify a reverse axis direction (e.g., to let the y-axis be positive down) by
setting y0 larger than y1, and similarly for an x-axis that
increases to the left.
void PSL_endaxes (struct PSL_CTRL *PSL)
Terminates the map scalings initialized by
PSL_beginaxes and returns PSL to standard scaling in measurement
units.
long PSL_beginplot (struct PSL_CTRL *P,
FILE *fp, long orientation, long
overlay, long color_mode, char origin[],
double offset[], double page_size[], char
*title, long font_no[])
Controls the initiation (or continuation) of a particular
plot within the current session. Pass file pointer fp where the
PostScript code will be written; if NULL then the output is written to
stdout. The Fortran interface always sends to stdout. If you
want to receive the PostScript back in memory then you need to add PSL_MEMORY
to orientation and call PSL_getplot to retrieve the plot after
you finish the plot with PSL_endplot. The orientation may be
landscape (PSL_LANDSCAPE or 0) or portrait (PSL_PORTRAIT or 1). Set
overlay to PSL_OVERLAY (0) if the following PostScript code should be
appended to an existing plot; otherwise pass PSL_INIT (1) to start a new plot.
Let colormode be one of PSL_RGB (0), PSL_CMYK (1), PSL_HSV (2) or
PSL_GRAY (3); this setting controls how colors are presented in the PostScript
code. The origin setting determines for x and y separately the origin
of the specified offsets (next argument). Each of the two characters are
either r for an offset relative to the current origin, a for a
temporary adjustment of the origin which is undone during BD(PSL_endplot),
f for a placement of the origin relative to the lower left corner of
the page, c for a placement of the origin relative to the center of the
page. The array offset specifies the offset of the new origin relative
to the position indicated by origin. page_size means the
physical width and height of the plotting media in points (typically 612 by
792 for Letter or 595 by 842 for A4 format). The character string title
can be used to specify the %%Title: header in the PostScript file (or
use NULL for the default). The array font_no specifies all fonts used
in the plot (by number), or use NULL to leave out the
%%DocumentNeededResources: comment in the PostScript file.
long PSL_endplot (struct PSL_CTRL *P,
long last_page)
Terminates the plotting sequence and closes plot file (if
other than stdout). If last_page == PSL_FINALIZE (1), then a
PostScript showpage command is issued, which initiates the printing
process on hardcopy devices. Otherwise, pass PSL_OVERLAY (0).
long PSL_setorigin (struct PSL_CTRL *P,
double xorigin, double yorigin, double
angle, long mode)
Changes the coordinate system by translating by
(xorigin,yorigin) followed by a angle-degree rotation
(mode=PSL_FWD or 0) or alternatively the rotation followed by
translation (mode=PSL_INV or 1).
MEMORY OUTPUT¶
Normally, PSL will write all PostScript to the designated file
stream set in PSL_beginplot. Alternatively, PSL can write all the
PostScript to an internal char * buffer which can be retrieved at the end of
the plotting. This mode can be enabled on a plot-by-plot basis by adding the
flag PSL_MEMORY to the variable orientation passed to
PSL_beginplot. Once we reach the end of the plot with
PSL_endplot the buffer will be available (see below). One function
provide the functionality for memory output.
char * PSL_getplot (struct PSL_CTRL *P)
Retrieves the pointer to the PostScript plot that is kept
in memory when PSL_beginplot was instructed to use memory rather than
stream output. Note: It is the responsibility of the programmer to ensure that
the object retrieved is duplicated or written or otherwise processed before
the next call to PSL_beginplot or PSL_endsession either of which
will destroy the memory pointed to.
CHANGING SETTINGS¶
The following functions are used to change various PSL settings
and affect the current state of parameters such as line and fill
attributes.
long PSL_define_pen (struct PSL_CTRL *P,
char *name, long width, char
*style, double offset, double rgb[])
Stores the specified pen characteristics in a PostScript
variable called name. This can be used to place certain pen attributes
in the PostScript file and then retrieve them later with PSL_load_pen.
This makes the stored pen the current pen.
long PSL_define_rgb (struct PSL_CTRL *P,
char *name, double rgb[])
Stores the specified color in a PostScript variable
called name. This can be used to place certain color values in the
PostScript file and then retrieve them later with PSL_load_rgb. This
makes the stored color the current color.
long PSL_setcolor (struct PSL_CTRL *P,
double rgb[], long mode)
Sets the current color for all stroked (mode =
PSL_IS_STROKE (0)) or filled (mode = PSL_IS_FILL (1)) material to follow
(lines, symbol outlines, text). rgb is a triplet of red, green and blue
values in the range 0.0 through 1.0. Set the red color to -3.0 and the green
color to the pattern number returned by PSL_setpattern to select a
pattern as current paint color. For PDF transparency, set rgb[3] to a
value between 0 (opaque) and 1 (fully transparent).
long PSL_setpattern (struct PSL_CTRL *P,
long image_no, char *imagefile, long
dpi, double f_rgb[], double b_rgb[])
Sets up the specified image pattern as the fill to use
for polygons and symbols. Here, image_no is the number of the standard
PSL fill patterns (1-90; use a negative number when you specify an image
filename instead. The scaling (i.e., resolution in dots per inch) of
the pattern is controlled by the image dpi; if set to 0 it will be
plotted at the device resolution. The two remaining settings apply to 1-bit
images only and are otherwise ignored: You may replace the foreground color
(the set bits) with the f_rgb color and the background color (the unset
bits) with b_rgb. Alternatively, pass either color with the red
component set to -1.0 and we will instead issue an image mask that is
see-through for the specified fore- or background component. To subsequently
use the pattern as a pen or fill color, use PSL_setcolor or
DB(PSL_setfill) with the a color rgb code made up of r = -3, and
b = the pattern number returned by PSL_setpattern.
long PSL_setdash (struct PSL_CTRL *P,
char *pattern, double offset)
Changes the current pen style attributes. The character
string
pattern contains the desired pattern using a series of lengths
in points specifying the alternating lengths of dashes and gaps in points.
E.g., "4 2" and
offset = 1 will plot like
where x is starting point of a line (The x is not plotted). That
is, the line is made up of a repeating pattern of a 4 points long solid line
and a 2 points long gap, starting 1 point after the x. To reset to solid
line, specify pattern = NULL ("") and offset =
0.
long PSL_setfill (struct PSL_CTRL *P,
double rgb[], long outline)
Sets the current fill color and whether or not outline is
needed for symbols. Special cases are handled by passing the red color as -1.0
(no fill), -2.0 (do not change the outline setting) or -3.0 (select the image
pattern indicated by the second (green) element of rgb). For PDF
transparency, set rgb[3] to a value between 0 (opaque) and 1 (fully
transparent). Set outline to PSL_OUTLINE (1) to draw the outlines of polygons
and symbols using the current pen.
long PSL_setfont (struct PSL_CTRL *P,
long fontnr)
Changes the current font number to fontnr. The
fonts available are: 0 = Helvetica, 1 = H. Bold, 2 = H. Oblique, 3 = H.
Bold-Oblique, 4 = Times, 5 = T. Bold, 6 = T. Italic, 7 = T. Bold Italic, 8 =
Courier, 9 = C. Bold, 10 = C Oblique, 11 = C Bold Oblique, 12 = Symbol, 13 =
AvantGarde-Book, 14 = A.-BookOblique, 15 = A.-Demi, 16 = A.-DemiOblique, 17 =
Bookman-Demi, 18 = B.-DemiItalic, 19 = B.-Light, 20 = B.-LightItalic, 21 =
Helvetica-Narrow, 22 = H-N-Bold, 23 = H-N-Oblique, 24 = H-N-BoldOblique, 25 =
NewCenturySchlbk-Roman, 26 = N.-Italic, 27 = N.-Bold, 28 = N.-BoldItalic, 29 =
Palatino-Roman, 30 = P.-Italic, 31 = P.-Bold, 32 = P.-BoldItalic, 33 =
ZapfChancery-MediumItalic, 34 = ZapfDingbats, 35 = Ryumin-Light-EUC-H, 36 =
Ryumin-Light-EUC-V, 37 = GothicBBB-Medium-EUC-H, and 38 =
GothicBBB-Medium-EUC-V. If fontnr is outside this range, it is reset to
0.
long PSL_setfontdims (struct PSL_CTRL *P,
double supsub, double scaps, double
sup, double sdown)
Changes the settings for a variety of relative font sizes
and shifts pertaining to sub-scripts, super-scripts, and small caps. Default
settings are given in brackets. Here, supsub sets the relative size of
sub- and super-scripts [0.58], scaps sets the relative size of small
caps [0.8], sup indicates the upward baseline shift for placement of
super-scripts [0.33], while sdown sets the downward baseline shift for
sub-scripts [0.33].
long PSL_setformat (struct PSL_CTRL *P,
long n_decimals)
Sets the number of decimals to be used when writing color
or gray values. The default setting of 3 gives 1000 choices per red, green,
and blue value, which is more than the 255 choices offered by most 24-bit
platforms. Choosing a lower value will make the output file smaller at the
expense of less color resolution. Still, a value of 2 gives 100 x 100 x 100 =
1 million colors, more than most eyes can distinguish. For a setting of 1, you
will have 10 nuances per primary color and a total of 1000 unique
combinations.
long PSL_setlinewidth (struct PSL_CTRL *P,
double linewidth)
Changes the current line width in points. Specifying 0
gives the thinnest line possible, but this is implementation-dependent (seems
to work fine on most PostScript printers).
long PSL_setlinecap (struct PSL_CTRL *P,
long cap)
Changes the current line cap, i.e., what happens at the
beginning and end of a line segment. PSL_BUTT_CAP (0) gives butt line caps
[Default], PSL_ROUND_CAP (1) selects round caps, while PSL_SQUARE_CAP (2)
results in square caps. Thus, the two last options will visually lengthen a
straight line-segment by half the line width at either end.
long PSL_setlinejoin (struct PSL_CTRL *P,
long join)
Changes the current linejoin setting, which handles how
lines of finite thickness are joined together when the meet at different
angles. PSL_MITER_JOIN (0) gives a mitered joint [Default], PSL_ROUND_JOIN (1)
makes them round, while PSL_BEVEL_JOIN (2) produces bevel joins.
long PSL_setmiterlimit (struct PSL_CTRL *P,
long limit)
Changes the current miter limit used for mitered joins.
PSL_MITER_DEFAULT (35) gives the default PS miter; other values are
interpreted as the cutoff acute angle (in degrees) when mitering becomes
active.
long PSL_settransparencymode (struct PSL_CTRL
*P, char *mode)
Changes the current PDF transparency rendering mode
[Default is Normal]. Choose among Color, ColorBurn, ColorDodge, Darken,
Difference, Exclusion, HardLight, Hue, Lighten, Luminosity, Multiply, Normal,
Overlay, Saturation, SoftLight, and Screen.
long PSL_setdefaults (struct PSL_CTRL *P,
double xyscales[], double pagergb[], char
*encoding)
Allows changes to the PSL session settings and should be
called immediately after PSL_beginsession. The xyscales array
affect an overall magnification of your plot [1,1]. This can be useful if you
design a page-sized plot but would then like to magnify (or shrink) it by a
given factor. Change the default paper media color [white; 1/1/1] by
specifying an alternate page color. Passing zero (or NULL for pagergb)
will leave the setting unchanged. Finally, pass the name of the character set
encoding (if NULL we select Standard).
long PSL_defunits (struct PSL_CTRL *P,
char *name, double value)
Creates a PostScript variable called name and
initializes it to the equivalent of value user units.
long PSL_defpoints (struct PSL_CTRL *P,
char *name, double fontsize)
Creates a PostScript variable called name and
initializes it to the value that corresponds to the font size (in points)
given by fontsize.
PLOTTING LINES AND POLYGONS¶
Here are functions used to plot lines and closed polygons, which
may optionally be filled. The attributes used for drawing and filling are
set prior to calling these functions; see CHANGING SETTINGS above.
long PSL_plotarc (struct PSL_CTRL *P,
double x, double y, double radius,
double angle1, double angle2, long
type)
Draws a circular arc with its center at plot coordinates
(x, y), starting from angle angle1 and end at
angle2. Angles must be given in decimal degrees. If angle1 >
angle2, a negative arc is drawn. The radius is in user units.
The type determines how the arc is interpreted: PSL_MOVE (1) means set
new anchor point, PSL_STROKE (2) means stroke the arc, PSL_MOVE + PSL_STROKE
(3) means both, whereas PSL_DRAW (0) just adds to arc path to the current
path.
long PSL_plotline (struct PSL_CTRL *P,
double x, double y, long n,
long type)
Assemble a continuous line through n points whose
the plot coordinates are in the x, y arrays. To continue an
existing line, use type = PSL_DRAW (0), or if this is the first segment
in a multisegment path, set type = PSL_MOVE (1). To end the segments
and draw the lines, add PSL_STROKE (2). Thus, for a single segment,
type must be PSL_MOVE + PSL_STROKE (3). The line is drawn using the
current pen attributes. Add PSL_CLOSE (8) to type to close the first
and last point by the PostScript operators; this is done automatically if the
first and last point are equal.
long PSL_plotpoint (struct PSL_CTRL *P,
double x, double y, long type)
Moves the pen from the current to the specified plot
coordinates (x, y) and optionally draws and strokes the line,
depending on type. Specify type as either a move (PSL_MOVE, 1),
or draw (PSL_DRAW, 2), or draw and stroke (PSL_DRAW + PSL_STOKE, 3) using
current pen attributes. It the coordinates are relative to the current point
add PSL_REL (4) to type.
long PSL_plotbox (struct PSL_CTRL *P,
double x0, double y0, double x1,
double y1)
Creates a closed box with opposite corners at plot
coordinates (x0,y1) and (x1,y1). The box may be
filled and its outline stroked depending on the current settings for fill and
pen attributes.
long PSL_plotpolygon (struct PSL_CTRL *P,
double x, double y, long n)
Creates a closed polygon through n points whose
plot coordinates are in the x, y arrays. The polygon may be
filled and its outline stroked depending on the current settings for fill and
pen attributes.
long PSL_plotsegment (struct PSL_CTRL *P,
double x0, double y0, double x1,
double y1)
Draws a line segment between the two points (plot
coordinates) using the current pen attributes.
PLOTTING SYMBOLS¶
Here are functions used to plot various geometric symbols or
constructs.
long PSL_plotaxis (struct PSL_CTRL *P,
double tickval, char *label, double
fontsize, long side)
Plots a basic axis with tick marks, annotations, and
label. Assumes that PSL_beginaxes has been called to set up positioning
and user data ranges. Annotations will be set using the fontsize in
points. side can be 0, 1, 2, or 3, which selects lower x-axis, right
y-axis, upper x-axis, or left y-axis, respectively. The label font size
is set to 1.5 times the fontsize.
long PSL_plotsymbol (struct PSL_CTRL *P,
double x, double y, double size[],
long symbol)
Plots a simple geometric symbol centered on plot
coordinates (x, y). The argument symbol selects the
geometric symbol to use. Most symbols are scaled to fit inside a circle of
diameter given as size[0], but some symbols take additional parameters.
Choose from these 1-parameter symbols using the predefined self-explanatory
integer values PSL_CIRCLE, PSL_DIAMOND, PSL_HEXAGON, PSL_INVTRIANGLE,
PSL_OCTAGON, PSL_PENTAGON, PSL_SQUARE, PSL_STAR, and PSL_TRIANGLE; these may
all be filled and stroked if PSL_setfill has been called first. In
addition, you can choose several line-only symbols that cannot be filled. They
are PSL_CROSS, PSL_DOT, PSL_PLUS, PSL_XDASH, and PSL_YDASH. Finally, more
complicated symbols require more than one parameter to be passed via
size. These are PSL_ELLIPSE (size is expected to contain the
three parameter angle, major, and minor axes, which
defines an ellipse with its major axis rotated by angle degrees),
PSL_MANGLE (size is expected to contain the 10 parameters
radius, angle1, and angle2 for the math angle
specification, followed by tailwidth, headlength,
headwidth, shape, status, trim1 and trim2
(see PSL_VECTOR below for explanation), PSL_WEDGE (size is expected to
contain the three parameter radius, angle1, and angle2
for the sector specification), PSL_RECT (size is expected to contain
the two dimensions width and height), PSL_RNDRECT (size
is expected to contain the two dimensions width and height and
the radius of the corners), PSL_ROTRECT (size is expected to
contain the three parameter angle, width, and height,
with rotation relative to the horizontal), and PSL_VECTOR (size is
expected to contain the 9 parameters x_tip, y_tip,
tailwidth, headlength, headwidth, shape,
status, head1, head2, trim1, and trim2.
Here (x_tip,y_tip) are the coordinates to the head of the
vector, while (x, y) are those of the tail. shape can
take on values from 0-1 and specifies how far the intersection point between
the base of a straight vector head and the vector line is moved toward the
tip. 0.0 gives a triangular head, 1.0 gives an arrow shaped head. The
status value is a bit-flag being the sum of several possible
contributions: PSL_VEC_RIGHT (2) = only draw right half of vector head,
PSL_VEC_BEGIN (4) = place vector head at beginning of vector, PSL_VEC_END (8)
= place vector head at end of vector, PSL_VEC_JUST_B (0) = align vector
beginning at (x,y), PSL_VEC_JUST_C (16) = align vector center at (x,y),
PSL_VEC_JUST_E (32) = align vector end at (x,y), PSL_VEC_JUST_S (64) = align
vector center at (x,y), PSL_VEC_OUTLINE (128) = draw vector head outline using
default pen, PSL_VEC_FILL (512) = fill vector head using default fill,
PSL_VEC_MARC90 (2048) = if angles subtend 90, draw straight angle symbol
(PSL_MANGLE only). The symbol may be filled and its outline stroked depending
on the current settings for fill and pen attributes. The parameters
head1 and head2 determines what kind of vector head will be
plotted at the two ends (if selected). 0 = normal vector head, 1 = circle, 2 =
terminal crossbar. Finally, trim1 and trim2 adjust the start and
end location of the vector.
PLOTTING IMAGES¶
Here are functions used to read and plot various images.
long PSL_plotbitimage (struct PSL_CTRL *P,
double x, double y, double xsize,
double ysize, int justify, unsigned char
buffer, long nx, long ny, double
f_rgb[], double b_rgb[])
Plots a 1-bit image image at plot coordinates (x,
y) justified as per the argument justify (see
JUSTIFICATION for details). The target size of the image is given by
xsize and ysize in user units. If one of these is specified as
zero, the corresponding size is adjusted to the other such that the aspect
ratio of the original image is retained. buffer is an unsigned
character array in scanline orientation with 8 pixels per byte. nx,
ny refers to the number of pixels in the image. The rowlength of
buffer must be an integral number of 8; pad with zeros.
buffer[0] is upper left corner. You may replace the foreground color
(the set bits) with the f_rgb color and the background color (the unset
bits) with b_rgb. Alternatively, pass either color with the red
component set to -1.0 and we will instead issue an image mask that is
see-through for the specified fore- or background component. See the Adobe
Systems PostScript Reference Manual for more details.
long PSL_plotcolorimage (struct PSL_CTRL *P,
double x, double y, double xsize,
double ysize, int justify, unsigned char
*buffer, long nx, long ny, long
depth)
Plots a 1-, 2-, 4-, 8-, or 24-bit deep image at plot
coordinates (x, y) justified as per the argument justify
(see JUSTIFICATION for details). The target size of the image is given
by xsize and ysize in user units. If one of these is specified
as zero, the corresponding size is adjusted to the other such that the aspect
ratio of the original image is retained. This functions sets up a call to the
PostScript colorimage or image operators. The pixel values are stored in
buffer, an unsigned character array in scanline orientation with gray
shade or r/g/b values (0-255). buffer[0] is the upper left corner.
depth is number of bits per pixel (24, 8, 4, 2, or 1). nx,
ny refers to the number of pixels in image. The rowlength of
buffer must be an integral number of 8/Idepth. E.g. if
depth = 4, then buffer[j]/16 gives shade for pixel[2j-1] and
buffer[j%16 (mod 16) gives shade for pixel[2j]. When -depth is
passed instead then "hardware" interpolation of the image is
requested (this is implementation dependent). If -nx is passed with 8-
(or 24-) bit images then the first one (or three) bytes of buffer holds
the gray (or r/g/b) color for pixels that are to be masked out using the PS
Level 3 Color Mask method. See the Adobe Systems PostScript Reference Manual
for more details.
long PSL_plotepsimage (struct PSL_CTRL *P,
double x, double y, double xsize,
double ysize, int justify, unsigned char
*buffer, long size, long nx, long
ny, long ox, long oy)
Plots an Encapsulated PostScript (EPS) image at plot
coordinates (x, y) justified as per the argument justify
(see JUSTIFICATION for details). The target size of the image is given
by xsize and ysize in user units. If one of these is specified
as zero, the corresponding size is adjusted to the other such that the aspect
ratio of the original image is retained. The EPS file is stored in
buffer and has size bytes. This function simply includes the
image in the PostScript output stream within an appropriate wrapper. Specify
position of lower left corner and size of image. nx, ny,
ox, oy refers to the width, height and origin (lower left
corner) of the BoundingBox in points.
long PSL_loadimage (struct PSL_CTRL *P,
FILE *fp, struct imageinfo *header, unsigned
char **image)
Reads the image contents of the EPS file or a raster
image pointed to by the open file pointer fp. The routine can handle
Encapsulated PostScript files or 1-, 8-, 24-, or 32-bit raster images in old,
standard, run-length encoded, or RGB-style Sun format. Non-Sun rasters are
automatically reformatted to Sun rasters via a system call to GraphicsMagick's
or ImageMagick's convert, if installed. The image is returned via the
image pointer.
PLOTTING TEXT¶
Here are functions used to read and plot text strings and
paragraphs. This can be somewhat complicated since we rely on the PostScript
interpreter to determine the exact dimensions of text items given the font
chosen. For perfect alignment you may have to resort to calculate offsets
explicitly using long PSL_deftextdim, PSL_set_height and
others and issue calculations with PSL_setcommand.
long PSL_plottext (struct PSL_CTRL *P,
double x, double y, double
fontsize, char *text, double angle,
long justify, long mode)
The text is plotted starting at plot coordinates
(x, y) and will make an angle with the horizontal. The
point (x, y) maps onto different points of the text-string by
giving various values for justify (see JUSTIFICATION for
details). If justify is negative, then all leading and trailing blanks
are stripped before plotting. Certain character sequences (flags) have special
meaning to PSL_plottext. @~ toggles between current font and the
Mathematical Symbols font. @%no% selects font no while @%%
resets to the previous font. @- turns subscript on/off, @+ turns superscript
on/off, @# turns small caps on/off, and @\ will make a composite character of
the following two character. @;r/g/b; changes the font color while @;;
resets it [optionally append =transparency to change the transparency
(0--100) of the text (the Default is opaque or 0)], @:size: changes the
font size (@:: resets it), and @_ toggles underline on/off. If text is
NULL then we assume PSL_plottextbox was called first. Give
fontsize in points. Normally, the text is typed using solid characters
in the current color (set by PSL_setcolor). To draw outlined
characters, set mode == 1; the outline will get the current color and
the text is filled with the current fill color (set by PSL_setfill).
Use mode == 2 if the current fill is a pattern. Use mode == 3 to
achieve the same as mode == 1, while preventing the outline from
obsuring any filled text font; the outline will hence be reduced to half the
selected width. If the text is not filled, mode == 3 operates the same
as mode == 1. If fontsize is negative it means that the current
point has already been set before PSL_plottext was called and that
(x, y) should be ignored.
long PSL_plottextbox (struct PSL_CTRL *P,
double x, double y, double
fontsize, char *text, double angle,
long justify, double offset[], long
mode)
This function is used in conjugation with
PSL_plottext when a box surrounding the text string is desired. Taking
most of the arguments of PSL_plottext, the user must also specify
mode to indicate whether the box needs rounded (PSL_YES = 1) or
straight (PSL_NO = 0) corners. The box will be colored with the current fill
style set by PSL_setfill. That means, if an outline is desired, and the
color of the inside of the box should be set with that routine. The outline
will be drawn with the current pen color (and width). The offset array
holds the horizontal and vertical distance gaps between text and the
surrounding text box in distance units. The smaller of the two determined the
radius of the rounded corners (if requested).
long PSL_deftextdim (struct PSL_CTRL *P,
char *prefix, double fontsize, char
*text)
Computes the dimensions (width and height) required by
the selected text given the current font and its fontsize (in
points). The values are stored as PostScript variables called prefix_w
and prefix_h, respectively. This function can be used to compute
dimensions and, via BF(PSL_setcommand), calculate chances to position a
particular item should be plotted. For instance, if you compute a position
this way and wish to plot the text there, pass the coordinates to
PSL_plottext as NaNs. If prefix is BF(-w), BF(-h), BF(-d) or
BF(-b), no PostScript variables will be assigned, but the values of width,
height, depth, or both width and height will be left on the PostScript
stack.
long PSL_setparagraph (struct PSL_CTRL *P,
double line_space, double par_width, long
par_just)
Initialize common settings to be used when typesetting
paragraphs of text with PSL_plotparagraph. Specify the line spacing (1
equals the font size) and paragraph width (in distance units). Text can be
aligned left (PSL_BL), centered (PSL_BC), right (PSL_BR), or justified
(PSL_JUST) and is controlled by par_just.
long PSL_plotparagraphbox (struct PSL_CTRL
*P, double x, double y, double
fontsize, char *text, double angle,
long justify, double offset[], long
mode)
Computes and plots the text rectangle for a paragraph
using the specified fontsize (in points). Here, text is an array
of the text to be typeset, using the settings initialized by
PSL_setparagraph. The escape sequences described for
PSL_plottext can be used to modify the text. Separate text into several
paragraphs by appending \r to the last item in a paragraph. The whole text
block is positioned at plot coordinates x, y, which is mapped to
a point on the block specified by justify (see JUSTIFICATION for
details). The whole block is then shifted by the amounts shift[]. The
box will be plotted using the current fill and outline settings. The
offset array holds the horizontal and vertical distance gaps between
text and the surrounding text box in distance units. Use mode to
indicate whether the box should be straight (PSL_RECT_STRAIGHT = 0), rounded
(PSL_RECT_ROUNDED = 1), convex (PSL_RECT_CONVEX = 2) or concave
(PSL_RECT_CONCAVE = 3).
long PSL_plotparagraph (struct PSL_CTRL *P,
double x, double y, double
fontsize, char *text, double angle,
long justify, long mode)
Typesets paragraphs of text using the specified
fontsize (in points). Here, text is an array of the text to be
typeset, using the settings initialized by PSL_setparagraph. The escape
sequences described for PSL_plottext can be used to modify the text.
Separate text into several paragraphs by appending \r to the last item in a
paragraph. The whole text block is positioned at plot coordinates x,
y, which is mapped to a point on the block specified by justify
(see JUSTIFICATION for details). See PSL_plotparagraphbox for
laying down the surrounding text rectangle first.
long PSL_plottextline (struct PSL_CTRL *P,
double *xpath, double *ypath, long
*np, long nseg, void *arg1, void
*arg2, char *text[], double angle[],
long n_per_seg[], double fontsize,
**long* justify, double offset[], long
mode)
Please text along one or more path segments. The function
does different things depending on the bit flags in mode. A key
distinction occurs if the bit flag contains the bit PSL_TXT_CURVED (64) which
means we wish to typeset the text along a variable and curved baseline given
by the segments in xpath, ypath; otherwise we set straight text
(possibly at an angle) and the xpath, ypath are not considered for text
placement [If no line drawing is desired then these two arrays may be NULL].
We will describe the action taken for each bit value. Multiple values may be
passed at the same time and we processes from low to hight bit. PSL_TXT_INIT:
When mode contains this bit (1) we will initialize all the required variables
and store them in the PostScript file. PSL_TXT_SHOW: We wish to see the text
strings (otherwise they may only serve as guides to set up clip paths).
PSL_TXT_CLIP_ON: Use the text and the paths to set up clip paths.
PSL_TXT_DRAW: Draw the lines defined by the xpath, ypath arrays.
PSL_TXT_CLIP_OFF: Turn the text path clipping off. We pass the text strings
via text. The locations of text plotting depends on whether
PSL_TXT_CURVED is selected. If it is then you must pass as arg1 the
node array indicating at which node in the xpath, ypath array
the text will be plotted; let arg2 be NULL. For straight baselines you
must instead pass another set of x,y coordinates with the locations of the
text label placements via arg1, arg2. Each label has its own entry in
the angle array. The text is an array of text pointers to the
individual text items. The offset array holds the x and y distance gaps
between text and the surrounding text box in user units (the clip path is the
combination of all these text boxes). Use justify to specify how the
text string relates to the coordinates (see BF(JUSTIFICATION) for details).
PSL_TXT_FILLBOX (128) will fill the text box (this requires you to first
define the text box rgb color with PSL_define_rgb by setting a local
PostScript variable that must be called PSL_setboxrgb). PSL_TXT_DRAWBOX (256)
will draw the text box outlines (this requires you to first define the text
box pen with PSL_define_pen by setting a local PostScript variable that
must be called PSL_setboxpen). Before calling this function you must also
initialize a PSL array for line pens and text fonts.
CLIPPING¶
Here are functions used to activate and deactivate clipping
regions.
long PSL_beginclipping (struct PSL_CTRL *P,
double x, double y, long n,
double rgb[], long flag)
Sets up a user-definable clip path as a series on
n points with plot coordinates (x, y). Plotting outside
this polygon will be clipped until PSL_endclipping is called. If
rgb[0] = -1 the inside of the path is left empty, otherwise it is
filled with the specified color. flag is used to create complex clip
paths consisting of several disconnected regions, and takes on values 0-3.
flag = PSL_PEN_MOVE_ABS (1) means this is the first path in a
multisegment clip path. flag = PSL_PEN_DRAW_ABS (2) means this is the
last segment. Thus, for a single path, flag =
PSL_PEN_DRAW_AND_STROKE_ABS (3).
long PSL_endclipping (struct PSL_CTRL *P,
long mode)
Depending on the mode it restores the clip path.
The mode values can be: -n will restore n levels of
text-based clipping, n will restore n levels of polygon
clipping, PSL_ALL_CLIP_TXT will undo all levels of text-based clipping, and
PSL_ALL_CLIP_POL will undo all levels of polygon-based clipping.
MISCELLANEOUS FUNCTIONS¶
Here are functions used to issue comments or to pass custom
PostScript commands directly to the output PostScript file. In C these
functions are declared as macros and they can accept a variable number of
arguments. However, from FORTRAN only a single text argument may be
passed.
BUGS¶
Caveat Emptor: The authors are not responsible for any
disasters, suicide attempts, or ulcers caused by correct or incorrect
use of PSL. If you find bugs, please report them to the authors by
electronic mail. Be sure to provide enough detail so that we can recreate
the problem.
REFERENCES¶
Adobe Systems Inc., 1990, PostScript language reference manual,
2nd edition, Addison-Wesley, (ISBN 0-201-18127-4).
COPYRIGHT¶
2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F.
Wobbe
