@latkit/network¶

WebGPU network renderer for Latkit.

Install¶

npm install @latkit/gpu @latkit/network @latkit/colormaps

Basic use¶

import { colormap } from '@latkit/colormaps';
import { requestDevice } from '@latkit/gpu';
import { createNetwork, type Topology } from '@latkit/network';

const topology: Topology = {
  vertexCount: 3,
  vertexCoords: new Float32Array([-96, 30, -95, 31, -94, 30]),
  edges: new Uint32Array([0, 1, 1, 2]),
  polylineStart: new Uint32Array([0, 0, 0]),
};

const device = await requestDevice();
const canvas = document.querySelector<HTMLCanvasElement>('#network')!;
const network = await createNetwork(device, canvas, {
  colormap: colormap('viridis'),
  graticule: true,
});

network.load(topology);
network.setChannel('vertexColor', new Float32Array([0.1, 0.8, 0.4]), [0, 1]);
network.fadeIn();

createNetwork() accepts a native Core GPUDevice and a caller-owned HTMLCanvasElement. @latkit/gpu acquires the device and supplies Network’s shared presentation internals. The caller controls the canvas’s placement and CSS size.

Network borrows both. Destroy the renderer before removing the canvas, and destroy the device only after every renderer using it has been destroyed:

network.destroy();
canvas.remove();
device.destroy();

Data shape¶

vertexCoords stores two numbers per vertex.
edges stores endpoint pairs.
polylineStart stores one offset per edge plus a terminal offset.
Channel arrays must match the current vertex or edge count.

See the repository docs for topology, channel, projection, and lifecycle guidance.

Interfaces¶

Interface	Description
Borders	GPU-ready world border geometry consumed directly by the renderer.
Network	Imperative controller for a WebGPU network canvas.
Options	Initial network renderer configuration.
Topology	CPU-side graph and geometry used to build network render buffers.

Type Aliases¶

Channel¶

Channel = "vertexColor" | "vertexHeight" | "vertexSize" | "edgeColor" | "edgeDash"

Named per-vertex or per-edge data stream that can affect rendering.

Events¶

Events = object

Events emitted by a Network instance.

Remarks¶

hover and select use null values to report cleared interaction state. Programmatic selection methods do not emit select; user pointer selection does emit it.

Properties¶

Property	Type	Description
`deviceLost`	(`reason`, `message`) => `void`	WebGPU device-loss notification surfaced before rendering pauses.
`hover`	(`kind`, `index`) => `void`	Hovered vertex or edge; null kind and index after hover exit.
`select`	(`kind`, `index`) => `void`	User-selected vertex or edge; null kind and index after selection clear.
`zoom`	(`atFitView`) => `void`	Camera zoom state after a fit-view transition or gesture.

Functions¶

createNetwork()¶

createNetwork(device, canvas, options?): Promise<Network>

Creates a WebGPU network renderer on a caller-owned canvas.

Parameters¶

Parameter	Type	Description
`device`	`GPUDevice`	Borrowed Core WebGPU device. The caller retains ownership.
`canvas`	`HTMLCanvasElement`	Borrowed canvas used for presentation and pointer input.
`options`	`Options`	Initial rendering and interaction options.

Returns¶

Promise<Network>

A controller for loading topology, binding channels, and releasing GPU resources.

Throws¶

TypeError when device does not provide Core WebGPU features and limits.

Throws¶

Error when canvas presentation or renderer initialization fails.

Example¶

const network = await createNetwork(device, canvas, { graticule: true });
network.load(topology);
network.fadeIn();

The returned controller owns its renderer resources, but not canvas or device. Destroy the controller before removing the canvas or destroying the borrowed device.