Topology and channels¶

Use this guide when adapting real network data to @latkit/network.

Topology arrays¶

Topology is the CPU-side graph shape passed to network.load().

Field	Length	Meaning
`vertexCount`	`1` number	Number of logical graph vertices
`vertexCoords`	`vertexCount * 2`	Interleaved `x, y` or `lon, lat` coordinates
`edges`	`edgeCount * 2`	Endpoint vertex indices as `from, to` pairs
`polylineStart`	`edgeCount + 1`	Offset table into `polylinePoints`
`polylinePoints`	`pointCount * 2`	Optional bend points for edge polylines

For straight edges with no bend points, use a zero-filled polylineStart with edgeCount + 1 entries:

const topology: Topology = {
  vertexCount: 4,
  vertexCoords: new Float32Array([0, 0, 1, 0, 1, 1, 0, 1]),
  edges: new Uint32Array([0, 1, 1, 2, 2, 3]),
  polylineStart: new Uint32Array([0, 0, 0, 0]),
};

For a bent edge, place the intermediate points in polylinePoints and use polylineStart to mark the range for each edge:

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

Projection support¶

Flat and tilt projections accept arbitrary coordinates. Globe projection is available only when loaded bounds look geographic: longitude in [-180, 180], latitude in [-90, 90], a non-trivial geographic span, and a characteristic length small enough for globe rendering.

Read support after load():

network.load(topology);

if (network.projections.globe) {
  network.setProjection('globe');
}

Channel arrays¶

Channels bind scalar values to vertices or edges after a topology is loaded.

Channel	Length	Effect
`vertexColor`	`vertexCount`	Colors vertices through the active colormap
`vertexHeight`	`vertexCount`	Raises vertices and height poles
`vertexSize`	`vertexCount`	Scales vertex billboards
`edgeColor`	`edgeCount`	Colors edges through the active colormap
`edgeDash`	`edgeCount`	Enables per-edge dash pattern values

network.load(topology);

network.setChannel('vertexColor', vertexLoad, [0, 1]);
network.setChannel('edgeColor', edgeStress, [0, 100]);
network.setChannel('vertexHeight', vertexLoad, [0, 1], [0, 0.8]);

The third argument is the input domain. Pass null to auto-scan height values. The fourth argument is the output height range and only applies to vertexHeight.

Validation failures¶

network.load() throws if lengths, endpoints, or polyline offsets are invalid. setChannel() throws if no topology is loaded or the channel length does not match the current topology.