PyFerret Known Issues and Release Notes

Previous

The following describes changes in behavior, known issues, desired enhancements, and release notes for PyFerret. The known issues listed are those specific to PyFerret and does not include issues with the Ferret engine contained within PyFerret.

Changes in behavior

Saved plot sizes can now be specified directly.

The pixel size of saved raster (PNG, JPEG) plots can be specified directly using the /XPIXEL or /YPIXEL options to the FRAME command. The inch size of saved vector (PDF, PS, SVG) plots can be specified directly using the /XINCH or /YINCH command to the FRAME command. The plot to be saved is just scaled to the desired size when written to file. The aspect ratio will be maintained, and all parts of the plot, including line thickness, are scaled.
The /XPIXEL and /YPIXEL options to the SET WINDOW command are only used to set the window aspect ratio and set the default values of /XPIXEL and /YPIXEL for the FRAME command.So normally these options to SET WINDOW are only useful for creating a raster plot of some exact pixel dimensions, or for creating a plot window with an appropriate aspect ratio.
The /SIZE option to SET WINDOW is deprecated in PyFerret, and is only used to assign /XPIXEL and /YPIXEL values in the SET WINDOW command.

Plot inch size can now be specified.

Users that wish to control the values of PPL$WIDTH and PPL$HEIGHT, the "canvas" inch size of a plot, can now do so using the /XINCH and /YINCH options (or one of these options and the /ASPECT option) to the SET WINDOW Ferret command. The default sizes of text are adjusted with these options, but the default thickness of lines do not.One can use the /THICKEN option to SET WINDOW to scale the thickness of all lines as desired.
Most users should not need to use the SET WINDOW /XINCH /YINCH options. To obtain a saved vector plot of a given inch size, one should just use the /XINCH or /YINCH option to the FRAME command.

Saving images in any of the supported format

One can save the plot in any of the supported formats at any time using the FRAME /FILE /FORMAT Ferret command.If the /FORMAT option is not specified, the format for the image file is guessed from the filename extension (for example, PNG for .png, PostScript for .ps, PDF for .pdf).
The use of the -batch command-line option, and the SET MODE METAFILE and SET GIFFILE Ferret commands are deprecated in PyFerret.Instead, one should just save the plot using the FRAME Ferret command in the appropriate formatat the appropriate time.

GIF files are no longer created

PyFerret does not produce GIF image files since the underlying graphics engines do not support creating images in GIF format. To support existing scripts, anytime a GIF image is requested, a PNG image will be saved with the same file name except with the .png extension instead of .gif

GKS metafiles (.plt files) are no longer created

PyFerret does not produce GKS metafiles since the underlying graphics engines do not support creating GKS metafiles. To support existing scripts, anytime a GKS metafile is requested, a PostScript file will be saved with the same file name except with the .ps extension instead of .plt

Changing a color does not change previously drawn items

In Ferret, the XGKS graphics engine uses color values in a color table when drawing and when refreshing a displayed image. The PPL COLOR command updates the values for a color table entry. So this command modifies the color of all items drawn that use the modified color table entry, including items drawn prior to the PPL COLOR command.
In PyFerret, the graphics engines use the color values in the color table only at the time of initial drawing of an item. Thus the PPL COLOR command will only affect the color of items drawn after the command. All items drawn prior to the PPL COLOR command will remain unchanged.

Known Issues

PLOT+ patterns are not supported

PLOT+ pattern files are not yet supported by the new graphics engines. Thus /pattern qualifiers on Ferret plotting commands usually will result in an error.

Shared time axis not always recognized with putdata and put functions

When bringing Python data into Ferret using the PyFerret put or putdata functions, sometimes a time axis in common with an existing time axis in Ferret is not recognized. This is most likely due to trying to map times derived from the six integer array values (year, month, day, hour, minute, second) to a single floating point time value.

A "metafile" name with a .plt extension can sometimes cause errors

Setting the "metafile" name (using the SET MODE METAFILE:filename Ferret command) to a filename with the .plt extension can sometimes cause errors. PyFerret should automatically convert to using PostScript format in these case, using the filename with a .ps extension instead of the .plt extension. But under some circumstances this process fails.Note, however, that use of -batch and SET MODE METAFILE are now deprecated as images can be saved at any time using the FRAME /FILE command.

Color name "white" not always white

If the number of line colors (SET MODE LINECOLORS) is left at the default value of six, the color name white does not give a white color. If the number of line colors is increased to seven of more, then the color name white does give a white color, which is pen (color) number seven. Note that the default pen (color) numbers beyond six have changed to go from white to darker shades of gray.

Incomplete display of the plot after changing window size or aspect ratio.

In some rare instances the plot is not completely displayed, or is not scaled appropriately to fit the displayed window.This has been seen sometimes with the first window displayed or sometimes when the aspect ratio changes.However, if one saves the plot to file, the complete plot is saved.The complete and correctly scaled plot will be show if one starts to adjusts the size of the displayed window using the mouse on the window frame.

The Ferret "where" function does not work properly in PyFerret.

The graphics input function, which returns coordinates of a mouse-click, has yet to be implemented for the new graphics engines in PyFerret. As a result, the Ferret "where" function returns random coordinates without any interaction with the displayed window.

Darker lines and polygons in shade and fill plots when using translucent colors

Some darker colored lines, and even some darker colored polygons, will appear in shade and fill plots when using translucent colors.

The get and getdata methods do not record the dataset

The get and getdata methods need to return the dataset ID forthe data. For getdata, this would be the value of the "dset" key. TheID should be the filename of the dataset from which the came from.

When adding a Python-defined data variable (put and putdata), an existing matching time axis may not be recognized.

Seconds are currently integer values and thus can causeslight differences in time values. Seconds need to be saved as afloating-point value.

SHOW DATA for a data variable added from Python sometimes does not display the grid correctly

The grid shown for a data variable added from Python is sometimes notdisplayed correctly in the SHOW DATA Ferret command, although thegrid is correct when displayed using the SHOW GRID Ferret command.

FRAME /FILE=... in unsupported formats does not immediately give back an error.

An error message is generated, but not displayed until the next Ferret command is given.

Recently discovered issues are listed here.

Desired Enhancements

Support patterns or some hatching

The *.pat pattern files, as used in FILL /PATTERN=... are not supported.
Alternatively (preferably) support hatching as this is used to mark areas where another color is not possible (as in black-and-white) or where the user wants the underlying color to show through.

PyFerret python method to get a Ferret symbol value

Create a method in PyFerret to return the value of a Ferret symbol as a Python string.

Enable PyFerret to work with commands piped to it

Piping output from a command into PyFerret, such as cat my.jnl | pyferret does not work.

Recognize embedded newlines in a pyferret.run command

Commands need to either separated with semicolons or entered as separated pyferret.run commands. To simplify using a multiline (triple-quoted) Python string as a source of commands, embedded newlinesshould also be recognized for separating commands.

Create multipage PS, PDF, SVG

Allow the PyFerret user to create multi-page PS, PDF, and SVG output files with the FRAME command; possibly by adding /multi, /append, and /close options to the frame command.

Provide layers (groups) in graphics output files where supported (SVG)

The SVG format provides support for grouping sets of drawingcommands. (The <g> XML tag.) This presumably turns into layersin inkscape, which are quite useful for editing graphics. So it wouldbe very useful if PyFerret would produce SVG files that separatedifferent parts of the drawing into layers (e.g., separate the axesfrom fills and shades, and maybe separate different fills and shadessuch as shade sst from go fland.)

Create get and put methods for strings in PyFerret

Generate PyFerret methods for getting and putting (arrays of)strings from/to Ferret. Maybe have getstring/putstring for a singlestring (no axes), putstringarray/getstringarray for arrays of strings(with axes).

PyFerret confirmation for Help->Exit in graphics window

Add a confirmation dialog to Help -> Exit from the menubar, explaining that this should only be used when PyFerret hascrashed or somehow shutdown without closing the window. Exiting awindow that PyFerret thinks is still viable will cause issues - most likely a crash.

Scan for +-Inf in Python external function results, converting to the missing value

Release Notes for PyFerret 1.2.0

Native fonts can be used for text

Text in PyFerret can now be drawn using fonts provided by your system.The SET TEXT Ferret command can be used to change the default font, color, and size of text drawn by PyFerret.When one of the system fonts are used in a plot, the text will be saved as character glyphs or text when the plot is saved to file.The font in traditional Ferret is still accessible by using SET TEXT /FONT=HERSHEY, but just as in traditional ferret,any text drawn in this font becomes just more drawn lines in the plot when saved to file.
When using native fonts, an HTML-like mark-up (style specification) language is used for special characters, superscripts, and subscripts.See PyFerret: embedding Special Characters in labels for more information.When using the Hershey font from traditional Ferret, the mark-up language used in traditional Ferret is still used.

Fuzzy PNG plots

When using the "-nodisplay" command-line option, lines in PNG plots were "fuzzy". This was especially noticeable in small PNG plots.This is actually a known issue in older versions of the Cairo library, including the version provided by RHEL6, when using the recording surface to store a plot.This is now fixed in PyFerret by statically linking in a private copy of the latest cairo library.PyFerret will use this private copy of the cairo library for its own use, but does not expose it to other programs (such as Qt) which may break using an unexpected version of the cairo library.

Thin white lines in plots

The appearance of this white lines in PostScript and PDF files is actually a known issue with ghostscript, the standard program (possibly via the evince program) used to display these files in Linux operating systems. Examining the PDFs with Acrobat Reader does not show the white lines problem.The ghostscript user's manual http://ghostscript.com/doc/8.63/Use.htm, under Rendering parameters, recommends rendering the file again with the -dGraphicsAlphaBits=1 command-line option to fix the display of the plot.
To work around this problem, the option /OUTLINE= was added to the Ferret command SET WINDOW.This option, if not zero, specifies the thickness of an outline to be drawn around every polygon that is drawn.Using this option with a very small value causes the polygons to slightly overlap.If using opaque colors, a small overlap should not be noticeable and prevents the white lines from appearing.

PyFerret commands added to Ferret documentation

Command options supported by PyFerret, but not Ferret, have been added to the standard Ferret documentation.These PyFerret-only options are clearly marked as not being available in standard Ferret.

Release Notes for PyFerret 1.0.2

/SIZE option to SET WINDOW just scales the displayed image

The behavior of the /SIZE option to SET WINDOW was changed so thatis just scales the displayed image (modifies the pixel size of the image). This causes line thickness to also be scaled, but line thickness scaling can be adjusted using the /THICKEN option to SET WINDOW.The previous behavior of adjusting the "inch" size caused severe compatibility issueswith scripts relying on traditional Ferret's behavior of having a fixed "inch" size for a plot at a given aspect ratio.

Release Notes for PyFerret 1.0.0

Graphics quality and other graphics options are part of the SET WINDOW command

SET GRAPHICS has been removed and is replaced by SET WINDOW /QUALITY=.... The anti-alias control also part of SET WINDOW. The default is HIGH quality graphics with anti-aliasing.Unmapped, high-quality graphics now specified using the -nodisplay command line option.

Save file in any format at any time with -nodisplay

Images can be saved in any of the supported formats (PNG, PS, PDF, SVG) at anytime during the session using the FRAME Ferret command, reagardless of whether the graphics are displayed or not (if the -nodisplay command-line option is given). An image can also be saved in multiple formats by repeated use of the FRAME command.

Option to set color and transparency (opacity) of graphics background

Color and opacity of the background can be specified with the SET WINDOW /COLOR=... /OPACITY=... options. This background color is used for both the displayed and saved image.

Global line thickness scaling factor; more line thickness control in new line specifications

The SET WINDOW /THICKEN=... allows setting of a global line thickness scaling factor.Line drawing commands also support a /THICK=... option that allows specifying line thickness(in points; 1/72 of an inch) as a floating point value. The value specified will be subject to scaling by the global line thickness scaling factor.

Dynamic resizing of the displayed image

The displayed image now resizes to fill the area inside the display window. The dialog from the menu item Scene -> Scale allows one to disable or re-enable this behavior.

Symbol to differentiate PyFerret from traditional Ferret

The Ferret symbol PROGRAM_NAME was added. The value is Ferret in Ferret, PyFerret in PyFerret.

Enable transparency value in color specifications (in particular, for shading overlay)

Opacity in all color specifications is supported. The /COLOR= option and colors in palettessupport (%red, %green, %blue, %opacity) quartets. The /OPACITY= option overrideopacity in colors specified elsewhere (such as in a named color or in a standard color palette).

Fixed: Inside a viewport, plots overlay instead of replace previous plot

Clearing and replotting only within a viewport (such as from set view ul) is now properly supported.

Fixed: White lines in shade and fill plots

The problem with white lines showing up primarily in PS and PDF out has (mostly) been fixed.The PDFs produced from high-quality displayed graphics plots can still show some of these white lines, although they are thinner than before. The PDFs produced from -nodisplay plots do nothave these lines. Note, however, that with translucent colors, darker lines now show up.

Fixed: Window displayed when using pyferret -unmapped

Although the -unmapped command-line option is suppose toprevent the display of any graphics, setting the graphics quality tohigh or draft caused PyFerret to switch to that graphics mode and display windows.This has now been fixed and any /QUALITY options are ignored whenPyFerret is run with the -nodisplay (or -unmapped) command-line option.

Fixed: CTRL-C exits PyFerret

When PyFerret is run using the pyferret.csh script, CTRL-C will exit the script. This is an issue with tcsh and not PyFerret. To circumvent this bug in tcsh, theBourne-shell script pyferret.sh is always used for the pyferret link, and thus is the script run (even in C-shell environments) when invoking pyferret.The pyferret.csh script should only be used if you wish to source this script from a C-shell.

Reverted: CTRL-C while reading a NetCDF variable can cause PyFerret to crash later

When using pyferret.sh (see previous issue), entering CTRL-C while Ferret is reading data using NetCDF successfully stopped the reading of the variable. However, the next use of data from the that NetCDF data set would cause a crash. After much discussion, it was decidedto return to the behavior where CTRL-C will not stop the reading of data using NetCDF.

Fixed: CTRL-C can cause the graphics display to crash

When using displayed graphics, entering CTRL-C could sometimes cause the graphics display program to exit. The graphics display program now ignores any CTRL-C that might leak tothe graphics display.

Fixed: Graphics not updated in pyferret.run semicolon-separated commands

Removed the deferral of updating graphics.

Fixed: FRAME /FILE=... in a script does not have complete graphics

Removed the deferral of updating graphics.

Show graphics details (quality, anti-alias) as part of SHOW WINDOW

Release Notes for PyFerret 0.0.9

PyFerret uses double-precision floating-point values for all calculations and data arrays.

PyFerret has been updated to use Ferret 6.8.2 as its Ferret engine. One major enhancement to Ferret 6.8.2 was the use of double-precision floating-point values for all calculations and data arrays. See these Ferret release notes for more details about this enhancement in Ferret.
Because of this change, NumPy numeric data arrays used by PyFerret now have the type NumPy float64 (or Python float). If your Python code explicitly creates NumPy float32 arrays that are given to PyFerret, the data type will need to be changed to float64. For most users, however, no changes to your Python code will be required.

PyFerret implements a six-dimensional grid.

This also is a result of the update of PyFerret to use Ferret 6.8.2 as its Ferret engine. This Ferret enhancement provides standard axes for ensembles as well as forecasts in a data array. See these Ferret release notes for more details about this enhancement in Ferret.
Because of this change, NumPy numeric data arrays returned by PyFerret now have six dimensions instead of four. As before, the NumPy array shape value for both singleton and normal (orthogonal, unused) axes is one. The additional axes can be used as desired in Ferret external functions written in Python. If not specified, the usual default values (such as the result axis is inherited from the arguments) will apply to the two additional axes.

Ferret Fortran external functions work properly.

Ferret Fortran external functions are created from Fortran source files that are compiled and linked to create a shared-object (.so) library file. These .so library files are contained in a directory listed in the $FER_EXTERNAL_FUNCTIONS environment variable. To work with PyFerret, these external functions will need to be rebuilt, not only to use double-precision (possibly six-dimensional) arrays, but also to use the PyFerret shared-object library to resolve calls to Ferret utility functions (the ef_... functions). See the Ferret Fortran external functions section of the PyFerret documentation for more information.

Command-line options -unmapped, -gif, -batch turn on anti-aliasing

When the pyferret script is called with either the -unmapped, -gif, or -batch command-line options, anti-aliasing is turned on by default to be consistent with the Ferret command SET GRAPHICS UNMAPPED.

Filenames completed using the TAB key

At the Ferret prompt in PyFerret, the TAB key will complete a partial file name or provide a list of matching file names if there is more than one. At the Python prompt, however, whatever completion method was used with the readline module will still be used (by default, the method in rlcompleter, which provides a list of matching Python variables and methods).

The initialization script $PYTHONSTARTUP is explicitly read

When Python starts under normal conditions, Python executes the commands given in an initialization script named by the environment variable PYTHONSTARTUP. When using the pyferret shell scripts, however, this initialization is not automatically performed by Python (because of the use of the -i Python command-line option).
To provide behavior consistent with a normal start-up of Python, the pyferret.init method (which is used by the pyferret shell scripts) now executes the commands in the $PYTHONSTARTUP initialization script unless -secure is given in the arguments (given as a command-line option).

PPL COLOR command works

The PPL COLOR command now works as expected, changing the color value used for a color number in subsequent drawing commands.However, see the note above about the change in behavior of this command in PyFerret.

Images automatically saved have an opaque white background by default

Images automatically saved from using the -batch filename command-line option or the SET MODE METAFILE:filename Ferret command now have an opaque white background. Use the -transparent command-line option to save the image with a transparent background (if transparency is supported by the image format used).

The window title of the default first window is properly assigned

The default first window displayed now has the standard window title of FERRET_(windownumber)_(datestamp).

Python modules gcircle and eofanalysis provided

The gcircle module provides some simple functions, using longitudes and latitudes, working with great circles on a sphere.
The eofanalysis module provides an EOFAnalysis class for performing empirical orthogonal function (EOF) analysis of space-time data, similar to that provided in the Ferret eof... functions. The EOFAnalysis class also provides methods for obtaining the explained data values from a truncated sum of EOFs and time amplitude function (TAF) products, of from a single EOF and TAF product.
Both these modules are pure-Python packages that use NumPy methods to provide efficient numerical array processing. See the Python help for these modules, or view the Python source files under the $FER_DIR/lib/python2.x/site-packages (where x is 6 or 7) directory for more information.