Expand the animate API

Author: rreusser

src/plot_api/plot_api.js

@@ -2532,7 +2532,7 @@ Plotly.relayout = function relayout(gd, astr, val) {
  * @param {string id or DOM element} gd
  *      the id or DOM element of the graph container div
  */
-Plotly.transition = function(gd, data, layout, traceIndices, transitionConfig) {
+Plotly.transition = function(gd, data, layout, traceIndices, transitionConfig, onTransitioned) {
     gd = getGraphDiv(gd);
 
     var i, traceIdx;
@@ -2700,6 +2700,8 @@ Plotly.transition = function(gd, data, layout, traceIndices, transitionConfig) {
             gd._transitioningWithDuration = false;
 
             gd.emit('plotly_transitioned', []);
+            onTransitioned && onTransitioned();
+            onTransitioned = null;
         });
     }
 
@@ -2753,22 +2755,133 @@ Plotly.transition = function(gd, data, layout, traceIndices, transitionConfig) {
  * @param {object} transitionConfig
  *      configuration for transition
  */
-Plotly.animate = function(gd, frameName, transitionConfig) {
+Plotly.animate = function(gd, groupNameOrFrameList, transitionConfig) {
     gd = getGraphDiv(gd);
+    var trans = gd._transitionData;
 
-    if(!gd._transitionData._frameHash[frameName]) {
-        Lib.warn('animateToFrame failure: keyframe does not exist', frameName);
-        return Promise.reject();
+    // This is the queue of frames that will be animated as soon as possible. They
+    // are popped immediately upon the *start* of a transition:
+    if(!trans._frameQueue) {
+        trans._frameQueue = [];
+    }
+
+    // Since frames are popped immediately, an empty queue only means all frames have
+    // *started* to transition, not that the animation is complete. To solve that,
+    // track a separate counter that increments at the same time as frames are added
+    // to the queue, but decrements only when the transition is complete.
+    if(trans._frameWaitingCnt === undefined) {
+        trans._frameWaitingCnt = 0;
+    }
+
+    function queueFrames(frameList) {
+        if(frameList.length === 0) return;
+
+        for(var i = 0; i < frameList.length; i++) {
+            var computedFrame = Plots.computeFrame(gd, frameList[i].name);
+
+            trans._frameWaitingCnt++;
+            trans._frameQueue.push({
+                frame: computedFrame,
+                name: frameList[i].name,
+                transitionConfig: frameList[i].transitionConfig || {},
+                frameduration: 0,
+            });
+        }
+
+        if(!trans._animationRaf) {
+            beginAnimation();
+        }
     }
 
-    var computedFrame = Plots.computeFrame(gd, frameName);
+    function completeAnimation() {
+        cancelAnimationFrame(trans._animationRaf);
+        trans._animationRaf = null;
+    }
+
+    function beginAnimation() {
+        gd.emit('plotly_animating');
+
+        // If no timer is running, then set last frame = long ago:
+        trans._lastframeat = 0;
+        trans._timetonext = 0;
+
+        var doFrame = function() {
+            // Check if we need to pop a frame:
+            if(Date.now() - trans._lastframeat > trans._timetonext) {
+                var newFrame = trans._frameQueue.shift();
+
+                var onTransitioned = function() {
+                    trans._frameWaitingCnt--;
+                    if(trans._frameWaitingCnt === 0) {
+                        gd.emit('plotly_animated');
+                    }
+                };
 
-    return Plotly.transition(gd,
-        computedFrame.data,
-        computedFrame.layout,
-        computedFrame.traceIndices,
-        transitionConfig
-    );
+                if(newFrame) {
+                    trans._lastframeat = Date.now();
+                    trans._timetonext = newFrame.transitionConfig.frameduration === undefined ? 50 : newFrame.transitionConfig.frameduration;
+
+
+                    Plotly.transition(gd,
+                        newFrame.frame.data,
+                        newFrame.frame.layout,
+                        newFrame.frame.traces,
+                        newFrame.transitionConfig,
+                        onTransitioned
+                    );
+                }
+
+                if(trans._frameQueue.length === 0) {
+                    completeAnimation();
+                    return;
+                }
+            }
+
+            trans._animationRaf = requestAnimationFrame(doFrame);
+        };
+
+        return doFrame();
+    }
+
+    var counter = 0;
+    function setTransitionConfig(frame) {
+        if(Array.isArray(transitionConfig)) {
+            frame.transitionConfig = transitionConfig[counter];
+        } else {
+            frame.transitionConfig = transitionConfig;
+        }
+        counter++;
+        return frame;
+    }
+
+    var i, frame;
+    var frameList = [];
+    var allFrames = typeof groupNameOrFrameList === 'undefined';
+    if(allFrames || typeof groupNameOrFrameList === 'string') {
+        for(i = 0; i < trans._frames.length; i++) {
+            frame = trans._frames[i];
+
+            if(allFrames || frame.group === groupNameOrFrameList) {
+                frameList.push(setTransitionConfig({name: frame.name}));
+            }
+        }
+    } else if(Array.isArray(groupNameOrFrameList)) {
+        for(i = 0; i < groupNameOrFrameList.length; i++) {
+            frameList.push(setTransitionConfig({name: groupNameOrFrameList[i]}));
+        }
+    }
+
+    // Verify that all of these frames actually exist; return and reject if not:
+    for(i = 0; i < frameList.length; i++) {
+        if(!trans._frameHash[frameList[i].name]) {
+            Lib.warn('animate failure: frame not found: "' + frameList[i].name + '"');
+            return Promise.reject();
+        }
+    }
+
+    queueFrames(frameList);
+
+    return Promise.resolve();
 };
 
 /**
@@ -2780,7 +2893,7 @@ Plotly.animate = function(gd, frameName, transitionConfig) {
  *      - data: {array of objects} trace data
  *      - layout {object} layout definition
  *      - traces {array} trace indices
- *      - baseFrame {string} name of keyframe from which this keyframe gets defaults
+ *      - baseframe {string} name of keyframe from which this keyframe gets defaults
  */
 Plotly.addFrames = function(gd, frameList, indices) {
     gd = getGraphDiv(gd);
@@ -2805,7 +2918,7 @@ Plotly.addFrames = function(gd, frameList, indices) {
     var insertions = [];
     for(i = frameList.length - 1; i >= 0; i--) {
         insertions.push({
-            frame: frameList[i],
+            frame: Plots.supplyFrameDefaults(frameList[i]),
             index: (indices && indices[i] !== undefined && indices[i] !== null) ? indices[i] : bigIndex + i
         });
     }

src/plots/frame_attributes.js

@@ -0,0 +1,55 @@
+/**
+* Copyright 2012-2016, Plotly, Inc.
+* All rights reserved.
+*
+* This source code is licensed under the MIT license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+
+'use strict';
+
+module.exports = {
+    group: {
+        valType: 'string',
+        role: 'info',
+        description: [
+            'An identifier that specifies the group to which the frame belongs,',
+            'used by animate to select a subset of frames.'
+        ].join(' ')
+    },
+    name: {
+        valType: 'string',
+        role: 'info',
+        description: ['A label by which to identify the frame']
+    },
+    traces: {
+        valType: 'data_array',
+        description: [
+            'A list of trace indices that identify the respective traces in the',
+            'data attribute'
+        ].join(' ')
+    },
+    baseframe: {
+        valType: 'string',
+        role: 'info',
+        description: [
+            'The name of the frame into which this frame\'s properties are merged',
+            'before applying. This is used to unify properties and avoid needing',
+            'to specify the same values for the same properties in multiple frames.'
+        ].join(' ')
+    },
+    data: {
+        valType: 'data_array',
+        description: [
+            'A list of traces this frame modifies. The format is identical to the',
+            'normal trace definition.'
+        ]
+    },
+    layout: {
+        valType: 'any',
+        description: [
+            'Layout properties which this frame modifies. The format is identical',
+            'to the normal layout definition.'
+        ]
+    }
+};

src/plots/plots.js

@@ -19,6 +19,7 @@ var Color = require('../components/color');
 
 var plots = module.exports = {};
 var transitionAttrs = require('./transition_attributes');
+var frameAttrs = require('./frame_attributes');
 
 // Expose registry methods on Plots for backward-compatibility
 Lib.extendFlat(plots, Registry);
@@ -626,6 +627,23 @@ plots.supplyTransitionDefaults = function(config) {
     return configOut;
 };
 
+plots.supplyFrameDefaults = function(frameIn) {
+    var frameOut = {};
+
+    function coerce(attr, dflt) {
+        return Lib.coerce(frameIn, frameOut, frameAttrs, attr, dflt);
+    }
+
+    coerce('group');
+    coerce('name');
+    coerce('traces');
+    coerce('baseframe');
+    coerce('data');
+    coerce('layout');
+
+    return frameOut;
+};
+
 plots.supplyTraceDefaults = function(traceIn, traceIndex, layout) {
     var traceOut = {},
         defaultColor = Color.defaults[traceIndex % Color.defaults.length];
@@ -1211,7 +1229,7 @@ plots.computeFrame = function(gd, frameName) {
     var frameNameStack = [framePtr.name];
 
     // Follow frame pointers:
-    while((framePtr = frameLookup[framePtr.baseFrame])) {
+    while((framePtr = frameLookup[framePtr.baseframe])) {
         // Avoid infinite loops:
         if(frameNameStack.indexOf(framePtr.name) !== -1) break;
 
@@ -1234,7 +1252,7 @@ plots.computeFrame = function(gd, frameName) {
             if(!result.data) {
                 result.data = [];
             }
-            traceIndices = framePtr.traceIndices;
+            traceIndices = framePtr.traces;
 
             if(!traceIndices) {
                 // If not defined, assume serial order starting at zero
@@ -1244,8 +1262,8 @@ plots.computeFrame = function(gd, frameName) {
                 }
             }
 
-            if(!result.traceIndices) {
-                result.traceIndices = [];
+            if(!result.traces) {
+                result.traces = [];
             }
 
             for(i = 0; i < framePtr.data.length; i++) {
@@ -1256,10 +1274,10 @@ plots.computeFrame = function(gd, frameName) {
                     continue;
                 }
 
-                destIndex = result.traceIndices.indexOf(traceIndex);
+                destIndex = result.traces.indexOf(traceIndex);
                 if(destIndex === -1) {
                     destIndex = result.data.length;
-                    result.traceIndices[destIndex] = traceIndex;
+                    result.traces[destIndex] = traceIndex;
                 }
 
                 copy = Lib.extendDeepNoArrays({}, framePtr.data[i]);

test/image/mocks/animation.json

@@ -40,39 +40,43 @@
         }
     }, {
         "name": "frame0",
+        "group": "even-frames",
         "data": [
             {"y": [0.5, 1.5, 7.5]},
             {"y": [4.25, 2.25, 3.05]}
         ],
-        "baseFrame": "base",
-        "traceIndices": [0, 1],
+        "baseframe": "base",
+        "traces": [0, 1],
         "layout": { }
     }, {
         "name": "frame1",
+        "group": "odd-frames",
         "data": [
             {"y": [2.1, 1, 7]},
             {"y": [4.5, 2.5, 3.1]}
         ],
-        "baseFrame": "base",
-        "traceIndices": [0, 1],
+        "baseframe": "base",
+        "traces": [0, 1],
         "layout": { }
     }, {
         "name": "frame2",
+        "group": "even-frames",
         "data": [
             {"y": [3.5, 0.5, 6]},
             {"y": [5.7, 2.7, 3.9]}
         ],
-        "baseFrame": "base",
-        "traceIndices": [0, 1],
+        "baseframe": "base",
+        "traces": [0, 1],
         "layout": { }
     }, {
         "name": "frame3",
+        "group": "odd-frames",
         "data": [
             {"y": [5.1, 0.25, 5]},
             {"y": [7, 2.9, 6]}
         ],
-        "baseFrame": "base",
-        "traceIndices": [0, 1],
+        "baseframe": "base",
+        "traces": [0, 1],
         "layout": {
             "xaxis": {
                 "range": [-1, 4]