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
python setup.py install
Schemdraw requires Python 3.7 or higher. Note that many of the examples and test notebooks still require 3.8+ to run due to their use of the walrus operator. The optional svgmath dependencies also require 3.8+.
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, a schemdraw.Drawing
is created and schemdraw.elements.Element
instances are added to it:
with schemdraw.Drawing() as d:
d.add(elm.Resistor())
d.add(elm.Capacitor())
d.add(elm.Diode())
The += operator may be used as shorthand notation to add elements to the drawing. This code is equivalent to the above:
with schemdraw.Drawing() as d:
d += elm.Resistor()
d += elm.Capacitor()
d += elm.Diode()
Element placement and other properties and are set using a chained method interface, for example:
with schemdraw.Drawing() as d:
d += elm.Resistor().label('100KΩ')
d += elm.Capacitor().down().label('0.1μF', loc='bottom')
d += elm.Line().left()
d += elm.Ground()
d += 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 calling draw() and/or save() explicitly:
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. A vector format such as svg is recommended for best results.
with schemdraw.Drawing(file='my_circuit.svg') as d:
...
The Drawing may also be saved using with the schemdraw.Drawing.save()
method.
Want to support Schemdraw development? Need more circuit examples? Check out the Schemdraw Examples Pack:
Schemdraw Examples Pack