| Contents | qtriplot home | QTriplot Manual

Integration with other applications

Introduction

Qtriplot can communicate with other applications like matlab. To achieve this, qtriplot has to be started with the command line option -p port. Qtriplot will then listen to tcp-port port, and accept data and commands sent to that port by other applications. The format in which applications must send data and commands is described below.

Integration with Matlab

For Matlab the script qtriplot.m is available from http://www.ecgsim.org/qtriplot. Whenever this script is used from Matlab, it first checks wether the qtriplot application is listening. If not, it starts the application. From then on subsequent calls of the scripts send data or commands to that instance of the qtriplot application.

The default port for communication, as defined in qtriplot.m, is 1041. This can be changed by setting the global matlab variable qtriplot_port. In this way multiple qtriplot instances can be used.

Examples of the usage of this script:

qtriplot(ver, tri) plot the surface described by vertices ver and triangles tri.
qtriplot(surfStruct) plot the surface described by fields .pnt and .tri in the object surfStruct.
qtriplot(surfStruct, 'surf') plot the surface described by fields .pnt and .tri in the object surfStruct, and use the name 'surf' for that object.
qtriplot(mat, 'surf') plot the function described by matrix mat on the qtriplot surface by the name of 'surf'.
qtriplot(mat) plot the function described by matrix mat on the most recently defined surface in qtriplot.
qtriplot('command') send qtriplot command 'command' to qtriplot.

The matlab.m script uses the tcp-udp-ip toolbox. See the help in qtriplot.m for full documentation.

Format of data structures

Data is sent to the qtriplot application in datagrams. Each datagram starts with a 4-byte field. This field is an unsigned integer, indicating the number of bytes in the remainder (the body) of the datagram.

The body of the datagram starts with a string. If this strings starts with the character |, qtriplot expects data in the remainder of the body (as explained below). If not, the string is sent to the qtriplot command interpreter, and the command is executed.

If the string at the start of the body datagram starts with |, the part of body from the start to the first null-byte is parsed using the following syntax:

|typ name

that is: directly after the | symbol there is a three-character identifier that defined the type of the data that follows (see below), then a space, and then a string that defines the name of the qtriplot object to apply the data to. The name may be ommitted, and the data describe a qtriplot object, a default name will be used (def_1, def_2, etc). If the name is omitted and the data describe something else than a qtriplot object (.e.g: a function matrix), the data is applied to the qtriplot object that was most recently defined.

The string at the start of the body of the datagram must be padded with null-bytes to a multiple of 8. After that, the actual data follow, as described below:

identifier number of bytes type description
|tri [ ] multiple of 8 string triangulated surface follows
4 integer number of vertices (np)
4 integer number of triangles (nt; may be zero)
3*8*np double coordinates of vertices (x1, y1, z1, x2, etc)
3*4*nt integer indices of the vertices of the triangles
|fun [ ] multiple of 8 string function matrix follows
4 integer number of rows (nr)
4 integer number of columns (nc)
8*nr*nc double function values (f11, f12 ... f1nc, f21, etc)
|ele [ ] multiple of 8 string electrode description follows
4 integer number of electrodes (ne)
4 integer type (0: vertex-electrodes; 1: lm-electrodes)
2*8*ne (0 for type 0) double lamba-mu parameters
4*ne integer indices of electrodes (see elfile)

All integers and doubles must be send in big-endian format, which is the network standard. Qtriplot will internally convert the data to native byte order.
Note: the manual for the matlab tcp-udp-ip toolbox uses an incorrect (i.e. swapped) terminology for big-endian and little endian; the qtriplot manual uses the correct one).