rubyvis 0.1.0 → 0.1.1

data/vendor/src/physics/Simulation.js

@@ -0,0 +1,159 @@
+/**
+ * Constructs a new empty simulation.
+ *
+ * @param {array} particles
+ * @returns {pv.Simulation} a new simulation for the specified particles.
+ * @see pv.Simulation
+ */
+pv.simulation = function(particles) {
+  return new pv.Simulation(particles);
+};
+
+/**
+ * Constructs a new simulation for the specified particles.
+ *
+ * @class Represents a particle simulation. Particles are massive points in
+ * two-dimensional space. Forces can be applied to these particles, causing them
+ * to move. Constraints can also be applied to restrict particle movement, for
+ * example, constraining particles to a fixed position, or simulating collision
+ * between circular particles with area.
+ *
+ * <p>The simulation uses <a
+ * href="http://en.wikipedia.org/wiki/Verlet_integration">Position Verlet</a>
+ * integration, due to the ease with which <a
+ * href="http://www.teknikus.dk/tj/gdc2001.htm">geometric constraints</a> can be
+ * implemented. For each time step, Verlet integration is performed, new forces
+ * are accumulated, and then constraints are applied.
+ *
+ * <p>The simulation makes two simplifying assumptions: all particles are
+ * equal-mass, and the time step of the simulation is fixed. It would be easy to
+ * incorporate variable-mass particles as a future enhancement. Variable time
+ * steps are also possible, but are likely to introduce instability in the
+ * simulation.
+ *
+ * <p>This class can be used directly to simulate particle interaction.
+ * Alternatively, for network diagrams, see {@link pv.Layout.Force}.
+ *
+ * @param {array} particles an array of {@link pv.Particle}s to simulate.
+ * @see pv.Layout.Force
+ * @see pv.Force
+ * @see pv.Constraint
+ */
+pv.Simulation = function(particles) {
+  for (var i = 0; i < particles.length; i++) this.particle(particles[i]);
+};
+
+/**
+ * The particles in the simulation. Particles are stored as a linked list; this
+ * field represents the first particle in the simulation.
+ *
+ * @field
+ * @type pv.Particle
+ * @name pv.Simulation.prototype.particles
+ */
+
+/**
+ * The forces in the simulation. Forces are stored as a linked list; this field
+ * represents the first force in the simulation.
+ *
+ * @field
+ * @type pv.Force
+ * @name pv.Simulation.prototype.forces
+ */
+
+/**
+ * The constraints in the simulation. Constraints are stored as a linked list;
+ * this field represents the first constraint in the simulation.
+ *
+ * @field
+ * @type pv.Constraint
+ * @name pv.Simulation.prototype.constraints
+ */
+
+/**
+ * Adds the specified particle to the simulation.
+ *
+ * @param {pv.Particle} p the new particle.
+ * @returns {pv.Simulation} this.
+ */
+pv.Simulation.prototype.particle = function(p) {
+  p.next = this.particles;
+  /* Default velocities and forces to zero if unset. */
+  if (isNaN(p.px)) p.px = p.x;
+  if (isNaN(p.py)) p.py = p.y;
+  if (isNaN(p.fx)) p.fx = 0;
+  if (isNaN(p.fy)) p.fy = 0;
+  this.particles = p;
+  return this;
+};
+
+/**
+ * Adds the specified force to the simulation.
+ *
+ * @param {pv.Force} f the new force.
+ * @returns {pv.Simulation} this.
+ */
+pv.Simulation.prototype.force = function(f) {
+  f.next = this.forces;
+  this.forces = f;
+  return this;
+};
+
+/**
+ * Adds the specified constraint to the simulation.
+ *
+ * @param {pv.Constraint} c the new constraint.
+ * @returns {pv.Simulation} this.
+ */
+pv.Simulation.prototype.constraint = function(c) {
+  c.next = this.constraints;
+  this.constraints = c;
+  return this;
+};
+
+/**
+ * Apply constraints, and then set the velocities to zero.
+ *
+ * @returns {pv.Simulation} this.
+ */
+pv.Simulation.prototype.stabilize = function(n) {
+  var c;
+  if (!arguments.length) n = 3; // TODO use cooling schedule
+  for (var i = 0; i < n; i++) {
+    var q = new pv.Quadtree(this.particles);
+    for (c = this.constraints; c; c = c.next) c.apply(this.particles, q);
+  }
+  for (var p = this.particles; p; p = p.next) {
+    p.px = p.x;
+    p.py = p.y;
+  }
+  return this;
+};
+
+/**
+ * Advances the simulation one time-step.
+ */
+pv.Simulation.prototype.step = function() {
+  var p, f, c;
+
+  /*
+   * Assumptions:
+   * - The mass (m) of every particles is 1.
+   * - The time step (dt) is 1.
+   */
+
+  /* Position Verlet integration. */
+  for (p = this.particles; p; p = p.next) {
+    var px = p.px, py = p.py;
+    p.px = p.x;
+    p.py = p.y;
+    p.x += p.vx = ((p.x - px) + p.fx);
+    p.y += p.vy = ((p.y - py) + p.fy);
+  }
+
+  /* Apply constraints, then accumulate new forces. */
+  var q = new pv.Quadtree(this.particles);
+  for (c = this.constraints; c; c = c.next) c.apply(this.particles, q);
+  for (p = this.particles; p; p = p.next) p.fx = p.fy = 0;
+  for (f = this.forces; f; f = f.next) f.apply(this.particles, q);
+};

data/vendor/src/physics/SpringForce.js

@@ -0,0 +1,141 @@
+/**
+ * Constructs a new spring force with the specified constant. The links
+ * associated with this spring force must be specified before the spring force
+ * can be applied.
+ *
+ * @class Implements a spring force, per Hooke's law. The spring force can be
+ * configured with a tension constant, rest length, and damping factor. The
+ * tension and damping will automatically be normalized using the inverse square
+ * root of the maximum link degree of attached nodes; this makes springs weaker
+ * between nodes of high link degree.
+ *
+ * <p>Unlike other forces (such as charge and drag forces) which may be applied
+ * globally, spring forces are only applied between linked particles. Therefore,
+ * an array of links must be specified before this force can be applied; the
+ * links should be an array of {@link pv.Layout.Network.Link}s. See also
+ * {@link pv.Layout.Force} for an example of using spring and charge forces for
+ * network layout.
+ *
+ * @extends pv.Force
+ * @param {number} k the spring constant.
+ * @see #constant
+ * @see #links
+ */
+pv.Force.spring = function(k) {
+  var d = .1, // default damping factor
+      l = 20, // default rest length
+      links, // links on which to apply spring forces
+      kl, // per-spring normalization
+      force = {};
+
+  if (!arguments.length) k = .1; // default spring constant (tension)
+
+  /**
+   * Sets or gets the links associated with this spring force. Unlike other
+   * forces (such as charge and drag forces) which may be applied globally,
+   * spring forces are only applied between linked particles. Therefore, an
+   * array of links must be specified before this force can be applied; the
+   * links should be an array of {@link pv.Layout.Network.Link}s.
+   *
+   * @function
+   * @name pv.Force.spring.prototype.links
+   * @param {array} x the new array of links.
+   * @returns {pv.Force.spring} this, or the current array of links.
+   */
+  force.links = function(x) {
+    if (arguments.length) {
+      links = x;
+      kl = x.map(function(l) {
+          return 1 / Math.sqrt(Math.max(
+              l.sourceNode.linkDegree,
+              l.targetNode.linkDegree));
+        });
+      return force;
+    }
+    return links;
+  };
+
+  /**
+   * Sets or gets the spring constant. The default value is 0.1; greater values
+   * will result in stronger tension. The spring tension is automatically
+   * normalized using the inverse square root of the maximum link degree of
+   * attached nodes.
+   *
+   * @function
+   * @name pv.Force.spring.prototype.constant
+   * @param {number} x the new spring constant.
+   * @returns {pv.Force.spring} this, or the current spring constant.
+   */
+  force.constant = function(x) {
+    if (arguments.length) {
+      k = Number(x);
+      return force;
+    }
+    return k;
+  };
+
+  /**
+   * The spring damping factor, in the range [0,1]. Damping functions
+   * identically to drag forces, damping spring bounciness by applying a force
+   * in the opposite direction of attached nodes' velocities. The default value
+   * is 0.1. The spring damping is automatically normalized using the inverse
+   * square root of the maximum link degree of attached nodes.
+   *
+   * @function
+   * @name pv.Force.spring.prototype.damping
+   * @param {number} x the new spring damping factor.
+   * @returns {pv.Force.spring} this, or the current spring damping factor.
+   */
+  force.damping = function(x) {
+    if (arguments.length) {
+      d = Number(x);
+      return force;
+    }
+    return d;
+  };
+
+  /**
+   * The spring rest length. The default value is 20 pixels.
+   *
+   * @function
+   * @name pv.Force.spring.prototype.length
+   * @param {number} x the new spring rest length.
+   * @returns {pv.Force.spring} this, or the current spring rest length.
+   */
+  force.length = function(x) {
+    if (arguments.length) {
+      l = Number(x);
+      return force;
+    }
+    return l;
+  };
+
+  /**
+   * Applies this force to the specified particles.
+   *
+   * @function
+   * @name pv.Force.spring.prototype.apply
+   * @param {pv.Particle} particles particles to which to apply this force.
+   */
+  force.apply = function(particles) {
+    for (var i = 0; i < links.length; i++) {
+      var a = links[i].sourceNode,
+          b = links[i].targetNode,
+          dx = a.x - b.x,
+          dy = a.y - b.y,
+          dn = Math.sqrt(dx * dx + dy * dy),
+          dd = dn ? (1 / dn) : 1,
+          ks = k * kl[i], // normalized tension
+          kd = d * kl[i], // normalized damping
+          kk = (ks * (dn - l) + kd * (dx * (a.vx - b.vx) + dy * (a.vy - b.vy)) * dd) * dd,
+          fx = -kk * (dn ? dx : (.01 * (.5 - Math.random()))),
+          fy = -kk * (dn ? dy : (.01 * (.5 - Math.random())));
+      a.fx += fx;
+      a.fy += fy;
+      b.fx -= fx;
+      b.fy -= fy;
+    }
+  };
+
+  return force;
+};

data/vendor/src/pv-internals.js

@@ -0,0 +1,154 @@
+/**
+ * @private Returns a prototype object suitable for extending the given class
+ * <tt>f</tt>. Rather than constructing a new instance of <tt>f</tt> to serve as
+ * the prototype (which unnecessarily runs the constructor on the created
+ * prototype object, potentially polluting it), an anonymous function is
+ * generated internally that shares the same prototype:
+ *
+ * <pre>function g() {}
+ * g.prototype = f.prototype;
+ * return new g();</pre>
+ *
+ * For more details, see Douglas Crockford's essay on prototypal inheritance.
+ *
+ * @param {function} f a constructor.
+ * @returns a suitable prototype object.
+ * @see Douglas Crockford's essay on <a
+ * href="http://javascript.crockford.com/prototypal.html">prototypal
+ * inheritance</a>.
+ */
+pv.extend = function(f) {
+  function g() {}
+  g.prototype = f.prototype || f;
+  return new g();
+};
+
+try {
+  eval("pv.parse = function(x) x;"); // native support
+} catch (e) {
+
+/**
+ * @private Parses a Protovis specification, which may use JavaScript 1.8
+ * function expresses, replacing those function expressions with proper
+ * functions such that the code can be run by a JavaScript 1.6 interpreter. This
+ * hack only supports function expressions (using clumsy regular expressions, no
+ * less), and not other JavaScript 1.8 features such as let expressions.
+ *
+ * @param {string} s a Protovis specification (i.e., a string of JavaScript 1.8
+ * source code).
+ * @returns {string} a conformant JavaScript 1.6 source code.
+ */
+  pv.parse = function(js) { // hacky regex support
+    var re = new RegExp("function\\s*(\\b\\w+)?\\s*\\([^)]*\\)\\s*", "mg"), m, d, i = 0, s = "";
+    while (m = re.exec(js)) {
+      var j = m.index + m[0].length;
+      if (js.charAt(j) != '{') {
+        s += js.substring(i, j) + "{return ";
+        i = j;
+        for (var p = 0; p >= 0 && j < js.length; j++) {
+          var c = js.charAt(j);
+          switch (c) {
+            case '"': case '\'': {
+              while (++j < js.length && (d = js.charAt(j)) != c) {
+                if (d == '\\') j++;
+              }
+              break;
+            }
+            case '[': case '(': p++; break;
+            case ']': case ')': p--; break;
+            case ';':
+            case ',': if (p == 0) p--; break;
+          }
+        }
+        s += pv.parse(js.substring(i, --j)) + ";}";
+        i = j;
+      }
+      re.lastIndex = j;
+    }
+    s += js.substring(i);
+    return s;
+  };
+}
+
+/**
+ * @private Computes the value of the specified CSS property <tt>p</tt> on the
+ * specified element <tt>e</tt>.
+ *
+ * @param {string} p the name of the CSS property.
+ * @param e the element on which to compute the CSS property.
+ */
+pv.css = function(e, p) {
+  return window.getComputedStyle
+      ? window.getComputedStyle(e, null).getPropertyValue(p)
+      : e.currentStyle[p];
+};
+
+/**
+ * @private Reports the specified error to the JavaScript console. Mozilla only
+ * allows logging to the console for privileged code; if the console is
+ * unavailable, the alert dialog box is used instead.
+ *
+ * @param e the exception that triggered the error.
+ */
+pv.error = function(e) {
+  (typeof console == "undefined") ? alert(e) : console.error(e);
+};
+
+/**
+ * @private Registers the specified listener for events of the specified type on
+ * the specified target. For standards-compliant browsers, this method uses
+ * <tt>addEventListener</tt>; for Internet Explorer, <tt>attachEvent</tt>.
+ *
+ * @param target a DOM element.
+ * @param {string} type the type of event, such as "click".
+ * @param {function} the event handler callback.
+ */
+pv.listen = function(target, type, listener) {
+  listener = pv.listener(listener);
+  return target.addEventListener
+      ? target.addEventListener(type, listener, false)
+      : target.attachEvent("on" + type, listener);
+};
+
+/**
+ * @private Returns a wrapper for the specified listener function such that the
+ * {@link pv.event} is set for the duration of the listener's invocation. The
+ * wrapper is cached on the returned function, such that duplicate registrations
+ * of the wrapped event handler are ignored.
+ *
+ * @param {function} f an event handler.
+ * @returns {function} the wrapped event handler.
+ */
+pv.listener = function(f) {
+  return f.$listener || (f.$listener = function(e) {
+      try {
+        pv.event = e;
+        return f.call(this, e);
+      } finally {
+        delete pv.event;
+      }
+    });
+};
+
+/**
+ * @private Returns true iff <i>a</i> is an ancestor of <i>e</i>. This is useful
+ * for ignoring mouseout and mouseover events that are contained within the
+ * target element.
+ */
+pv.ancestor = function(a, e) {
+  while (e) {
+    if (e == a) return true;
+    e = e.parentNode;
+  }
+  return false;
+};
+
+/** @private Returns a locally-unique positive id. */
+pv.id = function() {
+  var id = 1; return function() { return id++; };
+}();
+
+/** @private Returns a function wrapping the specified constant. */
+pv.functor = function(v) {
+  return typeof v == "function" ? v : function() { return v; };
+};