1POSTSCRIPTLIGHT(3) GMT POSTSCRIPTLIGHT(3)
2
6 postscriptlight - A PostScript based plotting library
7
9 PSL (PostScriptLight) was created to make the generation of PostScript
10 page description code easier. PS is a page description language devel‐
11 oped by the Adobe for specifying how a printer should render a page of
12 text or graphics. It uses a reverse Polish notation that puts and gets
13 items from a stack to draws lines, text, and images and even performs
14 calculations. PSL is a self-contained library that presents a series of
15 functions that can be used to create plots. The resulting PostScript
16 code is ASCII text (with some exceptions for images if so desired) and
17 can thus be edited using any text editor. Thus, it is possible to mod‐
18 ify a plot file even after it has been created, e.g., to change text
19 strings, set new gray shades or colors, experiment with various pen
20 widths, etc. Furthermore, various tools exist that can parse PostScript
21 and let you make such edits via a graphical user interface (e.g., Adobe
22 Illustrator). PSL is written in C but includes FORTRAN bindings and can
23 therefore be called from both C and FORTRAN programs. To use this
24 library, you must link your plotting program with PSL. PSL is used by
25 the GMT graphics programs to generate PS. PSL output is freeform Post‐
26 Script that conforms to the Adobe PostScript File Specification Version
27 3.0.
28 Before any PSL calls can be issued, the plotting system must be ini‐
30 tialized. This is done by calling PSL_beginsession, which initializes a
31 new PSL session; then call PSL_setdefaults which sets internal vari‐
32 ables and default settings, accepts settings for measurement units and
33 character encoding, and returns a pointer to a struct PSL_CTRL which
34 must be passed as first argument to all other PSL functions. The mea‐
35 sure unit for sizes and positions can be set to be centimeter (c), inch
36 (i), meter (m), or points (p). A PSL session is terminated by calling
37 PSL_endsession. You may create one or more plots within the same ses‐
38 sion. A new plot is started by calling PSL_beginplot, which defines
39 macros, sets up the plot-coordinate system, scales, and [optionally]
40 opens a file where all the PS code will be written. Normally, the plot
41 code is written to stdout. When all plotting to this file is done, you
42 finalize the plot by calling PSL_endplot.
43 A wide variety of output devices that support PostScript exist, includ‐
45 ing many printers and large-format plotters. Many tools exists to dis‐
46 play PostScript on a computer screen. Open source tools such as ghost‐
47 script can be used to convert PostScript into PDF or raster images
48 (e.g., TIFF, JPEG) at a user-defined resolution (DPI). In particular,
49 the GMT tool psconvert is a front-end to ghostscript and pre-selects
50 the optimal options for ghostscript that will render quality PDF and
51 images.
52 The PSL is fully 64-bit compliant. Integer parameters are here speci‐
54 fied by the type long to distinguish them from the 32-bit int. Note
55 that under standard 32-bit compilation they are equivalent. Users of
56 this library under 64-bit mode must make sure they pass proper long
57 variables (under Unix flavors) or __int64 under Windows 64.
58
60 PSL can be instructed to use centimeters, inches, meters or points as
61 input units for the coordinates and sizes of elements to be plotted.
62 Any dimension that takes this setting as a unit is specified as user
63 units or plot units in this manual. Excluded from this are line widths
64 and font sizes which are always measured in points. The user units can
65 be further refined by calling PSL_beginaxes, giving the user the oppor‐
66 tunity to specify any linear coordinate frame. Changing the coordinate
67 frame only affects the coordinates of plotted material indicated as
68 measured in plot units, not the sizes of symbols (which remain in user
69 units), nor line widths or font sizes (which remain in points).
70
72 PSL uses the direct color model where red, green, and blue are given
73 separately, each must be in the range from 0-1. If red = -1 then no
74 fill operation takes place. If red = -3, then pattern fill will be
75 used, and the green value will indicate the pattern to be used. Most
76 plot-items can be plotted with or without outlines. If outline is
77 desired (i.e., set to 1), it will be drawn using the current line width
78 and pattern. PSL uses highly optimized macro substitutions and scales
79 the coordinates depending on the resolution of the hardcopy device so
80 that the output file is kept as compact as possible.
81
83 Text strings, text boxes and images can be "justified" by specifying
84 the corner to which the x and y coordinates of the subroutine call
85 apply. Nine different values are possible, as shown schematically in
86 this diagram:
87 9------------10----------- 11
88 | |
90 5 6 7
92 | |
94 1------------ 2------------ 3
96 The box represents the text or image. E.g., to plot a text string with
98 its center at (x, y), you must use justify == 6. justify == 0 means "no
99 justification", which generally means (x, y) is at the bottom left.
100 Convenience values PSL_NONE, PSL_BL, PSL_BC, PSL_BL, PSL_ML, PSL_MC,
101 PSL_MR, PSL_TL, PSL_TC and PSL_TR are available.
102
104 These functions initialize or terminate the PSL system. We use the term
105 PSL session to indicate one instance of the PSL system (a complicated
106 program could run many PSL sessions concurrently as each would operate
107 via its own control structure). During a single session, one or more
108 plots may be created. Here are the functions involved in initializa‐
109 tion:
110 struct PSL_CTRL *New_PSL_Ctrl (char *session)
112 This is the first function that must be called as it creates a new
113 PSL session. Specifically, it will allocate a new PSL control struc‐
114 ture and initialize the session default parameters. The pointer that
115 is returned must be passed to all subsequent PSL functions.
116 long *PSL_beginsession (struct PSL_CTRL *PSL, long search, char
118 *sharedir, char *userdir)
119 This is the second function that must be called as it initializes
120 the new PSL session. Here, search is an integer that is passed as 0
121 in GMT but should be 1 for other users. If so we will search for the
122 environmental parameters PSL_SHAREDIR and PSL_USERDIR should the
123 corresponding arguments sharedir and userdir be NULL.
124 long PSL_endsession (struct PSL_CTRL *PSL)
126 This function terminates the active PSL session; it is the last
127 function you must call in your program. Specifically, this function
128 will deallocate memory used and free up resources.
129 struct PSL_CTRL *PSL_beginlayer (struct PSL_CTRL *PSL, long layer)
131 Adds a DSC comment by naming this layer; give a unique integer
132 value. Terminate layer with PSL_endlayer
133 struct PSL_CTRL *PSL_endlayer (struct PSL_CTRL *PSL)
135 Terminate current layer with a DSC comment.
136 long PSL_fopen (char *file, char *mode)
138 This function simply opens a file, just like fopen. The reason it is
139 replicated here is that under Windows, file pointers must be
140 assigned within the same DLL as they are being used. Yes, this is
141 retarded but if we do not do so then PSL will not work well under
142 Windows. Under non-Windows this functions is just a macro that
143 becomes fopen.
144 void PSL_free (void *ptr)
146 This function frees up the memory allocated inside PSL. Programmers
147 using C/C++ should now this is a macro and there is no need to cast
148 the pointer to void * as this will be done by the macro. Fortran
149 programmers should instead call PSL_freefunction.
150 void PSL_beginaxes (struct PSL_CTRL *PSL, double llx, double lly, dou‐
152 ble width, double height, double x0, double y0, double x1, double y1)
153 This function sets up the mapping that takes the users data coordi‐
154 nates and converts them to the positions on the plot in PostScript
155 units. This should be used when plotting data coordinates and is
156 terminated with PSL_endaxes, which returns PSL to the default mea‐
157 surement units and scaling. Here, llx and lly sets the lower left
158 position of the mapping region, while width and height sets the
159 dimension of the plot area in user units. Finally, x0, x1 and y0, y1
160 indicate the range of the users x- and y-coordinates, respectively.
161 Specify a reverse axis direction (e.g., to let the y-axis be posi‐
162 tive down) by setting y0 larger than y1, and similarly for an x-axis
163 that increases to the left.
164 void PSL_endaxes (struct PSL_CTRL *PSL)
166 Terminates the map scalings initialized by PSL_beginaxes and returns
167 PSL to standard scaling in measurement units.
168 long PSL_beginplot (struct PSL_CTRL *P, FILE *fp, long orientation,
170 long overlay, long color_mode, char origin[], double offset[], double
171 page_size[], char *title, long font_no[])
172 Controls the initiation (or continuation) of a particular plot
173 within the current session. Pass file pointer fp where the Post‐
174 Script code will be written; if NULL then the output is written to
175 stdout. The Fortran interface always sends to stdout. If you want
176 to receive the PostScript back in memory then you need to add
177 PSL_MEMORY to orientation and call PSL_getplot to retrieve the plot
178 after you finish the plot with PSL_endplot. The orientation may be
179 landscape (PSL_LANDSCAPE or 0) or portrait (PSL_PORTRAIT or 1). Set
180 overlay to PSL_OVERLAY (0) if the following PostScript code should
181 be appended to an existing plot; otherwise pass PSL_INIT (1) to
182 start a new plot. Let colormode be one of PSL_RGB (0), PSL_CMYK
183 (1), PSL_HSV (2) or PSL_GRAY (3); this setting controls how colors
184 are presented in the PostScript code. The origin setting determines
185 for x and y separately the origin of the specified offsets (next
186 argument). Each of the two characters are either r for an offset
187 relative to the current origin, a for a temporary adjustment of the
188 origin which is undone during BD(PSL_endplot), f for a placement of
189 the origin relative to the lower left corner of the page, c for a
190 placement of the origin relative to the center of the page. The
191 array offset specifies the offset of the new origin relative to the
192 position indicated by origin. page_size means the physical width
193 and height of the plotting media in points (typically 612 by 792 for
194 Letter or 595 by 842 for A4 format). The character string title can
195 be used to specify the %%Title: header in the PostScript file (or
196 use NULL for the default). The array font_no specifies all fonts
197 used in the plot (by number), or use NULL to leave out the %%Docu‐
198 mentNeededResources: comment in the PostScript file.
199 long PSL_endplot (struct PSL_CTRL *P, long last_page)
201 Terminates the plotting sequence and closes plot file (if other than
202 stdout). If last_page == PSL_FINALIZE (1), then a PostScript show‐
203 page command is issued, which initiates the printing process on
204 hardcopy devices. Otherwise, pass PSL_OVERLAY (0).
205 long PSL_setorigin (struct PSL_CTRL *P, double xorigin, double yorigin,
207 double angle, long mode)
208 Changes the coordinate system by translating by (xorigin,yorigin)
209 followed by a angle-degree rotation (mode=PSL_FWD or 0) or alterna‐
210 tively the rotation followed by translation (mode=PSL_INV or 1).
211
213 Normally, PSL will write all PostScript to the designated file stream
214 set in PSL_beginplot. Alternatively, PSL can write all the PostScript
215 to an internal char * buffer which can be retrieved at the end of the
216 plotting. This mode can be enabled on a plot-by-plot basis by adding
217 the flag PSL_MEMORY to the variable orientation passed to PSL_begin‐
218 plot. Once we reach the end of the plot with PSL_endplot the buffer
219 will be available (see below). One function provide the functionality
220 for memory output.
221 char * PSL_getplot (struct PSL_CTRL *P)
223 Retrieves the pointer to the PostScript plot that is kept in memory
224 when PSL_beginplot was instructed to use memory rather than stream
225 output. Note: It is the responsibility of the programmer to ensure
226 that the object retrieved is duplicated or written or otherwise pro‐
227 cessed before the next call to PSL_beginplot or PSL_endsession
228 either of which will destroy the memory pointed to.
229
231 The following functions are used to change various PSL settings and
232 affect the current state of parameters such as line and fill
233 attributes.
234 long PSL_define_pen (struct PSL_CTRL *P, char *name, long width, char
236 *style, double offset, double rgb[])
237 Stores the specified pen characteristics in a PostScript variable
238 called name. This can be used to place certain pen attributes in the
239 PostScript file and then retrieve them later with PSL_load_pen. This
240 makes the stored pen the current pen.
241 long PSL_define_rgb (struct PSL_CTRL *P, char *name, double rgb[])
243 Stores the specified color in a PostScript variable called name.
244 This can be used to place certain color values in the PostScript
245 file and then retrieve them later with PSL_load_rgb. This makes the
246 stored color the current color.
247 long PSL_setcolor (struct PSL_CTRL *P, double rgb[], long mode)
249 Sets the current color for all stroked (mode = PSL_IS_STROKE (0)) or
250 filled (mode = PSL_IS_FILL (1)) material to follow (lines, symbol
251 outlines, text). rgb is a triplet of red, green and blue values in
252 the range 0.0 through 1.0. Set the red color to -3.0 and the green
253 color to the pattern number returned by PSL_setpattern to select a
254 pattern as current paint color. For PDF transparency, set rgb[3] to
255 a value between 0 (opaque) and 1 (fully transparent).
256 long PSL_setpattern (struct PSL_CTRL *P, long image_no, char *image‐
258 file, long dpi, double f_rgb[], double b_rgb[])
259 Sets up the specified image pattern as the fill to use for polygons
260 and symbols. Here, image_no is the number of the standard PSL fill
261 patterns (1-90; use a negative number when you specify an image
262 filename instead. The scaling (i.e., resolution in dots per inch) of
263 the pattern is controlled by the image dpi; if set to 0 it will be
264 plotted at the device resolution. The two remaining settings apply
265 to 1-bit images only and are otherwise ignored: You may replace the
266 foreground color (the set bits) with the f_rgb color and the back‐
267 ground color (the unset bits) with b_rgb. Alternatively, pass
268 either color with the red component set to -1.0 and we will instead
269 issue an image mask that is see-through for the specified fore- or
270 background component. To subsequently use the pattern as a pen or
271 fill color, use PSL_setcolor or DB(PSL_setfill) with the a color rgb
272 code made up of r = -3, and b = the pattern number returned by
273 PSL_setpattern.
274 long PSL_setdash (struct PSL_CTRL *P, char *pattern, double offset)
276 Changes the current pen style attributes. The character string pat‐
277 tern contains the desired pattern using a series of lengths in
278 points specifying the alternating lengths of dashes and gaps in
279 points. E.g., "4 2" and offset = 1 will plot like
280 x ---- ---- ----
281 where x is starting point of a line (The x is not plotted). That is,
283 the line is made up of a repeating pattern of a 4 points long solid
284 line and a 2 points long gap, starting 1 point after the x. To reset
285 to solid line, specify pattern = NULL ("") and offset = 0.
286 long PSL_setfill (struct PSL_CTRL *P, double rgb[], long outline)
288 Sets the current fill color and whether or not outline is needed for
289 symbols. Special cases are handled by passing the red color as -1.0
290 (no fill), -2.0 (do not change the outline setting) or -3.0 (select
291 the image pattern indicated by the second (green) element of rgb).
292 For PDF transparency, set rgb[3] to a value between 0 (opaque) and 1
293 (fully transparent). Set outline to PSL_OUTLINE (1) to draw the out‐
294 lines of polygons and symbols using the current pen.
295 long PSL_setfont (struct PSL_CTRL *P, long fontnr)
297 Changes the current font number to fontnr. The fonts available are:
298 0 = Helvetica, 1 = H. Bold, 2 = H. Oblique, 3 = H. Bold-Oblique, 4
299 = Times, 5 = T. Bold, 6 = T. Italic, 7 = T. Bold Italic, 8 =
300 Courier, 9 = C. Bold, 10 = C Oblique, 11 = C Bold Oblique, 12 = Sym‐
301 bol, 13 = AvantGarde-Book, 14 = A.-BookOblique, 15 = A.-Demi, 16 =
302 A.-DemiOblique, 17 = Bookman-Demi, 18 = B.-DemiItalic, 19 =
303 B.-Light, 20 = B.-LightItalic, 21 = Helvetica-Narrow, 22 = H-N-Bold,
304 23 = H-N-Oblique, 24 = H-N-BoldOblique, 25 = NewCenturySchlbk-Roman,
305 26 = N.-Italic, 27 = N.-Bold, 28 = N.-BoldItalic, 29 = Pala‐
306 tino-Roman, 30 = P.-Italic, 31 = P.-Bold, 32 = P.-BoldItalic, 33 =
307 ZapfChancery-MediumItalic, 34 = ZapfDingbats, 35 = Ryu‐
308 min-Light-EUC-H, 36 = Ryumin-Light-EUC-V, 37 = Goth‐
309 icBBB-Medium-EUC-H, and 38 = GothicBBB-Medium-EUC-V. If fontnr is
310 outside this range, it is reset to 0.
311 long PSL_setfontdims (struct PSL_CTRL *P, double supsub, double scaps,
313 double sup, double sdown)
314 Changes the settings for a variety of relative font sizes and shifts
315 pertaining to sub-scripts, super-scripts, and small caps. Default
316 settings are given in brackets. Here, supsub sets the relative size
317 of sub- and super-scripts [0.58], scaps sets the relative size of
318 small caps [0.8], sup indicates the upward baseline shift for place‐
319 ment of super-scripts [0.33], while sdown sets the downward baseline
320 shift for sub-scripts [0.33].
321 long PSL_setformat (struct PSL_CTRL *P, long n_decimals)
323 Sets the number of decimals to be used when writing color or gray
324 values. The default setting of 3 gives 1000 choices per red, green,
325 and blue value, which is more than the 255 choices offered by most
326 24-bit platforms. Choosing a lower value will make the output file
327 smaller at the expense of less color resolution. Still, a value of 2
328 gives 100 x 100 x 100 = 1 million colors, more than most eyes can
329 distinguish. For a setting of 1, you will have 10 nuances per pri‐
330 mary color and a total of 1000 unique combinations.
331 long PSL_setlinewidth (struct PSL_CTRL *P, double linewidth)
333 Changes the current line width in points. Specifying 0 gives the
334 thinnest line possible, but this is implementation-dependent (seems
335 to work fine on most PostScript printers).
336 long PSL_setlinecap (struct PSL_CTRL *P, long cap)
338 Changes the current line cap, i.e., what happens at the beginning
339 and end of a line segment. PSL_BUTT_CAP (0) gives butt line caps
340 [Default], PSL_ROUND_CAP (1) selects round caps, while
341 PSL_SQUARE_CAP (2) results in square caps. Thus, the two last
342 options will visually lengthen a straight line-segment by half the
343 line width at either end.
344 long PSL_setlinejoin (struct PSL_CTRL *P, long join)
346 Changes the current linejoin setting, which handles how lines of
347 finite thickness are joined together when the meet at different
348 angles. PSL_MITER_JOIN (0) gives a mitered joint [Default],
349 PSL_ROUND_JOIN (1) makes them round, while PSL_BEVEL_JOIN (2) pro‐
350 duces bevel joins.
351 long PSL_setmiterlimit (struct PSL_CTRL *P, long limit)
353 Changes the current miter limit used for mitered joins.
354 PSL_MITER_DEFAULT (35) gives the default PS miter; other values are
355 interpreted as the cutoff acute angle (in degrees) when mitering
356 becomes active.
357 long PSL_settransparencymode (struct PSL_CTRL *P, char *mode)
359 Changes the current PDF transparency rendering mode [Default is Nor‐
360 mal]. Choose among Color, ColorBurn, ColorDodge, Darken, Difference,
361 Exclusion, HardLight, Hue, Lighten, Luminosity, Multiply, Normal,
362 Overlay, Saturation, SoftLight, and Screen.
363 long PSL_setdefaults (struct PSL_CTRL *P, double xyscales[], double
365 pagergb[], char *encoding)
366 Allows changes to the PSL session settings and should be called
367 immediately after PSL_beginsession. The xyscales array affect an
368 overall magnification of your plot [1,1]. This can be useful if you
369 design a page-sized plot but would then like to magnify (or shrink)
370 it by a given factor. Change the default paper media color [white;
371 1/1/1] by specifying an alternate page color. Passing zero (or NULL
372 for pagergb) will leave the setting unchanged. Finally, pass the
373 name of the character set encoding (if NULL we select Standard).
374 long PSL_defunits (struct PSL_CTRL *P, char *name, double value)
376 Creates a PostScript variable called name and initializes it to the
377 equivalent of value user units.
378 long PSL_defpoints (struct PSL_CTRL *P, char *name, double fontsize)
380 Creates a PostScript variable called name and initializes it to the
381 value that corresponds to the font size (in points) given by font‐
382 size.
383
385 Here are functions used to plot lines and closed polygons, which may
386 optionally be filled. The attributes used for drawing and filling are
387 set prior to calling these functions; see CHANGING SETTINGS above.
388 long PSL_plotarc (struct PSL_CTRL *P, double x, double y, double
390 radius, double angle1, double angle2, long type)
391 Draws a circular arc with its center at plot coordinates (x, y),
392 starting from angle angle1 and end at angle2. Angles must be given
393 in decimal degrees. If angle1 > angle2, a negative arc is drawn. The
394 radius is in user units. The type determines how the arc is inter‐
395 preted: PSL_MOVE (1) means set new anchor point, PSL_STROKE (2)
396 means stroke the arc, PSL_MOVE + PSL_STROKE (3) means both, whereas
397 PSL_DRAW (0) just adds to arc path to the current path.
398 long PSL_plotline (struct PSL_CTRL *P, double x, double y, long n, long
400 type)
401 Assemble a continuous line through n points whose the plot coordi‐
402 nates are in the x, y arrays. To continue an existing line, use type
403 = PSL_DRAW (0), or if this is the first segment in a multisegment
404 path, set type = PSL_MOVE (1). To end the segments and draw the
405 lines, add PSL_STROKE (2). Thus, for a single segment, type must be
406 PSL_MOVE + PSL_STROKE (3). The line is drawn using the current pen
407 attributes. Add PSL_CLOSE (8) to type to close the first and last
408 point by the PostScript operators; this is done automatically if the
409 first and last point are equal.
410 long PSL_plotpoint (struct PSL_CTRL *P, double x, double y, long type)
412 Moves the pen from the current to the specified plot coordinates (x,
413 y) and optionally draws and strokes the line, depending on type.
414 Specify type as either a move (PSL_MOVE, 1), or draw (PSL_DRAW, 2),
415 or draw and stroke (PSL_DRAW + PSL_STOKE, 3) using current pen
416 attributes. It the coordinates are relative to the current point add
417 PSL_REL (4) to type.
418 long PSL_plotbox (struct PSL_CTRL *P, double x0, double y0, double x1,
420 double y1)
421 Creates a closed box with opposite corners at plot coordinates
422 (x0,y1) and (x1,y1). The box may be filled and its outline stroked
423 depending on the current settings for fill and pen attributes.
424 long PSL_plotpolygon (struct PSL_CTRL *P, double x, double y, long n)
426 Creates a closed polygon through n points whose plot coordinates are
427 in the x, y arrays. The polygon may be filled and its outline
428 stroked depending on the current settings for fill and pen
429 attributes.
430 long PSL_plotsegment (struct PSL_CTRL *P, double x0, double y0, double
432 x1, double y1)
433 Draws a line segment between the two points (plot coordinates) using
434 the current pen attributes.
435
437 Here are functions used to plot various geometric symbols or con‐
438 structs.
439 long PSL_plotaxis (struct PSL_CTRL *P, double tickval, char *label,
441 double fontsize, long side)
442 Plots a basic axis with tick marks, annotations, and label. Assumes
443 that PSL_beginaxes has been called to set up positioning and user
444 data ranges. Annotations will be set using the fontsize in points.
445 side can be 0, 1, 2, or 3, which selects lower x-axis, right y-axis,
446 upper x-axis, or left y-axis, respectively. The label font size is
447 set to 1.5 times the fontsize.
448 long PSL_plotsymbol (struct PSL_CTRL *P, double x, double y, double
450 size[], long symbol)
451 Plots a simple geometric symbol centered on plot coordinates (x, y).
452 The argument symbol selects the geometric symbol to use. Most sym‐
453 bols are scaled to fit inside a circle of diameter given as size[0],
454 but some symbols take additional parameters. Choose from these
455 1-parameter symbols using the predefined self-explanatory integer
456 values PSL_CIRCLE, PSL_DIAMOND, PSL_HEXAGON, PSL_INVTRIANGLE,
457 PSL_OCTAGON, PSL_PENTAGON, PSL_SQUARE, PSL_STAR, and PSL_TRIANGLE;
458 these may all be filled and stroked if PSL_setfill has been called
459 first. In addition, you can choose several line-only symbols that
460 cannot be filled. They are PSL_CROSS, PSL_DOT, PSL_PLUS, PSL_XDASH,
461 and PSL_YDASH. Finally, more complicated symbols require more than
462 one parameter to be passed via size. These are PSL_ELLIPSE (size is
463 expected to contain the three parameter angle, major, and minor
464 axes, which defines an ellipse with its major axis rotated by angle
465 degrees), PSL_MANGLE (size is expected to contain the 10 parameters
466 radius, angle1, and angle2 for the math angle specification, fol‐
467 lowed by tailwidth, headlength, headwidth, shape, status, trim1 and
468 trim2 (see PSL_VECTOR below for explanation), PSL_WEDGE (size is
469 expected to contain the three parameter radius, angle1, and angle2
470 for the sector specification), PSL_RECT (size is expected to contain
471 the two dimensions width and height), PSL_RNDRECT (size is expected
472 to contain the two dimensions width and height and the radius of the
473 corners), PSL_ROTRECT (size is expected to contain the three parame‐
474 ter angle, width, and height, with rotation relative to the horizon‐
475 tal), and PSL_VECTOR (size is expected to contain the 9 parameters
476 x_tip, y_tip, tailwidth, headlength, headwidth, shape, status,
477 head1, head2, trim1, and trim2. Here (x_tip,y_tip) are the coordi‐
478 nates to the head of the vector, while (x, y) are those of the tail.
479 shape can take on values from 0-1 and specifies how far the inter‐
480 section point between the base of a straight vector head and the
481 vector line is moved toward the tip. 0.0 gives a triangular head,
482 1.0 gives an arrow shaped head. The status value is a bit-flag being
483 the sum of several possible contributions: PSL_VEC_RIGHT (2) = only
484 draw right half of vector head, PSL_VEC_BEGIN (4) = place vector
485 head at beginning of vector, PSL_VEC_END (8) = place vector head at
486 end of vector, PSL_VEC_JUST_B (0) = align vector beginning at (x,y),
487 PSL_VEC_JUST_C (16) = align vector center at (x,y), PSL_VEC_JUST_E
488 (32) = align vector end at (x,y), PSL_VEC_JUST_S (64) = align vector
489 center at (x,y), PSL_VEC_OUTLINE (128) = draw vector head outline
490 using default pen, PSL_VEC_FILL (512) = fill vector head using
491 default fill, PSL_VEC_MARC90 (2048) = if angles subtend 90, draw
492 straight angle symbol (PSL_MANGLE only). The symbol may be filled
493 and its outline stroked depending on the current settings for fill
494 and pen attributes. The parameters head1 and head2 determines what
495 kind of vector head will be plotted at the two ends (if selected).
496 0 = normal vector head, 1 = circle, 2 = terminal crossbar. Finally,
497 trim1 and trim2 adjust the start and end location of the vector.
498
500 Here are functions used to read and plot various images.
501 long PSL_plotbitimage (struct PSL_CTRL *P, double x, double y, double
503 xsize, double ysize, int justify, unsigned char buffer, long nx, long
504 ny, double f_rgb[], double b_rgb[])
505 Plots a 1-bit image image at plot coordinates (x, y) justified as
506 per the argument justify (see JUSTIFICATION for details). The tar‐
507 get size of the image is given by xsize and ysize in user units. If
508 one of these is specified as zero, the corresponding size is
509 adjusted to the other such that the aspect ratio of the original
510 image is retained. buffer is an unsigned character array in scanline
511 orientation with 8 pixels per byte. nx, ny refers to the number of
512 pixels in the image. The rowlength of buffer must be an integral
513 number of 8; pad with zeros. buffer[0] is upper left corner. You may
514 replace the foreground color (the set bits) with the f_rgb color and
515 the background color (the unset bits) with b_rgb. Alternatively,
516 pass either color with the red component set to -1.0 and we will
517 instead issue an image mask that is see-through for the specified
518 fore- or background component. See the Adobe Systems PostScript Ref‐
519 erence Manual for more details.
520 long PSL_plotcolorimage (struct PSL_CTRL *P, double x, double y, double
522 xsize, double ysize, int justify, unsigned char *buffer, long nx, long
523 ny, long depth)
524 Plots a 1-, 2-, 4-, 8-, or 24-bit deep image at plot coordinates (x,
525 y) justified as per the argument justify (see JUSTIFICATION for
526 details). The target size of the image is given by xsize and ysize
527 in user units. If one of these is specified as zero, the correspond‐
528 ing size is adjusted to the other such that the aspect ratio of the
529 original image is retained. This functions sets up a call to the
530 PostScript colorimage or image operators. The pixel values are
531 stored in buffer, an unsigned character array in scanline orienta‐
532 tion with gray shade or r/g/b values (0-255). buffer[0] is the upper
533 left corner. depth is number of bits per pixel (24, 8, 4, 2, or 1).
534 nx, ny refers to the number of pixels in image. The rowlength of
535 buffer must be an integral number of 8/Idepth. E.g. if depth = 4,
536 then buffer[j]/16 gives shade for pixel[2j-1] and buffer[j%16 (mod
537 16) gives shade for pixel[2j]. When -depth is passed instead then
538 "hardware" interpolation of the image is requested (this is imple‐
539 mentation dependent). If -nx is passed with 8- (or 24-) bit images
540 then the first one (or three) bytes of buffer holds the gray (or
541 r/g/b) color for pixels that are to be masked out using the PS Level
542 3 Color Mask method. See the Adobe Systems PostScript Reference Man‐
543 ual for more details.
544 long PSL_plotepsimage (struct PSL_CTRL *P, double x, double y, double
546 xsize, double ysize, int justify, unsigned char *buffer, long size,
547 long nx, long ny, long ox, long oy)
548 Plots an Encapsulated PostScript (EPS) image at plot coordinates (x,
549 y) justified as per the argument justify (see JUSTIFICATION for
550 details). The target size of the image is given by xsize and ysize
551 in user units. If one of these is specified as zero, the correspond‐
552 ing size is adjusted to the other such that the aspect ratio of the
553 original image is retained. The EPS file is stored in buffer and has
554 size bytes. This function simply includes the image in the Post‐
555 Script output stream within an appropriate wrapper. Specify position
556 of lower left corner and size of image. nx, ny, ox, oy refers to the
557 width, height and origin (lower left corner) of the BoundingBox in
558 points.
559 long PSL_loadimage (struct PSL_CTRL *P, FILE *fp, struct imageinfo
561 *header, unsigned char **image)
562 Reads the image contents of the EPS file or a raster image pointed
563 to by the open file pointer fp. The routine can handle Encapsulated
564 PostScript files or 1-, 8-, 24-, or 32-bit raster images in old,
565 standard, run-length encoded, or RGB-style Sun format. Non-Sun
566 rasters are automatically reformatted to Sun rasters via a system
567 call to GraphicsMagick's or ImageMagick's convert, if installed. The
568 image is returned via the image pointer.
569
571 Here are functions used to read and plot text strings and paragraphs.
572 This can be somewhat complicated since we rely on the PostScript inter‐
573 preter to determine the exact dimensions of text items given the font
574 chosen. For perfect alignment you may have to resort to calculate off‐
575 sets explicitly using long PSL_deftextdim, PSL_set_height and others
576 and issue calculations with PSL_setcommand.
577 long PSL_plottext (struct PSL_CTRL *P, double x, double y, double font‐
579 size, char *text, double angle, long justify, long mode)
580 The text is plotted starting at plot coordinates (x, y) and will
581 make an angle with the horizontal. The point (x, y) maps onto dif‐
582 ferent points of the text-string by giving various values for jus‐
583 tify (see JUSTIFICATION for details). If justify is negative, then
584 all leading and trailing blanks are stripped before plotting. Cer‐
585 tain character sequences (flags) have special meaning to PSL_plot‐
586 text. @~ toggles between current font and the Mathematical Symbols
587 font. @%no% selects font no while @%% resets to the previous font.
588 @- turns subscript on/off, @+ turns superscript on/off, @# turns
589 small caps on/off, and @\ will make a composite character of the
590 following two character. @;r/g/b; changes the font color while @;;
591 resets it [optionally append =transparency to change the trans‐
592 parency (0--100) of the text (the Default is opaque or 0)], @:size:
593 changes the font size (@:: resets it), and @_ toggles underline
594 on/off. If text is NULL then we assume PSL_plottextbox was called
595 first. Give fontsize in points. Normally, the text is typed using
596 solid characters in the current color (set by PSL_setcolor). To draw
597 outlined characters, set mode == 1; the outline will get the current
598 color and the text is filled with the current fill color (set by
599 PSL_setfill). Use mode == 2 if the current fill is a pattern. Use
600 mode == 3 to achieve the same as mode == 1, while preventing the
601 outline from obsuring any filled text font; the outline will hence
602 be reduced to half the selected width. If the text is not filled,
603 mode == 3 operates the same as mode == 1. If fontsize is negative
604 it means that the current point has already been set before
605 PSL_plottext was called and that (x, y) should be ignored.
606 long PSL_plottextbox (struct PSL_CTRL *P, double x, double y, double
608 fontsize, char *text, double angle, long justify, double offset[], long
609 mode)
610 This function is used in conjugation with PSL_plottext when a box
611 surrounding the text string is desired. Taking most of the arguments
612 of PSL_plottext, the user must also specify mode to indicate whether
613 the box needs rounded (PSL_YES = 1) or straight (PSL_NO = 0) cor‐
614 ners. The box will be colored with the current fill style set by
615 PSL_setfill. That means, if an outline is desired, and the color of
616 the inside of the box should be set with that routine. The outline
617 will be drawn with the current pen color (and width). The offset
618 array holds the horizontal and vertical distance gaps between text
619 and the surrounding text box in distance units. The smaller of the
620 two determined the radius of the rounded corners (if requested).
621 long PSL_deftextdim (struct PSL_CTRL *P, char *prefix, double fontsize,
623 char *text)
624 Computes the dimensions (width and height) required by the selected
625 text given the current font and its fontsize (in points). The values
626 are stored as PostScript variables called prefix_w and prefix_h,
627 respectively. This function can be used to compute dimensions and,
628 via BF(PSL_setcommand), calculate chances to position a particular
629 item should be plotted. For instance, if you compute a position this
630 way and wish to plot the text there, pass the coordinates to
631 PSL_plottext as NaNs. If prefix is BF(-w), BF(-h), BF(-d) or BF(-b),
632 no PostScript variables will be assigned, but the values of width,
633 height, depth, or both width and height will be left on the Post‐
634 Script stack.
635 long PSL_setparagraph (struct PSL_CTRL *P, double line_space, double
637 par_width, long par_just)
638 Initialize common settings to be used when typesetting paragraphs of
639 text with PSL_plotparagraph. Specify the line spacing (1 equals the
640 font size) and paragraph width (in distance units). Text can be
641 aligned left (PSL_BL), centered (PSL_BC), right (PSL_BR), or justi‐
642 fied (PSL_JUST) and is controlled by par_just.
643 long PSL_plotparagraphbox (struct PSL_CTRL *P, double x, double y, dou‐
645 ble fontsize, char *text, double angle, long justify, double offset[],
646 long mode)
647 Computes and plots the text rectangle for a paragraph using the
648 specified fontsize (in points). Here, text is an array of the text
649 to be typeset, using the settings initialized by PSL_setparagraph.
650 The escape sequences described for PSL_plottext can be used to mod‐
651 ify the text. Separate text into several paragraphs by appending \r
652 to the last item in a paragraph. The whole text block is positioned
653 at plot coordinates x, y, which is mapped to a point on the block
654 specified by justify (see JUSTIFICATION for details). The whole
655 block is then shifted by the amounts shift[]. The box will be plot‐
656 ted using the current fill and outline settings. The offset array
657 holds the horizontal and vertical distance gaps between text and the
658 surrounding text box in distance units. Use mode to indicate whether
659 the box should be straight (PSL_RECT_STRAIGHT = 0), rounded
660 (PSL_RECT_ROUNDED = 1), convex (PSL_RECT_CONVEX = 2) or concave
661 (PSL_RECT_CONCAVE = 3).
662 long PSL_plotparagraph (struct PSL_CTRL *P, double x, double y, double
664 fontsize, char *text, double angle, long justify, long mode)
665 Typesets paragraphs of text using the specified fontsize (in
666 points). Here, text is an array of the text to be typeset, using the
667 settings initialized by PSL_setparagraph. The escape sequences
668 described for PSL_plottext can be used to modify the text. Separate
669 text into several paragraphs by appending \r to the last item in a
670 paragraph. The whole text block is positioned at plot coordinates x,
671 y, which is mapped to a point on the block specified by justify (see
672 JUSTIFICATION for details). See PSL_plotparagraphbox for laying down
673 the surrounding text rectangle first.
674 long PSL_plottextline (struct PSL_CTRL *P, double *xpath, double
676 *ypath, long *np, long nseg, void *arg1, void *arg2, char *text[], dou‐
677 ble angle[], long n_per_seg[], double fontsize, **long* justify, double
678 offset[], long mode)
679 Please text along one or more path segments. The function does dif‐
680 ferent things depending on the bit flags in mode. A key distinction
681 occurs if the bit flag contains the bit PSL_TXT_CURVED (64) which
682 means we wish to typeset the text along a variable and curved base‐
683 line given by the segments in xpath, ypath; otherwise we set
684 straight text (possibly at an angle) and the xpath, ypath are not
685 considered for text placement [If no line drawing is desired then
686 these two arrays may be NULL]. We will describe the action taken
687 for each bit value. Multiple values may be passed at the same time
688 and we processes from low to hight bit. PSL_TXT_INIT: When mode
689 contains this bit (1) we will initialize all the required variables
690 and store them in the PostScript file. PSL_TXT_SHOW: We wish to see
691 the text strings (otherwise they may only serve as guides to set up
692 clip paths). PSL_TXT_CLIP_ON: Use the text and the paths to set up
693 clip paths. PSL_TXT_DRAW: Draw the lines defined by the xpath,
694 ypath arrays. PSL_TXT_CLIP_OFF: Turn the text path clipping off.
695 We pass the text strings via text. The locations of text plotting
696 depends on whether PSL_TXT_CURVED is selected. If it is then you
697 must pass as arg1 the node array indicating at which node in the
698 xpath, ypath array the text will be plotted; let arg2 be NULL. For
699 straight baselines you must instead pass another set of x,y coordi‐
700 nates with the locations of the text label placements via arg1,
701 arg2. Each label has its own entry in the angle array. The text is
702 an array of text pointers to the individual text items. The offset
703 array holds the x and y distance gaps between text and the surround‐
704 ing text box in user units (the clip path is the combination of all
705 these text boxes). Use justify to specify how the text string
706 relates to the coordinates (see BF(JUSTIFICATION) for details).
707 PSL_TXT_FILLBOX (128) will fill the text box (this requires you to
708 first define the text box rgb color with PSL_define_rgb by setting a
709 local PostScript variable that must be called PSL_setboxrgb).
710 PSL_TXT_DRAWBOX (256) will draw the text box outlines (this requires
711 you to first define the text box pen with PSL_define_pen by setting
712 a local PostScript variable that must be called PSL_setboxpen).
713 Before calling this function you must also initialize a PSL array
714 for line pens and text fonts.
715
717 Here are functions used to activate and deactivate clipping regions.
718 long PSL_beginclipping (struct PSL_CTRL *P, double x, double y, long n,
720 double rgb[], long flag)
721 Sets up a user-definable clip path as a series on n points with plot
722 coordinates (x, y). Plotting outside this polygon will be clipped
723 until PSL_endclipping is called. If rgb[0] = -1 the inside of the
724 path is left empty, otherwise it is filled with the specified color.
725 flag is used to create complex clip paths consisting of several dis‐
726 connected regions, and takes on values 0-3. flag = PSL_PEN_MOVE_ABS
727 (1) means this is the first path in a multisegment clip path. flag =
728 PSL_PEN_DRAW_ABS (2) means this is the last segment. Thus, for a
729 single path, flag = PSL_PEN_DRAW_AND_STROKE_ABS (3).
730 long PSL_endclipping (struct PSL_CTRL *P, long mode)
732 Depending on the mode it restores the clip path. The mode values can
733 be: -n will restore n levels of text-based clipping, n will restore
734 n levels of polygon clipping, PSL_ALL_CLIP_TXT will undo all levels
735 of text-based clipping, and PSL_ALL_CLIP_POL will undo all levels of
736 polygon-based clipping.
737
739 Here are functions used to issue comments or to pass custom PostScript
740 commands directly to the output PostScript file. In C these functions
741 are declared as macros and they can accept a variable number of argu‐
742 ments. However, from FORTRAN only a single text argument may be passed.
743 long PSL_setcommand (struct PSL_CTRL *P, char *text)
745 Writes a raw PostScript command to the PostScript output file,
746 e.g., "1 setlinejoin.
747 long PSL_comment (struct PSL_CTRL *P, char *text)
749 Writes a comment (text) to the PostScript output file, e.g.,
750 "Start of graph 20. The comment are prefixed with with %% .
751
753 Paul Wessel, School of Ocean and Earth Science and Technology,
754 http://www.soest.hawaii.edu.
755 Remko Scharroo, EUMETSAT, Darmstadt, Germany, http://www.eumetsat.int.
757
759 Caveat Emptor: The authors are not responsible for any disasters, sui‐
760 cide attempts, or ulcers caused by correct or incorrect use of PSL. If
761 you find bugs, please report them to the authors by electronic mail. Be
762 sure to provide enough detail so that we can recreate the problem.
763
765 psconvert
766
768 Adobe Systems Inc., 1990, PostScript language reference manual, 2nd
769 edition, Addison-Wesley, (ISBN 0-201-18127-4).
770
772 2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
7735.4.5 Feb 24, 2019 POSTSCRIPTLIGHT(3)