microsoft / graspologic-js

A high-performance modern set of graph rendering components, which enables users to visualize large graph datasets on the web.

graspologic-js

📄Overview

graspologic-js is a high-performance graph toolkit for the web.

Features

• A fast, memory-efficient, graph renderer.
  • WebGL based engine that can handle hundreds of thousands or even millions of nodes.
  • Utilizes SharedArrayBuffer for efficient and fast memory storage that can be shared between the UI thread and Web Workers, allowing for blazing fast layout algorithms that display output in real-time.
  • Supports ReactJS or standalone.
• Contains experimental implementations of a few popular graph layout algorithms that work directly with the graph renderer.

graspologic-js is a companion library to graspologic, which is a python library for intelligently building networks and network embeddings, and for analyzing connected data.

🌐Browser Compatibility

Any browser which supports WebGL2. To see which browsers support WebGL2, please see caniuse.com

It is recommended that you use a JavaScript bundling tool, such as Webpack or Browserify, as graspologic-js only exports CommonJS and ECMAScript module formats. It does not provide a web-friendly bundle in order to allow bundling tools to use tree-shaking to minimize dependency size.

It is also recommended that your bundler targets the following browser versions in order to minimize the amount of polyfills, which can adversely affect performance:

• Edge 79+
• Firefox 60+
• Chrome 72+

🔥 2 Minute Quick Start

React

Install the @graspologic/react dependency

npm install @graspologic/react

Add the GraphView component to your app

import React, { useMemo } from 'react'
import { GraphView } from '@graspologic/react'
export default () => {
	const data = useMemo(
		() => ({
			// Pass in your data here
			nodes: [],
			edges: [],
		}),
		[],
	)
	return <GraphView style={{ width: '100%', height: '100%' }} data={data} />
}

Standalone

Install the @graspologic/renderer dependency

npm install @graspologic/renderer

import { WebGLGraphRenderer } from '@graspologic/renderer'
import { GraphContainer } from '@graspologic/graph'

function createRenderer(width, height) {
	// Create a renderer and add it to the container
	const renderer = WebGLGraphRenderer.createInstance({
		width,
		height,
	})

	// Load the dataset
	renderer.load(
		GraphContainer.intern({
			// Pass in your data here
			nodes: [],
			edges: [],
		}),
	)

	// Start rendering
	renderer.start()

	// Return the container
	return renderer
}

// ...elsewhere in your app

// Instantiate the renderer
const renderer = createRenderer(500, 500)

// Add the renderer's canvas to your container element
containerElement.appendChild(renderer.view)

You can see more examples in the examples folder.

✅ License

Under the permissive MIT license

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

graspologic-js's Issues

Emit warning if edge's source or target value doesn't have a matching node.

More modular/pluggable components

In several instances I've needed just a very quick node renderer, but didn't need all the extra functionality of the renderer. It would've been nice if I could have just used the node renderer, to limit bundle size.

make available the dependency 'docs'

The examples all import import { exampleData, utils } from 'docs' which is not included in npm or this repository. Examples should be always run-able and it would be beneficial if this could get fixed.

Not rendering any nodes

When using graspologic, and following the example code, I can not get any rendering happening.

import React, { useState, useCallback, useMemo } from 'react'
import colorizer from './data/categoricalColorizer.ts'
import {
        Axes,
        GraphView,
        Camera,
        HighlightHoveredNode,
        HandleNodeClicks,
        NodeSetHighlight,
        Edges,
        Nodes,
} from '@graspologic/react'
import {
        SettingsPane,
        DisplaySettings,
        EdgeSettings,
        NodeSettings,
} from '@graspologic/render-controls-react'

import { NodeImpl, EdgeImpl } from '@graspologic/graph'

export default  () => {
  let data = {
                                        nodes: [
                                                {
                                                        group: '1',
                                                        id: 'A',
                                                        label: 'A',
                                                        weight: 10.0,
                                                        x: -71.6570947858611,
                                                        y: 100.9663430468361,
                                                },
                                                {
                                                        group: '2',
                                                        id: 'B',
                                                        label: 'B',
                                                        weight: 50.0,
                                                        x: 59.56856268696598,
                                                        y: -96.58517255185609,
                                                },
                                                {
                                                        group: '3',
                                                        id: 'C',
                                                        label: 'C',
                                                        weight: 100.0,
                                                        x: -73.72442078702332,
                                                        y: -120.15483189996596,
                                                },
                                                {
                                                        group: '4',
                                                        id: 'D',
                                                        label: 'D',
                                                        weight: 1.0,
                                                        x: -50.72442078702332,
                                                        y: -30.15483189996596,
                                                },
                                        ],
                                        edges: [
                                                {
                                                        source: 'B',
                                                        target: 'A',
                                                        weight: 0.5,
                                                },
                                                {
                                                        source: 'B',
                                                        target: 'C',
                                                        weight: 0.25,
                                                },
                                                {
                                                        source: 'B',
                                                        target: 'D',
                                                        weight: 1.0,
                                                },
                                        ],
                }


        // A function which takes a "group" property from a node and returns a color
        const [nodeIds, setNodeIds] = useState([])
        const handleVertexClick = useCallback(
                (id: string | undefined) => {
                        console.log('click', id)
                        if (id) {
                                if (nodeIds.indexOf(id) === -1) {
                                        setNodeIds([...nodeIds, id])
                                } else {
                                        setNodeIds(nodeIds.filter(v => v !== id))
                                }
                        }
                },
                [nodeIds, setNodeIds],
        )

        return (
                <GraphView
      style={{ width: 600, height: 300 }}
      data={data}
      colorizer={colorizer}
    >
                        { /* Displays a set of Axes on the graph */}
                        <Axes />

                        { /* Enables controlling of certain aspects of the camera */}
                        <Camera interactive />

                        { /* Enables highlighting of the node that is being hovered over */}
                        <HighlightHoveredNode />

                        { /* Enables handling of node click events */}
                        <HandleNodeClicks onClick={handleVertexClick} />

                        {/* Highlights the given set of node ids */}
                        <NodeSetHighlight vertexIds={nodeIds} />

                        { /* Controls rendering of edges */ }
                        <Edges minWidth={5} maxWidth={5} alpha={1}/>

                        { /* Controls rendering of nodes */ }
                        <Nodes minRadius={5} maxRadius={5} />

                        {/* Adds a settings pane that allows the user to configure the graph renderer on the fly */}
                        <SettingsPane>

                                {/* Adds a display settings section to the settings pane */}
                                <DisplaySettings />

                                {/* Adds a node settings section to the settings pane */}
                                <NodeSettings />

                                {/* Adds a edge settings section to the settings pane */}
                                <EdgeSettings />
                        </SettingsPane>
                </GraphView>
        )
}

This is inside my App.js created with create-react-scripts

Consistent property naming

Edges for example have color and color2, which represent start color and end color, but we also use sourcePosition and targetPosition. The positions should be named position and position2 to match. Also, source & target indicate a direction, but the edge doesn't currently support directionality

Better node antialiasing

More eventing out of the react wrapper.

There is very little events available, so users of the react wrapper cannot respond to the various events.

onHover, onClick, camera onMove...etc.

Improve React API ergonomics, more consistent approach

We've got a couple of competing ideas:

• Opt in functionality via HOCs
• Kitchen sink via GraphView

Diff node/edge properties rather than recreate on renderer.load

This will:

1. Not need to do as much work.
2. Allow for tweening between old values -> new values.

Investigate implementing edge sizing based on data (similar to node sizes)

Size edges based on the size of the graph domain. So, if the node positions go from -5 to 5 on the x axis, and the edge size is set to 5. Then the edge rendered to screen should take up half the screen.

GraphRenderer should not zoomToGraph on resize, if the size hasn't changed.

Node/Edge shapes based on SVG Path

Be able to define a node shape based on an SVG path.

This could involve creating a texture that represents the path, and using that texture as the node.

Edge arrow heads

All ids in the system should support either number/string

Particularly the community/group ids.

LabelRenderable should not re-render if the same set of labels is passed in.