Example Usage

A simple console driven topology viewer:

Pipeline( ConsoleReader(),
          lines_to_tokenlists(),
          TopologyViewer(),
        ).run()

Then at runtime try typing these commands to change the topology in real time:

>>> DEL ALL
>>> ADD NODE 1 "1st node" randompos -
>>> ADD NODE 2 "2nd node" randompos -
>>> ADD NODE 3 "3rd node" randompos -
>>> ADD LINK 1 2
>>> ADD LINK 3 2
>>> DEL LINK 1 2
>>> DEL NODE 1

User Interface

TopologyViewer manifests as a pygame display surface. As it is sent topology information nodes and links between them will appear.

You can click a node with the mouse to select it. Depending on the application, this may display additional data or, if integrated into another app, have some other effect.

Click and drag with the left mouse button to move nodes around. Note that a simple physics model or repulsion and attraction forces is always active. This causes nodes to move around to help make it visually clearer, however you may still need to drag nodes about to tidy it up.

The surface on which the nodes appear is notionally infinite. Scroll around using the arrow keys.

Press the 'f' key to toggle between windowed and fullscreen modes.

How does it work?

TopologyViewer is a specialisation of the Kamaeila.UI.MH.PyGameApp component. See documentation for that component to understand how it obtains and handles events for a pygame display surface.

A topology (graph) of nodes and links between them is rendered to the surface.

You can specify an initial topology by providing a list of instantiated particles and another list of pairs of those particles to show how they are linked.

TopologyViewer reponds to commands arriving at its "inbox" inbox instructing it on how to change the topology. A command is a list/tuple.

Commands recognised are:

[ "ADD", "NODE", <id>, <name>, <posSpec>, <particle type> ]

Add a node, using:

• id -- a unique ID used to refer to the particle in other topology commands. Cannot be None.
• name -- string name label for the particle
• posSpec -- string describing initial x,y (see _generateXY)
• particleType -- particle type (default provided is "-", unless custom types are provided - see below)

[ "DEL", "NODE", <id> ]

Remove a node (also removes all links to and from it)

[ "ADD", "LINK", <id from>, <id to> ]

Add a link, directional from fromID to toID

[ "DEL", "LINK", <id from>, <id to> ]

Remove a link, directional from fromID to toID

[ "DEL", "ALL" ]

Clears all nodes and links

[ "GET", "ALL" ]

Outputs the current topology as a list of commands, just like those used to build it. The list begins with a 'DEL ALL'.

[ "UPDATE_NAME", "NODE", <id>, <new name> ]

If the node does not already exist, this does NOT cause it to be created.

[ "GET_NAME", "NODE", <id> ]

Returns UPDATE_NAME NODE message for the specified node

[ "FREEZE", "ALL" ]

Freezes all particles in the system, essentially halting the simulation

[ "UNFREEZE", "ALL" ]

Unfreezes all particles in the system, essentially restarting the simulation

Commands are processed immediately, in the order in which they arrive. You therefore cannot refer to a node or linkage that has not yet been created, or that has already been destroyed.

If a stream of commands arrives in quick succession, rendering and physics will be temporarily stopped, so commands can be processed more quickly. This is necessary because when there is a large number of particles, physics and rendering starts to take a long time, and will therefore bottleneck the handling of commands.

However, there is a 1 second timeout, so at least one update of the visual output is guaranteed per second.

TopologyViewer sends any output to its "outbox" outbox in the same list/tuple format as used for commands sent to its "inbox" inbox. The following may be output:

[ "SELECT", "NODE", <id> ]

Notification that a given node has been selected.

[ "SELECT", "NODE", None ]

Notificaion that no node is now selected.

[ "ERROR", <error string> ]

Notification of errors - eg. unrecognised commands arriving at the "inbox" inbox

[ "TOPOLOGY", <topology command list> ]

List of commands needed to build the topology, as it currently stands. The list will start with a ("DEL","ALL") command. This is sent in response to receiving a ("GET","ALL") command.

Termination

If a shutdownMicroprocess message is received on this component's "control" inbox this it will pass it on out of its "signal" outbox and immediately terminate.

Historical note for short term: this has changed as of May 2008. In the past, this component would also shutdown when it recieved a producerFinished message. This has transpired to be a mistake for a number of different systems, hence the change to only shutting down when it recieves a shutdownMicroprocess message.

NOTE: Termination is currently rather cludgy - it raises an exception which will cause the rest of a kamaelia system to halt. Do not rely on this behaviour as it will be changed to provide cleaner termination at some point.

{ "major" : BigParticle,  "minor"  : SmallParticle  }

def render(self, surface):
    yield 1
    # render lines for bonds *from* this particle *to* others
    yield 2
    # render a blob and the name label for the particle

class TopologyViewer(Kamaelia.UI.MH.PyGameApp, Axon.Component.component)

TopologyViewer(...) -> new TopologyViewer component.

A component that takes incoming topology (change) data and displays it live using pygame. A simple physics model assists with visual layout. Particle types, appearance and physics interactions can be customised.

Keyword arguments (in order):

• screensize -- (width,height) of the display area (default = (800,600))
• fullscreen -- True to start up in fullscreen mode (default = False)
• caption -- Caption for the pygame window (default = "Topology Viewer")
• particleTypes -- dict("type" -> klass) mapping types of particle to classes used to render them (default = {"-":RenderingParticle})
• initialTopology -- (nodes,bonds) where bonds=list((src,dst)) starting state for the topology (default=([],[]))
• laws -- Physics laws to apply between particles (default = SimpleLaws(bondlength=100))
• simCyclesPerRedraw -- number of physics sim cycles to run between each redraw (default=1)
• border -- Minimum distance from edge of display area that new particles appear (default=100)
• extraDrawing -- Optional extra object to be rendered (default=None)
• showGrid -- False, or True to show gridlines (default=True)
• transparency -- None, or (r,g,b) colour to make transparent
• position -- None, or (left,top) position for surface within pygame window