1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
|
<HTML>
<HEAD>
<TITLE>pslib</TITLE>
</HEAD>
<BODY>
<H1>pslib</H1>
<HR>
<PRE>
<!-- Manpage converted by man2html 3.0.1 -->
pslib v3.2 - A <I>PostScript</I> based plotting library
</PRE>
<H2>DESCRIPTION</H2><PRE>
<B>pslib</B> was created to make the generation of <I>PostScript</I>
page description code easier. It is a library that con
tains a series of tools that can be used to create plots.
The resulting <I>PostScript</I> code is ASCII text and can be
edited using any text editor. Thus, it is fairly easy 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 penwidths etc. <B>pslib</B> is written
in C but now includes FORTRAN bindings (thanks to John
Goff, WHOI) and can therefore be called from both C and
FORTRAN programs. To use this library, you must link your
plotting program with pslib.a. <B>pslib</B> is the core of the
<B><A HREF="GMT.html">GMT</A></B> <B>SYSTEM</B> and <B>XY</B> graphics programs. <B>pslib</B> output conforms
to the Adobe Encapsulated <I>PostScript</I> File Specification
Version 3.0 (EPSL), and may be used as EPS files and
inserted into, say, a Word document on a Mac. See Appendix
F in the Technical Reference for detailed instructions.
Before any <B>pslib</B> calls can be issued, the plotting system
must be initialized. This is done by calling <B>ps_plotinit</B>,
which defines macros, sets up the plot-coordinate system,
scales, and [optionally] opens a file where all the
<I>PostScript</I> code will be written. Normally, the plot code
is written to <I>stdout</I>. The measure unit for sizes and posi
tions can be set to be centimeter, inch, or m. When all
plotting is done, you must terminate the plotting system
by calling <B>ps_plotend</B>.
<B>pslib</B> uses the direct color model where red, green, and
blue are given separately, each must be in the range from
0-255. If red < 0 then no fill operation takes place.
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 linewidth and pattern. <B>pslib</B> 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.
A wide variety of output devices that support <I>PostScript</I>
exist, including laserwriters (color or monochrome) and
workstations running <I>PostScript</I> based window systems like
SUNs OpenWindows. xnews (part of OpenWindows) or
ghostscript (public domain) can be used to create raster
files at a user-defined resolution (DPI), making it possi
ble to render <I>PostScript</I> on a Versatec and other non-
<I>PostScript</I> raster devices. Regular SUN rasterfiles created
under NeWS from <I>PostScript</I> files can be sent to a variety
of color hardcopy units. Check the devices available on
your network.
The following is a list of available functions and a short
description of what they do and what parameters they
expect. All floating point variables are expected to be
<B>double</B> (i.e., 8 bytes), whereas all integers are assumed
to be 4 bytes long. All plotting functions are declared as
functions returning an int. Currently, the return value is
undefined.
void <B>ps_arc</B> (<I>x,</I> <I>y,</I> <I>radius,</I> <I>angle1,</I> <I>angle2,</I> <I>status</I>)
<B>double</B> <I>x,</I> <I>y,</I> <I>radius,</I> <I>angle1,</I> <I>angle2</I>;
<B>int</B> <I>status</I>;
Draws a circular arc centered on (<I>x,y</I>) from
angle <I>angle1</I> to <I>angle2</I>. Angles must be given in
decimal degrees. If angle1 > angle2, a negative
arc is drawn. <I>status</I> is a value from 0 through
3. 1 means set new anchor point, 2 means stroke
the circle, 3 means both, 0 means none of the
above.
void <B>ps_axis</B> (<I>xpos,</I> <I>ypos,</I> <I>length,</I> <I>startval,</I> <I>stop</I>
<I>val,</I> <I>tickval,</I> <I>label,</I> <I>anotpointsize,</I> <I>side</I>)
<B>double</B> <I>xpos,</I> <I>ypos,</I> <I>length,</I> <I>startval,</I> <I>stopval,</I> <I>tick</I>
<I>val</I>;
<B>int</B> <I>anotpointsize,</I> <I>side</I>;
<B>char</B> <I>*label</I>;
Plots an axis with tickmarks, annotation, and
label. <I>xpos,</I> <I>ypos</I>, and <I>length</I> are in inches (or
cm or meters), <I>anotpointsize</I> in points (72
points = 1 inch), else data units are used. <I>side</I>
can be 0, 1, 2, or 3, which selects lower x-
axis, right y-axis, upper x-axis, or left y-
axis, respectively. labelpointsize = 1.5 * <I>anot</I>
<I>pointsize</I>. A negative <I>tickval</I> will reverse the
sense of positive direction, e.g., to have the
y-axis be positive down.
void <B>ps_circle</B> (<I>xcenter,</I> <I>ycenter,</I> <I>diameter,</I> <I>rgb,</I>
<I>outline</I>)
<B>double</B> <I>xcenter,</I> <I>ycenter,</I> <I>diameter</I>;
<B>int</B> <I>rgb[3],</I> <I>outline</I>;
Plots a circle and fills it with the specified
color. If <I>outline</I> == 1, the outline will be
drawn using current pen-width and -pattern.
void <B>ps_clipoff</B> ()
Resets the clip path to what it was before the
last call to <B>clipon</B>.
void <B>ps_clipon</B> (<I>xarray,</I> <I>yarray,</I> <I>npoints,</I> <I>rgb,</I> <I>flag</I>)
<B>double</B> <I>xarray[],</I> <I>yarray[]</I>;
<B>int</B> <I>npoints,</I> <I>rgb[3],</I> <I>flag</I>;
<B>ps_clipoff</B> is called. If <I>red</I> >= 0 the inside of
the path is filled with the specified color.
<I>flag</I> is used to create complex clip paths con
sisting of several disconnected regions, and
takes on values 0-3. <I>flag</I> = 1 means this is the
first path in a multi-segment clip path. <I>flag</I> =
2 means this is the last segment. Thus, for a
single path, <I>flag</I> = 3.
void <B>ps_colorimage</B> (<I>xpos,</I> <I>ypos,</I> <I>xlength,</I> <I>ylength,</I>
<I>buffer,</I> <I>nx,</I> <I>ny</I>)
<B>double</B> <I>xpos,</I> <I>ypos,</I> <I>xlength,</I> <I>ylength</I>;
<B>unsigned</B> <B>char</B> <I>buffer[]</I>;
<B>int</B> <I>nx,</I> <I>ny</I>;
Plots a 24-bit true color image using rgb col
ors. Similar to <I>ps</I><B>_</B><I>image</I> except <I>bits</I> is fixed to
be 8. The rgb triplets are stored in <I>buffer</I> as
rgbrgbrgb... This functions sets up a call to
the <I>PostScript</I> colorimage operator which is not
implemented in all drivers.
void <B>ps_colortiles</B> (<I>x0,</I> <I>y0,</I> <I>xlength,</I> <I>ylength,</I>
<I>buffer,</I> <I>nx,</I> <I>ny</I>)
<B>double</B> <I>x0,</I> <I>y0,</I> <I>xlength,</I> <I>ylength</I>;
<B>int</B> <I>nx,</I> <I>ny</I>;
<B>unsigned</B> <B>char</B> <I>buffer[]</I>;
Plots a true color image based on individual
color tiles. <I>x0,</I> <I>y0</I> is the location of the lower
left corner of the image in inches. <I>xlength,</I>
<I>ylength</I> is the image size in inches. <I>buffer</I> con
tains rgb triplets stored as rgbrgbrgb... <I>nx,</I> <I>ny</I>
is the image size in pixels.
void <B>ps_command</B> (<I>text</I>)
<B>char</B> <I>*text</I>;
Writes a raw <I>PostScript</I> command to the
<I>PostScript</I> output file, e.g. "1 setlinejoin".
void <B>ps_comment</B> (<I>text</I>)
<B>char</B> <I>*text</I>;
Writes a comment (<I>text</I>) to the <I>PostScript</I> output
file, e.g. "Start of graph 2".
void <B>ps_cross</B> (<I>xcenter,</I> <I>ycenter,</I> <I>diameter</I>)
<B>double</B> <I>xcenter,</I> <I>ycenter,</I> <I>diameter</I>;
Plots a cross at the specified point using cur
rent pen-width and -pattern that fits inside a
circle of given diameter.
void <B>ps_diamond</B> (<I>xcenter,</I> <I>ycenter,</I> <I>diameter,</I> <I>rgb,</I>
<I>outline</I>)
<B>double</B> <I>xcenter,</I> <I>ycenter,</I> <I>diameter</I>;
color. If <I>outline</I> == 1, the outline will be
drawn using current pen-width and -pattern. The
symbol will fit inside a circle of given diame
ter.
void <B>ps_ellipse</B> (<I>xcenter,</I> <I>ycenter,</I> <I>angle,</I> <I>major,</I>
<I>minor,</I> <I>rgb,</I> <I>outline</I>)
<B>double</B> <I>xcenter,</I> <I>ycenter,</I> <I>angle,</I> <I>major,</I> <I>minor</I>;
<B>int</B> <I>rgb[3],</I> <I>outline</I>;
Plots a ellipse with its major semiaxis rotated
by <I>angle</I> degrees and fills it with the specified
color. If <I>outline</I> == 1, the outline will be
drawn using current pen-width and -pattern.
void <B>ps_flush</B> ()
Flushes the output buffer.
void <B>ps_hexagon</B> (<I>xcenter,</I> <I>ycenter,</I> <I>diameter,</I> <I>rgb,</I>
<I>outline</I>)
<B>double</B> <I>xcenter,</I> <I>ycenter,</I> <I>diameter</I>;
<B>int</B> <I>rgb[3],</I> <I>outline</I>;
Plots a hexagon and fills it with the specified
color. If <I>outline</I> == 1, the outline will be
drawn using current pen-width and -pattern. The
symbol will fit inside a circle of given diame
ter.
void <B>ps_image</B> (<I>xpos,</I> <I>ypos,</I> <I>xlength,</I> <I>ylength,</I>
<I>buffer,</I> <I>nx,</I> <I>ny,</I> <I>bits</I>)
<B>double</B> <I>xpos,</I> <I>ypos,</I> <I>xlength,</I> <I>ylength</I>;
<B>unsigned</B> <B>char</B> <I>buffer[]</I>;
<B>int</B> <I>nx,</I> <I>ny,</I> <I>bits</I>;
Plots a bit-mapped image using grayshades. Spec
ify position of lower left corner and size (in
inches) of image. <I>buffer</I> is an unsigned charac
ter array with gray shade values (0 - 255) where
0 is black, 255 is white. <I>bits</I> is number of bits
pr pixel (8, 4, or 1). <I>nx,ny</I> refers to the num
ber of pixels in image. The rowlength of <I>buffer</I>
must be an integral number of 8/<I>bits.</I> <I>buffer[0]</I>
is upper left corner. E.g. if <I>bits</I> = 4, then
<I>buffer[j]</I>/16 gives shade for pixel[2j-1] and
<I>buffer[j]</I>%16 (mod 16) gives shade for pixel[2j].
<I>buffer</I> values are stored as columns, starting at
the lower left corner and ending at the upper
right corner. See the Adobe Systems <I>PostScript</I>
Reference Manual for more details.
void <B>ps_imagefill</B> (<I>x,</I> <I>y,</I> <I>n,</I> <I>image,</I> <I>imagefile,</I>
<I>invert,</I> <I>imagedpi,</I> <I>outline,</I> <I>template,</I> <I>r</I><B>_</B><I>rgb,</I> <I>b</I><B>_</B><I>rgb</I>)
<B>double</B> <I>x[],</I> <I>y[],</I> <I>x0,</I> <I>y0</I>;
<B>int</B> <I>n,</I> <I>image,</I> <I>invert,</I> <I>imagedpi,</I> <I>outline,</I> <I>template,</I>
Similar to <B>ps_polygon</B>, but fills the area with
an image pattern rather than a color or
grayshade. <I>x</I> and <I>y</I> hold the arrays of <I>n</I> points.
90 predefined patterns are available (See <A HREF="GMT.html">GMT</A>
Appendix E). <I>image</I> gives the image number
(1-90). If set to 0, <I>imagefile</I> must be the name
to the user's image, which must be stored as a'
SUN 1-, 8-, or 24-bit rasterfile. 1-bit images
only: (i) If <I>invert</I> is TRUE (1), the black and
white pixels are interchanged before plotting.
(ii) If template is TRUE (1), the set pixels are
colored using the RGB combination in <I>f</I><B>_</B><I>rgb</I>,
while the unset are painted with <I>b</I><B>_</B><I>rgb</I>. The unit
size of the image is controlled by <I>imagedpi</I>. If
set to zero, the image is plotted at the device
resolution. If <I>outline</I> is TRUE, the current pen
width is used to draw the polygon outline.
void <B>ps_imagemask</B> (<I>xpos,</I> <I>ypos,</I> <I>xlength,</I> <I>ylength,</I>
<I>buffer,</I> <I>nx,</I> <I>ny,</I> <I>polarity,</I> <I>rgb</I>)
<B>double</B> <I>xpos,</I> <I>ypos,</I> <I>xlength,</I> <I>ylength</I>;
<B>unsigned</B> <B>char</B> <I>buffer[]</I>;
<B>int</B> <I>nx,</I> <I>ny,</I> <I>polarity,</I> <I>rgb[3]</I>;
Plots a transparent 1-bit image mask using the
given <I>rgb</I> color. Specify position of lower left
corner and size (in inches) of image. <I>buffer</I> is
an unsigned character array with 8 pixels per
byte. <I>nx,ny</I> refers to the number of pixels in
image. The rowlength of <I>buffer</I> must be an inte
gral number of 8. buffer[0] <I>is</I> <I>upper</I> <I>left</I> <I>cor</I>
<I>ner.</I> <I>buffer</I> <I>values</I> <I>are</I> <I>stored</I> <I>as</I> <I>columns,</I> <I>start</I>
<I>ing</I> <I>at</I> <I>the</I> <I>lower</I> <I>left</I> <I>corner</I> <I>and</I> <I>ending</I> <I>at</I> <I>the</I>
<I>upper</I> <I>right</I> <I>corner.</I> <I>If</I> <I>polarity</I> <I>is</I> <I>0</I> <I>then</I> <I>the</I>
<I>bits</I> <I>that</I> <I>are</I> <I>0</I> <I>are</I> <I>painted</I> <I>with</I> <I>the</I> <I>rgb</I> <I>color,</I>
<I>else</I> <I>the</I> <I>bits</I> <I>that</I> <I>are</I> <I>1</I> <I>are</I> <I>colored.</I> <I>See</I> <I>the</I>
<I>Adobe</I> <I>Systems</I> <I>PostScript</I> Reference Manual for
more details.
void <B>ps_itriangle</B> (<I>xcenter,</I> <I>ycenter,</I> <I>diameter,</I> <I>rgb,</I>
<I>outline</I>)
<B>double</B> <I>xcenter,</I> <I>ycenter,</I> <I>diameter</I>;
<B>int</B> <I>rgb[3],</I> <I>outline</I>;
Plots an inverted and fills it with the speci
fied color. If <I>outline</I> == 1, the outline will be
drawn using current pen-width and -pattern. The
symbol will fit inside a circle of given diame
ter.
void <B>ps_line</B> (<I>xarray,</I> <I>yarray,</I> <I>npoints,</I> <I>type,</I> <I>close,</I>
<I>split</I>)
<B>double</B> <I>xarray[],</I> <I>yarray[]</I>;
<B>int</B> <I>npoints,</I> <I>type,</I> <I>close,</I> <I>split</I>;
point will automatically be closed by the
<I>PostScript</I> driver. If this is the first segment
in a multi-segment path, set <I>type</I> == 1. To end
the segments and have the line(s) drawn, set
<I>type</I> == 2. Thus, for a single segment, <I>type</I> must
be 3. The line is drawn using the current pen
width. Only if <I>split</I> is TRUE may ps_line use
multiple strokes to draw lines longer that
MAX_PATH. ps_polygon will call ps_line with
<I>split</I> = FALSE since the path must be continuous.
If <I>split</I> is FALSE and the pathlength exceeds
MAX_PATH a warning will be issued.
unsigned char <B>*ps_loadraster</B> (<I>fp,</I> <I>header,</I> <I>invert,</I>
<I>monochrome,</I> <I>template,</I> <I>f</I><B>_</B><I>rgb,</I> <I>b</I><B>_</B><I>rgb</I>)
<B>FILE</B> <I>*fp</I>;
<B>struct</B> <B>rasterfile</B> <I>*header</I>;
<B>BOOLEAN</B> <I>invert,</I> <I>monochrome,</I> <I>template</I>;
<B>int</B> <I>f</I><B>_</B><I>rgb[],</I> <I>b</I><B>_</B><I>rgb[]</I>;
Reads the image contents of the Sun rasterfile
pointed to by the open filepointer <I>fp</I>. The
<I>header</I> must first be obtained with
<B>ps_read_rasheader</B>. If <I>invert</I> is TRUE then 1-bit
images will be bit-reversed. If <I>monochrome</I> is
TRUE then color images are converted to grayim
ages using the TV YIQ translation. If <I>template</I>
is TRUE then 1-bit images will be colorized
using the for- and background colors provided in
<I>f</I><B>_</B><I>rgb</I> and <I>b</I><B>_</B><I>rgb</I>. The routine can handle 1-, 8-,
24-, or 32-bit files in old, standard, run-
length encoded, or RGB-style Sun format.
void <B>ps_patch</B> (<I>xarray,</I> <I>yarray,</I> <I>npoints,</I> <I>rgb,</I> <I>out</I>
<I>line</I>)
<B>double</B> <I>xarray[],</I> <I>yarray[]</I>;
<B>int</B> <I>npoints,</I> <I>rgb[3],</I> <I>outline</I>;
Identical to <B>ps_polygon</B> except polygon must be <
20 points long and there will be no attempt to
shorten the path by discarding unnecessary
intermediate points along straight segments.
Primarily used when painting large number of
small polygons and not waste output space.
void <B>ps_pie</B> (<I>xcenter,</I> <I>ycenter,</I> <I>radius,</I> <I>azimuth1,</I>
<I>azimuth2,</I> <I>rgb,</I> <I>outline</I>)
<B>double</B> <I>xcenter,</I> <I>ycenter,</I> <I>radius,</I> <I>azimuth1,</I>
<I>azimuth2</I>;
<B>int</B> <I>rgb[3],</I> <I>outline</I>;
Plots a sector of a circle and paints it with
the specified RGB combination. If <I>outline</I> == 1,
the outline will be drawn using current pen-
width and -pattern.
<B>double</B> <I>xabs,</I> <I>yabs</I>;
<B>int</B> <I>kpen;</I>
Absolute move (<I>kpen</I>=3) or draw (<I>kpen=</I>2), using
current linewidth.
void <B>ps_plotend</B> (<I>last</I><B>_</B><I>page</I>)
<B>int</B> <I>last</I><B>_</B><I>page</I>;
Terminates the plotting sequence and closes plot
file (if other than <I>stdout</I>). If <I>last</I><B>_</B><I>page</I> == 1,
then a <I>PostScript</I> showpage command is issued,
which initiates the printing process on hardcopy
devices.
void <B>ps_plotinit</B> (<I>plotfile,</I> <I>overlay,</I> <I>mode,</I> <I>xoff,</I>
<I>yoff,</I> <I>xscl,</I> <I>yscl,</I> <I>ncopies,</I> <I>dpi,</I> <I>unit,</I> <I>pagesize,</I>
<I>rgb,</I> <I>eps</I>)
<B>char</B> <I>*plotfile;</I>
<B>int</B> <I>overlay,</I> <I>mode,</I> <I>ncopies,</I> <I>dpi,</I> <I>unit</I>;
<B>double</B> <I>xoff,</I> <I>yoff,</I> <I>xscl,</I> <I>yscl</I>;
<B>int</B> <I>pagesize[2],</I> <I>rgb[3]</I>; <B>struct</B> <B>EPS</B> <B>*</B> <I>eps</I>;
Initializes the plotting. If <I>plotfile</I> == NULL
(or ""), then output is sent to <I>stdout</I>, else
output is sent to <I>plotfile</I>. <I>overlay</I> should be 1
only if you plan to append it to some existing
<I>PostScript</I> file. <I>mode</I> contains three flags in
the three lowest bits. The lowest bit controls
the plot orientation and can be 0 (Landscape) or
1 (Portrait). The next bit, if set to 1, will
re-encode the fonts to include European accented
characters. The third bit controls the format
used to write PostScript images: 0 means binary,
1 means hexadecimal. Most printers needs the
latter while some can handle binary which are
50% smaller and therefore execute faster.
<I>xoff,yoff</I> are used to move the origin from the
default position in the lower left corner.
<I>xscl,yscl</I> are used to scale the entire plot
(Usually set to 1.0, 1.0). Set <I>ncopies</I> to get
more than 1 copy. <I>dpi</I> sets the hardcopy resolu
tion in dots pr units. For optimum plot quality
and processing speed, choose <I>dpi</I> to match the
intended plotter resolution. Examples are 300
for most laserwriters, 2540 for Linotype-300,
and ~85 for SUN screens. When in doubt, use 300.
<I>unit</I> can be any of 0 (CM), 1 (INCH), or 2 (M),
telling the plot system what units are used for
distance and sizes. Note that, regardless of
choice of unit, dpi is still in dots-pr-inch.
<I>pagesize</I> means the physical width and height of
the plotting media in points, (typically 612 by
792 for Letter or 595 by 842 for A4 laserwriter
plotters. The <I>rgb</I> array holds the color of the
and contains information that will make up the
comments header of a EPS file. Programmers who
plan to call pslib routines should read the com
ments in pslib.h first. Note that the FORTRAN
binding does not expect this last argument.
void <B>ps_plotr</B> (<I>xrel,</I> <I>yrel,</I> <I>kpen</I>)
<B>double</B> <I>xrel,</I> <I>yrel</I>;
<B>int</B> <I>kpen</I>;
Move (<I>kpen</I> = 3) or draw (<I>kpen</I> = 2) relative to
current point (see <B>ps_plot</B>).
void <B>ps_polygon</B> (<I>xarray,</I> <I>yarray,</I> <I>npoints,</I> <I>rgb,</I> <I>out</I>
<I>line</I>)
<B>double</B> <I>xarray[],</I> <I>yarray[]</I>;
<B>int</B> <I>npoints,</I> <I>rgb[3],</I> <I>outline</I>;
Creates a colored polygon from the positions in
the x-y arrays. Polygon will automatically be
closed by the <I>PostScript</I> driver. If <I>outline</I> ==
0, no outline is drawn. If <I>outline</I> == 1, the
outline is drawn using current penwidth.
int <B>ps_read_rasheader</B> (<I>fp,</I> <I>header</I>)
<B>FILE</B> <I>*fp</I>;
<B>struct</B> <B>rasterfile</B> <I>*header</I>;
Using the pointer <I>fp</I> to the open file, return
the header structure of the Sun rasterfile. This
call is portable as it operates on the byte
level. Once the header is returned you may
obtain the raster image with <B>ps_loadraster</B>.
void <B>ps_rect</B> (<I>x1,</I> <I>y1,</I> <I>x2,</I> <I>y2,</I> <I>rgb,</I> <I>outline</I>)
<B>double</B> <I>x1,</I> <I>y1,</I> <I>x2,</I> <I>y2</I>;
int r<I>ed,</I> <I>green,</I> <I>blue,</I> <I>outline;</I>
Plots a colored rectangle. (<I>x1,y1)</I> and (<I>x2,y2</I>)
are any two corners on a diagonal. If <I>outline</I>
== 1, the outline will be drawn using current
pen-width and -pattern.
void <B>ps_rotatetrans</B> (<I>x,</I> <I>y,</I> <I>angle</I>)
<B>double</B> <I>x,</I> <I>y,</I> <I>angle</I>;
Rotates the coordinate system by <I>angle</I> degrees,
then translates origin to (<I>x,y</I>).
void <B>ps_setdash</B> (<I>pattern,</I> <I>offset</I>)
<B>char</B> <I>*pattern;</I>
<B>int</B> <I>offset;</I>
Changes the current dashpattern. The character
string <I>pattern</I> is set to the desired pattern.
E.g., "4 2" and <I>offset</I> = 1 will plot like:
x ---- ---- ----
etc, where x is starting point (The x is not
unit long gap, starting 1 unit after the x. To
reset to solid line, specify <I>pattern</I> = NULL ("")
and <I>offset</I> = 0. Units are in dpi units.
void <B>ps_setfont</B> (<I>fontnr</I>)
<B>int</B> <I>fontnr</I>;
Changes the current font number to <I>fontnr</I>. 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.-Demi
Italic, 19 = B.-Light, 20 = B.-LightItalic, 21 =
Helvetica-Narrow, 22 = H-N-Bold, 23 = H-N-
Oblique, 24 = H-N-BoldOblique, 25 = NewCentu
rySchlbk-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. If <I>fontnr</I> is out
side this range, it is set to 0.
void <B>ps_setformat</B> (<I>n</I><B>_</B><I>decimals</I>)
<B>int</B> <I>n</I><B>_</B><I>decimals</I>;
Sets 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 combi
nations.
void <B>ps_setline</B> (<I>linewidth</I>)
<B>int</B> <I>linewidth</I>;
Changes the current linewidth in DPI units. 0
gives thinnest line, but the use of 0 is imple
mentation-dependent (Works fine on most laser
writers).
void <B>ps_setpaint</B> (<I>rgb</I>)
<B>int</B> <I>rgb[3]</I>;
Changes the current RGB setting for pens and
text.
void <B>ps_square</B> (<I>xcenter,</I> <I>ycenter,</I> <I>diameter,</I> <I>rgb,</I>
<I>outline</I>)
Plots a square and fills it with the specified
color. If <I>outline</I> == 1, the outline will be
drawn using current pen-width and -pattern. The
symbol will fit inside a circle of given diame
ter.
void <B>ps_star</B> (<I>xcenter,</I> <I>ycenter,</I> <I>diameter,</I> <I>rgb,</I> <I>out</I>
<I>line</I>)
<B>double</B> <I>xcenter,</I> <I>ycenter,</I> <I>diameter</I>;
<B>int</B> <I>rgb[3],</I> <I>outline</I>;
Plots a star and fills it with the specified
color. If <I>outline</I> == 1, the outline will be
drawn using current pen-width and -pattern. The
symbol will fit inside a circle of given diame
ter.
void <B>ps_text</B> (<I>x,</I> <I>y,</I> <I>pointsize,</I> <I>text,</I> <I>angle,</I> <I>jus</I>
<I>tify,</I> <I>form</I>)
<B>double</B> <I>x,</I> <I>y,</I> <I>angle</I>;
<B>char</B> <I>*text</I>;
<B>int</B> <I>pointsize,</I> <I>justify,</I> <I>form</I>;
The <I>text</I> is plotted starting at (<I>x,y</I>), and will
make an <I>angle</I> with the horizontal. The point
(<I>x,y</I>) maps onto different points of the
textstring by giving various values for <I>justify</I>.
It is used as follows:
9------------10----------- 11
| |
5 6 7
| |
1------------ 2------------ 3
The box represents the textstring. E.g., to plot
a textstring with its center of gravity at
(<I>x,y</I>), you must use <I>justify</I> == 6. If <I>justify</I> is
negative, then all leading and trailing blanks
are stripped before plotting. Certain character
sequences (flags) have special meaning to
ps_text. @~ toggles between current font and the
Mathematical Symbols font. @%<I>no</I>% sets font to
<I>no</I>; @%% resets to starting font. @- turns sub
script on/off, @+ turns superscript on/off, @#
turns small caps on/off, and @\ will make a com
posite character of the following two character.
Give fontsize in points (72 points = 1 inch).
Normally, the text is typed using solid charac
ters. To draw outline characters, set <I>form</I> ==
1.
void <B>ps_textbox</B> (<I>x,</I> <I>y,</I> <I>pointsize,</I> <I>text,</I> <I>angle,</I> <I>jus</I>
<I>tify,</I> <I>outline,</I> <I>dx,</I> <I>dy,</I> <I>rgb</I>)
<B>double</B> <I>x,</I> <I>y,</I> <I>angle,</I> <I>dx,</I> <I>dy</I>;
This function is used in conjugation with
<B>ps_text</B> when a box surrounding the text string
is desired. Taking most of the arguments of
<B>ps_text</B>, the user must also specify the color of
the resulting rectangle, and whether its outline
should be drawn. More room between text and
rectangle can be obtained by setting <I>dx</I> and <I>dy</I>
accordingly.
void <B>ps_transrotate</B> (<I>x,</I> <I>y,</I> <I>angle</I>)
<B>double</B> <I>x,</I> <I>y,</I> <I>angle</I>;
Translates the origin to (<I>x,y</I>), then rotates the
coordinate system by <I>angle</I> degrees.
void <B>ps_triangle</B> (<I>xcenter,</I> <I>ycenter,</I> <I>diameter,</I> <I>rgb,</I>
<I>outline</I>)
<B>double</B> <I>xcenter,</I> <I>ycenter,</I> <I>diameter</I>;
<B>int</B> <I>rgb[3],</I> <I>outline</I>;
Plots a triangle and paints it with the speci
fied RGB combination. If <I>outline</I> == 1, the out
line will be drawn using current pen-width and
-pattern. The symbol will fit inside a circle
of given diameter.
void <B>ps_vector</B> (<I>xtail,</I> <I>ytail,</I> <I>xtip,</I> <I>ytip,</I> <I>tail</I>
<I>width,</I> <I>headlength,</I> <I>headwidth,</I> <I>headshape,</I> <I>rgb,</I> <I>out</I>
<I>line</I>)
<B>double</B> <I>xtail,</I> <I>ytail,</I> <I>xtip,</I> <I>ytip,</I> <I>tailwidth,</I>
<I>headlength,</I> <I>headwidth,</I> <I>headshape</I>;
<B>int</B> <I>rgb[3],</I> <I>outline</I>;
Draws a vector of size and appearance as speci
fied by the various parameters. <I>headshape</I> 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 gives a triangular head,
1.0 gives an arrow shaped head. If <I>outline</I> == 1,
the outline will be drawn using current pen
width.
void <B>ps_words</B> (<I>x,</I> <I>y,</I> <I>text,</I> <I>n</I><B>_</B><I>words,</I> <I>line</I><B>_</B><I>space,</I>
<I>par</I><B>_</B><I>width,</I> <I>par</I><B>_</B><I>just,</I> <I>font,</I> <I>font</I><B>_</B><I>size,</I> <I>angle,</I> <I>rgb,</I>
<I>justify,</I> <I>draw</I><B>_</B><I>box,</I> <I>x</I><B>_</B><I>off,</I> <I>y</I><B>_</B><I>off,</I> <I>x</I><B>_</B><I>gap,</I> <I>y</I><B>_</B><I>gap,</I> <I>box</I>
<I>pen</I><B>_</B><I>width,</I> <I>boxpen</I><B>_</B><I>texture,</I> <I>boxpen</I><B>_</B><I>offset,</I> <I>box</I>
<I>pen</I><B>_</B><I>rgb,</I> <I>vecpen</I><B>_</B><I>width,</I> <I>vecpen</I><B>_</B><I>texture,</I> <I>vecpen</I><B>_</B><I>off</I>
<I>set,</I> <I>vecpen</I><B>_</B><I>rgb,</I> <I>boxfill</I><B>_</B><I>rgb</I>)
<B>double</B> <I>x,</I> <I>y,</I> <I>line</I><B>_</B><I>space,</I> <I>par</I><B>_</B><I>width,</I> <I>angle,</I> <I>x</I><B>_</B><I>off,</I>
<I>y</I><B>_</B><I>off,</I> <I>x</I><B>_</B><I>gap,</I> <I>y</I><B>_</B><I>gap</I>;
<B>int</B> <I>n</I><B>_</B><I>words,</I> <I>font,</I> <I>font</I><B>_</B><I>size,</I> <I>justify,</I> <I>draw</I><B>_</B><I>box,</I>
<I>boxpen</I><B>_</B><I>width,</I> <I>boxpen</I><B>_</B><I>offset</I>;
<B>int</B> <I>boxpen</I><B>_</B><I>rgb[3],</I> <I>vecpen</I><B>_</B><I>width,</I> <I>vecpen</I><B>_</B><I>offset,</I>
<I>vecpen</I><B>_</B><I>rgb[3],</I> <I>boxfill</I><B>_</B><I>rgb[3]</I>;
the words to typeset, using the given line-spac
ing and paragraph width. The whole text block is
positioned at <I>x,</I> <I>y</I> which is the anchor point on
the box as indicated by <I>justify</I> (see ps_text).
The whole block is then shifted by <I>x</I><B>_</B><I>off,</I> <I>y</I><B>_</B><I>off</I>.
Inside the box, text is justified left, cen
tered, right, or justified as governed by
<I>par</I><B>_</B><I>just</I> (lcrj). <I>draw</I><B>_</B><I>box</I> contains 4 bit flags
pertaining to the surrounding outline box. If
on, the first (lowest) bit draws the box out
line. The second bit fills the box interior. The
third bit makes the outline box have rounded
corners (unless <I>x</I><B>_</B><I>gap,</I> <I>y</I><B>_</B><I>gap</I>, which specifies
the padding between the text and the box, are
zero), while the forth bit draws a line from the
original <I>x,</I> <I>y</I> point to the shifted position. The
escape sequences described for ps_text applies
here, as well as two additional commands:
@;<I>r/g/b</I>; changes the font color (@;; resets it),
and @:<I>size</I>: changes the font size (@:: resets
it).
</PRE>
<H2>AUTHOR</H2><PRE>
Paul Wessel, School of Ocean and Earth Science and Tech
nology, 1680 East-West Road, Honolulu, Hawaii 96822, (808)
956-4778, Internet address: wessel@soest.hawaii.edu.
</PRE>
<H2>BUGS</H2><PRE>
Caveat Emptor: The author is <B>not</B> responsible for any dis
asters, suicide attempts, or ulcers caused by correct <B>or</B>
incorrect use of <B>pslib</B>. If you find bugs, please report
them to the author by electronic mail. Be sure to provide
enough detail so that I can recreate the problem.
</PRE>
<H2>RESTRICTIONS</H2><PRE>
Due to the finite memory of some output devices like
Laserwriters, certain restrictions due to limitations of
the <I>PostScript</I> interpreter apply: For now, the arrays
passed to <B>ps_clipon</B> and <B>ps_polygon</B> must contain less than
about 1350 points. Also, the buffer array passed to
<B>ps_image</B> must be able to fit in the available memory.
Check the specifications of the hardcopy device you are
using. Note that some Raster Image Processors (RIPs) do
not support direct color so that the colors you get may
not be exactly the ones you wanted. This is a limitation
of the RIP, not the underlying <I>PostScript</I> code generated
by <B>pslib</B>.
</PRE>
<H2>REFERENCES</H2><PRE>
Adobe Systems Inc., 1990, <I>PostScript</I> language reference
manual, 2nd edition, Addison-Wesley, (ISBN 0-201-18127-4).
</PRE>
<HR>
<ADDRESS>
Man(1) output converted with
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
</ADDRESS>
</BODY>
</HTML>
<body bgcolor="#ffffff">
|
