Animate API

Author: rreusser

src/components/drawing/index.js

@@ -46,16 +46,62 @@ drawing.setRect = function(s, x, y, w, h) {
     s.call(drawing.setPosition, x, y).call(drawing.setSize, w, h);
 };
 
-drawing.translatePoints = function(s, xa, ya) {
-    s.each(function(d) {
+drawing.translatePoints = function(s, xa, ya, trace, transitionConfig, joinDirection) {
+    var size;
+
+    var hasTransition = transitionConfig && (transitionConfig || {}).duration > 0;
+
+    if(hasTransition) {
+        size = s.size();
+    }
+
+    s.each(function(d, i) {
         // put xp and yp into d if pixel scaling is already done
         var x = d.xp || xa.c2p(d.x),
             y = d.yp || ya.c2p(d.y),
             p = d3.select(this);
         if(isNumeric(x) && isNumeric(y)) {
             // for multiline text this works better
-            if(this.nodeName === 'text') p.attr('x', x).attr('y', y);
-            else p.attr('transform', 'translate(' + x + ',' + y + ')');
+            if(this.nodeName === 'text') {
+                p.attr('x', x).attr('y', y);
+            } else {
+                if(hasTransition) {
+                    var trans;
+                    if(!joinDirection) {
+                        trans = p.transition()
+                        .delay(transitionConfig.delay + transitionConfig.cascade / size * i)
+                        .duration(transitionConfig.duration)
+                        .ease(transitionConfig.ease)
+                        .attr('transform', 'translate(' + x + ',' + y + ')');
+
+                        if(trace) {
+                            trans.call(drawing.pointStyle, trace);
+                        }
+                    } else if(joinDirection === -1) {
+                        trans = p.style('opacity', 1)
+                        .transition()
+                            .duration(transitionConfig.duration)
+                            .ease(transitionConfig.ease)
+                            .style('opacity', 0)
+                            .remove();
+                    } else if(joinDirection === 1) {
+                        trans = p.attr('transform', 'translate(' + x + ',' + y + ')');
+
+                        if(trace) {
+                            trans.call(drawing.pointStyle, trace);
+                        }
+
+                        trans.style('opacity', 0)
+                        .transition()
+                            .duration(transitionConfig.duration)
+                            .ease(transitionConfig.ease)
+                            .style('opacity', 1);
+                    }
+
+                } else {
+                    p.attr('transform', 'translate(' + x + ',' + y + ')');
+                }
+            }
         }
         else p.remove();
     });

src/components/errorbars/plot.js

@@ -12,14 +12,18 @@
 var d3 = require('d3');
 var isNumeric = require('fast-isnumeric');
 
-var Lib = require('../../lib');
 var subTypes = require('../../traces/scatter/subtypes');
+var styleError = require('./style');
 
 
-module.exports = function plot(traces, plotinfo) {
+module.exports = function plot(traces, plotinfo, transitionConfig) {
+    var isNew;
     var xa = plotinfo.x(),
         ya = plotinfo.y();
 
+    transitionConfig = transitionConfig || {};
+    var hasAnimation = isNumeric(transitionConfig.duration) && transitionConfig.duration > 0;
+
     traces.each(function(d) {
         var trace = d[0].trace,
             // || {} is in case the trace (specifically scatterternary)
@@ -29,6 +33,12 @@ module.exports = function plot(traces, plotinfo) {
             xObj = trace.error_x || {},
             yObj = trace.error_y || {};
 
+        var keyFunc;
+
+        if(trace.identifier) {
+            keyFunc = function(d) {return d.identifier;};
+        }
+
         var sparse = (
             subTypes.hasMarkers(trace) &&
             trace.marker.maxdisplayed > 0
@@ -37,11 +47,21 @@ module.exports = function plot(traces, plotinfo) {
         if(!yObj.visible && !xObj.visible) return;
 
         var errorbars = d3.select(this).selectAll('g.errorbar')
-            .data(Lib.identity);
+            .data(d, keyFunc);
 
-        errorbars.enter().append('g')
+        errorbars.exit().remove();
+
+        errorbars.style('opacity', 1);
+
+        var enter = errorbars.enter().append('g')
             .classed('errorbar', true);
 
+        if(hasAnimation) {
+            enter.style('opacity', 0).transition()
+                .duration(transitionConfig.duration)
+                .style('opacity', 1);
+        }
+
         errorbars.each(function(d) {
             var errorbar = d3.select(this);
             var coords = errorCoords(d, xa, ya);
@@ -59,14 +79,28 @@ module.exports = function plot(traces, plotinfo) {
                     coords.yh + 'h' + (2 * yw) + // hat
                     'm-' + yw + ',0V' + coords.ys; // bar
 
+
                 if(!coords.noYS) path += 'm-' + yw + ',0h' + (2 * yw); // shoe
 
-                errorbar.append('path')
-                    .classed('yerror', true)
-                    .attr('d', path);
+                var yerror = errorbar.select('path.yerror');
+
+                isNew = !yerror.size();
+
+                if(isNew) {
+                    yerror = errorbar.append('path')
+                        .classed('yerror', true);
+                } else if(hasAnimation) {
+                    yerror = yerror
+                        .transition()
+                            .duration(transitionConfig.duration)
+                            .ease(transitionConfig.ease)
+                            .delay(transitionConfig.delay);
+                }
+
+                yerror.attr('d', path);
             }
 
-            if(xObj.visible && isNumeric(coords.y) &&
+            if(xObj.visible && isNumeric(coords.x) &&
                     isNumeric(coords.xh) &&
                     isNumeric(coords.xs)) {
                 var xw = (xObj.copy_ystyle ? yObj : xObj).width;
@@ -77,11 +111,26 @@ module.exports = function plot(traces, plotinfo) {
 
                 if(!coords.noXS) path += 'm0,-' + xw + 'v' + (2 * xw); // shoe
 
-                errorbar.append('path')
-                    .classed('xerror', true)
-                    .attr('d', path);
+                var xerror = errorbar.select('path.xerror');
+
+                isNew = !xerror.size();
+
+                if(isNew) {
+                    xerror = errorbar.append('path')
+                        .classed('xerror', true);
+                } else if(hasAnimation) {
+                    xerror = xerror
+                        .transition()
+                            .duration(transitionConfig.duration)
+                            .ease(transitionConfig.ease)
+                            .delay(transitionConfig.delay);
+                }
+
+                xerror.attr('d', path);
             }
         });
+
+        d3.select(this).call(styleError);
     });
 };
 

src/core.js

@@ -34,6 +34,10 @@ exports.register = Plotly.register;
 exports.toImage = require('./plot_api/to_image');
 exports.downloadImage = require('./snapshot/download');
 exports.validate = require('./plot_api/validate');
+exports.addFrames = Plotly.addFrames;
+exports.deleteFrames = Plotly.deleteFrames;
+exports.transition = Plotly.transition;
+exports.animate = Plotly.animate;
 
 // plot icons
 exports.Icons = require('../build/ploticon');

src/lib/index.js

@@ -573,6 +573,40 @@ lib.objectFromPath = function(path, value) {
     return obj;
 };
 
+/**
+ * Iterate through an object in-place, converting dotted properties to objects.
+ *
+ * @example
+ * lib.expandObjectPaths({'nested.test.path': 'value'});
+ * // returns { nested: { test: {path: 'value'}}}
+ */
+
+// Store this to avoid recompiling regex on every prop since this may happen many
+// many times for animations.
+// TODO: Premature optimization? Remove?
+var dottedPropertyRegex = /^([^\.]*)\../;
+
+lib.expandObjectPaths = function(data) {
+    var match, key, prop, datum;
+    if(typeof data === 'object' && !Array.isArray(data)) {
+        for(key in data) {
+            if(data.hasOwnProperty(key)) {
+                if((match = key.match(dottedPropertyRegex))) {
+                    datum = data[key];
+                    prop = match[1];
+
+                    delete data[key];
+
+                    data[prop] = lib.extendDeepNoArrays(data[prop] || {}, lib.objectFromPath(key, lib.expandObjectPaths(datum))[prop]);
+                } else {
+                    data[key] = lib.expandObjectPaths(data[key]);
+                }
+            }
+        }
+    }
+    return data;
+};
+
 /**
  * Converts value to string separated by the provided separators.
  *
@@ -616,3 +650,89 @@ lib.numSeparate = function(value, separators) {
 
     return x1 + x2;
 };
+
+/*
+ * Compute a keyframe. Merge a keyframe into its base frame(s) and
+ * expand properties.
+ *
+ * @param {object} frameLookup
+ *      An object containing frames keyed by name (i.e. gd._frameData._frameHash)
+ * @param {string} frame
+ *      The name of the keyframe to be computed
+ *
+ * Returns: a new object with the merged content
+ */
+lib.computeFrame = function(frameLookup, frameName) {
+    var i, traceIndices, traceIndex, expandedObj, destIndex, copy;
+
+    var framePtr = frameLookup[frameName];
+
+    // Return false if the name is invalid:
+    if(!framePtr) {
+        return false;
+    }
+
+    var frameStack = [framePtr];
+    var frameNameStack = [framePtr.name];
+
+    // Follow frame pointers:
+    while((framePtr = frameLookup[framePtr.baseFrame])) {
+        // Avoid infinite loops:
+        if(frameNameStack.indexOf(framePtr.name) !== -1) break;
+
+        frameStack.push(framePtr);
+        frameNameStack.push(framePtr.name);
+    }
+
+    // A new object for the merged result:
+    var result = {};
+
+    // Merge, starting with the last and ending with the desired frame:
+    while((framePtr = frameStack.pop())) {
+        if(framePtr.layout) {
+            copy = lib.extendDeepNoArrays({}, framePtr.layout);
+            expandedObj = lib.expandObjectPaths(copy);
+            result.layout = lib.extendDeepNoArrays(result.layout || {}, expandedObj);
+        }
+
+        if(framePtr.data) {
+            if(!result.data) {
+                result.data = [];
+            }
+            traceIndices = framePtr.traceIndices;
+
+            if(!traceIndices) {
+                // If not defined, assume serial order starting at zero
+                traceIndices = [];
+                for(i = 0; i < framePtr.data.length; i++) {
+                    traceIndices[i] = i;
+                }
+            }
+
+            if(!result.traceIndices) {
+                result.traceIndices = [];
+            }
+
+            for(i = 0; i < framePtr.data.length; i++) {
+                // Loop through this frames data, find out where it should go,
+                // and merge it!
+                traceIndex = traceIndices[i];
+                if(traceIndex === undefined || traceIndex === null) {
+                    continue;
+                }
+
+                destIndex = result.traceIndices.indexOf(traceIndex);
+                if(destIndex === -1) {
+                    destIndex = result.data.length;
+                    result.traceIndices[destIndex] = traceIndex;
+                }
+
+                copy = lib.extendDeepNoArrays({}, framePtr.data[i]);
+                expandedObj = lib.expandObjectPaths(copy);
+                result.data[destIndex] = lib.extendDeepNoArrays(result.data[destIndex] || {}, expandedObj);
+            }
+        }
+    }
+
+    return result;
+};