viz-core
Description
viz-core is a collection of Vue components and composables that allow to visualise and handle networks.
Demo of viz-core and its plugins
Features
- Read files in json Graph format
- Zoom
- Drag & Drop
- Undo & Redo
- Style managing
- Random graph creation
Getting started
Create a vue 3 project
First, you need to initialize a project. The simplest way is to create a Vue project to stay within the same environment as viz-core. To initialize your project, you can follow the instructions on the following page: Vue 3 tutorial.
We try to be up to date with the last versions of Vue. If you face to bugs with viz-core, please check that the version of Vue3 that you use and the version that is used in viz-core are compatible.
Css styles
Ensure that your project does not contain any default styles (CSS). Since viz-core operates through SVG tags, incorrectly configuring the default style of your page could result in truncated or even non-functional SVGs.
Install via npm
The viz-core package is currently only available on the MetaboHUB forge. To install it, you need to configure an .npmrc file to specify the retrieval path.
@metabohub:registry=https://forgemia.inra.fr/api/v4/packages/npm/
Then you can install the package:
npm install @metabohub/viz-core
Typescript configuration
Once the installation step is completed, you need to declare the module. To do this, add the following line in the env.d.ts file:
declare module "@metabohub/viz-core";
Usage
Javascript usage
<script setup lang="js">
import { NetworkComponent } from "@metabohub/viz-core";
import { ref } from "vue";
const nodes = {
A: {
id: 'A',
x: 50,
y: 50
},
B: {
id: 'B',
x: 100,
y: 100
}
}
const links = [
{
source: nodes.A,
target: nodes.B,
id: ''
}
]
const network = ref({ id: 'test', nodes: nodes, links: links });
const networkStyle = ref({ nodeStyles: {}, linkStyles: {} });
</script>
<template>
<NetworkComponent :network="network" :graphStyleProperties="networkStyle">
</NetworkComponent>
<br />
</template>
<style>
@import "@metabohub/viz-core/dist/style.css";
</style>
Typescript usage
<script setup lang="ts">
import type { Network } from "@metabohub/viz-core/src/types/Network";
import type { GraphStyleProperties } from "@metabohub/viz-core/src/types/GraphStyleProperties";
import { NetworkComponent } from "@metabohub/viz-core";
import { ref } from "vue";
const nodes = {
A: {
id: 'A',
x: 50,
y: 50
},
B: {
id: 'B',
x: 100,
y: 100
}
}
const links = [
{
source: nodes.A,
target: nodes.B,
id: ''
}
]
const network = ref<Network>({ id: 'test', nodes: nodes, links: links });
const networkStyle = ref<GraphStyleProperties>({ nodeStyles: {}, linkStyles: {} });
</script>
<template>
<NetworkComponent :network="network" :graphStyleProperties="networkStyle">
</NetworkComponent>
</template>
<style>
@import "@metabohub/viz-core/dist/style.css";
</style>
Import a json graph
Viz-core is compatible with the json-graph format.
Example:
{
"graph": {
"id": "example",
"nodes": {
"A": {
"id": "A",
"label": "Node A",
"metadata": {
"position": {
"x": 50,
"y": 50
}
}
},
"B": {
"id": "B",
"label": "Node B",
"metadata": {
"position": {
"x": 100,
"y": 100
}
}
}
},
"edges": [
{
"id": "AB",
"source": "A",
"target": "B",
"label": "Edge AB"
}
]
}
}
Use the importNetworkFromUrl method to import a json graph.
import { importNetworkFromURL } from "@metabohub/viz-core";
const network = ref<Network>();
cont networkStyle = ref<GraphStyleProperties>();
importNetworkFromURL('/example.json', network, networkStyle);
Navigation
By default, the network can be zoomed and moved.
- Zoom with the wheel of the mouse and move the whole network by
- Hold down the left mouse button and move the mouse to move the network.
Layout
Fixed layout
Node positions are those indicated in the Node objects by the values x and y, or 0 if no position is indicated.
Move nodes
You can move a node by holding down the left mouse button on a node and moving the mouse.
Style management
The style is managed via the graphStyleProperties props. To apply a style on a node or a link, the "class" attribute must be filled.
Example:
const nodes = {
A: {
id: 'A',
x: 50,
y: 50,
classes: ['classNode1']
},
B: {
id: 'B',
x: 100,
y: 100,
classes: ['classNode2']
}
}
const links = [
{
source: nodes.A,
target: nodes.B,
id: '',
class: ['classLink1']
}
]
Then, you define the style of each class in the a graphStyleProperties object:
const networkStyle = ref({
nodeStyles: {
classNode1: {
fill: 'red',
stroke: 'gray',
strokeWidth: 2,
}, classNode2: {
fill: 'blue',
stroke: 'purple',
strokeWidth: 4,
shape: 'circle',
width: 20,
height: 20
}
},
linkStyles: {
classLink1: {
stroke: 'red',
strokeWidth: 2
}, class2: {
stroke: 'blue',
strokeWidth: 2,
opacity: 0.5
}
}
});
const network = ref({ id: 'test', nodes: nodes, links: links });
In json graph format :
{
"graph": {
"id": "example",
"metadata": {
"style": {
"nodeStyles": {
"classNode1": {
"fill": "red",
"stroke": "gray",
"strokeWidth": 2
},
"classNode2": {
"fill": "blue",
"stroke": "purple",
"strokeWidth": 4,
"shape": "circle",
"width": 20,
"height": 20
}
},
"linkStyles": {
"classLink1": {
"stroke": "red",
"strokeWidth": 2
},
"classLink2": {
"stroke": "blue",
"strokeWidth": 2,
"opacity": 0.5
}
}
}
},
Undo & Redo
Undo and redo can be applied on the whole network:
const { undo, redo } = createUndoFunction(network);
If you want to store only the 10 last actions :
const { undo, redo } = createUndoFunction(network, 10);
Call the undo method will restore the network value to its previous value.
However, when you move a node, the undo is often too sensitive : we often want that the last position corresponds to the start of the drag.
To do this :
In the script:
const { undo, redo, pause, commit, resume } = createUndoFunction(network);
const onDragStart = () => {
pause();
}
const onDragEnd = () => {
resume();
commit();
}
In the template:
<NetworkComponent
:network="network"
:graphStyleProperties="networkStyle"
@dragStart="onDragStart"
@dragEnd="onDragEnd"
>
</NetworkComponent>
Props
NetworkComponent
Props | Type | default | Description | Optional |
---|---|---|---|---|
network | Network | {} | Network object that contains nodes and links of the network | No |
graphStyleProperties | GraphStyleProperties | {} | Network style object taht contains classes and style associated with of nodes and links | Yes |
hideAllNodes | Boolean | false | If true, hide all nodes | Yes |
hideAllLinks | Boolean | false | If true, hide all links | Yes |
A <slot />
tag is also available in the component. This tag allows you to add other components containing SVGs, which will be directly handled by the network's SVG tag, enabling you to add elements directly to the graph.
<template>
<NetworkComponent
:network="network"
:graphStyleProperties="networkStyle"
>
<yourComponent />
</NetworkComponent>
</template>
Types
Network
Attribut | Type | Description |
---|---|---|
id | string | Network's id |
label | string | Network's label |
nodes | {[key: string] Node} | Object that contains nodes |
links | Array | List that contains links |
type | string | Network type (metabolic, proteomic, knowledge, ...) |
rescale | boolean | Allows you to implement an automatic rescale |
Node
Attribut | Type | Description |
---|---|---|
id | string | Node's id |
label | string | Node's label |
x | number | X node's position |
y | number | Y node's position |
classes | Array | Node's classes to manage style |
hidden | boolean | Allows you to display or not the node |
metadata | {[key: string]: string | number |
Link
Attribut | Type | Description |
---|---|---|
id | string | Link's id |
label | string | Link's label |
source | Node | Source node of the link |
target | Node | Target node of the link |
type | string | Link's type |
classes | Array | Link's classes to manage style |
relation | string | Link's relation |
directed | boolean | Allows you to choose if the link is directed or not |
metadata | {[key: string]: string | number |
GraphStyleProperties
Attribut | Type | Description |
---|---|---|
nodeStyles | { [key: string]: NodeStyle } | Object that contains nodes classes name associated to their style |
linkStyles | { [key: string]: LinkStyle } | Object that contains links classes name associated to their style |
curveLine | boolean | Allows you to choose if links are curve or not |
directed | boolean | Allows you to choose if links are directed or not |
NodeStyle
Attribut | Type | Description |
---|---|---|
height | number | Node's height |
width | number | Node's width |
fill | string | Node's color |
strokeWidth | number | Node's border width |
stroke | string | Node's border color |
displayLabel | boolean | Allows you to display or not nodes label |
labelPosition | string | Where to display the label compared to the node (middle (default), top or bottom) |
label | string | Allows you to choose which node's attribut is display as label (id or label) |
shape | string | Node's shape (rectangle, circle, diamond, triangle, inverseTriangle, imageRect or imageCircle) |
opacity | number | Node's opacity (between 0 and 1) |
If the shape is an image, you need to add the image file path in the nodes metadata (metadata.image: string
).
LinkStyle
Attribut | Type | Description |
---|---|---|
display | boolean | Allows you to display or not links |
stroke | string | Link's color |
strokeWidth | number | Link's width |
opacity | number | Link's opacity (between 0 and 1) |
ForceParams
Attribut | Type | Description |
---|---|---|
charge | ForceChargeParams | Manage charge parameters for d3.forceSimulation |
collide | ForceCollideParams | Manage collide parameters for d3.forceSimulation |
gravity | ForceGravityParams | Manage gravity parameters for d3.forceSimulation |
link | ForceLinkParams | Manage link parameters for d3.forceSimulation |
ForceChargeParams
Attribut | Type | Description |
---|---|---|
strength | number | Force applies mutually amongst all nodes |
min | number | Minimal distance between two nodes |
max | number | Maximal distance between two nodes |
ForceCollideParams
Attribut | Type | Description |
---|---|---|
strength | number | Force to prevent nodes overlapping |
radius | number | Radius apply to nodes |
iteration | number | Number of iterations per application |
ForceGravityParams
Attribut | Type | Description |
---|---|---|
strength | number | Force applies on nodes to force them to be attract by the center |
ForceLinkParams
Attribut | Type | Description |
---|---|---|
distance | number | Sets the distance accessor to the specified number or function, re-evaluates the distance accessor for each link, and returns this force |
iteration | number | Sets the number of iterations per application to the specified number and returns this force |
Events
NetworkComponent
Name | Trigger | Output |
---|---|---|
nodeLeftClickEvent | left click on node | Event: MouseEvent, node: Node |
nodeRightClickEvent | right click on node | Event: MouseEvent, node: Node |
mouseOverNode | Mouse over a node | Event: MouseEvent, node: Node |
mouseLeaveNode | Mouse leave a node | Event: MouseEvent, node: Node |
dragStart | Start dragging a node | Void |
dragEnd | Stop dragging a node | Void |
Composables
CreateRandomGraph
Name | Arguments | Description | Output |
---|---|---|---|
useRandomNetwork | numNodes: number, numLinks: number | Create a random graph that contains number of nodes and links define in arguments | Network |
ReadJsonGraph
Name | Arguments | Description | Output |
---|---|---|---|
readJsonGraph | jsonGraph: string | Read graph data and return network and styles object | { network: Network, networkStyle: GraphStyleProperties } |
UseCreateForceLayout
Name | Arguments | Description | Output |
---|---|---|---|
createStaticForceLayout | network: Network, autoRescale: Boolean = false | Take a network and apply a d3 force layout algorithm on WITHOUT simulation | Promise |
createForceLayout | network: Network, autoRescale: Boolean = false | Take a network and apply a d3 force layout algorithm on WITH simulation | Network |
addNewParams | param: ForceParams | Add new parameters for d3.force layout | void |
applyParamsToForceLayout | network: Network, callBack: Function = () => {} | If new parameters have been add, apply this parameters to d3.force layout and restart simulation | void |
UseGraphManager
Name | Arguments | Description | Output |
---|---|---|---|
switchGraphMode | mode: boolean | Change a boolean to switch between two modes. For example between selection and zoom for graph panel | boolean |
nodeSelection | node: Node | Select or unselect a node | void |
defineBrush | network: Network, styles: {[key: string]: NodeStyle} | Define brush tag and functions to select multiple nodes at ctrl + left click | void |
stopBrush | X | Remove brush tag and functions | void |
switchCursor | style: string | Change cursor style for brush. Allow to switch between default (panzoom) and crosshair (brush) | void |
verticalNodesAlign | network: Network, styles: {[key: string]: NodeStyle} | Align vertically selected nodes (in list) | void |
horizontalNodesAlign | network: Network, styles: {[key: string]: NodeStyle} | Align horizontally selected nodes (in list) | void |
unselectAll | network: Network | Unselect all selected nodes | void |
UseImportNetwork
Name | Arguments | Description | Output |
---|---|---|---|
importNetworkFromURL | url: string, network: Ref, networkStyle: Ref, callbackFunction = () => {} | Import network at JSONGraph format from an URL | void |
importNetworkFromFile | file: File, network: Ref, networkStyle: Ref, callbackFunction = () => {} | Import network at JSONGraph format from a file | void |
UseManageNetworkData
Name | Arguments | Description | Output |
---|---|---|---|
checkNodesPosition | network: Network, threshold: number | Check if nodes of network have pos set to 0, 0. And returns a boolean according to a percentage threshold | boolean |
removeNode | nodeId: string, network: Network, rIsoNode: boolean = false | Remove specific node from network object | void |
removeAllSelectedNodes | network: Network, rIsoNode: boolean = false | Remove nodes from network object which have selected attribut at true | void |
duplicateNode | nodeId: string, network: Network, networkStyle: GraphStyleProperties | Duplicate specific node in network object | void |
removeIsolatedNodes | network: Network | Remove all nodes that are not connected with any other node | void |
removeAllNodesByAttribut | network: Network, attribut: string, rIsoNode: boolean = false | Remove all nodes according to a specific metadata attribut | void |
duplicateAllNodesByAttribut | network: Network, networkStyle: GraphStyleProperties, attribut: string | Duplicate all nodes according to a specific metadata attribut | void |
switchLineStyle | networkStyle: GraphStyleProperties | Switch between line path and curve path | void |
UseSaveNetwork
Name | Arguments | Description | Output |
---|---|---|---|
saveNetworkAsJSON | network: Network, networkStyle: GraphStyleProperties | Download JSONGraph of current visualisation for future use | void |
UseStyleManager
Name | Arguments | Description | Output |
---|---|---|---|
addLinkStyle | link: Link, linkStyle: LinkStyle, styleName: string, networkStyle: GraphStyleProperties | Apply specific style to one link | void |
removeLinkStyle | link: Link, styleName: string | Remove specific style to one link | void |
addNodeStyle | node: Node, nodeStyle: NodeStyle, styleName: string, networkStyle: GraphStyleProperties | Apply specific style to one node | void |
removeNodeStyle | node: Node, styleName: string | Remove specific style to one node | void |
nodeBorderColorByAttribut | network: Network, networkStyle: GraphStyleProperties, attribut: string | Color node border according to a metadata attribut. Must be a string | void |
updateClassStyle | networkStyle: GraphStyleProperties, className: string, styleObject: NodeStyle or LinkStyle, targetObject: string | Update style for a specific class | void |
createClassStyle | network: Network, networkStyle: GraphStyleProperties, className: string, styleObject: NodeStyle or LinkStyle, targetObject: string, listTarget: Array | Create new style class for a list of nodes or links | void |
addMappingStyleOnNode | type: string, style: string, targetLabel: string, values: Function or {[key: string]: string or number} or string, mappingName: string, conditionName: string, data: {[key: string]: {[key: string]: string or number} or Array}, network: Network, graphStyleProperties: GraphStyleProperties | ||
Apply style on nodes according to mapping values | void | ||
removeMappingStyleOnNode | network: Network, networkStyle: GraphStyleProperties, mappingName: string, conditionName: string, type: string, style: string | Remove specific mapping style over network | void |
UseUndo
Name | Arguments | Description | Output |
---|---|---|---|
createUndoFunction | objectUndoable: any, capacityNumber: number | Create different methods from useRefHistory to a specific object to manage undo / redo functions | {undo: Function, redo: Function, commit: Function, resume: Function, pause: Function} |
UseZoomSvg
Name | Arguments | Description | Output |
---|---|---|---|
initZoom | X | Apply d3.zoom() event on graph svg | d3.ZoomBehavior<Element, unknown> |
stopZoom | X | Remove d3.zoom() event from graph SVG | void |
rescale | zoomObject: d3.ZoomBehavior<Element, unknown> | Fit network to graph svg (screen) | void |