Processing.py on the command line

This tutorial is for Processing's Python Mode. If you see any errors or have comments, please let us know. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

Most of the material online about Processing.py is oriented to Python Mode, which allows you to write Processing sketches in the PDE using the Python programming language. But Processing.py also provides a way for you to write and launch sketches from the command line.

Why use the command line? The PDE is great, of course, and many people use it for writing interactive applications from sketch to finished product. But there are some scenarios in which you might want to use the command line: for easier integration with collaborative version control tools; for more control over how your application gets packaged; for easier interoperability with other tools that live on the command-line; etc. Or maybe (like me) you just prefer working on the command line to working in a GUI. Whatever your reason, this tutorial will show you how to get up and running.

These instructions are tested on OSX El Capitan, but should work on other platforms as well.

Requirements

In order to run Processing.py from the command line. For maximum compatability with processing, you'll need to install Java 8 -- specifically, we recommend JRE 8u202 from Oracle.

From the Processing Build Instructions: Other versions of Java are not supported. It must be 8u202. Later versions of Java (9, 10, et cetera) don't work either. OpenJDK is also not supported. Really. Please don't use it (and then complain when things break).

After installing, ensure that you can run Java by typing the following on the command line:

$ java -version

You should see some output that looks like this:

java version "1.8.0_202"
Java(TM) SE Runtime Environment (build 1.8.0_202-b08)
Java HotSpot(TM) 64-Bit Server VM (build 25.202-b08, mixed mode)

You'll also need to obtain the standalone version of Processing.py. Choose the appropriate link according to your platform:

• Mac OS X
• Windows: 64-bit, 32-bit
• Linux: 64-bit 32-bit

These files contain the Processing.py JAR file along with some example scripts and some utility programs for running Processing.py on its own, for various platforms. Decompress the file, making note of the location of the resulting directory.

The basics

Once you've installed Java and decompressed the processing-py.jar file, put a copy of the .jar file in a new directory for your project. Now you can use your favorite text editor to write a Processing.py sketch. Here's a simple sketch you can use for testing. Copy it and paste as mouse_follow.py:

def setup():
    size(400, 400)

def draw():
    background(255)
    fill(0)
    ellipse(mouseX, mouseY, 50, 50)

Save the file in the same directory as the .jar. Open a command line session (with, e.g., Terminal on OSX or Command Prompt in Windows) and cd to the directory with the sketch and the processing-py.jar file. Now, type the following:

java -jar processing-py.jar mouse_follow.py

The command above runs the Java interpreter (java), and tells the interpreter to run the code in the given JAR. The processing-py.jar file contains all of Processing.py along with a little bit of code that reads and executes the Python file specified on the command line.

After typing the above and hitting return, you should see a window appear with the mouse_follow.py sketch up and running. Once you have that program working, you can run any Processing.py program on the command line using the same syntax. The examples.py folder contains a number of example scripts to get you started.

If something goes wrong...

If the window did not appear, then something went wrong. Make sure that you typed the command as specified, spaces and all (note that there's a space between java and -jar and that there's only one hyphen in the -jar parameter). If your error message says something like 'java' is not a recognized command or java: command not found, then you may not have successfully installed Java (see previous section for further instructions).

Any syntax errors or runtime exceptions in your program will be printed to the terminal.

Java command-line parameters

When you run java on the command line, it's up to you to know which parameters to pass to the interpreter. For most simple applications of command-line Processing.py, the -jar parameter is probably the only parameter you'll need, but for more advanced usage you might need to dig a bit deeper into the possibilities. You can see a full list of parameters by typing java -help.

The most important parameters for you to know about right from the beginning are -Xms and -Xmx, which set the initial and maximum heap size, respectively. Roughly, the heap size is how much memory Java is allowed to use when running your program. If you're getting errors saying that you're out of memory, or if Java performance is poor when working with programs that load large objects into memory repeatedly, it might be worth overriding the defaults for these values by specifying them on the command line. All of the advice given here in the Java Processing Wiki also applies to Processing.py; here's another good starting point for adjusting these values.

For example, to run Processing.py requesting a starting heap size of 256 megabytes and a maximum heap size of 1 gigabyte:

java -Xms256m -Xmx1024m -jar processing-py.jar 

Included helper scripts

The distribution you downloaded comes with a number of "helper scripts" for running Processing.py on the command line. These are:

• processing-py.app: A drag-and-drop application for Mac OS X. You can run this and then drag Processing.py programs from the Finder into the window to run them.
• processing-py.bat: A Windows batch file that launches a Processing.py program with a splash screen and default Java parameters
• processing-py.sh: A shell script (for Linux, OS X and Cygwin) that launches a Processing.py program with a splash screen and default Java parameters

The benefit of using these programs is that you can launch them directly from your GUI's filesystem navigator without having to navigate to the appropriate directory, etc. All of these helper scripts, by default, launch a sketch called workspace/example.py; you can overwrite this script with your own code if you'd like.

Loading media and other data

The Processing language supports several functions, like loadImage(), loadFont(), loadShape(), etc. that load data from the filesystem. Processing.py supports these functions as well! In order to use these functions, you need to put the data in a place where Processing can find it. If you're used to working in the Processing IDE, you've probably added external data to your sketch using the "Add file..." menu option. When you're using Processing.py directly from the command line, you can accomplish the same task by copying files directly.

By default, functions like loadImage() in Processing.py will look for the given filename in a subdirectory named data located in the same directory as your sketch. If the file isn't found there, it will attempt to find the file in the same directory as the sketch itself. For example, the following statement:

loadImage("test.png")

... will first attempt to load <your sketch dir>/data/test.png; if it's not found there, Processing will try to load <your sketch dir>/test.png.

An additional wrinkle with Processing.py is that Python's built-in open() function has been modified to follow these same rules. So the following statement:

open("foo.txt").read()

... will attempt to open a file named foo.txt inside a data subdirectory as well. (If it can't find the file in the data subdirectory, it will default to Python's normal behavior of looking for the file in exactly the path specified.)

Note: For compatibility purposes, and to avoid any unusual behavior when your sketch is bundled as a standalone library, we recommend keeping your external media in the data subdirectory.

External libraries

Just like Python Mode in the Processing IDE, Processing.py on the command line can make use of third-party libraries.

Processing libraries

Processing (the vanilla Java version) has a rich library of third-party contributed libraries. The Processing IDE has a helpful "Add Library" feature that allows you to locate, download and use these libraries in your project using a GUI interface. Of course, on the command line, that option isn't available to you! So here's what you do:

• Make a subdirectory called 'libraries' in the same directory as your sketch file.
• Download the Processing library that you want to use. Depending on the library, it can sometimes be tricky to find the right file to download. The Processing Wiki has good advice on how to identify the appropriate file and how to find the relevant files within that repository
• Extract the library's archive file (usually a ZIP file) and copy the resulting directory into the libraries subdirectory that you just created.

If you're having trouble locating the right file to download for a particular library, there's a helpful alternative technique. Use the Processing IDE's "Add Library" feature to download and install the library for use in the IDE. Then find the folder where the IDE keeps the libraries you've downloaded by going to the IDE's Preferences panel and clicking the "Browse" button next to the "Sketchook Location" field. Take a look inside the libraries subdirectory and you'll find all of the Processing libraries that you've added to the IDE. To add any of these libraries to your Processing.py sketch, simply copy the library's entire directory Processing.py's libraries subdirectory.

Once you've copied the files to the correct location, use Processing.py's add_library() function to import the library, putting the name of the library as a string literal as the parameter to the function call.

For example, to use the Processing Sound library, download the ZIP file from the repository's "releases" page. Unzipping the file should result in a directory called sound; copy this to the libraries subdirectory for your sketch. Once the files are in the right location, put this function call at the top of your sketch:

add_library("sound")

Python code

Use the import keyword to use external Python modules in your sketch. For code that you've written, the import keyword works the same as it does in vanilla Python: import foo will first attempt to load the code in foo.py (or a package in a subdirectory named foo) in the same directory as the sketch, and then will attempt to load a module with that name from the standard library.

It's important to note that Processing.py uses the pre-packaged Jython standard library, and (by default) can't see or use any of the Python libraries in your own system installation of Python. See this tutorial on using Python libraries in Processing.py for more information. Because Processing.py is built with Jython, it might also be helpful to consult Jython's documentation on modules and packages.

Other Java libraries

Processing.py is built with Jython, which is built with Java, which means you can also regular Java libraries in your Processing.py sketches. (This is true whether you're using Python Mode in the IDE or Processing.py from the command line.) Just for starters, all of the Java standard API is available to you; here's a sample sketch that opens a Swing window:

from javax.swing import JFrame

def setup():
    size(400, 400)
    frame = JFrame("Simple Test", size=(200, 200))
    frame.setVisible(True)

def draw():
    background(0)

Consult the Jython Book's chapter on modules and packages for more information.

You can also use third-party Java libraries. The easiest way to do this is to download the library's JAR file and put it in the same directory as your Processing.py sketch. (The command-line launcher for Processing.py automatically adds whatever JARs it finds in the sketch's directory to Java's classpath.) A forthcoming tutorial will show a full example of using a Java library in a Processing.py sketch.

Command-line parameters and environment variables

Unfortunately, the way that the Processing.py command-line launcher is written makes it impossible to supply extra parameters to your script on the command line. As a workaround, you can use environment variables. For example, here's a sketch that reads the environment variables ELLIPSE_SIZE_X and ELLIPSE_SIZE_Y with Python's os library and uses them to initialize the size of an ellipse in the sketch:

import os
ellipse_size_x = int(os.environ['ELLIPSE_SIZE_X'])
ellipse_size_y = int(os.environ['ELLIPSE_SIZE_Y'])
def setup():
    size(400, 400)
def draw():
    background(0)
    fill(255)
    ellipse(width/2, height/2, ellipse_size_x, ellipse_size_y)

On the OS X or Linux command line, you can set the environment variables and run the sketch simultaneously by typing something like this (assuming you've put the code above in a file named env_params.py):

$ ELLIPSE_SIZE_X=100 ELLIPSE_SIZE_Y=150 java -jar processing-py.jar env_params.py

Moving a project from the IDE to the command line (and vice versa)

You can run any sketch you create in the Processing IDE on the command line. To do this, you'll first need to find the directory on your computer where the sketch files are using the "Show Sketch Folder" option in the "Sketch" menu of the IDE. Copy the processing-py.jar file to this directory and then navigate to the directory on the command line. (In OS X, the easiest way to do this is by typing cd in the Terminal window, followed by a space, and then dragging the folder from the Finder to the Terminal window and then hitting "Return.")

After you've done this, run the Java interpreter as you would for any command-line Processing.py sketch. The filename to supply on the command line is the main .pyde file of the sketch. So, for example, if your sketch from the IDE is called wonderful_python_sketch_yay you might type the following to run the sketch from the command-line:

$ java -jar processing-py.jar wonderful_python_sketch_yay.pyde

If you have an existing Processing.py sketch that you wrote on the command line, it's possible to "import" it back into the Processing IDE. For short sketches, the easiest way to do this is probably to just copy and paste the source code into a new Processing IDE project. For more sophisticated sketches, you can create a sketch in the format the IDE expects "by hand" using the following steps:

• Rename the main Python file of your sketch to have a .pyde extension.
• Make sure that the name of the directory that the .pyde file is in exactly matches the name of the .pyde file itself. (E.g., if your sketch is called foo.pyde, the directory it's in should be called foo).
• In the Processing IDE, use the File > Open menu option and navigate to the directory with your sketch. Select the .pyde file and click "Open."

Building a standalone application

The command-line version of Processing.py has had, in the past, a feature to create a standalone application bundle. Unfortunately, as of this writing this feature is broken on some platforms. For now, the easiest way to create a stand-alone application with a command-line Processing.py sketch is to import it into the Processing IDE (as outlined in the previous section) and use Python Mode's "Export Application" feature, which works just fine.

This tutorial is for Processing's Python Mode. If you see any errors or have comments, please let us know. This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.