Usage

Installation

Ziamath can be installed using pip:

pip install ziamath

Ziamath natively works with MathML. For Latex support, the latex2mathml package is used to convert the Latex into MathML first. It can be installed along with ziamath:

pip install ziamath[latex]

Ziamath depends on its sister package, Ziafont, for reading TTF font files.


Drawing Equations

The ziamath.zmath.Math class processes and draws a MathML <math> element. The Math class has a Jupyter representation that shows the SVG image as the output of a cell. To render a MathML string:

import ziamath as zm

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

To get the raw SVG, create the Math object, then use ziamath.zmath.Math.svg() for the SVG as a string:

eqn.svg()[:80]  # Only show first 80 characters...
'<svg width="23.972" height="21.699" xmlns="http://www.w3.org/2000/svg" viewBox="'

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

eqn.svgxml()
<Element 'svg' at 0x7f0f902c6cc0>

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.Math.fromlatex():

zm.Math.fromlatex(r'c = \pm \sqrt{a^2 + b^2}')
_images/usage_3_0.svg

Mixed Math and Text

ziamath.zmath.Math.fromlatextext() creates a MathML <math> element with text embedded in <mtext> elements. It takes a string input with math expressions enclosed between dollar signs $..$. This method works for single line math and text expressions.

zm.Math.fromlatextext(r'The volume of a sphere is $V = \frac{4}{3}\pi r^3$.', textstyle='sans')
_images/usage_4_0.svg

The textstyle argument provides styling to the plain text, and mathstyle provides styling to the math expressions. Both arguments may be an allowable MathML “mathvariant” attribute, such as ‘sans’, ‘serif’, ‘italic’, ‘bold’, ‘sans-bold’, etc.

Text Objects

Another option for mixed math and text is the ziamath.zmath.Text class. It takes a string, which may contain multiple lines and math expressions enclosed in $..$, and draws directly to SVG. The text is drawn directly; no <math> or <mtext> elements are accessible. 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')
_images/usage_5_0.svg

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

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

Drawing on an existing SVG

To draw math expressions on an existing SVG, create the SVG XML structure using an XML Element Tree. Then use ziamath.zmath.Math.drawon(), or ziamath.zmath.Text.drawon(), with the x and y position and svg to draw on:

from IPython.display import SVG
from xml.etree import ElementTree as ET

svg = ET.Element('svg')
svg.set('width', '200')
svg.set('height', '100')
svg.set('xmlns', 'http://www.w3.org/2000/svg')
svg.set('viewBox', f'0 0 100 100')
circ = ET.SubElement(svg, 'circle')
circ.set('cx', '20')
circ.set('cy', '25')
circ.set('r', '25')
circ.set('fill', 'orange')

myequation = zm.Math.fromlatex(r'\int_0^1 f(x) \mathrm{d}x', size=18)
myequation.drawon(svg, 50, 45)

SVG(ET.tostring(svg))
_images/usage_7_0.svg

Other image formats

Ziamath only outputs SVG format, but other image formats may be obtained using other Python libraries. Cairosvg can be used to convert to PNG, for example:

import cairosvg
expr = zm.Math.fromlatextext('$x^2 + y^2$')
pngbytes = cairosvg.svg2png(expr.svg())

Configuration Options

Global configuration options can be set in the ziamath.config object.

SVG Version Compatibility

Some SVG renderers, including recent versions of Inkscape and some OS built-in image viewers, are not fully compatible with the SVG 2.0 specification. Set the ziamath.config.svg2 parameter to False for better compatibility. This may result in larger file sizes as each glyph is included as its own <path> element rather than being reused with <symbol> and <use> elements.

zm.config.svg2 = False
zm.Math.fromlatextext('$x^2 + y^2$')

Decimal Precision

The decimal precision of coordinates in SVG tags can be set using ziafont.config.precision. Lower precision saves space in the SVG string, but may reduce quality of the image.

zm.config.precision = 2

Command Line

Ziamath may be accessed from the command line, reading input from a file with

python -m ziamath inputfile.txt

Or reading stdin (with LaTeX input):

echo "x^2 + y^2" | python -m ziamath --latex

Run python -m ziamath –help to show all the options.


Limitations

Not every MathML element is implemented at this time. Unsupported elements and attributes inculde:

  • <mstyle>

  • <ms>

  • <mglyph>

  • <merror>

  • <mmultiscripts>

  • <mlabeledtr>

  • scriptlevel attribute

  • table alignment attributes