Visualization Features

Data fetched from NetBox is mapped to visual properties of the diagram: link thickness, colors, line styles, node styles, and grouping.

Bandwidth Visualization

Link speed is auto-detected from the NetBox interface speed field (kbps) and stored on the link as rateBps. The renderer maps the speed to stroke width on a continuous logarithmic scale — a 1G link renders as a thin line, a 10G link noticeably thicker, and a 100G trunk as a wide "pipe".

When both endpoints report a speed, the source side's value takes precedence; links without any speed use the default width.

VLAN Visualization

VLAN information is collected from each interface's tagged_vlans and untagged_vlan and set on the link:

• VLANs from both endpoint interfaces are merged into link.vlan
• Each VLAN ID gets a deterministic color via getVlanColor(vid)

Cable Type Color Coding

With colorByCableType: true (the default), links are colored and styled based on the NetBox cable type. Fiber and copper render as solid lines, DAC/AOC as dashed lines:

If a cable has an explicit color set in NetBox, that color takes precedence over the type-based mapping. A cable's label and length are shown as the link label.

Device Status Visualization

With colorByStatus: true, node styles reflect the NetBox device status:

Grouping Options

The groupBy converter option controls how devices are nested into subgraphs:

Virtual Machines

When VMs are included (convertToNetworkGraphWithVMs with includeVMs: true):

• VMs render as server nodes with a dashed border
• The label shows the VM name, primary IP, and specs (vCPU / memory) when available
• With groupVMsByCluster: true, VMs are nested into dashed subgraphs per cluster

Legend

Display a legend on the diagram with the legend option:

// Simple enable
const graph = convertToNetworkGraph(devices, interfaces, cables, {
  legend: true,
})

// Customize
const graph = convertToNetworkGraph(devices, interfaces, cables, {
  legend: {
    enabled: true,
    position: 'top-right',
    showDeviceTypes: true,
    showBandwidth: true,
    showCableTypes: true,
    showVlans: false,
  },
})

Legend Options

Hierarchical Output

Multi-site networks can be split into hierarchical YAML with convertToHierarchicalYaml:

import { convertToHierarchicalYaml } from 'shumoku-plugin-netbox'

const result = convertToHierarchicalYaml(deviceResp, interfaceResp, cableResp, {
  hierarchyDepth: 'location', // 'site' | 'location' | 'rack'
  fileBasePath: './',
})

console.log(result.main)       // Content of main.yaml
console.log(result.files)      // Map<locationId, yamlContent>
console.log(result.crossLinks) // Cables crossing location boundaries

Hierarchy Depth

Output Example

# main.yaml
name: "Network Overview"
description: "Hierarchical network topology"

settings:
  direction: TB

subgraphs:
  - id: tokyo-dc
    label: "Tokyo Dc"
    file: "./tokyo-dc.yaml"
    style:
      fill: "accent-blue"
  - id: osaka-dc
    label: "Osaka Dc"
    file: "./osaka-dc.yaml"
    style:
      fill: "accent-green"

links:
  # Cross-site links reference devices directly
  - from:
      node: tokyo-router
      port: wan1
    to:
      node: osaka-router
      port: wan1