Learning Processing 3 Intermediate

Introduction

Workshop Synopsis:

This tutorial has been designed for a two-part full-day series of workshops at the University of Kent, which will provide students with an introduction to the Processing computer language. The first day you will be introduced to core programming terminologies, by coding basic programs, or sketches as they are referred to within Processing, demonstrating how programs are comprised of ‘syntax’, ‘functions’ and ‘data’ with a focus on how to draw 2D shapes. The first workshop will provide a foundation to move onto more advanced programming concepts. Click here to read the first workshop!

In the second workshop we will move towards three dimensions and learn how to make previously inanimate objects on a screen, interact with one another, act on individual rules and group behaviours, thus developing autonomous agents which can produce emergent ‘architectural’ forms. We will also briefly cover interaction with external data sources.

Workshop 2: Introducing Multiple Objects, 3D, Vectors and Agents

Workshop Two is a direct continuation of Workshop One: Learning Processing 3, if you’ve not followed from the beginning I would highly suggest you start with Workshop One, before continue to Workshop Two.

In this workshop we will extend what we’ve covered thus far to introduce more complex programming concepts such as arrays, which will allow us to create hundreds, even thousands of objects and we will no longer be confined to two dimensions as we will now explore how to draw in three dimensions. From here we will introduce vectors and forces which will form the foundation of calculating the motion of objects know as agents, which interact with one another as they move through space.

1. Arrays: Many Elements

The first lesson of Workshop Two will introduce a new core programming terminology and concept know as arrays. We will use arrays to extend the final Processing Sketch we developed in Workshop One, in which we constructed a class which describes a box.

Within Processing there are two principle types of arrays: fixed length arrays and variable length arrays, to begin we will investigate the former and some permutations of fixed length arrays such as first for lists and for lists. After that we will move to variable length arrays which will allow us to add arbitrary number of boxes to the canvas, without us having to repeat code unnecessarily.

Following this we will introduce dynamic motion in the form of a simulated gravitational field, facilitating our rotating boxes to ‘orbit’ around one another.

Key programming concepts:

Arrays, ArrayLists, enhanced loops and classes

1.1 Introduction

Following on from Workshop One’s last lesson: Introducing Classes (OOP) where we finally gained full control over each of our boxes and where each box was truly independent from one another, we will now look at solving a remaining limitation of that sketch, which was the limited number of boxes which we could create, without duplicating code. To create another box we needed to add code: each box required a call to its: ‘constructor’, ‘draw’ and ‘mousePressed’ function. Suppose we need 30 boxes this would require 30 lines of code multiplied by 3, or a total of 90 new lines. To solve this, would it not be simpler have a list of some sort to store each box and then be able to tell Processing once to call the ‘draw‘ function for all the boxes in said list. For this, there are arrays. We can iterate through the array, and access each element by integer position, from 0 to how ever many elements there are in the array. One important point to note, is that all arrays usually start from 0, or in other words the ‘data’ contained at the beginning of the array is at position (index) 0, this is one of the reasons we start ‘for‘ loops from 0.

By using arrays we can in fact have boxes which interact with other boxes, by passing array members (in this case boxes) to each other as a parameter. We will do just this to create a gravitational attraction, between each and every box.

1.2 Fixed Length Arrays

You can think of an array essentially as a list, which can be cycled through — therefore we can store a series of data elements as a single name: shoppingList: pasta, tomatoes, zucchini, eggs, potatoes, beer, etc…

A ‘for‘ loop will be used to cycle through each array element in sequence and an element can be accessed by referring to its position (index) within the list. Take the above shoppingList as an example, if I wanted to refer to eggs I would refer to its index: 3. Later, I will also introduce a new type of ‘for‘ loop, know as an ‘advanced for loop’ which is useful when we want to make reference to a single element within an array.

Using an array will also simplify drawing, as you don’t need to write the  parameters for each rectangle and apply whatever function we want to make the rectangle do something every time, thus making the processes of coding easier or at least reducing how much code we need to write.

1.2.1 Fixed Length Arrays Of Integers

Lets look at the following task: create 10 squares of different sizes and display them on the canvas. We can use an array when we have a list of information. To solve this task we could write the following in Processing:

As you can see there is a sizeable amount of repetition in the above code. It would be better if we could create a list of 10 different square sizes, and then draw the squares using a loop.

We can proceed as so, firstly we need some code to define our array of square sizes:

Let’s analyse the above syntax. The ‘int[]‘, declares this as an array (‘[]‘) of type integers. The ‘=‘ immediately assigns the array with a list, which is specified using curly brackets. Notice the differences between this and a straight declaration of an integer: int x = 3; and int[] x = {0,1,2,3};. We can access an element within the array by using the index of that element. We start by counting at 0, so the 0’th element in ‘squaresizes’ is 10, the 1’st is 5 and so forth. To obtain an element from the array in Processing, we make use of square bracket notation. For example, to draw the first square in the list, we would write:

We can also mix array elements by using alternative index, for example to make a thin tall rectangle:

Notice how we write the variable name ‘x‘ followed by the index of the element we want contained between square ‘[]‘ brackets. We don’t have to use a constant value between the square brackets either, we could in fact use another variable. This is how we will combine a ‘for‘ loop with our array to draw 10 boxes using the sizes we’ve specified in the array. Our loop index ‘i‘ will begin at 0, as usual, and count to 9, as so:

Notice in the above how we’ve reduced out initial code from 20 lines down to 5 lines of code. Also don’t forget that for each loop we need to include the ‘translate‘ function to cumulatively shift each box 10 pixels to the right.

In addition to allowing us to access different elements in the array, arrays (like String) have some special data associated with them. One you will frequently make use of is ‘length‘. These can be accessed using the dot notation, just as we would for class member functions and variables. The array ‘length’ is a query-type function and returns the length (or how many elements are in the array). To use ‘length()‘ we append it to the name of our array variable, as so: ‘x.length‘.

We can update our code to use the array length to determine how many times our loop should occur, which further allows us to change how many elements we include in the array. For example:

Notice how the above code works. The loop counts from 0 up till the value which ‘x.length‘ returns, in our case 5, less one due to the less-than operator. Our array has 5 elements, so the loop counts from 0 to 4, ensuring each element of the array is drawn on the canvas.

1.2.2 Fixed Length Arrays Of Classes

We are not only limited to arrays which contain integer elements. Like any variable, we can create arrays which store any type, or, better yet any class. Therefore, if we need to create an array of boxes, we can use a similar syntax.

Firstly, we will need the the rotating box class from the previous workshop. I’ve included the code bellow, which you can copy and past into Processing. Note there are some minor alterations to the code allowing us to pass even more parameters than before, see lines 15 and 16:

We’re now going to focus on the Main Code tab and instead of initialising each box one at a time, each with their own variable, we can list each box within an array as we’ve done previously with integers:

Whilst the above line looks rather intimating, it’s actually no more difficult than what we’ve already seen. The method to construct each new box in the list is exactly as it was in the last Workshop: each box must be declared as a ‘new’ instance of the Box class and each one has five parameters (x, y, size, spin speed and spin state). This list of new boxes is then encapsulated between braces ‘{‘ and ‘}‘, and the declaration changed to indicate that the array is of type Box (‘Box[]‘) rather than for a singular Box.

We may encounter situations where we needing to assign the elements of our array within the ‘setup‘ function, rather than as part of a global variable. In order to do so we need to write the following:

Notice the difference between declaring and assigning the ‘boxes‘ array in a single line compared to assigning the elements to it within ‘setup‘. We firstly define the variable (array) we will assign the boxes to using  ‘=‘, followed by ‘new Box[]‘ and lastly we encapsulate the list of new boxes between curly brackets.

Now that we’ve setup our array to contain two boxes, we can use it in the same way we have previously used an integer array, as so:

1.3 ‘Variably‘ Fixed Length Arrays

While in some cases you know beforehand what the data you require is prior to writing your code (as was demonstrated in the array of squares), in most cases you do not (for example, if you are loading in many shapes from a file). Furthermore, you may not even know how many items you want in your array before you start.

In order to demonstrate this lets change the declaration of the ‘boxes‘ array at the start of your sketch:

Also make sure to comment out the following line, temporarily, which will help to demonstrate more accurately what the new array declaration code above actually does:

Note that ‘new Box[30]‘ does not create any boxes, it simply tells Processing that the ‘boxes‘ array should contain 30 slots for Box type elements. If you run the sketch now it will crash, generating the following error:

Null Pointer Exception

This is most likely your first encounter of a memory error. Until now, every error we’ve encountered will have been a syntactic error. That is, a typo, a call to a function misspelled and so on. A memory error is a different, and a far more nefarious error. The syntax of the sketch as it stands is perfect, but because we have only created an empty list (series of containers) to place Box objects into, rather than the Box objects themselves, when we come to use them, in the ‘draw‘ function and the ‘mosuePressed‘ function, Processing finds a nothing object, a ‘null’, and it crashes. The problem with memory errors is that they can be very difficult to find: we may forget to initialise boxes but only use them many lines later. Notice how the above ‘Null Pointer Exception’ provides no indication of where the error occurred, therefore, finding out what went wrong can be very tricky.

That’s the gist of memory errors, just remember the ‘Null Pointer Exception’ as a clue that you have a memory error (usually a variable or array which has not been assigned any ‘data’ before it was used). Now let us move onto fixing this problem. We’ve stated that the array should contain 30 elements, thus we need to create 30 new boxes to fill our array. In order to achieve this, we change the ‘setup‘ function. Note, it must be the ‘setup‘ function in order that the boxes are initialised before they are used in the ‘draw‘ function.

The initialisation code will now look like this:

I have used a function we’ve not used often before, ‘random‘. When called with a single parameter, as in the ‘random(width)‘ the function creates a random floating point number between 0.0 and 100.0. The two calls to ‘random(width)‘ and ‘random(height)‘ create (different) random x and y coordinates for each box. Next, when ‘random‘ is called with two parameters, as in random(5, 25), it generates a random float from 5.0 to 25.0. I’ve used this so we only get boxes of a reasonable size: larger than 5 pixels yet, smaller than 25 pixels. Lastly to create a random boolean (true of false) to control the spinning state of the box, I’ve created my own function: ‘randomBoolean‘. Processing unfortunately has no shortcut method to create a random boolean, therefore we need to write this logic ourselves and encapsulate it within a function. This is also the first example, of a custom function which returns a value, which we’ve encountered so far.

The code for our ‘randomBoolean’ function is as follows:

Our ‘randomBoolean’ function won’t require any parameters, but it needs to return either a true or false value. To do this we remove the word ‘void‘ from the beginning of the function name and replace it with ‘boolean‘ which indicates that the type of data which the function will return is a boolean. Inside of our function we can write our logic in a single line, which is similar to the probability code we wrote in Workshop One: 3.8 Code Challenge (10PRINT). We simply tell processing to ‘return‘ the result of the condition ‘random(1) < 0.5‘. This results in a 50% probability of either a true or false value being returned.

There is an argument, that for every call to the ‘randomBoolean’ function we should first randomise the probability before the condition statement, thus for each call the probability won’t always be 50% and therefore our randomisation is more random. However, this is not particularly necessary right now.

We can of course also use a variable to set the size of the array when we declare it:

1.4 Variable Length Arrays: ArrayLists

Before we proceed I need to introduce a completely new type of array, known as an ‘ArrayList‘. Whilst the previous ‘fixed length arrays‘ (standard ‘array‘) are useful, as we start exploring more complex projects involving many objects and in which we are constantly adding and removing objects (hence adding and removing elements of an array), fixed length arrays will cause more challenges, which can be negated by using the more flexible ‘ArrayList‘.

In essence an ArrayList stores a variable number of objects. This is similar to making a standard array of objects, however, with an ArrayList, items can be easily added and removed from the ArrayList and it is resized dynamically. This will prove very convenient, though it’s slower than making an array of objects when using many elements, but, more suited towards arrays containing classes-objects, such as our Box class, as it has many methods used to control and search its contents. These include:

• size() method — used to get the length of the ArrayList, returned as an integer value for the total number of elements in the list.
• add() method — used to add an element to ArrayList, added at the end of the array by default.
• remove() method — used to remove an element from an ArrayList.
• get() method — used to return an element at the specified position in an ArrayList.

We are now going to convert our code from using a standard array to an ArrayList, from here we will include a function which allows us to add rotating boxes by clicking on the canvas. Firstly we need to change the declaration from a standard array to an ArrayList, which can be achieved as follows:

Let’s take a look at the syntax of the code above in order to determine what each part means. Firstly we write ‘ArrayList‘, which tells Processing that we are declaring an ArrayList, and takes the place of our previously used square brackets ‘[]‘ which indicated that we were creating a standard array. Also note that we write ‘ArrayList‘ at the start rather than after the type declaration. Next we tell Processing what type of data the ‘ArrayList‘ will contain, in this case ‘Box‘, this is written immediately after ‘ArrayList‘ and is contained within angle brackets ‘<‘ and ‘>‘. So what we’ve currently instructed Processing to do is create an ArrayList which accepts elements which are of the type ‘Box‘: ArrayList<Box> boxes.

Next, we are going to assign the ‘ArrayList‘ with data and a size. However, we don’t have the data ready nor do we know how many elements our ‘ArrayList‘ will need to store, therefore, we will tell Processing to store a ‘placeholder-like’ value in the ‘ArrayList‘ and that the ‘ArrayList‘ has no starting capacity, it is empty. This is done by assigning the ‘ArrayList‘ as follows: = new ArrayList<Box>();

This can be expressed as the follow: ArrayList<Type> boxes = new ArrayList<Type>(InitialCapacity);

Now we need to modify the code within ‘setup‘ to work with an ArrayList rather than a standard array, we can do this by making the following changes:

Take a look at line 7: here we’ve made a change to our code to make use of one of the special methods associated with ArrayLists, in this case the ‘add‘ function. We first write the name of the ArrayList variable ‘boxes‘ and then using dot notation (as ArrayList is actually a class), we call the ArrayList ‘add‘ function, which requires a parameter, and in this case it can be any ‘Box‘ type object, which is encased in round brackets. That’s most of the changes for the ‘setup‘ function, however, as the ‘boxes‘ ArrayList was declared as empty we can no longer use the size of the array to loop, and need to change this back to a constant value or an integer variable, see line 5.

Let’s now focus on the ‘draw‘ function and ‘mousePressed‘ function and make the changes necessary to update our code to work with an ArrayList. Here we are going to need to use the ArrayList ‘get‘ function, as so:

Firstly we’ve needed to update our loop to get the size (length) of our ‘boxes‘ ArrayList, on lines 3 and 9. Unlike a standard array where we use ‘length‘ which acts more like a variable, ArrayLists require us to use ‘size()‘, which is a question-style function and returns an integer value, in our case the number of elements within the ‘boxes‘ ArrayList (30). Next we change lines 4 and 10 to use the ‘get‘ function by writing the name of the ArrayList variable ‘boxes‘ and then using dot notation we call the ArrayList ‘get‘ function, which requires a parameter which is the index (position) of the element in the ArrayList. This is similar to how we previously included the index of the array within square brackets. Then we follow this by another dot notation which we call the ‘draw‘ and ‘mousePressed‘ functions of the particular box stored in the ‘i‘ index of the ArrayList.

We’ve now successfully converted our code to use an ArrayList, before we progress I want to quickly introduce a new type of loop, which is referred to as an ‘enhanced for loop’.

1.5 ArrayLists: A Case For Using Enhanced Loops

Enhanced Loops simplify the syntax of a standard ‘for‘ loop by removing the need to declare a counter variable ‘i‘, a condition statement ‘i < x‘ and a increment operator ‘i++‘. Enhanced loops also remove the requirement to use the ‘get‘ function associated with an ArrayList as this process is built into the syntax of the enhanced loop, and thus helps us to write condensed code. Enhanced loops and ArrayList go hand in hand and are to use an enhanced loop you need to be looping through an ArrayList.

We are now going to change the ‘draw‘ and ‘mousePressed‘ functions to use enhanced loops, instead of traditional ‘for‘ loops, as follows:

If we analyse the code above, specifically lines 3 – 4 and lines 9 – 10, you will see how we write an enhanced loop. We still write ‘for‘, however, our loop parameters are vastly different. What we are in fact telling Processing to do is loop through all elements of the ‘boxes’ ArrayList, and for each loop store the element (object) contained in the ArrayList in the variable ‘b‘. This can be expressed as follows:

for (type element: array)

The enhanced loop starts from the first element in the ArrayList ‘0‘ and iterates to the last ‘n‘, always from beginning to end. For each iteration of our enhanced loop we ‘get‘ the element (class-object) at the index of that iteration and assign this element of the array to a variable we’ve declared called say ‘b‘, which we have told Processing is a Box type variable. The variable type declared within the enhanced loop must mach the type we’ve defined the ArrayList as containing.

Limitations of using an enhanced loop:

Whilst an enhanced loop simplifies the code and streamlines it, it is not always a workable solution and here are some limitations regarding the use of an enhanced loop. Firstly they always iterate from start to end, thus if we need to loop backwards through the array we can’t use an enhanced loop. Secondly, an enhanced loop will always iterate through the entire array, thus if we need to stop iterating, say half way, we cannot.

1.6 User Interaction: Dynamically Adding To An ArrayLists

We mentioned earlier that once we’ve converted our code to use an ArrayList we would add functionality allowing us to add rotating boxes by clicking on the canvas. However, I want to maintain the functionality which allows us to stop and start a box from rotating by also clicking on it. Thus adding more rotating boxes will not be as simple as it may have previously seemed. To solve this we are going to employ much of what we’ve covered thus far.

First lets identify a fundamental problem if we add a rotating box by clicking on the canvas. Which is what would happen if we clicked on top of an exiting box? Will this stop that box and not create a new box or will a new box appear above the box we clicked on and impede us from interacting with the box underneath the new box.

Therefore, I propose that we need to first check if we’ve clicked on an existing box. If we have then that box will stop or start spinning, but a new box will not be created. Alternatively when we click on the canvas if we’ve not clicked on an existing box a new box will be created at the location of our mouse cursor.

To do this we need to make a change to the ‘mousePressed‘ function in the ‘Box‘ class, which will let us know if we have in fact clicked on an existing box, we can do this as so:

As we’ve done earlier for the ‘randomBoolean‘ function we have changed the ‘mousePressed‘ function in the ‘Box‘ class to return a boolean value. This will be used within the main sketch ‘mousePressed‘ function to know if we’ve clicked on an existing box. The ‘Box‘ class’s ‘mousePressed‘ function will return true when the distance between the mouse and the box is less than the size of the box divided by 2, which indicates the mouse did click a box. Else we return false, which indicates the mouse did not click a box.

When we specify that a function returns a value it’s important to make sure that the function in question will always return a value. When using an ‘if‘ statement to determine the return value it may be possible that the return value is not calculated as if the ‘if‘ statement resolved false it may skip the return line. Hence it is necessary to include an ‘else‘ statement at the end to insure that return is assigned a value. Processing will often notify you if it thinks a function which should return a value may not have an accessible return.

Now we need to return to the Main sketch tab to make the final changes, which will use the returned boolean value from the ‘Box‘ class’s ‘mousePressed‘ function, to determine whether a new box should be created or a whether an existing box was clicked. The changes are as follows, within the main ‘mousePressed‘ function:

We first need to declare a boolean variable within the ‘mousePressed‘ function and assign it the value true. Each time we call the ‘mousePressed‘ function (every mouse click) this variable will start with the value true. We will call this variable ‘check‘ on line 2. Next we need to alter the code within the enhanced loop by including the call to the class’s ‘mousePressed’ function as part of an ‘if‘ statement’s condition. We’ve done this on line 4, when we call the class’s ‘mousePressed’ function it will return a true or false value based on whether we did click this particular box. If the class’s ‘mousePressed’ function returns true, our if statement resolves to true and we proceed onto the next line, line 5. On line 5 we change the value of ‘check‘ to true. It’s important to note that we are looping through all the boxes in the ArrayList, and for a single mouse press we most likely would click on one of those boxes (not all of them) or non of them, hence our  ‘check‘ variable acts like a gate, if for any of the boxes we loop through returns true we must have clicked on at least one box. It does not matter which box, just that we’ve clicked on one!

We now include a new ‘if‘ statement outside the enhanced loop which checks what the final value of the ‘check‘ variable is after looping through all the box’s ‘mousePressed’ functions, see line 8. If it is false (no boxes clicked), our ‘if‘ statement resolves to true as we’ve inverted the checked value using a ‘not‘ operator. Thus we progress to the next line, line 10. Line 10 uses the special ArrayList ‘add‘ function to add a new box to the end of the ArrayList, we no longer pass a random position for the box, but rather the mouseX and mouseY position.

If during the enhanced loop one of the box’s ‘mousePressed’ functions returned true, we would have set the ‘check‘ variable to true and therefore the ‘if‘ statement on line 8 would resolve to false, and skip line 10. Hence no box is added, as the mouse click was over an existing box’s position and intended to stop that box or start it from spinning.

1.7 Gravitational Fields

For a little fun, let us try a more involved sketch than we have produced so far.

First, we need to make some extensions to the variables which define the properties of our Box class. We will add two variables called ‘movX’ and ‘movY’ for the x and y component of the velocity to apply to the Box class:

Once you’ve made the necessary changes, by assigning the new ‘movX‘ and ‘movY‘ variables with a random floating point number between (-1 and 1), line 20 and 21, followed by increasing the Box’s x and y position for each frame by ‘movX‘ and ‘movY‘, lines 25 and 26, you can run the sketch. Now you will see that the boxes should disappear off the canvas, as, at each call to each box’s ‘draw‘ function, it adds the value of ‘movX‘ to ‘posX‘, and similarly the value of ‘movY‘ to ‘posY‘. The variable ‘movX‘ and ‘movY‘ are assigned values just once, both within the Box constructor. The constructor for each box is called only once, from the ‘setup‘ function, so the velocity of each box is constant and they just continue in the direction they were first assigned.

Now the boxes move, we can add an ‘attract‘ function to the Box class, as follows:

This function will do the major work for us. It can be referred to as a gravitational attractor function. It is designed to be called for one of the boxes, say boxes[20], and to be given, as a parameter, another box, say boxes[5]. This combination could be expressed as:  boxes[20].attract(boxes[5]);. In natural language: ‘attract box number 20 to box number 5‘. From the perspective of the called function, there is no reference to box 20, as this is the code on hanger (or in container 20). ‘This‘ is box 20.The reference to box 5 is the parameter: ‘Box b‘. So ‘b‘ is box 5.

We can now go through the code. The floating point number ‘d‘ is the distance between ‘this‘ (box 20’s) position and box b’s position. So ‘d‘ is the current separation value. Next, ‘diffX‘ and ‘diffY‘ are assigned the x and y components of the vector from box 20 to box 5. Finally, we ‘accelerate’ ‘this‘ (box 20) in the direction of box 5, according to how far away it is. That is, we adjust the velocity components ‘movX‘ and ‘movY‘ according to the vector direction and the distance. The gravitation drops off quickly, as it is inversely proportional to the value of ‘d‘ squared. Of course, ‘attract’ does not need to be called just for the combination of box 20 and box 5, it can be called for all combinations of boxes.

Now in the main program, we will do just that: all combinations of boxes will be ‘attracted’ to one another. We add a double loop (nested loop) to call the attract function from within the ‘draw‘ function in the main program, however, here we will use a nested enhanced loop rather than a standard loop, as follows:

The double or nested enhanced loop requires us to use a different variable to store the box we are attracting ‘this‘ box to, therefore we will call the inner loops box variable ‘other‘, thus ‘this box attract other box‘. The nested loop will cycle through every box and attracts it to every other box. There is a careful exception though: no box is compared to itself (this is achieved through an ‘if‘ statement ‘b != other‘, on line 6. The reason for this is that ‘d‘ between a box and itself equals 0. In the ‘attract‘ function there is a divide by ‘d‘ and dividing anything by 0 is undefined (essentially, infinite), and would cause Processing to crash.

Once you run the sketch you will see the boxes fly around one another, and if you are luck, you may see some of them form orbits around each other, though it’s more likely the orbit will be around the average position of all the boxes, rather than a single box itself.

2. Three Dimensions

Lesson two is a direct continuation of lesson one, in which we will attempt to convert our two-dimensional simulated gravitational field of boxes into a three-dimensional one. This lesson will introduce the core principles required to develop a Processing sketch in three dimensions, by adding a new dimension to our existing sketch referred to as the z-axis. When working in 3D we will need to tell Processing that we require a three dimensional canvas and in order to better control our view of the canvas we will also need to introduce a camera object through the use of a library for Processing called PeasyCam.

Key programming concepts:

Libraries, ArrayLists, rendering in 3D

Key geometry concepts:

Boxes, Spheres and z-axis (z coordinates)

2.1 Introduction

The initial process of moving from 2D to 3D in processing is actually rather straight forward. Presently when referring to location within any of our sketches we have only referenced two coordinates; x and y, we have not presently considered a z coordinate. Neither have we considered a depth (height) value for any object, up till now we’ve only specified a width and height. Interestingly we can make all our sketches work in 3D without changing any of the code we’ve already written, and in this case we could consider all our objects (rectangles, ellipses, lines, etc) to be flat (i.e height of 0) and a z coordinate of 0. To truly translate our sketches into 3D, where ever we specify a coordinate {x,y} or a size (width, height) we need to include a z coordinate and a depth value for the size of the object. Many of Processing’s built in functions such as, ‘translate‘, native support a z coordinate by passing three parameters rather than two. Furthermore, Processing has native 3D primitives such as; box and sphere which require three parameters (width, height, depth).

Thus far we’ve also been telling Processing that all our sketches should be rendered in only 2D, moving to 3D will require us to change this. Processing has multiple render modes built into it and in order to change which mode our Processing sketch uses we need to specify which mode we wish to use. This can be done by including the mode type as a third parameter within the ‘size‘ function we call in ‘setup‘. Processing has the following render modes:

• No Parameter (default): 2D graphics renderer with no graphics hardware acceleration.
• P2D (Processing 2D): 2D graphics renderer that makes use of OpenGL-compatible graphics hardware.
• P3D (Processing 3D): 3D graphics renderer that makes use of OpenGL-compatible graphics hardware.
• FX2D (JavaFX 2D): A 2D renderer that uses JavaFX, which may be faster for some applications, but has some compatibility quirks.

2.2 Introducing a third axis: z-axis

As we mentioned above the goal of this section will be to convert our current sketch to work in 3D. To do this we are going to start by making some changes to extend the Box class to support a third dimension or more simply a third axis (z-axis). This will require us to first add a new ‘posZ‘ and ‘movZ‘ variable and include these within the Box constructor, which can be done as so:

In the above code, lines 7 and 10, we’ve declared our two new float variables to store the z-component of the location of a Box and the movement of the Box, represented by ‘posZ‘ and ‘movZ‘ respectively. Following this we need to treat these two new variables exactly as we’ve done with ‘posX‘, ‘posY‘, and ‘movX‘, ‘movY‘. Therefore, within the Box constructor we need to assign a parameter value to ‘posZ‘, see line 19 and assign a random floating point number between ‘-1 and 1‘ to ‘posZ‘, see line 25. We now have a z-coordinate value and a direction in the z-axis which the box will initial move towards. However, don’t forget we need to pass a value for the z-coordinate to the Box constructor, thus we need to include: ‘float z‘ as a new variable as part of the parameters of the Box constructor, as seen on line 16.

We can’t run the sketch now as when we add a box to the ArrayList within the main sketch tab ‘setup‘ function and ‘mousePressed‘ function we are missing the new parameter which we’ve included in the Box constructor. Thus Processing gives us an error when we try to run the sketch. Therefore we need to make some alterations to the code in the main sketch tab to support a z-component. First we are going to tell Processing we want to render in 3D rather than 2D, as follows:

In the above code I’ve created a new integer variable to store how many boxes should be created at the start of the sketch, this value is stored in ‘numBox‘, on line 5 and later used on line 10 within the loop to repeat the Box constructor 10 times. Next and most notably I’ve instructed Processing to render this sketch in 3D on line 8, as part of the ‘size‘ function: size(400, 400, P3D); by including a third parameter, ‘P3D‘. Lastly I’ve updated the Box constructor, on line 12, to include our new z-coordinate parameter, which for now I’ve set as: ‘random(height)‘. We will need to return to the ‘setup‘ function latter to make some further changes, but for now we can move on.

Next we need to update the second use of the Box constructor which is used in the ‘mousePressed‘ function to include the new z-coordinate parameter, as follows:

Here I’ve duplicated ‘mouseY‘ as our z-coordinate, and again we will need to return to this line later to make some changes. For now though, we should be able to run the sketch.

Our sketch is now rendering in 3D, and thus our task is complete, well not quite… Your sketch probably looks no different than before and this is because Processing’s built in 3D renderer won’t not render the canvas in perspective-mode but rather in orthographic-mode. Thus, we cannot see depth within the sketch and hence it looks like everything is still 2D, when it’s in fact in 3D. There are ways to solve this by using the built in Processing ‘perspective‘ function, however, there is in fact a simpler method and one which provides more functionality.

2.2.1 PeasyCam: A Solution For Perspective Rendering In 3D

This simpler method is provided through the use of a handy library (plugin) for Processing called PeasyCam, which will allow us to set up a virtual camera in our scene, which will render the canvas in perspective mode. However, before we implement PeasyCam, it’s important to take note of some changes PeasyCam will make to the global coordinate system of Processing:

The image above illustrates the effect switching from Processing’s 2D render to Processing’s 3D render will have on the global coordinate system. You should be familiar with the image to the left from Workshop One, however, when we use ‘P3D‘ the coordinate system shifts to that of the image on the right. The z-coordinate is zero at the surface of the image, with negative z-values moving back in space.

However, when we implement PeasyCam the global coordinate system will be further altered from the image on the right to the image bellow:

With PeasyCam the global coordinate system has now been altered to have the origin point appear at what will ‘look like‘ the centre of the canvas. The origin coordinated is still {0,0,0} however, as we are working in 3D each shift of 1 unit in either: x, y, or z will no longer be represented by a single pixel. Therefore, the size of the canvas we’ve set in the ‘size‘ function will now relate only to the size of the window and the ‘world size‘ or global coordinate system is entirely independent from the values set in the ‘size‘ function. Furthermore, as {0,0,0} appears at the centre of the canvas, we now will move both in positive values and negative values, i.e. -10 in the x will shift left, and 10 in the x will shift right from the origin and the same for y. -10 in the z will move down and 10 in the z will move up.

To illustrate this open a new Processing window, and copy the code bellow:

Lets take a look at the code quickly as we are going to need some of the same lines of code to implement PeasyCam into our gravitational box sketch later. On line 1 we use the word ‘import‘ to tell Processing we need to include (load) a library at the beginning of our sketch, this is followed by the name of the library ‘peasy‘ and then finally followed by ‘.*‘, to indicate that Processing must load all the modules associate with the ‘peasy‘ library. Sometimes we only need a specific module in a library and then would load that module as apposed to all the modules contained in a library. Most libraries can be found through the Processing IDE ‘add more‘ button or by searching online and in most cases each library will have its own reference page providing instructions on how to import the library and some examples on how to use it. Following this we need to declare a new variable which will store the PeasyCam, much like we did early by declaring a variable which would store a singe instance of the Box class. In this case we’ve done so on line 2 by declaring a variable which is type PeasyCam and we’ve named it ‘cam‘.

In the ‘setup‘ function on line 5, we’ve told Processing to create a canvas which is 500 by 500 pixels and to use the 3D renderer ‘P3D‘. Next we need to construct an instance of a PeasyCam assigning this to our variable ‘cam‘ as done on line 8: cam = new PeasyCam(this, 100);. Then we provide ‘cam‘ with some initial settings, as shown on lines 9 and 10, which define how far-in we can zoom ‘50‘ and how far-out we can zoom ‘200‘ respectively.

Now in ‘draw‘ we are using three lines to display a gumball widget, similar to many modelling software packages, using Processing’s ‘line‘ function, yet including a third pair of coordinates for the z-component: line(x1, y1, z1, x2, y2, z2). Each line has a unique colour and is drawn from the origin {0,0,0} to either x:15, y:15, or z:15.

When you run this sketch you will notice how the gumball widget appears at the centre of the canvas, even though we used the origin {0,0,0}, and never used a ‘translate‘ function to shift to the centre of the canvas. Each line will point in the respective direction of the three axes associated with 3D space: x, y and z.

2.2.2 Implementation: Of PeasyCam In Our Gravitational Fields Sketch

Now lets implement a PeasyCam in our gravitational box sketch, so we can better see the boxes move around in 3D space. To do so lets return to the main sketch tab and make the following changes:

As can be seen above we’ve included the PeasyCam library on line 1, followed by creating a new PeasyCam variable ‘cam’ on line 4. Within ‘setup‘ we’ve construct an instance of a PeasyCam assigning this to our variable ‘cam‘, though this time we’ve set a different start-zoom value of ‘1000‘ and a min-zoom of ‘100‘ and max-zoom of ‘1000‘, we may need to adjust these values later.

As mentioned earlier before we would we need to make some changes to the call to the Box constructor within our loop. This is because we can no longer use random values between 0 and ‘width’ and ‘height’ as the coordinates for a Box, as this would create boxes only in the top-left-quarter of the ‘world‘ (i.e. where x, y and z are all positive values.) We need a new range between which we can generate a random number, for this we’ve chosen ‘-500 and 500‘. Therefore a Box’s x, y and z coordinate will be a random floating point between ‘-500 and 500‘, thus, producing a random coordinate such as: {250.0, -100, -344}.

We need to make the same change for our second call to the Box constructor in the ‘mousePressed‘ function, as follows:

Now we can finally run the sketch and move around our world and see the boxes fly around one another in 3D space. Or not!

As you’ve probably noticed by now when you run the sketch all the boxes are on a single plane (i.e. their z-coordinate is 0). However, we’ve specified a random z coordinate between ‘-500 and 500‘ so why is this? Furthermore all our boxes are flat, would it not be better if they were cubes floating around one another? To address the first issue, we have indeed given each of our boxes a z coordinate value, however, when we draw each box we are not translating its position in 3D space, we are still simply translating it in 2D. To fix this we need to switch to the Box class tab and make some changes to our ‘draw‘ function, as follows:

Let’s take a look at the changes we’ve made and why they are necessary. Firstly, on line 4, we’ve included the line of code to add the z-component of our Box’s velocity to its z coordinate, ‘posZ‘, this is necessary otherwise a box will never move up or down in 3D space only side to side. Next we need to update our ‘translate‘ function to operate in 3D, as opposed to 2D. To do this we simply need to include a third parameter, the Box’s z coordinate or ‘posZ’. Thus each box will be correctly shifted to its correct position in both the x-axis, y-axis and z-axis. Whereas, before we effectively drew all boxes with a z coordinate of 0.

We also wanted to draw cubes rather than 2D rectangles. To achieve this we can make use of Processing’s native ‘box‘ function, which requires either a single parameter: box(size), to create a cube or three separate parameters: box(w, h, d), to create a rectangular prism. In our sketch we will simply create cubes of varying sizes. As can be seen on line 8: box(side).

Now we can run the sketch again and we should have a number of different sized cubes floating around one another in 3D space. However, the logic which controls the attraction of each box to another box is now broken, as the distance between each box is calculated incorrectly, as if all the boxes were still on a flat plane. Therefore, we need to return to the ‘attract‘ function within the Box class tab to fix this:

On line 2, I’ve updated the built in Processing distance function ‘dist‘ to correctly calculate the distance between ‘this‘ box and another box ‘b‘ by including the z coordinate for each box. Now we have the correct value for the distance between two boxes in 3D space. Next we need to make two more changes. The first, line 5, is to add a new float variable ‘diffZ‘ to store the z component difference between box ‘b‘ and ‘this‘ box and lastly we need to increase the value of ‘movZ‘ by the z-difference divided by the square-root of the distance ‘d‘. Now our ‘attract‘ function works correctly for all three axes of our 3D space.

Limitations: It’s important to note that when we click on the canvas we can create a new cube at a random position in space rather than at the location of the mouse, as the location of the mouse (mouseX and mouseY) does not really have any relation to a position in the 3D global coordinate frame. Furthermore, due to this fact, the code we have in ‘mousePressed‘ which enables us to click on a cube and stop or start it from spinning will no longer work and could either be removed or you could attempt to solve this problem. However, such an exercise is outside of the scope of this workshop.

2.3 Conclusion

Bellow I’ve included all the code necessary to re-create the sketch, along with some minor alterations to randomly select: the colour of each box, whether a box will be a sphere or a cube as well as alterations to the ‘attract‘ function to make it take the size of the cube or sphere into account. Thus larger objects have greater attraction than smaller objects.

3. Vectors: Motion And Acceleration

Lesson three can be considered a more self-contained lesson, in comparison to the first two lessons of this workshop, in which we are going to explore the programming of motion in more detail. Lesson three will introduce the most basic building block for programming motion — the vector. Whilst we’ve touched on calculating motion, such as in the ‘attract‘ function, in the previous lesson, this lesson will introduce a more efficient way to store location and direction by using vectors, something we did not use in our ‘attract‘ function. We will also introduced other types of motion such as, separation as well as calculating acceleration for an objects motion.

This lesson will provide a foundation to move onto lesson four in which we will use vectors to apply forces, such as gravity or wind to an object.

Key programming concepts:

Vectors (PVector) and Vector Maths

3.1 Introduction

‘PVectors‘ as they are referred to within Processing, are a class used to describe a two or three dimensional vector. What exactly is a vector? There are in fact multiple varying definitions for the term vector each pertaining to different fields of study. However, the definition of a vector we are look for would be an Euclidean vector (named for the Greek mathematician Euclid and also known as a geometric vector). A vector can be though of, or visualised, as as an arrow; the direction is indicated by where the arrow is pointing, and the magnitude by the length of the arrow itself:

The above illustration shows a vector which is drawn as an arrow from point A to point B and serves as an instruction for how to travel from A to B. In other words, in the diagram a vector (drawn as an arrow) has magnitude (length of arrow) and direction (which way it is pointing).

The ‘PVector‘ datatype, stores two or three variables. First the components of the vector (x,y for 2D, and x,y,z for 3D), second the magnitude or velocity and/or third the acceleration. We can obtain the components of a vector using dot notation to get the: ‘vector.x, vector.y, vector.z‘, we can also obtain the magnitude and heading through dot notation calling ‘magnitude()‘ and/or ‘heading()‘ respectively. Technically, position is a point {x,y,z} whilst velocity and acceleration are vectors, but this is often simplified to consider all three as vectors.

As an example lets consider a rectangle moving across the canvas, at any given moment it has a position (the object’s location, expressed as a point), a velocity (the rate at which the object’s position changes per time unit, expressed as a vector), and acceleration (the rate at which the object’s velocity changes per time unit, expressed as a vector).

3.2 Using PVectors

Before jumping into more detail about vectors, let’s look at a basic Processing example that demonstrates why we should care about vectors in the first place. To do this we will write a basic bouncing ball sketch, first without using vectors:

In the above sketch, we have a very simple world — a blank canvas with a circular shape (a ball) travelling around. This ball has some properties, which are represented in the code as variables which define the balls location: ‘x‘ and ‘y‘,  and the balls speed: ‘xSpeed‘ and ‘ySpeed‘. In a more advanced sketch we could include even more properties, such as:

• Acceleration — xAcceleration and yAcceleration
• Target — xTarget and yTarget location
• Wind — xWind and yWind
• Friction — xFriction and yFriction

As we can see for each new property we want to add to this world we need to add two new variables and this is only a 2D world. In a 3D world, we’ll need three variables for each property: ‘x, y, z‘, ‘xSpeed, ySpeed, zSpeed‘, and so on. Wouldn’t it be nice if we could simplify our code and use fewer variables? Well this is in fact possible with vectors, by replacing our properties as follows:

This is the first step towards using vectors, however this won’t provide anything new yet. Simply adding vectors does not magically make our Processing sketches simulate physics. However, they will drastically simplify your code and provide a set of functions for common mathematical operations which occur regularly while programming motion.

For now our introduction to vectors will live in two dimensions, as it’s not entirely necessary to over complicate things with a third dimension just yet, and as shown in the previous section: 2.2.2 Implementation: Of PeasyCam In Our Gravitational Fields Sketch converting a sketch from 2D to 3D is not as daunting a task as one you may have thought it to be. All of these examples can be fairly easily extended to three dimensions (and the class we will use — PVector — naively allows for three dimensions.)

We’ve actually already, unintentionally, explained what a vector is in the previous section: 1.7 Gravitational Fields, we can think of of a vector as the difference between two points. Consider how you might go about providing instructions to walk from one point to another:

We have already done this before whilst programming motion. For every frame of animation (i.e. a single cycle through Processing’s draw() loop), you instruct each object on the screen to move a certain number of pixels horizontally and a certain number of pixels vertically. This could be expressed at for every frame: ‘new location = velocity applied to current location‘. This is essentially what we were doing back in our ‘attract‘ function.

If velocity is a vector (the difference between two points), what is location? Is it a vector too? Technically, one might argue that location is not a vector, since it’s not describing how to move from one point to another — it’s simply describing a singular point in space. Nevertheless, another way to describe a location is the path taken from the origin to reach that location. Hence, a location can be the vector representing the difference between location {x,y,z} and origin {0,0,0}.

Let’s briefly examine the underlying data for both location and velocity. In the bouncing ball example in which we have the following two PVectors: ‘location’ and ‘speed‘. Notice how we are storing the same data for both — two floating point numbers, an x and a y. If we were to write a vector class ourselves, say if we were using a langue that did not have a vector class, we’d begin with something rather basic, like so:

Fortunately Processing has a vector class, PVector, so we don’t need to do this. Though at its core, a PVector is just a convenient way to store two values (or three, as we’ll see in 3D examples). Thus for us to start converting our bouncing ball example to use a PVector we would replace our initial property variables, ‘x‘, ‘y‘, ‘xSpeed‘ and ‘ySpeed‘, with the following:

Let’s take a look at the above code. First we declare two new PVector type variables ‘location‘ and ‘velocity‘ followed by immediately assigning them with a new PVector. Notice the use of the word ‘new‘ as we have previously done when creating a new Box in the previous lessons, this is always used when we assign a class-type variable a new instance of a class, such as a color, PVector, or our Box. We follow this by the parameter(s) of the PVector: PVector(x, y, z). Now that we have two vector objects, ‘location‘ and ‘velocity‘, we’re ready to implement the algorithm for motion: location = location + velocity.

Previously within ‘draw‘ we incremented ‘x‘ by ‘xSpeed‘ and ‘y‘ by ‘ySpeed‘ to apply motion (a change in position for each frame), in an ideal world, we would be able to rewrite the above, using PVectors, as: location = location + velocity;

However, in Processing, the addition operator ‘+‘ is reserved for primitive values (integers, floats, etc.) only. Processing doesn’t know how to add two PVector objects together any more than it knows how to add two PFont objects or Box objects. This is since vectors represent groupings of values, therefore, we cannot simply use traditional addition/multiplication/etc. Instead we need to do some ‘vector’ maths. Fortunately for us, the PVector class includes functions for common mathematical operations.

3.2.1 Vector Maths: Addition

Before we take a look at the PVector class and its ‘add()‘ method, let’s take a look at how addition is implemented in the PVector class itself by writing our own ‘add‘ function which takes another PVector object as its argument. We would write the following (this is purely for the sake of learning since it’s already implemented for us in Processing):

Now that we see how the ‘add‘ function essentially works inside of the PVector class, we can return to our bouncing ball example which requires the correct vector addition implementation of our location + velocity algorithm, to do this we change the following line to:

All that remains are a few more changes to the syntax of our code to correctly make reference to the bouncing ball’s location vector x and y components. To complete the sketch we would write the following:

We’ve made a couple of simple changes to the code. First we’ve updated the edge detection if statements, on lines 17 and 20, to get the ball’s x and y coordinates from the ball’s ‘location‘ vector, using dot notation: location.x and location.y. We’ve done the same on line 24, when drawing the ellipse. Lastly, we need to invert the x and y components of the ‘velocity‘ vector which we’ve done on lines 18 and 21, again using dot notation.

Now, you may be somewhat disappointed. After all, this may initially appear to have made the code more complicated than the original version. While this is a reasonable critique, it’s important to understand that we haven’t fully realised the potential of programming with vectors just yet. Looking at a simple bouncing ball and only implementing vector addition is just the first step. As we proceed into more complex worlds containing multiple objects and multiple forces (next lesson), the benefits of PVector will become more apparent.

3.2.2 More Vector Maths

Addition is only the first step, in learning about vector maths. There are many mathematical operations that are commonly used with vectors. Below is a comprehensive list of the operations available as functions within the PVector class. We’ll go through a few of the key ones now.

3.2.3 Vector Maths: Subtraction

Now that we’ve covered addition, let’s quickly explore subtraction. This one’s not so bad, simply replace the plus sign with a minus! Thus the ‘subtract‘ function inside the PVector class would look similar to this:

The following example demonstrates vector subtraction by calculating the difference between two points, in this case the mouse location and the centre of the canvas:

Again the above code is a rather unnecessary complication to the task of drawing a line from the canvas centre to the mouse location, however, it’s still a reasonably good way to visually represent how vector subtraction operates.

3.2.4 Vector Maths: Multiplication

Multiplication on the other hand operates a little differently. When we talk about multiplying a vector, what we typically mean is scaling a vector. If we wanted to scale a vector to twice its size or one-third of its size (leaving its direction the same), we would say: ‘multiply the vector by 2‘ or ‘multiply the vector by 1/3.‘ Note that we are multiplying a vector by a scalar, a single number, not another vector.

Therefore, the function inside the PVector class would be written as follows:

To implement vector multiplication in code we can write the following:

We’ve already stated that by multiplying a vector we are in fact scaling the vector. In the above example our vector is the visible line pointing from the canvas centre to the mouse location, which is first calculated as the difference between the these two points. We’ve included vector multiplication on line 14: mouse.mult(0.5);, here we are telling Processing to scale the ‘mouse‘ vector by the scalar value ‘0.5’. In other words, scale the size (length) of the mouse vector by 50% of its original length. Try moving the mouse further away from the canvas centre and notice how the line is only ever half the length of the total distance between the canvas centre and the mouse location.

3.2.4 Vector Magnitude

Vector Multiplication and division, are means by which the length of the vector can be changed without affecting direction. Perhaps you’re thinking: “Ok, so how do I know what the length of a vector is? I know the x and y components, but how long is the actual arrow?” The length of a vector is also referred to as the magnitude and being able to calculate the length of a vector is incredibly useful and important.

To illustrate this let’s draw a rectangle with its width equal to the hypotenuse or magnitude of the vector created between the centre of the canvas and the mouse position, or the ‘mouse‘ vector. To do so we will call the ‘mag()‘ function which returns a floating point value, which is the length of the vector and use this value as the rectangle’s width:

3.2.4 Normalizing Vectors

The magnitude function opens the door to many possibilities, the first of which is normalization. Normalizing refers to the process of making something “standard” or, well, “normal.” In the case of vectors, let’s assume for the moment that a standard vector has a length of 1. This is the way Processing is set to implement normalize and will always set the length of the vector to 1 unit. To normalize a vector, therefore, is to take an existing vector of any length and, without changing its position, set its length to 1, turning it into what is called a unit vector. A unit vector is rather useful as it describes a vector’s direction without regard for its length, having a unit vector readily accessible will prove useful as we start to implement forces in the next lesson. Within the PVector class the ‘normalize’ function would be written as so:

Once again to illustrate this let’s implement the ‘normalize’ function into our previous sketch. Doing so will set the length of the ‘mouse‘ vector to 1 unit, and as we move the mouse cursor around the vector will point in that direction but will not change length or magnitude. We can implement this as follows:

Once we have ‘normalized‘ the mouse vector, as seen on line 15: mouse.normalize();, the length of the line drawn on the screen will always be 1 pixel. If you run the sketch you may vaguely see the line move to point in the direction of the mouse cursor, however, 1 pixel is a little small to see this, thus we can scale up the vector by 50 times. To do so we will use the PVector ‘mult‘ function to multiple the vector by 50, as see on line 16: mouse.mult(50);. Now when we run the sketch the line is easier to see.

3.3 Vector Motion 101: Velocity

All this vector maths stuff sounds useful and is probably something we should know about, but why? How will it actually help us write code? In all honesty we need to be a little patience. It will take some time before the awesomeness of using the PVector class fully comes to light. This is a pretty common occurrence when first learning a new data structure. For example, when you first learn about an array and ArrayList, it might seem like much more work to use an array than to just have several variables stand for multiple things. But that plan quickly breaks down when you need a hundred, or a thousand, or ten thousand things. The same can be true for PVector. What might seem like more work now will pay off later, and pay off quite nicely. And you don’t have to wait too long, as your reward will come in the next lesson.

But first there are two final, and very important points we need to cover and those are velocity and acceleration. What does it mean to program motion using vectors? As demonstrated at the beginning of this lesson: 3.2 Using PVectors — the bouncing ball. An object on the canvas has a location (where it is at any given moment) as well as a velocity (instructions for how it should move from one frame to the next). Velocity is added to location, for each frame:

location.add(velocity);

Followed by drawing the object at that new location:

ellipse(location.x,location.y,25,25);

This is what we refer to as Motion 101:

1. Add velocity to location
2. Draw object at location

In our bouncing ball sketch, we have included all of this code within Processing’s main tab, within ‘setup‘ and ‘draw‘ functions. What we want to do now is move towards encapsulating all of the logic for motion inside of a class, much like we’ve already done at the end of Workshop 1. This way, we can create a foundation for programming moving objects in Processing. Beyond this point the lesson assumes you have experience with objects and classes in Processing, from the previous workshop!

In this case, we’re going to create a generic Vehicle class, which will describe a thing moving around the screen. This is the first stage in our long-term goal towards an autonomous agent. Thus we must consider the following two questions:

1. What data does a Vehicle require?
2. What functionality does a Vehicle have?

Our Motion 101 algorithm provides us the answers to these questions. A Vehicle object has two primary pieces of data: location and velocity, which are both PVector objects. So to begin lets create a new Vehicle class in a new tab (name the tab Vehicle) and the class ‘Vehicle‘, as so:

The Vehicle’s functionality is just as simple. The Vehicle needs to move and it needs to be seen. Therefore, we will implement these capabilities as functions named ‘update()‘ and ‘display()‘. We’ll put all of our motion logic code in ‘update()‘ and draw the object in ‘display()‘, as follows:

So far what we’ve written should seem somewhat familiar as it builds upon everything we’ve learnt thus far. Therefore, you should have picked up on the fact that we’ve forgotten one crucial function: the object’s constructor. The constructor always has the same name as the class and is where we give instructions on how to set up the object. It’s called by invoking the new operator, in the main sketch tab, which we will do as follows, a little later:

Vehicle v = new Vehicle();

For now let’s arbitrarily decide to initialize our Vehicle object by giving it a random location and a random velocity, as follows:

Let’s finish off the Vehicle class by developing a function to determine what the object should do when it reaches the edge of the canvas. For now let’s do something simple, and just have it wrap around the edges:

For now the Vehicle class is finished, so we need to look at what needs to be done in our main program. We first declare a Vehicle object:

Vehicle vehicle;

Then initialize the vehicle within ‘setup()‘:

vehicle = new vehicle();

and call the appropriate vehicle functions within ‘draw()‘:

vehicle.update();
vehicle.checkEdges();
vehicle.display();

Bellow is an example for reference:

3.4 Vector Motion 101: Acceleration

Congratulation, you’ve created a vehicle class implementing PVector. Therefore, currently, you should feel comfortable with two things:

1. What a PVector is
2. How we can use PVectors inside of an object (class) to keep track of its location and movement.

This is an excellent first step. Before standing ovations and screaming fans, however, we need to make one more, somewhat bigger step forward. After all, watching the Motion 101 example above is fairly boring — the circle never speeds up, never slows down, and never turns. For more interesting motion, for motion similar to that which appears in the real world around us, we need to add one more PVector to our class — acceleration.

The strict definition of acceleration we’re using here is: the rate of change of velocity. Let’s think about that definition for a moment. Is this a new concept? Not really. Velocity is defined as the rate of change of location. In essence, we are developing a “trickle-down” effect. Acceleration affects velocity, which in turn affects location. In code, this reads:

The above code should not seem too abstract at this point as we are essentially using the PVector ‘add‘ function twice, one after the other. Firstly to update the velocity at which the object is moving by adding the acceleration (or deceleration, ‘–‘ value) to the velocity followed by adding the newly calculated velocity to the objects present location.

As a challenge, from this point forward, let’s make a rule for ourselves. Let’s write every example in the rest of this lesson without ever touching the value of velocity and location (except to initialize them). In other words, our goal now for programming motion is: Come up with an algorithm for how we calculate acceleration and let the trickle-down effect work its magic. (In truth, you’ll find reasons to break this rule, but it’s important to illustrate the principles behind our motion algorithm.) And so we need to come up with some ways to calculate acceleration:

3.4.1 Types of Acceleration Algorithms?

• A constant acceleration
• A totally random acceleration
• Acceleration towards the mouse

The above is not an exhaustive list and we unfortunately don’t have time to demonstrate all these examples in this workshop, for now we will focus on; constant acceleration and Acceleration towards the mouse.

In order to demonstrate Algorithm 1: a constant acceleration, we will need to make some changes to our Vehicle class. Whilst this type of acceleration is not particularly interesting, it is the simplest and will help us begin incorporating acceleration into our code. The first thing we need to do is add another PVector to the Vehicle class:

This is not enough obviously to implement acceleration into our vehicle, we now need to incorporate acceleration into the Vehicle’s ‘update()‘ function:

We’re almost done. The only missing piece is the initialization in the constructor: ‘Vehicle()‘. Here let’s rather start the Vehicle object in the middle of the canvas and with an initial velocity of zero:

When we run the sketch this will result in the the object being at rest. We don’t have to worry about velocity anymore, as we are controlling the Vehicle’s motion entirely with acceleration. Speaking of which, according to Algorithm 1: a constant acceleration, our first sketch involves constant acceleration. So let’s select a value:

Maybe you’re thinking, “Hmm… those values seem awfully small!” That’s correct, they are quite small indeed. It’s important to realise that our acceleration values (measured in pixels whilst in 2D) accumulate over time in velocity, about thirty times per second depending on our sketch’s frame rate. And so to keep the magnitude of the velocity vector within a reasonable range, our acceleration values should remain quite small. We can also help this cause by incorporating the PVector function ‘limit()‘, as follows:

Limit will do the following: What is the magnitude of velocity? If it’s less than 10, just leave it as is. However, if it’s more than 10, however, reduce it to 10!

Let’s take a look at the changes to the Mover class, complete with ‘acceleration’ and ‘limit()‘.

3.5 Interactivity with Acceleration

We will finish this lesson by attempting something a bit more complex and a great deal more useful. We’ll dynamically calculate an object’s acceleration according to a rule stated in Algorithm 3 the object accelerates towards the mouse.

Anytime we want to calculate a vector based on a rule or a formula, we need to compute two things: magnitude and direction. Let’s start with direction. We know the acceleration vector should point from the object’s location towards the mouse location. Let’s say the object is located at the point {x,y} and the mouse at {mouseX,mouseY}. The acceleration is directly proportional to the distance or magnitude of the vector created between the mouse cursor and the object, the further away the faster the object will travel towards the mouse and the closer it gets the slower it will travel.

This will be similar to how we created a vector pointing from the centre of the canvas to the mouse location, only now we are pointing from the objects location to the location of the mouse. To do this we used the PVector ‘sub‘ (subtract) function to find the difference between to PVectors. Let’s write the above using PVector syntax. Assuming we are in the Vehicle class and thus have access to the vehicles’s PVector location, we then have:

We now have a new PVector, called ‘dir‘, which points from the vehicles’s location all the way to the mouse, ‘target‘. If the object were to actually accelerate using that vector, it would appear instantaneously at the mouse location. This does not make for good animation, of course, and what we want to do now is decide how quickly that object should accelerate toward the mouse.

In order to set the magnitude (whatever it may be) of our ‘acceleration’ PVector, we must first Normalize that direction ‘dir‘ vector. If we can shrink the vector down to its unit vector (of length one) then we have a vector that tells us the direction and can easily be scaled to any value. One multiplied by anything equals anything.

In summary, we’ve taken the following steps:

And here are those steps in the ‘update()‘ function itself:

You may be wondering why the circle doesn’t come to rest when it reaches the target. It’s important to note that the object moving has no knowledge about trying to stop at a destination; it only knows where the destination is and tries to go there as quickly as possible. Going as quickly as possible means it will inevitably overshoot the location and have to turn around, again going as quickly as possible towards the destination, overshooting it again, and so on and so forth.

This example is remarkably close to the concept of a gravitational attraction field (which we explored earlier however, without the use of vectors). However, one thing is missing here which is the strength of gravity (magnitude of acceleration) is inversely proportional to distance. This means that the closer the object is to the mouse, the faster it accelerates.

We’ve come to the end of lesson three, and whilst it may feel like we’ve covered everything there is to know about PVectors we have in fact only touched the surface. If you’re interested in exploring vector motion in more detail I would strongly encourage you to take a look at the book: The Nature of Code by Daniel Shiffman, which was incredibly useful in helping producing this lesson and covers the topic of vector motion in greater detail.

As an exercise to do yourself try implementing the above example with a variable magnitude of acceleration, stronger when it is either closer or farther away or maybe try using an array to have multiple vehicles visible on the canvas.

4. Autonomous Agents

Lesson four will extend what we’ve learnt about in lesson three: vectors, by adapting our Vehicle class into what is referred to as an agent or Agent class. This lesson aims to introduce you to the concept of an autonomous agent and provide a brief and basic example of how to implement multiple agents to create swarm like behaviours. Due to time availability, or the lack there of, of our all day workshops we’ve had to very quickly get to grips with vectors and vector motion. We have in fact jumped-the-gun, so to speak, by moving onto autonomous agents and completely skipped over other types of vector motion such as; forces, oscillation and more complex multi-vehicle driven systems such as, particle system. All of these are highly valuable fields to learn about and will assist in your understanding of both vector motion as well as programming complex multi-vehicle driven systems including autonomous agents, which we are about to look at.

Therefore, I would highly recommend that you read the book: The Nature of Code by Daniel Shiffman, where all these topic are discussed in considerably more detail!

However, let us consider what we’ve been designing so far? Inanimate objects. Lifeless shapes sitting on our screens that flop around when affected by external forces. What if we could breathe life into those shapes? What if those shapes could live by their own rules? This is what we will tackle in this lesson — the development of autonomous agents.

Key programming concepts:

Agents, agency, functional cylce and PVectors

3.1 Introduction

Alright! That’s all good and well, but what is an agent? The term autonomous agent usually refers to an entity that makes its own choices about how to act in its environment without any influence from a leader or global plan. For us, “acting” will mean moving. This addition is a significant conceptual leap as we are now expecting our box or shape or vehicle to have “desire” to move itself somewhere or interact with something off its own accord. The cause for change or the force for change occurs internally. There are three key characteristics of an agent:

1. An Agent is situated: it is in continuous interaction with its environment, perceiving its environment through sensors and acting upon that environment using effectors.
2. An Agent is a (computational) system. Since an agent is in interaction with an environment, that environment can, and in most situations will, demand action upon the agent – potentially within a certain amount of time. (So when designing an agent-based system, we (may) have to take into account that an agent’s resources are limited. i.e. it can die.)
3. An Agent is intentional: an agent is best described from an intentional stance. Systems which are less complex, are better described from a mechanical stance and are not agents by our definition: i.e., a light switch, steam governor or thermostat.

The good news is, while the concept of forces that come from within is a major shift in our design thinking, our code base will barely change, as these desires and actions are simply that — forces.

In the late 1980s, computer scientist Craig Reynolds developed algorithmic steering behaviours for animated characters. These behaviours allowed individual elements to navigate their digital environments in a “lifelike” manner with strategies for fleeing, wandering, arriving, pursuing, evading, etc. Used in the case of a single autonomous agent, these behaviours are fairly simple to understand and implement. In addition, by building a system of multiple characters that steer themselves according to simple, locally based rules, surprising levels of complexity emerge. The most famous example is Reynolds’s “boids” model for “flocking/swarming” behaviour. — Daniel Shiffman

3.2 Vehicles and Steering

Now that we have a rudimentary understanding of the core concepts behind autonomous agents, we can begin writing the code. There are many places where we could start such as, artificial simulations of ant and termite colonies which make for great demonstrations of systems of autonomous agents. However, for now we will begin by examining agent behaviours that build on the work we’ve done in previous lessons this workshop: modelling motion with vectors and driving motion with forces. I actually foreshadowed this development and named our class-object which moves as a Vehicle, you could change this to Agent or Boid, or whatever you wish.

We have the following so far:

We’ve already made reference to Craig Reynolds and in his 1999 paper “Steering Behaviors for Autonomous Characters” Reynolds uses the word “vehicle” to describe his autonomous agents, so we will follow suit. We are are going to implement many of the other methods Reynolds pioneered.

Reynolds describes the motion of idealised agents (vehicles) (idealised as we are not concerned with the actual scientific engineering of such vehicles, but simply assume that they exist and will respond to our rules) as a series of three layers — Action Selection, Steering, and Locomotion.

1. Action Selection. A vehicle has a goal (or goals) and can select an action (or a combination of actions) based on that goal. The vehicle takes a look at its environment and calculates/chooses an action based on a desire: “I see a zombie marching towards me. Since I don’t want my brains to be eaten, I’m going to flee from the zombie.”
2. Steering. Once an action has been selected, the vehicle has to calculate its next move. For us, the next move will be a force; more specifically, a steering force. Fortunately, Reynolds developed a simple steering force formula that we can adopt throughout the examples in this lesson: ‘steering force = desired velocity – current velocity‘. We’ll get into the details of this formula and why it works so effectively shortly.
3. Locomotion. For the most part, we’re going to ignore this third layer. In the case of fleeing from zombies, the locomotion could be described as “left foot, right foot, left foot, right foot, as fast as you can.” In our Processing world, however, a rectangle or circle or triangle’s actual movement across the canvas is irrelevant given that it’s all an illusion in the first place. Nevertheless, this isn’t to say that you should ignore locomotion entirely.

For the most part in this lesson Action Selection will be the most important layer for us to consider. What are the elements of our system and what are their goals? In this lesson, we are going to look at a series of steering behaviours (i.e. actions): seek and flock with your neighbours, etc. It’s important to realise, however, that the point of understanding how to write the code for these behaviours is not because you should use them in all of your projects. Rather, these are a set of building blocks, a foundation from which you can design and develop vehicles with creative goals and new and exciting behaviours. There are more behaviours to consider, such as: flee, follow a path and follow a flow field. However, these are outside of the scope of this workshop.

3.3 The Steering Force

All this theoretical talk makes for a fascinating discussion but it does not get us anywhere in Processing. Lets consider the following scenario. A vehicle moving with velocity desires to seek a target.

The vehicles goal and subsequent action is to seek the target. If you think back to the previous Lesson: 3.5 Interactivity With Acceleration, you might start by coding the target as an attractor and apply a gravitational force that pulls the vehicle to the target. This would be a relatively reasonable solution, yet, conceptually it’s not what we’re looking for here, in fact it’s actually the opposite. We don’t want to simply calculate a force that pushes/pulls the vehicle towards its target; instead, we require the vehicle to make an intelligent decision to steer towards the target based on its perception of; its state and environment (i.e. how fast and in what direction ‘am I, the agent’ currently moving). Therefore the solution is for the vehicle to ‘look‘ at how/where it desires to move (a vector pointing to the target), compare that goal with how quickly it is presently moving (its velocity), and apply a force accordingly. Thus steering, slowly altering its own direction, towards the target.

steering force = desired velocity – current velocity

How can we express this as code within Processing? By writing:

Let’s take a look at the above formula, we have a PVector variable ‘velocity‘, thus this is not a problem. However, we don’t have the desired velocity vector; this is something we are going to need to calculate. If we’ve defined the vehicle’s goal as “seeking the target,” then its desired velocity is a vector that points from its current location to the target location.

If we assume our target to be of a type PVector, we can calculate the desired velocity vector as follow:

Yet, this is not particularly realistic. What if we have a very high-resolution window and the target is thousands of pixels away? Sure, the vehicle might desire to teleport itself instantly to the target location with a massive velocity, but this won’t make for an effective animation. What we really want to say is:

The vehicle desires to move towards the target at maximum speed.

We’ve done something similar in the previous lesson, therefore, we should have a method to achieve the above statement as code within Processing. To make the above a bit simpler we could express it as: the vector should point from location to target and with a magnitude equal to a maximum speed (i.e. the fastest the vehicle can go). So first, we need to make sure we add a variable to our Vehicle class that stores maximum speed:

Thus within our desired velocity calculation, we scale according to maximum speed, hence limiting the maximum speed the vehicle can travel:

Putting this all together, we can write a new function called ‘seek()‘ that receives a PVector target (as a parameter), and calculates a steering force towards that target:

Note how in the above function we finish by passing the steering force into ‘applyForce()‘. We will shortly get to this. So why does this all work so well? Let’s see what the steering force looks like relative to the vehicle and target locations:

Image credit: Daniel Shiffman, The Nature of Code

Again, notice how this is not the same force as gravitational attraction. A principle of autonomous agents is that an agent has a limited ability to perceive its environment. Here is that principle, subtly embedded into Reynolds’s steering formula. If the vehicle was stationary (zero velocity), desired minus velocity, would be equal to desired. But this is not the case. The vehicle is aware of its own velocity and its steering force compensates accordingly. This creates a more active simulation, as the way in which the vehicle moves towards the targets depends on the way it is moving in the first place.

We now have a function which the Vehicle can call and pass a target location to in order to steer towards the target. However, if you look at line 7, you will notice we are calling another function called ‘applyForce()‘ which we are passing the PVector ‘steer’ to. However, we have not written an ‘applyForce()‘ function. This is because we are moving quite quickly through this lesson, so let’s quickly write this function as you will possibly be familiar with it already:

Our example code, as it stands, has no feature to account for the variability in the Vehicle’s steering ability. (Is it a super sleek race car with amazing handling? Or a giant Mack truck that needs a lot of advance notice to turn?) A method to control the Steering ability can be achieved through limiting the magnitude of the steering force. Let’s call that limit the maximum force (or ‘maxForce’ for short). And so finally, we have:

Followed by:

Limiting the steering force brings up an important consideration. We must always remember that it’s not actually our goal to get the vehicle to the target as fast as possible. If that were the case, we would just say “location equals target” and there the vehicle would appear. Our goal, as Reynolds puts it, is to move the vehicle in a “lifelike and improvisational manner.” We’re trying to make it appear as if the vehicle is steering its way to the target, and so it’s up to us to play with the forces and variables of the system to simulate a given behaviour. For example, a large maximum steering force would result in a very different path than a small one. One is not inherently better or worse than the other; it depends on your desired effect. (These values need not be fixed and could change based on other conditions. Perhaps a vehicle has health: the higher the health, the better it can steer.)

Image credit: Daniel Shiffman, The Nature of Code

Here is the full Vehicle class, incorporating the rest of the elements:

3.4 Agent Flocking Behaviours

Flocking is a group animal behaviour that is a characteristic of many living creatures, such as birds, fish, and insects. In 1986, Craig Reynolds created a computer simulation of flocking behaviour and documented the algorithm in his paper, “Flocks, Herds, and Schools: A Distributed Behavioural Model.” — Daniel Shiffman

In order to demonstrate agent flocking behaviours we’ve once again had to take a quantum leap ahead of ourselves, skipping many import steps along the way, which would have provided foundation for us to better understanding of how such complex multi-agent behaviours (i.e., flocking) operate and how we would go about implementing these behaviours as code within Processing. Such steps we’ve missed include covering other simpler behaviours such as: path-following, group separation and combinations. All these behaviours a covered within The Nature of Code by Daniel Shiffman, specifically chapter 6. Autonomous Agents

Flocking is essentially the combination of three base group behaviours, each we would need to first understand and then figure out how to code:

• Cohesion  — (also known as ‘centre‘): Steer towards the centre of your neighbours (stay with the group).
• Separation  — (also known as ‘avoidance’): Steer to avoid colliding with your neighbours.
• Alignment— (also known as ‘copy‘): Steer in the same direction as your neighbours.

Just as we did with our separate and seek example, we’ll want our Agent objects to have a single function that manages all the above behaviours. We would call this this function ‘flock‘.

Unfortunately, the topic of agent flocking behaviours and their implementation in Processing, is far to broad and complex to be explored in it’s entirety within this workshop. Therefore, an example of 2D agent flocking is provided bellow: