Font Control in GrADS

Hershey Fonts
Cairo Fonts
Cairo Emulation of Hershey Fonts
Controlling Font Size
Controlling Font Thickness
Temporary Overrides

Hershey Fonts

GrADS has traditionally used the Hershey vector fonts for all text displays. The Hershey fonts are drawn as a collection of line segments, and can be rotated or scaled (stretched) in the X or Y direction; this makes them extremely flexible for different applications in GrADS. The Hershey fonts are defined in a set of font files, which are part of the GrADS distribution and should be stored in a directory named by the GADDIR environment variable. The font style is controlled with the set font command. Font numbers 0-5 are provided by GrADS (definitions given below); numbers 6-9 are reserved for additional user-defined Hershey font files. The script will display all the characters in a given font set.

font 0 -- Simplex Roman 
font 1 -- Complex Roman
font 2 -- Complex Italic
font 3 -- Complex Greek
font 4 -- Duplex Roman
font 5 -- Triplex Roman

GrADS version 2.1 with the Cairo library enabled uses anti-aliasing to render the graphics when drawing to the X display window and for image output, which will make the Hershey fonts look smoother than they do with version 2.0.

Cairo Fonts

Beginning with GrADS version 2.1, additional fonts may be used through the Cairo graphics library. The integration of Cairo into GrADS provides access to fonts that are generated from polygons, and thus can look much nicer than Hershey fonts. However, these fonts do not behave like the raster screen fonts that are used in the browser or a terminal session, etc. They are still graphically rendered fonts, and how the graphics rendering aligns with the pixels on the screen or the page can affect the quality. This is especially noticeable for small characters or when image resolution is low. In some cases, the traditional stroke-generated Hershey font can produce characters that are easier to read.

Cairo employs the FreeType font library, which supports a number of scalable font formats including TrueType, Type 1, OpenType, X11 PCF, and Windows FNT. Please see for a complete list of font formats that FreeType supports. The fonts that GrADS supports will depend on whether the font files are available on your particular system. On macintosh OSX systems, available font files are generally found in two directories: /Library/Fonts and /System/Library/Fonts/. On unix systems, look in /usr/share/fonts/ and /usr/share/X11/fonts/.

Hershey fonts correspond to single-digit font numbers; Cairo fonts correspond to double-digit font numbers. Font numbers 10-99 are reserved for user-defined fonts, which are specified with the set font command. The user must provide the name of a local font file, including its full path. If the user-specified font file cannot be opened, then the display defaults to a generic sans-serif font. If your build of GrADS is not enabled with the Cairo graphics library, you will get an error message if you use set font to try to set a font number greater than 9.

When using Cairo fonts, you may see this error message pop up: Fontconfig error: Cannot load default config file. This is a file that helps Cairo find fonts, but is only useful on the system where the library was originally built. The default config file is not required, and this message is harmless. The non-portability of font file locations is why it is necessary to specify the full path for a font file when using the set font command.

Cairo Emulation of Hershey Fonts

If you would like to use Cairo fonts but do not know anything about font files on your system or do not want to bother editing the font controls your existing scripts, there is a quick shortcut command for you: 'set hershey off'. This command uses generic Cairo fonts that are reasonable approximations of Hershey fonts 0, 1, 2, 4, and 5. Font 3 is the Greek (symbol) font, and cannot be duplicated with generic controls.

Cairo version of font 0 -- Sans-Serif Regular 
Cairo version of font 1 -- Serif Regular
Cairo version of font 2 -- Monospace Italic
Cairo version of font 4 -- Sans-Serif Bold
Cairo version of font 5 -- Serif Bold

Controlling Font Size

The set strsiz command controls the font size for Hershey and Cairo fonts. Because the fonts are vector-based, you can give different scaling factors for the width and height of the letters and the font will stretch accordingly. If the vertical size is not given with set strsiz, the horizontal size will be used instead.

Controlling Font Thickness

The set string command controls the thickness for Hershey fonts. For Cairo fonts, the thickness is controlled by using a bold version of your font, which will mean using a different font file. When using Cairo fonts, or when 'set hershey off' has been invoked, the thickness setting from set string will be ignored.

Temporary Overrides

To access font numbers 10 and above within strings using the GrADS string escape characters, use the `f escape. The format of this is the backquote, followed by the character "f", followed by a two digit integer number.

Font Override:
To temporarily override the font in a string of text, use the back quote character (`). For Hershey fonts, a back quote followed by a single digit selects that font number for the remainder of the string, or until a new back quote character is encountered. For Cairo fonts, a back quote followed by 'f' and a double-digit number selects that font number for the remainder of the string, or until a new back quote character is encountered. See examples below.

Text Position Override:
It is also possible to use the back quote to change the position of the text, to draw a string above or below the base line for subscripts or superscripts. A back quote followed by the letter a (`a) will draw the subsequent text in the string as a superscript (above normal). A back quote followed by the letter b (`b) will draw the subsequent text in the string as a subscript (below normal). A back quote followed by the letter n (`n) will draw the subsequent text in the string in a normal position, to undo the effects of `a or `b. The use of the back quote to override the font works with the draw string command, contour labels, titles, axis labels, etc. The text position overrides `a, `b, and `n work in both hershey mode and cairo mode.

Degree Symbol:
You can draw a degree symbol by drawing a period with font number 3 (`3.) See examples below.


set font 0
draw string 1.5 1.25 `1use font 2 to `2emphasize `1a particular word
draw string 1.5 2.25 use font 3 for `3greek `0letters
draw string 1.5 3.25 `3p`0r`a2`n = area of a circle
draw string 1.5 4.25 label temperatures in `3.`0C or `3.`0F