API

Base Classes

class ziaplot.drawable.Drawable

Drawable SVG/XML object. Implements common XML and SVG functions, plus _repr_ for Jupyter

cls(cls)

Set the CSS class name for the item. Matches items in CSS with .name selector

Return type:

Drawable

cssid(idn)

Set the CSS id for the item. Matches items in CSS with #name selector

Return type:

Drawable

imagebytes(fmt='svg')

Get byte data for image

Parameters:

ext – File format extension. Will be extracted from fname if not provided.

Return type:

bytes

save(fname)

Save image to a file

Parameters:

fname (str) – Filename, with extension.

Notes

SVG format is always supported. EPS, PDF, and PNG formats are available when the cairosvg package is installed

span(columns=1, rows=1)

Set the row and column span for the item when placed in a grid layout.

Return type:

Drawable

svgxml(border=False)

Generate XML for a standalone SVG

Return type:

Element

tosvg()

Get SVG string representation

Return type:

str

zorder(zorder=1)

Set zorder for the drawable

Return type:

Drawable

class ziaplot.container.Container

Drawing container base class (either Diagrams or Layouts)

class ziaplot.element.Element

Base class for elements, defining a single object in a plot

name(name)

Sets the element name to include in the legend

Return type:

Element


Diagrams and Graphs

class ziaplot.diagrams.diagram.Diagram

Base plotting class

add(comp)

Add a component to the diagram

Return type:

None

add_def(svgdef)

Add an item to the svg <defs>

Return type:

Diagram

colorfade(*clrs, stops=None)

Define the color cycle evenly fading between multiple colors.

Parameters:

  • colors – List of colors in #FFFFFF format

  • stops (Optional[Sequence[float]]) – List of stop positions for each color in the gradient, starting with 0 and ending with 1.

Return type:

Diagram

datarange()

Get range of data only

Return type:

DataRange

equal_aspect()

Set equal aspect ratio on data limits

Return type:

Diagram

erase(*comp)

Erase a previously added component

Return type:

None

legend(loc='left')

Specify legend location

Return type:

Diagram

match_x(other)

Set this diagram’s x range equal to the other diagram’s x range

match_y(other)

Set this diagram’s y range equal to the other diagram’s y range

size(w=600, h=400)

Set canvas width and height

Return type:

Diagram

svgxml(border=False)

XML for standalone SVG

Return type:

Element

title(title)

Set the title

Return type:

Diagram

xrange(xmin, xmax)

Set x-range of data display

Return type:

Diagram

yrange(ymin, ymax)

Set y-range of data display

class ziaplot.diagrams.graph.Graph

Plot of x-y data

axesnames(x=None, y=None)

Set names for the x and y axes

Return type:

Diagram

noxticks()

Turn off x axis tick marks

Return type:

Diagram

noyticks()

Turn off y axis tick marks

Return type:

Diagram

xticks(values, names=None, minor=None)

Set x axis tick values and names

Return type:

Diagram

yticks(values, names=None, minor=None)

Set y axis tick values and names

Return type:

Diagram

class ziaplot.diagrams.graph.GraphQuad

Graph showing all 4 quadrants of the coordinate plane. Axes are drawn as arrows pointing to infinity with xname and yname labels at the ends of the arrows.

datarange()

Get range of x-y data. GraphQuad datarange must include x=0 and y=0

Return type:

DataRange

class ziaplot.diagrams.graph.GraphQuadCentered

GraphQuad with the origin always centered

datarange()

Get range of x-y data. GraphQuad datarange must include x=0 and y=0

Return type:

DataRange

class ziaplot.diagrams.graphlog.GraphLogY

Plot with Y on a log10 scale

datarange()

Get range of data

Return type:

DataRange

class ziaplot.diagrams.graphlog.GraphLogX

Plot with Y on a log10 scale

datarange()

Get range of data

Return type:

DataRange

class ziaplot.diagrams.graphlog.GraphLogXY

Plot with X and Y on a log10 scale

datarange()

Get range of data only

Return type:

DataRange

class ziaplot.diagrams.polar.GraphPolar(labeldeg=True, labeltheta=0)

Polar Plot. Use with LinePolar to define lines in (radius, angle) format.

Parameters:

  • labeldeg (bool) – Draw theta labels in degrees vs. radians

  • labeltheta (float) – Angle for drawing R labels

rrange(rmax)

Sets maximum radius to display

Return type:

None

yrange(ymin, ymax)

Sets range of y data

Return type:

None

class ziaplot.diagrams.smith.GraphSmith(grid='coarse')

Smith Chart

Parameters:

grid (Literal['coarse', 'medium', 'fine', 'extrafine']) – Smith grid spacing

class ziaplot.diagrams.ticker._Ticker

Use to generate ticks using slice notation:

Examples

ticker[0:10:1] # Generate ticks from 0 to 10 ticker[0:10:2] # Step from 0-10 by 2’s


Discrete Plot Types

class ziaplot.discrete.polylines.PolyLine(x, y)

A polyline of x-y data, points connected by line segments

Parameters:

  • x (Sequence[float]) – X-values to plot

  • y (Sequence[float]) – Y-values to plot

class ziaplot.discrete.polylines.Scatter(x, y)

An X-Y Scatter data

Parameters:

  • x (Sequence[float]) – X-values to plot

  • y (Sequence[float]) – Y-values to plot

class ziaplot.discrete.polylines.ErrorBar(x, y, yerr=None, xerr=None)

An X-Y PolyLine with Error Bars in X and/or Y

Parameters:

  • x (Sequence[float]) – X-values to plot

  • y (Sequence[float]) – Y-values to plot

  • yerr (Optional[Sequence[float]]) – Y errors

  • xerr (Optional[Sequence[float]]) – X errors

datarange()

Get range of data

Return type:

DataRange

class ziaplot.discrete.polylines.LineFill(x, ymax, ymin=None)

A filled line/region

Parameters:

  • x (Sequence[float]) – X-values

  • ymax (Sequence[float]) – Y-values defining upper limit of region

  • ymin (Optional[Sequence[float]]) – Y-values defining lower limit of region. Defaults to 0.

color(color)

Sets the edge color

Return type:

LineFill

datarange()

Get range of data

Return type:

DataRange

fill(color)

Set the region fill color and transparency

Parameters:

color (str) – Fill color

Return type:

LineFill

class ziaplot.discrete.bars.Bars(x, y, y2=None, width=None, align='center')

A series of bars to add to an Graph (quantitative x values) For qualitative bar chart, use a BarChart instance.

Parameters:

  • x (Sequence[float]) – X-values of each bar

  • y (Sequence[float]) – Y-values of each bar

  • y2 (Optional[Sequence[float]]) – Minimum y-values of each bar

  • width (Optional[float]) – Width of all bars

  • align (Literal['left', 'center', 'right']) – Bar position in relation to x value

datarange()

Get x-y datarange

svgxml(border=False)

Generate XML for standalone SVG

Return type:

Element

class ziaplot.discrete.bars.BarsHoriz(x, y, y2=None, width=None, align='center')

Horizontal bars

datarange()

Get x-y datarange

Return type:

DataRange

class ziaplot.discrete.bars.Histogram(x, bins=None, binrange=None, density=False, weights=None)

Histogram data

Parameters:

  • x (Sequence[float]) – Data to show as histogram

  • bins (Optional[int]) – Number of bins for histogram

  • binrange (Optional[tuple[float, float, float]]) – Tuple of (start, stop, step) defining bins

  • density (bool) – Normalize the histogram

  • weights (Optional[Sequence[float]]) – Weights to apply to each x value

class ziaplot.discrete.bars.HistogramHoriz(x, bins=None, binrange=None, density=False, weights=None)
class ziaplot.discrete.polar.LinePolar(radius, theta, deg=False)

Define a data PolyLine using polar coordinates

Parameters:

  • radius (Sequence[float]) – The radius values to plot

  • theta (Sequence[float]) – The theta values to plot, in degres or radians

  • deg (bool) – Interpret theta as degrees instead of radians

class ziaplot.discrete.contour.Contour(x, y, z, levels=7, colorbar=None)

Contour Plot

Parameters:

  • x (Sequence[float]) – 1D array of x values

  • y (Sequence[float]) – 1D array of y values

  • z (Sequence[Sequence[float]]) – 2D array of z (height) values

  • levels (Union[int, Sequence[float]]) – Number of contour lines, or array of contour line levels

  • colorbar (Optional[Literal['top', 'right', 'bottom', 'left']]) – Position of colorbar, top, bottom, left, or right.

colors(*colors, stops=None)

Set the start and end colors for the contours

Return type:

Contour

datarange()

Get range of data

Return type:

DataRange

get_color_steps()

Get colors for each level

Return type:

list[str]

property nlevels: int

Number of levels in the contour

svgxml(border=False)

Generate XML for standalone SVG

Return type:

Element

class ziaplot.diagrams.smith.SmithConstResistance(resistance, xmin=-inf, xmax=inf)

Smith chart circle of constant Resistance (normalized)

Parameters:

  • resistance (float) – Resistance value (0 to inf)

  • xmin (float) – Minimum reactance intersection value

  • xmax (float) – Maximum reactance intersection value

Notes

Leave xmin and xmax at inf to draw full circle

class ziaplot.diagrams.smith.SmithConstReactance(reactance, rmax=inf, rmin=0)

Smith chart arcs of constant Reactance (normalized). Draws both positive and negative (capacitive and inductive) arcs.

Parameters:

  • reactance (float) – Reactance value

  • rmax (float) – maximum resistance intersection value

  • rmin (float) – minimum resistance intersection value


Geometric Figures

class ziaplot.figures.function.Function(func, xrange=None, n=200)

Plot a function

Parameters:

  • func (Callable[[float], float]) – Callable function of x, returning y (e.g. lambda x: x**2)

  • xmin – Minimum x value

  • xmax – Maximum x value

  • n (int) – Number of datapoints for discrete representation

chord(x1, x2)

Create a chord Segment connecting x1 and x2 on the funciton

Return type:

Segment

endmarkers(start='<', end='>')

Define markers to show at the start and end of the line. Use defaults to show arrowheads pointing outward in the direction of the line.

Return type:

Function

midmarker(midmark='<')

Define marker for midpoint (x/2) of Function curve

Return type:

Function

normal(x)

Create tangent line to function at x

Return type:

Line

secant(x1, x2)

Create a Line connecting x1 and x2 on the funciton

Return type:

Line

svgxml(border=False)

Generate XML for standalone SVG

Return type:

Element

tangent(x)

Create tangent line to function at x

Return type:

Line

x(y)

Calculate x at given y

Return type:

float

xy(x)

Calculate (x, y) on function at x

Return type:

Tuple[float, float]

y(x)

Evaluate f(x)

Return type:

float

class ziaplot.figures.implicit.Implicit(f, xlim=(-1, 1), ylim=(-1, 1), n=100)

Plot an implicit function

Parameters:

  • f (Callable) – A function of x and y, to plot f(x, y) = 0.

  • xlim (Tuple[float, float]) – Range of data for x direction

  • ylim (Tuple[float, float]) – Range of data for y direction

  • n (int) – Number of data points along x and y used to estimate the plot curves

class ziaplot.figures.line.Line(point, slope=0)

A straight Line extending to infinity

Parameters:

  • point (Union[Tuple[float, float], Point]) – One point on the line

  • slope (float) – Slope of the line

bisect_angle(other, which='+')

Create new line bisecting the two Lines.

The which parameter specifies which of the two bisectors to return. It may be + to return the bisector with positive or 0 slope, or - to return the bisector with negative or vertical slope.

Return type:

Line

endmarkers(start='<', end='>')

Define markers to show at the start and end of the line. Use defaults to show arrowheads pointing outward in the direction of the line.

Return type:

Line

classmethod from_points(p1, p2)

Create a line from two points

Return type:

Line

classmethod from_slopeintercept(slope, intercept=0)

Create a line from slope and intercept

Return type:

Line

classmethod from_standard(a, b, c)

Create line from standard form ax + by = c

Return type:

Line

property intercept: float

Y-intercept of Line

label(text, loc=0, align='N', rotate=False, color=None, size=None)

Add a label along the Line

Parameters:

  • text (str) – The text to add

  • loc (float) – Position along the line as fraction from 0-1

  • align (Literal['N', 'E', 'S', 'W', 'NE', 'NW', 'SE', 'SW']) – Text alignment

  • rotate (bool) – Rotate the text with the line

  • color (Optional[str]) – Text color

  • size (Optional[float]) – Text size

Return type:

Line

midmarker(midmark='<')

Add a marker to the center of the Segment

Return type:

Line

normal(p)

Create normal Line passing through p

Return type:

Line

parallel(distance)

Create a line parallel to another line

Return type:

Line

property point2: Tuple[float, float]

Get a second point on the line, 1 unit away

property standard: tuple[float, float, float]

Line coefficients (A, B, C) in standard form Ax + By = C

svgxml(border=False)

Generate XML for standalone SVG

Return type:

Element

trim(x1, x2)

Convert the line into a segment

Return type:

Segment

trimd(x, d1, d2)

Covnvert the line into a segment extending a distance d1 left and d2 right of point x on the line

Return type:

Segment

x(y)

Calculate x at y

Return type:

float

xy(x)

Calculate y at x, returning point (x, y)

Return type:

Tuple[float, float]

y(x)

Calculate y at x

Return type:

float

class ziaplot.figures.line.VLine(x)

Vertical Line at x

class ziaplot.figures.line.HLine(y)

Horizontal Line at y

class ziaplot.figures.line.Segment(p1, p2)

Line segment from p1 to p2

bisect()

Perpendicular bisector of the segment

Return type:

Line

datarange()

Get range of data

Return type:

DataRange

classmethod horizontal(p, tox=0)

Create a horizontal segment from p to the tox x value

Return type:

Segment

property length: float

Length of the segment

midpoint()

Midpoint of the segment

Return type:

Tuple[float, float]

property point2: Tuple[float, float]

Second point on the segment

trim(x1=None, x2=None)

Move endpoints of segment, keeping slope and intercept

Return type:

Segment

classmethod vertical(p, toy=0)

Create a vertical segment from p to the toy y value

Return type:

Segment

class ziaplot.figures.line.Vector(x, y)

A Vector arrow from (0, 0) to (x, y)

classmethod from_angle(theta, d=1)

Create Vector from angle and length

class ziaplot.figures.point.Point(p)

Point with optional text label

Parameters:

p (Tuple[float, float]) – x, y tuple

classmethod at(f, x)

Draw a Point at y = f(x)

Return type:

Point

classmethod at_intersection(f1, f2, bounds=None, which='top', offarc=False)

Draw a Point at the intersection of two functions, lines, circles, or arcs.

Parameters:

  • f1 (Function | Line | Circle | Arc) – First function

  • f2 (Function | Line | Circle | Arc) – Second function

  • bounds (Optional[tuple[float, float]]) – tuple of x values to bound the search. Only used for intersection of two Functions

  • which (str) – in cases where more than one intersection occurs, return the top, bottom, left or right-most point.

Return type:

Point

classmethod at_maximum(f, x1, x2)

Draw a Point at local maximum of f between x1 and x2

Return type:

Point

classmethod at_midpoint(a, b)

Draw a point at the midpoint between the two given points

Return type:

Point

classmethod at_minimum(f, x1, x2)

Draw a Point at local minimum of f between x1 and x2

Return type:

Point

classmethod at_y(f, y)

Draw a Point at y = f(x)

Return type:

Point

bisect(point)

Create a new line bisecting the two points

Return type:

Line

datarange()

Get x-y datarange

Return type:

DataRange

guidex(toy=0)

Draw a vertical guide line between point and toy

Return type:

Point

guidey(tox=0)

Draw a horizontal guide line between point and tox

Return type:

Point

image(line)

Create a new point imaged onto the line (point on line at shortest distance to point)

Return type:

Point

label(text, pos='NE')

Add a text label to the point

Parameters:

  • text (str) – Label

  • text_pos – Position for label with repsect to the point (N, E, S, W, NE, NW, SE, SW)

Return type:

Point

marker(marker, radius=None, orient=False)

Sets the point marker shape and size

Return type:

Point

classmethod on_bezier(b, t)

Create a Point on the Bezier curve

Return type:

Point

classmethod on_circle(circle, theta)

Draw a Point on the circle at angle theta (degrees)

Return type:

Point

property point: Tuple[float, float]

XY coordinate tuple

reflect(line)

Create a new point reflected over line

Return type:

Point

class ziaplot.figures.bezier.Bezier(p1, p2, p3, p4=None)

Quadratic or Cubic Bezier Curve

Parameters:

  • p1 (Tuple[float, float]) – Control points for curve. p4 Optional.

  • p2 (Tuple[float, float]) – Control points for curve. p4 Optional.

  • p3 (Tuple[float, float]) – Control points for curve. p4 Optional.

  • p4 (Optional[Tuple[float, float]]) – Control points for curve. p4 Optional.

chord(t1, t2)

Create a Chord segment between parameters t1 and t2

Return type:

Segment

endmarkers(start='<', end='>')

Define markers to show at the start and end of the curve. Use defaults to show arrowheads pointing outward in the direction of the curve.

Return type:

Bezier

midmarker(midmark='<')

Add marker to center of curve

Return type:

Bezier

normal(t)

Create a normal line at parameter t

Return type:

Line

secant(t1, t2)

Create a secant line between parameters t1 and t2

Return type:

Line

svgxml(border=False)

Generate XML for standalone SVG

Return type:

Element

tangent(t)

Create tangent line at parameter t

Return type:

Line

xy(t)

Evaluate (x, y) value of curve at parameter t

Return type:

Tuple[float, float]

class ziaplot.figures.bezier.Curve(p1, p2, k=0.15)

Symmetric curve connecting the two points with deflection k as fraction of distance between endpoints

class ziaplot.figures.bezier.CurveThreePoint(start, end, mid, t=0.5)

Bezier Curve passing through three points and parameter t

class ziaplot.figures.integral.IntegralFill(f, f2=None, x1=None, x2=None)

Fill between two functions or between a function and the x-axis

Parameters:

  • f (Function) – Function or Line instance

  • f2 (Optional[Function]) – Another Function instance

  • x1 (Optional[float]) – Starting x value to fill

  • x2 (Optional[float]) – Ending x value to fill

classmethod intersection(f, f2, x1, x2)

Integral fill between intersection of f and f2, where x1 and x2 are points outside the intersection

class ziaplot.figures.shapes.Circle(center, radius)

Draw a circle

Parameters:

  • x – Center x coordinate

  • y – Center y coordinate

  • radius (float) – Radius of circle

chord(angle1=0, angle2=180)

Create a chord on the circle connecting the two angles (degrees)

Return type:

Segment

datarange()

Data limits

Return type:

DataRange

diameter_line(angle=0)

Create a new Line through a diameter at the angle (degrees)

Return type:

Line

diameter_segment(angle=0)

Create a new Segment through a diameter at the angle (degrees)

Return type:

Segment

classmethod from_lll(line1, line2, line3, which='top')

Create a circle tangent to all three lines.

The which paremeter specifies which of the 4 possible solutions to return, based on its center point. Options: :rtype: Circle

  • top: return the circle with the top-most center

  • bottom: return the circle with the bottom-most center

  • left: return the circle with the left-most center

  • right: return the circle with the right-most center

  • y0, y1, y2, y3: sort the circles by y value and return the Nth

  • x0, x1, x2, x3: sort the circles by x value and return the Nth

classmethod from_ppp(p1, p2, p3)

Create a circle passing through the three given points

Return type:

Circle

normal(p)

Create normal line from circle to point

Return type:

Line

on_arc_point(p)

Is the angle theta (in degrees) on the circle

Return type:

bool

radius_segment(angle=0)

Create a new Segment through a radius at the angle (degrees)

Return type:

Segment

sagitta(angle1=0, angle2=180)

Create a sagitta segment (perpendicular to the chord) on a circle defined by the chord with endpoints at angle1 and angle2.

Return type:

Segment

secant(angle1=0, angle2=180)

Create a secant on the circle through the two angles (degrees)

Return type:

Line

tangent(p, which='top')

Create a tangent line passing through p.

Parameters:

  • p (Tuple[float, float]) – Point the tangent passees through, on or outside the circle

  • which (str) – Determines which of the two possible tangents to return. may be top, bottom, left, or right based on the position ot the tangent point on the circle.

Return type:

Line

tangent_at(theta)

Create a tangent line at the angle theta

Return type:

Line

property x: float

Center X value

xy(theta)

Get x, y coordinate on the circle at the angle theta (degrees)

Return type:

Tuple[float, float]

property y: float

Center Y value

class ziaplot.figures.shapes.Ellipse(center, r1, r2, theta=0)

Draw an Ellipse

Parameters:

  • x – Center x coordinate

  • y – Center y coordinate

  • r1 (float) – Radius 1

  • r2 (float) – Radius 2

  • theta (float) – Angle of rotation (degrees)

datarange()

Data limits

Return type:

DataRange

tangent(p, which='top')

Create a tangent line passing through p.

Parameters:

  • p (Union[Tuple[float, float], Point]) – Point the tangent passees through, on or outside the circle

  • which (str) – Determines which of the two possible tangents to return. may be top, bottom, left, or right based on the position ot the tangent point on the circle.

Return type:

Line

xy(theta)

Get x, y coordinate on the circle at the angle theta (degrees)

Return type:

Tuple[float, float]

class ziaplot.figures.shapes.Rectangle(x, y, width, height, cornerradius=0)

Draw a rectangle

Parameters:

  • x (float) – lower left x value

  • y (float) – lower left y value

  • width (float) – width of rectangle

  • height (float) – height of rectangle

  • cornerradius (float) – radius of corners


Charts

class ziaplot.charts.pie.Pie(labelmode='name')

Pie Chart. Total of all wedge values will be normalized to 100%.

Parameters:

labelmode (Literal['name', 'percent', 'value']) – How to label each wedge - by name, percent, or value.

classmethod fromdict(slices, labelmode='name')

Create Pie from bars dictionary

Parameters:

  • slices (dict[str, float]) – dictionary of name:value pairs

  • labelmode (Literal['name', 'percent', 'value']) – How to label each wedge - by name, percent, or value.

Return type:

Pie

classmethod fromlist(slices, labelmode='name')

Create Pie from list of values

Parameters:

  • slices (list[float]) – list of values

  • labelmode (Literal['name', 'percent', 'value']) – How to label each wedge - by name, percent, or value.

Return type:

Pie

class ziaplot.charts.pie.PieSlice(value=1)

One slice of a pie.

Parameters:

value (float) – value assigned to this slice. Percent will be calculated using total value of all the slices.

edgecolor(color)

Sets the slice stroke/linestyle

Return type:

PieSlice

edgewidth(width)

Set the slice edge width

Return type:

PieSlice

extrude(extrude=20)

Extrude the slice

Return type:

PieSlice

class ziaplot.charts.bar.BarChart

A vertical bar chart with a single bar series. Independent variable is qualitative.

Note

For a bar graph with quantitative x values, use Graph and add Bars instances.

add(bar)

Add a single bar

Return type:

None

classmethod fromdict(bars)

Create a barchart from dictionary of name: value pairs

Return type:

BarChart

class ziaplot.charts.bar.Bar(value=1)

A single bar in a BarChart

Parameters:

value (float) – value assigned to this bar.

class ziaplot.charts.bar.BarChartGrouped(groups)

A grouped bar chart, where independent variable is qualitative.

Parameters:

groups (Sequence[str]) – list of x value strings

Note

For a bar graph with quantitative x values, use Graph and add Bars instances.

add(barseries)

Add a series of bars to the chart

Return type:

None

classmethod fromdict(bars, groups)

Create Bar Chart from dictionary of name: values list

Return type:

BarChartGrouped

class ziaplot.charts.bar.BarSeries(*values)

A series of bars across all groups

Parameters:

values (float) – values assigned to this bar series.


Annotations

class ziaplot.annotations.text.Text(x, y, s, halign='left', valign='bottom', rotate=None)

A text element to draw at a specific x-y location

Parameters:

  • x (float) – X-position for text

  • y (float) – Y-position for text

  • s (str) – String to draw

  • halign (Literal['left', 'center', 'right']) – Horizontal alignment

  • valign (Literal['top', 'center', 'baseline', 'base', 'bottom']) – Vertical alignment

  • rotate (Optional[float]) – Rotation angle, in degrees

color(color)

Sets the text color

Return type:

Text

datarange()

Get x-y datarange

Return type:

DataRange

class ziaplot.annotations.annotations.Arrow(xy, xytail, marker='arrow', tailmarker=None)

An arrow pointing to an XY location, with optional text annotation

Parameters:

  • xy (Sequence[float]) – XY position to point at

  • xytail (Sequence[float]) – XY-position of arrow tail

  • s – String to draw at tail of arrow

  • strofst – XY offset between text and arrow tail

  • marker (Literal['round', 'o', 'square', 's', 'triangle', '^', 'triangled', 'v', 'larrow', '<', 'arrow', '>', '+', 'x', '-', '|', '||', '|||', 'undefined', None]) – Arrowhead marker shape

  • tailmarker (Optional[Literal['round', 'o', 'square', 's', 'triangle', '^', 'triangled', 'v', 'larrow', '<', 'arrow', '>', '+', 'x', '-', '|', '||', '|||', 'undefined', None]]) – Arrowhead tail marker

label(text, pos='NE')

Add a text label to the point

Parameters:

  • text (str) – Label

  • text_pos – Position for label with repsect to the point (N, E, S, W, NE, NW, SE, SW)

Return type:

Arrow

class ziaplot.annotations.annotations.Angle(line1, line2, quad=1, arcs=1)

Draw angle between two Lines/Segments

color(color)

Sets the color of the angle arc

Return type:

Angle

radius(radius, text_radius=None)

Sets the radius of the angle arc

Return type:

Angle

strokewidth(width)

Sets the strokewidth of the angle arc

Return type:

Angle

classmethod to_zero(line, quad=1)

Create angle between line and y=0


Layouts

class ziaplot.layout.LayoutH(*diagrams, column_gap=10, **kwargs)

Lay out Diagrams in horizontal row

Parameters:

  • diagrams (Drawable) – The Diagrams/Graphs to add

  • column_gap (float) – Spacing between columns

class ziaplot.layout.LayoutV(*diagrams, row_gap=10, **kwargs)

Lay out Diagrams in vertical stack

Parameters:

  • diagrams (Drawable) – The Diagrams/Graphs to add

  • row_gap (float) – Spacing between rows

class ziaplot.layout.LayoutGrid(*diagrams, columns=1, column_widths=None, row_heights=None, column_gap=10, row_gap=10, **kwargs)

Lay out Diagrams in a grid. Diagrams added to the layout fill the grid from left to right, adding rows as needed.

Parameters:

  • diagrams (Drawable) – The diagrams to add

  • columns (int) – Number of columns

  • column_widths (Optional[str]) – String specifying widths of each column (see Note)

  • row_heights (Optional[str]) – String specifying widths of each column (see Note)

  • column_gap (float) – Spacing between columns

  • row_gap (float) – Spacing between rows

Notes

column_widths and row_heights specification is a similar style to a CSS grid layout. The string is space-delimited with each item either 1) a plain number representing the number of pixels 2) a percent of the whole width, 3) a number with “fr” suffix representing fractions of the whole. Examples: “25% 1fr” –> First column takes 25%, second column the remainder “200 1fr” –> First column takes 200 pixels, second column the remainder “2fr 1fr” –> First column is twice the width of second

add(diagram)

Add a Diagram to the grid

size(w=600, h=400)

Set canvas width and height

Return type:

LayoutGrid

svgxml(border=False)

XML for standalone SVG

Return type:

Element

class ziaplot.layout.LayoutEmpty

Empty placeholder for layout

Global Themes and CSS

ziaplot.style.themes.css(css)

Set global CSS styling

Return type:

None

ziaplot.style.themes.theme(name)

Activate a theme by name. Use list_themes to see list of available theme names.

Return type:

None

ziaplot.style.themes.theme_list()

Get a list of available themes

Return type:

list[str]

General Functions

ziaplot.container.save(fname)

Save the current drawing to a file. Must be used within a Diagram or Layout context manager.

Parameters:

fname (str) – Filename, with extension.

Return type:

None

Notes

SVG format is always supported. EPS, PDF, and PNG formats are available when the cairosvg package is installed

class ziaplot.attributes.Attributes

Access attributes and subelements of the SVG element

get(name, default=None)

Get an SVG attribute from the element

Parameters:

  • name (str) – The SVG/XML attribute name to get

  • default (Optional[str]) – Default value to return if the attribute does not exist

Return type:

Optional[str]

set(name, value)

Set an XML attribute to the SVG elemenet

Parameters:

  • name (str) – The SVG/XML attribute name to set

  • value (str) – Value of the attribute

Return type:

Attributes

subelement(element)

Add an XML/SVG sub element

Parameters:

element (str | Element) – The element to add, either as text or an ET.Element instance.

Return type:

Attributes

class ziaplot.attributes.Animatable

SVG attributes and subelements, with functions for adding SMIL annimation elements

animate(attribute, to, frm, begin='', duration='', repeat='indefinite')

Animate an attribute. (Note parameters are in SVG coordinates, not drawing coordinates)

Parameters:

  • attribute (str) – name of the attribute to set

  • to (str) – Value to set the attribute

  • frm (str) – Initial value of the attribute

  • begin (str) – Time or other criteria at which to set the attribute. Should be a string with units, e.g. ‘2s’. (see https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Attribute/begin)

  • duration (str) – Length of time from start to end of the path

  • repeat (str) – Number of times to repeat, or ‘indefinite’

Return type:

Animatable

animate_in(begin='', duration='', repeat='')

Animate the path as if it is being drawn

Parameters:
Return type:

Animatable

animate_move(path, begin='', duration='', repeat='indefinite', rotate='auto')

Animate the object, moving it along path defined by the path component. Sets the <animateMotion> svg tag.

Parameters:

  • path (Component) – Another drawing component, containing a path (such as a Segment, Bezier, or PolyLine)

  • begin (str) – Time or other criteria at which to set the attribute. Should be a string with units, e.g. ‘2s’. (see https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Attribute/begin)

  • duration (str) – Length of time from start to end of the path

  • repeat (str) – Number of times to repeat, or ‘indefinite’

  • rotate (str) – Whether to rotate the element in the direction of motion, may be ‘auto’, ‘auto-reverse’, or ‘0’

Return type:

Animatable

animate_out(begin='', duration='', repeat='')

Animate the path as if it is being erased

Parameters:
Return type:

Animatable

animate_set(attribute, to, begin='', duration='')

Animate an attribute value of the element (using svg <set> tag)

Parameters:

  • attribute (str) – name of the attribute to set

  • to (str) – Value to set the attribute

  • begin (str) – Time or other criteria at which to set the attribute. Should be a string with units, e.g. ‘2s’. (see https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Attribute/begin)

  • duration (str) – Length of time to leave the attribute set, or ‘indefinite’.

Return type:

Animatable

animate_show(begin='', duration='')

Animate the visibile attribute

Parameters:
Return type:

Animatable

Geometric Calculations

A few calculation functions are made available to the user.

ziaplot.geometry.distance(p1, p2)

Distance between two points

Return type:

float

ziaplot.geometry.isclose(p1, p2)

Determine if the points are identical (x and y within math.isclose)

Return type:

bool

ziaplot.geometry.midpoint(p1, p2)

Midpoint between two points

Return type:

Tuple[float, float]

ziaplot.geometry.translate(point, delta)

Translate the point by delta

Return type:

Tuple[float, float]

ziaplot.geometry.reflect(point, line)

Reflect the point over the line

Return type:

Tuple[float, float]

ziaplot.geometry.rotate(point, theta)

Rotate the point theta radians about the origin

Return type:

Tuple[float, float]

ziaplot.geometry.image(point, line)

Create a new point imaged onto the line (point on line at shortest distance to point)

Return type:

Tuple[float, float]

ziaplot.geometry.angle_mean(theta1, theta2)

Circular mean over 0 to 2pi (theta in radians)

Return type:

float

ziaplot.geometry.angle_diff(theta1, theta2)

Get angular difference between theta2 and theta1 (radians)

ziaplot.geometry.angle_isbetween(angle, theta1, theta2)

Is angle between theta1 and theta2 counterclockwise?

Return type:

bool

ziaplot.geometry.line.slope(line)

Get slope of the line

Return type:

float

ziaplot.geometry.line.intercept(line)

Get y-intercept of the line

Return type:

float

ziaplot.geometry.line.xintercept(line)

Get x-intercept of the line

Return type:

float

ziaplot.geometry.line.yvalue(line, x)

Get y value of the line at x

Return type:

float

ziaplot.geometry.line.xvalue(line, y)

Get x value of the line at y

Return type:

float

ziaplot.geometry.line.normal_distance(line, point)

Normal distance from point to line

Return type:

float

ziaplot.geometry.line.bisect(line1, line2)

Find the two lines bisecting the given two lines

Return type:

tuple[Tuple[float, float, float], Tuple[float, float, float]]

ziaplot.geometry.line.bisect_points(p1, p2)

Find the line bisecting the two points

Return type:

Tuple[float, float, float]

ziaplot.geometry.circle.point(circle, theta)

Coordinates of point on circle at angle theta (rad)

Return type:

Tuple[float, float]

ziaplot.geometry.circle.tangent_angle(theta)

Angle of tangent to circle at given theta around circle

Return type:

float

ziaplot.geometry.circle.tangent_at(circle, theta)

Find tanget to circle at given theta

Return type:

Tuple[float, float, float]

ziaplot.geometry.circle.tangent_points(circle, p)

Find the two points on the circle that form a tangent line through the given point

Return type:

tuple[Tuple[float, float], Tuple[float, float]]

ziaplot.geometry.circle.tangent(circle, p)

Find tangent points and slope of the two tangents to the circle through the point p

Return type:

tuple[tuple[Tuple[float, float], float], tuple[Tuple[float, float], float]]

ziaplot.geometry.ellipse.point(ellipse, theta)

Get point on ellipse at angle theta

Return type:

Tuple[float, float]

ziaplot.geometry.ellipse.tangent_points(ellipse, p)

Find the two points on the Ellipse that form a tangent line through the given point

Return type:

tuple[Tuple[float, float], Tuple[float, float]]

ziaplot.geometry.ellipse.tangent_angle(ellipse, theta)

Angle (radians) tangent to the Ellipse at theta (radians)

Return type:

float

ziaplot.geometry.function.local_max(f, x1, x2)

Find local maximum of function f between x1 and x2

Return type:

Tuple[float, float]

ziaplot.geometry.function.local_min(f, x1, x2)

Find local minimum of function f between x1 and x2

Return type:

Tuple[float, float]

ziaplot.geometry.function.tangent(f, x)

Find tangent to function at x

Return type:

Tuple[float, float, float]

ziaplot.geometry.function.normal(f, x)

Find normal to function at x

Return type:

Tuple[float, float, float]

ziaplot.geometry.bezier.xy(b, t)

Point on a Bezier curve at parameter t

Return type:

Tuple[float, float]

ziaplot.geometry.bezier.tangent_slope(b, t)
Return type:

float

ziaplot.geometry.bezier.tangent_angle(b, t)
Return type:

float

ziaplot.geometry.bezier.length(b, n=50)

Compute approximate length of Bezier curve (Quadtratic or Cubic)

Parameters:

n (int) – Number of points used for piecewise approximation of curve

Return type:

float

ziaplot.geometry.bezier.equal_spaced_points(b, nsegments=2, n=100)

Find (x, y) points spaced equally along a Bezier curve

Parameters:

  • bezier – The curve to split

  • nsegments (int) – Number of segments to split curve into

  • n (int) – Number of points used to approximate curve

Return type:

list[Tuple[float, float]]

ziaplot.geometry.intersect.lines(line1, line2)

Find point of intersection of two lines

Return type:

Tuple[float, float]

ziaplot.geometry.intersect.line_angle(line1, line2)

Find angle (rad) of intersection between the two lines

Return type:

float

ziaplot.geometry.intersect.line_circle(line, circle)

Find intersections between line and circle

Return type:

tuple[Tuple[float, float], Tuple[float, float]]

ziaplot.geometry.intersect.circles(circle1, circle2)

Get points of intersection between two circles

Return type:

tuple[Tuple[float, float], Tuple[float, float]]

ziaplot.geometry.intersect.line_arc(line, arc)

Find intersection of line and arc. Same as circle, but ensures point falls on the arc

ziaplot.geometry.intersect.functions(f1, f2, x1, x2)

Find intersection between two Functions in the interval x1 to x2. Raises ValueError if the curves do not intersect.

Return type:

Tuple[float, float]

ziaplot.util.linspace(start, stop, num=50)

Generate list of evenly spaced points

Return type:

list[float]