rubyvis 0.1.0 → 0.1.1

data/vendor/src/data/Scale.js

@@ -0,0 +1,86 @@
+/**
+ * Abstract; see the various scale implementations.
+ *
+ * @class Represents a scale; a function that performs a transformation from
+ * data domain to visual range. For quantitative and quantile scales, the domain
+ * is expressed as numbers; for ordinal scales, the domain is expressed as
+ * strings (or equivalently objects with unique string representations). The
+ * "visual range" may correspond to pixel space, colors, font sizes, and the
+ * like.
+ *
+ * <p>Note that scales are functions, and thus can be used as properties
+ * directly, assuming that the data associated with a mark is a number. While
+ * this is convenient for single-use scales, frequently it is desirable to
+ * define scales globally:
+ *
+ * <pre>var y = pv.Scale.linear(0, 100).range(0, 640);</pre>
+ *
+ * The <tt>y</tt> scale can now be equivalently referenced within a property:
+ *
+ * <pre>    .height(function(d) y(d))</pre>
+ *
+ * Alternatively, if the data are not simple numbers, the appropriate value can
+ * be passed to the <tt>y</tt> scale (e.g., <tt>d.foo</tt>). The {@link #by}
+ * method similarly allows the data to be mapped to a numeric value before
+ * performing the linear transformation.
+ *
+ * @see pv.Scale.quantitative
+ * @see pv.Scale.quantile
+ * @see pv.Scale.ordinal
+ * @extends function
+ */
+pv.Scale = function() {};
+
+/**
+ * @private Returns a function that interpolators from the start value to the
+ * end value, given a parameter <i>t</i> in [0, 1].
+ *
+ * @param start the start value.
+ * @param end the end value.
+ */
+pv.Scale.interpolator = function(start, end) {
+  if (typeof start == "number") {
+    return function(t) {
+      return t * (end - start) + start;
+    };
+  }
+
+  /* For now, assume color. */
+  start = pv.color(start).rgb();
+  end = pv.color(end).rgb();
+  return function(t) {
+    var a = start.a * (1 - t) + end.a * t;
+    if (a < 1e-5) a = 0; // avoid scientific notation
+    return (start.a == 0) ? pv.rgb(end.r, end.g, end.b, a)
+        : ((end.a == 0) ? pv.rgb(start.r, start.g, start.b, a)
+        : pv.rgb(
+            Math.round(start.r * (1 - t) + end.r * t),
+            Math.round(start.g * (1 - t) + end.g * t),
+            Math.round(start.b * (1 - t) + end.b * t), a));
+  };
+};
+
+/**
+ * Returns a view of this scale by the specified accessor function <tt>f</tt>.
+ * Given a scale <tt>y</tt>, <tt>y.by(function(d) d.foo)</tt> is equivalent to
+ * <tt>function(d) y(d.foo)</tt>.
+ *
+ * <p>This method is provided for convenience, such that scales can be
+ * succinctly defined inline. For example, given an array of data elements that
+ * have a <tt>score</tt> attribute with the domain [0, 1], the height property
+ * could be specified as:
+ *
+ * <pre>    .height(pv.Scale.linear().range(0, 480).by(function(d) d.score))</pre>
+ *
+ * This is equivalent to:
+ *
+ * <pre>    .height(function(d) d.score * 480)</pre>
+ *
+ * This method should be used judiciously; it is typically more clear to invoke
+ * the scale directly, passing in the value to be scaled.
+ *
+ * @function
+ * @name pv.Scale.prototype.by
+ * @param {function} f an accessor function.
+ * @returns {pv.Scale} a view of this scale by the specified accessor function.
+ */

data/vendor/src/data/Transform.js

@@ -0,0 +1,109 @@
+/**
+ * Returns a new identity transform.
+ *
+ * @class Represents a transformation matrix. The transformation matrix is
+ * limited to expressing translate and uniform scale transforms only; shearing,
+ * rotation, general affine, and other transforms are not supported.
+ *
+ * <p>The methods on this class treat the transform as immutable, returning a
+ * copy of the transformation matrix with the specified transform applied. Note,
+ * alternatively, that the matrix fields can be get and set directly.
+ */
+pv.Transform = function() {};
+pv.Transform.prototype = {k: 1, x: 0, y: 0};
+
+/**
+ * The scale magnitude; defaults to 1.
+ *
+ * @type number
+ * @name pv.Transform.prototype.k
+ */
+
+/**
+ * The x-offset; defaults to 0.
+ *
+ * @type number
+ * @name pv.Transform.prototype.x
+ */
+
+/**
+ * The y-offset; defaults to 0.
+ *
+ * @type number
+ * @name pv.Transform.prototype.y
+ */
+
+/**
+ * @private The identity transform.
+ *
+ * @type pv.Transform
+ */
+pv.Transform.identity = new pv.Transform();
+
+// k 0 x   1 0 a   k 0 ka+x
+// 0 k y * 0 1 b = 0 k kb+y
+// 0 0 1   0 0 1   0 0 1
+
+/**
+ * Returns a translated copy of this transformation matrix.
+ *
+ * @param {number} x the x-offset.
+ * @param {number} y the y-offset.
+ * @returns {pv.Transform} the translated transformation matrix.
+ */
+pv.Transform.prototype.translate = function(x, y) {
+  var v = new pv.Transform();
+  v.k = this.k;
+  v.x = this.k * x + this.x;
+  v.y = this.k * y + this.y;
+  return v;
+};
+
+// k 0 x   d 0 0   kd  0 x
+// 0 k y * 0 d 0 =  0 kd y
+// 0 0 1   0 0 1    0  0 1
+
+/**
+ * Returns a scaled copy of this transformation matrix.
+ *
+ * @param {number} k
+ * @returns {pv.Transform} the scaled transformation matrix.
+ */
+pv.Transform.prototype.scale = function(k) {
+  var v = new pv.Transform();
+  v.k = this.k * k;
+  v.x = this.x;
+  v.y = this.y;
+  return v;
+};
+
+/**
+ * Returns the inverse of this transformation matrix.
+ *
+ * @returns {pv.Transform} the inverted transformation matrix.
+ */
+pv.Transform.prototype.invert = function() {
+  var v = new pv.Transform(), k = 1 / this.k;
+  v.k = k;
+  v.x = -this.x * k;
+  v.y = -this.y * k;
+  return v;
+};
+
+// k 0 x   d 0 a   kd  0 ka+x
+// 0 k y * 0 d b =  0 kd kb+y
+// 0 0 1   0 0 1    0  0    1
+
+/**
+ * Returns this matrix post-multiplied by the specified matrix <i>m</i>.
+ *
+ * @param {pv.Transform} m
+ * @returns {pv.Transform} the post-multiplied transformation matrix.
+ */
+pv.Transform.prototype.times = function(m) {
+  var v = new pv.Transform();
+  v.k = this.k * m.k;
+  v.x = this.k * m.x + this.x;
+  v.y = this.k * m.y + this.y;
+  return v;
+};

data/vendor/src/data/Tree.js

@@ -0,0 +1,124 @@
+/**
+ * Returns a {@link pv.Tree} operator for the specified array. This is a
+ * convenience factory method, equivalent to <tt>new pv.Tree(array)</tt>.
+ *
+ * @see pv.Tree
+ * @param {array} array an array from which to construct a tree.
+ * @returns {pv.Tree} a tree operator for the specified array.
+ */
+pv.tree = function(array) {
+  return new pv.Tree(array);
+};
+
+/**
+ * Constructs a tree operator for the specified array. This constructor should
+ * not be invoked directly; use {@link pv.tree} instead.
+ *
+ * @class Represents a tree operator for the specified array. The tree operator
+ * allows a hierarchical map to be constructed from an array; it is similar to
+ * the {@link pv.Nest} operator, except the hierarchy is derived dynamically
+ * from the array elements.
+ *
+ * <p>For example, given an array of size information for ActionScript classes:
+ *
+ * <pre>{ name: "flare.flex.FlareVis", size: 4116 },
+ * { name: "flare.physics.DragForce", size: 1082 },
+ * { name: "flare.physics.GravityForce", size: 1336 }, ...</pre>
+ *
+ * To facilitate visualization, it may be useful to nest the elements by their
+ * package hierarchy:
+ *
+ * <pre>var tree = pv.tree(classes)
+ *     .keys(function(d) d.name.split("."))
+ *     .map();</pre>
+ *
+ * The resulting tree is:
+ *
+ * <pre>{ flare: {
+ *     flex: {
+ *       FlareVis: {
+ *         name: "flare.flex.FlareVis",
+ *         size: 4116 } },
+ *     physics: {
+ *       DragForce: {
+ *         name: "flare.physics.DragForce",
+ *         size: 1082 },
+ *       GravityForce: {
+ *         name: "flare.physics.GravityForce",
+ *         size: 1336 } },
+ *     ... } }</pre>
+ *
+ * By specifying a value function,
+ *
+ * <pre>var tree = pv.tree(classes)
+ *     .keys(function(d) d.name.split("."))
+ *     .value(function(d) d.size)
+ *     .map();</pre>
+ *
+ * we can further eliminate redundant data:
+ *
+ * <pre>{ flare: {
+ *     flex: {
+ *       FlareVis: 4116 },
+ *     physics: {
+ *       DragForce: 1082,
+ *       GravityForce: 1336 },
+ *   ... } }</pre>
+ *
+ * For visualizations with large data sets, performance improvements may be seen
+ * by storing the data in a tree format, and then flattening it into an array at
+ * runtime with {@link pv.Flatten}.
+ *
+ * @param {array} array an array from which to construct a tree.
+ */
+pv.Tree = function(array) {
+  this.array = array;
+};
+
+/**
+ * Assigns a <i>keys</i> function to this operator; required. The keys function
+ * returns an array of <tt>string</tt>s for each element in the associated
+ * array; these keys determine how the elements are nested in the tree. The
+ * returned keys should be unique for each element in the array; otherwise, the
+ * behavior of this operator is undefined.
+ *
+ * @param {function} k the keys function.
+ * @returns {pv.Tree} this.
+ */
+pv.Tree.prototype.keys = function(k) {
+  this.k = k;
+  return this;
+};
+
+/**
+ * Assigns a <i>value</i> function to this operator; optional. The value
+ * function specifies an optional transformation of the element in the array
+ * before it is inserted into the map. If no value function is specified, it is
+ * equivalent to using the identity function.
+ *
+ * @param {function} k the value function.
+ * @returns {pv.Tree} this.
+ */
+pv.Tree.prototype.value = function(v) {
+  this.v = v;
+  return this;
+};
+
+/**
+ * Returns a hierarchical map of values. The hierarchy is determined by the keys
+ * function; the values in the map are determined by the value function.
+ *
+ * @returns a hierarchical map of values.
+ */
+pv.Tree.prototype.map = function() {
+  var map = {}, o = {};
+  for (var i = 0; i < this.array.length; i++) {
+    o.index = i;
+    var value = this.array[i], keys = this.k.call(o, value), node = map;
+    for (var j = 0; j < keys.length - 1; j++) {
+      node = node[keys[j]] || (node[keys[j]] = {});
+    }
+    node[keys[j]] = this.v ? this.v.call(o, value) : value;
+  }
+  return map;
+};

data/vendor/src/data/Vector.js

@@ -0,0 +1,118 @@
+/**
+ * Returns a {@link pv.Vector} for the specified <i>x</i> and <i>y</i>
+ * coordinate. This is a convenience factory method, equivalent to <tt>new
+ * pv.Vector(x, y)</tt>.
+ *
+ * @see pv.Vector
+ * @param {number} x the <i>x</i> coordinate.
+ * @param {number} y the <i>y</i> coordinate.
+ * @returns {pv.Vector} a vector for the specified coordinates.
+ */
+pv.vector = function(x, y) {
+  return new pv.Vector(x, y);
+};
+
+/**
+ * Constructs a {@link pv.Vector} for the specified <i>x</i> and <i>y</i>
+ * coordinate. This constructor should not be invoked directly; use
+ * {@link pv.vector} instead.
+ *
+ * @class Represents a two-dimensional vector; a 2-tuple <i>&#x27e8;x,
+ * y&#x27e9;</i>. The intent of this class is to simplify vector math. Note that
+ * in performance-sensitive cases it may be more efficient to represent 2D
+ * vectors as simple objects with <tt>x</tt> and <tt>y</tt> attributes, rather
+ * than using instances of this class.
+ *
+ * @param {number} x the <i>x</i> coordinate.
+ * @param {number} y the <i>y</i> coordinate.
+ */
+pv.Vector = function(x, y) {
+  this.x = x;
+  this.y = y;
+};
+
+/**
+ * Returns a vector perpendicular to this vector: <i>&#x27e8;-y, x&#x27e9;</i>.
+ *
+ * @returns {pv.Vector} a perpendicular vector.
+ */
+pv.Vector.prototype.perp = function() {
+  return new pv.Vector(-this.y, this.x);
+};
+
+/**
+ * Returns a normalized copy of this vector: a vector with the same direction,
+ * but unit length. If this vector has zero length this method returns a copy of
+ * this vector.
+ *
+ * @returns {pv.Vector} a unit vector.
+ */
+pv.Vector.prototype.norm = function() {
+  var l = this.length();
+  return this.times(l ? (1 / l) : 1);
+};
+
+/**
+ * Returns the magnitude of this vector, defined as <i>sqrt(x * x + y * y)</i>.
+ *
+ * @returns {number} a length.
+ */
+pv.Vector.prototype.length = function() {
+  return Math.sqrt(this.x * this.x + this.y * this.y);
+};
+
+/**
+ * Returns a scaled copy of this vector: <i>&#x27e8;x * k, y * k&#x27e9;</i>.
+ * To perform the equivalent divide operation, use <i>1 / k</i>.
+ *
+ * @param {number} k the scale factor.
+ * @returns {pv.Vector} a scaled vector.
+ */
+pv.Vector.prototype.times = function(k) {
+  return new pv.Vector(this.x * k, this.y * k);
+};
+
+/**
+ * Returns this vector plus the vector <i>v</i>: <i>&#x27e8;x + v.x, y +
+ * v.y&#x27e9;</i>. If only one argument is specified, it is interpreted as the
+ * vector <i>v</i>.
+ *
+ * @param {number} x the <i>x</i> coordinate to add.
+ * @param {number} y the <i>y</i> coordinate to add.
+ * @returns {pv.Vector} a new vector.
+ */
+pv.Vector.prototype.plus = function(x, y) {
+  return (arguments.length == 1)
+      ? new pv.Vector(this.x + x.x, this.y + x.y)
+      : new pv.Vector(this.x + x, this.y + y);
+};
+
+/**
+ * Returns this vector minus the vector <i>v</i>: <i>&#x27e8;x - v.x, y -
+ * v.y&#x27e9;</i>. If only one argument is specified, it is interpreted as the
+ * vector <i>v</i>.
+ *
+ * @param {number} x the <i>x</i> coordinate to subtract.
+ * @param {number} y the <i>y</i> coordinate to subtract.
+ * @returns {pv.Vector} a new vector.
+ */
+pv.Vector.prototype.minus = function(x, y) {
+  return (arguments.length == 1)
+      ? new pv.Vector(this.x - x.x, this.y - x.y)
+      : new pv.Vector(this.x - x, this.y - y);
+};
+
+/**
+ * Returns the dot product of this vector and the vector <i>v</i>: <i>x * v.x +
+ * y * v.y</i>. If only one argument is specified, it is interpreted as the
+ * vector <i>v</i>.
+ *
+ * @param {number} x the <i>x</i> coordinate to dot.
+ * @param {number} y the <i>y</i> coordinate to dot.
+ * @returns {number} a dot product.
+ */
+pv.Vector.prototype.dot = function(x, y) {
+  return (arguments.length == 1)
+      ? this.x * x.x + this.y * x.y
+      : this.x * x + this.y * y;
+};

data/vendor/src/geo/Geo.js

@@ -0,0 +1,5 @@
+/**
+ * @ignore
+ * @namespace
+ */
+pv.Geo = function() {};

data/vendor/src/geo/GeoScale.js

@@ -0,0 +1,307 @@
+/**
+ * Returns a geographic scale. The arguments to this constructor are optional,
+ * and equivalent to calling {@link #projection}.
+ *
+ * @class Represents a geographic scale; a mapping between latitude-longitude
+ * coordinates and screen pixel coordinates. By default, the domain is inferred
+ * from the geographic coordinates, so that the domain fills the output range.
+ *
+ * <p>Note that geographic scales are two-dimensional transformations, rather
+ * than the one-dimensional bidrectional mapping typical of other scales.
+ * Rather than mapping (for example) between a numeric domain and a numeric
+ * range, geographic scales map between two coordinate objects: {@link
+ * pv.Geo.LatLng} and {@link pv.Vector}.
+ *
+ * @param {pv.Geo.Projection} [p] optional projection.
+ * @see pv.Geo.scale#ticks
+ */
+pv.Geo.scale = function(p) {
+  var rmin = {x: 0, y: 0}, // default range minimum
+      rmax = {x: 1, y: 1}, // default range maximum
+      d = [], // default domain
+      j = pv.Geo.projections.identity, // domain <-> normalized range
+      x = pv.Scale.linear(-1, 1).range(0, 1), // normalized <-> range
+      y = pv.Scale.linear(-1, 1).range(1, 0), // normalized <-> range
+      c = {lng: 0, lat: 0}, // Center Point
+      lastLatLng, // cached latlng
+      lastPoint; // cached point
+
+  /** @private */
+  function scale(latlng) {
+    if (!lastLatLng
+        || (latlng.lng != lastLatLng.lng)
+        || (latlng.lat != lastLatLng.lat)) {
+      lastLatLng = latlng;
+      var p = project(latlng);
+      lastPoint = {x: x(p.x), y: y(p.y)};
+    }
+    return lastPoint;
+  }
+
+  /** @private */
+  function project(latlng) {
+    var offset = {lng: latlng.lng - c.lng, lat: latlng.lat};
+    return j.project(offset);
+  }
+
+  /** @private */
+  function invert(xy) {
+    var latlng = j.invert(xy);
+    latlng.lng += c.lng;
+    return latlng;
+  }
+
+  /** Returns the projected x-coordinate. */
+  scale.x = function(latlng) {
+    return scale(latlng).x;
+  };
+
+  /** Returns the projected y-coordinate. */
+  scale.y = function(latlng) {
+    return scale(latlng).y;
+  };
+
+  /**
+   * Abstract; this is a local namespace on a given geographic scale.
+   *
+   * @namespace Tick functions for geographic scales. Because geographic scales
+   * represent two-dimensional transformations (as opposed to one-dimensional
+   * transformations typical of other scales), the tick values are similarly
+   * represented as two-dimensional coordinates in the input domain, i.e.,
+   * {@link pv.Geo.LatLng} objects.
+   *
+   * <p>Also, note that non-rectilinear projections, such as sinsuoidal and
+   * aitoff, may not produce straight lines for constant longitude or constant
+   * latitude. Therefore the returned array of ticks is a two-dimensional array,
+   * sampling various latitudes as constant longitude, and vice versa.
+   *
+   * <p>The tick lines can therefore be approximated as polylines, either with
+   * "linear" or "cardinal" interpolation. This is not as accurate as drawing
+   * the true curve through the projection space, but is usually sufficient.
+   *
+   * @name pv.Geo.scale.prototype.ticks
+   * @see pv.Geo.scale
+   * @see pv.Geo.LatLng
+   * @see pv.Line#interpolate
+   */
+  scale.ticks = {
+
+    /**
+     * Returns longitude ticks.
+     *
+     * @function
+     * @param {number} [m] the desired number of ticks.
+     * @returns {array} a nested array of <tt>pv.Geo.LatLng</tt> ticks.
+     * @name pv.Geo.scale.prototype.ticks.prototype.lng
+     */
+    lng: function(m) {
+      var lat, lng;
+      if (d.length > 1) {
+        var s = pv.Scale.linear();
+        if (m == undefined) m = 10;
+        lat = s.domain(d, function(d) { return d.lat; }).ticks(m);
+        lng = s.domain(d, function(d) { return d.lng; }).ticks(m);
+      } else {
+        lat = pv.range(-80, 81, 10);
+        lng = pv.range(-180, 181, 10);
+      }
+      return lng.map(function(lng) {
+        return lat.map(function(lat) {
+          return {lat: lat, lng: lng};
+        });
+      });
+    },
+
+    /**
+     * Returns latitude ticks.
+     *
+     * @function
+     * @param {number} [m] the desired number of ticks.
+     * @returns {array} a nested array of <tt>pv.Geo.LatLng</tt> ticks.
+     * @name pv.Geo.scale.prototype.ticks.prototype.lat
+     */
+    lat: function(m) {
+      return pv.transpose(scale.ticks.lng(m));
+    }
+  };
+
+  /**
+   * Inverts the specified value in the output range, returning the
+   * corresponding value in the input domain. This is frequently used to convert
+   * the mouse location (see {@link pv.Mark#mouse}) to a value in the input
+   * domain. Inversion is only supported for numeric ranges, and not colors.
+   *
+   * <p>Note that this method does not do any rounding or bounds checking. If
+   * the input domain is discrete (e.g., an array index), the returned value
+   * should be rounded. If the specified <tt>y</tt> value is outside the range,
+   * the returned value may be equivalently outside the input domain.
+   *
+   * @function
+   * @name pv.Geo.scale.prototype.invert
+   * @param {number} y a value in the output range (a pixel location).
+   * @returns {number} a value in the input domain.
+   */
+  scale.invert = function(p) {
+    return invert({x: x.invert(p.x), y: y.invert(p.y)});
+  };
+
+  /**
+   * Sets or gets the input domain. Note that unlike quantitative scales, the
+   * domain cannot be reduced to a simple rectangle (i.e., minimum and maximum
+   * values for latitude and longitude). Instead, the domain values must be
+   * projected to normalized space, effectively finding the domain in normalized
+   * space rather than in terms of latitude and longitude. Thus, changing the
+   * projection requires recomputing the normalized domain.
+   *
+   * <p>This method can be invoked several ways:
+   *
+   * <p>1. <tt>domain(values...)</tt>
+   *
+   * <p>Specifying the domain as a series of {@link pv.Geo.LatLng}s is the most
+   * explicit and recommended approach. However, if the domain values are
+   * derived from data, you may find the second method more appropriate.
+   *
+   * <p>2. <tt>domain(array, f)</tt>
+   *
+   * <p>Rather than enumerating the domain explicitly, you can specify a single
+   * argument of an array. In addition, you can specify an optional accessor
+   * function to extract the domain values (as {@link pv.Geo.LatLng}s) from the
+   * array. If the specified array has fewer than two elements, this scale will
+   * default to the full normalized domain.
+   *
+   * <p>2. <tt>domain()</tt>
+   *
+   * <p>Invoking the <tt>domain</tt> method with no arguments returns the
+   * current domain as an array.
+   *
+   * @function
+   * @name pv.Geo.scale.prototype.domain
+   * @param {...} domain... domain values.
+   * @returns {pv.Geo.scale} <tt>this</tt>, or the current domain.
+   */
+  scale.domain = function(array, f) {
+    if (arguments.length) {
+      d = (array instanceof Array)
+          ? ((arguments.length > 1) ? pv.map(array, f) : array)
+          : Array.prototype.slice.call(arguments);
+      if (d.length > 1) {
+        var lngs = d.map(function(c) { return c.lng; });
+        var lats = d.map(function(c) { return c.lat; });
+        c = {
+          lng: (pv.max(lngs) + pv.min(lngs)) / 2,
+          lat: (pv.max(lats) + pv.min(lats)) / 2
+        };
+        var n = d.map(project); // normalized domain
+        x.domain(n, function(p) { return p.x; });
+        y.domain(n, function(p) { return p.y; });
+      } else {
+        c = {lng: 0, lat: 0};
+        x.domain(-1, 1);
+        y.domain(-1, 1);
+      }
+      lastLatLng = null; // invalidate the cache
+      return this;
+    }
+    return d;
+  };
+
+  /**
+   * Sets or gets the output range. This method can be invoked several ways:
+   *
+   * <p>1. <tt>range(min, max)</tt>
+   *
+   * <p>If two objects are specified, the arguments should be {@link pv.Vector}s
+   * which specify the minimum and maximum values of the x- and y-coordinates
+   * explicitly.
+   *
+   * <p>2. <tt>range(width, height)</tt>
+   *
+   * <p>If two numbers are specified, the arguments specify the maximum values
+   * of the x- and y-coordinates explicitly; the minimum values are implicitly
+   * zero.
+   *
+   * <p>3. <tt>range()</tt>
+   *
+   * <p>Invoking the <tt>range</tt> method with no arguments returns the current
+   * range as an array of two {@link pv.Vector}s: the minimum (top-left) and
+   * maximum (bottom-right) values.
+   *
+   * @function
+   * @name pv.Geo.scale.prototype.range
+   * @param {...} range... range values.
+   * @returns {pv.Geo.scale} <tt>this</tt>, or the current range.
+   */
+  scale.range = function(min, max) {
+    if (arguments.length) {
+      if (typeof min == "object") {
+        rmin = {x: Number(min.x), y: Number(min.y)};
+        rmax = {x: Number(max.x), y: Number(max.y)};
+      } else {
+        rmin = {x: 0, y: 0};
+        rmax = {x: Number(min), y: Number(max)};
+      }
+      x.range(rmin.x, rmax.x);
+      y.range(rmax.y, rmin.y); // XXX flipped?
+      lastLatLng = null; // invalidate the cache
+      return this;
+    }
+    return [rmin, rmax];
+  };
+
+  /**
+   * Sets or gets the projection. This method can be invoked several ways:
+   *
+   * <p>1. <tt>projection(string)</tt>
+   *
+   * <p>Specifying a string sets the projection to the given named projection in
+   * {@link pv.Geo.projections}. If no such projection is found, the identity
+   * projection is used.
+   *
+   * <p>2. <tt>projection(object)</tt>
+   *
+   * <p>Specifying an object sets the projection to the given custom projection,
+   * which must implement the <i>forward</i> and <i>inverse</i> methods per the
+   * {@link pv.Geo.Projection} interface.
+   *
+   * <p>3. <tt>projection()</tt>
+   *
+   * <p>Invoking the <tt>projection</tt> method with no arguments returns the
+   * current object that defined the projection.
+   *
+   * @function
+   * @name pv.Scale.geo.prototype.projection
+   * @param {...} range... range values.
+   * @returns {pv.Scale.geo} <tt>this</tt>, or the current range.
+   */
+  scale.projection = function(p) {
+    if (arguments.length) {
+      j = typeof p == "string"
+          ? pv.Geo.projections[p] || pv.Geo.projections.identity
+          : p;
+      return this.domain(d); // recompute normalized domain
+    }
+    return p;
+  };
+
+  /**
+   * Returns a view of this scale by the specified accessor function <tt>f</tt>.
+   * Given a scale <tt>g</tt>, <tt>g.by(function(d) d.foo)</tt> is equivalent to
+   * <tt>function(d) g(d.foo)</tt>. This method should be used judiciously; it
+   * is typically more clear to invoke the scale directly, passing in the value
+   * to be scaled.
+   *
+   * @function
+   * @name pv.Geo.scale.prototype.by
+   * @param {function} f an accessor function.
+   * @returns {pv.Geo.scale} a view of this scale by the specified accessor
+   * function.
+   */
+  scale.by = function(f) {
+    function by() { return scale(f.apply(this, arguments)); }
+    for (var method in scale) by[method] = scale[method];
+    return by;
+  };
+
+  if (arguments.length) scale.projection(p);
+  return scale;
+};