Skip to content
Snippets Groups Projects
JeanClement's avatar
Jean-Clement Gallardo authored
0.11.31 0.11.31
798622a7
History

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

Simple network

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:

Styles network

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