Viz: the clients

Viz consists of a server, the rendering program, and clients the rest of the application. This document describes the various clients. Note that Python 1.5.1 and Tcl/Tk 8.0 are required to run these clients.

Before you run any of these programs, always make sure you have the right environment variables:
cd <viz directory>/src
source vizsource

Base Application
Viz shell
Viz relay

In addition to these clients, you can develop your own clients using the Viz Python or C++ API.

Base application

The base application is a shell script that calls Viz with a Python/Tk graphical user interface called TopGUI. TopGUI contains a series of widgets allowing the user to quickly access the function of Viz interactively. No programming is required, just run goViz. TopGUI is in fact decomposed into several basic Python classes that can be separately imported into a customized application.
 

Usage:

cd <viz directory>/src/BaseApp
./goViz

The following classes are available:
 
Class Function
Load model Load a file, a series of selected files, or directories recursively.
Add object Add/remove simple geometries
Change viewer Change the viewers number or type.

Viz shell

The Viz shell provides an easy way to interact with Viz from the command line. It is based on the Python interpreter, so in addition to the Viz-Python msg library, all the Python modules are available.

Usage:

cd <viz directory>/src/PyUtil
./vsh

Example: Add an object and change its color to red:

Python Viz> add('myNewObject','Parent','shape:cube',(0,0,0),(0,0,0),1)
Python Viz> changeColot('myNewObject',(1,0,0))

The complete list of messages and their parameters can be found in the Viz-python API.

Viz Relay

The relay allows your client to connect to multiple instances of Viz (that can run on different machines). It is typically used to "drive" another demo Viz that will show everything you're loading into your Viz.

The Viz Relay is a small server that can connect to multiple instances of Viz. Your client can connect to the relay the same way it connects to Viz, except that all messages sent from the client to the relay will be forwarded to all connected Viz. Similarly, all messages sent from any Viz will be forwarded to the client. The relay also allows multiple clients to connect.

Since all connections and forwarded connections are separate, this architecture will not break the subscription paradigm: in other words, a client connected to a particular Viz through a relay will still receive messages it has subscribed to from that instance of Viz.

In the case of two-way communication between the Viz's and the clients through the relay, it is the responsibility of the user who develop the clients to make sure any possible synchronous communication is properly handled.

Also, while it is possible to imagine a network of relays with multiple Viz's and multiple clients, we recommend to keep the number of relays as close to 1 as possible, as the number of connections can increase rapidly with the number of clients of Viz.

For 1 relay: number of connections = number of connections from clients * (number of Viz + 1)

FIGURE:

The relay is implemented in Python. To run the relay:
<viz directory>/src/PyCom/relay.py <service port number>

The relay will listen to a specific service port, to which clients can connect. Through this port, the relay will also accept the following string control commands (you can use telnet to connect and type the following commands):
~shutdown    : shuts down the relay
~verbose    : toggles verbosity on/off
~list    : list all relay connections
~newviz <hostname> <port>    : makes the relay connect to new viz at <hostname> on <port>
~outviz    : toggles output into following modes:
         - relay forwards outputs from all connected viz to clients
        - relay forwards ouptus from only primary viz to clients (default)
        - this mode is useful, because some communication logics on the clients depend on having only one viz on the other end.