---
name: threejs-network-viz
description: "Generate browser-based interactive 3D network topology visualizations from inventory or a topology description. Use when a portable HTML scene is wanted without a desktop 3D engine."
---

# Three.js Network Topology Visualization Skill

**Version**: 1.0.0
**Feature**: 046-threejs-network-viz
**Status**: Active

## Overview

Renders network topologies as interactive, fully-labeled 3D scenes directly in a web browser, using Three.js. Unlike NetClaw's UE5 (`ue5-network-viz`) and Blender (`blender-3d-viz`) visualization skills, this skill needs **no desktop application, no GPU, and no cross-OS bridge** — every visualization is a single, self-contained HTML file that opens directly in the engineer's own browser with no build step and no server process to manage, even in real-stencil mode.

Devices render as color-coded shapes by role (router, switch, firewall, load balancer, client); each device's interfaces are true child objects of that device (moving the device moves its interfaces automatically); links render as visible cables between the specific interfaces they connect (falling back to device-to-device when interface-level data isn't available); every device/interface/link is labeled with source-provided metadata (IP addresses, descriptions, etc., excluding credentials/config); operational state (healthy/degraded/down) overlays role coloring; and a legend explains every color/shape convention in use.

## Prerequisites

### Required

- **A modern desktop browser** (Chrome/Firefox/Edge) — nothing else. No engine, no GPU, no install.

### Optional (real-stencil mode, User Story 5)

- `SKETCHFAB_API_KEY` / `SKETCHFAB_USERNAME` in `.env` (see `.env.example`) — get a token from https://sketchfab.com/settings/password
- The vendored `sketchfab-mcp-server` (`mcp-servers/sketchfab-mcp-server/`), cloned and built via `npm install && npm run build`, registered as `sketchfab-mcp` in `config/openclaw.json`

### Topology sources

Any of NetClaw's existing topology-of-record or lab-emulation integrations — Cisco Modeling Labs, GNS3, containerlab, EVE-NG, Nautobot, NetBox/Infrahub, IP Fabric, or Forward Networks — or a freeform plain-language description requiring no live source at all.

## Natural Language Commands

### Render a live topology (User Story 1 & 2)

```
"Replicate the CML lab topology in a browser for me"
"Visualize my GNS3 project in Three.js"
"Show me the Nautobot-modeled network in a browser"
```

NetClaw resolves which source to use (asking for clarification if ambiguous and more than one is configured), retrieves the topology, builds the scene, writes it to `workspace/output/threejs-network-viz/topology-<timestamp>-<snapshot-id>.html`, and opens it in the default browser.

### Sketch a topology without a live source (User Story 3)

```
"Sketch a topology with a router called r1 and a switch called sw1, r1 connects to sw1"
"Show me two routers and a switch"
```

Produces the same quality scene as a live source, using the same shape/color/label/legend conventions. Omitted details (role, interface names) get clearly-marked defaults rather than failing to render.

### See health state (User Story 4)

State-based coloring is automatic whenever a source reports device/link operational state — no separate command needed. The legend explains both the role-color and state-color conventions together.

### Real 3D model stencils (User Story 5)

```
"Visualize the CML lab with real 3D models"
"Use real-stencil mode for this topology"
```

Enable real-stencil mode to attempt real 3D models (via Sketchfab, filtered to CC0-licensed models only) instead of procedural shapes, wherever a permitted model is found. Any device role without a verified CC0 model falls back automatically to its procedural shape, and NetClaw reports which devices fell back and why. **In practice, expect fallback to be the common outcome** — Sketchfab's catalog has essentially no CC0-licensed network-equipment-specific models; real-stencil mode is a visual enhancement layered on top of the same reliable procedural rendering, not a replacement for it.

Real-stencil mode never scrapes or auto-fetches from gated marketplaces (Fab, TurboSquid, CGTrader, GrabCAD) — for those, it only checks whether a user has manually placed a matching asset at `workspace/output/threejs-network-viz/assets/user-supplied/<role>.glb`.

### Navigate the scene

Standard mouse/trackpad controls once the page is open: left-drag to rotate, scroll to zoom, right-drag to pan (via `OrbitControls`).

## Architecture

| Module | Responsibility |
|---|---|
| `topology_model.py` | Canonical `Device`/`Interface`/`Link`/`TopologySnapshot` types every other module consumes |
| `layout.py` | Force-directed 3D layout with centroid re-centering (ported from `ue5-network-viz`) |
| `materials.py` | Role/state color tables and hostname-based device-role inference |
| `sources.py` | One adapter per topology source (8 live integrations + freeform), plus source-selection disambiguation |
| `assets.py` | Real-stencil resolution chain: cache/user-asset check → Sketchfab search + per-model CC0 verification → download+embed → procedural fallback |
| `scene_builder.py` | Builds the embedded topology JSON payload consumed by the HTML template |
| `html_template.py` | Renders the single self-contained HTML file, inlining vendored Three.js r147 |
| `output.py` | Writes the timestamped output file and opens it in the browser |
| `vendor/three/` | Vendored Three.js r147 core + `OrbitControls`/`GLTFLoader` (the last release with classic global/non-module builds — see `research.md` §1-2) |

## Environment Variables

| Variable | Required | Purpose |
|---|---|---|
| `SKETCHFAB_API_KEY` | Only for real-stencil mode | Sketchfab API authentication |
| `SKETCHFAB_USERNAME` | Only for real-stencil mode | Reference/attribution only, not required by the API itself |

## Known Limitations

- Extreme-scale topologies (thousands of devices) are not a target use case — the layout and scene are tuned for tens-of-devices/hundreds-of-interfaces lab and campus scale.
- Real-stencil mode embeds the full model into the HTML file (no linked assets, to preserve zero-server delivery), so a topology with several real models can produce a multi-megabyte file — a real, live-downloaded CC0 model tested during development was ~14MB (19MB base64-embedded).
- The vendored `sketchfab-mcp-server` had a real bug (license field silently dropped from its `sketchfab-model-details` tool output) found and patched during implementation — see the "NetClaw patch" comments in `mcp-servers/sketchfab-mcp-server/index.ts`. If this vendored server is ever re-cloned fresh from upstream, the patch must be reapplied and rebuilt (`npm run build`) before real-stencil mode's CC0 verification will work correctly.

See `specs/046-threejs-network-viz/tasks.md` for the full implementation history and `research.md` for the technical decisions behind the Three.js version pinning and Sketchfab integration.