[WIP] Frame + Animate API

src/lib/index.js

@@ -546,10 +546,10 @@ lib.objectFromPath = function(path, value) {
  * Iterate through an object in-place, converting dotted properties to objects.
  *
  * @example
- * lib.expandObjectPaths('nested.test[2].path', 'value');
- * // returns { nested: { test: [null, null, { path: 'value' }]}
- *
+ * 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?

src/plots/plots.js

@@ -1181,3 +1181,86 @@ plots.modifyFrames = function(gd, operations) {
 
     return Promise.resolve();
 };
+
+/*
+ * Compute a keyframe. Merge a keyframe into its base frame(s) and
+ * expand properties.
+ *
+ * @param {object} frame
+ *      The keyframe to be computed
+ *
+ * Returns: a third object with the merged content
+ */
+plots.computeFrame = function(gd, frameName) {
+    var i, traceIndices, traceIndex, expandedObj, destIndex;
+    var _hash = gd._frameData._frameHash;
+
+    var framePtr = _hash[frameName];
+
+    // Return false if the name is invalid:
+    if(!framePtr) {
+        return false;
+    }
+
+    var frameStack = [framePtr];
+    var frameNameStack = [framePtr.name];
+
+    // Follow frame pointers:
+    while((framePtr = gd._frameData._frameHash[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) {
+            expandedObj = Lib.expandObjectPaths(framePtr.layout);
+            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;
+                }
+
+                expandedObj = Lib.expandObjectPaths(framePtr.data[i]);
+                result.data[destIndex] = Lib.extendDeepNoArrays(result.data[destIndex] || {}, expandedObj);
+            }
+        }
+    }
+
+    return result;
+};

test/jasmine/tests/compute_frame_test.js

@@ -0,0 +1,185 @@
+var Plotly = require('@lib/index');
+
+var createGraphDiv = require('../assets/create_graph_div');
+var destroyGraphDiv = require('../assets/destroy_graph_div');
+var computeFrame = require('@src/plots/plots').computeFrame;
+
+describe('Test mergeFrames', function() {
+    'use strict';
+
+    var gd, mock;
+
+    beforeEach(function(done) {
+        mock = [{x: [1, 2, 3], y: [2, 1, 3]}, {x: [1, 2, 3], y: [6, 4, 5]}];
+        gd = createGraphDiv();
+        Plotly.plot(gd, mock).then(done);
+    });
+
+    afterEach(destroyGraphDiv);
+
+    describe('computing a single frame', function() {
+        var frame1;
+
+        beforeEach(function(done) {
+            frame1 = {
+                name: 'frame1',
+                data: [{'marker.size': 8, marker: {color: 'red'}}]
+            };
+
+            Plotly.addFrames(gd, [frame1]).then(done);
+        });
+
+        it('returns false if the frame does not exist', function() {
+            expect(computeFrame(gd, 'frame8')).toBe(false);
+        });
+
+        it('returns a new object', function() {
+            expect(computeFrame(gd, 'frame1')).not.toBe(frame1);
+        });
+
+        it('computes a single frame', function() {
+            var computed = computeFrame(gd, 'frame1');
+            var expected = {data: [{marker: {size: 8, color: 'red'}}], traceIndices: [0]};
+            expect(computed).toEqual(expected);
+        });
+    });
+
+    describe('circularly defined frames', function() {
+        var frames, results;
+
+        beforeEach(function(done) {
+            frames = [
+                {name: 'frame0', baseFrame: 'frame1', data: [{'marker.size': 0}]},
+                {name: 'frame1', baseFrame: 'frame2', data: [{'marker.size': 1}]},
+                {name: 'frame2', baseFrame: 'frame0', data: [{'marker.size': 2}]}
+            ];
+
+            results = [
+                {traceIndices: [0], data: [{marker: {size: 0}}]},
+                {traceIndices: [0], data: [{marker: {size: 1}}]},
+                {traceIndices: [0], data: [{marker: {size: 2}}]}
+            ];
+
+            Plotly.addFrames(gd, frames).then(done);
+        });
+
+        function doTest(i) {
+            it('avoid infinite recursion (starting point = ' + i + ')', function() {
+                var result = computeFrame(gd, 'frame' + i);
+                expect(result).toEqual(results[i]);
+            });
+        }
+
+        for(var ii = 0; ii < 3; ii++) {
+            doTest(ii);
+        }
+    });
+
+    describe('computing trace data', function() {
+        var frames;
+
+        beforeEach(function(done) {
+            frames = [{
+                name: 'frame0',
+                data: [{'marker.size': 0}],
+                traceIndices: [2]
+            }, {
+                name: 'frame1',
+                data: [{'marker.size': 1}],
+                traceIndices: [8]
+            }, {
+                name: 'frame2',
+                data: [{'marker.size': 2}],
+                traceIndices: [2]
+            }, {
+                name: 'frame3',
+                data: [{'marker.size': 3}, {'marker.size': 4}],
+                traceIndices: [2, 8]
+            }, {
+                name: 'frame4',
+                data: [
+                    {'marker.size': 5},
+                    {'marker.size': 6},
+                    {'marker.size': 7}
+                ]
+            }];
+
+            Plotly.addFrames(gd, frames).then(done);
+        });
+
+        it('merges orthogonal traces', function() {
+            frames[0].baseFrame = frames[1].name;
+            var result = computeFrame(gd, 'frame0');
+            expect(result).toEqual({
+                traceIndices: [8, 2],
+                data: [
+                    {marker: {size: 1}},
+                    {marker: {size: 0}}
+                ]
+            });
+        });
+
+        it('merges overlapping traces', function() {
+            frames[0].baseFrame = frames[2].name;
+            var result = computeFrame(gd, 'frame0');
+            expect(result).toEqual({
+                traceIndices: [2],
+                data: [{marker: {size: 0}}]
+            });
+        });
+
+        it('merges partially overlapping traces', function() {
+            frames[0].baseFrame = frames[1].name;
+            frames[1].baseFrame = frames[2].name;
+            frames[2].baseFrame = frames[3].name;
+            var result = computeFrame(gd, 'frame0');
+            expect(result).toEqual({
+                traceIndices: [2, 8],
+                data: [
+                    {marker: {size: 0}},
+                    {marker: {size: 1}}
+                ]
+            });
+        });
+
+        it('assumes serial order without traceIndices specified', function() {
+            frames[4].baseFrame = frames[3].name;
+            var result = computeFrame(gd, 'frame4');
+            expect(result).toEqual({
+                traceIndices: [2, 8, 0, 1],
+                data: [
+                    {marker: {size: 7}},
+                    {marker: {size: 4}},
+                    {marker: {size: 5}},
+                    {marker: {size: 6}}
+                ]
+            });
+        });
+    });
+
+    describe('computing trace layout', function() {
+        var frames;
+
+        beforeEach(function(done) {
+            frames = [{
+                name: 'frame0',
+                layout: {'margin.l': 40}
+            }, {
+                name: 'frame1',
+                layout: {'margin.l': 80}
+            }];
+
+            Plotly.addFrames(gd, frames).then(done);
+        });
+
+        it('merges layouts', function() {
+            frames[0].baseFrame = frames[1].name;
+            var result = computeFrame(gd, 'frame0');
+
+            expect(result).toEqual({
+                layout: {margin: {l: 40}}
+            });
+        });
+
+    });
+});