Refactor animationOpts API

Author: rreusser

src/components/errorbars/plot.js

@@ -14,12 +14,12 @@ var isNumeric = require('fast-isnumeric');
 
 var subTypes = require('../../traces/scatter/subtypes');
 
-module.exports = function plot(traces, plotinfo, transitionConfig) {
+module.exports = function plot(traces, plotinfo, transitionOpts) {
     var isNew;
     var xa = plotinfo.x(),
         ya = plotinfo.y();
 
-    var hasAnimation = transitionConfig && transitionConfig.transitionduration > 0;
+    var hasAnimation = transitionOpts && transitionOpts.duration > 0;
 
     traces.each(function(d) {
         var trace = d[0].trace,
@@ -55,7 +55,7 @@ module.exports = function plot(traces, plotinfo, transitionConfig) {
 
         if(hasAnimation) {
             enter.style('opacity', 0).transition()
-                .duration(transitionConfig.transitionduration)
+                .duration(transitionOpts.duration)
                 .style('opacity', 1);
         }
 
@@ -89,8 +89,8 @@ module.exports = function plot(traces, plotinfo, transitionConfig) {
                 } else if(hasAnimation) {
                     yerror = yerror
                         .transition()
-                            .duration(transitionConfig.transitionduration)
-                            .ease(transitionConfig.ease);
+                            .duration(transitionOpts.duration)
+                            .ease(transitionOpts.easing);
                 }
 
                 yerror.attr('d', path);
@@ -117,8 +117,8 @@ module.exports = function plot(traces, plotinfo, transitionConfig) {
                 } else if(hasAnimation) {
                     xerror = xerror
                         .transition()
-                            .duration(transitionConfig.transitionduration)
-                            .ease(transitionConfig.ease);
+                            .duration(transitionOpts.duration)
+                            .ease(transitionOpts.easing);
                 }
 
                 xerror.attr('d', path);

src/plot_api/plot_api.js

@@ -2460,10 +2460,10 @@ Plotly.relayout = function relayout(gd, astr, val) {
  *
  * @param {string} name
  *      name of the keyframe to create
- * @param {object} transitionOpts
- *      configuration for transition
+ * @param {object} animationOpts
+ *      configuration for animation
  */
-Plotly.animate = function(gd, frameOrGroupNameOrFrameList, transitionOpts, animationOpts) {
+Plotly.animate = function(gd, frameOrGroupNameOrFrameList, animationOpts) {
     gd = getGraphDiv(gd);
     var trans = gd._transitionData;
 
@@ -2474,6 +2474,8 @@ Plotly.animate = function(gd, frameOrGroupNameOrFrameList, transitionOpts, anima
     }
 
     animationOpts = Plots.supplyAnimationDefaults(animationOpts);
+    var transitionOpts = animationOpts.transition;
+    var frameOpts = animationOpts.frame;
 
     // 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,
@@ -2495,6 +2497,18 @@ Plotly.animate = function(gd, frameOrGroupNameOrFrameList, transitionOpts, anima
         }
     }
 
+    function getFrameOpts(i) {
+        if(Array.isArray(frameOpts)) {
+            if(i >= frameOpts.length) {
+                return frameOpts[0];
+            } else {
+                return frameOpts[i];
+            }
+        } else {
+            return frameOpts;
+        }
+    }
+
     return new Promise(function(resolve, reject) {
         function discardExistingFrames() {
             if(trans._frameQueue.length === 0) {
@@ -2522,12 +2536,11 @@ Plotly.animate = function(gd, frameOrGroupNameOrFrameList, transitionOpts, anima
                     computedFrame = frameList[i].frame;
                 }
 
-                var opts = Plots.supplyTransitionDefaults(getTransitionOpts(i));
-
                 var nextFrame = {
                     frame: computedFrame,
                     name: frameList[i].name,
-                    transitionOpts: opts
+                    frameOpts: getFrameOpts(i),
+                    transitionOpts: getTransitionOpts(i)
                 };
 
                 if(i === frameList.length - 1) {
@@ -2559,12 +2572,13 @@ Plotly.animate = function(gd, frameOrGroupNameOrFrameList, transitionOpts, anima
 
             if(newFrame) {
                 trans._lastframeat = Date.now();
-                trans._timetonext = newFrame.transitionOpts.frameduration;
+                trans._timetonext = newFrame.frameOpts.duration;
 
                 Plots.transition(gd,
                     newFrame.frame.data,
                     newFrame.frame.layout,
                     newFrame.frame.traces,
+                    newFrame.frameOpts,
                     newFrame.transitionOpts
                 ).then(function() {
                     if(trans._frameQueue.length === 0) {

src/plots/animation_attributes.js

@@ -19,4 +19,80 @@ module.exports = {
             'are rejected and a `plotly_animateinterrupt` event is emitted.'
         ].join(' ')
     },
+    frame: {
+        duration: {
+            valType: 'number',
+            role: 'info',
+            min: 0,
+            dflt: 500,
+            description: 'The duration in milliseconds of each frame.'
+        },
+        redraw: {
+            valType: 'boolean',
+            role: 'info',
+            dflt: true,
+            description: [
+                'Redraw the plot at completion of the transition. This is desirable',
+                'for transitions that include properties that cannot be transitioned,',
+                'but may significantly slow down updates that do not require a full',
+                'redraw of the plot'
+            ].join(' ')
+        },
+    },
+    transition: {
+        duration: {
+            valType: 'number',
+            role: 'info',
+            min: 0,
+            dflt: 500,
+            description: [
+                'The duration of the transition, in milliseconds. If equal to zero,',
+                'updates are synchronous.'
+            ].join(' ')
+        },
+        easing: {
+            valType: 'enumerated',
+            dflt: 'cubic-in-out',
+            values: [
+                'linear',
+                'quad',
+                'cubic',
+                'sin',
+                'exp',
+                'circle',
+                'elastic',
+                'back',
+                'bounce',
+                'linear-in',
+                'quad-in',
+                'cubic-in',
+                'sin-in',
+                'exp-in',
+                'circle-in',
+                'elastic-in',
+                'back-in',
+                'bounce-in',
+                'linear-out',
+                'quad-out',
+                'cubic-out',
+                'sin-out',
+                'exp-out',
+                'circle-out',
+                'elastic-out',
+                'back-out',
+                'bounce-out',
+                'linear-in-out',
+                'quad-in-out',
+                'cubic-in-out',
+                'sin-in-out',
+                'exp-in-out',
+                'circle-in-out',
+                'elastic-in-out',
+                'back-in-out',
+                'bounce-in-out'
+            ],
+            role: 'info',
+            description: 'The easing function used for the transition'
+        },
+    }
 };

src/plots/cartesian/transition_axes.js

@@ -17,7 +17,7 @@ var Lib = require('../../lib');
 var Axes = require('./axes');
 var axisRegex = /((x|y)([2-9]|[1-9][0-9]+)?)axis$/;
 
-module.exports = function transitionAxes(gd, newLayout, transitionConfig, makeOnCompleteCallback) {
+module.exports = function transitionAxes(gd, newLayout, transitionOpts, makeOnCompleteCallback) {
     var fullLayout = gd._fullLayout;
     var axes = [];
 
@@ -277,7 +277,7 @@ module.exports = function transitionAxes(gd, newLayout, transitionConfig, makeOn
     }
 
     var t1, t2, raf;
-    var easeFn = d3.ease(transitionConfig.ease);
+    var easeFn = d3.ease(transitionOpts.easing);
 
     gd._transitionData._interruptCallbacks.push(function() {
         cancelAnimationFrame(raf);
@@ -288,14 +288,14 @@ module.exports = function transitionAxes(gd, newLayout, transitionConfig, makeOn
     function doFrame() {
         t2 = Date.now();
 
-        var tInterp = Math.min(1, (t2 - t1) / transitionConfig.transitionduration);
+        var tInterp = Math.min(1, (t2 - t1) / transitionOpts.duration);
         var progress = easeFn(tInterp);
 
         for(var i = 0; i < affectedSubplots.length; i++) {
             updateSubplot(affectedSubplots[i], progress);
         }
 
-        if(t2 - t1 > transitionConfig.transitionduration) {
+        if(t2 - t1 > transitionOpts.duration) {
             transitionComplete();
             raf = cancelAnimationFrame(doFrame);
         } else {

src/plots/plots.js

@@ -17,7 +17,6 @@ var Registry = require('../registry');
 var Lib = require('../lib');
 var Color = require('../components/color');
 var plots = module.exports = {};
-var transitionAttrs = require('./transition_attributes');
 var animationAttrs = require('./animation_attributes');
 var frameAttrs = require('./frame_attributes');
 
@@ -616,6 +615,8 @@ plots.supplyDataDefaults = function(dataIn, dataOut, layout) {
 };
 
 plots.supplyAnimationDefaults = function(opts) {
+    opts = opts || {};
+    var i;
     var optsOut = {};
 
     function coerce(attr, dflt) {
@@ -624,24 +625,53 @@ plots.supplyAnimationDefaults = function(opts) {
 
     coerce('immediate');
 
+    if(Array.isArray(opts.frame)) {
+        optsOut.frame = [];
+        for(i = 0; i < opts.frame.length; i++) {
+            optsOut.frame[i] = plots.supplyAnimationFrameDefaults(opts.frame[i] || {});
+        }
+    } else {
+        optsOut.frame = plots.supplyAnimationFrameDefaults(opts.frame || {});
+    }
+
+    if(Array.isArray(opts.transition)) {
+        optsOut.transition = [];
+        for(i = 0; i < opts.transition.length; i++) {
+            optsOut.transition[i] = plots.supplyAnimationTransitionDefaults(opts.transition[i] || {});
+        }
+    } else {
+        optsOut.transition = plots.supplyAnimationTransitionDefaults(opts.transition || {});
+    }
+
     return optsOut;
 };
 
-plots.supplyTransitionDefaults = function(opts) {
+plots.supplyAnimationFrameDefaults = function(opts) {
     var optsOut = {};
 
     function coerce(attr, dflt) {
-        return Lib.coerce(opts || {}, optsOut, transitionAttrs, attr, dflt);
+        return Lib.coerce(opts || {}, optsOut, animationAttrs.frame, attr, dflt);
     }
 
-    coerce('frameduration');
-    coerce('transitionduration');
-    coerce('ease');
+    coerce('duration');
     coerce('redraw');
 
     return optsOut;
 };
 
+plots.supplyAnimationTransitionDefaults = function(opts) {
+    var optsOut = {};
+
+    function coerce(attr, dflt) {
+        return Lib.coerce(opts || {}, optsOut, animationAttrs.transition, attr, dflt);
+    }
+
+    coerce('duration');
+    coerce('easing');
+
+    return optsOut;
+};
+
 plots.supplyFrameDefaults = function(frameIn) {
     var frameOut = {};
 
@@ -1316,11 +1346,8 @@ plots.computeFrame = function(gd, frameName) {
  * @param {string id or DOM element} gd
  *      the id or DOM element of the graph container div
  */
-plots.transition = function(gd, data, layout, traceIndices, transitionOpts) {
+plots.transition = function(gd, data, layout, traceIndices, frameOpts, transitionOpts) {
     var i, traceIdx;
-    var fullLayout = gd._fullLayout;
-
-    transitionOpts = plots.supplyTransitionDefaults(transitionOpts);
 
     var dataLength = Array.isArray(data) ? data.length : 0;
 
@@ -1371,10 +1398,14 @@ plots.transition = function(gd, data, layout, traceIndices, transitionOpts) {
         // This step fies the .xaxis and .yaxis references that otherwise
         // aren't updated by the supplyDefaults step:
         var subplots = Plotly.Axes.getSubplots(gd);
-        for(i = 0; i < subplots.length; i++) {
-            plotinfo = gd._fullLayout._plots[subplots[i]];
-            plotinfo.xaxis = plotinfo.x();
-            plotinfo.yaxis = plotinfo.y();
+
+        // Polar does not have _plots:
+        if(gd._fullLayout._plots) {
+            for(i = 0; i < subplots.length; i++) {
+                plotinfo = gd._fullLayout._plots[subplots[i]];
+                plotinfo.xaxis = plotinfo.x();
+                plotinfo.yaxis = plotinfo.y();
+            }
         }
 
         plots.doCalcdata(gd);
@@ -1410,7 +1441,7 @@ plots.transition = function(gd, data, layout, traceIndices, transitionOpts) {
             // When instantaneous updates are coming through quickly, it's too much to simply disable
             // all interaction, so store this flag so we can disambiguate whether mouse interactions
             // should be fully disabled or not:
-            if(transitionOpts.transitionduration > 0) {
+            if(transitionOpts.duration > 0) {
                 gd._transitioningWithDuration = true;
             }
 
@@ -1435,7 +1466,7 @@ plots.transition = function(gd, data, layout, traceIndices, transitionOpts) {
 
             var traceTransitionOpts;
             var j;
-            var basePlotModules = fullLayout._basePlotModules;
+            var basePlotModules = gd._fullLayout._basePlotModules;
             var hasAxisTransition = false;
 
             if(layout) {
@@ -1452,7 +1483,7 @@ plots.transition = function(gd, data, layout, traceIndices, transitionOpts) {
             // to instantaneous.
             if(hasAxisTransition) {
                 traceTransitionOpts = Lib.extendFlat({}, transitionOpts);
-                traceTransitionOpts.transitionduration = 0;
+                traceTransitionOpts.duration = 0;
             } else {
                 traceTransitionOpts = transitionOpts;
             }
@@ -1475,7 +1506,7 @@ plots.transition = function(gd, data, layout, traceIndices, transitionOpts) {
         flushCallbacks(gd._transitionData._interruptCallbacks);
 
         return Promise.resolve().then(function() {
-            if(transitionOpts.redraw) {
+            if(frameOpts.redraw) {
                 return Plotly.redraw(gd);
             }
         }).then(function() {