rubyvis 0.1.0 → 0.1.1

data/vendor/src/mark/Wedge.js

@@ -0,0 +1,244 @@
+/**
+ * Constructs a new wedge with default properties. Wedges are not typically
+ * constructed directly, but by adding to a panel or an existing mark via
+ * {@link pv.Mark#add}.
+ *
+ * @class Represents a wedge, or pie slice. Specified in terms of start and end
+ * angle, inner and outer radius, wedges can be used to construct donut charts
+ * and polar bar charts as well. If the {@link #angle} property is used, the end
+ * angle is implied by adding this value to start angle. By default, the start
+ * angle is the previously-generated wedge's end angle. This design allows
+ * explicit control over the wedge placement if desired, while offering
+ * convenient defaults for the construction of radial graphs.
+ *
+ * <p>The center point of the circle is positioned using the standard box model.
+ * The wedge can be stroked and filled, similar to {@link pv.Bar}.
+ *
+ * <p>See also the <a href="../../api/Wedge.html">Wedge guide</a>.
+ *
+ * @extends pv.Mark
+ */
+pv.Wedge = function() {
+  pv.Mark.call(this);
+};
+
+pv.Wedge.prototype = pv.extend(pv.Mark)
+    .property("startAngle", Number)
+    .property("endAngle", Number)
+    .property("angle", Number)
+    .property("innerRadius", Number)
+    .property("outerRadius", Number)
+    .property("lineWidth", Number)
+    .property("strokeStyle", pv.color)
+    .property("fillStyle", pv.color);
+
+pv.Wedge.prototype.type = "wedge";
+
+/**
+ * The start angle of the wedge, in radians. The start angle is measured
+ * clockwise from the 3 o'clock position. The default value of this property is
+ * the end angle of the previous instance (the {@link Mark#sibling}), or -PI / 2
+ * for the first wedge; for pie and donut charts, typically only the
+ * {@link #angle} property needs to be specified.
+ *
+ * @type number
+ * @name pv.Wedge.prototype.startAngle
+ */
+
+/**
+ * The end angle of the wedge, in radians. If not specified, the end angle is
+ * implied as the start angle plus the {@link #angle}.
+ *
+ * @type number
+ * @name pv.Wedge.prototype.endAngle
+ */
+
+/**
+ * The angular span of the wedge, in radians. This property is used if end angle
+ * is not specified.
+ *
+ * @type number
+ * @name pv.Wedge.prototype.angle
+ */
+
+/**
+ * The inner radius of the wedge, in pixels. The default value of this property
+ * is zero; a positive value will produce a donut slice rather than a pie slice.
+ * The inner radius can vary per-wedge.
+ *
+ * @type number
+ * @name pv.Wedge.prototype.innerRadius
+ */
+
+/**
+ * The outer radius of the wedge, in pixels. This property is required. For
+ * pies, only this radius is required; for donuts, the inner radius must be
+ * specified as well. The outer radius can vary per-wedge.
+ *
+ * @type number
+ * @name pv.Wedge.prototype.outerRadius
+ */
+
+/**
+ * The width of stroked lines, in pixels; used in conjunction with
+ * <tt>strokeStyle</tt> to stroke the wedge's border.
+ *
+ * @type number
+ * @name pv.Wedge.prototype.lineWidth
+ */
+
+/**
+ * The style of stroked lines; used in conjunction with <tt>lineWidth</tt> to
+ * stroke the wedge's border. The default value of this property is null,
+ * meaning wedges are not stroked by default.
+ *
+ * @type string
+ * @name pv.Wedge.prototype.strokeStyle
+ * @see pv.color
+ */
+
+/**
+ * The wedge fill style; if non-null, the interior of the wedge is filled with
+ * the specified color. The default value of this property is a categorical
+ * color.
+ *
+ * @type string
+ * @name pv.Wedge.prototype.fillStyle
+ * @see pv.color
+ */
+
+/**
+ * Default properties for wedges. By default, there is no stroke and the fill
+ * style is a categorical color.
+ *
+ * @type pv.Wedge
+ */
+pv.Wedge.prototype.defaults = new pv.Wedge()
+    .extend(pv.Mark.prototype.defaults)
+    .startAngle(function() {
+        var s = this.sibling();
+        return s ? s.endAngle : -Math.PI / 2;
+      })
+    .innerRadius(0)
+    .lineWidth(1.5)
+    .strokeStyle(null)
+    .fillStyle(pv.Colors.category20().by(pv.index));
+
+/**
+ * Returns the mid-radius of the wedge, which is defined as half-way between the
+ * inner and outer radii.
+ *
+ * @see #innerRadius
+ * @see #outerRadius
+ * @returns {number} the mid-radius, in pixels.
+ */
+pv.Wedge.prototype.midRadius = function() {
+  return (this.innerRadius() + this.outerRadius()) / 2;
+};
+
+/**
+ * Returns the mid-angle of the wedge, which is defined as half-way between the
+ * start and end angles.
+ *
+ * @see #startAngle
+ * @see #endAngle
+ * @returns {number} the mid-angle, in radians.
+ */
+pv.Wedge.prototype.midAngle = function() {
+  return (this.startAngle() + this.endAngle()) / 2;
+};
+
+/**
+ * Constructs a new wedge anchor with default properties. Wedges support five
+ * different anchors:<ul>
+ *
+ * <li>outer
+ * <li>inner
+ * <li>center
+ * <li>start
+ * <li>end
+ *
+ * </ul>In addition to positioning properties (left, right, top bottom), the
+ * anchors support text rendering properties (text-align, text-baseline,
+ * textAngle). Text is rendered to appear inside the wedge.
+ *
+ * @param {string} name the anchor name; either a string or a property function.
+ * @returns {pv.Anchor}
+ */
+pv.Wedge.prototype.anchor = function(name) {
+  function partial(s) { return s.innerRadius || s.angle < 2 * Math.PI; }
+  function midRadius(s) { return (s.innerRadius + s.outerRadius) / 2; }
+  function midAngle(s) { return (s.startAngle + s.endAngle) / 2; }
+  return pv.Mark.prototype.anchor.call(this, name)
+    .left(function() {
+        var s = this.scene.target[this.index];
+        if (partial(s)) switch (this.name()) {
+          case "outer": return s.left + s.outerRadius * Math.cos(midAngle(s));
+          case "inner": return s.left + s.innerRadius * Math.cos(midAngle(s));
+          case "start": return s.left + midRadius(s) * Math.cos(s.startAngle);
+          case "center": return s.left + midRadius(s) * Math.cos(midAngle(s));
+          case "end": return s.left + midRadius(s) * Math.cos(s.endAngle);
+        }
+        return s.left;
+      })
+    .top(function() {
+        var s = this.scene.target[this.index];
+        if (partial(s)) switch (this.name()) {
+          case "outer": return s.top + s.outerRadius * Math.sin(midAngle(s));
+          case "inner": return s.top + s.innerRadius * Math.sin(midAngle(s));
+          case "start": return s.top + midRadius(s) * Math.sin(s.startAngle);
+          case "center": return s.top + midRadius(s) * Math.sin(midAngle(s));
+          case "end": return s.top + midRadius(s) * Math.sin(s.endAngle);
+        }
+        return s.top;
+      })
+    .textAlign(function() {
+        var s = this.scene.target[this.index];
+        if (partial(s)) switch (this.name()) {
+          case "outer": return pv.Wedge.upright(midAngle(s)) ? "right" : "left";
+          case "inner": return pv.Wedge.upright(midAngle(s)) ? "left" : "right";
+        }
+        return "center";
+      })
+    .textBaseline(function() {
+        var s = this.scene.target[this.index];
+        if (partial(s)) switch (this.name()) {
+          case "start": return pv.Wedge.upright(s.startAngle) ? "top" : "bottom";
+          case "end": return pv.Wedge.upright(s.endAngle) ? "bottom" : "top";
+        }
+        return "middle";
+      })
+    .textAngle(function() {
+        var s = this.scene.target[this.index], a = 0;
+        if (partial(s)) switch (this.name()) {
+          case "center":
+          case "inner":
+          case "outer": a = midAngle(s); break;
+          case "start": a = s.startAngle; break;
+          case "end": a = s.endAngle; break;
+        }
+        return pv.Wedge.upright(a) ? a : (a + Math.PI);
+      });
+};
+
+/**
+ * Returns true if the specified angle is considered "upright", as in, text
+ * rendered at that angle would appear upright. If the angle is not upright,
+ * text is rotated 180 degrees to be upright, and the text alignment properties
+ * are correspondingly changed.
+ *
+ * @param {number} angle an angle, in radius.
+ * @returns {boolean} true if the specified angle is upright.
+ */
+pv.Wedge.upright = function(angle) {
+  angle = angle % (2 * Math.PI);
+  angle = (angle < 0) ? (2 * Math.PI + angle) : angle;
+  return (angle < Math.PI / 2) || (angle >= 3 * Math.PI / 2);
+};
+
+/** @private Sets angle based on endAngle or vice versa. */
+pv.Wedge.prototype.buildImplied = function(s) {
+  if (s.angle == null) s.angle = s.endAngle - s.startAngle;
+  else if (s.endAngle == null) s.endAngle = s.startAngle + s.angle;
+  pv.Mark.prototype.buildImplied.call(this, s);
+};

data/vendor/src/physics/BoundConstraint.js

@@ -0,0 +1,75 @@
+/**
+ * Constructs a new bound constraint. Before the constraint can be used, the
+ * {@link #x} and {@link #y} methods must be call to specify the bounds.
+ *
+ * @class Constrains particles to within fixed rectangular bounds. For example,
+ * this constraint can be used to constrain particles in a physics simulation
+ * within the bounds of an enclosing panel.
+ *
+ * <p>Note that the current implementation treats particles as points, with no
+ * area. If the particles are rendered as dots, be sure to include some
+ * additional padding to inset the bounds such that the edges of the dots do not
+ * get clipped by the panel bounds. If the particles have different radii, this
+ * constraint would need to be extended using a radius function, similar to
+ * {@link pv.Constraint.collision}.
+ *
+ * @see pv.Layout.Force
+ * @extends pv.Constraint
+ */
+pv.Constraint.bound = function() {
+  var constraint = {},
+      x,
+      y;
+
+  /**
+   * Sets or gets the bounds on the x-coordinate.
+   *
+   * @function
+   * @name pv.Constraint.bound.prototype.x
+   * @param {number} min the minimum allowed x-coordinate.
+   * @param {number} max the maximum allowed x-coordinate.
+   * @returns {pv.Constraint.bound} this.
+   */
+  constraint.x = function(min, max) {
+    if (arguments.length) {
+      x = {min: Math.min(min, max), max: Math.max(min, max)};
+      return this;
+    }
+    return x;
+  };
+
+  /**
+   * Sets or gets the bounds on the y-coordinate.
+   *
+   * @function
+   * @name pv.Constraint.bound.prototype.y
+   * @param {number} min the minimum allowed y-coordinate.
+   * @param {number} max the maximum allowed y-coordinate.
+   * @returns {pv.Constraint.bound} this.
+   */
+  constraint.y = function(min, max) {
+    if (arguments.length) {
+      y = {min: Math.min(min, max), max: Math.max(min, max)};
+      return this;
+    }
+    return y;
+  };
+
+  /**
+   * Applies this constraint to the specified particles.
+   *
+   * @function
+   * @name pv.Constraint.bound.prototype.apply
+   * @param {pv.Particle} particles particles to which to apply this constraint.
+   */
+  constraint.apply = function(particles) {
+    if (x) for (var p = particles; p; p = p.next) {
+      p.x = p.x < x.min ? x.min : (p.x > x.max ? x.max : p.x);
+    }
+    if (y) for (var p = particles; p; p = p.next) {
+      p.y = p.y < y.min ? y.min : (p.y > y.max ? y.max : p.y);
+    }
+  };
+
+  return constraint;
+};

data/vendor/src/physics/ChargeForce.js

@@ -0,0 +1,184 @@
+/**
+ * Constructs a new charge force, with an optional charge constant. The charge
+ * constant can be negative for repulsion (e.g., particles with electrical
+ * charge of equal sign), or positive for attraction (e.g., massive particles
+ * with mutual gravity). The default charge constant is -40.
+ *
+ * @class An n-body force, as defined by Coulomb's law or Newton's law of
+ * gravitation, inversely proportional to the square of the distance between
+ * particles. Note that the force is independent of the <i>mass</i> of the
+ * associated particles, and that the particles do not have charges of varying
+ * magnitude; instead, the attraction or repulsion of all particles is globally
+ * specified as the charge {@link #constant}.
+ *
+ * <p>This particular implementation uses the Barnes-Hut algorithm. For details,
+ * see <a
+ * href="http://www.nature.com/nature/journal/v324/n6096/abs/324446a0.html">"A
+ * hierarchical O(N log N) force-calculation algorithm"</a>, J. Barnes &amp;
+ * P. Hut, <i>Nature</i> 1986.
+ *
+ * @name pv.Force.charge
+ * @param {number} [k] the charge constant.
+ */
+pv.Force.charge = function(k) {
+  var min = 2, // minimum distance at which to observe forces
+      min1 = 1 / min,
+      max = 500, // maximum distance at which to observe forces
+      max1 = 1 / max,
+      theta = .9, // Barnes-Hut theta approximation constant
+      force = {};
+
+  if (!arguments.length) k = -40; // default charge constant (repulsion)
+
+  /**
+   * Sets or gets the charge constant. If an argument is specified, it is the
+   * new charge constant. The charge constant can be negative for repulsion
+   * (e.g., particles with electrical charge of equal sign), or positive for
+   * attraction (e.g., massive particles with mutual gravity). The default
+   * charge constant is -40.
+   *
+   * @function
+   * @name pv.Force.charge.prototype.constant
+   * @param {number} x the charge constant.
+   * @returns {pv.Force.charge} this.
+   */
+  force.constant = function(x) {
+    if (arguments.length) {
+      k = Number(x);
+      return force;
+    }
+    return k;
+  };
+
+  /**
+   * Sets or gets the domain; specifies the minimum and maximum domain within
+   * which charge forces are applied. A minimum distance threshold avoids
+   * applying forces that are two strong (due to granularity of the simulation's
+   * numeric integration). A maximum distance threshold improves performance by
+   * skipping force calculations for particles that are far apart.
+   *
+   * <p>The default domain is [2, 500].
+   *
+   * @function
+   * @name pv.Force.charge.prototype.domain
+   * @param {number} a
+   * @param {number} b
+   * @returns {pv.Force.charge} this.
+   */
+  force.domain = function(a, b) {
+    if (arguments.length) {
+      min = Number(a);
+      min1 = 1 / min;
+      max = Number(b);
+      max1 = 1 / max;
+      return force;
+    }
+    return [min, max];
+  };
+
+  /**
+   * Sets or gets the Barnes-Hut approximation factor. The Barnes-Hut
+   * approximation criterion is the ratio of the size of the quadtree node to
+   * the distance from the point to the node's center of mass is beneath some
+   * threshold.
+   *
+   * @function
+   * @name pv.Force.charge.prototype.theta
+   * @param {number} x the new Barnes-Hut approximation factor.
+   * @returns {pv.Force.charge} this.
+   */
+  force.theta = function(x) {
+    if (arguments.length) {
+      theta = Number(x);
+      return force;
+    }
+    return theta;
+  };
+
+  /**
+   * @ignore Recursively computes the center of charge for each node in the
+   * quadtree. This is equivalent to the center of mass, assuming that all
+   * particles have unit weight.
+   */
+  function accumulate(n) {
+    var cx = 0, cy = 0;
+    n.cn = 0;
+    function accumulateChild(c) {
+      accumulate(c);
+      n.cn += c.cn;
+      cx += c.cn * c.cx;
+      cy += c.cn * c.cy;
+    }
+    if (!n.leaf) {
+      if (n.c1) accumulateChild(n.c1);
+      if (n.c2) accumulateChild(n.c2);
+      if (n.c3) accumulateChild(n.c3);
+      if (n.c4) accumulateChild(n.c4);
+    }
+    if (n.p) {
+      n.cn += k;
+      cx += k * n.p.x;
+      cy += k * n.p.y;
+    }
+    n.cx = cx / n.cn;
+    n.cy = cy / n.cn;
+  }
+
+  /**
+   * @ignore Recursively computes forces on the given particle using the given
+   * quadtree node. The Barnes-Hut approximation criterion is the ratio of the
+   * size of the quadtree node to the distance from the point to the node's
+   * center of mass is beneath some threshold.
+   */
+  function forces(n, p, x1, y1, x2, y2) {
+    var dx = n.cx - p.x,
+        dy = n.cy - p.y,
+        dn = 1 / Math.sqrt(dx * dx + dy * dy);
+
+    /* Barnes-Hut criterion. */
+    if ((n.leaf && (n.p != p)) || ((x2 - x1) * dn < theta)) {
+      if (dn < max1) return;
+      if (dn > min1) dn = min1;
+      var kc = n.cn * dn * dn * dn,
+          fx = dx * kc,
+          fy = dy * kc;
+      p.fx += fx;
+      p.fy += fy;
+    } else if (!n.leaf) {
+      var sx = (x1 + x2) * .5, sy = (y1 + y2) * .5;
+      if (n.c1) forces(n.c1, p, x1, y1, sx, sy);
+      if (n.c2) forces(n.c2, p, sx, y1, x2, sy);
+      if (n.c3) forces(n.c3, p, x1, sy, sx, y2);
+      if (n.c4) forces(n.c4, p, sx, sy, x2, y2);
+      if (dn < max1) return;
+      if (dn > min1) dn = min1;
+      if (n.p && (n.p != p)) {
+        var kc = k * dn * dn * dn,
+            fx = dx * kc,
+            fy = dy * kc;
+        p.fx += fx;
+        p.fy += fy;
+      }
+    }
+  }
+
+  /**
+   * Applies this force to the specified particles. The force is applied between
+   * all pairs of particles within the domain, using the specified quadtree to
+   * accelerate n-body force calculation using the Barnes-Hut approximation
+   * criterion.
+   *
+   * @function
+   * @name pv.Force.charge.prototype.apply
+   * @param {pv.Particle} particles particles to which to apply this force.
+   * @param {pv.Quadtree} q a quadtree for spatial acceleration.
+   */
+  force.apply = function(particles, q) {
+    accumulate(q.root);
+    for (var p = particles; p; p = p.next) {
+      forces(q.root, p, q.xMin, q.yMin, q.xMax, q.yMax);
+    }
+  };
+
+  return force;
+};