rubyvis 0.1.0 → 0.1.1

data/vendor/src/physics/CollisionConstraint.js

@@ -0,0 +1,113 @@
+/**
+ * Constructs a new collision constraint. The default search radius is 10, and
+ * the default repeat count is 1. A radius function must be specified to compute
+ * the radius of particles.
+ *
+ * @class Constraints circles to avoid overlap. Each particle is treated as a
+ * circle, with the radius of the particle computed using a specified function.
+ * For example, if the particle has an <tt>r</tt> attribute storing the radius,
+ * the radius <tt>function(d) d.r</tt> specifies a collision constraint using
+ * this radius. The radius function is passed each {@link pv.Particle} as the
+ * first argument.
+ *
+ * <p>To accelerate collision detection, this implementation uses a quadtree and
+ * a search radius. The search radius is computed as the maximum radius of all
+ * particles in the simulation.
+ *
+ * @see pv.Constraint
+ * @param {function} radius the radius function.
+ */
+pv.Constraint.collision = function(radius) {
+  var n = 1, // number of times to repeat the constraint
+      r1,
+      px1,
+      py1,
+      px2,
+      py2,
+      constraint = {};
+
+  if (!arguments.length) r1 = 10; // default search radius
+
+  /**
+   * Sets or gets the repeat count. If the repeat count is greater than 1, the
+   * constraint will be applied repeatedly; this is a form of the Gauss-Seidel
+   * method for constraints relaxation. Repeating the collision constraint makes
+   * the constraint have more of an effect when there is a potential for many
+   * co-occurring collisions.
+   *
+   * @function
+   * @name pv.Constraint.collision.prototype.repeat
+   * @param {number} x the number of times to repeat this constraint.
+   * @returns {pv.Constraint.collision} this.
+   */
+  constraint.repeat = function(x) {
+    if (arguments.length) {
+      n = Number(x);
+      return constraint;
+    }
+    return n;
+  };
+
+  /** @private */
+  function constrain(n, p, x1, y1, x2, y2) {
+    if (!n.leaf) {
+      var sx = (x1 + x2) * .5,
+          sy = (y1 + y2) * .5,
+          top = sy > py1,
+          bottom = sy < py2,
+          left = sx > px1,
+          right = sx < px2;
+      if (top) {
+        if (n.c1 && left) constrain(n.c1, p, x1, y1, sx, sy);
+        if (n.c2 && right) constrain(n.c2, p, sx, y1, x2, sy);
+      }
+      if (bottom) {
+        if (n.c3 && left) constrain(n.c3, p, x1, sy, sx, y2);
+        if (n.c4 && right) constrain(n.c4, p, sx, sy, x2, y2);
+      }
+    }
+    if (n.p && (n.p != p)) {
+      var dx = p.x - n.p.x,
+          dy = p.y - n.p.y,
+          l = Math.sqrt(dx * dx + dy * dy),
+          d = r1 + radius(n.p);
+      if (l < d) {
+        var k = (l - d) / l * .5;
+        dx *= k;
+        dy *= k;
+        p.x -= dx;
+        p.y -= dy;
+        n.p.x += dx;
+        n.p.y += dy;
+      }
+    }
+  }
+
+  /**
+   * Applies this constraint to the specified particles.
+   *
+   * @function
+   * @name pv.Constraint.collision.prototype.apply
+   * @param {pv.Particle} particles particles to which to apply this constraint.
+   * @param {pv.Quadtree} q a quadtree for spatial acceleration.
+   */
+  constraint.apply = function(particles, q) {
+    var p, r, max = -Infinity;
+    for (p = particles; p; p = p.next) {
+      r = radius(p);
+      if (r > max) max = r;
+    }
+    for (var i = 0; i < n; i++) {
+      for (p = particles; p; p = p.next) {
+        r = (r1 = radius(p)) + max;
+        px1 = p.x - r;
+        px2 = p.x + r;
+        py1 = p.y - r;
+        py2 = p.y + r;
+        constrain(q.root, p, q.xMin, q.yMin, q.xMax, q.yMax);
+      }
+    }
+  };
+
+  return constraint;
+};

data/vendor/src/physics/Constraint.js

@@ -0,0 +1,26 @@
+/**
+ * Abstract; see an implementing class.
+ *
+ * @class Represents a constraint that acts on particles. Note that this
+ * interface does not specify how to bind a constraint to specific particles; in
+ * general, constraints are applied globally to all particles. However, some
+ * constraints may be applied to specific particles or between particles, such
+ * as position constraints, through additional specialization.
+ *
+ * @see pv.Simulation
+ * @see pv.Particle
+ * @see pv.Constraint.bound
+ * @see pv.Constraint.collision
+ * @see pv.Constraint.position
+ */
+pv.Constraint = {};
+
+/**
+ * Applies this constraint to the specified particles.
+ *
+ * @function
+ * @name pv.Constraint.prototype.apply
+ * @param {pv.Particle} particles particles to which to apply this constraint.
+ * @param {pv.Quadtree} q a quadtree for spatial acceleration.
+ * @returns {pv.Constraint} this.
+ */

data/vendor/src/physics/DragForce.js

@@ -0,0 +1,49 @@
+/**
+ * Constructs a new drag force with the specified constant.
+ *
+ * @class Implements a drag force, simulating friction. The drag force is
+ * applied in the opposite direction of the particle's velocity. Since Position
+ * Verlet integration does not track velocities explicitly, the error term with
+ * this estimate of velocity is fairly high, so the drag force may be
+ * inaccurate.
+ *
+ * @extends pv.Force
+ * @param {number} k the drag constant.
+ * @see #constant
+ */
+pv.Force.drag = function(k) {
+  var force = {};
+
+  if (!arguments.length) k = .1; // default drag constant
+
+  /**
+   * Sets or gets the drag constant, in the range [0,1]. The default drag
+   * constant is 0.1. The drag forces scales linearly with the particle's
+   * velocity based on the given drag constant.
+   *
+   * @function
+   * @name pv.Force.drag.prototype.constant
+   * @param {number} x the new drag constant.
+   * @returns {pv.Force.drag} this, or the current drag constant.
+   */
+  force.constant = function(x) {
+    if (arguments.length) { k = x; return force; }
+    return k;
+  };
+
+  /**
+   * Applies this force to the specified particles.
+   *
+   * @function
+   * @name pv.Force.drag.prototype.apply
+   * @param {pv.Particle} particles particles to which to apply this force.
+   */
+  force.apply = function(particles) {
+    if (k) for (var p = particles; p; p = p.next) {
+      p.fx -= k * p.vx;
+      p.fy -= k * p.vy;
+    }
+  };
+
+  return force;
+};

data/vendor/src/physics/Force.js

@@ -0,0 +1,25 @@
+/**
+ * Abstract; see an implementing class.
+ *
+ * @class Represents a force that acts on particles. Note that this interface
+ * does not specify how to bind a force to specific particles; in general,
+ * forces are applied globally to all particles. However, some forces may be
+ * applied to specific particles or between particles, such as spring forces,
+ * through additional specialization.
+ *
+ * @see pv.Simulation
+ * @see pv.Particle
+ * @see pv.Force.charge
+ * @see pv.Force.drag
+ * @see pv.Force.spring
+ */
+pv.Force = {};
+
+/**
+ * Applies this force to the specified particles.
+ *
+ * @function
+ * @name pv.Force.prototype.apply
+ * @param {pv.Particle} particles particles to which to apply this force.
+ * @param {pv.Quadtree} q a quadtree for spatial acceleration.
+ */

data/vendor/src/physics/Particle.js

@@ -0,0 +1,81 @@
+/**
+ * Abstract; not implemented. There is no explicit constructor; this class
+ * merely serves to document the attributes that are used on particles in
+ * physics simulations.
+ *
+ * @class A weighted particle that can participate in a force simulation.
+ *
+ * @name pv.Particle
+ */
+
+/**
+ * The next particle in the simulation. Particles form a singly-linked list.
+ *
+ * @field
+ * @type pv.Particle
+ * @name pv.Particle.prototype.next
+ */
+
+/**
+ * The <i>x</i>-position of the particle.
+ *
+ * @field
+ * @type number
+ * @name pv.Particle.prototype.x
+ */
+
+/**
+ * The <i>y</i>-position of the particle.
+ *
+ * @field
+ * @type number
+ * @name pv.Particle.prototype.y
+ */
+
+/**
+ * The <i>x</i>-velocity of the particle.
+ *
+ * @field
+ * @type number
+ * @name pv.Particle.prototype.vx
+ */
+
+/**
+ * The <i>y</i>-velocity of the particle.
+ *
+ * @field
+ * @type number
+ * @name pv.Particle.prototype.vy
+ */
+
+/**
+ * The <i>x</i>-position of the particle at -dt.
+ *
+ * @field
+ * @type number
+ * @name pv.Particle.prototype.px
+ */
+
+/**
+ * The <i>y</i>-position of the particle at -dt.
+ *
+ * @field
+ * @type number
+ * @name pv.Particle.prototype.py
+ */
+
+/**
+ * The <i>x</i>-force on the particle.
+ *
+ * @field
+ * @type number
+ * @name pv.Particle.prototype.fx
+ */
+
+/**
+ * The <i>y</i>-force on the particle.
+ *
+ * @field
+ * @type number
+ * @name pv.Particle.prototype.fy
+ */

data/vendor/src/physics/PositionConstraint.js

@@ -0,0 +1,72 @@
+/**
+ * Constructs a default position constraint using the <tt>fix</tt> attribute.
+ * An optional position function can be specified to determine how the fixed
+ * position per-particle is determined.
+ *
+ * @class Constraints particles to a fixed position. The fixed position per
+ * particle is determined using a given position function, which defaults to
+ * <tt>function(d) d.fix</tt>.
+ *
+ * <p>If the position function returns null, then no position constraint is
+ * applied to the given particle. Otherwise, the particle's position is set to
+ * the returned position, as expressed by a {@link pv.Vector}. (Note: the
+ * position does not need to be an instance of <tt>pv.Vector</tt>, but simply an
+ * object with <tt>x</tt> and <tt>y</tt> attributes.)
+ *
+ * <p>This constraint also supports a configurable alpha parameter, which
+ * defaults to 1. If the alpha parameter is in the range [0,1], then rather than
+ * setting the particle's new position directly to the position returned by the
+ * supplied position function, the particle's position is interpolated towards
+ * the fixed position. This results is a smooth (exponential) drift towards the
+ * fixed position, which can increase the stability of the physics simulation.
+ * In addition, the alpha parameter can be decayed over time, relaxing the
+ * position constraint, which helps to stabilize on an optimal solution.
+ *
+ * @param {function} [f] the position function.
+ */
+pv.Constraint.position = function(f) {
+  var a = 1, // default alpha
+      constraint = {};
+
+  if (!arguments.length) /** @ignore */ f = function(p) { return p.fix; };
+
+  /**
+   * Sets or gets the alpha parameter for position interpolation. If the alpha
+   * parameter is in the range [0,1], then rather than setting the particle's
+   * new position directly to the position returned by the supplied position
+   * function, the particle's position is interpolated towards the fixed
+   * position.
+   *
+   * @function
+   * @name pv.Constraint.position.prototype.alpha
+   * @param {number} x the new alpha parameter, in the range [0,1].
+   * @returns {pv.Constraint.position} this.
+   */
+  constraint.alpha = function(x) {
+    if (arguments.length) {
+      a = Number(x);
+      return constraint;
+    }
+    return a;
+  };
+
+  /**
+   * Applies this constraint to the specified particles.
+   *
+   * @function
+   * @name pv.Constraint.position.prototype.apply
+   * @param {pv.Particle} particles particles to which to apply this constraint.
+   */
+  constraint.apply = function(particles) {
+    for (var p = particles; p; p = p.next) {
+      var v = f(p);
+      if (v) {
+        p.x += (v.x - p.x) * a;
+        p.y += (v.y - p.y) * a;
+        p.fx = p.fy = p.vx = p.vy = 0;
+      }
+    }
+  };
+
+  return constraint;
+};

data/vendor/src/physics/Quadtree.js

@@ -0,0 +1,195 @@
+/**
+ * Constructs a new quadtree for the specified array of particles.
+ *
+ * @class Represents a quadtree: a two-dimensional recursive spatial
+ * subdivision. This particular implementation uses square partitions, dividing
+ * each square into four equally-sized squares. Each particle exists in a unique
+ * node; if multiple particles are in the same position, some particles may be
+ * stored on internal nodes rather than leaf nodes.
+ *
+ * <p>This quadtree can be used to accelerate various spatial operations, such
+ * as the Barnes-Hut approximation for computing n-body forces, or collision
+ * detection.
+ *
+ * @see pv.Force.charge
+ * @see pv.Constraint.collision
+ * @param {pv.Particle} particles the linked list of particles.
+ */
+pv.Quadtree = function(particles) {
+  var p;
+
+  /* Compute bounds. */
+  var x1 = Number.POSITIVE_INFINITY, y1 = x1,
+      x2 = Number.NEGATIVE_INFINITY, y2 = x2;
+  for (p = particles; p; p = p.next) {
+    if (p.x < x1) x1 = p.x;
+    if (p.y < y1) y1 = p.y;
+    if (p.x > x2) x2 = p.x;
+    if (p.y > y2) y2 = p.y;
+  }
+
+  /* Squarify the bounds. */
+  var dx = x2 - x1, dy = y2 - y1;
+  if (dx > dy) y2 = y1 + dx;
+  else x2 = x1 + dy;
+  this.xMin = x1;
+  this.yMin = y1;
+  this.xMax = x2;
+  this.yMax = y2;
+
+  /**
+   * @ignore Recursively inserts the specified particle <i>p</i> at the node
+   * <i>n</i> or one of its descendants. The bounds are defined by [<i>x1</i>,
+   * <i>x2</i>] and [<i>y1</i>, <i>y2</i>].
+   */
+  function insert(n, p, x1, y1, x2, y2) {
+    if (isNaN(p.x) || isNaN(p.y)) return; // ignore invalid particles
+    if (n.leaf) {
+      if (n.p) {
+        /*
+         * If the particle at this leaf node is at the same position as the new
+         * particle we are adding, we leave the particle associated with the
+         * internal node while adding the new particle to a child node. This
+         * avoids infinite recursion.
+         */
+        if ((Math.abs(n.p.x - p.x) + Math.abs(n.p.y - p.y)) < .01) {
+          insertChild(n, p, x1, y1, x2, y2);
+        } else {
+          var v = n.p;
+          n.p = null;
+          insertChild(n, v, x1, y1, x2, y2);
+          insertChild(n, p, x1, y1, x2, y2);
+        }
+      } else {
+        n.p = p;
+      }
+    } else {
+      insertChild(n, p, x1, y1, x2, y2);
+    }
+  }
+
+  /**
+   * @ignore Recursively inserts the specified particle <i>p</i> into a
+   * descendant of node <i>n</i>. The bounds are defined by [<i>x1</i>,
+   * <i>x2</i>] and [<i>y1</i>, <i>y2</i>].
+   */
+  function insertChild(n, p, x1, y1, x2, y2) {
+    /* Compute the split point, and the quadrant in which to insert p. */
+    var sx = (x1 + x2) * .5,
+        sy = (y1 + y2) * .5,
+        right = p.x >= sx,
+        bottom = p.y >= sy;
+
+    /* Recursively insert into the child node. */
+    n.leaf = false;
+    switch ((bottom << 1) + right) {
+      case 0: n = n.c1 || (n.c1 = new pv.Quadtree.Node()); break;
+      case 1: n = n.c2 || (n.c2 = new pv.Quadtree.Node()); break;
+      case 2: n = n.c3 || (n.c3 = new pv.Quadtree.Node()); break;
+      case 3: n = n.c4 || (n.c4 = new pv.Quadtree.Node()); break;
+    }
+
+    /* Update the bounds as we recurse. */
+    if (right) x1 = sx; else x2 = sx;
+    if (bottom) y1 = sy; else y2 = sy;
+    insert(n, p, x1, y1, x2, y2);
+  }
+
+  /* Insert all particles. */
+  this.root = new pv.Quadtree.Node();
+  for (p = particles; p; p = p.next) insert(this.root, p, x1, y1, x2, y2);
+};
+
+/**
+ * The root node of the quadtree.
+ *
+ * @type pv.Quadtree.Node
+ * @name pv.Quadtree.prototype.root
+ */
+
+/**
+ * The minimum x-coordinate value of all contained particles.
+ *
+ * @type number
+ * @name pv.Quadtree.prototype.xMin
+ */
+
+/**
+ * The maximum x-coordinate value of all contained particles.
+ *
+ * @type number
+ * @name pv.Quadtree.prototype.xMax
+ */
+
+/**
+ * The minimum y-coordinate value of all contained particles.
+ *
+ * @type number
+ * @name pv.Quadtree.prototype.yMin
+ */
+
+/**
+ * The maximum y-coordinate value of all contained particles.
+ *
+ * @type number
+ * @name pv.Quadtree.prototype.yMax
+ */
+
+/**
+ * Constructs a new node.
+ *
+ * @class A node in a quadtree.
+ *
+ * @see pv.Quadtree
+ */
+pv.Quadtree.Node = function() {
+  /*
+   * Prepopulating all attributes significantly increases performance! Also,
+   * letting the language interpreter manage garbage collection was moderately
+   * faster than creating a cache pool.
+   */
+  this.leaf = true;
+  this.c1 = null;
+  this.c2 = null;
+  this.c3 = null;
+  this.c4 = null;
+  this.p = null;
+};
+
+/**
+ * True if this node is a leaf node; i.e., it has no children. Note that both
+ * leaf nodes and non-leaf (internal) nodes may have associated particles. If
+ * this is a non-leaf node, then at least one of {@link #c1}, {@link #c2},
+ * {@link #c3} or {@link #c4} is guaranteed to be non-null.
+ *
+ * @type boolean
+ * @name pv.Quadtree.Node.prototype.leaf
+ */
+
+/**
+ * The particle associated with this node, if any.
+ *
+ * @type pv.Particle
+ * @name pv.Quadtree.Node.prototype.p
+ */
+
+/**
+ * The child node for the second quadrant, if any.
+ *
+ * @type pv.Quadtree.Node
+ * @name pv.Quadtree.Node.prototype.c2
+ */
+
+/**
+ * The child node for the third quadrant, if any.
+ *
+ * @type pv.Quadtree.Node
+ * @name pv.Quadtree.Node.prototype.c3
+ */
+
+/**
+ * The child node for the fourth quadrant, if any.
+ *
+ * @type pv.Quadtree.Node
+ * @name pv.Quadtree.Node.prototype.c4
+ */