12-1 Libraries

Whenever you call a Processing function, such as line(), background(), stroke(), and so on, you are calling a function that you learned about from the Processing reference page (or perhaps even from this book!). That reference page is a list of all the available functions in the Processing’s core library. In computer science, a library refers to a collection of “helper” code. A library might consist of functions, variables, and objects. The bulk of things you do are made possible by the core Processing library.

In most programming languages, you are required to specify which libraries you intend to use at the top of your code. This tells the compiler (see Chapter 2) where to look things up in order to translate your source code into machine code. If you were to investigate the files inside of the Processing application itself, you would find a file named core.jar. That file contains the compiled code for just about everything you do in Processing. Since it’s used in every program, Processing just assumes that it should be imported and does not require that you explicitly write an import statement. However, if this were not the case, you would have the following line of code at the top of every single sketch:

import processing.core.*;

import indicates you are going to make use of a library, and the library you using is “processing.core” The “.*” is a wildcard, meaning you would like access to everything in the library. The naming of the library using the dot syntax (processing dot core) has to do with how collections of classes are organized into “packages” in the Java programming language. As you get more comfortable with Processing and programming, this is likely a topic you will want to investigate further. For now, all you need to know is that “processing.core” is the name of the library.

While the core library covers all the basics, for other more advanced functionality, you will have to import specific libraries that are not assumed. Your first encounter with this will come in Chapter 16, where in order pull images from a camera, the Processing video library will be required:

import processing.video.*;

Many of the chapters that follow will require the explicit use of Processing libraries, such as video, networking, serial, and so on. Documentation for these libraries can be found on the Processing website libraries page (http://www.processing.org/reference/libraries/). There, you will find a list of libraries that come with Processing, as well as links to third party libraries available for download on the web.

12-2 Built-in libraries

Some built-in libraries require no installation process. These libraries come with your Processing application. The list of built-in libraries (full list available at above URL) is not terribly long and the following libraries are covered in this book. The last two (video and sound) require a separate installation process as described in the next section.

• Serial — For sending data between Processing and an external device via serial communication. Covered in Chapter 19.

• Network — For creating client and server sketches that can communicate across the internet. Covered in Chapter 19.

• PDF — For creating high resolution PDFs of graphics generated in Processing. Covered in Chapter 21.

• Video — For capturing images from a camera and playing movie files. Covered in Chapter 16.

• Sound — For sound analysis, synthesis, and playback. Covered in Chapter 20.

Examples specifically tailored toward using the above libraries are found in the chapters listed. The Processing website also has superb documentation for these libraries (found on the “libraries” page). The only generic knowledge you need regarding Processing built-in libraries is that you must include the appropriate import statement at the top of your program. This statement will automatically be added to the sketch if you select Sketch → Import Library. Or, you can simply type the code in manually (using the import library menu option does not do anything other than just add the text for the import statement).

import processing.video.*;

import processing.serial.*;

import processing.net.*;

import processing.pdf.*;

import processing.sound.*;

12-3 Contributed libraries

The world of third party (also known as “contributed”) libraries for Processing resembles the wild west. As of the writing of this book, there are 113 contributed libraries officially listed on the Processing site, with capabilities ranging from physics simulation to packet sniffing to computer vision to generative text to GUI controls. Online searches will reveal probably another hundred more not listed (and possibly not compatible with current versions of Processing). I’ll discuss the code for several contributed libraries during the course of the remainder of this book. For now, let’s focus on installing libraries themselves.

The process for installing a contributed library is the same as for installing the Processing Foundation libraries video and sound. I’ll use video as an example below. The first step is to open the Processing contributions manager. This can be accessed by the menu option Sketch → Import Library → Add Library.

Figure 12-1

This will reveal the Library Manager. There, you can search through the list of libraries to find the one you’re looking for. You can filter the list by category or by typing into the search box. For example, I can quickly find the Processing Foundation video library by typing “video”.

Figure 12-2

To install a library, simply press the “install” button and wait for the library to download. That’s all! While it’s not required, if you run into issues, try re-starting Processing after installing. You can also update libraries through the manager if and when an update is released. You can check which libraries have updates available with the Library Manager.

12-4 Manually installing libraries

I hesitate to even include this section given that the recommended way to install a library is through the manager. And all libraries listed in the manager have been tested by the Processing Foundation. However, there are some useful libraries that you might find online that are not listed. These have to be installed through a manual process. To do so, the first thing you need to do is find your sketch folder. On a Mac, this is typically /Documents/Processing/ and on a PC, C:/Documents/Processing. If you’re not sure you can always check via the Processing preferences.

Figure 12-3

Once you have determined the sketch folder location, find the subfolder named “libraries”

The libraries directory is where you can manually install contributed libraries. A library is just a directory of files and assuming you’ve found one you’d like to download, it will most likely arrive as a zip file. Once you’ve got the file, follow the instructions below, referencing Figure 12-4.

Figure 12-4

1. Extract the ZIP file. This can usually be accomplished by double-clicking the file or with any decompression application, such as Winzip on a PC.

2. Copy the extracted files to the libraries folder. Most libraries you download will automatically unpack with the right directory structure. The full directory structure should look like this: libraries/libraryName/library/libraryName.jar
Most libraries include additional files such as source code and examples. If the library does not automatically unpack itself with the above directory structure, you can manually create these folders (using the finder or explorer) and place the libraryName.jar file in the appropriate location yourself.

3. Restart Processing. If Processing was running while you performed Step 2, you will need to quit Processing and restart it in order for the library to be recognized.

Whether you installed the library manually or through the contributions manager, if it’s working properly it should now now appear in the list under the “Sketch → Import Library” option shown in Figure 12-5. What to do once you have installed the library really depends on which library you have installed. Examples that make use of code in a library can be found in Chapter 16, Chapter 18, and Chapter 20.

Figure 12-5

Although it’s a topic beyond the scope of the book, you can also create your own Processing libraries. Instructions and information for how to do so can be found in the Processing github repository (https://github.com/processing/processing/wiki/Library-Overview). Finally, in addition to libraries, the Processing development environment (“PDE”) itself can be extended with tools and modes. Tools provide smaller features to the PDE and modes offer radical large changes (like writing your code in an entirely different programming language!). These can be installed with the contributions manager as well and live in the “tools” and “modes” subdirectories of your sketchbook.