The PlotDevice application is a convenient environment for writing scripts and being able to quickly see how your edits affect the graphical output. But once you’re happy with the state of a script, you can start to treat it as a program in its own right (rather than a mere ‘document’ that only exists inside the app).
The graphics core used by the application is also available in a ‘console’ setting, allowing you to run your scripts from the command line. It can even be used as a traditional Python module that you
import into your own programs.
The scripts you write in PlotDevice can be run from the terminal using an external command line tool called
plotdevice. The command allows you to run scripts, coordinate with an external editor, and export images, movies, or animated GIFs.
In the application, open the Preferences window and click the Install button:
Select a destination folder in your shell’s
PATH and the application will create a symlink from there to the script contained in the app bundle. If admin privileges are required to access the selected folder, you will be prompted for your password.
Note that since this connection involves a symlink, the
plotdevice command will break if you move the application after installing the tool. If this happens, you will see an error message in the Preferences window and can reinstall the link using the same procedure as before.
Once you have installed the
plotdevice tool you can run any of the ’.pv’ scripts you’ve written with the app. Running one of the example scripts is as simple as opening a Terminal window and typing:
You’ll see a new document icon appear in the Dock and the script’s output will be displayed in a window:
As in the PlotDevice application, you can useand to re-run and interrupt the script. The menu items are also available to you.
Running the command with just a filename argument will display its output in a window, but with the right combination of command line switches you can export graphics to file using any of the supported image/video formats.
There are quite a few optional switches:
plotdevice [-f] [-b] [--live] [--cmyk] [--virtualenv PATH] [--args [a [b ...]]] [--export FILE] [--frames N or M-N] [--fps N] [--rate N] [--loop [N]] file
But fear not; we’ll walk through each of the options below.
path to a virtualenv whose libraries you want to use (this should point to the top-level virtualenv directory)
--args [a [b ...]]
arguments to be passed to the script as
run PlotDevice in the background (i.e., don’t switch apps when the script is run)
re-render graphics each time the script file is saved
a destination filename ending in
convert colors to c/m/y/k before generating images (otherwise colors will be r/g/b)
--frames N or M-N
number of frames to render or a range specifying the first and last frames (default
frames per second in exported video (default
video bitrate in megabits per second (default
number of times to loop an exported animated gif (omit
N to loop forever)
# Run a script plotdevice script.pv
# Run fullscreen plotdevice -f script.pv
# Save script's output to pdf plotdevice script.pv --export output.pdf
# Create an animated gif that loops every 2 seconds plotdevice script.pv --export output.gif --frames 60 --fps 30 --loop
# Create a sequence of numbered png files – one for each frame in the animation plotdevice script.pv --export output.png --frames 10
# Create a 5 second long H.264 video at 2 megabits/sec plotdevice script.pv --export output.mov --frames 150 --rate 2.0
plotdevice command provides a convenient way to launch scripts with the PlotDevice interpreter, you may prefer to use the graphics context and export functions from within your own module (and running whichever
python binary your system or virtualenv provides).
Detailed installation instructions can be found in the project’s
README file. To simplify the use of PlotDevice with other external libraries, we recommend installing the module into a virtualenv alongside your script:
$ virtualenv env $ source ./env/bin/activate (env)$ pip install plotdevice
But you don’t need to stop there. The Python Package Index has thousands of other modules your script can use. Install them into the virtualenv and your script will know just where to find them:
(env)$ pip install requests envoy bs4 # some other useful packages
A nice side-effect of installing into a virtualenv is that it automatically creates a copy of the
plotdevice command that’s specific to that particular folder. When you ‘source’ the
activate file, your path is adjusted to let you run the
plotdevice command without specifying its path:
$ source ./env/bin/activate (env)$ plotdevice myscript.pv # uses the tool found at ./env/bin/plotdevice
plotdevice module contains all the global commands and constants you’re used to from the application. For instance, the following will draw a few boxes:
#!/usr/bin/env python from plotdevice import * for x, y in grid(10,10,12,12): rect(x,y, 10,10)
Though using ‘
import *’ is generally frowned upon in the Python community, we feel like it’s pretty easily justified in this case since PlotDevice’s raison d’être is to make your drawing code short-and-sweet.
You can then generate output files using the export() command. It takes a file path as an argument and the format will be determined by the file extension (
If you’re generating multiple images, be sure to reset the graphics state in between frames with:
But if you plan to do more than generate a one-off, you’ll likely find the with export() usage more convenient. The context-manager provides some handy methods for writing images, multi-page PDFs, and even animations.
As you can see from the toy example above, Python scripts that use the
plotdeivce module look a little different from scripts that run in the PlotDevice application. In particular, the lines at the very beginning of the Python script aren’t necessary in the application since it provides all the graphics commands implicitly as part of the script’s runtime environment.
In addition, scripts that run in the app or with the
plotdevice command expect special handling relating to animations. Just by defining a draw() method in your script, the viewer will repeatedly clear the canvas and call your method – even though the script itself doesn’t explicity call it.
It’s for this reason that the scripts you save from the application end with a
.pv extension rather than a
.py. The file extension is a small reminder that there are some missing pieces required to turn the file into full-fledged Python script.
Luckily, converting a .pv script to run without the
plotdevice tool is as simple as changing its file extension to py and adding three lines to the top of the code:
#!/usr/bin/env python # encoding: utf-8 from plotdevice import *
Importing the module won’t give you the default animation behavior (though you can easily create movies with the export() command), but it will add all the familiar PlotDevice commands to the script’s namespace. In addition, it will load all the necessary C-extensions and other system dependencies.
If you’d prefer to keep your namespace tidy, you can also import the module as-is. Just remember to prefix all your commands with the module name:
#!/usr/bin/env python # encoding: utf-8 import plotdevice as pd pd.size(256, 256) pd.background('red') pd.rect(64,64, 128,128, fill='white') pd.export('white-box.png')