Ref Sec24.
POLYGON
/I/J/K/L/M/N /X/Y/Z/T/E/F /OVERLAY /SET_UP /FRAME/D /TRANSPOSE /COORD_AX /NOLABELS /LEVELS /LINE /COLOR /PALETTE /TITLE /THICKNESS /NOAXES /PATTERN /FILL /KEY /NOKEY /HLIMITS /VLIMITS /HGRATICULE/ VGRATICULE /GRATICULE /MODULO /OPACITY
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:
The script polymark.jnl is an easy way to call the polygon command and draw polygons at a set of locations, optionally colored by the values of a variable.
yes? go/help polymark
The script requires an underlying 2D plot, and draws polygons as an overlay. Here is an example taken from the comments at the start of the script:
yes? ! dfine a set of locations for a cruise track, and plot on a map:yes? LET xpts = 180 + 50*COS(2*3.14*I[I=1:50]/60)yes? LET ypts = 15 + 20*SIN(2*3.14*I[I=1:50]/60)yes? LET sst = 25 - ypts + RANDN(ypts)yes? GO basemap x=120:250 Y=25s:65n 20yes? GO polymark polygon/over/key/title="SST" xpts,ypts,sst,ex, 0.5
Example:
This example is taken from 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 the polymark_demo foror examples. Polymark.jnl calls polyshape.jnl to define various shapes . 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/help polyshape.jnl ! lists the pre-defined shapes available to polymark. yes? go polymark.jnl yes? go polymark_demo.jnl 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=/M=/N=/X=/Y=/Z=/T=/E=/F=
Specifies value or range of axis subscripts (I, J, K, L, M, or N), or axis coordinates (X, Y, Z, T, E, or F) 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 is more flexible and we recommend its use rather than this qualifier.
Displays a color key for the palette and color levels used in the color-filled polygon 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.
/KEY options further customize the key. Multiple options may be given, stringing them together with commas, e.g. /KEY=CONT,HORIZ
Chooses a continous color key for the palette used in a color-filled contour plot, without lines separating the colors. This option is particularly good for fill plots having many levels.
Draws a horizontal key just above a color fill plot.
Labels the color key in the colors of the key rather than at the line dividing one color from the next. The contour levels used, whether specified with a /LEVELS qualifier or computed by Ferret, correspond to the labeled color blocks along the colorbar. In other colorbar styles, the levels correspond to the equivalent of contour lines between colors.
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. Note that the /SET_UP qualifier disables the action of /LINE. When using /SET_UP, follow the PPL POLYGON command with a POLYGON/LINE/OVERLAY command to draw the outlines of the polygons.
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
PyFerret Only:
POLYGON/LINE/COLOR=
In PyFerret, the value for the /COLOR= may be specified as a color name or number, as in classic Ferret; or may be of the form (R,G,B) or (R,G,B,A). The values of R, G, B, and A range from zero to 100 and are the percent of red, green, blue, and opacity (alpha channel) for the color. If only R, G, and B are given, an opacity of 100 (opaque) is used.
yes? POLYGON/LINE/COLOR=(100,85,50){1,2,1}, {3,2,1}POLYGON/LINE/THICKNESS=
In PyFerret, the value given to /THICKNESS may be any positive real number.
POLYGON/LINE/OPACITY=
In PyFerret, the /OPACITY option can be used to specify the opacity (alpha channel value) of the colors used in the plot. The opacity given by this option will be used even if a color definition includes an opacity. This may also be set as a fourth argument to the /COLOR qualifier: PLOT/COLOR=(RGBA).
POLGON/MODULO
For curvilinear (3-argument) polygon plots only. Beginning with Ferret v6.85 the /MODULO qualifier for POLYGON plots will draw modulo replications in longitude for curvilinear data in order to fill out the specified extent in the longitude direction. For instance, if the xcoords variable contains longitudes in the range -270:90 we can draw a plot with longitudes 0:360 by using /HLIMITS=0:360/MODULO on the POLYGON command.
POLYGON/NOKEY
Suppresses the drawing of a color key for the palette used in the plot.
POLYGON/NOLABELS
Suppresses all plot labels.
POLYGON/OVERLAY
Causes the indicated POLYGON plot to be overlaid on the existing plot.
POLYGON/PALETTE=
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.
POLYGON/PATTERN=
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. Pattern is available only in classic-ferret interactive or metafile batch modes. It is not available in PyFerret. See the PATTERN command for more information.
POLYGON/SET_UP
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)
POLYGON/TITLE=
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
POLYGON/TRANSPOSE
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.
POLYGON/HLIMITS=
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.
POLYGON/VLIMITS=
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.
POLYGON/HLOG /VLOG
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=] x-vertices, y-vertices, values yes? POLYGON/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(dash),large(thick)"/VGRAT="large(thick),small(dash)" xpts,ypts