Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/artzub/blackhole.js

Library for dinamyc visaulization such as code_swarm. Sandbox:
https://github.com/artzub/blackhole.js

Last synced: 7 months ago
JSON representation

Library for dinamyc visaulization such as code_swarm. Sandbox:

Awesome Lists containing this project

README 

          
blackHole.js

============



## Introduce



[![Blackhole.js](http://i.imgur.com/6d588zV.png)](http://codepen.io/artzub/pen/vcfyd)

![Analytics](https://ga-beacon.appspot.com/UA-28343295-16/blackhole.js/readme?pixel)

This library is child of two projects:  

* [WorldBank Contract Awards](http://d3.artzub.com/wbca/)

* [GitHub Visualizer](http://artzub.com/ghv)



The main objective of this library is the visualization of data that change over time.

Suitable for the visualization of such data as:

* Commits history ([GitHub Visualizer](http://artzub.com/ghv)) 

* Economic Indicators ([Distribution of Russian budget 2013](http://clearspending.artzub.com/), [LuckyLunch](http://works.artzub.com/luckylunch/))

* Network attacks ([NetMonitor](http://artzub.com/img/demo_netMon.gif)) 

* And etc.



Depends on [D3js](http://d3js.org)



## Structure



- [Quick Example](#qe)

- [Documentation](#api)

    - [Properties](#properties)

    - [Settings](#settings)

    - [Methods](#methods)

    - [Realtime Mode](#realtime-mode)

    - [Node object](#node-object)

        - [Parent node](#parent-node)

        - [Child node](#child-node)

    - [Category object](#category-object)

- [For developers](#fd)





## Quick Examples

  



> For fast look [Example I](http://codepen.io/artzub/pen/vcfyd)



We have data (generated by [script](http://codepen.io/artzub/pen/bIkvH.js)):



```json

[

  {

    "key": 119,

    "category": "nemo,",

    "parent": {

      "name": "cumque5",

      "key": 5

    },

    "date": "2014-01-29T15:39:45.340Z"

  },

  {

    "key": 96,

    "category": "nemo,",

    "parent": {

      "name": "cumque5",

      "key": 5

    },

    "date": "2014-01-29T19:56:18.885Z"

  },

  {

    "key": 125,

    "category": "nemo,",

    "parent": {

      "name": "cumque5",

      "key": 5

    },

    "date": "2014-01-30T01:00:53.648Z"

  },

  {

    "key": 51,

    "category": "nemo,",

    "parent": {

      "name": "eveniet1",

      "key": 1

    },

    "date": "2014-01-30T06:46:51.531Z"

  },

  {

    "key": 237,

    "category": "nemo,",

    "parent": {

      "name": "cumque5",

      "key": 5

    },

    "date": "2014-01-30T12:25:14.810Z"

  },

  //...

]

```



And code:



```html




var data = rawData.map(function(d) {

        d.date = new Date(d.date);

        return d;

    })

    , stepDate = 864e5

    , d3bh = d3.blackHole("#canvas")

    ;



d3bh.setting.drawTrack = true;



d3bh.on('calcRightBound', function(l) {

        return +l + stepDate;

    })

    .start(data)

    ;



```





## Documentation



For creation instance of the `blackHole` object, need call method of the d3js object

```javascript

var bh = d3.blackHole('#canvas');

```

__d3.blackHole(*[node]*)__  

> __node__ — or a selector, or a dom node, or a d3 node (default: `document.body`)  

> returning the blackHole object



Next describe the properties and methods of the blackHole object.



### Properties



* *bh.setting.*__version__ — the version of library

* *bh.setting.*__setting__ — object with fields of [settings](#settings)



### Settings



All fields can change dynamic.  



> For try how to work setting look this [example II](http://codepen.io/artzub/pen/pygqo)  

> also try this [dataset](https://gist.githubusercontent.com/artzub/10685338/raw/a2db0bc109ef94d3f93747c0100a4385e9eb5d4a/nodejs_history.xml)  



* #### Items

    * *bh.setting.*__alpha__ — uses for calculation cluster (default: `0.025`)

    * *bh.setting.*__childLife__ — number of ticks of life a child node (default: `255`)

    * *bh.setting.*__parentLife__ — number of ticks of life a parent node, after the death of all children (default: `255`)

    * *bh.setting.*__rateOpacity__ — rate of decrease of opacity (default: `.5`)

    * *bh.setting.*__rateFlash__ — rate of decrease of flash effect (default: `2.5`)

    * *bh.setting.*__padding__ — padding of parent (default: `25`)



* #### Behavior

    * *bh.setting.*__skipEmptyDate__ — skips empty dates (default: `true`).  

        

        > if after filtering data, an array is empty then it steps on next date.

           

    * *bh.setting.*__realtime__ — indicates that need work in mode realtime (default: `false`).

       

        > more info [realtime mode](#realtime-mode)  

        > *This parameters must be initialized before starting visualization.*  

          

    * *bh.setting.*__asyncParsing__ — parsing data in async mode (default: `false`).

      

        > If param is true, then will work method [.on('parsing')](#on_parsing)  

        > *This parameters must be initialized before starting visualization.* 

         

    * *bh.setting.*__speed__ — sets milliseconds for `setInterval` of method filtering data (default: `1000`)

        

        > *This parameters must be initialized before starting visualization.*  

        > After need use [speed](#speed) method

        

    * *bh.setting.*__increaseChildWhenCreated__ — increase children nodes when they are created (default: `false`)

    * *bh.setting.*__increaseChild__ — should children nodes increase size (default: `true`)

    * *bh.setting.*__createNearParent__ — create children nodes near they parents (default: `false`)



* #### Drawing

    * *bh.setting.*__blendingLighter__ — if true, then sets the property `compositeOperation` of canvas in the `'lighter'` value (default: `true`)

    * *bh.setting.*__drawEdge__ — drawing edges (default: `false`)

    * *bh.setting.*__drawChild__ — drawing children nodes (default: `true`)

    * *bh.setting.*__drawChildLabel__ — drawing labels of children nodes (default: `false`)

    * *bh.setting.*__drawParent__ — drawing parents nodes (default: `true`)

    * *bh.setting.*__drawParentLabel__ — drawing labels of parents nodes (default: `true`) 

    * *bh.setting.*__drawPaddingCircle__ — drawing padding circles of parents nodes (default: `false`) 

    * *bh.setting.*__drawHalo__ — drawing the halo effect of children nodes (default: `true`)

    * *bh.setting.*__drawTrack__ — drawing track of children nodes (default: `false`)

    * *bh.setting.*__drawAsPlasma__ — drawing children nodes uses plasma effect (default: `true`)

    * *bh.setting.*__drawParentImg__ — drawing images of parents nodes (default: `true`) 

    * *bh.setting.*__hasLabelMaxWidth__ — if true, then uses the `maxWidth` argument into the `fillText` method, in other words, text zooming based on the max width of canvas. (default: `true`) 



* #### Colors

    * *bh.setting.*__colorless__ — a color for bleaching (default: `rgb(128, 128, 128)`)

    * *bh.setting.*__colorlessFlash__ — a color for bleaching when using the flash effect (default: `rgb(211, 211, 211)`)

    * *bh.setting.*__parentColors__ — colors of parents nodes (default: `d3.scale.category20b()`)

    

        > it is a `d3.scale.ordinal` object, can initialised as `d3.scale.ordinal.domain(['pie', 'roll', ...]).range(['red', 'blue', ...])`  

        > [more about d3 category](https://github.com/mbostock/d3/blob/master/src/scale/category.js)

          

    * *bh.setting.*__categoryColors__ — colors of children nodes categories (default: `d3.scale.category20()`)



* #### Zoom and drag

    * *bh.setting.*__zoomAndDrag__ — enable zooming and dragging canvas (default: `true`)

    * *bh.setting.*__zoom__ — a function [d3.zoom](https://github.com/mbostock/d3/wiki/Zoom-Behavior) (default: ~~generate when start visualization~~)

    * *bh.setting.*__scaleExtent__ — scale extent for `d3.zoom` (default: `[.1, 8]`)

    

    _Following settings must be initialized before starting, after need using methods with the same names_  

    

    * *bh.setting.*__scale__ — initial `scale` for `d3.zoom` (default: `1`)

    * *bh.setting.*__translate__ — initial `translate` for `d3.zoom` (default: `[0, 0]`)



### Methods



Most of the methods returning `blackHole` object in order to use chain.



* *bh.*__[start](#start)(inData *[, width[, height[, reInitData[, callback]]]]*)__

    

    > running the dynamic visualization, also using for restart the visualization.

    >   

    > __inData__ *{Array}* — an array of source data  

    > __width__ *{Number}* — width of canvas that will be created (default: `parentNode.width`)  

    > __height__ *{Number}* — height of canvas that will be created (default: `parentNode.height`)  

    > __reInitData__ *{Boolean}* — reinitializing source data   

    > __callback__ *{Function}* — callback method. Mainly used if use start method when visualizing is ran  

    >   

    > __return__ `blackHole` object  

    

* *bh.*__[stop](#stop)()__



    > Stop a running visualization  

    > After using this method [resume](#resume) will not work, need use [start](#start)  

    > __return__ `blackHole` object  



* *bh.*__[pause](#pause)()__



    > Pause a running visualization  

    > __return__ `blackHole` object  



* *bh.*__[resume](#resume)()__



    > Resume a paused visualization  

    > __return__ `blackHole` object  



* *bh.*__[append](#append)(array)__



    > Append source data into visualization collection with using parsing.

    > __array__ {Array} — array of new source data  

    > This method is effective if [realtime](#realtime) is true, but can used anytime  

    > more info [realtime mode](#realtime-mode)  

    >   

    > __return__ `backHole` object  



* *bh.*__[IsRun](#is-run)()__



    > Returning the true if a visualization is paused or running  



* *bh.*__[IsPaused](#is-paused)()__



    > Returning the true if a visualization is paused



***



* *bh.*__[selectNode](#select-node)(*[node]*)__

    

    > Gets or sets a selected [node](#node-object).  

    > __node__ — [node](#node-object) object   

    > If called without arguments then returns the selected node,  

    > else sets the selected node and returns `blackHole` object.  

    >   

    > If set the selected node, then colors of nodes will be [colorless](#colorless),  

    > if a [category](#category-object) of a node is not equals a category of the selected node.



* *bh.*__[selectCategory](#select-category)(*[category]*)__



    > Gets or sets a selected [category](#category-object)  

    > __category__ — [category](#category-object) object  

    > If called without arguments then returns the selected category,  

    > else sets the selected node and returns `blackHole` object.  

    >   

    > If set the selected category, then colors of nodes will be [colorless](#colorless),  

    > if a category of a node is not equals the selected category.



* *bh.*__[frozenCategory](#frozen-category)(**[category]**)__



    > Gets or sets a frozen [category](#category-object)  

    > __category__ — [category](#category-object) object   

    > If called without arguments then returns the frozen category,  

    > else sets the frozen node and returns `blackHole` object.  

    >   

    > If set the frozen category, then nodes will be hidden,  

    > if a category of a node is not equals the frozen category.



***



* *bh.*__[parents](#parents)(*[arg]*)__



    > Gets or sets [d3_Map](https://github.com/mbostock/d3/wiki/Arrays#d3_map) object of [parents nodes](#parent-node)  

    > __arg__ — must be or hash object,  or `d3_Map` object where a key is a key field of a parent node  

    >   

    > If called without arguments then returns the `d3_Map` object of patents nodes  

    > else sets patents nodes and returns `blackHole` object. 

    

* *bh.*__[children](#children)(*[arg]*)__



    > Gets or sets [d3_Map](https://github.com/mbostock/d3/wiki/Arrays#d3_map) object of [children nodes](#child-node)  

    > __arg__ — must be or hash object,  or `d3_Map` object where a key is a key field of a child node  

    >   

    > If called without arguments then returns the `d3_Map` object of children nodes  

    > else sets children nodes and returns `blackHole` object.  



* *bh.*__[categories](#categories)(*[arg]*)__



    > Gets or sets [d3_Map](https://github.com/mbostock/d3/wiki/Arrays#d3_map) object of [categories](#category-object)  

    > __arg__ — must be or hash object, or `d3_Map` object where a key is a key field of a category  

    >   

    > If called without arguments then returns the `d3_Map` object of categories  

    > else sets categories and returns `blackHole` object.  



***



* *bh.*__[sort](#sort)(*[func]*)__



    > Gets or sets a sort function for source data  

    > __func__ *{Function}* — `function(a, b) {}`, `a` and `b` are two source nodes value ([default function](src/core.js#L211))  

    >   

    > If called without arguments then returns a sort function  

    > else sets a sort function and returns `blackHole` object.



* *bh.*__[filter](#filter)(*[func]*)__

    

    > Gets or sets a filter function for source data  

    > __func__ *{Function}* — `function(l, r) {}`, `l` and `r` are the left and the right bounds of filtering ([default function](src/core.js#L223))  

    >   

    > If called without arguments then returns a filter function  

    > else sets a filter function and returns `blackHole` object.



***



* *bh.*__[speed](#speed)(*[milliseconds]*)__



    > Gets or sets a [speed](#setting-speed) of visualization on milliseconds  

    > __milliseconds__ {Number}  

    > If called without arguments then returns current speed  

    > else sets a speed and returns `blackHole` object.



* *bh.*__[size](#size)(*[array]*)__



    > Gets and sets a size for canvas  

    > __array__ {Array} — `[w, h]` the new size of canvas  

    > This method used for resizing canvas  

    >   

    > If called without arguments then returns current size  

    > else sets a size and returns `blackHole` object.   



* *bh.*__[style](#style)(name *[, value[, priority]]*)__



    > Wrapper for [d3.style](https://github.com/mbostock/d3/wiki/Selections#style) but apply only the main canvas node.



* *bh.*__[scale](#scale)(*[scale]*)__



    > Gets and sets a scale for [d3.zoom](https://github.com/mbostock/d3/wiki/Zoom-Behavior)  

    > __scale__ {Number}  

    >   

    > If called without arguments then returns current scale  

    > else sets a scale and returns `blackHole` object.



* *bh.*__[translate](#translate)(*[array]*)__



    > Gets and sets a translate for [d3.zoom](https://github.com/mbostock/d3/wiki/Zoom-Behavior)  

    > __array__ {Array} — `[x, y]` the coordinate of point for translate  

    >   

    > If called without arguments then returns current translate  

    > else sets a translate and returns `blackHole` object.  



* *bh.*__[getCanvas](#get-canvas)()__



    > Returns the main canvas or null, if the visualization is not running.



***



> [Complex example using maps](http://codepen.io/artzub/pen/molHj)



* *bh.*__[on](#on)(key *[, value]*)__  



    > ***key*** — a string value form __keys__  

    > ***value*** — a function  



    * *__Action signals__*  

    

    |  key  | value | description |

    | ----- | ----- | ----------- |

    | __[calcRightBound](#on-calc-right-bound)__ | `function(`__leftBound__`)` |  |  

    | __[getChildLabel](#on-get-child-label)__ | `function(`__sourceItem__`)` |  |

    | __[getParentLabel](#on-get-parent-label)__ | `function(`__parentNodeItem__`)` |  |

    | __[getSelectedColor](#on-get-selected-color)__ | `function(`__nodeItem__`)` |  |

    | __[getVisibleByStep](#on-get-visible-by-step)__ | `function(`__nodeItem__`)` |  |

    | __[getCreateNearParent](#on-get-create-near-parent)__ | `function(`__sourceItem, nodeItem__`)` |  |

    | __[getCategoryKey](#on-get-category-key)__ | `function(`__sourceItem__`)` |  |

    | __[getCategoryName](#on-get-category-name)__ | `function(`__sourceItem__`)` |  |

    | __[getChildKey](#on-get-child-key)__ | `function(`__sourceItem__`)` |  |

    | __[getParent](#on-get-parent)__ | `function(`__sourceItem__`)` |  |

    | __[getParentKey](#on-get-parent-key)__ | `function(`__sourceParentItem__`)` |  |

    | __[getParentImage](#on-get-parent-image)__ | `function(`__sourceParentItem__`)` |  |

    | __[getGroupBy](#on-get-group-by)__ | `function(`__sourceItem__`)` |  |

    | __[getValue](#on-get-value)__ | `function(`__sourceItem__`)` |  |

    | __[getParentRadius](#on-get-parent-radius)__ | `function(`__parentNodeItem__`)` |  |

    | __[getChildRadius](#on-get-child-radius)__ | `function(`__nodeItem__`)` |  |

    | __[getParentPosition](#on-get-parent-position)__ | `function(`__sourceParentItem__`)` |  |

    | __[getParentFixed](#on-get-parent-fixed)__ | `function(`__sourceParentItem__`)` |  |



    * *__Event signals__*  

    

    |  key  | value | description |

    | ----- | ----- | ----------- |

    | __[beforeParsing](#on-before-parsing)__ | `function(`__sourceData__`)` |  |

    | __[parsing](#on-parsing)__ | `function(`__nodeItem__`)` |  |

    | __[afterParsing](#on-after-parsing)__ | `function(`__nodesCollection__`)` |  |

    | __[processing](#on-processing)__ | `function(`__currentItems, leftBound, rightBound__`)` |  |

    | __[processed](#on-processed)__ | `function(`__currentItems, leftBound, rightBound__`)` |  |

    | __[stopped](#on-stopped)__ | `function()` |  |

    | __[finished](#on-finished)__ | `function(`__leftBound, rightBound__`)` |  |

    | __[starting](#on-starting)__ | `function()` |  |

    | __[started](#on-started)__ | `function()` |  |

    | __[mouseOverNode](#on-mouse-over-node)__ | `function(`__nodeItem, d3event__`)` |  |

    | __[mouseMove](#on-mouse-move)__ | `function(`__nodeItem, d3event__`)` |  |

    | __[mouseOutNode](#on-mouse-out-node)__ | `function(`__nodeItem, d3event__`)` |  |

    | __[particleAtTarget](#particleattarget)__ | `function(`__nodeItem, parentNodeItem__`)` |  |

    

### Realtime Mode



*bh.setting.*__realtime__

*bh.*__append(array)__



### Node object

#### Parent node

#### Child node

### Category object





## For developers



If you want to modify `blackHole.js`, click the "Fork" button in the top-right corner of this page, and then clone your fork from the command line by replacing username with your GitHub username:

```bash

git clone git://github.com/username/blackhole.js.git

```

On the other hand, if you want to extend blackHole with new features, fix bugs, or run tests, you should fork the blackHole repository, and install Node.js (version 0.10.x or higher). From the root directory of this repository, you can then install blackHole's dependencies:

```bash

npm install

```

For make:

```bash

make full

```