cosmograph-org/cosmos

GPU-accelerated force graph layout and rendering

🌌 Cosmos

GPU-accelerated Force Graph

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.

📺 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%.

Warning If you're going to create a new graph within the same HTML canvas element that already has a graph, destroy the previous graph using graph.destroy() to prevent unexpected glitches.

Check out the Wiki for more information on 🛠 Configuration and ⚙️ API Reference.

Examples

• Basic Set-Up
• Adding Node Labels (via @interacta/css-labels)

Showcase (via cosmograph.app)

• 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)

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

📩 [email protected]

cosmos's Issues

Visually highlight a node when hovering/clicking

Presumably with a ring around the hovered/clicked node.

Community Server?

Hi Cosmograph team,

Do you have a Discord Server or plan to create one? I've recently stumbled on your project and have assigned one of our interns to explore the tool. She's planning on creating some content (sample project, video, and blog) integrating CosmosGraph and TigerGraph. Having an open communication channel (ie. Discord) would be Super helpful incase we run into snags. Alternatively you could join our Discord channel https://discord.gg/tigergraph.

Cheers!
Jon Herke

repulsionFromMouse doesn't seem to work

Hello,

I can't manage to get the repulsionFromMouse option to work.
I try to add this option on this sandbox but it doesn't work.
https://codesandbox.io/s/cosmos-usage-example-forked-cfloc1?file=/src/index.ts

Is there something I don't understand or it's not implemented ?

Problem in combining the cosmos usage example into my own project.

Thank you for developing this powerful tool and providing usage examples!

The aim of my project is to visualize a large medical network on a webpage. Thus, your package will be extremely helpful.

However, I have encountered a problem:
TS2305: Module '"C:/Users/22171/viz_web_project/mysite/frontend/node_modules/@cosmograph/cosmos/dist/index"' has no exported member 'GraphConfigInterface'.

Could you help me to solve it? I am totally new to typescript and web projects.

set linkColor rgba

Hello,

I'm trying to update the alpha values of edges by changing linkColor in the config, but it does not appear to work. I can set the alpha value on first load however.

Ideally, I tried graph.setConfig({ linkColor: [128,128,178,.5] }); first, as well as by string "rbga(128,128,178.5)"

(Almost there, hopefully I can send a link to you tomorrow, when we have https working so you can see our application of cosmograph)

Linkable library?

Hi,

This is super cool. I'm a researcher in bioinformatics, and we frequently need to visualize large graphs involving genome assembly data. Is there a core layout method from your work that could be broken out into a reusable library? I'm familiar with Python and C++, but i'm terribly inexperienced with javascript, or any web interface language, so I'm having difficulty tracking down where the bulk of the computational methods are implemented, and if it is possible to port for non-web purposes.

Any advice or alternative recommendations for efficient large scale graph layout would also be appreciated. I'm currently relying on OGDF in C++ for everything.

Feature request: implement collision force to prevent overlap

Hi there,

First thank you for this great lib, the performance is outstanding!

I was wondering implementing the collision force of D3-force is considered?

I would like to use cosmos as a layout calculator with a different renderer, and for that I need a "prevent overlap" setting, which this force could provide.

I would like to contribute although i'm not well versed in glsl. Would you say implementing this is feasible?

Is a React Component possible?

Hi,

a quick question from a Javascript Noob.
Is there any major obstacle to write a React Component around your library to display your graph in a React webapp?

I would be interested in doing so, or even more favorable: to further translate the React component to a Dash component in order to go full Python with the rest of my webapp. How much effort do you think this would be?

Appreciate any guidance!

Feature request: same dataset should render the same layout

Hi,

Is there a way to specify the a "random seed", so that, given the same dataset twice, the generated layout is the same?

Doing a quick scan over the repo I see quite some places random numbers are inserted, so this might not be easy?

Thank you

Adjusting link strength through data

Is there any way to adjust the base link strength of a given edge based on some value provided in the data?

For example, a higher weight may correspond to a stronger link, effectively clustering nodes which are connected with higher weighted edges.

Device render problem

Of course Cosmograph is best experienced on a large monitor with nice graphics card, but still, some people are expecting to see at least a reduced version on other devices.

Besides going out of memory (I realise that is a different and difficult issue!) we have seen two types of error, on creating the graph and setting the data.

I guess these are more problems with regl than Cosmograph, but is there any plan to cope with these devices?

new Graph(canvas, config)
(regl) "OES_texture_float" extension is not supported by the current WebGL context, try upgrading your system or a different browser

graph.current.setData(nodes, links)
(regl) invalid width

Adjustable Link Length

Hello,

This library is absolutely awesome! I couldn't seem to find it anywhere in the wiki or README, but I might have missed it - is there any way to specify the length of each link? Thank you!

question

hi,

is there a way to visualize a decision tree - and import graphviz with dot format?
https://mljar.com/blog/visualize-decision-tree/

Style nodes using images or svgs

We have a requirement where we would like the nodes to represent different entities, using svgs. How do we go about this? Other than that this seems to be the perfect library ! Great work

Feature Ideas: Fit Selection; Highlight connected nodes

Hi there! I adore this library, thank you for making it and maintaining it.

I'm currently using it to visualize all the internal links of a website so that we can discover things like where broken links tend to occur and visualize how much of our website is devoted to certain features, etc. Your library is hands-down the best I've used in terms of performance.

What would make my life so much easier would be the ability to highlight the immediate ancestors and descendants of a given node on click. Currently, when a single node is clicked, everything else gets "greyed-out". While I like this feature, it makes manually exploring the graph a pain in some circumstances, especially when I'd click (or miss-click, lol) on a node and I'd immediately lose where I was. Perhaps, a color / size change to emphasize that some other nodes are "related" to the currently selected one would help out here, but I'm unsure how to manage that with the current API.

Relatedly, I'd really like something like "fitView" but for "fitSelection" that references all the currently selected nodes and centers the viewport upon them. This would really be handy for a "search" feature that I'm working on that emphasizes the query's results.

In general, the ability to selectively show / hide / filter certain portions or categories of nodes would be hugely helpful as well.

Anyway, thanks for your consideration! Keep well!

getNodePositions return incorrect positions

When I call the getNodePositions function, node positions are returned inconsistently with the visualization.

As an example, I took the coordinates and displayed them in Cytoscape, and as you can see, nodes have the same shape, but the ids are in different positions.

Taking the coordinates that the method returns and drawing them on paper, it comes something similar to Cytoscape.

It looks as if the mapping returned by the method returns the correct positions, but reverses the node ids

Contributing Guidelines?

Hi! What are the contributing guidelines for this repository?

Center on a specific node during simulation?

Hi there,
I feel this is possible with the API as it stands today, though maybe i am missing something. We have a small network centered on a central point, which of course drifts around during the simulation.
Is there a way to "fix" the view on the central node? I feel like trackNodeById should do this, but it does not seem to work for me?

A problem with building application after using @interacta/css-labels

Hi, recently I started using Cosmos library. I find it very interesting and all worked fine at first, but after I started using node labels with @interacta/css-labels, I encountered a problem with the application build. I thought there was a problem with my code, but after testing the build on the example you provided the same thing occurred.

After I downloaded your example Adding Node Labels locally and ran the command "npm run build", I got the error below.
I'm using Node.js version v16.14.2 and npm version 8.5.0.
Could you, please, provide any help?

C:\Users\Mia\Desktop\cosmos-node-labels\node_modules\@interacta\css-labels\dist\index.js: Unexpected token: punc (.)
    at Z.get (C:\Users\Mia\Desktop\cosmos-node-labels\node_modules\terser\dist\bundle.min.js:1:525)
    at Object.errorToJson (C:\Users\Mia\Desktop\cosmos-node-labels\node_modules\@parcel\utils\src\errorUtils.js:9:20)
    at Pipeline.process (C:\Users\Mia\Desktop\cosmos-node-labels\node_modules\parcel-bundler\src\Pipeline.js:29:26)
    at async Object.run (C:\Users\Mia\Desktop\cosmos-node-labels\node_modules\parcel-bundler\src\worker.js:15:12)
    at async Bundler.loadAsset (C:\Users\Mia\Desktop\cosmos-node-labels\node_modules\parcel-bundler\src\Bundler.js:577:19)
    at async C:\Users\Mia\Desktop\cosmos-node-labels\node_modules\parcel-bundler\src\Bundler.js:610:13
    at async Promise.all (index 2)
    at async C:\Users\Mia\Desktop\cosmos-node-labels\node_modules\parcel-bundler\src\Bundler.js:610:13
    at async Promise.all (index 4)
    at async Bundler.loadAsset (C:\Users\Mia\Desktop\cosmos-node-labels\node_modules\parcel-bundler\src\Bundler.js:599:21)
    at async C:\Users\Mia\Desktop\cosmos-node-labels\node_modules\parcel-bundler\src\Bundler.js:610:13
    at async Promise.all (index 0)
    at async Bundler.loadAsset (C:\Users\Mia\Desktop\cosmos-node-labels\node_modules\parcel-bundler\src\Bundler.js:599:21)
    at async Bundler.processAsset (C:\Users\Mia\Desktop\cosmos-node-labels\node_modules\parcel-bundler\src\Bundler.js:557:5)
    at async PromiseQueue._runJob (C:\Users\Mia\Desktop\cosmos-node-labels\node_modules\parcel-bundler\src\utils\PromiseQueue.js:48:7)

First node in graph has no mouse event

The first node does not trigger an onClick or a onMouseOver event.

Is it possible to add/remove nodes and links during simulation?

I am trying to create a simulation where new nodes and links are added / removed as the simulation time progresses (kind of like the time filter option on cosmograph.app, but with manipulating the graph structure instead of just highlighting).

As a test, I tried the following onClick to remove a clicked node:

  events: {
    onClick: (node, i, pos, event) => {
      if (node && i !== undefined) {
        graphNodes = graphNodes.filter(n => n.id !== node.id);
        graphLinks = graphLinks.filter(l => l.source !== node.id && l.target !== node.id);
        graph.setData(graphNodes, graphLinks);
      }
      console.log("Clicked node: ", node);
    },
  },

This works, but it re-renders the whole graph with new random positioning and starts the simulation over, losing temporal cohesion in the graph visualization.

Is this behaviour supported by the library in principle? Is there a way to make sure nodes are removed / added in place without manipulating the position of other nodes in the visualization?

Note: I'm pretty sure stuff like this is possible in d3.js ;)

Is iOS support still planned / possible?

Hi, thanks for the library – the performance is great. However, I'm trying to find a library I can use to replace our existing graph visualizer react-force-graph and I've noticed that iOS support currently seems broken (the force algo seems to just result in all nodes being clustered in a big soup at the center of the graph). I saw the webkit issue, which seemed to clarify that the lack of support was not a bug and that RGBA16F would need to be used due to lack of EXT_float_blend extension.

I've never really worked with WebGL so after looking at the cosmos code-base I have no idea how possible this is. I have already forked the library to make some usability changes just for myself to better understand how we'd use it, but would definitely like to know if iOS support is a tractable problem. Thanks again for your work on this library!

Missing dist folder in the published 1.3.0-beta.0

Looks like publishing the last version didn't quite succeed. The dist folder is missing:

Stylesheets / Open-Source Sample Projects

Hello! I was wondering if you had any “style sheets”—or style templates for setting the configuration. Alternatively, if you could open-source the sample projects (other than the already open-sourced Sandbox) to be a point of reference for setting the configuration, that would be fantastic! Thanks!

Can't get basic setup to work on a Vue application

I don't know what is wrong because no errors occur also, here's a codebox of the basic setup:
https://codesandbox.io/p/devbox/gallant-forest-7vgq4z?file=%2Fsrc%2Fcomponents%2FHelloWorld.vue

If you spot any errors or have any tips it would be much appreciated.

Question: Using only the simulation and skipping visualization?

First of all, this seems like a truly awesome library. I've thought for a long time about trying to do force simulations on the GPU myself because I felt like that was the key element missing in scalable client-side graph viz tools. Bravo to you all! You hit the nail on the head with this! I can only imagine the headaches that you all have saved people like myself from...

Now, to my question: How difficult is it to use exclusively the simulation aspects of this library, and how would one go about this?

I wish to have a great deal of control over visualization in my application, and I'm confident in the viz's performance at scale. However, I've always struggled with scaling the layout computation. I have not (yet) had the chance to dig through the source or attempt to use this library, though I hope to get the chance to change that very, very soon.

I'd assume that while most users would only want a "graph-in-a-box" solution, many would probably have similar desires as myself. Could you explain if this is possible, and, if so, where to start looking?

I can only imagine that when one is using WebGL for both computation and visualization in a library like this it can be extremely tempting to closely bind the simulation and visualization aspects for simplicity's sake (and probably a bit to minimize latency as well), but I'm wondering if that decision was made here?

Thanks in advance! Looking forward to getting to play with this! I've waited a long time for something like this to pop up!

Scaling Issue in cosmograph/react on Safari and Chrome

Hi everyone,

Firstly, I want to express my gratitude for the fantastic work on this library. It's a great resource, and making it open-source is highly appreciated :)

I've been using cosmograph/react, and I've encountered a problem with how nodes and edges scale, specifically in Safari but also in Google Chrome. This issue doesn't occur in my default browser, Arc.

The problem becomes apparent when you zoom in or out on this CodeSandbox example in Safari: https://codesandbox.io/p/sandbox/cosmos-usage-example-forked-kwswkv?file=/src/index.ts

It seems that newer versions of cosmograph have fixed this issue, but the react binding is still on version 1.3.1, where the problem persists.

Could anyone offer some insights or solutions to this?

Thanks,
Jonathan

Selection and with selection; action(s)

We want to make the visualization of graph data useful for a data analyst.
They may come for the beauty, but making things useful will help them stay.

I imagine, as they explore the galaxies of their data, they'll spot something interesting or curious, and want to ask further questions to the data. For this, they'll want to be able to select one or many nodes (and/or links) and do stuff with them: Drill into the information associated with the selection, of course, but much more.

Here are a few considerations to think of.

With selection; actions

It's important that the selection and action concerns be as separated as possible.

Here's a list of possibilities, off the top of my head (but we should extend this list):

• view information (may be different whether the selection has a single, a few, or many items)
• produce some selection specification data (node ids, links -- whatever can allow a user to then recreate the selection within the same context) that can subsequently be;
  • downloaded
  • saved
  • copied
• add information (tag, label, comment, etc.)
• apply some analysis function to it (could be a function that produces the data of the subgraph, which can also be used to re-render)

How is a selection made?

Let's emulate whatever are the most common means of selection, such as (off the top of my head -- this is not verified to be the most common):

• click
• Ctrl+click to add an additional item to the selection
• click and drag to make a rectangular selection (i.e. all items within the rectangle). Problem with click and drag is that it is already used for controlling position/perspective, so we may need to add a keypress for selection (or the current use of click+drag)
• Shift+click to add an additional rectangular selections to the on going selection

The above is relevant to keyboard+mouse "manual" selection.
There's also "logical selectors": Some criteria, or formula, that can be applied to the dataset (or view, or selection) to determine what items should be selected.

What is being selected?

We'll need to figure out rules on how the relationship between node and link selection works. Are we selecting nodes through links or links through nodes. And in the latter case, when a node is selected, are all the links it's involved in selected to? Only the outgoing links? Only the incoming links? Neither? The user should probably be able to chose (again, the right choice might depend on the context).

graph nodes are in blury format and the labels are illegible

Hello!
I use cosmograph in my app and unfortunately, tgraph nodes are in blury format and the labels are illegible , is this related to vga of the server?
or require the gpu module in production space?

Feature request: Distinct Node Colors for various Groups Perception

Hi there,

Before further explanation, I have to say that this library is a masterpiece really!

It's also great that I can provide group metadata for coloring the groups. However it would be if the nodes could have scalar colors rather than having a continuous between pink and blue. (e.g. for the largest 5 group red, yellow, pink ... and grey for the rest of them)