@cosmograph/cosmos v1.6.1

Cosmos is a WebGL Force Graph layout algorithm and rendering engine. All the computations and drawing are happening on the GPU in fragment and vertex shaders avoiding expensive memory operations.

It enables real-time simulation of network graphs consisting of hundreds of thousands of nodes and edges on modern hardware.

https://user-images.githubusercontent.com/755708/173392407-9b05cbb6-d39e-4c2c-ab41-50900cfda823.mp4

📺 Comparison with other libraries

🎮 Try Cosmos on CodeSandbox

Quick Start

Install the package:

npm install @cosmograph/cosmos

Get the data, configure the graph and run the simulation:

import { Graph } from '@cosmograph/cosmos'
import { nodes, links } from './data'

const canvas = document.querySelector('canvas')
const config = {
  simulation: {
    repulsion: 0.5,
  },
  renderLinks: true,
  linkColor: link => link.color,
  nodeColor: node => node.color,
  events: {
    onClick: node => { console.log('Clicked node: ', node) },
  },
  /* ... */
}

const graph = new Graph(canvas, config)

graph.setData(nodes, links)

Note If your canvas element has no width and height styles (either CSS or inline) Cosmos will automatically set them to 100%.

Examples

• Silk Road Case: Bitcoin Transactions (📄 Read about the case)
• ABACUS Shell (source)
• The MathWorks, Inc: symmetric positive definite matrix (source)
• 4 Tower Silo (source)
• Jacobian from Bank of Canada ‘jan99’ model (source)

# Cosmos configuration

# Simulation configuration

Cosmos layout algorithm was inspired by the d3-force simulation forces: Link, Many-Body, Gravitation, and Centering. It provides several simulation settings to adjust the layout. Each of them can be changed in real time, while the simulation is in progress.

# API Reference

# graph.setConfig(config)

Set Cosmos configuration. The changes will be applied in real time.

# graph.setData(nodes, links, runSimulation)

Pass data to Cosmos: an array of nodes and an array of links. When runSimulation is set to false, the simulation won't be started automatically (true by default).

# graph.findNodeById(id)

Find a node by its id.

# graph.zoomToNodeById(id, duration)

Center the view on a node and zoom in; by node id with given animation duration. The default duration is 700.

# graph.zoomToNodeByIndex(index, duration)

Center the view on a node and zoom in; by node index with given animation duration. The default duration is 700.

# graph.setZoomLevel(value, duration)

Zoom the view in or out to the specified zoom level value with given animation duration. The default duration is 0.

# graph.fitView(duration)

Center and zoom in/out the view to fit all nodes in the scene with given animation duration. The default duration is 500 ms.

# graph.selectNodesInRange(selection)

Select nodes inside a rectangular area defined by two corner points [[left, top], [right, bottom]]. The left and right values should be from 0 to the width of the canvas in pixels.

The top and bottom values should be from 0 to the height of the canvas in pixels.

# graph.selectNodeById(id)

Select a node by id.

# graph.selectNodesByIds(ids)

Select multiple nodes by an array of their ids.

# graph.getSelectedNodes()

Get an array of currently selected nodes.

# graph.start(alpha)

Start the simulation. The alpha value can be from 0 to 1 (1 by default). The higher the value, the more initial energy the simulation will get.

# graph.pause()

Pause the simulation.

# graph.restart()

Restart the simulation.

# graph.step()

Render only one frame of the simulation. The simulation will be paused if it was active.

# graph.destroy()

Destroy this Cosmos instance.

# graph.getZoomLevel()

Get current zoom level of the view.

# graph.getNodePositions()

Get an object with node coordinates, where keys are the ids of the nodes and values are their X and Y coordinates in the { x: number; y: number } format.

# graph.getNodePositionsMap()

Get a Map object with node coordinates, where keys are the ids of the nodes and the values are their X and Y coordinates in the [number, number] format.

# graph.getNodePositionsArray()

Get an array of [number, number] arrays corresponding to the X and Y coordinates of the nodes.

# graph.isSimulationRunning

A boolean value showing whether the simulation is active or not.

# graph.maxPointSize

The maximum point size the user's hardware can render. This value is a limitation of the gl.POINTS primitive of WebGL and differs from GPU to GPU.

Known Issues

Starting from version 15.4, iOS has stopped supporting the key WebGL extension powering our Many-Body force implementation (EXT_float_blend). We're trying to figure out why that happened and hope to find a way to solve the problem in the future.

License

CC-BY-NC-4.0

Cosmos is free non-commercial usage. If you're a scientist, artist, educator, journalist, student, ..., we would love to hear about your project and how you use Cosmos! If you want to use it in a commercial project, please reach out to us.

Contact

Write us!

📩 hi@cosmograph.app