Overview Examples Documentation Learning Source Contact / Feedback

Visual Sedimentation

Download the beta:

Reseach Project:

This library is part of AVIZ INRIA and IRI research project. We value any comment and suggestion. So please visit our Google Group. We also need your feedback, please take a couple of minute to fill out our questionnaire.

If you want to know more about the design space behind Visual Sedimentation, also read the following paper:

"Towards Visual Sedimentation" Samuel Huron, Romain Vuillemot, Jean-Daniel Fekete, Poster at IEEE Infovis, 2012

title={Towards Visual Sedimentation},
author={Huron, S. and Vuillemot, R. and Fekete, J.D. and others},
journal={VisWeek 2012 Electronic Conference Proceedings (2012)},



The current version of Visual Sedimentation generates three types of classic visualizations: bar chart, pie char and bubble chart. In a future version, it will support the generation of any chart.

Visual Sedimentation is best used for continuously updated data (data streams). Therefore the overall process of running a visualization is a follows:

  1. New data enter the charts under the state of token (similar as particles)
  2. The token is processed by the physical engine and decay over time
  3. Finally the token flocculates (i.e. it disappears) and the chart is updated accordingly

Data streams can be Tweets, SVN commits, RSS feeds, Email, etc. They can either be coming live, or generated from the dump of timestamped data. Data can also be a ratio that is reflected by the tokens flow density.

# Hello World

Hello World is a minimal example to show the library in action. It uses pre-recorded parameters that will be explained later. To generate this visualization, add the following in the header of the HTML document:

<script type="text/javascript" src="visualsedimentation.js">
In the body, create a div myDemo that will contain the visualization. Then initialize the library and start the rendering with the vs() function as follows:

<div id="myDemo">Hello World container</div>
  var scene =  $("#myDemo").vs().data('visualSedimentation');

# Streaming Data Generator

The library includes a data stream generator that will generate tokens at a refresh. This generator provides synthetic data mostly for testing the visualization, we'll see later that tokens can be added individually.

mySettings = {
    provider:"tokens", // token / generator 
    refresh:1000,	  // delay to execute the function
    now:0 			  // time of the visualization, is increasing by one each refresh time

# Settings

To pick up and customize the chart, a parameter object mySettings can be created and added to the library. Below is an overview of the structure of such a setting element. Look at the examples is the best way to see the possibilities (not all documented, yet).

mySettings = {
  // view port width and height 

  // chart position x,y, width and height
    x:500,      // chart.x on the schema
    y:206,      // chart.y on the schema
    width:300,  // chart.width on the schema
    height:400  // chart.width on the schema

The following diagram indicates the position parameters of the chart. For the margin convention of the visualization part itself, see d3.js margin conventions.

Look at the source code of the following example for more details and see what can be done with the viewport.

# Chart configuration

Among the many parameters, the most important one is the chart.type that defines which chart is picked up and its properties. The choice of charts are the following:

# Bar Chart

The following configuration creates a simple bar chart with three bars (as in the default example):


# Pie Chart

Pie chart type is CircleLayout.


# Bubble Chart

Bubble chart type is also CircleLayout with the addition of treeLayout = true to create it.

 treeLayout = true
 spacer     = 1000      // space between two bubbles
 column     = 3         // the number of column for the positon setup

# Generative Chart (Experimental features)

You can also create the following cool examples: heap chart, sylo chart, line chart, piechart without bounderies.

To do so, the chart layout is setup by a function in the file _vs.chart.[type_name].js, you could make your own file if you want a custom physical and visual layout.

This file is defined by three functions:

				// - CircleLayout,
				// - StackedAreaChart,

# Tokens

A token is the minimal unit of represented data, according to the data flow type it's could be one tweet, one article entry, or a mail or others. Tokens have several attributes :

# Attributes

To customize a token, use the following parameters (defaults are in _vs.token.js):

	category:0,             // Corresponding to the datamodel (wich column in the data set)
	x:50,					// Incoming positions of token, if not define use incomming point of the category
	y:50,              		// same than previous
	t:1360164350473,		// timestamp, if not define use now time by default 

	size:10,                // Size (diameter) of the token 
	fillStyle:'#000000',    // FillStyle as an HTML5 canvas Property
	strokeStyle:'#000000',  // StrokeStyle as an HTML5 canvas Property
	lineWidth:0,            // LineWidth as an HTML5 canvas Property
	texture:{src:"URL"},    // Texture     
	shape:'round',          // Not implemented yet
	timestamp:null,         // Not implemented yet
	userdata:{},            // Add some personal information 
	callback:{},            // Interactions callbacks 
   	texture:{				// image fill in the token (only url are allowed)

	phy:{					// physical parameters
    	angle:95,			// angle 
    	power:10,			// throw force
	targets:[ 				// Not implemented yet 
	elbow:{					// Not implemented yet	 

# Adding Tokens

In the previous examples, the tokens were added automatically. To manually add tokens, the following function is to be used:

   size:30,				   // size of your token 
   category:1,			   // category of your token
   t:1360164350473 // milliseconde number form 1970 first january (Date.getTime())

Below with the d3.js style:

	.attr("x", d3.select("#data1").attr("x"))
	.attr("y", d3.select("#data1").attr("y"))
	.attr("radius", 10)
	.attr("texture", "img/twitter_face.jpg")      
	.attr("strokeStyle", "red")

See this example for a roundup of all parameters.

# Incoming Point

Incoming points are location from which the tokens enter the scene and the physical forces start to be applied on it.

They can be customized separately, for each of the dimensions (e.g. for each bar of the chart):


#Callback for token

Callbacks are triggered depending on the state of the token. Six sates/callback are available:

Some callback exemples are available here. Below is the configuration file of a token that contains the callbacks:

"model":[{label:"Column A"}],
   value: 1,

# Selecting tokens

To select one or multiple tokens, a selector function is provided:

  var myToken = barChart.select('key','value');

Examples are available here for: select a group , or everything selectAll.

# Easy customization

You can easily customize every single token.

  .attr("radius", 10)
  .attr("texture", "img/twitter_face.jpg")      
  .attr("strokeStyle", "red")

#Decay Function

The decay function is in charge of shrinking tokens over time. It is null by default. It can be setup at the initialization of the chart in the settings:


The decay function could also be change with the globalDecay():

  .globalDecay()    // to get the decay power (return a float or null)
  .globalDecay(1.09)// to setup the decay function at 1.09
  .globalDecay(null)   // no decay


Flocculation is when a token disappears to be part of the aggregated area or just to be removed. The function remove the physical body representing the object.

Flocculation function is triggered once a token reaches token.size.minimum size. It can also be manully triggered with the flocculate() function applied to a set of tokens.


  tokens = chart.selectAll("category",1) //select all token from category 1

As a further example, sediClock flocculates tokens every minutes (each token representing a second).


Strata compress aggregated data into a finite set of layers. Each layer represents a temporal interval. For instance, it can be the count of data during the last 30 seconds or last 5 minutes. Therefore the strata value is usually a function rather a fixed number.

		{value: 10, 
		 text: "first strata", 
		 texture: {url:"../..", size:1}, 
		 color: ..
	], [

The text, textures and color are settings for each strata. Texture images are any image file provided as a url to be mapped to each layer as a tile, and scale according to the size factor.

Fork me on GitHub