PlotDevice

PlotDevice is a Macintosh application used for computational graphic design. It provides an interactive Python environment where you can create two-dimensional graphics and output them in a variety of vector, bitmap, and animation formats. It is meant both as a sketch environment for exploring generative design and as a general purpose graphics library for use in external Python programs.

PlotDevice scripts can create images from simple geometric primitives, text, and external vector or bitmap images. Drawing commands provide a thin abstraction over macOS's Quartz graphics engine, providing high-quality rendering of 2D imagery and powerful compositing operations.

Requirements

The PlotDevice application requires macOS 11 or greater (either on Intel or Apple Silicon) and comes bundled with a Python 3.10 distribution. The module can be installed via pip3 on Python versions ≥3.6 (including the interpreter from the Xcode command line tools and those installed through Homebrew).

Latest changes (July 2022)

Over the years since the last release, progress in both macOS and Python itself led to quite a bit of breakage. Some of the highlights of this maintenance release include:

New Features

• Runs natively on Intel and Apple Silicon and supports retina displays
• Python 3 support (including a bundled 3.10 installation in the app)
• images can now be exported in HEIC format and videos support H.265 (HEVC)
• SVG files can now be drawn to the canvas using the image() command (thanks to the magical SwiftDraw library)
• image exports have a configurable zoom to create 2x/3x/etc ‘retina’ images
• revamped var() command for creating GUIs to modify values via sliders, buttons, toggles, etc.
• updated text editor with multiple tabs, new themes, and additional key-binding modes emulating Sublime Text and VS Code
• the module's command line interface is now accessible through python3 -m plotdevice
• the command line tool has a new --install option to download PyPI packages for use within the app
• document autosaving is now user-configurable

Bugfixes

• exported images generated on retina machines now have the proper dimensions
• hex colors can now use lowercase letters
• automatic variables like WIDTH & HEIGHT correctly support the / operator
• the Color object's .blend() method is working again
• the read() command can now handle csv files with spaces in their header row names
• the translate() command now incorporates non-pixel grid units set via the size() command
• cmyk exports are working reliably for command line --export and via the export(cmyk=True) method
• arguments defined using the command line tool's --args options are now passed to the script's sys.argv

Misc. Improvements

• the command line tool can be exited via ctrl-c in addtion to being Quit from the menu bar
• simplified unicode handling (and improved support for normalization of user-provided strings)
• building the module now only requires Xcode command line tools—not a full Xcode.app installation
• the text() command will always treat its first argument as content (even if it's not a string) unless a str, xml, or src keyword argument is provided
• the mouse pointer is now visible in full-screen mode (and will auto-hide when inactive)

Unfortunate Casualties

• The NodeBox Libraries (coreimage, colors, and friends) would require quite a bit of attention to get working properly again. A first pass can be found in the plotdevice-libs repository but they're not ready for prime-time. If you're interested in contributing, this would be a terrific place to start!

Installation

PlotDevice supports being built as either a full-fledged Cocoa application, or as a standard Python module to be installed into a virtualenv alongside your source files. In both cases it now includes a command line tool called plotdevice allowing you to run scripts and perform batch exports from the console.

Application builds

The application can be built in Xcode with the PlotDevice.xcodeproj project. It can also be built from the command line by using python3 setup.py app (which uses Xcode) or python3 setup.py py2app (which uses setuptools).

The resulting binary will appear in the dist subdirectory and can be moved to your Applications folder or any other fixed directory. To install a symlink to the command line tool, launch the app from its installed location and click the Install button in the Preferences window.

Prebuilt application binaries can be downloaded from the PlotDevice site.

Module builds

PlotDevice can also be built as a Python module, allowing you to rely on an external editor and launch scripts from the command line (or from a ‘shebang’ line at the top of your script invoking the plotdevice tool). To install the module and command line tool use python3 setup.py install

Easier still, you can install the module directly from PyPI with a simple pip3 install plotdevice. It's a good idea to install the wheel module first since it greatly speeds up installation of the PyObjC libraries PlotDevice depends on.

Alternative Python Interpreters

When using pyenv (or compiling Python from source) you have the option of building the interpreter as a Framework. This gives you access to a GUI interface for running PlotDevice scripts via the python3 -m plotdevice command. Non-framework builds support the command line's --export functionality and will open a viewer window, but will not show an icon in the Dock or give you access to the menu bar.

To set up and run a script using a Framework build, do something along the lines of:

env PYTHON_CONFIGURE_OPTS="--enable-framework" pyenv install 3.10.4
pyenv shell 3.10.4
pip3 install plotdevice
python3 -m plotdevice <script.pv>

Building from source

You can also clone the git repository and build PlotDevice as a module or application from scratch. Consult the build instructions for details.

Documentation

The PlotDevice Manual provides extensive documentation of the various drawing commands and features sample code for nearly all of them. In addition to a detailed Reference, the manual also contains a number of Tutorial chapters that explain PlotDevice's inner workings concept-by-concept.

Beyond the core API, the Manual also collects documentation for the set of third-party Libraries that were written by the NodeBox community and ported to work with PlotDevice.

Running scripts

Once you have installed PlotDevice and added the plotdevice command to your shell's path, it can be used to run scripts in a window or export graphics to file using one of the supported image/video formats. The command itself is just a shorthand for running the module directly via python3 -m plotdevice (which accepts all the same command line arguments).

Command line usage

plotdevice [-h] [-f] [-b] [-q] [--live] [--cmyk] [--virtualenv PATH] [--args [a [b ...]]]
           [--export FILE] [--frames N or M-N] [--fps N] [--rate N] [--loop [N]] [--install [PACKAGES ...]]
           file

Runtime arguments

-h show the help message then quit
-f run full-screen
-b run PlotDevice in the background (i.e., leave focus in the active application)
-q run a PlotDevice script ‘quietly’ (without opening a window)
--virtualenv PATH 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 sys.argv

External editor integration

-b run PlotDevice in the background (i.e., don't switch apps when the script is run)
--live re-render graphics each time the file is saved

Image/animation export

--export FILE a destination filename ending in pdf, eps, png, tiff, jpg, heic, gif, or mov
--zoom PERCENT scale of the output image (100 = regular size) unless specified by a filename ending in @2x/@3x/etc --cmyk convert colors to CMYK before generating images (colors will be RGB if omitted)

Animation options

--frames N or M-N number of frames to render or a range specifying the first and last frames (default 1-150)
--fps N frames per second in exported video (default 30)
--rate N video bitrate in megabits per second (default 1)
--loop [N] number of times to loop an exported animated gif (omit N to loop forever)

Installing Packages from PyPI:

--install [packages ...] Use pip install to download libraries into the ~/Library/Application Support/PlotDevice directory, making them import-able in the application and by scripts run from the command line

Usage examples

# 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.265 video at 2 megabits/sec
plotdevice script.pv --export output.mov --frames 150 --rate 2.0

# I