Modified: 01/25/2008, Created: 11/12/2007
This Quick Start Guide will demonstrate how to create, build and run two Processing sketches written in Groovy incorporated into a project that uses Maven to build. According to the book "Groovy in Action", Groovy can be run in either direct mode or precompiled mode . In this guide, one Groovy script will be compiled to a Java class file (precompiled mode) and the other Groovy script will be left uncompiled (direct mode).
Many Professional Java programmers are already familiar with Maven or Eclipse. This article has the goal of introducing Java and Groovy programmers to using Processing (graphics library) and introducing Groovy, Maven and Eclipse to Processing coders.
I propose that Processing , Groovy and Maven all working together would have the following benefits.
Benefits: One Can...
Cons:
Below is a Java Applet that was generated via export from the Processing IDE.
TODO add applet code here
NOTE: This document will refer to Processing as Processing.org occasionally because Processing as a word is common in computing lingo and Processing.org is more specific and will be more easily found in web search engines.
Processing is like a DSL (Domain Specific Language) for making art images. It was designed to teach programming to artists and art image making to programmers. Processing is a Free and Open Source graphics library that also comes with an Integrated Development Environmemt (IDE) called the Processing Development Environment (PDE). Processing has also incorporated several third party libraries. Processing has its roots in the MIT Media Lab . Processing has been used to code applications displayed in art exhibits. Here is a list of books concerning Processing: "Processing: A Programming Handbook for Visual Designers and Artists" by Casey Reas and Ben Fry, "Visualizing Data" by Ben Fry and "Processing: Creative Coding and Computational Art" by Ira Greenberg.
Processing calls the apps it creates "sketches". The sketches can be animated or static, interactive or non-interactive, 2-D or 3-D. Processing can build both Java Applets with a minimal html web page and standalone applications. You can code your Processing sketches in either "pde" (pseudo Java) or Java. The "pde" format looks very Java-like and is actually used to generate Java source files that are then compiled and optionally packaged into a jar file when exported. Processing's libraries are regular Java "jar" files and thus can be accessed from outside the PDE application. Processing's libraries are written in Java and thus can be used from Java and Groovy. Processing has an excellent reference guide and examples with source code.
Here is an example web page with Java Applet that can be quickly built with the Processing IDE.
Groovy is a dynamic scripting language with Java like syntax that can call out to Java libraries and optionally be compiled into Java class files. Groovy runs on the JVM (Java Virtual Machine). Groovy is like Fast Food Java or Java++. Groovy has syntax support for Lists, Maps, Ranges, Closures, and Regular Expressions. Groovy also has an advanced switch statement, operator overloading and conveniences for writing JavaBeans.
It should be noted that uncompiled Groovy scripts run slower than compiled Java programs.
Maven is becoming the standard way to build Java based projects. It can manage the library dependencies of your project. Maven has a standard directory layout that eases understanding where files are located when moving from one Maven project to another. Maven can also generate a quick and dirty development web site. There is a Groovy plugin that will allow Maven to compile Groovy scripts into Java class files during the build process.
Eclipse is a free Integrated Development Environment (IDE). Many professional Java programmers use Eclipse at work. Processing comes with an IDE called the Processing Development Environment (PDE). The PDE is helpful during your first exposure to Processing; however, professional Java and Groovy coders will probably want to switch over to an industrial strength IDE and editor that they are already familiar with such as Eclipse.
The PDE will still be needed to create Processing font files.
In my experiments of writing Java Applets with Groovy (even when compiled), I received a java.security.AccessControlException . To get rid of such an exception, I assume one would need to configure security settings and/or sign the Applet. I really did not want to get into doing either security configuring or signed Applet stuff at this time; so, for now I am limiting myself to launching the Processing sketches from the command line.
See URLs:
If you want a limited form of Compiled Groovy Applet shown locally at your Desktop in a web browser, see this link
For this Quick Start, you must do the optionally listed step:
"...if you need the dependency lib files to be available after the build, add the following section to the pom.xml file within your <build><plugins> tag"
In this Quick Start Guide, I named the Maven project groovy-and-processingorg and thus the Maven project's root directory is named groovy-and-processingorg .
As an example, I would use the following command to generate the project's initial files and folders.
mvn archetype:create -DarchetypeGroupId=org.codehaus.mojo.groovy -DarchetypeArtifactId=groovy-maven-archetype -DgroupId=com.mycompany.app -DpackageName=com.mycompany.app.mygroovymodule -DartifactId=groovy-and-processingorg
NOTE: From this point on, it is assumed that all command line commands are issued while being in the Maven project's root directory. In our case this is groovy-and-processingorg .
The primary library file provided by Processing is named "core.jar". (More advanced Processing applications may need other jar files.) In order to write Processing sketches (art work applications), you will need to at least include Processing.org's core.jar in your classpath. When using Maven, this means you will need to set up a dependency on Processing.org's core.jar file.
As far as the author knows, Processing.org's core.jar is not in a public Maven repository. This means that you will need to download and install Processing in order to get a hold of the Processing jar files. (It is the author's opinion that the Processing developers would be open to the idea of placing the "core.jar" file in a public Maven repository, if one would provide explicit instructions or an automated procedure to do it.)
Adjust the following instructions to wherever you installed Processing.
Issue the following commands (adjusting the version value to whatever version of Proccessing you downloaded):
C: cd C:\dev\tools\processing-0135-expert\lib mvn install:install-file -DgroupId=org.processing -DartifactId=processing-core -Dversion=0135-BETA -Dpackaging=jar -Dfile=core.jar
Then add the following dependency section within your pom.xml files dependencies tag
<dependencies>
...
<dependency>
<groupId>org.processing</groupId>
<artifactId>processing-core</artifactId>
<version>0135-BETA</version>
</dependency>
...
</dependencies>
mvn eclipse:clean eclipse:eclipse
Processing requires resource data files such as fonts (as special *.vlw files) or images to be in a folder named data located in the same folder as the sketch program.
See: http://processing.org/reference/environment/index.html
If you have any resource files to be used in your Processing sketches, create a folder named "data" at
src/main/resources
For example, if you have one font file named "FranklinGothic-Medium-48.vlw", the path should be
src/main/resources/data/FranklinGothic-Medium-48.vlw
mkdir src\main\resources\data
to
src/main/resources/data/
Processing's primary file extension is *.pde. The *.pde file format allows the user to code using the Processing DSL. When an "export" action is performed in the Processing IDE (PDE), the *.pde file is used to generate a *.java file of the sketch. This *.java file is a great place to study who to write a Java file that uses the processing API. In the same way, the *.java file is also a great place to examine how to write a Groovy version of the file.
Change
static public void main(String args[])
{
PApplet.main(new String[] { "sketch_071112a" });
}
to
static void main(args)
{
PApplet.main([ "sketch_071112a" ] as String[]);
}
Where sketch_071112a is the name of your sketch.
Here is a sample Processing Sketch source code written in Groovy.
A listing of the file is shown below.
File: sketch_071112a.groovy to be placed at src/main/groovy
import processing.core.*;
public class sketch_071112a
extends PApplet
{
// global variables
public PFont font;
public int a = 0;
public void setup()
{
size(200, 200);
background(0);
noStroke();
// The font must be located in the sketch's
// "data" directory to load successfully
font = loadFont("FranklinGothic-Medium-48.vlw");
textFont(font, 32);
}
public void draw()
{
background(0);
fill(102);
rect(a++%width, 10, 20, 80);
fill(250);
// draw text/font stuff
text("word", 15, 50);
}
static void main(args)
{
PApplet.main([ "sketch_071112a" ] as String[]);
}
}
The above file will be compiled to a Java class file when we build the project.
Now lets create a similar Processing sketch written in Groovy but leave it uncompiled.
This file we will not be compiled and stay a Groovy script.
This file we will not be compiled and stay a Groovy script.
Here are the contents of the helper Groovy Script named runart.groovy .
import processing.core.*;
import javax.swing.*
import java.awt.*;
import groovy.swing.SwingBuilder
import java.awt.BorderLayout as BL
// pseudo main begins here
if (args.size() > 0 && args[0] != null)
{
String strGroovyFileExtension = ".groovy"
String strProcessingSketchFileName = args[0]
if (strProcessingSketchFileName.indexOf(strGroovyFileExtension) == -1)
{
strProcessingSketchFileName += strGroovyFileExtension;
}
def embed = runart.getClassLoader().parseClass(new
java.io.File(strProcessingSketchFileName)).newInstance()
SwingBuilder swingBuilder = new SwingBuilder()
JFrame frame = swingBuilder.frame(title:"", layout: new BL()) {
}
frame.add(embed, BorderLayout.CENTER);
// important to call this whenever embedding a PApplet.
// It ensures that the animation thread is started and
// that other internal variables are properly set.
embed.init();
frame.setDefaultCloseOperation(WindowConstants.EXIT_ON_CLOSE)
frame.pack()
frame.setVisible(true)
println "DONE"
}
else
{
println "ERROR: processing_sketch_filename not provided"
println "usage: runart <processing_sketch_filename>"
}
Now let's build (and package) the project.
mvn clean package
The file src/main/groovy/sketch_071112a.groovy will be compiled and become target/classes/sketch_071112a.class
The file src/main/resources/sketch_071112a_groovy.groovy will be copied to target/classes/ and become target/classes/sketch_071112a_groovy.groovy
If you followed the steps correctly when editing the pom.xml file, you will also have your jar file dependencies (such as processing-core-0135-BETA.jar) in target/lib .
java -cp target/classes/.;target/lib/processing-core-0135-BETA.jar;target/lib/groovy-all-1.5.1.jar sketch_071112a
Where sketch_071112a is the name of your sketch.
groovy runart <processing_sketch_filename>
groovy -cp "target/classes;target/lib/processing-core-0135-BETA.jar" target/classes/runart target/classes/sketch_071112a_groovy
or
cd target/classes groovy -cp ".;../lib/processing-core-0135-BETA.jar" runart sketch_071112a_groovy
Where sketch_071112a_groovy is the name of your sketch.
Draw, using the mouse, circles of random sizes.
Dots appear and then shrink in size. This sketch uses the Groovy List and uses a second class SpriteEllipseInternal.
Dots appear and then shrink in size. This sketch uses the Groovy List and uses an external second class SpriteEllipse.
Draw disappearing dots. This sketch uses the Groovy List and uses an external second class SpriteEllipse.