General Notes:
In the main Ferret Users Guide, Pyferret-specific information is included using this style of text.
These notes list the ways in which Pyferret command syntax differs from or extends Ferret command syntax. Some commands or qualifiers are available only in PyFerret; other changes are to the arguments that are allowed or expected. In PyFerret with few exceptions, graphics settings may be made as in Ferret. For instance, line colors may be set in Pyferret as in Ferret with a color number or name; or with the new RGB syntax available only in PyFerret.
In PyFerret, for commands with a /COLOR option, colors can be specified as always with a color number or name; or with an (R,G,B) or (R,G,B,A) value.The values of R, G, B, and A go 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.Color palettes used by PyFerret can include an opacity value in each color definition.
In PyFerret, commands with a /COLOR option, as well as command that use color palettes, also have a /OPACITY qualifier.The /OPACITY value assigns the opacity of the color(s) used, even for color definitions that include an opacity value.For instance, /COLOR=red /OPACITY=50 will draw with a semi-transparent red pen.
For commands with a /THICK or /THICKNESS option, in PyFerret the line thickness values can be any positive real number.
Unix Command-line switches
When starting PyFerret, the command line switches -memsize, -nojnl, -noverify, -secure, -server, -version, -script, -help are identical to their behavior in classic Ferret. -help lists the switches and information relevant to PyFerret. -batch i an option in PyFerret is not recommended. If -batch is used, new windows should not be created and the FRAME command should not be used. In addition the -transparent command line option is not recommended. Instead use the -nodisplay option and the FRAME/FILE=<filename> [ /TRANSPARENT ] command.
-gif and -unmapped are recognized by PyFerret; they have become aliases for the -nodisplay switch, listed below.
Command-line switches in PyFerret only:
-nodisplay Do not display to the console; a drawing can be saved using the FRAME command in any of the supported file
formats. The /QUALITY option of SET WINDOW will be ignored when this is specified. The deprecated
command-line options -unmapped and -gif are now aliases of this option.
-quiet: Do not display the startup header.
-python: Start at the Python prompt instead of the Ferret prompt. The ferret prompt can be obtained using 'pyferret.run()'
SET WINDOW
SET WINDOW options in PyFerret
SET WINDOW /ANTIALIAS /NOANTIALIAS
Assigns whether lines are draw with or without anti-aliasing.The default is to use anti-aliasing, which results in lines that appear smoother in raster (such as PNG and JPEG) images.Rarely will one want to turn off anti-aliasing.Only one of these options can be given.
SET WINDOW /COLOR= /OPACITY=
Assigns the color of the background of the window as well as images saved from this window.The opacity of the background color is also used when saving images in formats, such as PNG, that support opactity (the alpha channel).The /TRANSPARENT option to the FRAME command in PyFerret is equivalent to temporarily setting SET WINDOW /OPACITY=0 for just the image being saved by that FRAME command.
SET WINDOW /THICKEN=
Assigns the line thickness scaling factor for the window.Any line thicknesses, even those explicitly specified, are scaled by this factor before being drawn.This allows one to modify the thickness of all lines in a plot to suit ones needs.This value will need to be modified if one significantly changes the actual size of the plot window using the /XINCHES= /YINCHES= PyFerret options to the SET WINDOW command.
SET WINDOW /TEXTPROM=
Assigns the scaling factor for all text in the window.All text sizes, even those explicitly specified, are scaled by this factor before being drawn.This allows one to modify the size of all text in a plot to suit ones needs.Rarely will this option be need as text is automatically adjusted for the window "inch" size.
SET WINDOW /OUTLINE=
When drawing color-filled rectangles and other polygons, this option allows one to specify the thickness of a outline to be drawn around each polygon.The color of the outline will be the same as the fill color.The main purpose of this option is to provide a work-around fix to some PostScript and PDF viewers that show thin white lines in FILL and SHADE plots.Typically only a very small value (0.05) is needed for this fix.If a value of zero is given, these outlines will not be drawn.The default behavior is to not draw these outlines.
SET WINDOW /XPIXELS= /YPIXELS= /ASPECT=
Assigns the default pixels size of the working plot being shown.Using these options is preferred over the use of the /SIZE option.These options scale the displayed plot to the indicated size but do not affect the actual "inch" size of the working plot.Normally these options are used when one wants to see how a raster image of the given size and aspect ratio will look when saved.Only two the these three options can be given.If you only want specify the pixel size of a saved image, use the /XPIXELS /YPIXELS PyFerret options to the FRAME commands.
SET WINDOW /XINCHES= /YINCHES= /ASPECT=
Assigns the actual "inch" size of the working plot being shown.This should only be used by advanced users that want to have an known plot "inch" size when creating the plot,such as for explicit placement of labels relative to the edges of the window.(See the ANNOTATE command for a flexible method for putting labels onto a plot.)Only two the these three options can be given.If you only want specify the inch size of a saved image, use the /XINCHES /YINCHES PyFerret options to the FRAME commands.
SET WINDOW /QUALITY=
Set the quality of the plot.The default, /QUALITY=HIGH should almost always be used.The other option is /QUALITY=DRAFT which can be useful for on-the-fly animations, or may give quicker displayed but lower quality plots when displaying plots remotely over a slow connection.
SET WINDOW /ENGINE=
Set the graphics engine to perform the plotting.This should only be used by very advanced users, or programmers wishing to develop their own PyFerret graphics engine.All standard options are available to the usual users through other commands.Currently the only options are /ENGINE=Cairo (almost equivalent to using the PyFerret -nodisplay command-line option),/ENGINE=PipedViewerPQ (equivalent to SET WINDOW /QUALITY=HIGH), and/ENGINE=PipedImage (equivalent to SET WINDOW /QUALITY=DRAFT).There is one scenario that a normal Ferret user might use this option: if one did not specify -nodisplay on the PyFerret command line but then wants to create and save a plot without displaying it and without restarting PyFerret,one can do this with the /ENGINE=Cairo option to SET WINDOW.
SHOW WINDOW
In PyFerret, the SHOW WINDOW command displays additional values that are options for the SET WINDOW command in PyFerret.For example:
yes? show window OPEN ACTIVE ANTIALIAS QUALITY DISPLAY THICKEN TEXTPROM 1 * YES HIGH YES 1.00 1.00
PPLUS commands
PyFerret recognizes PPL commands used to customize plots. See the section below for more on using existing Ferret scripts in PyFerret.
CONTOUR
CONTOUR options in PyFerret
CONTOUR /COLOR=
In PyFerret, the value for the /COLOR= option may be of the form (R,G,B) or (R,G,B,A).The values of R, G, B, and A go 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.
CONTOUR /OPACITY=
In PyFerret, the /OPACITY qualifier 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.
CONTOUR /THICKNESS=
In PyFerret, the /THICKNESS option can be any positive real number.
PLOT
PLOT options in PyFerret
PLOT /COLOR=
In PyFerret, the value for the /COLOR= option may be of the form (R,G,B) or (R,G,B,A).The values of R, G, B, and A go 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.
PLOT /OPACITY=
In PyFerret, the /OPACITY qualifier 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.
PLOT /THICKNESS=
In PyFerret, the /THICKNESS option can be any positive real number.
POLYGON
POLYGON options in PyFerret
POLYGON /COLOR=
In PyFerret, the value for the /COLOR= option may be of the form (R,G,B) or (R,G,B,A).The values of R, G, B, and A go 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.
POLYGON /OPACITY=
In PyFerret, the /OPACITY qualifier 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.
POLYGON /THICKNESS=
In PyFerret, the /THICKNESS option can be any positive real number.
SHADE
SHADE options in Pyferret
SHADE /COLOR=
In PyFerret, the value for the /COLOR= option may be of the form (R,G,B) or (R,G,B,A).The values of R, G, B, and A go 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.
SHADE /OPACITY=
In PyFerret, The /OPACITY qualifier can be used to specify the opacity (alpha channel value) of the colors in the palette used in the plot.The opacity given by this option will be used even if the color definitions in the palette include opacity values.
VECTOR
VECTOR options in PyFerret
VECTOR /COLOR=
In PyFerret, the value for the /COLOR= option may be of the form (R,G,B) or (R,G,B,A).The values of R, G, B, and A go 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.
VECTOR /OPACITY=
In PyFerret, the /OPACITY qualifier 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.
VECTOR /THICK=
In PyFerret, the /THICKNESS option can be any positive real number.
SET TEXT for fonts and text style
SET TEXT /FONT= /COLOR= /ISIZ= /ITALIC /BOLD [text-group name]
In Pyferret, SET TEXT sets the style for text in labels.
The following text groups are defined. When used as an argument to a SET TEXT command the settings are applied only to that text grouping. If there is no argument, the settings are applied to all text. Note that text group settings are applied only if PyFerret fonts have been first turned on with a general SET TEXT/FONT= command without a text group.
| text-group name | description |
|---|---|
| HTICS | tic mark labels on horizontal axis |
| VTICS | tic mark labels on vertical axis |
| TITLE | main title |
| HLAB | horizontal axis label |
| VLAB | vertical axis label |
| CONTOUR | contour labels |
| LOGO | Ferret logo |
| CBAR | colorbar labels |
| MOVEABLE | moveable (user added) labels |
SET TEXT /FONT=
In PyFerret, the SET TEXT/FONT= option is used to name a font. The fonts available are those available to the Python packages. These will generally be the fonts available on your system where PyFerret is running. The HERSHEY font which draws letters exactly as is done in Ferret, is currently the default.
SET TEXT /COLOR=
In PyFerret, the SET TEXT/COLOR= option makes a color setting. The argument may be a Ferret color setting, or the form (R,G,B) or (R,G,B,A)
If PyFerret encounters a command with text that Ferret-style font or color settings using the @ sign, those settings will be ignored and a NOTE is issued. PyFerret strips off the @XX portion of the label text.
SET TEXT /ISIZ=
In PyFerret, the SET TEXT/ISIZ= option bumps the defult size of all text up or down. The argument is an integer between -4 and 4 to make text smaller or larger.
SET TEXT /ITALIC
In PyFerret, the SET TEXT/ITALIC option sets the text to italic style, if it is available in the currently chosen font.
SET TEXT /BOLD
In PyFerret, the SET TEXT/BOLD option sets the text to bold style, if it is available in the currently chosen font.
SHOW TEXT
In PyFerret, the SHOW TEXT command lists the current text settings, including any group settings that are different from the main defaults.
CANCEL TEXT
In PyFerret, CANCEL TEXT restores text settings to the default.
CANCEL TEXT/[qualifiers] [text-group name]
with a group-name argument as listed above in SET TEXT, restores settings for that group to global settings
CANCEL TEXT/ALL
CANCEL TEXT/ALL or CANCEL TEXT with no arguments resets both the groups and the all of the main settings
FRAME /FILE= /FORMAT=
In PyFerret, the FRAME command is able to save the current plot in a variety of image formats, including PNG, PDF, and SVG.The desired format can be specified by the /FORMAT option.If the /FORMAT option is not given the desired format is guessed from the extension of the filename given by the /FILE option(.png for PNG, .jpg or .jpeg for JPEG, .ps for PostScript, .pdf for PDF, .svg for SVG).Note that GIF output is not supported in PyFerret; however, requests for a GIF image (including giving just a filename with the .gif extension)are automatically converted to PNG output (changing any .gif extension to .png).With PyFerret, the FRAME command can be called at any time, with either displayed or non-displayed plots, and has no effect on the current plot or its state.Thus, for PyFerret we recommend that you not use batch mode, or the -batch option, as the final plot can always be saved at whatever sizes and formats are desired using FRAME commands near the end of your work.
FRAME /ANNOTATE=
Note: experimental The /ANNOTATE option to the FRAME command in PyFerret can be used to add lines of annotations to the top of the saved plot.The height of the saved image will be increased so as to contain the annotations without changing the size of the plot underneath.The value given to the /ANNOTATE option should be a Ferret string variable.Each string in this variable will be start on a new line.Each string will be treated as text formatted using the Pango Markup Language(Note: this link goes to an external site) which is similar to HTML.
FRAME /XPIXELS= /YPIXELS=
The /XPIXELS and /YPIXELS options to the FRAME command in PyFerret allows one to specify the pixel size of raster-type (PNG, JPEG) saved images.The current image is scaled to the desired size when saving it.Only one of these options may be given as the aspect ratio of the plot is always preserved.
FRAME /XINCHES= /YINCHES=
The /XINCHES and /YINCHES options to the FRAME command in PyFerret allows one to specify the inches size of vector-type (PostScript, PDF, SVG) saved images.The current image is scaled to the desired size when saving it.Only one of these options may be given as the aspect ratio of the plot is always preserved.
- DEFINE PYFUNC [ /NAME=alias ] module.name
- Creates an external function using the Python module given by module.name. If /NAME is given, the name of the function will the the name given by alias; otherwise, the name of the functions will be the name of the module.
- EXIT /TOPYTHON
- Exits the Ferret command-line interface and returns to the Python interface. To return to the Ferret command-line interface, enter pyferret.run() at the Python prompt.
CANCEL PYVAR /ALL /DATASET
PyFerret has the ability, using methods in the pyferret Python module, to add data from Python as Ferret data variables.The CANCEL PYVAR command enables one to remove these added variables from Ferret.
Special Characters in labels:
In PyFerret, use HTML-like character syntax to put a wide range of special characters such as Greek characters or mathematical symbols into a label. The syntax is <#nnn> where nnn is the 3- or 4-digit html code or <&code> when a code has been defined.
yes? set text/font=arial yes? plot/title="stress <#964>-x" tau ! Greek tau in the label
Where there is a standard name for a symbol, the name may be used instead, using the syntax <&name>
yes? plot/title="<&Eta> and <&eta>" var ! Greek upper-case and lower-case eta
Subscripts and superscripts in labels
In PyFerret, when using Pyferret fonts, Subscripts and superscripts in labels are made by enclosing the subscript or superscript text in tags.
The tags <sub> </sub> enclosing text in a label will make that portion of the text a subscript; likewise <sup> </sup> will make the enclosed text a superscript.
Converting or Customizing Ferret scripts for PyFerret
Existing Ferret scripts will run under PyFerret with minimal changes. In PyFerret you may wish to change to a Python-library font, and take advantage of enhanced graphics settings and other options discussed in this page.
When Ferret and PyFerret start, there is a pre-defined symbol "program_name" which returns the name of the program running this session.
yes? show symbol program_name PROGRAM_NAME = "Ferret"
or
yes? show symbol program_name PROGRAM_NAME = "PyFerret"
To write scripts that run under both Ferret and PyFerret, syntax that is valid only under one or the other programs can be chosen with, for example,
IF ($program_name"0|PyFerret>1|*>0") THEN SET TEXT/FONT=arial ELSE SET MODE META ENDIf ... Ferret script commands IF ($program_name"0|PyFerret>1|*>0") THEN FRAME/FILE=my_output.pdf ELSE CANCEL MODE META ENDIF
In Ferret, we change Fonts and request color changes in text with text that is set apart with @. In PyFerret, when using the HERSHEY font, all of this works unchanged. When using a python font, these syntax elements are ignored, and a NOTE is issued. Likewise MODE METAFILE is ignored.
yes? show symbol program_name PROGRAM_NAME = "PyFerret" yes? set mode meta *** NOTE: the use of "SET MODE METAFILE" is deprecated; *** NOTE: instead use "FRAME /FILE=... /FORMAT=..." yes? set text/font=arial yes? plot/title="@P2Red title" sst *** NOTE: Non-Hershey fonts: ignoring Hershey pen or font codes
More-detailed text editing will require custom script changes. If special characters are embedded in text for a label, for example by changing to a Greek font or Math symbols font, then that will require a change in the script itself to use PyFerret's special character methods.