gabrielmoreira 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_USERNAMEin.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 vianpm install && npm run build, registered assketchfab-mcpinconfig/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-serverhad a real bug (license field silently dropped from itssketchfab-model-detailstool output) found and patched during implementation — see the "NetClaw patch" comments inmcp-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.