Visualizing 3D Network Topologies Using Unity

Network topology visualization can be performed using a wide variety of technologies ranging from simple 2D applications to complex 3D applications. This approach utilizes the Unity (http://unity3d.com/) game engine to develop a network topology visualization in 3D complete with FPS controls in zero gravity and warp to zones.

Demo

Here’s an example of what the end product will look like: View Demo

Screenshots

Source Files

The entire Unity project and source files are available for download: Download Unity Topology Source

Layout File Format

Let’s get started, first a data format (or formats) needs to be chosen for loading the layout or topology data. For my example I have chosen to use GraphML (http://graphml.graphdrawing.org/) being that Unity in C# directly supports XmlDocument.

The GraphML format I am using will support a collection of <node> and <edge> with standard and custom attributes:

[codesyntax lang=”xml”]

<node id="node_1" x="0" y="0" z="0" name="156.145.220.128/25" ... />

[/codesyntax]

[codesyntax lang=”xml”]

<edge id="link_1" source="node_1" target="node_2" ... />

[/codesyntax]

The node defines at the very least the node identifier which will uniquely identify the node in the topology map, the x, y and z which will become our Vector3 coordinates and the name attribute which will become the node label.

The edge defines at the very least the link identifier which will uniquely identify the link in the topology map, the source which identifies the source node of the link and the target which identifies the target node of the link.

Unity Setup

Next let’s define our basic Unity project structure. Under the Assets folder, create the following subfolders:

Data

Materials

Prefabs

Scenes

Scripts

Once we have our basic folder structure setup, let’s create our 2 prefabs we will be using in our project, the Node prefab and the Link prefab.

The Node

Start by creating a new cylinder (GameObject -> Create Other -> Cylinder), size the cylinder down a little to make it look like and adding a Self-Illumin/Diffuse shader. I made mine blue, however feel free to choose whatever color you wish. Name the new object “Node”.

Next add a new script and call it “Node” (Node.cs). For the script we want to define a basic bit of logic to have our node text always facing the camera and a public string id:

[codesyntax lang=”csharp”]

using UnityEngine; using System.Collections; namespace Topology { public class Node : MonoBehaviour { public string id; public TextMesh nodeText; void Update () { //node text always facing camera nodeText.transform.LookAt (Camera.main.transform); } } }

[/codesyntax]

Add a 3D Text object (GameObject -> Create Other -> 3D Text), move the 3D Text just below the cylinder and move the 3D Text as a child of the Node object. Next drag the reference into the Node Text (Text Mesh) property.

Finally drag the “Node” from the Hierarchy window to the “Assets/Prefabs” folder. Then remove the “Node” object from the Hierarchy view.

The Link

For the link, create an empty game object (GameObject -> Create Empty), name it “Link” and add a new script called “Link” (Link.cs). Within the script we’ll expose a few public properties such as id, source_id, target_id, etc; and define a LineRenderer which will be used to draw the line connecting the nodes.

[codesyntax lang=”csharp”]

using UnityEngine; using System.Collections; namespace Topology { public class Link : MonoBehaviour { public string id; public Node source; public Node target; public string sourceId; public string targetId; public string status; public bool loaded = false; private LineRenderer lineRenderer; void Start () { lineRenderer = gameObject.AddComponent<LineRenderer>(); //color link according to status Color c; if (status == "Up") c = Color.gray; else c = Color.red; c.a = 0.5f; //draw line lineRenderer.material = new Material (Shader.Find("Self-Illumin/Diffuse")); lineRenderer.material.SetColor ("_Color", c); lineRenderer.SetWidth(0.3f, 0.3f); lineRenderer.SetVertexCount(2); lineRenderer.SetPosition(0, new Vector3(0,0,0)); lineRenderer.SetPosition(1, new Vector3(1,0,0)); } void Update () { if(source && target && !loaded){ //draw links as full duplex, half in each direction Vector3 m = (target.transform.position - source.transform.position)/2 + source.transform.position; lineRenderer.SetPosition(0, source.transform.position); lineRenderer.SetPosition(1, m); loaded = true; } } } }

[/codesyntax]

Being that this script was a bit larger, I’ll walk through what it does. First, the public properties; the “id” is the link identifier (ie. “link_1”), the “source” will become the source node reference, the “target” will become the target node, the “sourceId” will hold the id of the source node until the “source” property is populated and the same goes for the “targetId”. The “status” will hold a value of either “Up” or “Down” and will be used to color the LineRenderer. Within the “Start()” function, we create a new LineRenderer and color it according to the “status” property value setting its initial line positions to vectors (0,0,0) and (1,0,0) respectively. The “Update()” method waits until the “source” and “target” properties are populated then sets the LineRenderer end points. The “loaded” property makes sure this only happens once.

Finally drag the “Link” object from the Hierarchy window to the “Assets/Prefabs” folder. Then remove the “Link” object from the Hierarchy window.

Controller

Add a new empty game object (GameObject -> Create Empty) and name it “GameController”. Create a new script called “GameController” (GameController.cs). This script will be responsible for loading the layout file, creating Nodes and Links and handling general UI updates.

[codesyntax lang=”csharp”]

using UnityEngine; using System.Collections; using System.Xml; using System.IO; namespace Topology { public class GameController : MonoBehaviour { public Node nodePrefab; public Link linkPrefab; private Hashtable nodes; private Hashtable links; private GUIText statusText; private int nodeCount = 0; private int linkCount = 0; private GUIText nodeCountText; private GUIText linkCountText; //Method for loading the GraphML layout file private IEnumerator LoadLayout(){ string sourceFile = Application.dataPath + "/Data/layout.xml"; statusText.text = "Loading file: " + sourceFile; //determine which platform to load for string xml = null; if(Application.isWebPlayer){ WWW www = new WWW (sourceFile); yield return www; xml = www.text; } else{ StreamReader sr = new StreamReader(sourceFile); xml = sr.ReadToEnd(); sr.Close(); } XmlDocument xmlDoc = new XmlDocument(); xmlDoc.LoadXml(xml); statusText.text = "Loading Topology"; int scale = 2; XmlElement root = xmlDoc.FirstChild as XmlElement; for(int i=0; i<root.ChildNodes.Count; i++){ XmlElement xmlGraph = root.ChildNodes[i] as XmlElement; for(int j=0; j<xmlGraph.ChildNodes.Count; j++){ XmlElement xmlNode = xmlGraph.ChildNodes[j] as XmlElement; //create nodes if(xmlNode.Name == "node"){ float x = float.Parse(xmlNode.Attributes["x"].Value)/scale; float y = float.Parse (xmlNode.Attributes["y"].Value)/scale; float z = float.Parse(xmlNode.Attributes["z"].Value)/scale; Node nodeObject = Instantiate(nodePrefab, new Vector3(x,y,z), Quaternion.identity) as Node; nodeObject.nodeText.text = xmlNode.Attributes["name"].Value; nodeObject.id = xmlNode.Attributes["id"].Value; nodes.Add(nodeObject.id, nodeObject); statusText.text = "Loading Topology: Node " + nodeObject.id; nodeCount++; nodeCountText.text = "Nodes: " + nodeCount; } //create links if(xmlNode.Name == "edge"){ Link linkObject = Instantiate(linkPrefab, new Vector3(0,0,0), Quaternion.identity) as Link; linkObject.id = xmlNode.Attributes["id"].Value; linkObject.sourceId = xmlNode.Attributes["source"].Value; linkObject.targetId = xmlNode.Attributes["target"].Value; linkObject.status = xmlNode.Attributes["status"].Value; links.Add(linkObject.id, linkObject); statusText.text = "Loading Topology: Edge " + linkObject.id; linkCount++; linkCountText.text = "Edges: " + linkCount; } //every 100 cycles return control to unity if(j % 100 == 0) yield return true; } } //map node edges MapLinkNodes(); statusText.text = ""; } //Method for mapping links to nodes private void MapLinkNodes(){ foreach(string key in links.Keys){ Link link = links[key] as Link; link.source = nodes[link.sourceId] as Node; link.target = nodes[link.targetId] as Node; } } void Start () { nodes = new Hashtable(); links = new Hashtable(); //initial stats nodeCountText = GameObject.Find("NodeCount").guiText; nodeCountText.text = "Nodes: 0"; linkCountText = GameObject.Find("LinkCount").guiText; linkCountText.text = "Edges: 0"; statusText = GameObject.Find("StatusText").guiText; statusText.text = ""; StartCoroutine( LoadLayout() ); } } }

[/codesyntax]

So now time for the walk through. The 2 public properties nodePrefab and linkPrefab define the prefabs to be used when creating nodes and links. The 2 Hastables, nodes and links define the collection which will hold the live instances of the prefabs “Node” and “Link”. The GUIText objects will reference the loading status displayed on the screen, the count of nodes and the count of links. The nodeCount and linkCount hold the actual numeric values for the count of nodes and links. The “LoadLayout()” method handles the loading of the GraphML file, it loads the xml file into a string, populates an XmlDocument object and iterates over the <node/> and <edge/> elements. When a <node /> is encountered we instantiate a Node object and populate its members and same goes for <edge /> with respect to populating a Link. Once all the “Node” and “Link” objects have been created, the “source” and “target” members of the “Link” object are replaced with the living references of “Node” through the call to “MapLinkNodes()”. The “Start()” method instantiates the nodes and links Hastables, resets the GUIText objects and starts a coroutine call to “LoadLayout()” which allows for returning control back to the Unity platform and preventing UI lock up.

Next, lets’ add the GUIText objects. Create a GUIText object for LinkCount, NodeCount and StatusText at a minimum. Next place the GUIText objects in the Game view to their relative positions.

Make these GUIText objects a child of GameController and add drag the references to the GameController script references.

Camera

Click on the Main Camera object and add a new script “CameraController” (CameraController.cs). In this script we’ll add basic controls for WASD, Control, Space and Wheel/Scroll controls.

[codesyntax lang=”csharp”]

using UnityEngine; using System.Collections; [AddComponentMenu("Camera-Control/Move ZeroG")] public class CameraControlZeroG : MonoBehaviour { public float speed = 5f; public GUIText movementSpeed; private Vector3 move = new Vector3(); private Vector3 cluster1 = new Vector3(1960, 1791, 2726); private Vector3 cluster2 = new Vector3(2042, 1579, 4254); private Vector3 cluster3 = new Vector3(2692, 81, 2526); private Vector3 cluster4 = new Vector3(531, 2317, 3776); private Vector3 cluster5 = new Vector3(-587, 2043, 2194); void Start(){ //set to first cluster position transform.position = cluster1; } void Update () { move.x = Input.GetAxis("Horizontal") * speed * Time.deltaTime; move.z = Input.GetAxis("Vertical") * speed * Time.deltaTime; move.y = 0; if (Input.GetKey ("space")) { move.y = speed * Time.deltaTime; } if (Input.GetKey ("left ctrl")) { move.y = -speed * Time.deltaTime; } //adjust speed with mouse wheel speed += Input.GetAxis("Mouse ScrollWheel"); if (speed < 5) speed = 5; movementSpeed.text = "Move Speed: " + speed; move = transform.TransformDirection(move); transform.position += move; //set warp to cluster controls if(Input.GetKey("1")){ transform.position = cluster1; } if(Input.GetKey("2")){ transform.position = cluster2; } if(Input.GetKey("3")){ transform.position = cluster3; } if(Input.GetKey("4")){ transform.position = cluster4; } if(Input.GetKey("5")){ transform.position = cluster5; } } }

[/codesyntax]

Walking through the above code, we define 2 public properties, speed which will hold the speed of movement through the zero gravity environment and GUIText movementSpeed which displays our current movement speed. Next we define a Vector3 for move which will be used as the movement vector. The following cluster[1-5] members define areas of the Topology which we’ll allow the camera to quickly jump to, feel free to replace these with your own coordinates. The “Start()” function places our camera at the first cluster position (the largest cluster). The “Update()” function first updates the move vector to move the camera in a direction. The “space” check will change our “y” movement upward. The “left ctrl” changes our “y” movement downward. The “Mouse ScrollWheel” changes our overall movement speed, then we display the speed in the GUIText. The final modifications are made to the camera’s transform position. The GetKey() calls for 1 through 5 warp our camera to the cluster[1-5] positions.

We’ll also want to import a standard asset from the Unity “Character Controller” set. Click Assets -> Import Package -> Character Controller, deselect everything, then online select “MouseLook.cs”.

This will import the “MouseLook.cs” script which we’ll need to add to the Main Camera (Add Component -> Camera-Control -> Mouse Look).

Putting It All Together

Lastly, build, deploy and check it out. One thing to keep in mind is that the layout.xml in the Data directory (/Assets/Data/layout.xml) does not get deployed with the build. You will need to manually copy this file out to your build/deploy directory. Hopefully you won’t have any errors and will be able to view the 3D topology in all of its beauty and splendor. Have fun!