Getting Started¶
Installation¶
schemdraw can be installed from pip using
pip install schemdraw
or to include optional matplotlib
backend dependencies:
pip install schemdraw[matplotlib]
To allow the SVG drawing Backends to render math expressions, install the optional ziamath dependency with:
pip install schemdraw[svgmath]
Alternatively, schemdraw can be installed directly by downloading the source and running
pip install ./
Schemdraw requires Python 3.8 or higher.
Overview¶
The schemdraw
module allows for drawing circuit elements.
schemdraw.elements
contains Basic Elements pre-defined for
use in a drawing. A common import structure is:
import schemdraw
import schemdraw.elements as elm
To make a circuit diagram, use a context manager (with statement) on a schemdraw.Drawing
. Then any schemdraw.elements.Element
instances created within the with block added to the drawing:
with schemdraw.Drawing():
elm.Resistor()
elm.Capacitor()
elm.Diode()
New in version 0.18: The context manager keeps track of the active drawing, so that using drawing.add(element) or drawing += element is no longer necessary. These operators are still functional and are needed if drawing outside a with context manager:
with schemdraw.Drawing() as drawing:
drawing += elm.Resistor()
drawing += elm.Capacitor()
drawing.add(elm.Diode()) # Same as `drawing +=`
Element placement and other properties and are set using a chained method interface, for example:
with schemdraw.Drawing():
elm.Resistor().label('100KΩ')
elm.Capacitor().down().label('0.1μF', loc='bottom')
elm.Line().left()
elm.Ground()
elm.SourceV().up().label('10V')
Methods up, down, left, right specify the drawing direction, and label adds text to the element. If not specified, elements reuse the same direction from the previous element, and begin where the previous element ended.
Using the with context manager is a convenience, letting the drawing be displayed and saved upon exiting the with block. Schematics may also be created simply by assinging a new Drawing instance, but this requires explicitly adding elements to the drawing with d.add or d +=`, and calling draw() and/or save() to show the drawing:
d = schemdraw.Drawing()
d += elm.Resistor()
...
d.draw()
d.save('my_circuit.svg')
For full details of placing and stylizing elements, see Placing Elements.
and schemdraw.elements.Element
.
In general, parameters that control what is drawn are passed to the element itself, and parameters that control how things are drawn are set using chained Element methods. For example, to make a polarized Capacitor, pass polar=True as an argument to Capacitor, but to change the Capacitor’s color, use the .color() method: elm.Capacitor(polar=True).color(‘red’).
Viewing the Drawing¶
Jupyter¶
When run in a Jupyter notebook, the schematic will be drawn to the cell output after the with block is exited. If your schematics pop up in an external window, and you are using the Matplotlib backend, set Matplotlib to inline mode before importing schemdraw:
%matplotlib inline
For best results when viewing circuits in the notebook, use a vector figure format, such as svg before importing schemdraw:
%config InlineBackend.figure_format = 'svg'
Python Scripts and GUI/Web apps¶
If run as a Python script, the schematic will be opened in a pop-up window after the with block exits. Add the show=False option when creating the Drawing to suppress the window from appearing.
with schemdraw.Drawing(show=False) as d:
...
The raw image data as a bytes array can be obtained by calling .get_imagedata() with the after the with block exits. This can be useful for integrating schemdraw into an existing GUI or web application.
with schemdraw.Drawing() as drawing:
...
image_bytes = drawing.get_imagedata('svg')
Headless Servers¶
When running on a server, sometimes there is no display available. The code may attempt to open the GUI preview window and fail. In these cases, try setting the Matplotlib backend to a non-GUI option. Before importing schemdraw, add these lines to use the Agg backend which does not have a GUI. Then get the drawing using d.get_imagedata(), or d.save() to get the image.
import matplotlib
matplotlib.use('Agg') # Set Matplotlib's backend here
Alternatively, use Schemdraw’s SVG backend (see Backends).
Saving Drawings¶
To save the schematic to a file, add the file parameter when setting up the Drawing. The image type is determined from the file extension. Options include svg, eps, png, pdf, and jpg when using the Matplotlib backend, and svg when using the SVG backend. A vector format such as svg is recommended for best image quality.
with schemdraw.Drawing(file='my_circuit.svg') as d:
...
The Drawing may also be saved using with the schemdraw.Drawing.save()
method.