postscriptlight(3) GMT postscriptlight(3)
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 devel-
oped 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 mod-
ify 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 Post-
Script that conforms to the Adobe PostScript File Specification Version
3.0.
Before any PSL calls can be issued, the plotting system must be ini-
tialized. This is done by calling PSL_beginsession, which initializes a
new PSL session; then call PSL_setdefaults which sets internal vari-
ables 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 mea-
sure 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 ses-
sion. 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, includ-
ing many printers and large-format plotters. Many tools exists to dis-
play 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 speci-
fied 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 oppor-
tunity 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 ajustifieda 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:
9aaaa10aaaa 11
| |
5 6 7
| |
1aaaa 2aaaa 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 ano
justificationa, 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 initializa-
tion:
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 struc-
ture 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, dou-
ble width, double height, double x0, double y0, double x1, double y1)
This function sets up the mapping that takes the users data coordi-
nates 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 mea-
surement 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 posi-
tive 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 Post-
Script 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 %%Docu-
mentNeededResources: 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 show-
page 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 alterna-
tively 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_begin-
plot. 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 pro-
cessed 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 *image-
file, 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 back-
ground 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 pat-
tern contains the desired pattern using a series of lengths in
points specifying the alternating lengths of dashes and gaps in
points. E.g., a4 2a and offset = 1 will plot like
x a- a- a-
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 (aa) 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 out-
lines 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 = Sym-
bol, 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 = Ryu-
min-Light-EUC-H, 36 = Ryumin-Light-EUC-V, 37 = Goth-
icBBB-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 place-
ment 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 pri-
mary 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) pro-
duces 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 Nor-
mal]. 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 font-
size.
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 inter-
preted: 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 coordi-
nates 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 con-
structs.
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 sym-
bols 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, fol-
lowed 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 parame-
ter angle, width, and height, with rotation relative to the horizon-
tal), 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 coordi-
nates 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 inter-
section 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 tar-
get 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 Ref-
erence 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 correspond-
ing 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 orienta-
tion 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
ahardwarea interpolation of the image is requested (this is imple-
mentation 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 Man-
ual 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 correspond-
ing 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 Post-
Script 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 GraphicsMagickas or ImageMagickas 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 inter-
preter to determine the exact dimensions of text items given the font
chosen. For perfect alignment you may have to resort to calculate off-
sets 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 font-
size, 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 dif-
ferent points of the text-string by giving various values for jus-
tify (see JUSTIFICATION for details). If justify is negative, then
all leading and trailing blanks are stripped before plotting. Cer-
tain character sequences (flags) have special meaning to PSL_plot-
text. @~ 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 trans-
parency (0a100) 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) cor-
ners. 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 Post-
Script 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 justi-
fied (PSL_JUST) and is controlled by par_just.
long PSL_plotparagraphbox (struct PSL_CTRL *P, double x, double y, dou-
ble 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 mod-
ify 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 plot-
ted 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[], dou-
ble angle[], long n_per_seg[], double fontsize, **long* justify, double
offset[], long mode)
Please text along one or more path segments. The function does dif-
ferent 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 base-
line 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 coordi-
nates 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 surround-
ing 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 dis-
connected 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 argu-
ments. However, from FORTRAN only a single text argument may be passed.
long PSL_setcommand (struct PSL_CTRL *P, char *text)
Writes a raw PostScript command to the PostScript output file,
e.g., a1 setlinejoin.
long PSL_comment (struct PSL_CTRL *P, char *text)
Writes a comment (text) to the PostScript output file, e.g.,
aStart of graph 20. The comment are prefixed with with %% .
AUTHORS
Paul Wessel, School of Ocean and Earth Science and Technology,
http://www.soest.hawaii.edu.
Remko Scharroo, EUMETSAT, Darmstadt, Germany, http://www.eumetsat.int.
BUGS
Caveat Emptor: The authors are not responsible for any disasters, sui-
cide 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.
SEE ALSO
psconvert(1)
REFERENCES
Adobe Systems Inc., 1990, PostScript language reference manual, 2nd
edition, Addison-Wesley, (ISBN 0-201-18127-4).
COPYRIGHT
2017, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
5.4.2 Jun 24, 2017 postscriptlight(3)
gmt5 5.4.2 - Generated Wed Jun 28 14:39:53 CDT 2017