toxiclibs roadmap Q4/2011 - Q2/2012 (click to enlarge)

A bit of philosophy

From the very outset, the creation of design oriented, composable and reusable data structures and algorithms for manipulating them has been the main aim of this project and also one of the most obvious counter approaches to the way people traditionally work with Processing (hitherto the most used environment for the libs). Even though the majority of classes provided by toxiclibs can have a visual representation, there’s a strict exclusion of any rendering related code in the core packages of the library, since these often carry a vast amount of secondary dependencies, eventually binding the library to a large, rigid environment. Me not likey. Almost all toxiclibs classes are “pure” models which can be queried, transformed, combined and otherwise manipulated as abstract entities. They’re usable as a tool for solving (design) problems, not only for drawing. They are the M in MVC. If one of them ever needs to be drawn/rendered, a 3rd party component is required (the V in MVC, e.g. Processing or straight OpenGL), but toxiclibs does not prescribe how this drawing should be done (but it provides optional tools to support that task). This separation of concerns really has been the #1 feature aimed at making it as easy as possible (and encouraging) to enter this next stage of the project: systematically porting to other languages.

Polyglot toxiclibs

JavaScript

In the past, myself and other people have done half-baked attempts to port selected classes to other languages (ActionScript, JavaScript, C++). However, all of them were just isolated fragments needed for specific projects and never approached general library status even closely. As most people are surely aware of by now, since the beginning of the year Mr. Kyle Philips has been doing a stellar effort systematically porting large parts of the toxiclibs core and physics classes to JavaScript and due to the popularity of that language this port is gaining huge traction. That’s exactly what I’ve been hoping for to happen as an eventual consequence of the above design points, so I’m super happy to see this effect kicking in. JavaScript however does not only mean in-browser usage, even though in combination with WebGL and libraries like three.js & Processing.js the number of potential use cases is huge (I’d say even more so than in the traditional Processing tied context). JavaScript’s reach is massive and it also has deservedly gained traction outside the browser as general purpose language (largely thanks to V8 based platforms, like Node.js, but also Dean McNamee‘s Plask as a more related example). I think toxiclibs can contribute and actively support new developments on these platforms.

In terms of similarity and porting, JavaScript is one of the closest things to Java there is, but it also has unique deployment issues and there’s some substantial organizational effort needed to create a better system for splitting the codebase into modules and integrating the JS port with existing coding standards (CommonJS) and module managers/loaders (e.g. NPM, RequireJS), incl. to start thinking about adopting Google Closure conventions to harness the optimizations achievable by that compiler (e.g. dead code removal, a huge benefit for large libraries as this).

Good API design requires a clean, consistent ethos, a worldview and opinion which not only is carried through and made visible throughout a project, but also leads users of that API to write their own software in a certain/similar manner. To achieve that goal is often a long, winding road and takes much longer to get right than writing actual code, but I think by now, toxiclibs does provide a decent set of consistently used patterns (excluding a few edge cases). Having such a familiar set of classes & APIs available in multiple languages is a serious benefit for users and makes it much easier to experiment & switch between environments, and that without forcing users to stay in a sandbox of sorts (e.g. as ProcessingJS does). I think, having a familiar API too needs to be complimented & balanced with the unique features, idioms and development practices of the host language to allow both code & coder live up to their full potential. For JS these differences are still relatively harmless, but even there we should embrace them more.

Clojure

Ever since college, I had an ongoing, if usually fleeting, fascination with Lisp and its seemingly alien, stripped down approach to syntax, its obsession with brackets and generally doing things “the way round”, at least compared to common (imperative) languages. I never considered Lisp as a serious contender for my own development arsenal until earlier this summer, when I stumbled across Clojure, a modern dialect of Lisp running on the JVM (get a detailed feature overview on their website, it’s worth reading). This time I immediately was struck by its elegance, the resulting concise code and the many other features this language brings to the table, especially for working with collections, data processing & concurrency. Many data munging tasks can be solved in approx. 30-50% code than in Java/Processing, very useful for dataviz. So I made an effort to get into it more seriously. Then I read this article and when I hit this quote, I felt in very similar shoes:

“Many extremely intelligent people I knew and had much respect for were praising Lisp with almost religious dedication. There had to be something there, something I couldn’t afford not to get my hands on! Eventually my thirst for knowledge won me over. I took the plunge, bit the bullet, got my hands dirty, and began months of mind bending exercises. It was a journey on an endless lake of frustration. I turned my mind inside out, rinsed it, and put it back in place. I went through seven rings of hell and came back. And then I got it.

The enlightenment came instantaneously. One moment I understood nothing, and the next moment everything clicked into place. I’ve achieved nirvana.”

Similar to Scala, Clojure compiles directly into JVM byte code and therefore provides comparable speed and can easily interoperate with the vast amount of Java libraries available. Unlike Java, Clojure is focused on immutable data and provides a functional approach to computing, an antidote to living a kingdom of nouns. Common to all Lisps also is the REPL, offering livecoding features as part of the core development process. Lisp/Clojure code is data is code. I don’t need to point out, how exciting this is for people in our field. Besides that though, my main excitement is about the forward thinking take on concurrency/multicore support (agents/futures/atoms/refs) and the ability to easily create domain specific languages. Community activity around the language seems to be glowing hot and is sporting an impressive ecosystem of libraries and amazing support tools, making open source development true fun. Some noteworthy introductory links, should you feel inclined to give it a spin too:

• Clojure – Functional programming for the JVM
• The Joy of Clojure
• Casting Spels in Clojure
• learn-clojure.com
• 4clojure

ClojureScript

ClojureScript is a recent addition to the Clojure ecosystem and potentially something to keep watching closely for the purposes of porting: Clojure compiled into JavaScript. I know it sounds like herasy, but in some respects it seems ClojureScript does “better” JavaScript than the original, providing all the intelligent language features of Clojure (e.g. namespaces, destructuring, function overloading, atoms, macros) and generating JavaScript in a format targeted to Google’s Closure compiler, allowing for vastly better optimizations of large applications than handwritten JavaScript (which can only fully utilize the compiler if you stick to the necessary conventions in ALL your code). I’m in no position yet to actually back any of that with my own experience so far, but it’s an exciting development for sure. Here’s also a video of the launch event of ClojureScript at Google: Rich Hickey (creator of Clojure) unveils ClojureScript and the official announcement with more links.

Keeping in sync & documentation

The next major set of tasks related to porting is figuring out ways to keep the different ports in sync or at least better document which parts of the library are available in which port. For that purpose, I started prototyping a new web app (WebNoir + CouchDB) which will collect metadata from the different source codes and automatically produce a port coverage/sync report. Kyle started manually producing a top-level version of this for his JS port, but its granularity is only at class level, whereas we really do need that information per function/method to be truly useful. This is also because there are still some areas of the original Java version, which will receive further updates and bug fixes and at current there’s no system to mark those places in the code as needing to be reflected in the other ports. Serious development of this tool is top priority after v0021 is out.

Related to that also is documentation, the historically slowest evolving aspect of the whole project. One of the comments I hear most often is “Javadocs suck”. They suck even more so, since for many library classes they’re not even existing or if so only superficially. So in a way I couldn’t agree more, but then again, for the past four years these libraries have largely evolved around my own needs and client projects and I’ve relied on users to consult the 95+ examples bundled with each release (or attend my workshops) in order to learn the basic usage patterns. Whilst I still believe the latter (learning by example) is by far the most efficient way of learning (having done so my entire career), I also think things can be vastly improved by offering documentation in several formats, all cross-referenced between: actual running examples with source code, a literate programming style doc system (e.g. Docco/Marginalia based, very good for workshops) and the traditional javadoc style, for integrating the docs in an IDE setup.

Example output of running an early(ier) Clojure porting effort through Marginalia to produce nice, easy to read documentation next to source code.

IMHO the reason Javadocs are soooo unsuccessful amongst Processing users is actually largely down to the lack of Javadoc support in the Processing PDE. If people would use IDEs like Eclipse showing Javadocs in-situ within the editor context by simply hovering over class names, I believe people would see them for what they really are: kind of awesome!

Eclipse screenshot with Javadocs in editor context.

So in conjunction with the task of adding metadata to every method of every public class in the codebase, all methods will also be receiving full documentation. These docs will then also link to existing examples using the particular method. This will be the second main focal point of the v0022 release (the one after next).

Versioning & repositories

Speaking of version numbers: Again, due to the organic and isolated growth of this project and my own past development practice, the linear versioning scheme was quite sufficient for now. As we all learn new things and our development tactics change, so too will the versioning for this project have to change to something more meaningful. Enter semantic versioning. The idea is nothing new and I’ve been using it for most other projects in the past, but I think this time the reasoning behind it is somewhat different:

1. Currently there’s toxiclibs support for 2.1 languages (the Clojure port is not quite there yet to fully count)
2. Development outside the Processing IDE is far more dependent on build management tools, open source repositories and module managers (e.g. Maven, NPM, Leiningen)
3. Different projects are created at different times and might require different versions of the libraries and
4. I’d really love to get to a point where there’ll be synchronised releases in order to reduce build & documentation complexity and avoid confusion for users so that they can assume v1.0.0 of a module will contain the same features in all (sup)ported languages.

Semantic versioning is the lowest common denominator between all current module managers/repositories and hence will be introduced with the next release. As a result, users will have a much easier way to integrate the libraries into their own (non-Processing) projects, since they will also be available via the major existing open source repositories for the various languages (Sonatype [Java/Maven], NPM registry (JS), Clojars [Clojure/Leiningen]). Apparently, Processing 2.0 will feature its own centralized library management system, but from what I gather it will not offer any integration with any of these existing open source repositories.

New website & tutorials

The current WordPress based setup is not the best platform for integrating all the planned new documentation, tutorials and other features like the bundled example & user galleries. I’ve been test driving Confluence on a private dev server and found this more promising (at least for the documentation & tutorial side), so I might adopt this in the near future. The other (more appealing) alternative is to extend the new CouchDB based sync/doc tool into a more generic web app and add wiki & blogging features. The main issue for that will be increased hosting costs, which I will need to think about more how they can be better balanced. The new website will also host as many of the bundled examples as possible, effectively deprecating the current gallery on openprocessing.org, which is impossible to batch update and therefore can’t reflect any API changes in older examples (which causes unnecessary comments). To better integrate community contributions, that new system will also be used to provide a user gallery.

Furthermore, if you’re like the amazing Amnon Owed, and feel like creating super useful tutorials for the libraries, please start doing so. Any help on increasing the number of learning resources would be an amazing contribution to this project and will play a major role on the new site. Speaking of tutorials, I really do think there also is a big need for a general knowledge tutorial about how to make the most of open source libraries like this from a user perspective and encourage people to contribute (even if in the most indirect ways). Much of the feedback and comments I receive, hints at a large knowledge gap about how to even go about finding out (in a self guided manner) about existing resources, updates, work with the source code, work with issue trackers etc. This generally seems to be a far bigger problem with users in the Processing camp than I’m aware of from other environments. Food for thought!

Summary & next steps

Well, this is the closest thing to a sharable master plan as I could get to for now. Before most of these things will/can be addressed, other minor tasks need to be completed to get 0021 out of the door first. A brief, non-exhaustive overview of new features is here:

• Initial support for NURBS curves and surfaces is the biggest new addition and still requires some more testing and internal restructuring. Supported operations are:
  • Curve builders for circles, arcs and creating curves from a list of points, joining curves
  • Surface builders: extrude curve, revolve curve, construct surface from a grid of points/control mesh
  • Convert surface into TriangleMesh instance (variable resolution & UV coordinate generation)
• Several important additions to the Polygon2D class:
  • construct regular polygons from a given base line segment (useful for creating tesselations)
  • rotate/scale/translate polygons
  • pick random points within a polygon (useful for color sampling)
  • retrieving edge list
• Tesselate polygons using Delaunay triangulation with flexible grid resolutions
• Addition of ConvexPolygonClipper to clip a polygon to the shape of another
• New BezierCurve2D/3D classes in addition to existing Spline2D/3D
• Implementing Visitor pattern for PointQuadtree/PointOctree
• Adding UV coordinate generation to SurfaceMeshBuilder
• Adding PLYWriter for exporting 3D meshes in Standard Polygon format
• ToxiclibsSupport line drawing now supports decorators for dashed lines and arrow heads (customizable)
• Custom DXFWriter for 2D shapes with DXF layer support
• Improving precision/reducing rounding errors for VolumetricBrush
• Adding FluidSolver3D

There’re also a ton of other smaller additions and bug fixes plus approx. 10-15 new examples. Let me also point you again to the repository of workshop projects at learn.postspectacular.com, which contains also several larger projects than the examples bundled with the release.

Showreel

A few people have been asking about sending in stuff for this year’s showreel. Of course, I do intend to produce one again (it’s one of the highlights of the year), though I can only realistically get to this in Nov/Dec, hopefully making it a nice video for the Holiday season. I will send out a proper call for submissions in the next month, but if you have stuff ready, please send it along already. Specs will be the same as previously: Video assets 1280×720 (if possible), still images are fine too and of course please add some brief description & credits.

Any feedback, suggestions & help offers are highly appreciated! So long…

In the past few days I’ve uploaded 20 new demos (many of them using new functionality) to OpenProcessing. The release contains now 95 demos(!) in total, incl. several complete exercises of workshops I’ve taught throughout the past years. So let’s please also say thank you to the universities & institutions which made these possible!

Here’s also a quick list of some key additions & updates (some were already quietly introduced with the 0019 release in summer, but never documented). A complete & detailed changelog is bundled with each library module.

• 3D mesh construction & processing:
  • New Winged-Edge mesh class for structured 3D data & enabling complex mesh operations/navigation
  • Adding mesh subdivision strategies, vertex selectors & mesh filter classes (e.g. for modeling, smoothing)
  • New BezierPatch class for constructing 3D surfaces from 4×4 control points
  • Added .toMesh() methods for all 3D geometry primitives: AABB, Cone, Cylinder, Sphere, Plane, Terrain, BezierPatch
• Revamped architecture of all voxel based modeling classes:
  • VolumetricSpace is now an abstract class with array or HashMap based implementations
  • IsoSurface is now an interface with array or HashMap based implementations
  • HashMap implementations able to produce much higher resolution meshes
• Major refactoring of core geometry classes:
  • Introduction of immutable vectors (ReadonlyVec2D/3D)
  • Introduction of Shape2D/3D interfaces for more polymorphic client code
  • Support for barycentric coordinates in Triangle2D/3D
  • Added Sutherland-Hodgeman polygon clipping algorithm (useful for laser cutting tasks)
• Behavioral physics:
  • Massive refactoring of internal force handling & introduction of ParticleBehaviour implementations
  • Added Attraction and ConstantForce (Gravity) behaviours
  • Behaviours can be dynamically added globally (for entire sim) or to individual particles
• More maths:
  • Added bezier, exponential, threshold and decimated interpolation classes
  • SinCosLUT not a static class anymore, but can be instantiated with different precisions
• More utils:
  • Added FileSequenceDescriptor class for working with file sequences
  • Added FileUtils for file chooser dialogs, stream wrappers etc.
  • Added DateUtils for creating timestamps (with optional timezone support)
  • Added generic pluggable EventDispatcher helper to easily implement Observer pattern in client code
• Image based color palettes using new Histogram class in toxi.color package
• More simulations:
  • Added 2D heightfield erosion strategies: TalusAngleErosion, ThermalErosion (still lacking good demos)
  • Integrated optimized Jos Stam 2D fluid solver (from old 2006 demo, also still lacking bundled demo)

A lot of these above additions are in dire need for more documentation & tutorials. I will do my best to rectify this situation ASAP, but do hope the supplied demos do give you a jump start in the meantime. A lot of time went into creating & documenting them.

Likewise, to ensure the ongoing quality of the libraries and examples, please submit a bug report or enhancement request via the issue tracker…

Finally, another kind request, largely addressed to recent developments in the open source world around creative coding tools like this one: Please give credit where credit is due. If you’re using these libraries with Processing, please also list them in the tools used in your documentation (this is a separate project). Same goes for porting parts of these libraries to other languages. This social link back is hugely important and essential for this culture to exist and grow in the future.

Thank you & all the best for 2011!!

Having connectivity information for each vertex, edge and face of the mesh allows for a whole wide range of new, exciting applications and my first exploration on this front deals with various subdivision and mesh smoothing strategies and their use as generative modeling tools… I’m currently developing an extensible architecture to make this system as flexible as possible and you’ll be able to create your own custom strategies to decide about the location of new vertices, but without having to deal with any of the actual subdivision complexities itself, like splitting edges & faces. The same interface pattern thinking is also applied to mesh smoothing and currently I’ve implemented Laplacian smoothing and am working on other options as well…

All this should be very interesting for all users with a more architectural background, but IMHO has also lots of potential for those creating digital fabrication tools. If you have any interest in this and/or some useful pointers to share, please do get in touch!

Pending further testing, this new mesh structure and support architecture will available in the next release (0020)…

The mesh in the video and the examples below are using normal shading to help verifying the correctness of the edge/face splitting algorithm. Each vertex is tinted using its normal vector XYZ components interpreted as RGB color intensities.

These following images show a displacement-subdivided cube with (right) & without (left) mesh smoothing applied…

Some slightly older experiments from the early stages of developing the system. These meshes started out as a simple 8-point cube, subdivided 4-5 levels and then rendered as VBOs with standard gouroud shading…

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):

By Joe Turner

By DieTapete

By Stefan Mylleager

By Lia