MooCirclePack: a javascript circle packing library

The purpose of this script is to bring circle packing to Javascript, as opposed to Flash or Java. While this implementation is less efficient than the aforementioned technologies, it produces a nice data visualization and is quick and simple for anyone to set up. The script is licensed under an MIT-style license.

There are two components to creating an interactive circle packing visualization. The first component is the Circle class. The Circle class is the building block of the visualization; each instance created represents a circle on the canvas. The class takes up to five arguments:

new Circle(x, y, radius, color[, image])

The x and y arguments specify the circle's starting position on the canvas. This can generally be random (within the boundaries of the canvas), as the circle will move around anyway. The radius is the circle's radius in pixels. Color should be a string in the format rgba(r, g, b, alpha). Alpha can be any decimal between 0 and 1, while R, G, and B are between 0 and 255. Image, the final argument, is optional. This argument allows you to superimpose an image onto the circle. This would be helpful if you wanted to visually display what that particular circle represented. The second component is the class that does all the work, the MooCirclePack class. It takes two arguments:

new MooCirclePack(circleArray, canvasElement);

circleArray, the first argument, is an array of Circle objects. These are the objects that you want packed. The canvas element (canvasElement) can be passed as either an element reference or an id string. The MooCirclePack can also generate a visualization based on a JSON request. There is a special sub-class used to make this call, named MooCirclePack.Remote. The main difference in calling this class is that there are now three new initialization arguments:

new MooCirclePack.Remote(url, method, query, canvasElement);

These arguments are fairly self-explanatory, but briefly: the first argument is the request URL, the second argument is the method (POST, GET), the third argument is any query string you want to pass (?arg=data), and the fourth is (obviously) the canvas element. There are also a few important functions within MooCirclePack. The first of these functions is run(), which begins the whole circle packing action for the first time. This needs to be run at after initializing the MooCirclePack object. hook() and unhook(), the other functions, allow you to let the user drag the circles around and interact with them. hook() needs to be called manually, but unhook() is called automatically on page unload. Speaking of interactivity, there are a few events that can be watched through the MooCirclePack class, using MooTools' addEvent function:

settleStart: function(),
settleEnd: function()

settleStart and settleEnd are called when the packing iterator begins and ends. This is useful if you want to display a status message to the user. There are also a few events that are only called after hook() has been initialized:

dragStart: function(circleObject),
onDrag: function(circleObject, x, y),
dragEnd: function(circleObject),
mouseOver: function(circleObject, x, y),
mouseOut: function(circleOjbect, x, y)

The drag functions work like any standard drag callbacks. The circleObject returned is the Circle object that is being dragged. mouseOver and mouseOut are called whenever the mouse is moved over/off a circle, but only when nothing is currently being dragged. It returns the current mouse x/y and the Circle object that was entered/left. One final tidbit: the mousewheel. If you scroll the mousewheel up or down, you can zoom in/out of the visualization.

Getting started with MooCirclePack is a snap. Below, I will go over the steps to create a very basic example. First, include the necessary files in the header of your page:

<script type="text/javascript" src="js/mootools-1.2-core-nc.js">
</script>
<script type="text/javascript" src="js/mootools-1.2-more.js">
</script>
<script type="text/javascript" src="js/excanvas.js"></script>
<script type="text/javascript" src="js/moocirclepack.js"></script>

Next, create your Circle objects:

var circles = [
                new Circle(10, 10, 50, 'rgba(120, 80, 120, 0.75)'),
                new Circle(20, 25, 20, 'rgba(174, 175, 76, 0.75)'),
                new Circle(30, 40, 70, 'rgba(88, 88, 120, 0.75)'),
                new Circle(65, 65, 10, 'rgba(205, 55, 140, 0.75)')
              ];

Then you add a canvas tag to the body of your document:

<canvas id="canvasElement" width="500" height="500"></canvas>

And finally, go back to your script, initialize your MooCirclePack object and run it:

var packer = new MooCirclePack(circles, 'canvasElement');
packer.run();
packer.hook();