NetFogVis

WebGL network-graph visualiser built on PixiJS.
Supports graphs with hundreds of thousands of nodes and edges via viewport culling, spatial hashing, LOD rendering and sprite pooling.

Installation

npm install netfogvis

Quick Start

import { init, loadGraph } from 'netfogvis';

const container = document.getElementById('graph');
await init(container);

await loadGraph({
  nodes: [
    { id: 0, label: 'A', x: 100, y: 200 },
    { id: 1, label: 'B', x: 400, y: 300 },
  ],
  edges: [
    { source: 0, target: 1, weight: 2 },
  ],
});

API Reference

init(containerEl, options?)

Initialises the PixiJS application and attaches the canvas to containerEl.
Must be called before any other function.

await init(document.getElementById('graph'), {
  quality: 4,           // LOD preset: 1 (low) | 2 (medium) | 3 (high) | 4 (ultra, default)
  background: 0xffffff, // background color (default: white)
  antialias: true,      // (default: true)
  resolution: 2,        // pixel ratio (default: devicePixelRatio)
  powerPreference: 'high-performance', // WebGL hint
  hoverEdgeMode: false, // start with hover-edge mode on/off
});

Returns: Promise<PIXI.Application>

addNode(opts)

Adds a single node to the graph.

| Option | Type | Default | Description | |---|---|---|---| | id | string \| number | auto-increment | Unique node identifier | | x | number | required | World-space X position | | y | number | required | World-space Y position | | label | string | '' | Text label rendered below the node | | color | number | global node color | Fill color, e.g. 0xff0000 | | borderColor | number \| null | global border color | Stroke color; null removes the border | | labelColor | number | global label color | Label text color |

Returns: { id, x, y, label }

addNode({ id: 'alice', x: 200, y: 150, label: 'Alice', color: 0x4287f5 });

addEdge(opts)

Adds a single edge between two existing nodes.

| Option | Type | Default | Description | |---|---|---|---| | source | string \| number | required | Source node id | | target | string \| number | required | Target node id | | directed | boolean | false | Draw an arrowhead towards target | | weight | number | 1 | Controls line thickness (lineWidth = 1.5 × weight) | | color | number | global edge color | Edge color, e.g. 0xff0000 |

Returns: { source, target, directed, weight }

addEdge({ source: 'alice', target: 'bob', directed: true, weight: 3, color: 0xaaaaaa });

loadGraph(data, bounds?, opts?)

Clears the current graph and loads a new one from a plain object. Inserts nodes in chunks to avoid blocking the UI thread.

await loadGraph(
  {
    nodes: [{ id: 0, label: 'A', x: 0.1, y: 0.2 }, ...],  // x/y in [0, 1] by default (normalised)
    edges: [{ source: 0, target: 1, weight: 1, color: 0x000000 }, ...],
    arcs:  [{ source: 1, target: 2, weight: 1 }, ...],      // directed edges
  },
  { width: 1920, height: 1080, minWidth: 20, minHeight: 20 }, // world bounds for de-normalisation
  {
    onProgress: (loaded, total) => console.log(loaded, total),
    normalized: true,   // (default) x/y in [0, 1] → x * (W - MIN_W) + MIN_W
                        // set to false when x/y are already in pixel coordinates
  },
);

clearGraph()

Removes all nodes and edges from the canvas and resets internal state.

clearGraph();

createRandomGraph(nodeCount, edgeCount, opts?)

Generates a random graph and renders it. World size scales automatically to avoid node cramping.

await createRandomGraph(500, 1000, {
  directed: false,
  onProgress: (loaded, total) => {},
  width: 3000,   // override world width
  height: 2000,  // override world height
});

Returns: Promise<{ nodes: Array, edges: Array }>

exportPajek()

Serialises the current graph to Pajek .net format and triggers a file download (data.net).

exportPajek();

exportJson()

Serialises the current graph to JSON and triggers a file download (data.json).

exportJson();
// { nodes: [{id, label}], edges: [{source, target}], arcs: [{source, target}] }

resetCamera()

Resets pan and zoom to the initial state (no transform).

resetCamera();

Style Setters

These affect nodes/edges added after the call. Existing sprites are not retroactively updated.

setNodeColor(color)

Sets the default fill color for new nodes.

setNodeColor(0x0000ff); // blue

setNodeBorderColor(color, width?)

Sets the default border color and width for new nodes. Pass null to remove borders.

setNodeBorderColor(0x000000, 2); // black border, 2px
setNodeBorderColor(null);        // no border

setEdgeColor(color)

Sets the default color for new edges.

setEdgeColor(0x333333);

setLabelColor(color)

Sets the default label text color.

setLabelColor(0x000000);

LOD (Level of Detail)

NetFogVis automatically adjusts rendering quality based on zoom level and visible node count to maintain performance.

setLODConfig(cfg)

Overrides individual LOD thresholds at runtime.

| Key | Type | Description | |---|---|---| | noEdgeScale | number | Zoom below which edges are hidden entirely | | simpleScale | number | Zoom below which edges switch to thin semi-transparent lines | | noEdgeCount | number | Visible node count above which edges are hidden | | simpleCount | number | Visible node count above which edges switch to simple lines | | capLOD1 | number | Max edges drawn in simple-line mode | | capLOD2 | number | Max edges drawn in full mode | | nodeLabelScale | number | Zoom below which node labels are hidden | | nodeSimpleScale | number | Zoom below which nodes switch to dot sprites |

setLODConfig({ noEdgeScale: 0.05, capLOD2: 5000 });

The quality option in init() applies one of four built-in presets:

| Preset | noEdgeScale | simpleScale | noEdgeCount | capLOD2 | |---|---|---|---|---| | 1 (low) | 0.10 | 0.35 | 500 | 800 | | 2 (medium) | 0.07 | 0.25 | 1200 | 1500 | | 3 (high) | 0.05 | 0.18 | 2000 | 2500 | | 4 (ultra) | 0.02 | 0.10 | 5000 | 8000 |

getLODConfig()

Returns the current LOD thresholds as a plain object.

const cfg = getLODConfig();
// { noEdgeScale, simpleScale, noEdgeCount, simpleCount, capLOD1, capLOD2, nodeLabelScale, nodeSimpleScale }

setHoverEdgeMode(enabled)

When enabled, only edges connected to the node under the cursor are rendered. Useful for dense graphs where edge overlap is hard to read.

setHoverEdgeMode(true);

Can also be set at init time via options.hoverEdgeMode.

Graph Data Format

JSON (loadGraph / exportJson)

{
  "nodes": [
    { "id": 0, "label": "Alice", "x": 120, "y": 340, "color": 4358389 }
  ],
  "edges": [
    { "source": 0, "target": 1, "weight": 1.5, "color": 0 }
  ],
  "arcs": [
    { "source": 1, "target": 2, "weight": 1 }
  ]
}

• edges — undirected edges
• arcs — directed edges (arrowheads rendered)
• x / y are normalised coordinates in [0, 1] by default, mapped via x * (W - minWidth) + minWidth (mirrors the Python denormalize_positions formula). Pass normalized: false in opts to supply raw pixel coordinates instead.

Pajek .net (exportPajek)

*Vertices 2
0 "Alice" 0.0800 0.4857
1 "Bob"   0.2667 0.3143
*Edges
0 1 1