From 64a0c9c378539e8f15aff91cc8dfcba2f1a36c3f Mon Sep 17 00:00:00 2001 From: Kaelem Chandra Date: Sat, 15 Feb 2025 19:47:37 +1300 Subject: [PATCH] Polish --- docs/images/topoviewer-icons/client.svg | 1 + docs/images/topoviewer-icons/controller.svg | 1 + docs/images/topoviewer-icons/dcgw.svg | 1 + docs/images/topoviewer-icons/pon.svg | 1 + docs/images/topoviewer-icons/rgw.svg | 1 + docs/images/topoviewer-icons/router.svg | 1 + docs/images/topoviewer-icons/server.svg | 1 + docs/images/topoviewer-icons/spine.svg | 1 + docs/images/topoviewer-icons/switch.svg | 1 + docs/manual/vsc-extension.md | 121 ++++++++++++-------- 10 files changed, 84 insertions(+), 46 deletions(-) create mode 100644 docs/images/topoviewer-icons/client.svg create mode 100644 docs/images/topoviewer-icons/controller.svg create mode 100644 docs/images/topoviewer-icons/dcgw.svg create mode 100644 docs/images/topoviewer-icons/pon.svg create mode 100644 docs/images/topoviewer-icons/rgw.svg create mode 100644 docs/images/topoviewer-icons/router.svg create mode 100644 docs/images/topoviewer-icons/server.svg create mode 100644 docs/images/topoviewer-icons/spine.svg create mode 100644 docs/images/topoviewer-icons/switch.svg diff --git a/docs/images/topoviewer-icons/client.svg b/docs/images/topoviewer-icons/client.svg new file mode 100644 index 000000000..a755e3ec0 --- /dev/null +++ b/docs/images/topoviewer-icons/client.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/images/topoviewer-icons/controller.svg b/docs/images/topoviewer-icons/controller.svg new file mode 100644 index 000000000..b7eead34a --- /dev/null +++ b/docs/images/topoviewer-icons/controller.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/images/topoviewer-icons/dcgw.svg b/docs/images/topoviewer-icons/dcgw.svg new file mode 100644 index 000000000..f0a3ad492 --- /dev/null +++ b/docs/images/topoviewer-icons/dcgw.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/images/topoviewer-icons/pon.svg b/docs/images/topoviewer-icons/pon.svg new file mode 100644 index 000000000..183a003ed --- /dev/null +++ b/docs/images/topoviewer-icons/pon.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/images/topoviewer-icons/rgw.svg b/docs/images/topoviewer-icons/rgw.svg new file mode 100644 index 000000000..708af82ba --- /dev/null +++ b/docs/images/topoviewer-icons/rgw.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/images/topoviewer-icons/router.svg b/docs/images/topoviewer-icons/router.svg new file mode 100644 index 000000000..1bd7dc7d4 --- /dev/null +++ b/docs/images/topoviewer-icons/router.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/images/topoviewer-icons/server.svg b/docs/images/topoviewer-icons/server.svg new file mode 100644 index 000000000..e1e81baa0 --- /dev/null +++ b/docs/images/topoviewer-icons/server.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/images/topoviewer-icons/spine.svg b/docs/images/topoviewer-icons/spine.svg new file mode 100644 index 000000000..20ffd5251 --- /dev/null +++ b/docs/images/topoviewer-icons/spine.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/images/topoviewer-icons/switch.svg b/docs/images/topoviewer-icons/switch.svg new file mode 100644 index 000000000..fcc3cbf16 --- /dev/null +++ b/docs/images/topoviewer-icons/switch.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/manual/vsc-extension.md b/docs/manual/vsc-extension.md index 22c8de386..efed17b71 100644 --- a/docs/manual/vsc-extension.md +++ b/docs/manual/vsc-extension.md @@ -60,81 +60,110 @@ Integrated as a 'graph' action within the extension, The [clab-io-draw](https:// ### TopoViewer -Integrated as a 'graph' action within the extension, the [TopoViewer](https://github.com/asadarafat/topoViewer) project by @asadarafat offers an interactive way to visualize your containerlab topologies. Please ensure that containerlab is running for TopoViewer to function properly. +Integrated as a 'graph' action within the extension, the [TopoViewer](https://github.com/asadarafat/topoViewer) project by @asadarafat offers an interactive way to visualize your containerlab topologies. -#### Enhanced Containerlab Topology Visualization with TopoViewer +/// tip +Your lab must be deployed in order to use TopoViewer. +/// -By adding specific labels to your Containerlab topology definition, you can customize device icons, logically group nodes, and even define geo-positioning for a more intuitive network diagram. +#### Label reference -TopoViewer leverages custom labels in your Containerlab topology to: +TopoViewer enables customization of the topology visualization by use of the `labels` field in your Containerlab topology definition. By adding these labels you are able to: - **Customize Icons:** Assign specific icons to nodes based on their role. - **Organize Nodes:** Group nodes under defined categories with hierarchical levels. - - **Position Nodes Geographically:** Use geo-coordinates to map node positions. + - **Position Nodes Geographically:** Use geographic coordinates (latitude and longitude) to place nodes on a world map. + +//// tab | Icon +| Type | Name | Alias | +| -------- | ------------ | ----------------- | +| `string` | `graph-icon` | `topoviewer-icon` | -/// details | Supported TopoViewer Labels -these are supported TopoViewer labes -//// tab | graph-icon +Using `graph-icon` you can define a role for a node. Changing the role will change the icon of the node in the topology visualization. - - **Value Format:** `string` - - **Alias:** `topoViewer-role` - - **Purpose:** Defines the role of each node. TopoViewer maps these roles to unique icons. - - **Available Roles and Icons:** +!!!info + When no icon label is defined. The node icon will default to `pe`. - | Role | Icon | - |----------------|----------------------------------------------------------------------------------------------------------------------------------------------| - | **pe** / **router** | | - | **dcgw** | | - | **leaf** / **switch** | | - | **spine** | | - | **server** | | - | **pon** | | - | **controller** | | - | **rgw** | | - | **client** | | +**Available Roles and Icons:** -!!!warning - when label topoViewer-role value is not defined, it will be defaulted to **pe** +| Role | Icon | +| ------------------------- | ---------------------------------------------- | +| **`pe`** / **`router`** | ![](../images/topoviewer-icons/router.svg) | +| **`dcgw`** | ![](../images/topoviewer-icons/dcgw.svg) | +| **`leaf`** / **`switch`** | ![](../images/topoviewer-icons/switch.svg) | +| **`spine`** | ![](../images/topoviewer-icons/spine.svg) | +| **`server`** | ![](../images/topoviewer-icons/server.svg) | +| **`pon`** | ![](../images/topoviewer-icons/pon.svg) | +| **`controller`** | ![](../images/topoviewer-icons/controller.svg) | +| **`rgw`** | ![](../images/topoviewer-icons/rgw.svg) | +| **`client`** | ![](../images/topoviewer-icons/client.svg) | //// -//// tab | graph-group +//// tab | Group + +| Type | Name | Alias | +| -------- | ------------- | ------------------ | +| `string` | `graph-group` | `topoviewer-group` | - - **Value Format:** `string` - - **Alias:** `topoViewer-group` - - **Purpose:** Categorizes nodes into specific groups (e.g., "Data Center Spine", "Data Center Leaf") to enhance the structure and readability of the topology. +Use `graph-group` to categorize nodes into specific groups such as "Datacenter Spine" or "Datacenter Leaf". + +In the topology visualization this will position all nodes that belong tothe group together in a box. //// -//// tab | graph-level +//// tab | Level + +| Type | Name | Alias | +| -------------------- | ------------- | ---------------------------------- | +| `integer (unsigned)` | `graph-level` | `graph-leveltopoViewer-groupLevel` | + +When you have groups defined, you can use the `graph-level` label to position the nodes hierarchically depending on their level value. + +The level value must be a positive integer. + +The `graph-level` value is defined in a reverse scale, where `1` is the highest or best value. + +**Vertical Layout** + +When using the vertical layout algorithm to position nodes. The numerically higher the level value, the lower the group will be positioned relative to other groups. - - **Value Format:** Positive `integer` - - **Alias:** `graph-leveltopoViewer-groupLevel` - - **Purpose:** Works in conjunction with `topoViewer-group` to define the hierarchical level of nodes: - - **Vertical Layout:** Level 1 nodes appear at the top, with higher numbers positioned lower. - - **Horizontal Layout:** Level 1 nodes appear on the left, with higher numbers positioned to the right. +The group with the value `1` will be positioned at the top of the visualization. + +**Horizontal Layout** + +When using the horizontal layout algorithm, The numerically higher the level value, the further left the group will be positioned relative to other groups. + +The group with the value `1` will be positioned furtherest to the left. //// -//// tab | geo-coordinate-lat / geo-coordinate-lng +//// tab | Geo coordinates + +| Type | Name | +| -------- | -------------------------------------------------- | +| `string` | `topoViewer-geoCoordinateLat`/`geo-coordinate-lng` | + +When using the geo positioning layout algorithm, you should set geographical coordinates in your topology definition so that TopoViewer is aware of where the nodes should be positioned. - - **Value Format:** `string` - - **Alias:** `topoViewer-geoCoordinateLat` and `topoViewer-geoCoordinateLng` - - **Purpose:** Define the geographic latitude and longitude for node positioning in a geo-based layout. If omitted, TopoViewer assigns random positions. +If not defined the nodes will be randomly placed on the map. + +TopoViewer accepts coordinates in latitude and longitude. Ensure to convert if using other coordinate systems (such as DMS). + +`topoViewer-geoCoordinateLat` is sets the latitude component of the coordinates. +`topoViewer-geoCoordinateLng` is sets the longitude component of the coordinates. //// -/// -#### Example Containerlab Topology Definition +##### Sample topology -Below is an example Containerlab topology definition that utilizes these labels to enhance the visualization +Below is an example Containerlab topology definition that utilizes these labels to enhance the visualization. -//// tab | Visualization output +//// tab | Topology visualization ![topoviewer-labeled-topology](https://github.com/user-attachments/assets/f8c75b7f-36aa-46d3-865b-3f6a25ac52dc) //// -//// tab | Containerlab Topology definition +//// tab | Topology definition -/// details | ```yaml name: nokia-DataCenter-lab @@ -256,7 +285,7 @@ topology: - endpoints: ["Spine-02:e1-5", "BorderLeaf-02:e1-1"] - endpoints: ["DCGW-02:e1-1", "BorderLeaf-02:e1-2"] ``` -/// + ////