section p of routines in graph.i

Home Manual Packages Global Index Keywords Quick Reference | # functions in graph.i - p
palette |
                 palette, filename
              or palette, source_window_number
              or palette, red, green, blue, ntsc=1/0
              or palette, red, green, blue, gray
     	 or palette, red, green, blue, query=1
     	 or palette, red, green, blue, gray, query=1

         sets (or retrieves with query=1) the palette for the current
         graphics window.  The FILENAME is the name of a Gist palette file;
         the standard palettes are "earth.gp", "stern.gp", "rainbow.gp",
         "heat.gp", "gray.gp", and "yarg.gp".  Use the maxcolors keyword
         in the pldefault command to put an upper limit on the number of
         colors which will be read from the palette in FILENAME.
         In the second form, the palette for the current window is copied
         from the SOURCE_WINDOW_NUMBER.  If the X colormap for the window is
         private, there will still be two separate X colormaps for the two
         windows, but they will have the same color values.
         In the third form, RED, GREEN, and BLUE are 1-D arrays of the same
         length specifying the palette you wish to install; the values
         should vary between 0 and 255, and your palette should have no
         more than 240 colors.  If ntsc=0, monochrome devices (such as most
         laser printers) will use the average brightness to translate your
         colors into gray; otherwise, the NTSC (television) averaging will
         be used (.30*RED+.59*GREEN+.11*BLUE).  Alternatively, you can specify
         GRAY explicitly.
         Ordinarily, the palette is not dumped to a hardcopy file
         (color hardcopy is still rare and expensive), but you can
         force the palette to dump using the window or hcp_file commands.
         See the dump= keyword for the hcp_file and window commands if you
         are having trouble getting color in your hardcopy files.

    builtin function, documented at i0/graph.i   line 227
SEE ALSO: | window, fma, hcp, pldefault, plg
pause |
                 pause, milliseconds

         pause for the specified number of milliseconds of wall clock
         time, or until input arrives from the keyboard.
         This is intended for use in creating animated sequences.

    builtin function, documented at i0/graph.i   line 1307
plc |
                 plc, z, y, x, levs=z_values
              or plc, z, y, x, ireg, levs=z_values
     	 or plc, z, levs=z_values

         plots a contours of Z on the mesh Y versus X.  Y, X, and IREG are
         as for plm.  The Z array must have the same shape as Y and X.
         The function being contoured takes the value Z at each point
         (X,Y) -- that is, the Z array is presumed to be point-centered.
         The Y, X, and IREG arguments may all be omitted to default to the
         mesh set by the most recent plmesh call.
         The LEVS keyword is a list of the values of Z at which you want
         contour curves.  The default is eight contours spanning the
         range of Z.
         See plfc if you want to color the regions between contours.
         The following keywords are legal (each has a separate help entry):
       KEYWORDS: legend, hide
    	     type, width, color, smooth
                 marks, marker, mspace, mphase
    	     smooth, triangle, region

    builtin function, documented at i0/graph.i   line 369
SEE ALSO: | plg, plm, plc, plv, plf, pli, plt, pldj, plfp, plmesh, plfc, contour, spann, limits, logxy, range, fma, hcp
pldefault |
                 pldefault, key1=value1, key2=value2, ...

         sets default values for the various properties of graphical elements.
         The keywords can be most of the keywords that can be passed to the
         plotting commands:
           plg:  color, type, width,
                 marks, mcolor, msize, mspace, mphase,
    	     rays, rspace, rphase, arrowl, arroww
           pldj: color, type, width
           plt:  color, font, height, path, justify, opaque
           plm:  color, type, width
           plv:  color, hollow, width, aspect
           plc:  color, type, width,
                 marks, mcolor, marker, msize, mspace, mphase
           plf:  edges, ecolor, ewidth
         The initial default values are:
           color="fg", type="solid", width=1.0 (1/2 point),
           marks=1, mcolor="fg", msize=1.0 (10 points),
              mspace=0.16, mphase=0.14,
           rays=0, arrowl=1.0 (10 points), arroww=1.0 (4 points),
              rspace=0.13, rphase=0.11375,
           font="helvetica", height=12.0, justify="NN", opaque=0,
           hollow= 0, aspect=0.125,
           edges=0, ecolor="fg", ewidth=1.0 (1/2 point)
         Additional default keywords are:
           dpi, style, legends  (see window command)
           palette              (to set default filename as in palette command)
           maxcolors            (default 200)

    builtin function, documented at i0/graph.i   line 1180
SEE ALSO: | window, plsys, plq, pledit, plg
pldj |
                 pldj, x0, y0, x1, y1

         plots disjoint lines from (X0,Y0) to (X1,Y1).  X0, Y0, X1, and Y1
         may have any dimensionality, but all must have the same number of
         elements.
         The following keywords are legal (each has a separate help entry):
       KEYWORDS: legend, hide
    	     type, width, color

    builtin function, documented at i0/graph.i   line 546
SEE ALSO: | plg, plm, plc, plv, plf, pli, plt, pldj, plfp, limits, logxy, range, fma, hcp
pledit |
                 pledit, key1=value1, key2=value2, ...
              or pledit, n_element, key1=value1, key2=value2, ...

              or pledit, n_element, n_contour, key1=value1, key2=value2, ...

         changes some property of element number N_ELEMENT (and contour
         number N_CONTOUR of that element).  If N_ELEMENT and N_CONTOUR are
         omitted, the default is the most recently added element, or the
         element specified in the most recent plq query command.
         The keywords can be any of the keywords that apply to the current
         element.  These are:
           plg:  color, type, width,
                 marks, mcolor, marker, msize, mspace, mphase,
    	     rays, rspace, rphase, arrowl, arroww,
    	     closed, smooth
           pldj: color, type, width
           plt:  color, font, height, path, justify, opaque
           plm:  region, boundary, inhibit, color, type, width
           plf:  region
           plv:  region, color, hollow, width, aspect, scale
           plc:  region, color, type, width,
                 marks, mcolor, marker, msize, mspace, mphase
    	     smooth, levs
         (For contours, if you aren't talking about a particular N_CONTOUR,
          any changes will affect ALL the contours.)
         A plv (vector field) element can also take the scalem
         keyword to multiply all vector lengths by a specified factor.
         A plt (text) element can also take the dx and/or dy
         keywords to adjust the text position by (dx,dy).

    builtin function, documented at i0/graph.i   line 1145
SEE ALSO: | window, plsys, plq, pldefault, plg
plf |
                 plf, z, y, x
              or plf, z, y, x, ireg
     	 or plf, z

         plots a filled mesh Y versus X.  Y, X, and IREG are as for plm.
         The Z array must have the same shape as Y and X, or one smaller
         in both dimensions.  If Z is of type char, it is used "as is",
         otherwise it is linearly scaled to fill the current palette, as
         with the bytscl function.
         (See the bytscl function for explanation of top, cmin, cmax.)
         The mesh is drawn with each zone in the color derived from the Z
         function and the current palette; thus Z is interpreted as a
         zone-centered array.
         As for pli and plfp, Z may also be a 3x(NX-1)x(NY-1) array
         of char giving the [r,g,b] components of each color.  See the
         color keyword for cautions about using this if you do not have
         a true color display.
         The Y, X, and IREG arguments may all be omitted to default to the
         mesh set by the most recent plmesh call.
         A solid edge can optionally be drawn around each zone by setting
         the EDGES keyword non-zero.  ECOLOR and EWIDTH determine the edge
         color and width.  The mesh is drawn zone by zone in order from
         IREG(2+imax) to IREG(jmax*imax) (the latter is IREG(imax,jmax)),
         so you can achieve 3D effects by arranging for this order to
         coincide with back-to-front order.  If Z is nil, the mesh zones
         are filled with the background color, which you can use to
         produce 3D wire frames.
         The following keywords are legal (each has a separate help entry):
       KEYWORDS: legend, hide
    	     region, top, cmin, cmax, edges, ecolor, ewidth

    builtin function, documented at i0/graph.i   line 453
SEE ALSO: | plg, plm, plc, plv, plf, pli, plt, pldj, plfp, plmesh, limits, logxy, range, fma, hcp, palette, bytscl, histeq_scale
plfc |
                 plfc, z, y, x, levs=z_values
              or plfc, z, y, x, ireg, levs=z_values

         fills contours of Z on the mesh Y versus X.  Y, X, and IREG are
         as for plm.  The Z array must have the same shape as Y and X.
         The function being contoured takes the value Z at each point
         (X,Y) -- that is, the Z array is presumed to be point-centered.
         The LEVS keyword is a list of the values of Z at which you want
         contour curves.  These curves divide the mesh into numberof(LEVS)+1
         regions, each of which is filled with a solid color.  If LEVS is
         nil, up to 19 "nice" equally spaced level values spanning the
         range of Z are selected.  The level values actually used are
         always output to the external variable plfc_levs.
         If you specify levs=, you may also specify colors= a list of
         colors of length numberof(LEVS)+1.  The colors should be indices
         into the current palette.  If you do not specify them, equally
         spaced colors are chosen.
         The following keywords are legal (each has a separate help entry):
       KEYWORDS: triangle, region

    interpreted function, defined at i0/graph.i   line 1520
SEE ALSO: | plg, plm, plc, plv, plf, pli, plt, pldj, plfp, plmesh, color_bar, spann, contour, limits, logxy, range, fma, hcp
plfp |
                 plfp, z, y, x, n

         plots a list of filled polygons Y versus X, with colors Z.
         The N array is a 1D list of lengths (number of corners) of the
         polygons; the 1D colors array Z has the same length as N.  The
         X and Y arrays have length sum(N).
         If Z is of type char, it is used "as is", otherwise it is linearly
         scaled to fill the current palette, as with the bytscl function.
         If Z is nil, the background color is used for every polygon.
         (See the bytscl function for explanation of top, cmin, cmax.)
         As for plf and pli, Z may also be a 3-by-numberof(N) array of
         char giving the [r,g,b] components of each color.  See the
         color keyword for cautions about using this if you do not have
         a true color display.
         As a special case, if n(2:)==1, the first polygon is assumed
         to have NDC coordinates, while the remaining individual X and Y
         values are in world coordinates.  The first polygon is drawn
         numberof(n)-1 times, with its (0,0) placed at each of the
         individual (X,Y) values in succession.  This is a hack to enable
         plotting of more elaborate data markers than plg,type=0 -- see
         the plmk function for details.
         The following keywords are legal (each has a separate help entry):
       KEYWORDS: legend, hide, top, cmin, cmax, edges, ecolor, ewidth

    builtin function, documented at i0/graph.i   line 489
SEE ALSO: | plg, plm, plc, plv, plf, pli, plt, pldj, plfc, limits, logxy, range, fma, hcp
plg |
                 plg, y, x
              or plg, y

         plots a graph of Y versus X.  Y and X must be 1-D arrays of equal
         length; if X is omitted, it defaults to [1, 2, ..., numberof(Y)].
         A keyword n=[n1,n2,n3,...nN] can be used to add N curves.  In this
         case, sum(n) must be numberof(y).
         The following keywords are legal (each has a separate help entry):
       KEYWORDS: legend, hide
    	     type, width, color, closed, smooth
                 marks, marker, mspace, mphase
    	     rays, arrowl, arroww, rspace, rphase

    builtin function, documented at i0/graph.i   line 305
SEE ALSO: | plg, plm, plc, plv, plf, pli, plt, pldj, plfp, plmk, limits, logxy, range, fma, hcp
pli |
                 pli, z
              or pli, z, x1, y1
              or pli, z, x0, y0, x1, y1

         plots the image Z as a cell array -- an array of equal rectangular
         cells colored according to the 2-D array Z.  The first dimension
         of Z is plotted along x, the second dimension is along y.
         If Z is of type char, it is used "as is", otherwise it is linearly
         scaled to fill the current palette, as with the bytscl function.
         (See the bytscl function for explanation of top, cmin, cmax.)
         As for plf and plfp, Z may also be a 3D array with 1st dimension 3
         of char giving the [r,g,b] components of each color.  See the
         color keyword for cautions about using this if you do not have
         a true color display.
         If X1 and Y1 are given, they represent the coordinates of the
         upper right corner of the image.  If X0, and Y0 are given, they
         represent the coordinates of the lower left corner, which is at
         (0,0) by default.  If only the Z array is given, each cell will be
         a 1x1 unit square, with the lower left corner of the image at (0,0).
         The following keywords are legal (each has a separate help entry):
       KEYWORDS: legend, hide, top, cmin, cmax

    builtin function, documented at i0/graph.i   line 519
SEE ALSO: | plg, plm, plc, plv, plf, pli, plt, pldj, plfp, limits, logxy, range, fma, hcp, palette, bytscl, histeq_scale
plm |
                 plm, y, x, boundary=0/1, inhibit=0/1/2
              or plm, y, x, ireg, boundary=0/1, inhibit=0/1/2
     	 or plm, boundary=0/1, inhibit=0/1/2

         plots a mesh of Y versus X.  Y and X must be 2-D arrays with equal
         dimensions.  If present, IREG must be a 2-D region number array
         for the mesh, with the same dimensions as X and Y.  The values of
         IREG should be positive region numbers, and zero for zones which do
         not exist.  The first row and column of IREG never correspond to any
         zone, and should always be zero.  The default IREG is 1 everywhere
         else.  If present, the BOUNDARY keyword determines whether the
         entire mesh is to be plotted (boundary=0, the default), or just the
         boundary of the selected region (boundary=1).  If present, the
         INHIBIT keyword causes the (X(,j),Y(,j)) lines to not be plotted
         (inhibit=1), or the (X(i,),Y(i,)) lines to not be plotted (inhibit=2).
         By default (inhibit=0), mesh lines in both logical directions are
         plotted.
         The Y, X, and IREG arguments may all be omitted to default to the
         mesh set by the most recent plmesh call.
         The following keywords are legal (each has a separate help entry):
       KEYWORDS: legend, hide
    	     type, width, color
    	     region

    builtin function, documented at i0/graph.i   line 321
SEE ALSO: | plg, plm, plc, plv, plf, pli, plt, pldj, plfp, plmesh, limits, logxy, range, fma, hcp
plmesh |
                 plmesh, y, x, ireg, triangle=tri_array
              or plmesh

         sets the default mesh for subsequent plm, plc, plv, and plf calls.
         In the second form, deletes the default mesh (until you do this,
         or switch to a new default mesh, the default mesh arrays persist and
         take up space in memory).  The Y, X, and IREG arrays should all be
         the same shape; Y and X will be converted to double, and IREG will
         be converted to int.  If IREG is omitted, it defaults to IREG(1,)=
         IREG(,1)= 0, IREG(2:,2:)=1; that is, region number 1 is the whole
         mesh.  The triangulation array TRI_ARRAY is used by plc; the
         correspondence between TRI_ARRAY indices and zone indices is the
         same as for IREG, and its default value is all zero.
         The IREG or TRI_ARRAY arguments may be supplied without Y and X
         to change the region numbering or triangulation for a given set of
         mesh coordinates.  However, a default Y and X must already have been
         defined if you do this.
         If Y is supplied, X must be supplied, and vice-versa.

    builtin function, documented at i0/graph.i   line 348
SEE ALSO: | plm, plc, plv, plf, plfp
plmk |
                 plmk, y,x

         Make a scatter plot of the points Y versus X.  If X is nil,
         it defaults to indgen(numberof(Y)).  By default, the marker
         cycles through 7 predefined marker shapes.  You may specify a shape
         using the marker= keyword, line width using the width= keyword (you
         get solid fills for width>=10), color using the color= keyword.
         You can also use the msize= keyword to scale the marker (default
         msize=1.0).  You can change the default width, color, or msize
         using the plmk_default function.
         The predefined marker= values are:
         marker=
           1	square
           2	cross
           3	triangle
           4	circle
           5	diamond
           6	cross (rotated 45 degrees)
           7	triangle (upside down)
         You may also put marker=[xm,ym] where xm and ym are vectors
         of NDC coordinates to design your own custom marker shapes.

    interpreted function, defined at i0/graph.i   line 1415
SEE ALSO: | plmk_default, plg
plmk_default |
                 plmk_default, color=color, msize=msize, width=width

         sets default color, msize, and width values for plmk.  Use
         width=10 to get solid fills.  With no parameters, plmk_default
         restores the initial default values.

    interpreted function, defined at i0/graph.i   line 1484
SEE ALSO: | plmk
plq |
                 plq
              or plq, n_element
     	 or plq, n_element, n_contour
     	 or legend_list= plq()
     	 or properties= plq(n_element, n_contour)

         Called as a subroutine, prints the list of legends for the current
         coordinate system (with an "(H)" to mark hidden elements), or prints
         a list of current properties of element N_ELEMENT (such as line type,
         width, font, etc.), or of contour number N_CONTOUR of element number
         N_ELEMENT (which must be contours generated using the plc command).
         Called as a function, returns either the list of legend strings, or a
         list of pointers to the values of the various element properties.
         Elements and contours are both numbered starting with one; hidden
         elements or contours are included in this numbering.
         The PROPERTIES list returned by plq is a list of pointers to the
         relevent properties for the specified graphical element.  Each
         possible property has a particular index in the returned PROPERTIES
         list as follows:
         *PROPERTIES(1)   int([element type (0 for none, 1 for plg, 2 for pldj,
                                             3 for plt, 4 for plm, 5 for plf,
    					 6 for plv, 7 for plc, 8 for pli,
    					 9 for plfp),
                               hide flag])
         *PROPERTIES(2)   string(legend)
         *PROPERTIES(3)   int array, depends on type (names match keywords):
           1 plg:  [color, type, marks, mcolor, marker, rays, closed, smooth]
           2 pldj: [color, type]
           3 plt:  [color, font, path, justify, opaque]
           4 plm:  [color, type, region, boundary, inhibit]
           5 plf:  [region, edges, ecolor]
           6 plv:  [region, color, hollow]
           7 plc:  [region, color, type, marks, mcolor, marker, smooth]
           8 pli:  nil
         *PROPERTIES(4)   double array, depends on type (names match keywords):
           1 plg:  [width, msize, mspace, mphase, rspace, rphase, arrowl, arroww]
           2 pldj: [width]
           3 plt:  [height, x, y]
           4 plm:  [width]
           5 plf:  [ewidth]
           6 plv:  [width, aspect, scale]
           7 plc:  [width, msize, mspace, mphase]
           8 pli:  [x0, x1, y0, y1]
         *PROPERTIES(5)   long array, depends on type (names match arguments):
           1 plg:  [npoints, &x, &y]
           2 pldj: [npoints, &x0, &y0, &x1, &y1]
           3 plt:  [nchars, &text]
           4 plm:  [imax, jmax, &x, &y, &ireg]
           5 plf:  [imax, jmax, &x, &y, &ireg, &colors]
           6 plv:  [imax, jmax, &x, &y, &ireg, &vx, &vy]
           7 plc:  [imax, jmax, &x, &y, &ireg, &z, &triangle, nlevs, &levs]
           8 pli:  [imax, jmax, &colors]
           9 plfp: [n, &x, &y, &colors, &pn]
         You can use the reshape function to peek at the data at the addresses
         returned in PROPERTIES(5) as longs.  The appropriate data types are:
         char for text, int for ireg, short for triangle, char for colors, and
         double for everything else.  In a plf, colors is (imax-1)-by-(jmax-1).
         Although PROPERTIES(5) returns pointers to the data plotted, attempting
         to poke new values into this data will not produce immediate changes
         to your plot, since the graphics package does not realize that anything
         has changed.  Use pledit to make changes to plotted elements.
         The plq function always operates on the current coordinate system
         in the current graphics window; use window and plsys to change these.

    builtin function, documented at i0/graph.i   line 1077
SEE ALSO: | window, plsys, pledit, pldefault, plg
plsys |
                 plsys, n
              or plsys(n)   or   plsys()

         sets the current coordinate system to number N in the current
         graphics window.  If N equals 0, subsequent elements will be
         plotted in absolute NDC coordinates outside of any coordinate
         system.  The default style sheet "work.gs" defines only a single
         coordinate system, so the only other choice is N equal 1.  You
         can make up your own style sheet (using a text editor) which
         defines mulitple coordinate systems.  You need to do this if
         you want to display four plots side by side on a single page,
         for example.  The standard style sheets "work2.gs" and "boxed2.gs"
         define two overlayed coordinate systems with the first labeled
         to the right of the plot and the second labeled to the left of
         the plot.  When using overlayed coordinate systems, it is your
         responsibility to ensure that the x-axis limits in the two
         systems are identical.
         Return value is coordinate system setting before this call;
         input n may be nil to retrieve this without changing it.  Return
         value can be <0 if the information is unavailable for some reason.

    builtin function, documented at i0/graph.i   line 279
SEE ALSO: | window, limits, plg
plt |
                 plt, text, x, y, tosys=0/1

         plots TEXT (a string) at the point (X,Y).  The exact relationship
         between the point (X,Y) and the TEXT is determined by the
         justify keyword.  TEXT may contain newline ("\n") characters
         to output multiple lines of text with a single call.  The
         coordinates (X,Y) are NDC coordinates (outside of any coordinate
         system) unless the tosys keyword is present and non-zero, in
         which case the TEXT will be placed in the current coordinate
         system.  However, the character height is NEVER affected by the
         scale of the coordinate system to which the text belongs.
         Note that the pledit command takes dx and/or dy keywords to
         adjust the position of existing text elements.
         The characters ^, _, and ! are treated specially in TEXT.
         ^ begins a superscript, _ begins a subscript, and ! causes the
         following character to be rendered using the symbol font.  As
         special cases, !^, !_, and !! render the ^, _, and ! characters
         themselves.  However, if ! is the final character of TEXT
         (or immediately before a newline in multiline text), it
         loses its special meaning.  TEXT has just three modes: ordinary,
         superscript, and subscript.  A ^ character enters superscript
         mode from ordinary or subscript mode, and returns to ordinary
         mode from superscript mode.  A _ enters subscript mode, except
         from subscript mode it returns to ordinary mode.  For example,
         Euclid said, "!pr^2", and Einstein said, "G_!s!n_=8!pT_!s!n".
         One final special escape: !] produces the ^ character in the
         symbol font (it is a perpendicular sign, whereas ] is just ]).
         The following keywords are legal (each has a separate help entry):
       KEYWORDS: legend, hide
    	     color, font, height, opaque, orient, justify

    builtin function, documented at i0/graph.i   line 558
SEE ALSO: | plt1, plg, plm, plc, plv, plf, pli, plt, pldj, plfp, pledit, limits, range, fma, hcp, pltitle
plt1 |
                 plt1, text, x, y

         same as plt, but TEXT, X, and Y may be arrays to plot multiple
         strings.  The tosys= keyword works as for plt.
       KEYWORDS: color, font, height, opaque, orient, justify

    interpreted function, defined at i0/graph.i   line 594
SEE ALSO: | plt
pltitle |
                 pltitle, title

         Plot TITLE centered above the coordinate system for any of the
         standard Gist styles.  You may want to customize this for other
         plot styles.

    interpreted function, defined at i0/graph.i   line 612
SEE ALSO: | plt, xytitles
plv |
                 plv, vy, vx, y, x, scale=dt
              or plv, vy, vx, y, x, ireg, scale=dt
     	 or plv, vy, vx, scale=dt

         plots a vector field (VX,VY) on the mesh (X,Y).  Y, X, and IREG are
         as for plm.  The VY and VX arrays must have the same shape as Y and X.
         The Y, X, and IREG arguments may all be omitted to default to the
         mesh set by the most recent plmesh call.
         The SCALE keyword is the conversion factor from the units of

         (VX,VY) to the units of (X,Y) -- a time interval if (VX,VY) is a velocity
         and (X,Y) is a position -- which determines the length of the
         vector "darts" plotted at the (X,Y) points.  If omitted, SCALE is
         chosen so that the longest ray arrows have a length comparable
         to a "typical" zone size.
         You can use the scalem keyword in pledit to make adjustments to the
         SCALE factor computed by default.
         The following keywords are legal (each has a separate help entry):
       KEYWORDS: legend, hide
    	     type, width, color, smooth
                 marks, marker, mspace, mphase
    	     triangle, region

    builtin function, documented at i0/graph.i   line 428
SEE ALSO: | plg, plm, plc, plv, plf, pli, plt, pldj, plfp, plmesh, pledit, limits, logxy, range, fma, hcp