Document Actions
POLYGON
Ref Sec24.
POLYGON
/I/J/K/L /X/Y/Z/T /OVERLAY /SET_UP /FRAME/D /TRANSPOSE /COORD_AX /SYMBOL /NOLABELS /LEVELS /LINE /COLOR /PALETTE /TITLE /THICKNESS /NOAXES /PATTERN /FILL /KEY /NOKEY /HLIMITS /VLIMITS
Produces a color-filled or line plot of polygons. By default a color key is drawn and lines are not drawn.
POLYGON[/qualifiers] x-vertices, y-vertices [, values]
Example:
This is the first example in the script poly_vec_demo.jnl The scripts poly_vector.jnl and mp_poly_vector.jnl make definitions to set up a polygon command to draw a vector field using arrow-shaped polygons, optionally filled with a color representing another quantity. Here is a wind field, colored according to Sea Level Pressure.
Parameters
The two x- and y- vertices parameters separately specify the x and y coordinates of the vertices of the polygons to be plotted.
The values may be any valid expression. If a color-filled plot is specified, the numerical value of the expression associated with each polygon determines the color of that polygon, as in SHADE and FILL plots. See the chapter "Variables and Expressions", section Expressions) for a definition of valid expressions. If values are omitted the /FILL option is not valid—only /LINE plots may be made.
The POLYGON command accepts single and multi-dimensional arguments.
- 1D FORM
yes? POLYGON xpoly1D, ypoly1D, values
where if xpoly1D or ypoly1D contain missing values, those represent the end of one polygon and the start of the next. The length of the values array must equal the number of polygons in which case the X coordinate might ve visualized as
x1,x1,x1,x1,BAD,x2,x2,x2,BAD,x3,x3,x3,x3,x3,x3,x3,x3,BAD,...
where the "1","2","3" refer to the successive polygons The script polymark.jnl makes a polygon plot by generating the correct 1-D arrays from a set of x and y coordinates and a polygon-shape specification. See polymark_demo for examples. polytube.jnl also makes use of the polymark command to draw "Lagrangian" plots along a track using color fill. These scripts are also distributed with Ferret :
yes? go polytube_demo.jnl
- 2D FORM
yes? POLYGON xpoly2D, ypoly2D, values
where values must be 1-dimensional and its axis must match in size and orientation one of the axes from the 2D arrays. This axis represents the list of successive polygons. The other axis of the 2D coordinates is the coordinates within each polygon. In the default case the X coordinate is the axis of the coordinates within polygons, and might be visualized as
x1,x1,x1,x1,BAD,BAD,...
x2,x2,x2,BAD,BAD,...
x3,x3,x3,x3,x3,x3,x3,x3,BAD,BAD,...
(with each list of polygon coordinates along the first axis padded with BAD to become the same length)
If the "values" argument is not given the coordinate axis may be specified using the /COORD_AX qualifier.
Example:
yes? LET XTRIANGLE = YSEQUENCE({-1,0,1})
yes? LET YTRIANGLE = YSEQUENCE({-1,1,-1})
yes? LET XPTS = 180+30*RANDU(I[i=1:10])
yes? LET YPTS = 30*RANDU(1+I[i=1:10])
yes? POLYGON XTRIANGLE+XPTS, YTRIANGLE+YPTS, I[I=1:10]
Command qualifiers for POLYGON:
POLYGON /I=/J=/K=/L=/X=/Y=/Z=/T=
Specifies value or range of axis subscripts (I, J, K, or L), or axis coordinates (X, Y, Z, or T) to be used when evaluating the expression being plotted.
For the 2-dimensional version of POLYGON, if "values" is omitted or is a constant then there is no information on which to determine which is the axis of the vertices within each polygon and which is the axes of successive polygons. The qualifier /COORD_AX can be used to specify which is the axis of successive polygons.
If COORD_AX is not specified, and values is unspecified or a constant, Ferret assumes that /COORD-AX is the second axis of the 2-dimensional coordinate arrays and issues a message to this effect.
Specifies the default data set to be used when evaluating the expression being plotted.
Fills the polygons with colors according to the third argument, values. If the values argument is omitted the /FILL option is not valid—only /LINE plots may be made.
Causes the graphic image produced by the command to be captured as an animation frame in the file specified by SET MOVIE. In general the FRAME command (p. 358) is more flexible and we recommend its use rather than this qualifier.
Displays a color key for the palette used in the color-filled plot. By default a key is drawn unless the /LINE or /NOKEY qualifier is specified. To control the color key position and labeling, see the command SHAKEY in the appendix, Ferret Enhancements to PPLUS). Note in particular that the Ferret Alias command, KEYMARK,1 turns on the annotation of the ends of the key with the minimum and maximum data values from the data that was plotted. KEYMARK,0 turns this capability off.
Specifies the POLYGON levels or how the levels will be determined. If the /LEVELS qualifier is omitted Ferret automatically selects reasonable POLYGON levels.
See the chapter "Customizing Plots", section "Contouring" for examples and more documentation on /LEVELS.
Outlines polygons specified by x and y vertices on a POLYGON plot. When /LINE is specified the color key is omitted unless specifically requested via /KEY. The line type is controlled by the /COLOR= and /THICK= qualifiers
Simple specification of outline characteristics for polygon plots which specify an outline line we control line thickness and color with commands such as
yes? POLYGON/LINE/COLOR=blue/THICK=2 {1,2,1}, {3,2,1}
This is equivalent to the (still supported) use of the /LINE qualifiers in
yes? POLYGON/LINE=10 {1,2,1}, {3,2,1} ! 4(blue) + 6*(2-1)
The available color names are Black, Red, Green, Blue, LightBlue, Purple, and White (not case sensitive), corresponding to the /LINE values 1-6, respectively. (/COLOR also accepts numerical values.) The line thickness may be 1, 2, or 3 corresponding to pixel thickness on the screen or corresponding to multiples of the default line thickness on hard copy, however the color White is only available in the default THICKNESS=1. The /DASH qualifier is not available for the outlines of POLYGON but dashes can be drawn using
POLYGON x-vertices, y-vertices
PLOT/OVER/VS/DASH x-vertices, y-vertices
Suppresses the drawing of a color key for the palette used in the plot.
Suppresses all plot labels.
Causes the indicated POLYGON plot to be overlaid on the existing plot.
Specifies a color palette (otherwise, a default rainbow palette is used). Try the Unix command % Fpalette '*' to see available palettes. The file suffix *.spk is not necessary when specifying a palette.
The /PALETTE qualifier changes the current palette for the duration of the plotting command and then restores the previous palette. This behavior is not immediately compatible with the /SET_UP qualifier. See the PALETTE command for further discussion.
Specifies a pattern file (otherwise, a default SOLID pattern is used). Try the Unix command % Fpattern '*' to see available pattern files. The file suffix *.pat is not necessary when specifying a pattern file. See the PATTERN command for more information.
Performs all the internal preparations required by program Ferret for a POLYGON plot but does not actually render output. Then PPL commands can then be used to make changes to the plot prior to producing output, to make customizations that are not possible with Ferret command qualifiers. For this command, the syntax for producing the plot is different from the other plot commands. Output is made with the PPL FILLPOL or PPL POLYGON command. See the chapter "Customizing Plots".
Example:
yes? ! use the SHAKEY command with the second argument = 0,
yes? ! to place the colorkey at the top of the plot
yes? POLYGON/SET x_vertices, y_vertices, values
yes? PPL SHAKEY 1,0
yes? PPL FILLPOL !draws the plot (or use PPL POLYGON)
IF the /FILL or /LINE qualifiers are used, specify them AGAIN on the PPL command.
yes? POLYGON/LINE/FILL/SET x_vertices, y_vertices, values
yes? PPL SHAKEY 1,0
yes? PPL POLYOGN/LINE/FILL !draws the plot (or use PPL POLYGON)
Allows user to specify a plot title (enclosed in quotation marks). Without this qualifier Ferret selects a title based on information about the expression(s). To include font change and color_thickness specifications (e.g., @TI@C002) in the title string, it is necessary either to CANCEL MODE ASCII or to include a leading ESC (escape) character. See the chapter "Customizing Plots", section Fonts).
yes? POLYGON/TITLE="title string" x-vertices, y-vertices, values
Causes the horizontal and vertical axes to be interchanged. By default the X axis is drawn horizontally on the plot and the Y and Z axes are drawn vertically. For Y-Z plots the Z data axis is vertical.
Note that plots in the YT and ZT planes have /TRANSFORM applied by default in order to achieve a horizontal T axis. See /HLIMITS (below) for further details. Use /TRANSPOSE manually to reverse this effect.
Specifies the horizontal axis range and tic interval (otherwise, Ferret selects reasonable values).
yes? POLYGON/HLIMITS=lo:hi:increment
The optional "increment" parameter determines tic mark spacing on the axis. If the increment is negative, the axis will be reversed.
This qualifier does not have any impact on the context of the expression being plotted. If data is on a modulo x axis but the arguments of the /HLIMITS qualifier represent a region outside the actual coordinates of the data, only the range including the actual coordinates is shown. Use /X=lo:hi or SET REGION or a context on the variable itself, var[X=lo:hi], to set the context for the expression.
The /HLIMITS and /VLIMITS qualifiers will retain their "horizontal" and "vertical" interpretations in the presence of the /TRANSPOSE qualifier. Thus, the addition of /TRANSPOSE to a plotting command mandates the interchange of "H" and "V" on the limits qualifiers.
Specifies the vertical axis range and tic interval. See /HLIMITS (above)
POLYGON/XLIMITS= /YLIMITS=
Note: XLIMITS and YLIMITS have been deprecated. Please use HLIMITS and VLIMITS instead.
For 1-D plots only. /VLOG sets a vertical log axis, /HLOG sets a horizontal log axis. If /VLIMITS or /HLIMITS is specified, they should be in data units (not log10 axis units). If the axis is a depth axis, an inverse log axis is drawn.
See the notes under PLOT/VLOG/HLOG
Example:
yes? POLYGON/VLOG/VLIMITS=1:1000 xpts, ypts, my_ fcn
POLYGON/AXES[=top,bottom,left,right]
Turns plotting of individual axes off and on. This replaces the use of the "PPL AXSET" command. The syntax is
yes? POLYGON/AXES[=top,bottom,left,right] x-vertices, y-vertices, values
where the arguments are 1 to turn the axis on and 0 to turn it off. For example, this command draws the bottom and left axes only
yes? POLYGON/AXES=0,1,1,0 x-vertices, y-vertices, values
POLYGON/GRATICULE[=line specifiers]
(Introduced in Ferret version 5.6) Turns on graticule lines for the horizontal and vertical axes. These are lines across the plot at the tic marks. /GRATICULE sets both horizontal and vertical lines; to set each separately see /HGRATICULE and /VGRATICULE, below. The syntax is
yes? POLY/GRATICULE[=line or dash,COLOR=,THICKNESS=] x-vertices, y-vertices, values
where the default is a thin, solid black line. The line colors available are Black, Red, Green, Blue, LightBlue, Purple, and White. The thickness codes are 1, 2, or 3 and as for plot lines, thickness=1 is a thin line, thickness=3 is the thickest, and THICK specified with no value defaults to thickness=2. For clarity the arguments to GRAT may be placed in parentheses
yes? POLY/GRAT x-vertices, y-vertices, values ! default settings
yes? POLY/GRAT=(LINE,COLOR=red,THIICK=3) x-vertices, y-vertices, values
yes? POLY/GRAT=(DASH,COLOR=lightblue) x-vertices, y-vertices, values
yes? POLY/FILL/GRAT=(DASH,COLOR=white) x-vertices, y-vertices, values
The above commands make settings for the large tic marks. If small tic marks are being plotted on the axes, we can make settings for them as well using keywords SMALL and LARGE. Place all of the arguments for the /GRAT qualifier in double quotes. Note that the PPL AXNMTC command sets the plotting of small tics.
POLYGON/grat="small(color=red,dash),large(thick,color=green)" {1,2,1}, {2,1,0.5}
POLYGON/HGRATICULE[=line specifiers]/VGRATICULE[=line specifiers]
Turns on graticule lines and sets the line characteristics of the graticule for the horizontal or vertical axis separately. You may specify only one of /HGRAT or /VGRAT if desired. These are lines across the plot at the tic marks. The syntax is
yes? POLYGON/HGRATICULE[=line or dash,COLOR=,THICKNESS=] /VGRATICULE[=line or dash,COLOR=,THICKNESS=] x-vertices, y-vertices, values
where the default is a thin, solid black line. The line colors available are Black, Red, Green, Blue, LightBlue, Purple, and White. The thickness codes are 1, 2, or 3 and as for plot lines, thickness=1 is a thin line, thickness=3 is the thickest, and THICK specified with no value defaults to thickness=2. For clarity the arguments to HGRAT may be placed in parentheses
yes? POLYGON/HGRAT/VGRAT xpts, ypts !equivalent to POLY/GRAT
yes? PLOT/HGRAT=(LINE,COLOR=red,THIICK=3)/VGRAT=(color=green) xpts,ypts
yes? PLOT/HGRAT=(DASH,COLOR=lightblue) xpts, ypts! horizontal only
The above commands make settings for the large tic marks. If small tic marks are being plotted on the axes, we can make settings for them as well using keywords SMALL and LARGE. Place all of the arguments for the /HGRAT qualifier in double quotes. Note that the PPL AXNMTC command sets the plotting of small tics, and that small tics are used by default for many time axes and for logarithmic axes.
yes? POLY/HGRAT="small(color=red,dash),large(thick,color=red)" /VGRAT="large(thick,color=white),small(dash,color=white)" xpts,ypts