visualization

Browser-based network visualization renderer.

This module provides the shared canvas renderer for demos and external users who want to visualize neural networks in the browser. It accepts a VisualizationGraphV1 (from exportVisualizationGraph) and lays out/draws the network with optional demo-specific overlay hooks. Main entry point:*

• renderNetworkView(canvas, graph, options) — render a network on a canvas Shared infrastructure:*
• positionNetworkNodes() — generic layer-based node positioning
• centerPositionedNodesInDrawableArea() — centering logic
• resolveNetworkVisualizationTopologyPlan() — topology inference

Usage: canvas renderer (browser)

Drop-in minimal usage — no overlay config required:

import { Network, exportVisualizationGraph, renderNetworkView } from 'neataptic';

const network = Network.createMLP(2, [4], 1);
const graph = exportVisualizationGraph(network);
const canvas = document.getElementById('viz-canvas') as HTMLCanvasElement;
const frame = renderNetworkView(canvas, graph);
// frame.positionedNodes can be used for hover hit-testing

To inject demo-specific overlays (e.g. sensor-band labels), pass an overlayFactory hook — the shared renderer stays unmodified:

const frame = renderNetworkView(canvas, graph, {
  nodeDimensions: { widthPx: 28, heightPx: 28 },
  colorScales: { weightPositive: '#00ff88', weightNegative: '#ff0088',
                 activationHot: '#ffcc00', activationCold: '#0088ff', bias: '#8800ff' },
  overlayFactory: {
    createDemoOverlayScenes: (positionedNodes, nodeDimensions) => {
      // return your custom overlay scene objects here
      return [];
    },
  },
});

Usage: schema export + Graphviz DOT (external tooling)

Export a network as a portable JSON schema and convert it to a DOT diagram:

import { Network, exportVisualizationGraph, toDot } from 'neataptic';

const network = Network.createMLP(3, [5], 2);
// Full export (weights + biases included by default).
const graph = exportVisualizationGraph(network);

// Lightweight export — omit weights and biases for a large population.
const compact = exportVisualizationGraph(network, {
  includeWeights: false,
  includeBiases: false,
});

// Convert to Graphviz DOT and paste into https://dreampuf.github.io/GraphvizOnline/
const dot = toDot(graph);
console.log(dot);

The two paths share one data contract (VisualizationGraphV1) so a single exportVisualizationGraph call can feed both a canvas renderer and an external tool in the same session.

visualization/visualization.ts

centerPositionedNodesInDrawableArea

centerPositionedNodesInDrawableArea(
  positionedNodes: PositionedNetworkNode[],
  drawableWidthPx: number,
  drawableLeftPx: number,
): PositionedNetworkNode[]

Centers positioned nodes horizontally within the drawable area.

Shifts all node x-coordinates so the leftmost and rightmost nodes are balanced around the center of available space.

Parameters:

• positionedNodes - Positioned nodes.
• drawableWidthPx - Drawable width.

Returns: Centered positioned nodes.

EdgePadding

Padding on all four edges.

NetworkLayerAnnotation

Semantic annotation for one layer of nodes.

For example, recurrent networks can label hidden columns as "input gate", "hidden state t-1", etc. Feed-forward networks might have generic labels.

NetworkNodeDimensions

Dimensions shared across all nodes in a rendering pass.

NetworkVisualizationColorScales

Color scale for weight and activation visualization.

NetworkVisualizationResolvedFrame

Complete resolved frame for hover-driven incremental redraws.

The host can cache this between pointer events so it only recomputes topology, layout, and legend when the network payload changes.

NetworkVisualizationTopologyPlan

Full topology plan for layout and rendering.

Preserves the layer-array input used by layout helpers and adds optional semantic annotations for overlays.

OverlayFactoryHooks

Optional hook functions that demos can use to inject custom overlays.

Flappy Bird injects input-group label bands and per-input descriptions. ASCII Maze could inject custom layer labels, or leave hooks undefined.

PositionedNetworkNode

A node with its position and dimensions resolved in canvas coordinates.

positionNetworkNodes

positionNetworkNodes(
  networkLayers: VisualNetworkNode[][],
  leftPaddingPx: number,
  topPaddingPx: number,
  drawableWidthPx: number,
  drawableHeightPx: number,
  nodeLayoutPaddingPx: number,
  nodeDimensions: NetworkNodeDimensions,
  inputLayerTargetGapPx: number,
): PositionedNetworkNode[]

Positions network nodes into drawable canvas coordinates.

The layout preserves layer ordering while adapting inter-node spacing to available vertical space. Nodes in earlier layers are placed left; nodes in later layers are placed right.

Parameters:

• networkLayers - Resolved network layers (each layer is a list of nodes).
• leftPaddingPx - Left graph padding.
• topPaddingPx - Top graph padding.
• drawableWidthPx - Drawable graph width (canvas width minus horizontal padding).
• drawableHeightPx - Drawable graph height (canvas height minus vertical padding).
• nodeLayoutPaddingPx - Inner graph padding around nodes.
• nodeDimensions - Node dimensions (width × height px).
• inputLayerTargetGapPx - Optional target gap between input nodes (default: 0).

Returns: Positioned nodes.

renderNetworkView

renderNetworkView(
  canvas: HTMLCanvasElement,
  graph: VisualizationGraphV1,
  options: RenderNetworkViewOptions | undefined,
): NetworkVisualizationResolvedFrame

Renders a network visualization onto a canvas.

This is the main public entry point. It accepts a VisualizationGraphV1 (from exportVisualizationGraph), lays out the nodes, and draws them with optional demo-specific overlays.

Typical usage:

const graph = exportVisualizationGraph(network);
const canvas = document.getElementById('network-canvas') as HTMLCanvasElement;
const frame = renderNetworkView(canvas, graph, {
  nodeDimensions: { widthPx: 32, heightPx: 32 },
  overlayFactory: { createDemoOverlayScenes: myCustomOverlays },
});
// frame contains positioned nodes for hover hit testing

Parameters:

• canvas - Canvas element to render onto.
• graph - Visualization graph (from exportVisualizationGraph).
• options - Optional render settings (dimensions, padding, colors, overlays).

Returns: Resolved frame with positioned nodes and scene state (reusable for hover).

RenderNetworkViewOptions

Options passed to the shared renderer.

resolveNetworkVisualizationLayers

resolveNetworkVisualizationLayers(
  network: default | undefined,
  inputSize: number,
  outputSize: number,
): VisualNetworkNode[][]

Resolves layered node groups for network layout.

Parameters:

• network - Runtime network instance (or undefined for fallback).
• inputSize - Input count (used if network is undefined).
• outputSize - Output count (used if network is undefined).

Returns: Layered nodes for rendering.

resolveNetworkVisualizationTopologyPlan

resolveNetworkVisualizationTopologyPlan(
  network: default | undefined,
  inputSize: number,
  outputSize: number,
): NetworkVisualizationTopologyPlan

Resolves the full topology plan including optional layer annotations.

For recurrent networks, this detects temporal modules and creates annotations. For feed-forward networks, this creates a simple acyclic plan.

Parameters:

• network - Runtime network instance (or undefined for fallback).
• inputSize - Input count (used if network is undefined).
• outputSize - Output count (used if network is undefined).

Returns: Layered nodes plus semantic layer annotations.

VisualNetworkConnection

A visual connection between two positioned nodes.

VisualNetworkNode

A simple node representation for layout input.