source: trunk/packages/vizservers/nanovis/protocol-nanovis.txt @ 3630

================================================================================

 Copyright (C) 2004-2013  HUBzero Foundation, LLC

================================================================================
Protocol for nanovis render server.  

Commands take the general form of command and arguments using Tcl syntax and are 
terminated by a newline.  Some command arguments expect a Tcl list which can be
sent by enclosing the list in curly braces to prevent the interpreter from 
splitting the list into multiple arguments.  Likewise, strings with spaces 
should be quoted or enclosed in curly braces.  In the documentation below,
arguments are indicated by angle brackets and optional arguments are surrounded
by question marks -- the brackets and question marks are not part of the
protocol and should not be included in argument strings.  The arguments shown 
in angle brackets should be replaced with a string (where there are fixed 
choices this document indicates valid values by separating them with pipe 
symbols), a list in Tcl syntax, or a numeric value.  Boolean arguments can take
the form of 0|1, true|false, or yes|no.  Since the protocol commands are 
executed in a Tcl interpreter, Tcl code such as math expressions in expr 
commands enclosed in square brackets are also allowed.  Since the interpreter
is a "safe" interpreter, some Tcl commands that could cause security issues may 
not be available for use.

Some commands such as the 'flowvis add' commands create Tcl objects within the
server's interpreter.  The name sent as an argument when adding the object can 
then be used as a protocol command.  For example, the string sent as the <name>
argument to 'flowvis add' can then be used in place of <flowObj> in the commands
documented below.  The flow object name also creates a volume name that can 
be used in volume and cutplane commands, but in that case the name is used as
an argument to the volume or cutplane commands rather than as the command 
itself.

When binary data is to be sent, it should follow the newline after a command 
that indicates incoming data including a byte count argument.
================================================================================
================================================================================
Requests:
================================================================================
axis visible <bool> 

camera angle <xAngle> <yAngle> <zAngle>
       ** Deprecated, use camera orient **
camera orient <quatW> <quatX> <quatY> <quatZ>
camera pan <x> <y>
camera pos <x> <y> <z>
camera reset <?all?>
camera zoom <factor>

clientinfo <list>

cutplane position <relval> <x|y|z> <?names?>
         Set the position of a volume cutplane.  Names is
         an optional list of volume names.
         relval = [0,1]
cutplane state <bool> <x|y|z> <?names?>
         Set the axis (normal) of a volume cutplane.  Names is
         an optional list of volume names.

flow add <name> <?option value...?>
         <name> is an object name to use in <flowObj> commands
         In addition, a volume is added with the same name
         which can be used in volume and cutplane commands
         see '<flowObj> configure' for switch options
flow delete <names>
flow exists <name>
     This doesn't currently produce a response, it only returns a boolean
     within the server's interpreter
flow goto <nSteps>
flow names
     This doesn't currently produce a response, it only returns a Tcl list
     within the server's interpreter
flow next
flow reset
flow video <token> <?switches...?>
     -bitrate <val>
     -format <mpeg|theora|mov>
     -framerate <val>
     -height <val>
     -numframes <val>
     -width <val>

<flowObj> box add <name> <?switches...?>
          See '<flowObj> box configure' for switches
<flowObj> box configure <name> <?switches...?>
         -color <{r g b a}>
         -corner1 <{x y z}>
         -corner2 <{x y z}>
         -hide <bool>
         -linewidth <val>
<flowObj> box delete <names>
<flowObj> box names
          This doesn't currently produce a response, it only returns a Tcl list
          within the server's interpreter

<flowObj> configure <?option value...?>
          -ambient <val>
          -arrows <bool>
          -axis <x|y|z>
          -diffuse <val>
          -hide <bool>
          -light2side <bool>
          -opacity <val>
          -outline <bool>
          -position <val|%val>
           val = world coordinate, or %val = [0,100]
          -slice <bool>
          -specularExp <val>
          -specularLevel <val>
          -transferfunction <name>
          -volume <bool>
<flowObj> data file <fileName> <numComponents>
          Load a data file.  fileName is path to file on server
<flowObj> data follows <nbytes> <numComponents>
          Send flow data.  Data bytes follow the newline after the command
<flowObj> legend <w> <h>

<flowObj> particles add <name> <?switches?>
          see '<flowObj> particles configure' for switches
<flowObj> particles configure <name> <?switches?>
          -axis <x|y|z>
          -color <{r g b a}>
          -hide <bool>
          -position <val|%val>
           val = [0,100], or %val = [0,1]
          -size <val>
<flowObj> particles delete <names>
<flowObj> particles names
          This doesn't currently produce a response, it only returns a Tcl list
          within the server's interpreter

grid axiscolor <red> <green> <blue> <?alpha?>
grid axisname <x|y|z> <name> <units>
grid linecolor <red> <green> <blue> <?alpha?>
grid visible <bool>

heightmap create <heightmapName> <xMin> <yMin> <xMax> <yMax> <xNum> <yNum> <valueList>
heightmap cull <none|back|front>
heightmap data follows <nBytes> <heightmapName>
          After newline following command, nBytes of data are sent
heightmap data visible <bool> <?heightmapNames?>
heightmap legend <heightmapName> <width> <height>
heightmap linecontour color <red> <green> <blue> <?heightmapNames?>
heightmap linecontour visible <bool> <?heightmapNames?>
heightmap opacity <value> <?heightmapNames?>
heightmap polygon <wireframe|fill> 
          **Warning: This is a global setting**
heightmap shading <flat|smooth>
          **Warning: This is a global setting**
heightmap transfunc <transferFunctionName> <?heightmapNames?>

legend <transferfunc name> <width> <height>
       Request render of transfer function

screen bgcolor <r> <g> <b>
       Set screen background color
screen size <width> <height>
       Set size of rendered images

snapshot
         Render a 2k x 2k image (offscreen buffer). Response image data is tagged
         as '-type print'

transfunc define <name> {colors} {alpha}
          colors => 1 line each of "value r g b"
          alpha => 1 line each of "value alpha"
          value => [0,1]

up <x|y|z|-x|-y|-z>
   Set orientation of volumes

volume animation capture <numframes> <?filename?>
       This is not fully implemented.  Rendered frames are not returned
       to the client.
volume animation clear
volume animation start
volume animation stop
volume animation volumes <?names?>

volume data follows <nbytes> <name>
volume data state <bool> <?names?>
volume delete <names>
volume exists <name>
       This doesn't currently produce a response, it only returns a boolean
       within the server's interpreter
volume names
       This doesn't currently produce a response, it only returns a Tcl list
       within the server's interpreter
volume outline color <r> <g> <b> <?names?>
volume outline state <bool> <?names?>
volume outline visible <bool> <?names?>
volume shading ambient <value> <?names?>
volume shading diffuse <value> <?names?>
volume shading isosurface <bool> <?names?>
volume shading light2side <bool> <?names?>
volume shading opacity <value> <?names?>
volume shading specularExp <value> <?names?>
volume shading specularLevel <value> <?names?>
volume shading transfunc <tfName> <?names?>
volume state <bool> <?names?>

================================================================================
Replies:
================================================================================
nv>legend <volume> <min> <max> <nbytes>
  (followed by bytes)

nv>image -type image -bytes <nbytes>
  (followed by bytes)

nv>image -type print -bytes <nbytes>
  (followed by bytes)

nv>image -type movie -token <token> -bytes <nbytes>
  (followed by bytes)

nv>data tag <dataobj-tag> min <val> max <val> vmin <val> vmax <val>
   The min,max data values for the data object and the cumulative volume data
   min,max over all volumes

nv>data tag <flow-tag> min <val> max <val>
   Sent after a "<flowObj> data follows...".  Min,max values are for the 
   magnitude of the vector field.

================================================================================
Error Replies:
================================================================================
nv>viserror -bytes <nbytes>
   <multi-line error string of nbytes>
================================================================================