Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/zakjan/pixi-graph

Graph visualization library using PIXI.js and Graphology
https://github.com/zakjan/pixi-graph

Last synced: 3 months ago
JSON representation

Graph visualization library using PIXI.js and Graphology

Host: GitHub
URL: https://github.com/zakjan/pixi-graph
Owner: zakjan
License: mit
Archived: true
Created: 2020-08-26T09:43:46.000Z (over 4 years ago)
Default Branch: master
Last Pushed: 2023-06-02T07:06:10.000Z (over 1 year ago)
Last Synced: 2024-08-30T05:10:36.384Z (4 months ago)
Language: TypeScript
Homepage: https://zakjan.github.io/pixi-graph/
Size: 203 KB
Stars: 147
Watchers: 6
Forks: 41
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE

Awesome Lists containing this project

README

        # pixi-graph

[![](https://img.shields.io/npm/dm/pixi-graph)](https://www.npmjs.com/package/pixi-graph)

[![](https://img.shields.io/david/zakjan/pixi-graph)](https://www.npmjs.com/package/pixi-graph)

[![](https://img.shields.io/bundlephobia/min/pixi-graph)](https://www.npmjs.com/package/pixi-graph)

Graph visualization library using [PIXI.js](https://www.pixijs.com/) and [Graphology](https://graphology.github.io/).

⚠️ **The repository is archived as read-only. Feel free to continue in your own fork.**

Developing a full-featured graph visualization library is a significant effort. I'd appreciate your feedback to prioritize new features by filling in a [survey](https://link.zakjan.cz/pixi-graph-survey).

[Demo](https://zakjan.github.io/pixi-graph/)



## Install

```

npm install graphology pixi-graph

```

or

```html

```

## Usage

### Basic

```ts

const graph = new graphology.Graph();

// populate Graphology graph with data

// assign layout positions as `x`, `y` node attributes

const pixiGraph = new PixiGraph.PixiGraph({

  container: document.getElementById('graph'),

  graph

});

```

### Layouts

In its simplicity, a graph layout is a function `nodes => positions`. Therefore a layout from any other library can be used. Run the layout separately, and assign layout positions as `x`, `y` node attributes.

[graphology-layout-forceatlas2](https://github.com/graphology/graphology-layout-forceatlas2) example:

```ts

const graph = new graphology.Graph();

// populate Graphology graph with data

graph.forEachNode(node => {

  graph.setNodeAttribute(node, 'x', Math.random());

  graph.setNodeAttribute(node, 'y', Math.random());

});

forceAtlas2.assign(graph, { iterations: 300, settings: { ...forceAtlas2.inferSettings(graph), scalingRatio: 80 }});

const pixiGraph = new PixiGraph.PixiGraph({ ..., graph });

```

### Style

```ts

const style = {

  node: {

    color: '#000000',

  },

  edge: {

    color: '#000000',

  },

};

const pixiGraph = new PixiGraph.PixiGraph({ ..., style });

```

#### Colors

Colors are resolved with [color-rgba](https://github.com/colorjs/color-rgba). The following CSS colors strings are supported: named colors, hex, short-hand hex, RGB, RGBA, HSL, HSLA.

#### Webfonts

Preload fonts before creating PixiGraph with [FontFaceObserver](https://github.com/bramstein/fontfaceobserver).

[Material Icons](https://google.github.io/material-design-icons/) example:

```html

```

```ts

const style = {

  node: {

    icon: {

      content: 'person',

      fontFamily: 'Material Icons',

    },

  },

};

await new FontFaceObserver('Material Icons').load();

const pixiGraph = new PixiGraph.PixiGraph({ ..., style });

```

#### Bitmap fonts

Register bitmap fonts as [resource-loader](https://github.com/englercj/resource-loader) external resource.

```ts

const style = {

  node: {

    label: {

      content: node => node.id,

      type: PixiGraph.TextType.BITMAP_TEXT,

      fontFamily: 'HelveticaRegular',

    },

  },

};

const resources = [

  { name: 'HelveticaRegular', url: 'https://gist.githubusercontent.com/zakjan/b61c0a26d297edf0c09a066712680f37/raw/8cdda3c21ba3668c3dd022efac6d7f740c9f1e18/HelveticaRegular.fnt' },

];

const pixiGraph = new PixiGraph.PixiGraph({ ..., style, resources });

```

#### Hover style

Hover style values override style values when node/edge is hovered.

```ts

const style = {

  node: {

    color: '#000000',

  },

  edge: {

    color: '#000000',

  },

};

const hoverStyle = {

  node: {

    color: '#ff0000',

  },

  edge: {

    color: '#ff0000',

  },

};

const pixiGraph = new PixiGraph.PixiGraph({ ..., style, hoverStyle });

```

⚠️ subject to change with the implementation of other states

## API

```ts

export interface GraphOptions {

  container: HTMLElement;

  graph: AbstractGraph;

  style: GraphStyleDefinition;

  hoverStyle: GraphStyleDefinition;

  resources?: IAddOptions[];

}

export class PixiGraph {

  constructor(options: GraphOptions);

}

```

- `container` - HTML element to use as a container

- `graph` - [Graphology](https://graphology.github.io/) graph

- `style` - style definition

- `hoverStyle` - additional style definition for hover state

  - ⚠️ subject to change with the implementation of other states

- `resources` - [resource-loader](https://github.com/englercj/resource-loader) external resource definitions

  - resources are passed to loader.add function

  - currently used only for external bitmap fonts

### Style definition

`GraphStyle` interface represents a resolved style, all values are mandatory.

`GraphStyleDefinition` interface allows functions or missing values at any key. Functions are resolved, missing values fall back to a previous definition, or default values.

```ts

export interface GraphStyle {

  node: {

    size: number;

    color: string;

    border: {

      width: number;

      color: string;

    };

    icon: {

      content: string;

      type: TextType;

      fontFamily: string;

      fontSize: number;

      color: string;

    };

    label: {

      content: string;

      type: TextType;

      fontFamily: string;

      fontSize: number;

      color: string;

      backgroundColor: string;

      padding: number;

    };

  };

  edge: {

    width: number;

    color: string;

  };

}

export type NodeStyle = GraphStyle['node'];

export type EdgeStyle = GraphStyle['edge'];

export type StyleDefinition =

  ((attributes: Attributes) => Style) |

  {[Key in keyof Style]?: StyleDefinition<Style[Key], Attributes>} |

  Style;

export interface GraphStyleDefinition<NodeAttributes extends BaseNodeAttributes = BaseNodeAttributes, EdgeAttributes extends BaseEdgeAttributes = BaseEdgeAttributes> {

  node?: StyleDefinition<NodeStyle, NodeAttributes>;

  edge?: StyleDefinition<EdgeStyle, EdgeAttributes>;

}

```

This allows either static styles, or data-driven styles at any style definition level. Each function is resolved only once.

```ts

const style = {

  node: {

    color: '#000000',

  },

};

```

or

```ts

const style = {

  node: {

    color: node => colors[node.group % colors.length],

  },

};

```

or

```ts

const style = {

  node: node => {

    const color = colors[node.group % colors.length];

    return { color };

  },

};

```

### Events

Node events:

- nodeClick

- nodeMousemove

- nodeMouseover

- nodeMouseout

- nodeMousedown

- nodeMouseup

```ts

pixiGraph.on('nodeClick', (event, nodeKey) => ...);

```

Edge events:

- edgeClick

- edgeMousemove

- edgeMouseover

- edgeMouseout

- edgeMousedown

- edgeMouseup

```ts

pixiGraph.on('edgeClick', (event, edgeKey) => ...);

```

## Sponsors

<a href="https://reflect.app/"><img src="https://reflect.app/static/icons/icon-bare.svg" alt="Reflect" width="48" height="48"></a>