Visualizing 3D Network Topologies Using Unity

Introduction

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.

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:

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

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

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:

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);
        }
    }

}

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.

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;
            }
        }
    }

}

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.

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() );
        }

    }

}

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.

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;
        }
    }
}

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!