Overview

Canis is a high-level grammar for animations. It provides an easy-understanding JSON syntax, and generates multi-view animations of the given visualization charts to support storytelling or analysis. Canis can describe and create animations in a declarative format. To use Canis, our compiler compiles the specification into a corresponding relation between time and visual attributes of the graphical marks in charts. Then it generates Lottie JSON file to enable rendering natively on iOS, Windows, and Web.

This document describes the syntax of Canis and how to use it in web applications.

Canis

Canis specification is a JSON object that describes a diverse range of animations of the given visualization charts.

The specification has three parameters:

                    
//Top-level View Specification
{
    "charts" : [...],
    "facet" : ...,
    "animations" : [...]
}
                

Chart-Level Spec

Specificaitons that describe the sources, grouping according to facet views, and animations of the input visualization charts.

Chart Object

A chart object describes one input visualization chart used to generate animations.

For example, import a line chart.

                    
{
    "source" : "./lineChart.dsvg"
}
                

A chart object can contain the following properties:

For example, we can pick an id for the chart (form lineChart0.dsvg to lineChart10.dsvg).

                    
{
    "id" : "lineChart",
    "source" : "./lineChart.dsvg" 
}
                

Or, we can import a series of charts.

                    
{
    "source" : "./lineChart",
    "start" : 0,
    "end" : 10
}
                

                    
//Top-level View Specification
{
    "charts" : [
        {...},
        ...
    ],
    ...
}
                

Facet Object

The facet object facets views for multi-view animation. We can then specify charts for each view to generate animations.

                        
{
    "charts" : [
        {
            "id" : "lineChart1",
            "source" : "./lineChart1.dsvg"
        },
        {
            "id" : "lineChart2",
            "source" : "./lineChart2.dsvg"
        }
    ],
    "facet" : {
        "type" : "column",
        "views" : [
            {"frames": ["lineChart1"]}, 
            {"frames":["lineChart2"]}
        ]
    },
    ...
}
                        
                    

A facet object can contain the following properties:

                    
//Top-level View Specification
{
    "charts" : [...],
    "facet" : {...},
    ...
}
                

Animation Object

An Animation object describes the animations of charts. It selects marks from the chart by selection, animations described by this animation object will be bind to those marks. grouping decides the minimum unit during animaiton (marks that animate together), and their timing relations. And actions specify animation parameters like type of animation, duration of the animation of each unit, and so on.

                    
//Top-level View Specification
{
    "charts" : [...],
    "facet" : {...},
    "animations" : [
        {...},
        ...
    ]
}
                

Mark-Level Spec

These are the parameters of the animation object.

Selection

Borrowing form CSS 1-3, Canis provides a set of tools for matching marks in given charts. The W3C CSS specification contains the complete set of rules regarding valid CSS selectors.

                    
{
"selection" : ".dot",//select marks with the class name as "dot".
...
}
                

Here we list some of the commonly used selectors:

• Class Selector (".class")

  Select all marks which have the given class name.

• ID Selector ("#id")

  Select the mark the given id.

• All Selector ("*")

  Select all the marks.

• Element Selector ("tag")

  Select all marks which have the given tag name.

• Attribute Equals Selector ([name="value"])

  Select all marks whose values of the given attribute are equal to a certain given value.

• Multiple Selector ("selector1, selector2, selectorN")

  Select all marks with all the specified selectors.

Grouping Object

A grouping object groups the selected marks by attributes of the data they encoded in a hierarchical manner. Each group is a minimum animation unit, and marks within the same unit will be animated together. The timing relationships between units like animation order, delay are also specified.

                        
{
    "selection" : ".dot",//all marks are selected.
    //the following code groups dots into cells as shown in the figure.
    "grouping" : {
        "groupBy" : "Odor",//all dots will be grouped into columns.
        "reference" : "previousEnd",//animate column after column.
        "grouping" : {
            "groupBy" : "Surface",//dots in each column are further grouped into rows.
            "reference" : "previousEnd",//animate row after row.
        }
    },
    ...
}
                        
                    

A grouping object can contain the following parameters:

                    
//Top-level View Specification
{
    "charts" : [...],
    "facet" : {...},
    "animations" : [
        {
            "selection" : ...,
            "grouping" : {...},
            ...
        },
        ...
    ]
}
                

Sort Object

A sort object specifies the animation order of the mark groups.

                    
//groups will be animated with their value of "attr" in ascending order
{
    "field" : "attr",
    "order" : "ascending"
}
                

A sort object can contian the following parameters:

Action Object

An animation can have multiple actions. For example the marks can wipe in from bottom while they wipe in from left. An action object describe parameters of one action, including type, easing, duration, order, and timing offset of the action.

                    
{
    "type" : "fade",
    "easing" : "easeOutBounce",
    "duration" : 1000//ms
}
                

An action can contain the following parameters:

For example we can animate marks with the same duration:

                        
    {
        "selection" : ".Shape2",
        "actions" : [
            {
                "type" : "wipe bottom",
                "duration" : 1000
            }
        ]
    }
                    

Or we can control the animation speed by defining the minimum duration time with duration object:

                        
    {
        "selection" : ".Shape2",
        "actions" : [
            {
                "type" : "wipe bottom",
                "duration" : {
                    "field" : "percentage",
                    "minDuration" : 300
                }
            }
        ]
    }
                    

                    
//Top-level View Specification
{
    "charts" : [...],
    "facet" : {...},
    "animations" : [
        {
            "selection" : ...,
            "grouping" : {...},
            "actions" : [
                {...},
                ...
            ]
        },
        ...
    ]
}
                

Offset Object

An offset object defines the offset time of marks according to the values of one of their data attributes.

For example, marks selected have a data attribute called "attr" with its values ranging from 10 to 100, we define the minimum offset time as 200ms, then the offset time of the mark whose "attr" value is 10 will be 200ms, and the one whose "attr" value is 100 will be 2,000ms. The example code is shown below:

                    
{
    "field" : "attr",
    "minOffset" : 200
}
                

An offset object can contian the following parameters:

Duration Object

A duration object defines the duration time of marks according to the values of one of their data attributes.

For example, marks selected have a data attribute called "attr" with its values ranging from 10 to 100, we define the minimum duration as 200ms, then the duration of the mark whose "attr" value is 10 will be 200ms, and the one whose "attr" value is 100 will be 2,000ms. The example code is shown below:

                    
{
    "field" : "attr",
    "minDuration" : 200
}
                

A duration object can contian the following parameters:

Attribute Object

An attribute object picks one of the visual parameters and defines the start and end value of this parameter using percentages.

                    
{
    "attrName" : "attr",
    "from" : 0,
    "to" : 1
}
                

An attribute object can contian the following parameters:

Web Application

We can use the following snippet to link to the latest release:

                    
<script src="http://www.njvis.net/CanisWeb/anichart.min.js"></script>"
                

We can create an animated visualization on the web page using the following code:

                    
<div id='chartContainer'></div>
<div id='videoContainer'></div>
<script>
    aniChart.loadSpec('./specs/line2.ac', (spec) => {
        aniChart.renderSpec(spec);
        aniChart.play();
    })
</script>
                

Canis provides the following variables and functions to create or customize animations.

aniChart.loadSpec()

This function fetches the AC format spec file at the specified input URL and returns the spec as a JSON object.

                    
aniChart.loadSpec('./spec.ac', (spec) => {
    console.log(spec);
})
                

aniChart.renderSpec(spec)

This function renders the animation using the input spec.

aniChart.play()

Call this function to play the rendered animation.

The following functions and variables can be used to create a customized animation player:

aniChart.frameRate

This is the frame rate of the animation.

                    
console.log(aniChart.frameRate);//25
                

aniChart.duration()

This is the duration time of the entire animation.

                    
console.log(aniChart.duration());//1000
                

aniChart.renderFrame(time)

This returns the visual effects of all the marks at a specific time point.

                    
aniChart.renderFrame(300);//render the frame at 300ms
                

aniChart.reset()

Reset all status.