How to Use Processing Libraries

How to Use Processing Libraries#

This is an introduction to py5’s integration with Processing Libraries.

Processing Libraries#

Processing offers a collection of community maintained libraries, implemented in Java, that can add extra features to a Processing Sketch. Because py5 is built around the Processing Java code, these community maintained libraries can in theory work with py5. In reality, not all of them work perfectly with py5, but with a bit of effort and experimentation one can often use many of them productively in a py5 Sketch.

Managing Libraries#

The first step is to download and install a Processing Library. The easiest way to do this is with py5’s built in tools for managing Processing Libraries. Start with the py5_tools.processing.download_library() function to download a few Processing Libraries.

import py5_tools

py5_tools.processing.download_library("PeasyCam")

{'name': 'PeasyCam',
 'version': '302',
 'prettyVersion': '302',
 'downloadDate': datetime.datetime(2025, 4, 18, 0, 18, 4),
 'dir': 'peasycam'}

py5_tools.processing.download_library('JavaFX')

{'name': 'JavaFX',
 'version': '1280',
 'prettyVersion': '4.0 beta 5',
 'downloadDate': datetime.datetime(2025, 5, 7, 18, 47, 18),
 'dir': 'javafx'}

You can use the py5_tools.processing.library_storage_dir() method to get the location of where these libraries are stored. This location is comparable to where other Python libraries will store downloaded files.

py5_tools.processing.library_storage_dir()

PosixPath('/home/jim/.cache/py5/processing-libraries')

The default location of this directory for Windows users is in the AppData/Local/py5/processing-libraries subdirectory of your home directory. For Linux and MacOS users, it is in your .cache/py5/processing-libraries subdirectory. If you’d like to move this someplace else, set the PY5_HOME environment variable to your preferred location.

This directory is intended to be a place that py5 maintains, so please don’t directly add, edit, or remove files from this directory. If you have your own jar files you’d like to add to a Sketch, put them in a jars subdirectory relative to the current working directory of your Python code. Or use the PY5_JARS environment variable to point to a directory of jar files that you manage yourself.

To get a list of currently installed libraries, use py5_tools.processing.installed_libraries().

py5_tools.processing.installed_libraries()

['PeasyCam', 'ColorBlindness', 'Camera 3D', 'JavaFX']

You can use py5_tools.processing.remove_library() if you want to remove a previously installed library. Use py5_tools.processing.check_library() to test if a library has already been installed, although calling py5_tools.processing.download_library() multiple times is also acceptable. It won’t re-download a library if py5 sees that it has already downloaded the most recent version.

if not py5_tools.processing.check_library("PeasyCam"):
    py5_tools.processing.download_library("PeasyCam")

Using Processing Libraries#

Once your Processing Library has been installed, you can import py5 and begin your Sketch code. Importing py5 will add the installed Processing Libraries to the classpath. This can only be done once, so if you want to install anything else later, you’ll need to restart your Python session.

import py5

For this PeasyCam example, our next task is to import the PeasyCam Java class. JPype makes this easy to do and very much like regular Python imports.

from peasy import PeasyCam

Now, our actual Sketch code.

def setup():
    py5.size(500, 500, py5.P3D)
    PeasyCam(py5.get_current_sketch(), 500)

def draw():
    py5.background(128)
    py5.box(200)

In this example, the PeasyCam(py5.get_current_sketch(), 500) code will link a PeasyCam instance to the py5 Sketch. Everything else is typical py5 code.

Our last step is to run the Sketch and admire our work:

py5.run_sketch()

JavaFX#

The tools described on this page provide an avenue for using Processing’s JavaFX renderer. The code and libraries for JavaFX are quite large so they must be installed separately.

Once installed, you can use the JavaFX renderer. It provides excellent 2D graphics without the use of OpenGL.

def setup():
    py5.size(500, 500, py5.FX2D)

def draw():
    py5.rect(py5.mouse_x, py5.mouse_y, 10, 10)

py5.run_sketch()

JavaFX Limitations#

JavaFX with py5 has some known limitations.

Unfortunately, JavaFX doesn’t currently work with py5 on Windows machines. It should work, and maybe someday this will be fixed. It would be great if someone would help with this.

With JavaFX you are limited to running one Sketch per Python session. For a Python script this is irrelevant but you might not want to use JavaFX in a Jupyter Notebook, where you would typically run multiple Sketches. In addition, on MacOS the JavaFX Sketch window might not get focus when run from a Jupyter Notebook, which is a nuisance. Other than that, this library seems to work just fine with py5.

Contents