# Getting Started¶

## Installation¶

schemdraw can be installed from pip using

pip install schemdraw


python setup.py install


Starting with version 0.7, schemdraw requires Python 3.7+.

## Overview¶

The schemdraw module allows for drawing circuit elements. schemdraw.elements contains Basic Circuit Elements pre-defined for use in a drawing. A common import structure is:

import schemdraw
import schemdraw.elements as elm


Schemdraw uses two main classes for creating circuit diagrams: schemdraw.Element and schemdraw.Drawing. Element instances are created and added to a Drawing to make a complete schematic diagram. All the different circuit elements subclass schemdraw.Element and are instantiated with keyword arguments defining the element’s parameters and location within the drawing. Individual elements can be viewed using the Jupyter representation of the element object:

elm.Resistor(label='R1')


To make a complete circuit diagram, a schemdraw.Drawing is created and schemdraw.Element are added to it:

d = schemdraw.Drawing()
d.add(elm.Resistor(d='right', label='1$\Omega$'))
d.add(elm.Capacitor(d='down', label='10$\mu$F'))


The element classes take a number of keyword arguments that define their position, direction, color, and other parameters. If any required argument is not provided, its value will be inherited from the schemdraw.Drawing the element belongs to.

The d keyword specifies the drawing direction, either ‘right’, ‘left’, ‘up’, or ‘down’, or with their abbreviations ‘r’, ‘l’, ‘u’, and ‘d’. The at keyword specifies the exact coordinates for the starting point of the element. If d is not supplied, the element will be drawn in the same direction as the previous element, and if at is not supplied, the element will start at the endpoint of the previously added element.

To display the schematic, call d.draw(). In Jupyter, this will show the schematic inline as the cell output. If run as a script, the schematic will display in the interactive matplotlib window.

d.draw()


When saving, the image type is determined from the extension. Options include svg, eps, png, pdf, and jpg. A vector format, such as svg is recommended for best results.

d.save('basic_rc.svg')


For full details of placing and stylizing elements, see Adding circuit elements.

## Usage Modes¶

### Jupyter Notebooks¶

Using a Jupyter Notebook in inline mode is recommended for the easy interactive creation of circuit diagrams. If your schematics pop up in an external window, 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¶

Code in a .py file can be run to generate figures, and by default, calling d.draw() will display a GUI window for viewing the schematic. Add the show=False option to d.draw() to suppress the window from appearing.

Rather than saving the schematic image to a file, the raw image data as a bytes array can be obtained by calling d.get_imagedata() using the desired ImageFormat. This can be useful for integrating schemdraw into an existing GUI or web application.

from schemdraw import Drawing, ImageFormat

drawing = Drawing()
...
image_bytes = drawing.get_imagedata(ImageFormat.SVG)


### Server Side¶

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() rather than d.draw().

import matplotlib
matplotlib.use('Agg') # Set the backend here