Cytoscape.js Storm Layout

A custom layout plugin for Cytoscape.js that organizes nodes based on semantic coordinates. This is designed for visualizing job and task dependencies for VFX and animation pipelines, where there are typically hundreds of tasks and in each step.

Semantic coordinates are step and order. Each node can provide these values as hints for the layout algorithm. If they are not provided, the layout will attempt to infer them by doing a topological sort of the graph and assigning step and order values based on path distance from the job node.

The layout algorithm also sets taxi turn points for edges. When the edge connects 2 nodes that are in adjacent steps, the edge route makes two taxi turns. When the edge connects 2 nodes that are in steps that are not adjacent, the edge route makes four taxi turns and is routed beteen nodes to ensure the full route is always visible.

The screenshots below illustrate this.

Installation

First, ensure you have Cytoscape.js installed in your project. Then, add the Storm Layout plugin.

NPM

npm install storm-layout

Yarn

yarn add storm-layout

Usage

Import and Register the Layout

import cytoscape from 'cytoscape';
import stormLayout from 'storm-layout';

cytoscape.use(stormLayout);

Initialize Cytoscape with the Storm Layout

const cy = cytoscape({
  container: document.getElementById('cy'), // your Cytoscape container
  elements: {
    nodes: [
      { data: { id: 'a', type: 'job' } },
      { data: { id: 'b', type: 'task' } },
      { data: { id: 'c', type: 'task' } },
      { data: { id: 'd', type: 'task' } }
    ],
    edges: [
      { data: { source: 'a', target: 'b' } },
      { data: { source: 'a', target: 'c' } },
      { data: { source: 'a', target: 'd' } },
      { data: { source: 'b', target: 'c' } }
    ]
  },
  layout: {
    name: 'storm', // specify the layout name
    eles: cy.elements()
  },
  style: [/* your styles here */]
});

API

Constructor

Layout(options)

• options: An object containing layout options, merged with default options.

Methods

run()

Runs the layout algorithm, positioning nodes based on their semantic coordinates.

stop()

Stops the layout algorithm. Returns the layout instance for chaining.

destroy()

Destroys the layout instance. Returns the layout instance for chaining.

Example

import cytoscape from 'cytoscape';
import stormLayout from 'storm-layout';

cytoscape.use(stormLayout);

const cy = cytoscape({
  container: document.getElementById('cy'),
  elements: [
    { data: { id: 'Job_1-17', type: 'job' } },
    { data: { id: 'Qt_1-17', type: 'task' } },
    { data: { id: 'Ren_0001', type: 'task' } },
    // Add other nodes here
  ],
  edges: [
    { data: { source: 'Job_1-17', target: 'Qt_1-17' } },
    { data: { source: 'Qt_1-17', target: 'Ren_0001' } },
    // Add other edges here
  ],
  layout: {
    name: 'storm',
    eles: cy.elements()
  },
  style: [
    {
      selector: 'node',
      style: {
        'background-color': '#666',
        'label': 'data(id)'
      }
    },
    {
      selector: 'edge',
      style: {
        'width': 3,
        'line-color': '#ccc',
        'target-arrow-color': '#ccc',
        'target-arrow-shape': 'triangle'
      }
    }
  ]
});

cy.layout({ name: 'storm', eles: cy.elements() }).run();

Contributing

Thank you for considering contributing to storm-layout! Here are some guidelines to help you get started.

Getting Started

1. Clone the repository:

   git clone https://github.com/ConductorTechnologies/storm-layout.git
   cd storm-layout

2. Install dependencies:

   yarn

Building the Project

To build the project, use the following command:

yarn build

This will generate the build files using Rollup.

Running Tests

Currently, there are no tests specified. You can run the placeholder test script with:

yarn test

Feel free to add your own tests and update the test script accordingly.

Watching for Changes

For development purposes, you can watch for changes and automatically rebuild the project:

yarn watch

Sending Graph Data

To send graph data from an example JSON file

yarn graph

Build and Send

You can build the project and then send graph data in one step:

yarn buildAndSend

Bumping the Version

To bump the version using standard-version:

yarn bump

Releasing a New Version

To release, after bumping the version, use the following command:

yarn release

This will push the tags to the origin and publish the package.

Pre-publish Steps

Before publishing, the project will automatically build:

yarn prepublishOnly

Submitting Changes

1. Clone the repository
2. Create a new branch (git checkout -b feature/your-feature-name)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin feature/your-feature-name)
5. Create a new Pull Request

We appreciate your contributions and will review them as soon as possible!

Feel free to modify this section according to your project's specific needs. If you have any questions or need further assistance, don't hesitate to reach out.