3
Copyright (c) 1996, 1997, The Regents of the University of
4
California. All rights reserved. See Legal.htm for full
7
This is the help file for the Python Gist Graphics Module. Gist
8
is a portable graphics package for scientific applications. It
9
can produce interactive graphics in the X-window and Macintosh
10
environments (the Python module currently supports only X11), and
11
it can produce file output conforming to ANSI standard CGM or
14
Gist was developed by David H. Munro <munro@icf.llnl.gov> at
15
Lawrence Livermore National Laboratory, as part of his Yorick
16
scientific interpreter. Gist is distributed as part of Yorick, and
17
is available at the following sites:
19
wuarchive.wustl.edu: /languages/yorick/yorick-1.2.tar.gz
20
sunsite.unc.edu: /pub/languages/yorick/yorick-1.2.tar.gz
21
sunsite.unc.edu: /pub/Linux/apps/math/matrix/yorick-1.2.tar.gz
22
netlib.att.com: /netlib/env/yorick-1.2.tar.gz
23
netlib2.cs.utk.edu: /env/yorick-1.2.tar.gz
25
Much of the code in the Python Gist C extension module was
26
adapted from similar code in Yorick, and this help file also
27
originated there. I am greatly indebted to Dave for his prior work.
28
Questions about this module should be directed to me, Lee Busby,
31
/*--------------------------------------------------------------------------*/
32
/* Control functions */
35
window( [n] [, display = "host:server.screen", dpi=100/75, wait=0/1,
36
private=0/1, hcp="hcp_filename", dump=0/1,
37
legends=1/0, style="style_sheet_filename" ] )
38
select window N as the current graphics output window. N may
39
range from 0 to 7, inclusive. Each graphics window corresponds to
40
an X window, and optionally has its own associated hardcopy file.
41
If N is omitted, it defaults to the current coordinate system.
43
The X window will appear on your default display at 75 dpi, unless
44
you specify the display and/or dpi keywords. A dpi=100 X window
45
is larger than a dpi=75 X window; both represent the same thing
46
on paper. Use display="" to create a graphics window which has
47
no associated X window (you should do this if you want to make
48
plots in a non-interactive batch mode).
50
By default, an X window will attempt to use shared colors, which
51
permits several Pygist graphics windows (including windows from
52
multiple instances of Python) to use a common palette. You can
53
force an X window to post its own colormap (set its colormap
54
attribute) with the private=1 keyword. You will most likely have
55
to fiddle with your window manager to understand how it handles
56
colormap focus if you do this. Use private=0 to return to shared
59
By default, Python will not wait for the X window to become visible;
60
code which creates a new window, then plots a series of frames to
61
that window should use wait=1 to assure that all frames are actually
64
By default, a graphics window does NOT have a hardcopy file
65
of its own -- any request for hardcopy are directed to the
66
default hardcopy file, so hardcopy output from any window goes
67
to a single file. By specifying the hcp keyword, however, a
68
hardcopy file unique to this window will be created. If the
69
"hcp_filename" ends in ".ps", the hardcopy file will be a PostScript
70
file; otherwise, hardcopy files are in binary CGM format. Use
71
hcp="" to revert to the default hardcopy file (closing the window
72
specific file, if any). The legends keyword, if present, controls
73
whether the curve legends are (legends=1, the default) or are not
74
(legends=0) dumped to the hardcopy file. The dump keyword, if
75
present, controls whether all colors are converted to a gray scale
76
(dump=0, the default), or the current palette is dumped at the
77
beginning of each page of hardcopy output. (The legends keyword
78
applies to all pictures dumped to hardcopy from this graphics
79
window. The dump keyword applies only to the specific hardcopy
80
file defined using the hcp keyword -- use the dump keyword in the
81
hcp_file command to get the same effect in the default hardcopy
84
If both display="" and hcp="", the graphics window will be
87
The style keyword, if present, specifies the name of a Gist style
88
sheet file; the default is "work.gs". The style sheet determines
89
the number and location of coordinate systems, tick and label styles,
90
and the like. Other choices include "axes.gs", "boxed.gs",
91
"work2.gs", and "boxed2.gs".
93
Window(...) returns the current window number.
94
SEE ALSO: plsys, hcp_file, fma, hcp, redraw, palette, animate, plg,
99
Delete the current graphics window, or graphics window N (0-7).
103
Return the number of the current graphics window, or -1 if none.
106
hcp_file( [filename] [, dump=0/1] )
107
Sets the default hardcopy file to FILENAME. If FILENAME ends with
108
".ps", the file will be a PostScript file, otherwise it will be a
109
binary CGM file. By default, the hardcopy file name will be
110
"Aa00.cgm", or "Ab00.cgm" if that exists, or "Ac00.cgm" if both
111
exist, and so on. The default hardcopy file gets hardcopy from all
112
graphics windows which do not have their own specific hardcopy file
113
(see the window command). If the dump keyword is present and non-zero,
114
the current palette will be dumped at the beginning of each frame
115
of the default hardcopy file. With dump=0, the default behavior of
116
converting all colors to a gray scale is restored.
117
SEE ALSO: window, fma, hcp, plg
120
filename = hcp_finish( [n] )
121
Close the current hardcopy file and return the filename.
122
If N is specified, close the hcp file associated with window N
123
and return its name; use hcp_finish(-1) to close the default
125
SEE ALSO: window, fma, hcp, hcp_out, plg
127
hcp_out: **** NOT YET IMPLEMENTED ****
128
hcp_out( [n] [,keep = 0/1] )
129
Finishes the current hardcopy file and sends it to the printer.
130
If N is specified, prints the hcp file associated with window N;
131
use hcp_out(-1) to print the default hardcopy file.
132
Unless the KEEP keyword is supplied and non-zero, the file will
133
be deleted after it is processed by gist and sent to lpr.
134
SEE ALSO: window, fma, hcp, hcp_finish, plg
138
Write the picture in the current graphics window to the Encapsulated
139
PostScript file NAME+".epsi" (i.e.- the suffix .epsi is added to NAME).
140
The eps function requires the ps2epsi utility which comes with the
141
project GNU Ghostscript program. Any hardcopy file associated with
142
the current window is first closed, but the default hardcopy file is
143
unaffected. As a side effect, legends are turned off and color table
144
dumping is turned on for the current window.
145
The environment variable PS2EPSI_FORMAT contains the format for the
146
command to start the ps2epsi program.
147
SEE ALSO: window, fma, hcp, hcp_finish, plg
151
Frame advance the current graphics window. The current picture
152
remains displayed in the associated X window until the next element
154
SEE ALSO: window, hcp, animate, plg
159
hcp(), or hcpon(), or hcpoff()
160
The hcp command sends the picture displayed in the current graphics
161
window to the hardcopy file. (The name of the default hardcopy file
162
can be specified using hcp_file; each individual graphics window may
163
have its own hardcopy file as specified by the window command.)
164
The hcpon command causes every fma (frame advance) command to do
165
and implicit hcp, so that every frame is sent to the hardcopy file.
166
The hcpoff command reverts to the default "demand only" mode.
167
SEE ALSO: window, fma, plg
171
Redraw the X window associated with the current graphics window.
172
SEE ALSO: window, fma, hcp, plg
176
or palette( source_window_number )
177
or palette( red, green, blue, ntsc=1/0 )
178
or palette( red, green, blue, gray )
179
or palette( red, green, blue, query=1 )
180
or palette( red, green, blue, gray, query=1 )
181
Set (or retrieve with query=1) the palette for the current
182
graphics window. The FILENAME is the name of a Gist palette file;
183
the standard palettes are "earth.gp", "stern.gp", "rainbow.gp",
184
"heat.gp", "gray.gp", and "yarg.gp". Use the maxcolors keyword
185
in the pldefault command to put an upper limit on the number of
186
colors which will be read from the palette in FILENAME.
188
In the second form, the palette for the current window is copied
189
from the SOURCE_WINDOW_NUMBER. If the X colormap for the window is
190
private, there will still be two separate X colormaps for the two
191
windows, but they will have the same color values.
193
In the third form, RED, GREEN, and BLUE are 1-D arrays of the same
194
length specifying the palette you wish to install; the values
195
should vary between 0 and 255, and your palette should have no
196
more than 240 colors. If ntsc=0, monochrome devices (such as most
197
laser printers) will use the average brightness to translate your
198
colors into gray; otherwise, the NTSC (television) averaging will
199
be used (.30*RED+.59*GREEN+.11*BLUE). Alternatively, you can specify
202
Ordinarily, the palette is not dumped to a hardcopy file
203
(color hardcopy is still rare and expensive), but you can
204
force the palette to dump using the window() or hcp_file() commands.
206
See the dump= keyword for the hcp_file() and window() commands if you
207
are having trouble getting color in your hardcopy files.
209
SEE ALSO: window, fma, hcp, pldefault, plg
214
Without any arguments, toggle animation mode; with argument 0,
215
turn off animation mode; with argument 1 turn on animation mode.
216
In animation mode, the X window associated with a graphics window
217
is actually an offscreen pixmap which is bit-blitted onscreen
218
when an fma() command is issued. This is confusing unless you are
219
actually trying to make a movie, but results in smoother animation
220
if you are. Generally, you should turn animation on, run your movie,
222
SEE ALSO: window, fma, plg
226
Set the current coordinate system to number N in the current
227
graphics window. If N equals 0, subsequent elements will be
228
plotted in absolute NDC coordinates outside of any coordinate
229
system. The default style sheet "work.gs" defines only a single
230
coordinate system, so the only other choice is N equal 1. You
231
can make up your own style sheet (using a text editor) which
232
defines multiple coordinate systems. You need to do this if
233
you want to display four plots side by side on a single page,
234
for example. The standard style sheets "work2.gs" and "boxed2.gs"
235
define two overlayed coordinate systems with the first labeled
236
to the right of the plot and the second labeled to the left of
237
the plot. When using overlayed coordinate systems, it is your
238
responsibility to ensure that the x-axis limits in the two
239
systems are identical.
240
SEE ALSO: window, limits, plg
242
/*--------------------------------------------------------------------------*/
243
/* Plotting functions (output primitives) */
247
Plot a graph of Y versus X. Y and X must be 1-D arrays of equal
248
length; if X is omitted, it defaults to [1, 2, ..., 1+range(len(Y))].
249
The following keywords are legal (each has a separate help entry):
250
KEYWORDS: legend, hide
251
type, width, color, closed, smooth
252
marks, marker, mspace, mphase
253
rays, arrowl, arroww, rspace, rphase
254
SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj, plfp
255
limits, logxy, ylimits, fma, hcp
258
plm( y, x, boundary=0/1, inhibit=0/1/2 )
259
or plm( y, x, ireg, boundary=0/1, inhibit=0/1/2 )
260
or plm( boundary=0/1, inhibit=0/1/2 )
261
Plot a mesh of Y versus X. Y and X must be 2-D arrays with equal
262
dimensions. If present, IREG must be a 2-D region number array
263
for the mesh, with the same dimensions as X and Y. The values of
264
IREG should be positive region numbers, and zero for zones which do
265
not exist. The first row and column of IREG never correspond to any
266
zone, and should always be zero. The default IREG is 1 everywhere
267
else. If present, the BOUNDARY keyword determines whether the
268
entire mesh is to be plotted (boundary=0, the default), or just the
269
boundary of the selected region (boundary=1). If present, the
270
INHIBIT keyword causes the (X(,j),Y(,j)) lines to not be plotted
271
(inhibit=1), or the (X(i,),Y(i,)) lines to not be plotted (inhibit=2).
272
By default (inhibit=0), mesh lines in both logical directions are
274
The Y, X, and IREG arguments may all be omitted to default to the
275
mesh set by the most recent plmesh call.
276
The following keywords are legal (each has a separate help entry):
277
KEYWORDS: legend, hide
280
SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj, plfp, plmesh
281
limits, logxy, ylimits, fma, hcp
284
plmesh( y, x, ireg, triangle=tri_array )
286
Set the default mesh for subsequent plm, plc, plv, and plf calls.
287
In the second form, deletes the default mesh (until you do this,
288
or switch to a new default mesh, the default mesh arrays persist and
289
take up space in memory). The Y, X, and IREG arrays should all be
290
the same shape; Y and X will be converted to double, and IREG will
291
be converted to int. If IREG is omitted, it defaults to IREG(1,)=
292
IREG(,1)= 0, IREG(2:,2:)=1; that is, region number 1 is the whole
293
mesh. The triangulation array TRI_ARRAY is used by plc; the
294
correspondence between TRI_ARRAY indices and zone indices is the
295
same as for IREG, and its default value is all zero.
296
The IREG or TRI_ARRAY arguments may be supplied without Y and X
297
to change the region numbering or triangulation for a given set of
298
mesh coordinates. However, a default Y and X must already have been
299
defined if you do this.
300
If Y is supplied, X must be supplied, and vice-versa.
301
SEE ALSO: plm, plc, plv, plf, plfp
304
plc( z, y, x, levs=z_values )
305
or plc( z, y, x, ireg, levs=z_values )
306
or plc( z, levs=z_values )
307
Plot contours of Z on the mesh Y versus X. Y, X, and IREG are
308
as for plm. The Z array must have the same shape as Y and X.
309
The function being contoured takes the value Z at each point
310
(X,Y) -- that is, the Z array is presumed to be point-centered.
311
The Y, X, and IREG arguments may all be omitted to default to the
312
mesh set by the most recent plmesh call.
313
The LEVS keyword is a list of the values of Z at which you want
314
contour curves. The default is eight contours spanning the
316
The following keywords are legal (each has a separate help entry):
317
KEYWORDS: legend, hide
318
type, width, color, smooth
319
marks, marker, mspace, mphase
320
smooth, triangle, region
321
SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj, plfp, plmesh
322
limits, logxy, ylimits, fma, hcp
325
plv( vy, vx, y, x, scale=dt )
326
or plv( vy, vx, y, x, ireg, scale=dt )
327
or plv( vy, vx, scale=dt )
328
Plot a vector field (VX,VY) on the mesh (X,Y). Y, X, and IREG are
329
as for plm. The VY and VX arrays must have the same shape as Y and X.
330
The Y, X, and IREG arguments may all be omitted to default to the
331
mesh set by the most recent plmesh call.
332
The SCALE keyword is the conversion factor from the units of
333
(VX,VY) to the units of (X,Y) -- a time interval if (VX,VY) is a velocity
334
and (X,Y) is a position -- which determines the length of the
335
vector "darts" plotted at the (X,Y) points. If omitted, SCALE is
336
chosen so that the longest ray arrows have a length comparable
337
to a "typical" zone size.
338
You can use the scalem keyword in pledit to make adjustments to the
339
SCALE factor computed by default.
340
The following keywords are legal (each has a separate help entry):
341
KEYWORDS: legend, hide
342
type, width, color, smooth
343
marks, marker, mspace, mphase
345
SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj, plfp, plmesh, pledit,
346
limits, logxy, ylimits, fma, hcp
350
or plf( z, y, x, ireg )
352
Plot a filled mesh Y versus X. Y, X, and IREG are as for plm.
353
The Z array must have the same shape as Y and X, or one smaller
354
in both dimensions. If Z is of type char, it is used "as is",
355
otherwise it is linearly scaled to fill the current palette, as
356
with the bytscl function.
357
(See the bytscl function for explanation of top, cmin, cmax.)
358
The mesh is drawn with each zone in the color derived from the Z
359
function and the current palette; thus Z is interpreted as a
361
The Y, X, and IREG arguments may all be omitted to default to the
362
mesh set by the most recent plmesh call.
363
A solid edge can optionally be drawn around each zone by setting
364
the EDGES keyword non-zero. ECOLOR and EWIDTH determine the edge
365
color and width. The mesh is drawn zone by zone in order from
366
IREG(2+imax) to IREG(jmax*imax) (the latter is IREG(imax,jmax)),
367
so you can achieve 3D effects by arranging for this order to
368
coincide with back-to-front order. If Z is nil, the mesh zones
369
are filled with the background color, which you can use to
370
produce 3D wire frames.
371
The following keywords are legal (each has a separate help entry):
372
KEYWORDS: legend, hide
373
region, top, cmin, cmax, edges, ecolor, ewidth
374
SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj, plfp, plmesh,
375
limits, logxy, ylimits, fma, hcp, palette, bytscl, histeq_scale
379
plfc (z, y, x, ireg, contours = 20, colors = None, region = 0,
380
triangle = None, scale = "lin")
381
fills contours of Z on the mesh Y versus X. Y, X, and IREG are
382
as for plm. The Z array must have the same shape as Y and X.
383
The function being contoured takes the value Z at each point
384
(X, Y) -- that is, the Z array is presumed to be point-centered.
386
The CONTOURS keyword can be an integer specifying the number of
387
contours desired, or a list of the values of Z at which you want
388
contour curves. These curves divide the mesh into len(CONTOURS+1)
389
regions, each of which is filled with a solid color. If CONTOURS is
390
None or not given, 20 "nice" equally spaced level values spanning the
391
range of Z are selected.
393
If you specify CONTOURS, you may also specify COLORS, an array of
394
color numbers (Python typecode 'b', integers between 0 and the
395
length of the current palette - 1, normally 199) of length
396
len(CONTOURS)+1. If you do not specify them, equally
397
spaced colors are chosen.
399
If CONTOURS is an integer, SCALE expresses how contour levels
400
are determined. SCALE may be "lin", "log", or "normal"
401
specifying linearly, logarithmically, or normally spaced
402
contours. Note that unlike Yorick's plfc, this routine does
403
not use spann to compute its contours. Neither, apparently,
404
does plc, which uses a third algorithm which matches neither
405
the one we use nor the one spann uses. So if you plot filled
406
contours and then plot contour lines, the contours will in
407
general not coincide exactly.
409
Note that you may use spann to calculate your contour levels
412
The following keywords are legal (each has a separate help entry):
413
KEYWORDS: triangle, region
414
SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj, plfp, plmesh
415
color_bar, spann, contour, limits, logxy, range, fma, hcp
419
Plot a list of filled polygons Y versus X, with colors Z.
420
The N array is a 1D list of lengths (number of corners) of the
421
polygons; the 1D colors array Z has the same length as N. The
422
X and Y arrays have length equal to the sum of all dimensions
424
The Z array must have the same shape as Y and X. If Z is of
425
type char, it is used "as is", otherwise it is linearly scaled
426
to fill the current palette, as with the bytscl function.
427
(See the bytscl function for explanation of top, cmin, cmax.)
428
The following keywords are legal (each has a separate help entry):
429
KEYWORDS: legend, hide, top, cmin, cmax
430
SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj
431
limits, logxy, ylimits, fma, hcp
437
or pli( z, x0, y0, x1, y1 )
438
Plot the image Z as a cell array -- an array of equal rectangular
439
cells colored according to the 2-D array Z. The first dimension
440
of Z is plotted along x, the second dimension is along y.
441
If Z is of type char, it is used "as is", otherwise it is linearly
442
scaled to fill the current palette, as with the bytscl function.
443
(See the bytscl function for explanation of top, cmin, cmax.)
444
If X1 and Y1 are given, they represent the coordinates of the
445
upper right corner of the image. If X0, and Y0 are given, they
446
represent the coordinates of the lower left corner, which is at
447
(0,0) by default. If only the Z array is given, each cell will be
448
a 1x1 unit square, with the lower left corner of the image at (0,0).
449
The following keywords are legal (each has a separate help entry):
450
KEYWORDS: legend, hide, top, cmin, cmax
451
SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj, plfp,
452
limits, logxy, ylimits, fma, hcp, palette, bytscl, histeq_scale
455
pldj( x0, y0, x1, y1 )
456
Plot disjoint lines from (X0,Y0) to (X1,Y1). X0, Y0, X1, and Y1
457
may have any dimensionality, but all must have the same number of
459
The following keywords are legal (each has a separate help entry):
460
KEYWORDS: legend, hide
462
SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj, plfp
463
limits, logxy, ylimits, fma, hcp
466
plt( text, x, y, tosys=0/1 )
467
Plot TEXT (a string) at the point (X,Y). The exact relationship
468
between the point (X,Y) and the TEXT is determined by the
469
justify keyword. TEXT may contain newline ("\n") characters
470
to output multiple lines of text with a single call. The
471
coordinates (X,Y) are NDC coordinates (outside of any coordinate
472
system) unless the tosys keyword is present and non-zero, in
473
which case the TEXT will be placed in the current coordinate
474
system. However, the character height is NEVER affected by the
475
scale of the coordinate system to which the text belongs.
476
Note that the pledit command takes dx and/or dy keywords to
477
adjust the position of existing text elements.
478
The following keywords are legal (each has a separate help entry):
479
KEYWORDS: legend, hide
480
color, font, height, opaque, path, justify
481
SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj, plfp, pledit
482
limits, ylimits, fma, hcp, pltitle
486
Plot TITLE centered above the coordinate system for any of the
487
standard Gist styles. You will need to customize this for other
490
/*--------------------------------------------------------------------------*/
491
/* Plot limits and log/linear scaling */
494
old_limits = limits()
495
or old_limits = limits( xmin [, xmax, ymin, ymax,]
496
[ square=0/1, nice=0/1, restrict=0/1 ] )
497
or limits( old_limits )
499
In the first form, restore all four plot limits to extreme values,
500
and save the previous limits in the tuple old_limits.
502
In the second form, set the plot limits in the current coordinate
503
system to XMIN, XMAX, YMIN, YMAX, which may each be a number to fix
504
the corresponding limit to a specified value, or the string "e"
505
to make the corresponding limit take on the extreme value of the
506
currently displayed data. Arguments may be omitted from the right
507
end only. (But see ``ylimits'' to set limits on the y-axis.)
509
If present, the square keyword determines whether limits marked as
510
extreme values will be adjusted to force the x and y scales to be
511
equal (square=1) or not (square=0, the default). If present, the
512
nice keyword determines whether limits will be adjusted to nice
513
values (nice=1) or not (nice=0, the default). There is a subtlety
514
in the meaning of "extreme value" when one or both of the limits
515
on the OPPOSITE axis have fixed values -- does the "extreme value"
516
of the data include points which will not be plotted because their
517
other coordinate lies outside the fixed limit on the opposite axis
518
(restrict=0, the default), or not (restrict=1)?
520
Limits() always returns a tuple of 4 doubles and an integer;
521
OLD_LIMITS[0:3] are the previous xmin, xmax, ymin, and ymax, and
522
OLD_LIMITS[4] is a set of flags indicating extreme values and the
523
square, nice, restrict, and log flags. This tuple can be saved and
524
passed back to limits() in a future call to restore the limits to a
527
In an X window, the limits may also be adjusted interactively with
528
the mouse. Drag left to zoom in and pan (click left to zoom in on a
529
point without moving it), drag middle to pan, and click (and drag)
530
right to zoom out (and pan). If you click just above or below the
531
plot, these operations will be restricted to the x-axis; if you
532
click just to the left or right, the operations are restricted to
533
the y-axis. A shift-left click, drag, and release will expand the
534
box you dragged over to fill the plot (other popular software zooms
535
with this paradigm). If the rubber band box is not visible with
536
shift-left zooming, try shift-middle or shift-right for alternate
537
XOR masks. Such mouse-set limits are equivalent to a limits command
538
specifying all four limits EXCEPT that the unzoom command can
539
revert to the limits before a series of mouse zooms and pans.
541
The limits you set using the limits or ylimits functions carry over
542
to the next plot -- that is, an fma operation does NOT reset the
543
limits to extreme values.
545
SEE ALSO: plsys, ylimits, logxy, zoom_factor, unzoom, plg
549
Set the y-axis plot limits in the current coordinate system to
550
YMIN, YMAX, which may each be a number to fix the corresponding
551
limit to a specified value, or the string "e" to make the
552
corresponding limit take on the extreme value of the currently
553
displayed data. Arguments may be omitted only from the right. Use
554
limits( xmin, xmax ) to accomplish the same function for the x-axis
555
plot limits. Note that the corresponding Yorick function for
556
ylimits is ``range'' - since this word is a Python built-in function,
557
I've changed the name to avoid the collision.
558
SEE ALSO: plsys, limits, logxy, plg
561
logxy( xflag, yflag )
562
Sets the linear/log axis scaling flags for the current coordinate
563
system. XFLAG and YFLAG may be 0 to select linear scaling, or 1 to
564
select log scaling. YFLAG may be omitted (but not XFLAG).
565
SEE ALSO: plsys, limits, ylimits, plg, gridxy
569
or gridxy( xflag, yflag )
570
Turns on or off grid lines according to FLAG. In the first form, both
571
the x and y axes are affected. In the second form, XFLAG and YFLAG
572
may differ to have different grid options for the two axes. In either
573
case, a FLAG value of 0 means no grid lines (the default), a value of
574
1 means grid lines at all major ticks (the level of ticks which get
575
grid lines can be set in the style sheet), and a FLAG value of 2 means
576
that the coordinate origin only will get a grid line. In styles with
577
multiple coordinate systems, only the current coordinate system is
578
affected. The keywords can be used to affect the style of the grid
581
You can also turn the ticks off entirely. (You might want to do this
582
to plot your own custom set of tick marks when the automatic tick
583
generating machinery will never give the ticks you want. For example
584
a latitude axis in degrees might reasonably be labeled "0, 30, 60,
585
90", but the automatic machinery considers 3 an "ugly" number - only
586
1, 2, and 5 are "pretty" - and cannot make the required scale. In
587
this case, you can turn off the automatic ticks and labels, and use
588
plsys, pldj, and plt to generate your own.)
589
To fiddle with the tick flags in this general manner, set the
590
0x200 bit of FLAG (or XFLAG or YFLAG), and "or-in" the 0x1ff bits
591
however you wish. The meaning of the various flags is described
592
in the ``work.gs'' Gist style sheet. Additionally, you can use the
593
0x400 bit to turn on or off the frame drawn around the viewport.
594
Here are some examples:
595
gridxy(0x233) work.gs default setting
596
gridxy(0, 0x200) like work.gs, but no y-axis ticks or labels
597
gridxy(0, 0x231) like work.gs, but no y-axis ticks on right
598
gridxy(0x62b) boxed.gs default setting
600
KEYWORDS: color, type, width
601
SEE ALSO: window, plsys, limits, ylimits, logxy
604
zoom_factor( factor )
605
Set the zoom factor for mouse-click zoom in and zoom out operations.
606
The default FACTOR is 1.5; FACTOR should always be greater than 1.0.
607
SEE ALSO: limits, ylimits, unzoom, plg
611
Restore limits to their values before zoom and pan operations
612
performed interactively using the mouse.
613
Use old_limits = limits()
616
to save and restore plot limits generally.
617
SEE ALSO: limits, ylimits, zoom_factor, plg
619
/*--------------------------------------------------------------------------*/
620
/* Keywords for plotting functions */
623
legend = "text destined for the legend"
624
Set the legend for a plot. There are no default legends in Python
625
Gist. Legends are never plotted to the X window; use the plq
626
command to see them interactively. Legends will appear in hardcopy
627
output unless they have been explicitly turned off.
628
PLOTTING COMMANDS: plg, plm, plc, plv, plf, pli, plt, pldj
633
Set the visibility of a plotted element. The default is hide=0,
634
which means that the element will be visible. Use hide=1 to remove
635
the element from the plot (but not from the display list).
636
PLOTTING COMMANDS: plg, plm, plc, plv, plf, pli, plt, pldj
640
type = <line type value>
641
Select line type. Valid values are the strings "solid", "dash",
642
"dot", "dashdot", "dashdotdot", and "none". The "none" value causes
643
the line to be plotted as a polymarker. The type value may also be
644
a number; 0 is "none", 1 is "solid", 2 is "dash", 3 is "dot", 4 is
645
"dashdot", and 5 is "dashdotdot".
646
PLOTTING COMMANDS: plg, plm, plc, pldj
647
SEE ALSO: width, color, marks, marker, rays, closed, smooth
650
width = <floating point value>
651
Select line width. Valid values are positive floating point numbers
652
giving the line thickness relative to the default line width of one
653
half point, which is width = 1.0.
654
PLOTTING COMMANDS: plg, plm, plc, pldj, plv (only if hollow=1)
655
SEE ALSO: type, color, marks, marker, rays, closed, smooth
658
color = <color value>
659
Select line or text color. Valid values are the strings "bg", "fg",
660
"black", "white", "red", "green", "blue", "cyan", "magenta", "yellow",
661
or a 0-origin index into the current palette. The default is "fg".
662
Negative numbers may be used instead of the strings: -1 is bg
663
(background), -2 is fg (foreground), -3 is black, -4 is white,
664
-5 is red, -6 is green, -7 is blue, -8 is cyan, -9 is magenta, and
666
PLOTTING COMMANDS: plg, plm, plc, pldj, plt
667
SEE ALSO: type, width, marks, marker, mcolor, rays, closed, smooth
671
Select unadorned lines (marks=0), or lines with occasional markers
672
(marks=1). Ignored if type is "none" (indicating polymarkers instead
673
of occasional markers). The spacing and phase of the occasional
674
markers can be altered using the mspace and mphase keywords; the
675
character used to make the mark can be altered using the marker
677
PLOTTING COMMANDS: plg, plc
678
SEE ALSO: type, width, color, marker, rays, mspace, mphase, msize, mcolor
681
marker = <character or integer value>
682
Select the character used for occasional markers along a polyline,
683
or for the polymarker if type = "none". The special values
684
'\1', '\2', '\3', '\4', and '\5' stand for point, plus, asterisk,
685
circle, and cross, which are prettier than text characters on output
686
to some devices. The default marker is the next available capital
687
letter, 'A', 'B', ..., 'Z'.
688
PLOTTING COMMANDS: plg, plc
689
SEE ALSO: type, width, color, marks, rays, mspace, mphase, msize, mcolor
695
mspace = <float value>
696
or mphase = <float value>
697
or msize = <float value>
698
or mcolor = <color value>
699
Select the spacing, phase, and size of occasional markers placed
700
along polylines. The msize also selects polymarker size if type
701
is "none". The spacing and phase are in NDC units (0.0013 NDC
702
equals 1.0 point); the default mspace is 0.16, and the default
703
mphase is 0.14, but mphase is automatically incremented for
704
successive curves on a single plot. The msize is in relative
705
units, with the default msize of 1.0 representing 10 points.
706
The mcolor keyword is the same as the color keyword, but controls
707
the marker color instead of the line color. Setting the color
708
automatically sets the mcolor to the same value, so you only
709
need to use mcolor if you want the markers for a curve to be a
710
different color than the curve itself.
711
PLOTTING COMMANDS: plg, plc
712
SEE ALSO: type, width, color, marks, marker, rays
716
Select unadorned lines (rays=0), or lines with occasional ray
717
arrows (rays=1). Ignored if type is "none". The spacing and phase
718
of the occasional arrows can be altered using the rspace and rphase
719
keywords; the shape of the arrowhead can be modified using the
720
arroww and arrowl keywords.
721
PLOTTING COMMANDS: plg, plc
722
SEE ALSO: type, width, color, marker, marks, rspace, rphase
729
rspace = <float value>
730
or rphase = <float value>
731
or arroww = <float value>
732
or arrowl = <float value>
733
Select the spacing, phase, and size of occasional ray arrows
734
placed along polylines. The spacing and phase are in NDC units
735
(0.0013 NDC equals 1.0 point); the default rspace is 0.13, and
736
the default rphase is 0.11375, but rphase is automatically
737
incremented for successive curves on a single plot.
738
The arrowhead width, arroww, and arrowhead length, arrowl are
739
in relative units, defaulting to 1.0, which translates to an
740
arrowhead 10 points long and 4 points in half-width.
741
PLOTTING COMMANDS: plg
742
SEE ALSO: type, width, color, marks, marker, rays
747
or smooth = 0/1/2/3/4
748
Select closed curves (closed=1) or default open curves (closed=0),
749
or Bezier smoothing (smooth>0) or default piecewise linear curves
750
(smooth=0). The value of smooth can be 1, 2, 3, or 4 to get
751
successively more smoothing. Only the Bezier control points are
752
plotted to an X window; the actual Bezier curves will show up in
753
PostScript hardcopy files. Closed curves join correctly, which
754
becomes more noticeable for wide lines; non-solid closed curves
755
may look bad because the dashing pattern may be incommensurate
756
with the length of the curve.
757
PLOTTING COMMANDS: plg, plc (smooth only)
758
SEE ALSO: type, width, color, marks, marker, rays
766
height = <float value>
769
justify = (see text description)
770
Select text properties. The font can be any of the strings
771
"courier", "times", "helvetica" (the default), "symbol", or
772
"schoolbook". Append "B" for boldface and "I" for italic, so
773
"courierB" is boldface Courier, "timesI" is Times italic, and
774
"helveticaBI" is bold italic (oblique) Helvetica. Your X server
775
should have the Adobe fonts (available free from the MIT X
776
distribution tapes) for all these fonts, preferably at both 75
777
and 100 dpi. Occasionally, a PostScript printer will not be
778
equipped for some fonts; often New Century Schoolbook is missing.
779
The font keyword may also be an integer: 0 is Courier, 4 is Times,
780
8 is Helvetica, 12 is Symbol, 16 is New Century Schoolbook, and
781
you add 1 to get boldface and/or 2 to get italic (or oblique).
783
The height is the font size in points; 14.0 is the default.
784
X windows only has 8, 10, 12, 14, 18, and 24 point fonts, so
785
don't stray from these sizes if you want what you see on the
786
screen to be a reasonably close match to what will be printed.
788
By default, opaque=0 and text is transparent. Set opaque=1 to
789
white-out a box before drawing the text. The default path
790
(path=0) is left-to-right text; set path=1 for top-to-bottom text.
792
The default text justification, justify="NN" is normal is both
793
the horizontal and vertical directions. Other possibilities
794
are "L", "C", or "R" for the first character, meaning left,
795
center, and right horizontal justification, and "T", "C", "H",
796
"A", or "B", meaning top, capline, half, baseline, and bottom
797
vertical justification. The normal justification "NN" is equivalent
798
to "LA" if path=0, and to "CT" if path=1. Common values are
799
"LA", "CA", and "RA" for garden variety left, center, and right
800
justified text, with the y coordinate at the baseline of the
801
last line in the string presented to plt. The characters labeling
802
the right axis of a plot are "RH", so that the y value of the
803
text will match the y value of the corresponding tick. Similarly,
804
the characters labeling the bottom axis of a plot are "CT".
805
The justification may also be a number, horizontal+vertical,
806
where horizontal is 0 for "N", 1 for "L", 2 for "C", or 3 for "R",
807
and vertical is 0 for "N", 4 for "T", 8 for "C", 12 for "H",
808
16 for "A", or 20 for "B".
810
PLOTTING COMMANDS: plt
814
region = <region number>
815
Select the part of mesh to consider. The region should match one
816
of the numbers in the IREG array. Putting region=0 (the default)
817
means to plot the entire mesh, that is, everything EXCEPT region
818
zero (non-existent zones). Any other number means to plot only
819
the specified region number; region=3 would plot region 3 only.
820
PLOTTING COMMANDS: plm, plc, plv, plf
823
triangle = <triangulation array>
824
Set the triangulation array for a contour plot. The triangulation
825
array must be the same shape as the IREG (region number) array, and
826
the correspondence between mesh zones and indices is the same as
827
for IREG. The triangulation array is used to resolve the ambiguity
828
in saddle zones, in which the function Z being contoured has two
829
diagonally opposite corners high, and the other two corners low.
830
The triangulation array element for a zone is 0 if the algorithm is
831
to choose a triangulation, based on the curvature of the first
832
contour to enter the zone. If zone (i,j) is to be triangulated
833
from point (i-1,j-1) to point (i,j), then TRIANGLE(i,j)=1,
834
while if it is to be triangulated from (i-1,j) to (i,j-1), then
835
TRIANGLE(i,j)=-1. Contours will never cross this "triangulation
837
You should rarely need to fiddle with the triangulation array;
838
it is a hedge for dealing with pathological cases.
839
PLOTTING COMMANDS: plc
844
aspect = <float value>
845
Set the appearance of the "darts" of a vector field plot. The
846
default darts, hollow=0, are filled; use hollow=1 to get just the
847
dart outlines. The default is aspect=0.125; aspect is the ratio
848
of the half-width to the length of the darts. Use the color
849
keyword to control the color of the darts.
850
PLOTTING COMMANDS: plv
857
ecolor = <color value>
858
ewidth = <float value>
859
set the appearance of the zone edges in a filled mesh plot (plf).
860
By default, edges=0, and the zone edges are not plotted. If
861
edges=1, a solid line is drawn around each zone after it is
862
filled; the edge color and width are given by ecolor and ewidth,
863
which are "fg" and 1.0 by default.
864
PLOTTING COMMANDS: plf
865
SEE ALSO: color, width
867
/*--------------------------------------------------------------------------*/
868
/* Inquiry and editing functions */
873
or plq( n_element, n_contour )
874
or legend_list = plq() **** RETURN VALUE NOT YET IMPLEMENTED ****
875
or properties = plq(n_element, n_contour)
876
Called as a subroutine, prints the list of legends for the current
877
coordinate system (with an "(H)" to mark hidden elements), or prints
878
a list of current properties of element N_ELEMENT (such as line type,
879
width, font, etc.), or of contour number N_CONTOUR of element number
880
N_ELEMENT (which must be contours generated using the plc command).
881
Elements and contours are both numbered starting with one; hidden
882
elements or contours are included in this numbering.
884
The plq function always operates on the current coordinate system
885
in the current graphics window; use window and plsys to change these.
886
SEE ALSO: window, plsys, pledit, pldefault, plg
889
pledit( key1=value1, key2=value2, ... )
890
or pledit( n_element, key1=value1, key2=value2, ... )
891
or pledit( n_element, n_contour, key1=value1, key2=value2, ... )
892
Changes some property of element number N_ELEMENT (and contour
893
number N_CONTOUR of that element). If N_ELEMENT and N_CONTOUR are
894
omitted, the default is the most recently added element, or the
895
element specified in the most recent plq query command.
897
The keywords can be any of the keywords that apply to the current
899
plg: color, type, width,
900
marks, mcolor, marker, msize, mspace, mphase,
901
rays, rspace, rphase, arrowl, arroww,
903
pldj: color, type, width
904
plt: color, font, height, path, justify, opaque
905
plm: region, boundary, inhibit, color, type, width
907
plv: region, color, hollow, width, aspect, scale
908
plc: region, color, type, width,
909
marks, mcolor, marker, msize, mspace, mphase
911
(For contours, if you aren't talking about a particular N_CONTOUR,
912
any changes will affect ALL the contours.)
914
A plv (vector field) element can also take the scalem
915
keyword to multiply all vector lengths by a specified factor.
917
A plt (text) element can also take the dx and/or dy
918
keywords to adjust the text position by (dx,dy).
920
SEE ALSO: window, plsys, plq, pldefault, plg
923
plwf (z, y = None, x = None, fill = None, shade = 0, edges = 1,
924
ecolor = None, ewidth = None, cull = None, scale = None, cmax = None,
926
plots a 3-D wire frame of the given Z array, which must have the
927
same dimensions as the mesh (X, Y). If X and Y are not given, they
928
default to the first and second indices of Z, respectively.
929
The drawing order of the zones is determined by a simple "painter's
930
algorithm", which works fairly well if the mesh is reasonably near
931
rectilinear, but can fail even then if the viewpoint is chosen to
932
produce extreme fisheye perspective effects. Look at the resulting
933
plot carefully to be sure the algorithm has correctly rendered the
936
KEYWORDS: FILL -- optional colors to use (default is to make zones
937
have background color), same dimension options as
938
for z argument to plf function
939
SHADE -- set non-zero to compute shading from current
941
EDGES -- default is 1 (draw edges), but if you provide fill
942
colors, you may set to 0 to supress the edges
943
ECOLOR, EWIDTH -- color and width of edges
944
CULL -- default is 1 (cull back surfaces), but if you want
945
to see the "underside" of the model, set to 0
946
SCALE -- by default, Z is scaled to "reasonable" maximum
947
and minimum values related to the scale of (X,Y).
948
This keyword alters the default scaling factor, in
949
the sense that scale=2.0 will produce twice the
950
Z-relief of the default scale=1.0.
951
CMAX -- the AMBIENT keyword in light3 can be used to
952
control how dark the darkest surface is; use this
953
to control how light the lightest surface is
954
the lightwf routine can change this parameter
957
SEE ALSO: lightwf, plm, plf, orient3, light3, fma3, window3
960
pldefault( key1=value1, key2=value2, ... )
961
Set default values for the various properties of graphical elements.
963
The keywords can be most of the keywords that can be passed to the
965
plg: color, type, width,
966
marks, mcolor, msize, mspace, mphase,
967
rays, rspace, rphase, arrowl, arroww
968
pldj: color, type, width
969
plt: color, font, height, path, justify, opaque
970
plm: color, type, width
971
plv: color, hollow, width, aspect
972
plc: color, type, width,
973
marks, mcolor, marker, msize, mspace, mphase
974
plf: edges, ecolor, ewidth
976
The initial default values are:
977
color="fg", type="solid", width=1.0 (1/2 point),
978
marks=1, mcolor="fg", msize=1.0 (10 points),
979
mspace=0.16, mphase=0.14,
980
rays=0, arrowl=1.0 (10 points), arroww=1.0 (4 points),
981
rspace=0.13, rphase=0.11375,
982
font="helvetica", height=12.0, path=0, justify="NN", opaque=0,
983
hollow= 0, aspect=0.125,
984
edges=0, ecolor="fg", ewidth=1.0 (1/2 point)
986
Additional default keywords are:
987
dpi, style, legends (see window command)
988
palette (to set default filename as in palette command)
989
maxcolors (default 200)
991
SEE ALSO: window, plsys, plq, pledit, plg
993
/*--------------------------------------------------------------------------*/
998
or bytscl(z, top=max_byte, cmin=lower_cutoff, cmax=upper_cutoff)
999
Returns a char array of the same shape as Z, with values linearly
1000
scaled to the range 0 to one less than the current palette size.
1001
If MAX_BYTE is specified, the scaled values will run from 0 to
1003
If LOWER_CUTOFF and/or UPPER_CUTOFF are specified, Z values outside
1004
this range are mapped to the cutoff value; otherwise the linear
1005
scaling maps the extreme values of Z to 0 and MAX_BYTE.
1006
SEE ALSO: plf, pli, histeq_scale
1009
[nc, yc, xc] = contour (level, z, y, x [, ireg] [, triangle = <vals>]
1011
returns the points on the contour curve that would have been
1012
plotted by plc. Z, Y, X, and IREG are as for plc, and the
1013
triangle= and region= keywords are accepted and have the same
1014
meaning as for plc. Unlike plc, the triangle array is an output
1015
as well as an input to contour; if supplied it may be modified
1016
to reflect any triangulations which were performed by contour.
1019
LEVEL is a scalar z value to return the points at that contour
1020
level. All such points lie on edges of the mesh. If a contour
1021
curve closes, the final point is the same as the initial point
1022
(i.e.- that point is included twice in the returned list).
1025
LEVEL is a pair of z values [z0,z1] to return the points of
1026
a set of polygons which outline the regions between the two
1027
contour levels. These will include points on the mesh boundary
1028
which lie between the levels, in addition to the edge points
1029
for both levels. The polygons are closed, simply connected,
1030
and will not contain more than about 4000 points (larger polygons
1031
are split into pieces with a few points repeated where the pieces
1034
YC and XC are the output points on the curve(s), or None if there
1035
are no points. The return value NC is a list of the lengths of
1036
the polygons/polylines returned in (XC,YC), or None if there are
1037
none. len(XC) == len(YC) == sum(NC). For the level pair
1038
case, YC, XC, and NC are ready to be used as inputs to plfp.
1040
KEYWORDS: triangle, region
1045
or mesh_loc(y0, x0, y, x)
1046
or mesh_loc(y0, x0, y, x, ireg)
1047
Returns the zone index (=i+imax*(j-1)) of the zone of the mesh
1048
(X,Y) (with optional region number array IREG) containing the
1049
point (X0,Y0). If (X0,Y0) lies outside the mesh, returns 0.
1050
Thus, eg- ireg(mesh_loc(x0, y0, y, x, ireg)) is the region number of
1051
the region containing (x0,y0). If no mesh specified, uses default.
1052
X0 and Y0 may be arrays as long as they are conformable.
1053
SEE ALSO: plmesh, moush, mouse
1056
result = mouse(system, style, prompt)
1057
Displays a PROMPT, then waits for a mouse button to be pressed,
1058
then released. Returns tuple of length eleven:
1059
result= [x_pressed, y_pressed, x_released, y_released,
1060
xndc_pressed, yndc_pressed, xndc_released, yndc_released,
1061
system, button, modifiers]
1063
If SYSTEM>=0, the first four coordinate values will be relative to
1064
that coordinate system.
1065
For SYSTEM<0, the first four coordinate values will be relative to
1066
the coordinate system under the mouse when the button was pressed.
1067
The second four coordinates are always normalized device coordinates,
1068
which start at (0,0) in the lower left corner of the 8.5x11 sheet of
1069
paper the picture will be printed on, with 0.0013 NDC unit being
1070
1/72.27 inch (1.0 point). Look in the style sheet for the location
1071
of the viewport in NDC coordinates (see the style keyword).
1073
If STYLE is 0, there will be no visual cues that the mouse
1074
command has been called; this is intended for a simple click.
1075
If STYLE is 1, a rubber band box will be drawn; if STYLE is 2,
1076
a rubber band line will be drawn. These disappear when the
1079
Clicking a second button before releasing the first cancels the
1080
mouse function, which will then return nil.
1081
Ordinary text input also cancels the mouse function, which again
1084
The left button reverses forground for background (by XOR) in
1085
order to draw the rubber band (if any). The middle and right
1086
buttons use other masks, in case the rubber band is not visible
1087
with the left button.
1089
result[8] is the coordinate system in which the first four
1090
coordinates are to be interpreted.
1091
result[9] is the button which was pressed, 1 for left, 2
1092
for middle, and 3 for right (4 and 5 are also possible).
1093
result[10] is a mask representing the modifier keys which
1094
were pressed during the operation: 1 for shift, 2 for shift lock,
1095
4 for control, 8 for mod1 (alt or meta), 16 for mod2, 32 for mod3,
1096
64 for mod4, and 128 for mod5.
1104
Returns the 1-origin zone index for the point clicked in
1105
for the default mesh, or for the mesh (X,Y) (region array IREG).
1108
pause( milliseconds )
1109
Pause for the specified number of milliseconds of wall clock
1110
time, or until input arrives from the keyboard.
1111
This is intended for use in creating animated sequences.
1113
/*--------------------------------------------------------------------------*/
1115
histeq_scale: **** NOT YET IMPLEMENTED ****
1116
histeq_scale(z, top=top_value, cmin=cmin, cmax=cmax)
1117
Returns a byte-scaled version of the array Z having the property
1118
that each byte occurs with equal frequency (Z is histogram
1119
equalized). The result bytes range from 0 to TOP_VALUE, which
1120
defaults to one less than the size of the current palette (or
1121
255 if no pli, plf, or palette command has yet been issued).
1123
If non-nil CMIN and/or CMAX is supplied, values of Z beyond these
1124
cutoffs are not included in the frequency counts.
1126
SEE ALSO: bytscl, plf, pli
1129
spann (zmin, zmax, n = 8, fudge = 0, force = 0)
1130
return no more than N equally spaced "nice" numbers between
1132
Note that in general spann may not supply the number of
1133
values that you asked for. To force it to do so, set
1134
keyword FORCE to nonzero.
1135
SEE ALSO: span, spanl, plc, plfc
1139
Sets the CMAX parameter interactively, assuming the current
1140
3D display list contains the result of a previous plwf call.
1141
This changes the color of the brightest surface in the picture.
1142
The darkest surface color can be controlled using the AMBIENT
1145
SEE ALSO: plwf, light3
1148
orient3 ( [phi = val1, theta = val2] )
1149
Set the orientation of the object to (PHI, THETA). Orientations
1150
are a subset of the possible rotation matrices in which the z axis
1151
of the object appears vertical on the screen (that is, the object
1152
z axis projects onto the viewer y axis). The THETA angle is the
1153
angle from the viewer y axis to the object z axis, positive if
1154
the object z axis is tilted towards you (toward viewer +z). PHI is
1155
zero when the object x axis coincides with the viewer x axis. If
1156
neither PHI nor THETA is specified, PHI defaults to - pi / 4 and
1157
THETA defaults to pi / 6. If only PHI is specified, THETA remains
1158
unchanged, unless the current THETA is near pi / 2, in which case
1159
THETA returns to pi / 6, or unless the current orientation does
1160
not have a vertical z axis, in which case THETA returns to its
1161
default. If only THETA is specified, PHI retains its current value.
1162
Unlike rot3, orient3 is not a cumulative operation.
1164
SEE ALSO: rot3, mov3, aim3, save3, restore3, light3
1167
light3 (ambient=a_level,
1172
Sets lighting properties for 3D shading effects.
1173
A surface will be shaded according to its to its orientation
1174
relative to the viewing direction.
1176
The ambient level A_LEVEL is a light level (arbitrary units)
1177
that is added to every surface independent of its orientation.
1179
The diffuse level D_LEVEL is a light level which is proportional
1180
to cos(theta), where theta is the angle between the surface
1181
normal and the viewing direction, so that surfaces directly
1182
facing the viewer are bright, while surfaces viewed edge on are
1183
unlit (and surfaces facing away, if drawn, are shaded as if they
1186
The specular level S_LEVEL is a light level proportional to a high
1187
power spower=N of 1+cos(alpha), where alpha is the angle between
1188
the specular reflection angle and the viewing direction. The light
1189
source for the calculation of alpha lies in the direction XYZ (a
1190
3 element vector) in the viewer's coordinate system at infinite
1191
distance. You can have ns light sources by making S_LEVEL, N, and
1192
XYZ (or any combination) be vectors of length ns (3-by-ns in the
1193
case of XYZ). (See source code for specular_hook function
1194
definition if powers of 1+cos(alpha) aren't good enough for you.)
1196
With no arguments, return to the default lighting.
1199
light3 ( diffuse=.1, specular=1., sdir=[0,0,-1])
1200
(dramatic "tail lighting" effect)
1201
light3 ( diffuse=.5, specular=1., sdir=[1,.5,1])
1202
(classic "over your right shoulder" lighting)
1203
light3 ( ambient=.1,diffuse=.1,specular=1.,
1204
sdir=[[0,0,-1],[1,.5,1]],spower=[4,2])
1205
(two light sources combining previous effects)
1207
SEE ALSO: rot3, save3, restore3
1210
window3 ( [n,] , dump = 0, hcp = None)
1211
initialize style="nobox.gs" window for 3D graphics. dump = 1
1212
to dump the palette to the hardcopy file (if any), for color
1213
plots; use hcp to specify the filename for hardcopy.
1216
rot3 (xa = 0., ya = 0., za = 0.)
1217
rotate the current 3D plot by XA about viewer's x-axis,
1218
YA about viewer's y-axis, and ZA about viewer's z-axis.
1220
SEE ALSO: orient3, mov3, aim3, setz3, undo3, save3, restore3, light3
1224
Save the current 3D viewing transformation and lighting.
1225
Actually, this doesn't save anything; it returns a copy
1226
of the current 3D viewing transformation and lighting, so
1227
that the user can put it aside somewhere.
1229
SEE ALSO: restore3, rot3, mov3, aim3, light3
1233
Restore a previously saved 3D viewing transformation and lighting.
1234
If view is missing, rotate object to viewer's coordinate system.
1236
SEE ALSO: restore3, rot3, mov3, aim3, light3
1239
aim3 ( xa = 0., ya = 0., za = 0. )
1240
move the current 3D plot to put the point (XA, YA, ZA) in object
1241
coordinates at the point (0, 0, 0) -- the aim point -- in the
1242
viewer's coordinates. If any of the XA, YA, or ZA is None or
1243
missing, it defaults to zero.
1245
SEE ALSO: mov3, rot3, orient3, setz3, undo3, save3, restore3, light3
1248
mov3 ( xa = 0., ya = 0., za = 0. )
1249
move the current 3D plot by XA along the viewer's x axis,
1250
YA along the viewer's y axis, and ZA along the viewer's z axis.
1252
SEE ALSO: rot3, orient3, setz3, undo3, save3, restore3, light3
1256
Set the camera position to z = ZC (x = y = 0) in the viewer's coordinate
1257
system. If zc is None, set the camera to infinity (default).
1259
SEE ALSO: rot3, orient3, undo3, save3, restore3, light3
1263
Undo the effects of the last N (default 1) rot3, orient3, mov3, aim3,
1264
setz3, or light3 commands.
1267
get3_light (xyz [, nxyz])
1268
return 3D lighting for polygons with vertices XYZ. If NXYZ is
1269
specified, XYZ should be sum(nxyz)-by-3, with NXYZ being the
1270
list of numbers of vertices for each polygon (as for the plfp
1271
function). If NXYZ is not specified, XYZ should be a quadrilateral
1272
mesh, ni-by-nj-by-3 (as for the plf function). In the first case,
1273
the return value is len (NXYZ) long; in the second case, the
1274
return value is (ni-1)-by-(nj-1).
1276
The parameters of the lighting calculation are set by the
1279
SEE ALSO: light3, set3_object, get3_normal, get3_centroid
1282
set3_object (fnc, arg)
1283
or set3_object (fnc, [arg1, arg2,...])
1284
set up to trigger a call to draw3, adding a call to the
1285
3D display list of the form:
1287
DRAWING_FUNCTION ( [ARG1, ARG2, ...]))
1289
When draw3 calls DRAWING_FUNCTION, the external variable _draw3
1290
will be non-zero, so DRAWING_FUNCTION can be written like this:
1292
def drawing_function(arg) :
1298
...<calls to get3_xy, sort3d, get3_light, etc.>...
1299
...<calls to graphics functions plfp, plf, etc.>...
1303
...<do orientation and lighting independent calcs>...
1304
set3_object (drawing_function, [arg1,arg2,...])
1306
SEE ALSO: get3_xy, get3_light, sort3d
1310
given Z and NPOLYS, with len(Z)==sum(npolys), return
1311
a 2-element list [LIST, VLIST] such that Z[VLIST] and NPOLYS[LIST] are
1312
sorted from smallest average Z to largest average Z, where
1313
the averages are taken over the clusters of length NPOLYS.
1314
Within each cluster (polygon), the cyclic order of Z[VLIST]
1315
remains unchanged, but the absolute order may change.
1317
This sorting order produces correct or nearly correct order
1318
for a plfp command to make a plot involving hidden or partially
1319
hidden surfaces in three dimensions. It works best when the
1320
polys form a set of disjoint closed, convex surfaces, and when
1321
the surface normal changes only very little between neighboring
1322
polys. (If the latter condition holds, then even if sort3d
1323
mis-orders two neighboring polys, their colors will be very
1324
nearly the same, and the mistake won't be noticeable.) A truly
1325
correct 3D sorting routine is impossible, since there may be no
1326
rendering order which produces correct surface hiding (some polys
1327
may need to be split into pieces in order to do that). There
1328
are more nearly correct algorithms than this, but they are much
1330
SEE ALSO: get3_xy, plfp
1333
def draw3 (called_as_idler = 0, lims = None)
1334
Draw the current 3d display list.
1335
(Ordinarily triggered automatically when the drawing changes.)
1338
get3_normal (xyz [, nxyz])
1339
return 3D normals for polygons with vertices XYZ. If NXYZ is
1340
specified, XYZ should be sum(nxyz)-by-3, with NXYZ being the
1341
list of numbers of vertices for each polygon (as for the plfp
1342
function). If NXYZ is not specified, XYZ should be a quadrilateral
1343
mesh, ni-by-nj-by-3 (as for the plf function). In the first case,
1344
the return value is len(NXYZ)-by-3; in the second case, the
1345
return value is (ni-1)-by-(nj-1)-by-3.
1347
The normals are constructed from the cross product of the lines
1348
joining the midpoints of two edges which as nearly quarter the
1349
polygon as possible (the medians for a quadrilateral). No check
1350
is made that these not be parallel; the returned "normal" is
1351
[0,0,0] in that case. Also, if the polygon vertices are not
1352
coplanar, the "normal" has no precisely definable meaning.
1354
SEE ALSO: get3_centroid, get3_light
1357
get3_centroid (xyz [, nxyz])
1358
return 3D centroids for polygons with vertices XYZ. If NXYZ is
1359
specified, XYZ should be sum(nxyz)-by-3, with NXYZ being the
1360
list of numbers of vertices for each polygon (as for the plfp
1361
function). If NXYZ is not specified, XYZ should be a quadrilateral
1362
mesh, ni-by-nj-by-3 (as for the plf function). In the first case,
1363
the return value is len(NXYZ) in length; in the second case, the
1364
return value is (ni-1)-by-(nj-1)-by-3.
1366
The centroids are constructed as the mean value of all vertices
1369
SEE ALSO: get3_normal, get3_light
1372
get3_xy (xyz [, flg])
1373
Given anything-by-3 coordinates XYZ, return X and Y in viewer's
1374
coordinate system (set by rot3, mov3, orient3, etc.). If the
1375
second argument is present and non-zero, also return Z (for use
1376
in sort3d or get3_light, for example). If the camera position
1377
has been set to a finite distance with setz3, the returned
1378
coordinates will be tangents of angles for a perspective
1379
drawing (and Z will be scaled by 1/zc).
1380
Unlike the Yorick version, this function returns a 3-by-anything
1381
array of coordinates.
1382
Actually, what it returns is a 3-by-anything python array, whose
1383
0th element is the x array, whose 1th element is the y array, and
1384
whose 2th element is the z array if asked for.
1385
I believe that x, y, and z can be either 1d or 2d, so this
1386
routine is written in two cases.
1389
gnomon ( [onoff] [, chr = ["X", "Y", "Z"]])
1390
Toggle the gnomon display. If on is present and non-zero,
1391
turn on the gnomon. If zero, turn it off.
1393
The gnomon shows the X, Y, and Z axis directions in the
1394
object coordinate system. The directions are labeled.
1395
The gnomon is always infinitely far behind the object
1396
(away from the camera).
1398
There is a mirror-through-the-screen-plane ambiguity in the
1399
display which is resolved in two ways: (1) the (X, Y, Z)
1400
coordinate system is right-handed, and (2) If the tip of an
1401
axis projects into the screen, its label is drawn in opposite
1402
polarity to the other text in the screen.
1404
CHR specifies the axis labels.
1407
spin3 (nframes = 30, axis = array ([-1, 1, 0], Float), tlimit = 60.,
1408
dtmin = 0.0, bracket_time = array ([2., 2.], Float), lims = None,
1409
timing = 0, angle = 2. * pi)
1410
Spin the current 3D display list about AXIS over NFRAMES. Keywords
1411
TLIMIT the total time allowed for the movie in seconds (default 60),
1412
DTMIN the minimum allowed interframe time in seconds (default 0.0),
1413
BRACKET_TIME (as for movie function in movie.py), TIMING = 1 if
1414
you want timing measured and printed out, 0 if not.
1419
color_bar (minz, maxz, split = 0)
1420
color_bar (minz, maxz) plots a color bar to the right of the plot square
1421
labelled by the z values from minz to maxz.
1424
color_bar (z (min, min), z (max, max))
1427
plf (z, y, x, cmin = MINZ, cmax = MAXZ)
1428
color_bar (MINZ, MAXZ)
1432
The SPLIT keyword should be nonzero for a split palette.
1435
movie (draw_frame, time_limit = 120., min_interframe = 0.0,
1436
bracket_time = array ([2., 2.], Float ), lims = None, timing = 0)
1437
runs a movie based on the given DRAW_FRAME function. The movie
1438
stops after a total elapsed time of TIME_LIMIT seconds, which
1439
defaults to 60 (one minute), or when the DRAW_FRAME function
1442
note: All but the first argument are keyword arguments, with
1446
# Input argument i is the frame number.
1447
# draw_frame should return non-zero if there are more
1448
# frames in this movie. A zero return will stop the
1450
# draw_frame must NOT include any fma command if the
1451
# making_movie variable is set (movie sets this variable
1452
# before calling draw_frame)
1454
If MIN_INTERFRAME is specified, a pause will be added as
1455
necessary to slow down the movie. MIN_INTERFRAME is a time
1456
in seconds (default 0).
1458
The keyword BRACKET_TIME (again a time in seconds) can be
1459
used to adjust the duration of the pauses after the first
1460
and last frames. It may also be a two element array [beg, end].
1461
If the pause at the end is greater than five seconds, you will
1462
be prompted to explain that hitting <RETURN> will abort the final
1463
pause. Well, the Python version does not have this capability.
1465
TIMING = 1 enables a timing printout for your movie.
1467
If every frame of your movie has the same limits, use the
1468
limits function to fix the limits before you call movie.
1470
BUG: If you hit <RETURN> to start a movie early, it will not
1471
pause at the end of the movie at all. You probably should
1472
not use long initial pauses.
1475
movie_stats ( [timing])
1476
prints statistics from the last movie command, or from the
1477
command which produced TIMING. TIMING is the contents of the
1478
movie_timing external variable after the movie command completes.
1481
plane3 (normal, point)
1482
NORMAL and POINT are sequences of length 3.
1483
returns [nx,ny,nz,pp] for the specified plane.
1487
or m = mesh3 (x, y, z, funcs = [f1, f2,...])
1488
or m = mesh3 (xyz, funcs = [f1, f2,...])
1489
or m = mesh3 (nxnynz, dxdydz, x0y0z0, funcs = [f1, f2,...])
1491
make mesh3 argument for slice3, xyz3, getv3, etc., functions.
1492
X, Y, and Z are each 3D coordinate arrays. The optional F1, F2,
1493
etc. are 3D arrays of function values (e.g. density, temperature)
1494
which have one less value along each dimension than the coordinate
1495
arrays. The "index" of each zone in the returned mesh3 is
1496
the index in these cell-centered Fi arrays, so every index from
1497
one through the total number of cells indicates one real cell.
1498
The Fi arrays can also have the same dimensions as X, Y, or Z
1499
in order to represent point-centered quantities.
1501
If X has four dimensions and the length of the first is 3, then
1502
it is interpreted as XYZ (which is the quantity actually stored
1503
in the returned cell list).
1505
If X is a vector of 3 integers, it is interpreted as [nx,ny,nz]
1506
of a uniform 3D mesh, and the second and third arguments are
1507
[dx,dy,dz] and [x0,y0,z0] respectively. (DXDYDZ represent the
1508
size of the entire mesh, not the size of one cell, and NXNYNZ are
1509
the number of cells, not the number of points.)
1511
Added by ZCM 1/13/97: if x, y, and z are one-dimensional of
1512
the same length and if the keyword verts exists and yields
1513
an NCELLS by 8 integer array, then we have an unstructured
1514
rectangular mesh, and the subscripts of cell i's vertices
1517
other sorts of meshes are possible -- a mesh which lives
1518
in a binary file is an obvious example -- which would need
1519
different workers for xyz3, getv3, getc3, and iterator3
1520
iterator3_rect may be more general than the other three.
1523
[NVERTS, XYZVERTS, color] = slice3 (m3, fslice, nverts, xyzverts)
1524
or [NVERTS, XYZVERTS, color] =
1525
slice3(m3, fslice, nverts, xyzverts, fcolor, node = 0)
1526
or [NVERTS, XYZVERTS, color] =
1527
slice3(m3, fslice, nverts, xyzverts, fcolor, 1, node = 0)
1529
slice the 3D mesh M3 using the slicing function FSLICE, returning
1530
the list [NVERTS, XYZVERTS, color]. Note that it is impossible to
1531
pass arguments as addresses, as yorick does in this routine.
1532
NVERTS is the number of vertices in each polygon of the slice, and
1533
XYZVERTS is the 3-by-sum(NVERTS) list of polygon vertices. If the
1534
FCOLOR argument is present, the values of that coloring function on
1535
the polygons are returned as the value of the slice3 function
1536
(len (color_values) == len (NVERTS) == number of polygons).
1538
If the slice function FSLICE is a function, it should be of the
1540
func fslice(m3, chunk)
1541
returning a list of function values on the specified chunk of the
1542
mesh m3. The format of chunk depends on the type of m3 mesh, so
1543
you should use only the other mesh functions xyz3 and getv3 which
1544
take m3 and chunk as arguments. The return value of fslice should
1545
have the same dimensions as the return value of getv3; the return
1546
value of xyz3 has an additional first dimension of length 3.
1547
N. B. (ZCM 2/24/97) I have eliminated the globals iso_index
1548
and _value, so for isosurface_slicer only, the call must be
1549
of the form fslice (m3, chunk, iso_index, _value).
1550
Likewise, I have eliminated normal and projection, so
1551
for plane_slicer only, we do fslice (m3, chunk, normal, projection).
1553
If FSLICE is a list of 4 numbers, it is taken as a slicing plane
1554
of the form returned by plane3.
1556
If FSLICE is a single integer, the slice will be an isosurface for
1557
the FSLICEth variable associated with the mesh M3. In this case,
1558
the keyword VALUE must also be present, representing the value
1559
of that variable on the isosurface.
1561
If FCOLOR is None, slice3 returns None. If you want to color the
1562
polygons in a manner that depends only on their vertex coordinates
1563
(e.g.- by a 3D shading calculation), use this mode.
1565
If FCOLOR is a function, it should be of the form:
1566
func fcolor(m3, cells, l, u, fsl, fsu, ihist)
1567
returning a list of function values on the specified cells of the
1568
mesh m3. The cells argument will be the list of cell indices in
1569
m3 at which values are to be returned. l, u, fsl, fsu, and ihist
1570
are interpolation coefficients which can be used to interpolate
1571
from vertex centered values to the required cell centered values,
1572
ignoring the cells argument. See getc3 source code.
1573
The return values should always have cells.shape.
1575
If FCOLOR is a single integer, the slice will be an isosurface for
1576
the FCOLORth variable associated with the mesh M3.
1578
If the optional argument after FCOLOR is non-nil and non-zero,
1579
then the FCOLOR function is called with only two arguments:
1580
func fcolor(m3, cells)
1582
The keyword argument NODE, if present and nonzero, is a signal
1583
to return node-centered values rather than cell-centered
1584
values. (ZCM 4/16/97)
1587
slice3mesh (z, color = None, smooth = 0)
1588
slice3mesh (nxny, dxdy, x0y0, z, color = None, smooth = 0)
1589
slice3mesh (x, y, z, color = None, smooth = 0)
1591
slice3mesh returns a triple [nverts, xyzverts, color]
1592
nverts is no_cells long and the ith entry tells how many
1593
vertices the ith cell has.
1594
xyzverts is sum (nverts) by 3 and gives the vertex
1595
coordinates of the cells in order.
1596
color, if present, is len (nverts) long and contains
1597
a color value for each cell in the mesh if smooth == 0;
1598
sum (nverts) long and contains a color value for each
1599
node in the mesh if smooth == 1.
1600
There are a number of ways to call slice3mesh:
1601
slice3mesh (z, color = None, smooth = 0)
1602
z is a two dimensional array of function values, assumed
1603
to be on a uniform mesh nx by ny nodes (assuming z is nx by ny)
1604
nx being the number of nodes in the x direction, ny the number
1606
color, if specified, is either an nx - 1 by ny - 1 array
1607
of cell-centered values by which the surface is to
1608
be colored, or an nx by ny array of vertex-
1609
centered values, which will be averaged over each
1610
cell to give cell-centered values if smooth == 0, or
1611
returned as a node-centered array sum (nverts) long if
1613
slice3mesh (nxny, dxdy, x0y0, z, color = None, smooth = 0)
1614
In this case, slice3mesh accepts the specification for
1615
a regular 2d mesh: nxny is the number of cells in the
1616
x direction and the y direction (i. e., its two components
1617
are nx - 1 and ny - 1, nx by ny being the node size;
1618
x0y0 are the initial values of x and y; and dxdy are the
1619
increments in the two directions. z is the height of a
1620
surface above the xy plane and must be dimensioned nx by ny.
1621
color, if specified, is as above.
1622
slice3mesh (x, y, z, color = None, smooth = 0)
1623
z is as above, an nx by ny array of function values
1624
on a mesh of the same dimensions. There are two choices
1625
for x and y: they can both be one-dimensional, dimensioned
1626
nx and ny respectively, in which case they represent a
1627
mesh whose edges are parallel to the axes; or else they
1628
can both be nx by ny, in which case they represent a
1629
general quadrilateral mesh.
1630
color, if specified, is as above.
1633
iterator3 (m3 , chunk = None, clist = None)
1634
The iterator3 function combines three distinct operations:
1635
(1) If only the M3 argument is given, return the initial
1636
chunk of the mesh. The chunk will be no more than
1637
chunk3_limit cells of the mesh.
1638
(2) If only M3 and CHUNK are given, return the next CHUNK,
1639
or [] if there are no more chunks.
1640
(3) If M3, CHUNK, and CLIST are all specified, return the
1641
absolute cell index list corresponding to the index list
1642
CLIST of the cells in the CHUNK.
1643
Do not increment the chunk in this case.
1645
The form of the CHUNK argument and return value for cases (1)
1646
and (2) is not specified, but it must be recognized by the
1647
xyz3 and getv3 functions which go along with this iterator3.
1648
(For case (3), CLIST and the return value are both ordinary
1652
This is the iterator3 function for a regular rectangular mesh.
1655
Does the same thing as iterator3_rect only for an irregular
1656
rectangular mesh. It simply splits a large mesh into smaller
1657
parts. Whether this is necessary I am not sure.
1658
Certainly it makes it easier in the irregular case to handle
1659
the four different types of cells separately.
1660
if clist is present, in the irregular case it is already
1661
the list of absolute cell indices, so it is simply returned.
1662
This and other routines to do with irregular meshes return a
1663
chunk which is a 2-list. The first item delimits the chunk;
1664
the second gives a list of corresponding cell numbers.
1669
return vertex values of the Ith function attached to 3D mesh M3
1670
for cells in the specified CHUNK. The CHUNK may be a list of
1671
cell indices, in which case getv3 returns a 2x2x2x(CHUNK.shape)
1672
list of vertex coordinates. CHUNK may also be a mesh-specific data
1673
structure used in the slice3 routine, in which case getv3 may
1674
return a (ni)x(nj)x(nk) array of vertex values. For meshes which
1675
are logically rectangular or consist of several rectangular
1676
patches, this is up to 8 times less data, with a concomitant
1677
performance advantage. Use getv3 when writing slicing functions
1681
the getv3 function for regular rectangular meshes.
1684
for an irregular mesh, returns a 3-list whose elements are:
1685
(1) the function values for the ith function on the vertices of the
1686
given chunk. (The function values must have the same dimension
1687
as the coordinates; there is no attempt to convert zone-centered
1688
values to vertex-centered values.)
1689
(2) an array of relative cell numbers within the list of cells
1691
(3) a number that can be added to these relative numbers to gives
1692
the absolute cell numbers for correct access to their coordinates
1693
and function values.
1697
or getc3(i, m3, clist, l, u, fsl, fsu, cells)
1699
return cell values of the Ith function attached to 3D mesh M3
1700
for cells in the specified CHUNK. The CHUNK may be a list of
1701
cell indices, in which case getc3 returns a (CHUNK.shape)
1702
list of vertex coordinates. CHUNK may also be a mesh-specific data
1703
structure used in the slice3 routine, in which case getc3 may
1704
return a (ni)x(nj)x(nk) array of vertex values. There is no
1705
savings in the amount of data for such a CHUNK, but the gather
1706
operation is cheaper than a general list of cell indices.
1707
Use getc3 when writing colorng functions for slice3.
1709
If CHUNK is a CLIST, the additional arguments L, U, FSL, and FSU
1710
are vertex index lists which override the CLIST if the Ith attached
1711
function is defined on mesh vertices. L and U are index lists into
1712
the (CLIST.shape)x2x2x2 vertex value array, say vva, and FSL
1713
and FSU are corresponding interpolation coefficients; the zone
1714
centered value is computed as a weighted average of involving these
1715
coefficients. The CELLS argument is required by histogram to do
1716
the averaging. See the source code for details.
1717
By default, this conversion (if necessary) is done by averaging
1718
the eight vertex-centered values.
1721
The getc3 function for a regular rectangular mesh.
1724
Returns the same type of data structure as getc3_rect,
1725
but from an irregular rectangular mesh.
1726
m3 [1] is a 2-list; m3[1] [0] is an array whose ith element
1727
is an array of coordinate indices for the ith cell,
1728
or a list of up to four such arrays.
1729
m3 [1] [1] is the 3 by nverts array of coordinates.
1730
m3 [2] is a list of arrays of vertex-centered or cell-centered
1732
chunk may be a list, in which case chunk [0] is a 2-sequence
1733
representing a range of cell indices; or it may be a one-dimensional
1734
array, in which case it is a nonconsecutive set of cell indices.
1735
It is guaranteed that all cells indexed by the chunk are the
1739
plzcont (nverts, xyzverts, contours = 8, scale = "lin", clear = 1,
1740
edges = 0, color = None, cmin = None, cmax = None, split = 0)
1741
Plot filled z contours on the specified surface. NVERTS and
1742
XYZVERTS arrays specify the polygons for the surface being
1743
drawn. CONTOURS can be one of the following:
1744
N, an integer: Plot N contours (therefore, N+1 colored
1745
components of the surface)
1746
CVALS, a vector of floats: draw the contours at the
1748
SCALE can be "lin", "log", or "normal" specifying the
1749
contour scale. (Only applicable if contours = N, of course).
1750
If CLEAR = 1, clear the display list first.
1751
If EDGES = 1, plot the edges.
1752
The algorithm is to apply slice2x repeatedly to the surface.
1753
If color == None, then bytscl the palette into N + 1 colors
1754
and send each of the slices to pl3tree with the appropriate color.
1755
If color == "bg", will plot only the edges.
1756
If CMIN is given, use it instead of the minimum z actually
1757
being plotted. If CMAX is given, use it instead of the maximum
1758
z actually being plotted.
1759
If SPLIT is nonzero, then colors are computed based only on the
1760
first half of the palette (i. e., a split palette is assumed).
1763
pl4cont (nverts, xyzverts, values, contours = 8, scale = "lin", clear = 1,
1764
edges = 0, color = None, cmin = None, cmax = None, split = 0)
1765
Plot filled z contours on the specified surface. VALUES is
1766
a cell-centered array the same length as SUM (NVERTS) whose
1767
contours will be drawn. NVERTS and
1768
XYZVERTS arrays specify the polygons for the surface being
1769
drawn. CONTOURS can be one of the following:
1770
N, an integer: Plot N contours (therefore, N+1 colored
1771
components of the surface)
1772
CVALS, a vector of floats: draw the contours at the
1774
SCALE can be "lin", "log", or "normal" specifying the
1775
contour scale. (Only applicable if contours = N, of course).
1776
If CLEAR == 1, clear the display list first.
1777
If EDGES == 1, plot the edges.
1778
The algorithm is to apply slice2x repeatedly to the surface.
1779
If color == None, then bytscl the palette into N + 1 colors
1780
and send each of the slices to pl3tree with the appropriate color.
1781
If color == "bg", will plot only the edges.
1782
If CMIN is given, use it instead of the minimum z actually
1783
being plotted. If CMAX is given, use it instead of the maximum
1784
z actually being plotted.
1785
If SPLIT is nonzero, then colors are computed based only on the
1786
first half of the palette (i. e., a split palette is assumed).
1789
[nvf, xyzvf, colorf, nvb, xyzvb, colorb] =
1790
slice2x (plane, nverts, xyzverts, values = None)
1791
Slice a polygon list, returning in nvf and xyzvf only those
1792
polygons or parts of polygons on the positive side of PLANE,
1793
and in nvb and xyzvb only those polygons or parts of polygons
1794
on the negative side of PLANE.
1795
If PLANE is a scalar real, then VALUES must be a function
1796
defined on the vertices of the mesh, and the mesh will
1797
be sliced where the function has that value.
1798
The NVERTS, XYZVERTS, and VALUES arrays have the meanings
1799
of the return values from the slice3 function. It is legal
1800
to omit the VALUES argument (e.g.- if there is no fcolor
1802
In order to plot two intersecting slices, one could
1803
slice (for example) the horizontal plane twice (slice2x) -
1804
first with the plane of the vertical slice, then with minus
1805
that same plane. Then, plot first the back part of the
1806
slice, then the vertical slice, then the front part of the
1807
horizontal slice. Of course, the vertical plane could
1808
be the one to be sliced, and "back" and "front" vary
1809
depending on the view point, but the general idea always
1813
[nvf, xyzvf, colorf] = slice2 ((plane, nverts, xyzverts, values = None)
1814
Slice a polygon list, returning in nvf and xyzvf only those
1815
polygons or parts of polygons on the positive side of PLANE.
1816
If PLANE is a scalar real, then VALUES must be a function
1817
defined on the vertices of the mesh, and the mesh will
1818
be sliced where the function has that value.
1819
The NVERTS, XYZVERTS, and VALUES arrays have the meanings
1820
of the return values from the slice3 function. It is legal
1821
to omit the VALUES argument (e.g.- if there is no fcolor
1823
In order to plot two intersecting slices, one could
1824
slice (for example) the horizontal plane twice (slice2x) -
1825
first with the plane of the vertical slice, then with minus
1826
that same plane. Then, plot first the back part of the
1827
slice, then the vertical slice, then the front part of the
1828
horizontal slice. Of course, the vertical plane could
1829
be the one to be sliced, and "back" and "front" vary
1830
depending on the view point, but the general idea always
1834
pl3surf(nverts, xyzverts = None, values = None, cmin = None, cmax = None,
1835
lim = None, edges = 0)
1836
Perform simple 3D rendering of an object created by slice3
1837
(possibly followed by slice2). NVERTS and XYZVERTS are polygon
1838
lists as returned by slice3, so XYZVERTS is sum(NVERTS)-by-3,
1839
where NVERTS is a list of the number of vertices in each polygon.
1840
If present, the VALUES should have the same length as NVERTS;
1841
they are used to color the polygon. If VALUES is not specified,
1842
the 3D lighting calculation set up using the light3 function
1843
will be carried out. Keywords CMIN and CMAX as for plf, pli,
1844
or plfp are also accepted. (If you do not supply VALUES, you
1845
probably want to use the AMBIENT keyword to light3 instead of
1846
CMIN here, but CMAX may still be useful.)
1847
EDGES should be set nonzero if you wish the mesh lines plotted
1851
pl3tree (nverts, xyzverts = None, values = None, plane = None,
1852
cmin = None, cmax = None, split = 1, edges = 0)
1853
Add the polygon list specified by NVERTS (number of vertices in
1854
each polygon) and XYZVERTS (3-by-sum(NVERTS) vertex coordinates)
1855
to the currently displayed b-tree. If VALUES is specified, it
1856
must have the same dimension as NVERTS, and represents the color
1857
of each polygon. (ZCM 7/18/97) Or, if VALUES == "bg" ("background")
1858
Then each polygon will be filled with the background color,
1859
giving just a wire frame. If VALUES is not specified, the polygons
1860
are assumed to form an isosurface which will be shaded by the
1861
current 3D lighting model; the isosurfaces are at the leaves of
1862
the b-tree, sliced by all of the planes. If PLANE is specified,
1863
the XYZVERTS must all lie in that plane, and that plane becomes
1864
a new slicing plane in the b-tree.
1866
Each leaf of the b-tree consists of a set of sliced isosurfaces.
1867
A node of the b-tree consists of some polygons in one of the
1868
planes, a b-tree or leaf entirely on one side of that plane, and
1869
a b-tree or leaf on the other side. The first plane you add
1870
becomes the root node, slicing any existing leaf in half. When
1871
you add an isosurface, it propagates down the tree, getting
1872
sliced at each node, until its pieces reach the existing leaves,
1873
to which they are added. When you add a plane, it also propagates
1874
down the tree, getting sliced at each node, until its pieces
1875
reach the leaves, which it slices, becoming the nodes closest to
1878
This structure is relatively easy to plot, since from any
1879
viewpoint, a node can always be plotted in the order from one
1880
side, then the plane, then the other side.
1881
This routine assumes a "split palette"; the colors for the
1882
VALUES will be scaled to fit from color 0 to color 99, while
1883
the colors from the shading calculation will be scaled to fit
1884
from color 100 to color 199. (If VALUES is specified as an
1885
unsigned char (Python typecode 'b') array, however, it will
1886
be used without scaling.) You may specifiy a CMIN or CMAX
1887
keyword to affect the scaling; CMIN is ignored if VALUES is
1888
not specified (use the AMBIENT keyword from light3 for that
1891
(ZCM 4/23/97) Add the SPLIT keyword. This will determine
1892
whether or not to split the palette (half to the isosurfaces
1893
for shading and the other half to plane sections for contouring).
1896
split_palette ( [ <string>])
1897
split the current palette or the specified palette into two
1898
parts; colors 0 to 99 will be a compressed version of the
1899
original, while colors 100 to 199 will be a gray scale.
1902
split_bytscl (x, upper, cmin = None, cmax = None)
1903
as bytscl function, but scale to the lower half of a split
1904
palette (0-99, normally the color scale) if the second parameter
1905
is zero or nil, or the upper half (100-199, normally the gray
1906
scale) if the second parameter is non-zero.
1910
return vertex coordinates for CHUNK of 3D mesh M3. The CHUNK
1911
may be a list of cell indices, in which case xyz3 returns a
1912
(CHUNK.shape)x3x2x2x2 list of vertex coordinates. CHUNK may
1913
also be a mesh-specific data structure used in the slice3
1914
routine, in which case xyz3 may return a 3x(ni)x(nj)x(nk)
1915
array of vertex coordinates. For meshes which are logically
1916
rectangular or consist of several rectangular patches, this
1917
is up to 8 times less data, with a concomitant performance
1918
advantage. Use xyz3 when writing slicing functions or coloring
1919
functions for slice3.
1922
The xyz3 function for a regular, rectangular mesh.
1925
The xyz3 function for an irregular, unstructured mesh.
1928
The xyz3 function for a uniform mesh.
1931
to_corners3(list, nj, nk)
1932
convert an array of cell indices in an (ni-1)-by-(NJ-1)-by-(NK-1)
1933
logically rectangular grid of cells into the list of
1934
len(LIST)-by-2-by-2-by-2 cell corner indices in the
1935
corresponding ni-by-NJ-by-NK array of vertices.
1936
Note that this computation in Yorick gives an absolute offset
1937
for each cell quantity in the grid. In Yorick it is legal to
1938
index a multidimensional array with an absolute offset. In
1939
Python it is not. However, an array can be flattened if
1941
Other changes from Yorick were necessitated by row-major
1942
order and 0-origin indices, and of course the lack of
1943
Yorick array facilities.
added
removed
Lib/xplt/gistdata/gist.help
