Overview

This document provides information about a communication mechanism which can be used to drive EnSight from an external program using EnSight's command language. The logical steps involved in this process are:

More detail will now be provided for each of these steps.

Step 1

Compile your external program with the enscmddriver.a library. This library is provided in the EnSight distribution, under the src/cmddriver directory. Directions for compiling are contained in the README file contained in that directory. Also provided therein is a sample external program (entitled enscmddriver.c) which is used to show how to compile, as well as for examples of how to utilize the following routines within your external driver:

Step 2

Start EnSight and have it listen for the connection from the external program. Normally this will be done from your external program and will therefore use batch mode to start EnSight.

In Batch Mode

ensight251 -X -batch -externalcmds

While not the norm, it is possible to have EnSight start listening for the connection from an interactive session.

Interactively (From the Command Dialog in EnSight)

test: acceptcmddriver

EnSight will listen on Port 1104 for the connection from the external program. If a different port is desired, you can use the command line option -externalcmdport # when starting EnSight. Replace the # with a legitimate (>1024) port number. Then be sure to use the specified socket in the enscmddriver_connect call within your external program.

Step 3

Once EnSight is listening, start the external program and issue the connect command within that program.

For the provided enscmddriver sample, this is done as follows:

enscmddriver HOSTNAME

Where, HOSTNAME is the name of the machine running EnSight.

Step 4

Send commands to EnSight using the enscmddriver_sendmesg routine. The commands that you send to EnSight using this routine are the same commands that EnSight produces when users are manipulating a model with the EnSight Graphical User Interface.

It is possible to play entire command files that are accessible from the machine where the EnSight client is running. You can send a "play:" command to specify the name of the command file to use. Commands that are played using a file (play:) will execute faster than sending individual commands. The following is a command file (amiread.enc) that reads and colors the ami data set that is shipped with EnSight.

VERSION 7.52

data: binary_files_are big_endian

data: format case

data: path /usr/local/CEI/ensight251/data/ami

data: geometry ami.case

data: read

data_partbuild: begin

part: select_default

part: modify_begin

part: elt_representation not_loaded

part: modify_end

data_partbuild: data_type unstructured

data_partbuild: select_begin

1

data_partbuild: select_end

data_partbuild: description

data_partbuild: create

part: select_default

part: modify_begin

part: elt_representation 3D_border_2D_full

part: modify_end

data_partbuild: data_type unstructured

data_partbuild: select_begin

2

data_partbuild: select_end

data_partbuild: description

data_partbuild: create

data_partbuild: end

variables: activate pressure

part: select_all

part: modify_begin

part: colorby_palette pressure

part: modify_end

Your external program could send the command "play: amiread.enc" to EnSight using the enscmddriver_sendmesg routine. EnSight would play the command file, which would read in the model and color it by pressure, etc. It would then return and allow the external program to continue to issue other commands, such as would create images, create flipbook or keyframe animation sequences, etc.

The enscmddriver_query routine can be used to obtain some limited information back from EnSight. The current possibilities for this option will be described in the query section below.

Step 5

Shutdown EnSight. If you did the normal, and started EnSight in batch mode - you close the communication and get EnSight to stop by sending an exit command with the enscmddriver_sendmesg routine.

If you happen to be running EnSight interactively, rather than the normal batch mode, and you desire to close the connection, but leave EnSight running - you can use the enscmddriver_disconnect routine.

Example

Assuming that you were able to successfully compile our sample external program, enscmddriver, and that your machine name was speedy, you could do the following:

Start EnSight in batch mode (on your machine named speedy):

> ensight251 -X -batch -externalcmds &

Start the enscmddriver sample routine:

> enscmddriver speedy

Issue the following commands as prompted by the enscmddriver program:

What would you like to do?

play: amiread.enc

What would you like to do?

view: hidden_surface ON

What would you like to do?

savegeom: format STL

What would you like to do?

savegeom: binary OFF

What would you like to do?

savegeom: save_geometric_entities /tmp/ami

What would you like to do?

exit

Which would read in the ami model using the amiread.enc command file, then turn shading on, then save a VRML file in /tmp. It would then close the communication and cause EnSight to exit.

You will of course be using your own external program, so the actual use of the enscmddriver_connect, and enscmddriver_sendmesg routines will be of interest to you. You can see them being used in the enscmddriver.c file. The routine arguments are described in detail in Routine Descriptions.