Creating and manipulating Tulip visualizations with the tulipgui module

Starting the 4.4 release of Tulip, a new module called tulipgui is available allowing to create and manipulate Tulip views (typically Node Link diagrams). The module can be used inside the Python Script editor integrated in the Tulip software GUI but also through the classical Python interpreter.

The main features offered by that module are :

  • creation of interactive Tulip visualizations
  • the ability to change the data source on opened visualizations
  • the possibilty to modify the rendering parameters for node link diagram visualizations
  • the ability to save visualization snapshots to image files on disk

Using the module from the main Tulip GUI

When the tulipgui module is used through the Python script editor integrated in the Tulip GUI, it enables to add and manipulate views in the Tulip workspace.

For instance, the following script works on a geographical network. We suppose that we already have an opened Node Link Diagram view (plus one Python Script view) in Tulip for visualizing the whole network. The script will extract the induced sub-graph of the european nodes, create a new Node Link Diagram view for visualizing it and set some rendering parameters:

from tulip import *
from tulipgui import *

def main(graph):

    # extraction and creation of the european sub-graph
    continent =  graph.getStringProperty("continent")
    europeNodes = []
    for n in graph.getNodes():
        if continent[n] == "Europe":
            europeNodes.append(n)
    europeSg = graph.inducedSubGraph(europeNodes)
    europeSg.setName("Europe")

    nlvEurope = tlpgui.createView("Node Link Diagram view", europeSg)

    # set labels scaled to node sizes mode
    renderingParameters = nlvEurope.getRenderingParameters()
    renderingParameters.setLabelScaled(True)
    nlvEurope.setRenderingParameters(renderingParameters)

Using the module with the classical Python interpreter

The tulipgui module can also be used with the classical Python interpreter and shell. Tulip interactive visualizations will be displayed in separate windows once they have been created.

Warning

On Ubuntu systems with proprietary NVIDIA drivers installed from the “nvidia-current” package, there is an installation issue that prevents Qt OpenGL stack to work properly from Python. Tulip visualizations are displayed but not the configurations widgets and there is some annoying messages displayed on the error output. To fix that issue, remove the “nvidia-current” package and manually install the NVIDIA proprietary driver from the install script downloadable through the NVIDIA website.

Interactive mode

When working through the Python shell, Tulip views can be created interactively. The opened views will be updated each time the graph or its properties are modified.

For instance, the following session imports a grid graph, creates a Node Link Diagram view of it and then changes the nodes colors. The Node Link Diagram view will be updated automatically.

>>> from tulip import *
>>> from tulipgui import *
>>> grid = tlp.importGraph("Grid")
>>> view = tlp.createNodeLinkDiagramView(grid)
>>> viewColor = graph.getColorProperty("viewColor")
>>> for n in graph.getNodes():
...     viewColor[n] = tlp.Color(0, 255, 0)
...

Warning

When working on Windows platforms, you have to use the Python command line utility (not the IDLE one) if you want to use the tulipgui module interactively. In a same maneer, if you intend to launch python through a terminal, you have to used the basic windows console cmd.exe. Other shells like mintty or rxvt do not allow to process the GUI events, required for interactive use.

Script execution mode

When executing a script from a command line through the classical python interpreter, if Tulip views had been created during its execution, the script will terminate once all view windows had been closed.

Below are some samples scripts illustrating the features of the tulipgui module. The first script imports a grid approximation graph, computes some visual attributes on it and creates a Node Link Diagram visualization (which will remain displayed at the end of the script execution). Figure 1 introduces a screenshot of the created view.:

from tulip import *
from tulipogl import *
from tulipgui import *

# Import a grid approximation (with default parameters)
graph = tlp.importGraph("Grid Approximation")

# Get references to some view properties
viewLayout = graph.getLayoutProperty("viewLayout")
viewSize = graph.getSizeProperty("viewSize")
viewBorderWidth = graph.getDoubleProperty("viewBorderWidth")
viewLabelBorderWidth = graph.getDoubleProperty("viewLabelBorderWidth")
viewColor = graph.getColorProperty("viewColor")
viewLabelColor = graph.getColorProperty("viewLabelColor")
viewLabelBorderColor = graph.getColorProperty("viewLabelBorderColor")
viewBorderColor = graph.getColorProperty("viewBorderColor")
viewLabel = graph.getStringProperty("viewLabel")
viewShape = graph.getIntegerProperty("viewShape")

# Compute an anonymous degree property
degree = tlp.DoubleProperty(graph)
degreeParams = tlp.getDefaultPluginParameters("Degree")
graph.applyDoubleAlgorithm("Degree", degree, degreeParams)

# Map the node sizes to their degree
sizeMappingParams = tlp.getDefaultPluginParameters("Metric Mapping", graph)
sizeMappingParams["property"] = degree
sizeMappingParams["min size"] = 10
sizeMappingParams["max size"] = 30
graph.applySizeAlgorithm("Metric Mapping", viewSize, sizeMappingParams)

# Apply an FM^3 layout on it
fm3pParams = tlp.getDefaultPluginParameters("FM^3 (OGDF)", graph)
fm3pParams["Unit edge length"] = 100
graph.applyLayoutAlgorithm("FM^3 (OGDF)", viewLayout, fm3pParams)

# Create a heat map color scale
heatMap = tlp.ColorScale([tlp.Color.Green, tlp.Color.Black, tlp.Color.Red])

# Map the node colors to their degree using the heat map color scale
# Also set the nodes labels to their id
for n in graph.getNodes():
    pos = (degree[n] - degree.getNodeMin()) / (degree.getNodeMax() - degree.getNodeMin())
    viewColor[n] = heatMap.getColorAtPos(pos)
    viewLabel[n] = str(n.id)

# Set border colors values
viewBorderColor.setAllNodeValue(tlp.Color.Black)
viewLabelColor.setAllNodeValue(tlp.Color.Blue)
viewLabelBorderColor.setAllNodeValue(tlp.Color.Blue)

# Add a border to nodes/edges
viewBorderWidth.setAllNodeValue(1)
viewBorderWidth.setAllEdgeValue(1