In the meanwhile, I’ve been doing my best to respond to concrete issues & tasks people were trying solve on the Processing forums as well as the issue tracker. The list of demos on OpenProcessing has grown too. And thanks to personal heroes of mine, like Golan Levin, Daniel Shiffman and their students, there’re also a number of very interesting student projects this year, which are utilising the libraries and (in some cases) have their code explorations shared (like good citizens tend to do :). A round-up post of these will follow shortly.

Speaking of missing examples and small projects, teaching workshops has been another well under-documented effort of mine. For most of them, I’ve created a Mercurial repository on this website and I’d encourage you to download and play with these examples as well. A lot of them are more advanced than the examples bundled with each release, some utilize 3rd party libraries and all are generally full of comments, not just about library specific topics. Please also send your virtual thanks to all the unis & institutions allowing this material to be shared!

Workshop repositories: http://learn.postspectacular.com/hg/ – All source code is LGPL licensed unless stated otherwise.

Before I get to the compiled list of mini-tutorials and discussions from the Processing forum, Amnon Owed has recently produced two excellent tutorials for this project and I sincerely hope his efforts will inspire other users to follow suit:

Working with toxiclibs, part #1 (polygons, voronoi explosions)
Working with toxiclibs & Processing, part #2 (physics, colors, zoomlens)

List of recent forum threads (including lots of source code), sorted by subject:

Interaction, events, multi-threading

iPad, TUIO & particles with dynamic attraction behaviors
Custom Events + Event listener?

Geometry

How to use the Toxiclibs Voronoi class?
2D Collision detection – irregular shapes (computer vision blobs)
Octree Visualization
PerlinNoise to specified target destination
What does Vec2D.heading() in Toxiclibs do exactly?
How to calculate the tangent line of a circle?
Mouse within a certain area
using toxiclibs geomutils to solve the “pulley problem”

Geo location (Twitter & Flickr)

GPS to spherical coordinates with Vec3D & toxilibs
GeoLocation Twitter Search: Twitter4j
Simple mapping of geolocated tweets

Color

Working with toxiclibs & Processing, part #2
Question on toxiclibs colorutils Histogram

Rendering

GLGraphics + Toxiclibs Volumeutils (also see post on codeanticode)
Drawing a dotted/dashed arc
Library with box(x,y,z) function?

Math

Can toxi Spline2D be use for more than Vector positions?
convert 0.54321 to 0.54 and convert 2 to 100

XML (JAXB)

These two threads are about JAXB, which is indirectly referenced by various toxiclibs geometry types in order to store them as XML. In anyway, many users are interested in data visualization and JAXB is lightyears ahead of the default XML library bundled with Processing…

JAXB tutorial: XML parsing with style
JAXB tutorial question

Last, but not least: If you have any similar questions, interest in running workshops at your university/company or any small tutorials to share, please do get in touch! ¡Muchas gracias!

The Gray-Scott reaction diffusion model is a member of a whole variety of RD systems, popular largely due to its ability to produce a very varied number of biological looking (and behaving) patterns, both static and constantly changing. Some patterns are reminiscent of cell devision, gastrulation or the formation of spots & stripes on furry animals. As with all RD models, these patterns are the result of an iterative process evaluating each cell of the simulation space based on the concentrations of the two main parameters (for Gray-Scott usually named f and K) of the reaction equation as well as taking into account the concentrations of these 2 substances in neighboring cells. So conceptually the reaction diffusion system lies somewhere between the isolated DLA process working with individual particles and the entirely rulebased evaluation of a cell’s neighborhood in traditional cellular automatas, which we will deal with in the next post.

The image below, by Robert Munafo, is a fantastically helpful map of possible patterns resulting from various combinations of the f and K coefficients. Click the image to go to his website and explore the parameters in more detail (there’re close-ups and videos of all interesting combinations).

As with the other classes of the simutils package, the GrayScott implementation comes with several small demos to help you get started. The most basic use case (HelloGrayScott) is just setting up a simulation with default parameters and then allows you to draw in the simulation space with the mouse. Each frame, the reaction is updated, its new state translated into grayscale pixels and then rendered to the screen. The important thing to know here is that there’re 2 separate results states available, normally called the u and v buffers.

GrayScott gs;

// create a new simulation instance
// the "false" refers to a non-tiled space with walls
// set to true to create tiling patterns
gs=new GrayScott(width,height,false);

// configure the simulation params to:
// f=0.023, K=0.074
// diffusion speed for u buffer = 0.095
// diffusion speed for u buffer = 0.03
gs.setCoefficients(0.023,0.074,0.095,0.03);

The main draw() loop then just does this:

void draw() {
  if (mousePressed) {
    // set cells around mouse pos to max saturation
    gs.setRect(mouseX, mouseY,20,20);
  }
  loadPixels();
  // update simulation by 10 time steps per frame
  for(int i=0; i<10; i++) gs.update(1);
  // read out the v buffer and translate into grayscale colors
  for(int i=0; i<gs.v.length; i++) {
    float cellValue=gs.v[i];
    // the cell values in v are usually in the range 0.0 .. 0.33
    int col=255-(int)(min(255,cellValue*768));
    // use the col value for red, green and blue and set alpha to full opacity
    pixels[i]=col<<16|col<<8|col|0xff000000;
  }
  updatePixels();
}

To avoid this manual pixel pushing and enable us to make some of the subtle changes of densities more obvious, we can also use the handy (and also new) ToneMap class of the colorutils package. This allows us to map a number range to different positions (colors) on a multi-color gradient and so potentially better visualize the different densities. The basic usage of this class is shown below:

import toxi.color.*;

ToneMap toneMap;

// define a color gradient by adding colors at certain key points
// a gradient is like a 1D array with target colors at certain points
// all inbetween values are automatically interpolated (customizable too)
// this gradient here will contain 256 values
ColorGradient gradient=new ColorGradient();
gradient.addColorAt(0, NamedColor.BLACK);
gradient.addColorAt(128, NamedColor.RED);
gradient.addColorAt(192, NamedColor.YELLOW);
gradient.addColorAt(255, NamedColor.WHITE);

// now create a ToneMap instance using this gradient
// this maps the value range 0.0 .. 0.33 across the entire gradient width
// a 0.0 input value will be black, 0.33 white
toneMap=new ToneMap(0, 0.33, gradient);

Now we can refactor our Gray-Scott rendering code into something even simpler:

for(int i=0; i<gs.v.length; i++) {
    // take a GS v value and turn it into a packed integer ARGB color value
    pixels[i]=toneMap.getARGBToneFor(gs.v[i]);
}

Btw. The ToneMap class is a nice example of the whole reusable “building block philosophy” of toxiclibs (and the object oriented approach in general). The class is simply a composition of other library classes and under the hood delegates everything to these elements:

All other GrayScott demos, as well as all Cellular Automata examples, make use of this ToneMap class, so do have a look at those for more reference…

Since a homogeneous configuration of the entire sim grid will always just provide one particular character/patterning, the GrayScott class has been designed with extension in mind. The CustomGrayScott demo shows how to impose a pattern on the actual simulation parameters themselves, so that cells at different positions are evaluated using different parameters:

class PatternedGrayScott extends GrayScott {

  // our constructor just passes things on to the parent class
  PatternedGrayScott(int w, int h, boolean tiling) {
    super(w,h,tiling);
  }

  // this function is called for each cell
  // to retrieve its f coefficient
  public float getFCoeffAt(int x, int y) {
    // here we only take the x coordinate
    // and choose one of 2 options (even & odd)
    x/=32;
    return 0==x%2 ? f : f-0.005;
  }

  // this function is called for each cell
  // to retrieve its K coefficient
  public float getKCoeffAt(int x, int y) {
    // here we only use the y coordinate
    // and create a gradient falloff for this param
    return k-y*0.00004;
  }
}

Instead of using the default GrayScott class, we only need to change one line in the setup() method to use our extended version instead:

GrayScott gs;

void setup() {
	size(200,200);
	gs=new PatternedGrayScott(width,height,false);
	...
}

The result of this is shown below… Easy, huh? :)

Having this mechanism in place, it can be also used to create more interesting types of masking. For a commission to produce a cover design for Print Magazine in 2008, I generated a type face from simple line & arc segments and used it as mask to manipulate the concentrations of the f & K parameters to achieve two different types of patterning: one for the inside of the letter shapes, the other for the outside…

The frames of that animation were then stacked up along the Z axis in 3D space and with the help of the volumeutils classes turned into 3D mesh, exported as STL format (also see TriangleMesh.saveAsSTL()) and finally fabricated into the physical, 3D printed sculpture shown below. In a way, the sculpture can be seen as a map of its entire creation process…

Here’re some more rendered detail shots of the sculpture. More information about this project is here and the related flickr set.

Finally, the GrayScottImage demo shows another supported technique of using the library: the seeding of the simulation using a bitmap image.

I’ve been working on some designs for custom made wheels for a potential installation project. The aim is to lasercut some light-weight & good looking acrylic wheels and so I’ve been literally searching for a few candidate solutions, which allow me to cut out large pieces of material from inside the wheel to keep the weight down whilst still being sturdy enough (thankfully the load on them will be minimal so I can skip the structural analysis).

Not wanting to do this exploration/hike manually, I opted for the Processing PDF output route and have written this little tool below to show me my options (at least some of them) and also tweak them easily.

Apart from Processing, the tool also makes use of these 3 classes from the toxiclibscore package:

Vec2D

This class, alongside its sibling Vec3D, is likely one of the most used classes of the entire library. Since 1.0 Processing has its own vector class too now, but Vec2D/3D are far more feature complete, implement a fluent interface for more legible code when dealing with complex vector maths and can be faster too (especially for 2D, but also by helping you to avoid temporary object creation). Furthermore Vec2D also has support for polar coordinates (Vec3D has spherical as equivalent) which was very helpful for building the tool below:

Normally, you’d specify a Cartesian point with:

Vec2D v = new Vec2D(x, y);

However, if we want to interpret our vector as polar coordinates, we’re using the x component to specify the radius and the y component as rotation angle. To convert the vector back into Cartesian space (e.g. our screen) we can use the .toCartesian() method…

Vec2D v = new Vec2D(radius, theta).toCartesian();

In a similar manner, you can also transform a Cartesian point into polar coordinates:

// here we 1st create a copy of v and then convert that one
Vec2D p = v.copy().toPolar();

To see this basic usage pattern in more context, take a closer look at the drawHoles() method below (lines 114-134) or check out the PolarUnravel demo bundled with the core lib.

Spline2D

Each cut-out shape in the wheel is created from a simple spline shape, specified using only 4 points. As mentioned above, these anchor points are specified using (initially) polar coordinates and the Spline2D class is then computing control points (handles) for each of these given points automatically. As user you can also specify tightness & subdivisions for the computed curve vertices in between. While the lack of direct manual control over the spline handles might be a shortcoming in some situations, I generally found it easier to work with this automated version, especially when working with long curves and not only single bezier segments.

The next release of the library will also add a decimator method to this class which will enable the sampling of the curve at a uniform interval (i.e. all successive points of the returned list have the same distance (within a tolerance), regardless of curvature). This feature comes from the ParticlePath class briefly described in the Happy 2010 post.

Computing symmetrical handles for the curve endpoints is another still outstanding feature, but currently low priority (unless someone has got a patch ready for that ;)

The next image shows the 4 anchor points of each spline shape in green and all other computed vertices in pink.

UnitTranslator

This class is the sole, lonely member of the toxi.math.conversion package, but is especially useful for those of you using Processing for digital fabrication or creating printed outputs. It provides the following conversion methods, making it trivial to e.g produce PDF outputs at the right physical dimensions (without trial & error):

• millisToPixels(double mm, int dpi) – Converts millimeters into pixels.
• millisToPoints(double mm) – Converts millimeters into PostScript points.
• pixelsToInch(int pix, int dpi) – Converts pixels into inches.
• pixelsToMillis(int pix, int dpi) – Converts pixels into millimeters.
• pixelsToPoints(int pix, int dpi) – Converts pixels into points.
• pointsToMillis(double pt) – Converts points into millimeters.
• pointsToPixels(double pt, int dpi) – Converts points into pixels.

In the demo below, we’re using it to specifiy the wheel radius and drill holes in mm and then automatically calculate the required window size in pixels. In that case we’re however not using millisToPixels(), but millisToPoints() because PDF units are in points which are interpreted as 1 pixel (at 72 dpi)…

The Wheel tool

Just copy & paste the code below into Processing and hit Run to fill up your hard disk (kidding, by default it only generates 120 different small PDF files/variations). The variations are created by iterating over all permutations of 4 parameters: number of symmetry steps, inset radius, core radius, alternate core radius.

/**
 * Generative wheel designs utilizing Vec2D polar coordinates,
 * splines and unit conversion. By default each design is exported as
 * PDF & PNG file, but can be turned off by setting the doExport flag to false.
 *
 * Usage: if export is enabled simply run & wait until all permutations
 * have been generated. Else press 'x' to activate next permutation or
 * use - / = to adjust the ARC_WIDTH parameter which defines the
 * size of the cutouts.
 *
 * (c) 2010 Karsten Schmidt, PostSpectacular Ltd.
 *
 * More info: http://toxiclibs.org/2010/01/re-inventing-the-wheel/
 * Source code licensed under GPL v3.0. See http://www.gnu.org/licenses/gpl.html
 */

import processing.pdf.*;

import toxi.geom.*;
import toxi.math.conversion.*;

// bleed in mm
int BLEED = 6;

// wheel radii & document size
float R = (float)UnitTranslator.millisToPoints(370 / 2);
float W = 2 * R + 2 * (float)UnitTranslator.millisToPoints(BLEED);
float EMPTY_CORE_SIZE = (float)UnitTranslator.millisToPoints(5);

// start number of main segments
int NUM_SEGMENTS = 3;

// normalized parameters
float INSET_RADIUS = 0.8f;
float OFFSET = 0.1f;
float CORE_RADIUS = 0.15f;
float ALTCORE_RADIUS = 0.3f;
float ARC_WIDTH = 0.4f;

// optional mounting holes
int NUM_DOTS = 18;
float DOT_RADIUS = 0.97f;
float DOTSIZE = (float)UnitTranslator.millisToPoints(2);

// number of subdivisions for spline vertex computation
int SPLINE_SUBDIV = 20;

// flag for PDF & PNG export of all permutations
boolean doExport = true;

public void setup() {
  size((int) W, (int) W);
  // turn off automatic redraws when not exporting
  if (!doExport) {
    noLoop();
  }
}

public void draw() {
  String frameID =
    "wheel-" + NUM_SEGMENTS + "-" + nf(INSET_RADIUS, 1, 2) + "-"
    + nf(ALTCORE_RADIUS, 1, 2) + "-"
    + nf(CORE_RADIUS, 1, 2) + "-" + nf(ARC_WIDTH, 1, 2);
  println(frameID);
  if (doExport) {
    beginRecord(PDF, "out/" + frameID + ".pdf");
  }
  background(255);
  noStroke();
  fill(0);
  translate(width / 2, height / 2);
  ellipseMode(RADIUS);
  ellipse(0, 0, R, R);
  fill(255);
  ellipse(0, 0, EMPTY_CORE_SIZE, EMPTY_CORE_SIZE);
  // main holes
  drawHoles((INSET_RADIUS + OFFSET) * R, CORE_RADIUS * R, (INSET_RADIUS
    + OFFSET + CORE_RADIUS)
    / 2 * R, ARC_WIDTH, 0, NUM_SEGMENTS);
  if (CORE_RADIUS >= 0.5) {
    drawHoles(CORE_RADIUS * 0.85f * R, 0.2f * R,
    (CORE_RADIUS * 0.85f + 0.2f) / 2 * R, ARC_WIDTH, 0,
    NUM_SEGMENTS);
  }
  // small cutouts
  drawHoles(INSET_RADIUS * R, ALTCORE_RADIUS * R,
  (INSET_RADIUS + ALTCORE_RADIUS) / 2 * R, ARC_WIDTH / 2, PI
    / NUM_SEGMENTS, NUM_SEGMENTS);
  if (ALTCORE_RADIUS >= 0.5) {
    drawHoles(ALTCORE_RADIUS * 0.85f * R, 0.3f * R,
    (ALTCORE_RADIUS * 0.85f + 0.3f) / 2 * R, ARC_WIDTH / 2, PI
      / NUM_SEGMENTS, NUM_SEGMENTS);
  }
  // drill holes
  drawDots(NUM_DOTS, DOT_RADIUS * R, DOTSIZE);
  if (doExport) {
    endRecord();
    saveFrame("png/" + frameID + ".png");
    nextPermutation();
  }
}

void drawDots(int num, float radius, float s) {
  float delta = TWO_PI / num;
  for (int i = 0; i < num; i++) {
    Vec2D p = new Vec2D(radius, i * delta).toCartesian();
    ellipse(p.x, p.y, s, s);
  }
}

void drawHoles(float outerR, float innerR, float centerR, float radiusWidth, float thetaOffset, int num) {
  radiusWidth *= PI / num;
  Spline2D s = new Spline2D();
  // define point in polar coordinates, then convert them
  Vec2D p = new Vec2D(outerR, 0).toCartesian();
  Vec2D a = new Vec2D(outerR, radiusWidth).toCartesian();
  Vec2D b = new Vec2D(centerR, radiusWidth).toCartesian();
  Vec2D c = new Vec2D(innerR, 0).toCartesian();
  Vec2D d = new Vec2D(centerR, -radiusWidth).toCartesian();
  Vec2D e = new Vec2D(outerR, -radiusWidth).toCartesian();
  // add points to spline & compute
  s.add(p).add(a).add(b).add(c).add(d).add(e).add(p);
  java.util.List verts = s.computeVertices(SPLINE_SUBDIV);
  float delta = TWO_PI / num;
  for (int i = 0; i < num; i++) {
    pushMatrix();
    rotate(i * delta + thetaOffset);
    drawPath(verts);
    popMatrix();
  }
}

void drawPath(java.util.List verts) {
  beginShape();
  for (Iterator i = verts.iterator(); i.hasNext();) {
    Vec2D v = (Vec2D) i.next();
    vertex(v.x, v.y);
  }
  endShape();
}

public void keyPressed() {
  if (key == 'x') {
    nextPermutation();
  } else if (key == '-') {
    ARC_WIDTH -= 0.02;
  } else if (key == '=') {
    ARC_WIDTH += 0.02;
  }
  redraw();
}

void nextPermutation() {
  CORE_RADIUS += 0.2;
  if (CORE_RADIUS >= INSET_RADIUS) {
    CORE_RADIUS = 0.15f;
    ALTCORE_RADIUS += 0.2f;
    if (ALTCORE_RADIUS >= INSET_RADIUS) {
      ALTCORE_RADIUS = 0.3f;
      INSET_RADIUS += 0.1f;
      if (INSET_RADIUS > 0.8) {
        NUM_SEGMENTS++;
        INSET_RADIUS = 0.8f;
        if (NUM_SEGMENTS > 12) {
          exit();
        }
      }
    }
  }
}

Finally, below are some more images of variations created with this tool (see the full size & set on flickr):

The Processing source code for generating these meshes is available with the library download, with an excerpt shown also below. But first, here’s a brief overview of how to use these classes:

Waves & oscillation in general are very flexible & powerful tools for many different design tasks and shouldn’t always be thought of in an audio context. For example, a square wave can be used to flick between 2 values at a given frequency, without the need for any if() statements. I also often use sine waves to create cyclical, soft, harmonious value changes, be it for interface design, movement, animation or even the time based modulation of behavioural parameters of agents. The core library comes with the following pre-defined wave types:

• Sine (pure, frequency modulated (FM), amplitude & frequency modulated (AMFM))
• Sawtooth (FM)
• Square (FM and FM with harmonics)
• Triangle (FM)
• Constant (only provides a static value, e.g. useful as static source for input as FM)

All of these types are expressed as implementations of the AbstractWave class in the toxi.math.waves package. This abstract class defines all commonalities of what constitutes a wave: a phase, a frequency, an amplitude, a centre offset and a bunch of accessors and converters. The actual wave function then needs to be implemented by a concrete sub-class. Using poly-morphism and having an abstract super class makes a lot of sense in this case, since it allows for all this:

1. It frees our main application from having to know which exact wave type we’re going to use and so allows for easier/faster experimentation and generally more flexibility.
2. It enables us to plug-in any of the available wave types as input for frequency or amplitude modulation and so create highly (theoretically infinitely) complex waveforms.
3. It provides the basics of an extensible framework for creating new wave types.

These points are hopefully confirmed by you when looking at this method below (taken from the AdditveWaves demo, bundled since toxiclibscore-0015):

AbstractWave createRandomWave() {

  AbstractWave result=null;

  // create a randomized sine wave to be used as
  // FM input for the main wave chosen below
  // the order of parameters is:
  // start phase, frequency (in radians), amplitude, offset value
  AbstractWave fmod=new SineWave(0, random(0.005, 0.02), random(0.1, 0.5), 0);

  // pick a random frequency
  float freq=random(0.005, 0.05);

  // choose a wave type
  switch((int)random(7)) {
  case 0:
    result = new FMTriangleWave(0, freq, 1, 0, fmod);
    break;
  case 1:
    result = new FMSawtoothWave(0, freq, 1, 0, fmod);
    break;
  case 2:
    result = new FMSquareWave(0, freq, 1, 0, fmod);
    break;
  case 3:
    // harmonic square waves are created by
    // adding sine waves upto a number of octaves
    // above the base frequency
    result = new FMHarmonicSquareWave(0, freq, 1, 0, fmod);
    ((FMHarmonicSquareWave)result).maxHarmonics=(int)random(3,30);
    break;
  case 4:
    result = new FMSineWave(0, freq, 1, 0, fmod);
    break;
  case 5:
    AbstractWave amod=new SineWave(0, random(0.01,0.2), random(2, 3), 0);
    result = new AMFMSineWave(0, freq, 0, fmod, amod);
    break;
  case 6:
    result = new ConstantWave(random(-1,1));
    break;
  }
  return result;
}

The next snippet then quickly shows how this method would be used:

import toxi.math.waves.*;

AbstractWave wave=createRandomWave();

// updates the wave phase and computes the new function value
// this code doesn't care which wave type we're dealing with
float currValue=wave.update();

The generators have another useful feature, though: A state stack. If you’ve used Processing or OpenGL before, you have likely come across the concept in the form of pushMatrix()/popMatrix() calls to save and restore the state of the graphical transformation matrix. The wave generators implement the same idea and so can be easily used to create the 3D meshes above.

// save current wave state
wave.push();

for(int i=0; i<10; i++) {
  float lookahead=wave.update();
  // do something clever
}

// restore wave to previous state
wave.pop();