Usage

Installation

Ziamath can be installed using pip:

pip install ziamath

Ziamath depends only on two pure-Python packages: Ziafont, for reading TTF/OTF font files, and latex2mathml for parsing Latex math expressions.

Drawing Equations

The ziamath.zmath.Math class processes and draws a given MathML <math> element. Set up a Math object by providing a MathML string:

import ziamath as zm

eqn = zm.Math('''
              <mrow>
                  <msup>
                      <mi>x</mi>
                      <mn>2</mn>
                  </msup>
              </mrow>
              ''')
eqn

In Jupyter notebooks, the Math instance will be rendered in the cell’s output. The raw SVG is obtained using ziamath.zmath.Math.svg(), for SVG as a string:

eqn.svg()[:80]  # Only show first 80 characters...

'<svg xmlns="http://www.w3.org/2000/svg" width="23.907" height="22.153" viewBox="'

or ziamath.zmath.Math.svgxml() for the SVG in an XML ElementTree.

eqn.svgxml()

<Element 'svg' at 0x7731d2d9aea0>

The Math class takes optional parameters for font file name and font size. The font file must be math-enabled, with an embedded ‘MATH’ table.

Drawing Latex

To render a math expression in Latex format, create the Math object using ziamath.zmath.Latex():

zm.Latex(r'c = \pm \sqrt{a^2 + b^2}')

The Latex class inherits from the Math class. Be sure to use raw strings (prefixed with an r) so that slashes for Latex commands are interpreted as slashes and not string escape characters.

Display Mode and Inline Mode

Latex math is drawn in display (block) mode by default. To render inline (text) mode, set the inline parameter to True.

zm.Latex(r'\sum_a^b', inline=False)  # Default display mode

zm.Latex(r'\sum_a^b', inline=True)  # Inline mode

Equation Numbering

Ziamath supports numbering of equations using either the LaTeX tag command, a number label argument to Math or Latex, or automatic numbering.

Equation numbers are right-aligned to the edge of the “page” with the equation centered on the page. The page or column width is defined in the config option, whose value may be defined using the common Latex units in, cm, pt, etc.:

zm.config.numbering.columnwidth = '6.5in'

Use the number parameter to add an equation number:

zm.Latex(r'y = mx + b', number='1.1')

In LaTeX, the tag{} command may also be used with any LaTeX code embedded:

zm.Latex(r'y = mx + b \tag{5 \star}')

Alternatively, equations may be automatially numbered sequentially:

zm.config.numbering.autonumber = True
zm.Latex('a = 1')

zm.Latex('b = 2')

Reset the equation number with ziamath.zmath.reset_numbering()

zm.reset_numbering(10)
zm.Latex('c = a + b')

Alternate number formats are specified using the config options. The format is a Python format-string. For example, to use square brackets and numbering preceeded with a chapter number:

zm.config.numbering.format = '[1.{0}]'
zm.Latex('x + y + z')

More complex numbering schemes may be created by specifying a format_func callable that takes the equation number as input and returns a formatted string. For example, to use letters as the equation numbers:

zm.reset_numbering(1)
zm.config.numbering.format_func = lambda i: '({})'.format(chr(ord('A')+i-1))
zm.Latex('a^2 + b^2 = c^2')

Mixed Math and Text

:py:class:ziamath.zmath.Text renders mixed math and text into a single <svg> element, drawing both math and text characters as SVG paths. It takes a string input with math expressions enclosed between single dollar signs $..$ for inline-mode math, and double dollar signs $$..$$ for block or display style math. Different fonts may be used for the plain text and math portions.

zm.Text(
    r'''The volume of a sphere is
$V = \frac{4}{3}\pi r^3$
or in terms of diameter,
$ V = \frac{\pi d^3}{6}$.
''', halign='center')

The textfont argument may be the path to a font file, or name of a font-family such as “sans”, “sans bold”, etc. The mathstyle provides styling to the math expressions.

Text objects support rotation (in degrees) and color (CSS named color or hex color value):

zm.Text('$\\sqrt{a}$', rotation=30, color='mediumslateblue')