Use the TRIUMF / Physica stroke fonts (vaxfont.dat) in matplotlib.
The strokefont package reads the original binary font library and provides StrokeText, a
drop-in matplotlib.text.Text replacement that draws text as pen strokes. Strings use
matplotlib's own mathtext conventions ($\alpha^2$, \frac, \sqrt, ...), and a single call
(strokefont.use()) switches every tick label, axis label, title and legend of an ordinary
matplotlib script. The original PSYM control-character syntax is available as an optional
legacy mode. Output is real vector geometry on every backend (PNG, PDF, SVG, ...).
| Path | Purpose |
|---|---|
src/strokefont/__init__.py |
Public API: StrokeText, use/install, stroke_texts, get_font, ... |
src/strokefont/_font.py |
Binary font-file reader and font cache |
src/strokefont/_symbols.py |
EBCDIC character/symbol mapping and PSYM control characters |
src/strokefont/_markup.py |
Mathtext-subset parser |
src/strokefont/_layout.py |
Glyph layout, line handling and legacy PSYM state machine |
src/strokefont/_text.py |
The StrokeText matplotlib artist |
src/strokefont/_install.py |
Matplotlib text-creation hooks (use, install, stroke_texts) |
examples/ |
Runnable demos and the character-map generator |
tests/ |
Pytest suite (functional tests skip without vaxfont.dat) |
docs/api.md |
Complete API reference for the public package interface |
docs/ |
Rendered examples and the generated character map |
pyproject.toml |
Package metadata and build configuration |
src/strokefont/data/vaxfont.dat |
Optional local font library (git-ignored); bundled into private installs when present (see Licensing) |
You also need vaxfont.dat, the font library. It is not part of this repository (see
Licensing).
Requirements: Python 3.9+, NumPy, matplotlib (developed against 3.11).
Sources. The fonts and the routines that use them come from PHYSICA, the interactive
graphics and data-analysis environment developed at TRIUMF, the Canadian national particle and
nuclear physics laboratory on the UBC campus. The TRIUMF wiki says PHYSICA "was developed at
TRIUMF by Joe Chuma, Fred Jones and other[s]" (the sentence is truncated on the page). The text
below is drawn from the comments in two Fortran files of its gplot graphics library, PFONT.F
(font loading) and PSYM.F (text drawing), and from the wiki page.
What the source code states
- The design is "adapted from UBC PLOT (April 1981)", a plotting package from the University of
British Columbia. The documentation of both routines was written by Richard T. Lee (TRIUMF,
UBC), dated July 1981;
PSYM.Fdescribes itself as "PSYM package (Version 2.0), copyright 1988 R. Lee", and says it "tries to simulate the 'PSYM' of UBC Computer Centre, which is written in ASSEMBLER", in a version meant to be more portable and easier to modify. - The font data are indexed by EBCDIC codes:
PSYM.Fcalls EBCDIC "the native code of the PSYM font structure" and converts ordinary ASCII strings with a routine namedASCEBC. This is why the glyph directory invaxfont.datis in EBCDIC order (Ais 193,ais 129, digits are 240-249). PALPHAwas the original routine for choosing a character set. On 28 Nov 1991 F. W. Jones replaced it withPFONT, which selects a font by name, and keptPALPHAas a compatibility shell.- Maintenance history recorded in the comments: spelling fixes to three font names (Alan
Carruthers, 1983); a faster VMS reader (F. W. Jones, 1984); output of text into Graphics Editor
drawing files and colour encoding (F. W. Jones, 1984-86); the
TRIUMF.OUTLINEfont (R. Lee, 1988); an error exit for illegal ASCII (F. W. Jones, 1990); caching of up to five loaded fonts (C. Kost, 1991); and ports to HP-UX, AIX, g77 on Linux and Absoft (F. W. Jones and J. Chuma, 1995-1998). - The library is called
vaxfont.datbecause it was first a VAX/VMS file (TRIUMF$FONTS:VAXFONT.DAT). On Unix it is found through theTRIUMF_FONTSenvironment variable. In its original form it had three lines per font; the Unix version used here is a 12000-byte-record direct-access file. - The wiki gives some of the people and dates around PHYSICA: Joe Chuma joined TRIUMF in October 1981 and retired in March 2008, and died on 5 August 2011. Extrema, a successor he helped develop, was released as open source in 2006. The wiki page itself does not mention the fonts, PSYM or UBC PLOT.
- PHYSICA page on the TRIUMF DAQ wiki: https://daq00.triumf.ca/DaqWiki/index.php/PHYSICA (source repository, user guide and reference guide are linked from it).
- Legacy PHYSICA home page: https://computing.triumf.ca/legacy/physica/ (suggested as a further history source; I could not retrieve it automatically, so nothing here is taken from it).
- PHYSICA source on Bitbucket: https://bitbucket.org/ttriumfdaq/physica (
PFONT.Fisgplot/src/pfont.FandPSYM.Fisgplot/src/psym.F). - PHYSICA manual: TRIUMF Computing Document TRI-CD-93-01, v1.3, J. L. Chuma, January 1998 (the cover page is the source of the copyright notice quoted under Licensing; the rest of the manual is not used here).
- Hershey vector fonts, for comparison: A. V. Hershey, Calligraphy for Computers, U.S. Naval Weapons Laboratory, 1967.
Install the package from the source tree:
pip install .For development, use an editable install with the test tools:
pip install -e ".[dev]"
pytestThe font library is data, not code, so it is not included in the package. Tell strokefont
where it is, either in code or through the environment:
import strokefont as sf
sf.set_font_file("/path/to/vaxfont.dat")export TRIUMF_FONTS=/path/to/dir/containing/vaxfont.dat # same variable the Fortran code usedTRIUMF_FONTS may name either the directory or the file itself. Without an explicit path,
strokefont looks in strokefont/data/vaxfont.dat, then fonts/vaxfont.dat, then
./vaxfont.dat, mirroring PFONT.F. sf.get_font_file() reports the path that will be used.
For a private installation that should not need TRIUMF_FONTS or set_font_file(), put the
font at src/strokefont/data/vaxfont.dat before installing:
mkdir -p src/strokefont/data
cp /path/to/vaxfont.dat src/strokefont/data/vaxfont.dat
pip install .That file is git-ignored, but the build configuration includes it in the wheel and sdist when it
is present, so it lands at strokefont/data/vaxfont.dat inside the installation. A
vaxfont.dat in the project root is also recognized for regular (non-editable) builds, but the
package-data location above works for editable installs too. Builds still succeed when the file
is absent. Do not commit or redistribute the font without permission (see
Licensing).
The scripts in examples/ write their output to docs/images/ (and docs/charmap.pdf):
| Script | Demonstrates |
|---|---|
examples/demo_install.py |
Drop-in use: an ordinary script (log axes, legend, colour bar) wrapped in sf.use() |
examples/demo.py |
Converting an existing figure with stroke_texts |
examples/demo_legend.py |
Legend with title, multi-line entries, Greek and sub/superscripts |
examples/demo_markup.py |
Mathtext subset, legacy mode, font parameters and several fonts |
examples/demo_charmap.py |
PDF character map of all 43 fonts, one page per font |
python examples/demo_install.py
python examples/demo.py
python examples/demo_legend.py
python examples/demo_markup.py
python examples/demo_charmap.py # optional [vaxfont.dat] [charmap.pdf]When the package is not installed, the examples fall back to importing it from src/.
The complete public API — font loading, StrokeText, install()/use(), stroke_texts(),
symbol mapping and constants — is documented in docs/api.md.
import matplotlib.pyplot as plt
import strokefont as sf
with sf.use("TRIUMF.2"):
fig, ax = plt.subplots()
ax.semilogy(x, y, label=r"$N \propto E^{-3/2}$")
ax.set_xlabel(r"Energy $E$ (MeV)")
ax.legend()
fig.savefig("out.pdf")sf.use() is a context manager; sf.install("TRIUMF.2") and sf.uninstall() do the same
without one. Inside it, everything matplotlib creates as Text becomes StrokeText: tick labels
(including $\mathdefault{10^{n}}$ log ticks and offset text), axis labels, titles, ax.text,
fig.text, suptitle, legends and colour-bar labels. Annotations (ax.annotate) keep the normal
font. Only artists created while installed are affected.
Both functions accept the same global rendering defaults as StrokeText:
sf.install("TRIUMF.2", linewidth=1.0, capheight=0.70, params={"SHGT": 0.8})
with sf.use("ROMAN.2", "plain", linewidth=0.8):
...The signature is install(font=None, markup=None, *, linewidth=None, capheight=None, params=None); use() takes the same arguments. These values apply to artists created while
installed, and explicit arguments on an individual StrokeText still take precedence. use()
restores all previous defaults when the block exits.
StrokeText accepts the usual Text arguments: fontsize, color, alpha, ha, va,
rotation, rotation_mode, multialignment, linespacing, transform, clip_on, zorder,
parse_math, and so on. fontfamily, fontweight and fontstyle are ignored, since the font is
chosen by font=.
ax.add_artist(sf.StrokeText(0.5, 0.5, r"decay $e^{-t/\tau}$", font="ROMAN.2", fontsize=14,
transform=ax.transAxes, ha="center", va="center"))| Extra argument | Meaning | Default |
|---|---|---|
font |
One of the 43 font names (below) | "TRIUMF.2" (StrokeText.default_font) |
linewidth |
Pen width in points | 0.09 * fontsize (StrokeText.default_linewidth if set) |
capheight |
Cap height as a fraction of fontsize |
0.72 (StrokeText.default_capheight) |
markup |
"mathtext", "legacy" or "plain" |
"mathtext" (StrokeText.default_markup) |
params |
PSALPH-style font parameter overrides (below) | none (StrokeText.default_params if set) |
Sizes are normalised so that the capital-letter height is capheight * fontsize in every font,
so fonts look comparably sized even though their internal grids range from 16 to 246 units. Change
the weight of a font with linewidth.
fig.canvas.draw() # make sure tick labels exist
sf.stroke_texts(fig, "TRIUMF.2") # figure, axes, legend or single Text objectsConvert after the legend exists and after the ticks exist; ticks created later (for example by
zooming) use normal text. For that case use sf.use() instead.
As in matplotlib, a string is plain text unless it contains an even number of unescaped $; the
parts between $...$ are then math, and \$ is a literal dollar sign. parse_math=False turns
parsing off. Inside math:
| Syntax | Result |
|---|---|
x^2, x^{ab}, x_i, x_{ab}, x_i^2 |
super/subscripts (nest; both together are stacked) |
{...} |
grouping |
\alpha \Omega \pm \infty \le ... |
symbols from the table below, also Unicode α ± ≤ ∞ ° |
\frac{a}{b} |
stacked fraction |
\sqrt{x} |
radical drawn over the argument |
\sin \cos \log ... |
function names, upright |
\mathrm{..} \mathit{..} \mathdefault{..} \text{..} ... |
accepted; the style is ignored (one font per object) |
\, \: \; \ \! \quad \qquad |
spaces |
\left( \right) |
accepted; delimiters are not stretched |
\{ \} \$ \% \& \# \_ |
literal characters |
Operators (= < > + - \pm \times ...) get TeX-like spacing; spaces typed in math are ignored.
Script positions use the font's own PSUP, PSUB and SHGT header values, exactly as the
original PSYM routine did.
markup="legacy" uses the original PSYM control characters (PSYM.F, ASCII input). There is no
$ or ^ syntax in this mode; those characters are drawn literally.
| Constant | Character | Effect (original name) |
|---|---|---|
sf.UP |
\t (0x09) |
superscript; at a higher level, the next higher superscript level |
sf.DOWN |
\x01 |
subscript; from a superscript, back down one level |
sf.UPSIZE |
\x03 |
up, and the size always changes (each level smaller) |
sf.DOWNSIZE |
\x02 |
down, and the size always changes |
sf.BACKSPACE |
\b (0x08) |
one-character backspace (further if letterspacing is on) |
\n |
carriage return (matplotlib line breaking is used) |
sf.StrokeText(0, 0, "x" + sf.UP + "2" + sf.DOWN + " y" + sf.DOWN + "i" + sf.UP,
markup="legacy", fontsize=14)The state machine is a literal port of PSYM.F, including its asymmetries between the first and
higher script levels. Differences from the Fortran: size is set by fontsize and capheight,
not by HEIGHT and SSCAL; line spacing comes from matplotlib's linespacing; state is not
carried across line breaks. The old PSMLEN (string length) is text.get_window_extent().
params= takes the parameter names of the original PSALPH call, applied to this object
only (e.g. params={"SHGT": 0.8, "LSPC": 4}):
| Name | Parameter | Name | Parameter |
|---|---|---|---|
HSPC |
HSPAC fixed advance (letterspacing off) |
ANGL |
slant of the Y axis, degrees (-90 < ANGL < 90) |
VSPC |
VSPAC line spacing (not used; see linespacing) |
LTRS |
letterspacing on/off |
SUPS |
PSUP superscript reference point (x, y) |
REFP |
REF reference point (x, y) |
SUBS |
PSUB subscript reference point (x, y) |
LSPC |
LSPAC letterspacing constant |
SHGT |
script height / character height | SCAL |
horizontal scale |
HSCL |
SSCAL height scale (no effect; see capheight) |
Greek letters and math symbols occupy EBCDIC slots that letters and digits do not use. They are
present in TRIUMF.1 and TRIUMF.2, which I checked on the contact sheet; other fonts may
differ, so consult docs/charmap.pdf to see exactly what each font contains.
- Greek capitals:
\Gamma \Delta \Theta \Lambda \Xi \Upsilon \Phi \Psi \Omega \Sigma \Pi - Greek lower case:
\alpha \beta \gamma \delta \epsilon \zeta \eta \theta \vartheta \iota \kappa \lambda \mu \nu \xi \omicron \pi \rho \sigma \tau \upsilon \phi \varphi \chi \psi \omega \varepsilon - Relations and operators:
\le \ge \ne \approx \equiv \sim \ll \gg \propto \pm \mp \times \div \cdot \in \subset \supset \cup \cap \vee \wedge \oplus \perp \parallel \angle - Other:
\forall \exists \neg \therefore \infty \int \oint \partial \nabla \sqrt \aleph \hbar \dagger \degree \section \langle \rangle - Arrows:
\rightarrow \leftarrow \uparrow \downarrow \Rightarrow(also\to)
The table is strokefont.SYMBOLS (name to EBCDIC code); extend it for other fonts.
strokefont.FONT_NAMES lists the 43 fonts in library order:
STANDARD HELVETICA.1 GOTHIC.ENGLISH ROMAN.3 ITALIC.3 GREEK.2A ITALIC.2A ROMAN.2A
SANSERIF.2 GREEK.1 SANSERIF.1 SCRIPT.1 GOTHIC.FRAKTUR GOTHIC.ITALIAN SCRIPT.2
ROMAN.2 ITALIC.2 GREEK.2 CYRILLIC.2 SANSERIF.CART GREEK.CART HIRAGANA KATAKANA
KANJI1 ... KANJI5 OLDALPH TRIUMF.1 TRIUMF.2 TSAN ROMAN.FUTURA ROMAN.SERIF
ROMAN.FASHON ROMAN.LOGO1 ROMAN.SWISSL ROMAN.SWISSM ROMAN.SWISSB SPECIAL MATH
HEBREW TRIUMF.OUTLINE
The names are those in PFONT.F; matching is case-insensitive. (The header stored inside the file
reads MATHEMATICAL for MATH and TRMF:TRIUMF.1 / TRMF:TRIUMF.2 for the two TRIUMF fonts.)
Only the Latin and TRIUMF-style fonts have the ASCII and symbol mapping that the markup relies
on. The Kanji, Kana, Hebrew and Cyrillic fonts load and draw, but their characters can only be
reached through their code slots, which the markup does not yet expose. Generate the complete map
with python examples/demo_charmap.py vaxfont.dat docs/charmap.pdf.
f = sf.get_font("ROMAN.2") # optionally get_font(name, params={...})
width, verts, codes = f.glyph(193) # EBCDIC code of "A"
# verts: (N, 2) grid coordinates; codes: matplotlib Path codes (MOVETO / LINETO)
f.grid, f.refx, f.refy, f.lspac, f.letterspacing, f.psup, f.psub, f.shgt, f.angl, f.definedEach font occupies 24000 bytes (two 12000-byte records); the file is 43 x 24000 = 1,032,000
bytes. Fields as documented in PFONT.F:
| Offset | Content |
|---|---|
| 0-179 | ASCII header: SIZE GRID HSPAC VSPAC PSUPx PSUPy PSUBx PSUBy (8 x I8), SHGT SCAL SSCAL ANGL (4 x F16.6), REFx REFy SWITCH LSPAC (4 x I8), 4 blanks, 16-character name |
| 180-691 | Directory: 256 little-endian 16-bit offsets into the glyph data, indexed by EBCDIC code |
| 692- | Glyph data (SIZE bytes): per glyph npoints, width, then the points |
Points are on a GRID x GRID lattice with the origin at the lower left. For GRID <= 16 each
point is one byte (high nibble x, low nibble y) and the pen-up marker is (15,15). For larger
grids each point is two bytes (x, y) and the marker is (255,255). Consecutive points are joined by
straight lines. A glyph's width byte is the x coordinate of its right edge.
Notes from PSYM.F and from reconstructing the format:
- Offset 0 is a blank glyph, and undefined characters point at it.
- A character is drawn with its
REFpoint at the pen position. The pen then advances bywidth + LSPACgrid units if letterspacing is on (high bit ofSWITCH), otherwise byGRID + HSPAC. - A superscript (subscript) is drawn at
SHGTtimes the size with its grid origin placed at thePSUP(PSUB) point of the preceding character's grid; leaving the script undoes the offset. - The cap height is not stored;
strokefontmeasures it from the glyph forH.
- Mathtext is a subset: one font per object (no
\mathbf/\mathitswitching), basic\fracand\sqrt, no stretchy delimiters, matrices or accents. install()redirects the creation sites in matplotlib's modules; it affects artists created afterwards, and modules imported later keep normal text.Annotationtext keeps the normal font.- No mixing of fonts within one string; create separate
StrokeTextobjects instead. - Stroke fonts have no outline, so
fontweighthas no meaning here; uselinewidth. Very thin fonts at small sizes work best withlinewidthraised a little. - Some fonts are decorative or have overlapping strokes (for example
SCRIPT.2).
This repository contains only the code that reads and draws the fonts; it does not include
vaxfont.dat or any of the original PHYSICA/gplot sources.
The Python code and documentation are released under the BSD 3-Clause License; see
LICENSE. This licence does not apply to vaxfont.dat, which is not part of the
project and remains subject to whatever terms TRIUMF may set.
The only licensing statement found so far is on the cover page of the PHYSICA manual: a TRIUMF
Computing Document (4004 Wesbrook Mall, Vancouver, B.C., Canada V6T 2A3), by J. L. Chuma,
January 1998, document number TRI-CD-93-01, version 1.3, marked "Copyright
1993,1994,1995,1996,1997,1998 - All rights are reserved". That is a copyright notice on the
manual. It grants no permission, and it does not say what terms apply to the software or to the
font data, so the status of vaxfont.dat remains unknown (the wiki page states no licence
either). Until that is clarified, do not redistribute the font file or the Fortran sources with
this code, and contact TRIUMF before doing so.
The Python code in this repository is an independent reimplementation of the file format and
drawing rules described in the Fortran comments; it contains no text or data copied from those
sources, except the font names and the small symbol and character-code tables needed to read the
file. The package metadata declares BSD-3-Clause, and the wheel/sdist builds exclude
vaxfont.dat and the generated documentation images by default.
